summer-engine 2.6.6 → 2.7.0

package/dist/lib/mcp-log.js

@@ -0,0 +1,72 @@
+import { appendFileSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getSummerDir } from "./auth.js";
+const MAX_LOG_BYTES = 512 * 1024;
+const RETAIN_LOG_BYTES = 256 * 1024;
+export function getMcpLogPath() {
+    return join(getSummerDir(), "mcp.log");
+}
+function redact(value) {
+    if (Array.isArray(value))
+        return value.map((item) => redact(item));
+    if (!value || typeof value !== "object")
+        return value;
+    const out = {};
+    for (const [key, nested] of Object.entries(value)) {
+        if (/token|secret|password|authorization|cookie|api[-_]?key/i.test(key)) {
+            out[key] = "[REDACTED]";
+        }
+        else {
+            out[key] = redact(nested);
+        }
+    }
+    return out;
+}
+function rotateIfNeeded(path) {
+    try {
+        if (statSync(path).size < MAX_LOG_BYTES)
+            return;
+        const text = readFileSync(path, "utf-8");
+        const retained = text.slice(-RETAIN_LOG_BYTES);
+        writeFileSync(path, `{"event":"mcp:log_rotated"}\n${retained}`, {
+            encoding: "utf-8",
+            mode: 0o600,
+        });
+    }
+    catch {
+        // No existing log, or not readable. The next append will recreate it.
+    }
+}
+export function appendMcpLogEvent(event, details = {}) {
+    try {
+        const dir = getSummerDir();
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const path = getMcpLogPath();
+        rotateIfNeeded(path);
+        const safeDetails = redact(details);
+        const payload = {
+            ts: new Date().toISOString(),
+            event,
+            ...safeDetails,
+        };
+        appendFileSync(path, `${JSON.stringify(payload)}\n`, {
+            encoding: "utf-8",
+            mode: 0o600,
+        });
+    }
+    catch {
+        // Logging must never affect MCP behavior.
+    }
+}
+export async function readRecentMcpLogLines(maxLines = 120) {
+    try {
+        const text = await readFile(getMcpLogPath(), "utf-8");
+        if (!text.trim())
+            return [];
+        return text.trimEnd().split(/\r?\n/).slice(-maxLines);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/lib/skills-registry.d.ts

@@ -23,7 +23,7 @@ export declare const SKILL_REGISTRY: readonly [{
     readonly public: true;
     readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf", "cline", "roo-code", "kilo-code", "gemini", "github-copilot", "vscode-copilot", "opencode"];
     readonly recommended: true;
-    readonly requiresMcpTools: readonly ["summer_get_console", "summer_get_debugger_errors", "summer_get_script_errors", "summer_get_diagnostics", "summer_clear_console", "summer_play", "summer_stop", "summer_inspect_node"];
+    readonly requiresMcpTools: readonly ["summer_create_debug_report", "summer_get_console", "summer_get_debugger_errors", "summer_get_script_errors", "summer_get_diagnostics", "summer_clear_console", "summer_play", "summer_stop", "summer_inspect_node"];
     readonly testScenario: "Triage a runtime crash end-to-end: read errors, locate code, propose fix, apply on approval, verify.";
 }, {
     readonly name: "play";
@@ -49,6 +49,14 @@ export declare const SKILL_REGISTRY: readonly [{
     readonly recommended: true;
     readonly requiresMcpTools: readonly ["summer_create_scene", "summer_open_scene", "summer_get_scene_tree", "summer_add_node", "summer_instantiate_scene", "summer_save_scene"];
     readonly testScenario: "Build a small reusable player scene, instantiate it in a main scene, and save both scenes through Summer tools.";
+}, {
+    readonly name: "summer-cloud";
+    readonly category: "scene-and-project";
+    readonly public: true;
+    readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf", "cline", "roo-code", "kilo-code", "gemini", "github-copilot", "vscode-copilot", "opencode"];
+    readonly recommended: true;
+    readonly requiresMcpTools: readonly ["summer_cloud_init", "summer_cloud_status", "summer_cloud_push", "summer_cloud_pull", "summer_cloud_restore", "summer_cloud_checkpoints", "summer_cloud_conflicts"];
+    readonly testScenario: "Enable Cloud for a project, push it, then pull it onto a second machine, taking the bootstrap choice and surfacing the delete count before any guarded deletion.";
 }, {
     readonly name: "fps-controller";
     readonly category: "character-controllers";
@@ -201,6 +209,14 @@ export declare const SKILL_REGISTRY: readonly [{
     readonly recommended: true;
     readonly requiresMcpTools: readonly ["summer_get_scene_tree", "summer_inspect_node", "summer_project_setting", "summer_get_console", "summer_get_diagnostics"];
     readonly testScenario: "Run the Steam pre-flight checklist (Windows + Mac + Linux), validate icons/banners/screenshots/build config, and produce a release build only when green.";
+}, {
+    readonly name: "remote-deploy";
+    readonly category: "deployment";
+    readonly public: true;
+    readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf", "cline", "roo-code", "kilo-code", "gemini", "github-copilot", "vscode-copilot", "opencode"];
+    readonly recommended: true;
+    readonly requiresMcpTools: readonly ["summer_project_setting", "summer_get_diagnostics", "summer_get_console", "summer_get_script_errors"];
+    readonly testScenario: "User says \"deploy the game to my Android phone\" — skill walks the prerequisites (runnable export preset, installed export templates, USB-debugging device), checks diagnostics are clean, and points them at the topnav Remote Deploy button to deploy a debug build with on-device remote debugging.";
 }, {
     readonly name: "concept-art";
     readonly category: "2d-assets";
@@ -249,6 +265,14 @@ export declare const SKILL_REGISTRY: readonly [{
     readonly recommended: false;
     readonly requiresMcpTools: readonly ["summer_generate_image", "summer_import_from_url", "summer_set_resource_property", "summer_add_node", "summer_set_prop"];
     readonly testScenario: "User requests a '4-frame walk cycle for the goblin' — skill generates per-frame at locked anchor, builds SpriteFrames resource, wires AnimatedSprite2D.";
+}, {
+    readonly name: "create-asset-sheet";
+    readonly category: "2d-assets";
+    readonly public: true;
+    readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf", "cline", "roo-code", "kilo-code", "gemini", "github-copilot", "vscode-copilot", "opencode"];
+    readonly recommended: false;
+    readonly requiresMcpTools: readonly ["summer_get_studio_workflow", "summer_generate_image", "summer_slice_asset_sheet", "summer_import_asset_by_id"];
+    readonly testScenario: "User requests a Japanese village asset pack — skill loads the Guided asset-pack recipe, generates one coherent sheet, slices it through the shared cloud pipeline, and imports selected results.";
 }, {
     readonly name: "skybox-panorama";
     readonly category: "2d-assets";

package/dist/lib/skills-registry.js

@@ -53,6 +53,7 @@ export const SKILL_REGISTRY = [
         clients: ALL_CLIENTS,
         recommended: true,
         requiresMcpTools: [
+            "summer_create_debug_report",
             "summer_get_console",
             "summer_get_debugger_errors",
             "summer_get_script_errors",
@@ -108,6 +109,23 @@ export const SKILL_REGISTRY = [
         ],
         testScenario: "Build a small reusable player scene, instantiate it in a main scene, and save both scenes through Summer tools.",
     },
+    {
+        name: "summer-cloud",
+        category: "scene-and-project",
+        public: true,
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: [
+            "summer_cloud_init",
+            "summer_cloud_status",
+            "summer_cloud_push",
+            "summer_cloud_pull",
+            "summer_cloud_restore",
+            "summer_cloud_checkpoints",
+            "summer_cloud_conflicts",
+        ],
+        testScenario: "Enable Cloud for a project, push it, then pull it onto a second machine, taking the bootstrap choice and surfacing the delete count before any guarded deletion.",
+    },
     {
         name: "fps-controller",
         category: "character-controllers",
@@ -413,6 +431,20 @@ export const SKILL_REGISTRY = [
         ],
         testScenario: "Run the Steam pre-flight checklist (Windows + Mac + Linux), validate icons/banners/screenshots/build config, and produce a release build only when green.",
     },
+    {
+        name: "remote-deploy",
+        category: "deployment",
+        public: true,
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: [
+            "summer_project_setting",
+            "summer_get_diagnostics",
+            "summer_get_console",
+            "summer_get_script_errors",
+        ],
+        testScenario: "User says \"deploy the game to my Android phone\" — skill walks the prerequisites (runnable export preset, installed export templates, USB-debugging device), checks diagnostics are clean, and points them at the topnav Remote Deploy button to deploy a debug build with on-device remote debugging.",
+    },
     {
         name: "concept-art",
         category: "2d-assets",
@@ -494,6 +526,20 @@ export const SKILL_REGISTRY = [
         ],
         testScenario: "User requests a '4-frame walk cycle for the goblin' — skill generates per-frame at locked anchor, builds SpriteFrames resource, wires AnimatedSprite2D.",
     },
+    {
+        name: "create-asset-sheet",
+        category: "2d-assets",
+        public: true,
+        clients: ALL_CLIENTS,
+        recommended: false,
+        requiresMcpTools: [
+            "summer_get_studio_workflow",
+            "summer_generate_image",
+            "summer_slice_asset_sheet",
+            "summer_import_asset_by_id",
+        ],
+        testScenario: "User requests a Japanese village asset pack — skill loads the Guided asset-pack recipe, generates one coherent sheet, slices it through the shared cloud pipeline, and imports selected results.",
+    },
     {
         name: "skybox-panorama",
         category: "2d-assets",

package/dist/mcp/server.d.ts

@@ -1,6 +1,6 @@
 import { EngineApiClient } from "../lib/api-client.js";
-import { type BootDriftNotice } from "../lib/version-check.js";
-export declare function getCachedBootDriftNotice(): BootDriftNotice | null;
+import { getCachedBootDriftNotice as getCachedNotice } from "../lib/mcp-boot-notice.js";
+export declare const getCachedBootDriftNotice: typeof getCachedNotice;
 export declare function getClient(): Promise<EngineApiClient>;
 export declare function resetClient(): void;
 export declare function startMcpServer(): Promise<void>;

package/dist/mcp/server.js

@@ -7,16 +7,17 @@ import { registerDebugTools } from "./tools/debug-tools.js";
 import { registerVisualTools } from "./tools/visual-tools.js";
 import { WITH_ENGINE_META } from "./tools/with-engine.js";
 import { registerProjectTools } from "./tools/project-tools.js";
+import { registerFileTools } from "./tools/file-tools.js";
 import { registerAssetTools } from "./tools/asset-tools.js";
 import { registerGenerateTools } from "./tools/generate-tools.js";
 import { registerCloudTools } from "./tools/cloud-tools.js";
+import { getCachedBootDriftNotice as getCachedNotice, setCachedBootDriftNotice, } from "../lib/mcp-boot-notice.js";
+import { appendMcpLogEvent } from "../lib/mcp-log.js";
 import { buildBootDriftNotice, fetchLatestRegistryVersion, } from "../lib/version-check.js";
 const require = createRequire(import.meta.url);
 const { version } = require("../../package.json");
-let cachedBootDriftNotice = null;
-export function getCachedBootDriftNotice() {
-    return cachedBootDriftNotice;
-}
+let processDiagnosticsInstalled = false;
+export const getCachedBootDriftNotice = getCachedNotice;
 /**
  * Fire-and-forget probe of the npm registry on MCP boot. Caches the result for
  * the session. We never await this in startup so a slow / offline registry
@@ -27,7 +28,7 @@ async function probeBootDrift() {
     const registry = await fetchLatestRegistryVersion();
     // Agent is unknown at the MCP layer; use a generic placeholder. Doctor still
     // prescribes the correct agent-aware command via setup recommendations.
-    cachedBootDriftNotice = buildBootDriftNotice(version, registry);
+    setCachedBootDriftNotice(buildBootDriftNotice(version, registry));
 }
 let cachedClient = null;
 export async function getClient() {
@@ -69,8 +70,56 @@ export function resetClient() {
  * out to produce pathological payloads in practice, the right fix is
  * adding range/depth/filter parameters to that tool — not a blanket cap.
  */
+function errorDetails(error) {
+    if (error instanceof Error) {
+        return {
+            name: error.name,
+            message: error.message,
+            stack: error.stack,
+        };
+    }
+    return { message: String(error) };
+}
+function writeMcpStderr(event, details = {}) {
+    process.stderr.write(`[summer-mcp] ${JSON.stringify({ event, ...details })}\n`);
+}
+function installMcpProcessDiagnostics() {
+    if (processDiagnosticsInstalled)
+        return;
+    processDiagnosticsInstalled = true;
+    process.once("uncaughtException", (error) => {
+        const details = errorDetails(error);
+        appendMcpLogEvent("mcp:uncaught_exception", details);
+        writeMcpStderr("mcp:uncaught_exception", {
+            message: details.message,
+            log: "~/.summer/mcp.log",
+        });
+        process.exit(1);
+    });
+    process.once("unhandledRejection", (reason) => {
+        const details = errorDetails(reason);
+        appendMcpLogEvent("mcp:unhandled_rejection", details);
+        writeMcpStderr("mcp:unhandled_rejection", {
+            message: details.message,
+            log: "~/.summer/mcp.log",
+        });
+        process.exit(1);
+    });
+    process.once("SIGTERM", () => {
+        appendMcpLogEvent("mcp:sigterm", { pid: process.pid });
+        process.exit(0);
+    });
+    process.once("SIGINT", () => {
+        appendMcpLogEvent("mcp:sigint", { pid: process.pid });
+        process.exit(0);
+    });
+    process.once("exit", (code) => {
+        appendMcpLogEvent("mcp:exit", { pid: process.pid, code });
+    });
+}
 function installResultSizeLogger(server) {
     const original = server.tool.bind(server);
+    let registeredToolCount = 0;
     server.tool = function patchedTool(...args) {
         if (args.length < 2)
             return original(...args);
@@ -81,6 +130,7 @@ function installResultSizeLogger(server) {
         const handler = args[lastIdx];
         if (typeof handler !== "function")
             return original(...args);
+        registeredToolCount += 1;
         const wrapped = async (...handlerArgs) => {
             const startedAt = Date.now();
             const result = await handler(...handlerArgs);
@@ -133,6 +183,11 @@ function installResultSizeLogger(server) {
                             chars,
                             bytes,
                         });
+                        appendMcpLogEvent("mcp:result_size", {
+                            toolName: name,
+                            chars,
+                            bytes,
+                        });
                         process.stderr.write(`[summer-mcp] ${line}\n`);
                     }
                 }
@@ -146,25 +201,42 @@ function installResultSizeLogger(server) {
         newArgs[lastIdx] = wrapped;
         return original(...newArgs);
     };
+    return () => registeredToolCount;
 }
 export async function startMcpServer() {
+    installMcpProcessDiagnostics();
+    appendMcpLogEvent("mcp:start", {
+        version,
+        pid: process.pid,
+        node: process.version,
+        cwd: process.cwd(),
+    });
     const server = new McpServer({
         name: "summer-engine",
         version,
     });
     // Passive observability: log result-size to stderr but do not modify
     // results. See installResultSizeLogger above.
-    installResultSizeLogger(server);
+    const getRegisteredToolCount = installResultSizeLogger(server);
     registerSceneTools(server);
     registerDebugTools(server);
     registerVisualTools(server);
     registerProjectTools(server);
+    registerFileTools(server);
     registerAssetTools(server);
     registerGenerateTools(server);
     registerCloudTools(server);
     // Fire-and-forget — never block tool registration on the npm registry.
-    void probeBootDrift();
+    void probeBootDrift().catch((error) => {
+        setCachedBootDriftNotice(null);
+        appendMcpLogEvent("mcp:boot_drift_probe_failed", errorDetails(error));
+    });
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    appendMcpLogEvent("mcp:ready", {
+        version,
+        pid: process.pid,
+        toolCount: getRegisteredToolCount(),
+    });
     process.stderr.write(`[summer-mcp] MCP server running v${version}.\n`);
 }

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

@@ -168,7 +168,10 @@ async function buildImportEntriesForAsset(asset, targetPath) {
     return { imports: [{ url: fileUrl, path }], importPath: path };
 }
 async function importResolvedAsset(args) {
-    const { asset, parent, path, name } = args;
+    const { asset, parent, scenePath, path, name } = args;
+    if (parent && !scenePath) {
+        throw new Error("scenePath is required when importing an asset into a scene");
+    }
     const { imports, importPath } = await buildImportEntriesForAsset(asset, path);
     const client = await getClient();
     const importResult = imports.length === 1
@@ -176,20 +179,30 @@ async function importResolvedAsset(args) {
             { 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.");
+    const importReceipts = importResult?.results ?? [];
+    const importFailure = importReceipts.find((receipt) => receipt?.ok === false);
+    if (importResult?.status === "error" || importFailure) {
+        throw new Error(importFailure?.error || "Could not import asset. Check engine logs.");
     }
     let addedToScene = false;
+    let sceneReceipt = null;
     if (parent && asset.type === "3d_model") {
-        await client.executeOps([
+        sceneReceipt = await client.executeIdentityBoundOps([
             {
                 op: "InstantiateScene",
                 parent,
                 scene: importPath,
                 name: sanitizeNodeName(name || asset.title),
             },
-        ]);
+            { op: "SaveScene" },
+        ], { scenePath });
+        const placementReceipts = sceneReceipt?.results ?? [];
+        const placementFailure = placementReceipts.find((receipt) => receipt?.ok !== true);
+        if (sceneReceipt?.status === "error" ||
+            placementReceipts.length !== 2 ||
+            placementFailure) {
+            throw new Error(placementFailure?.error || `Could not add asset to ${scenePath}`);
+        }
         addedToScene = true;
     }
     return {
@@ -200,6 +213,8 @@ async function importResolvedAsset(args) {
         importedTo: importPath,
         addedToScene,
         parent: parent || null,
+        scenePath: scenePath || null,
+        sceneReceipt,
     };
 }
 function jsonSuccess(data) {
@@ -345,8 +360,8 @@ Cloud tool — works WITHOUT the Summer Engine app open.`, {
 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.
+pipeline. For 3D models, pass parent and scenePath to instantiate it in that
+exact scene; it does not need to be the active editor tab.
 
 Requires the Summer Engine app to be open with the project loaded (generation
 itself does not — only this import step does).`, {
@@ -359,11 +374,15 @@ itself does not — only this import step does).`, {
             .string()
             .optional()
             .describe("Optional parent node path. For 3D models only; imports and instantiates under this node."),
+        scenePath: z
+            .string()
+            .optional()
+            .describe("Required with parent. Exact res:// scene that receives the 3D model."),
         name: z
             .string()
             .optional()
             .describe("Optional scene node name when parent is provided."),
-    }, async ({ assetId, path, parent, name }) => {
+    }, async ({ assetId, path, parent, scenePath, name }) => {
         const fetched = await getAssetApi(assetId);
         if (fetched.error || !fetched.asset) {
             return jsonError({
@@ -375,6 +394,7 @@ itself does not — only this import step does).`, {
             const imported = await importResolvedAsset({
                 asset: fetched.asset,
                 parent,
+                scenePath,
                 path,
                 name,
             });
@@ -390,7 +410,7 @@ itself does not — only this import step does).`, {
             return jsonError({
                 error: "import_failed",
                 message: msg,
-                hint: "Make sure Summer Engine is running and the target scene is open.",
+                hint: "Make sure Summer Engine is running and pass the exact scenePath when parent is set.",
             });
         }
     });
@@ -402,9 +422,10 @@ Searches, picks the top result, downloads and imports it, then optionally adds i
 Requires authentication. If the user gets an auth error, they need to run 'npx summer-engine login' in their terminal first. Summer Engine must be running.`, {
         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)"),
+        scenePath: z.string().optional().describe("Required with parent. Exact res:// target scene path."),
         assetType: z.enum(["2d_image", "animation", "3d_model", "audio", "music", "all"]).default("3d_model").describe("Preferred asset type"),
         source: z.enum(["library", "my_assets", "all"]).default("all").describe("Where to search before importing"),
-    }, async ({ query, parent, assetType, source }) => {
+    }, async ({ query, parent, scenePath, assetType, source }) => {
         const searchResult = await searchAssetsApi({ query, assetType, limit: 5, source });
         if (searchResult.error) {
             return {
@@ -443,7 +464,7 @@ Requires authentication. If the user gets an auth error, they need to run 'npx s
             };
         }
         try {
-            const imported = await importResolvedAsset({ asset: best, parent });
+            const imported = await importResolvedAsset({ asset: best, parent, scenePath });
             // 2D sprites and audio: import only; user adds to scene manually
             return {
                 content: [

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

@@ -15,28 +15,28 @@ function textJson(value) {
     };
 }
 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.", {
+    server.tool("summer_cloud_init", "Enable Summer Cloud (content-addressed whole-project sync) for a project, writing the git-tracked summer-cloud.json binding. Use once per project before the first push, or after deleting the binding to fork the project into a new cloud line.", projectArg.shape, async (args) => textJson(await cloudInit({ project: args.project, face: "mcp" })));
+    server.tool("summer_cloud_status", "Show what a sync would move: file counts, paths queued to push or pull, and any waiting conflict sets. Always call this before push or pull so you can report the delete and change counts to the user; never sync blind.", projectArg.shape, async (args) => textJson(await cloudStatus({ project: args.project, face: "mcp" })));
+    server.tool("summer_cloud_push", "Upload local project changes to Summer Cloud as a new restorable version (use to back up big assets, move to another machine, or snapshot before a risky bulk op). confirmDeletes gates large deletions (more than 10 files, or >=20% of the tree, or the whole tree): run summer_cloud_status first, show the exact delete count to the user, and only set it once they confirm. Never pass confirmDeletes blindly.", {
         ...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."),
+        confirmDeletes: z.boolean().default(false).describe("Gate for large cloud deletions. Required when a push would delete more than 10 files, at least 20% of the tracked tree, or the entire tree. Surface the delete count from summer_cloud_status to the user before setting this; never set it blindly."),
+        bootstrap: bootstrap.optional().describe("No-base bootstrap choice when local and cloud both have files: keep-cloud, keep-local, or merge. Present the choice to the user."),
+        adoptPath: z.boolean().optional().describe("Accept that the project folder moved and update the recorded path. Only set after confirming the move is intentional, not a copy."),
     }, async (args) => textJson(await cloudPush({ ...args, face: "mcp" })));
-    server.tool("summer_cloud_pull", "Pull Summer Cloud changes into the local project.", {
+    server.tool("summer_cloud_pull", "Download Summer Cloud changes into the local project (use to fetch a teammate's bytes or hydrate on a second machine). A local checkpoint is written before any destructive apply, and concurrent edits become recoverable conflict sets rather than silent overwrites. Run summer_cloud_status first.", {
         ...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."),
+        bootstrap: bootstrap.optional().describe("No-base bootstrap choice when local and cloud both have files: keep-cloud, keep-local, or merge. Present the choice to the user."),
+        adoptPath: z.boolean().optional().describe("Accept that the project folder moved and update the recorded path. Only set after confirming the move is intentional, not a copy."),
     }, 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.", {
+    server.tool("summer_cloud_restore", "Roll a project back to an earlier state. Pass version to restore a retained cloud version (creates a new head version server-side, then pulls); pass checkpointStamp to restore a local pre-sync checkpoint for unpushed work. The restore restores bytes but does not delete files a later sync added, so review the extraneous-file list it returns.", {
         ...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)."),
+        version: z.number().int().positive().optional().describe("Cloud version to restore (see summer_cloud_status / version history)."),
+        checkpointStamp: z.string().optional().describe("Local checkpoint stamp (see summer_cloud_checkpoints). Use for unpushed local-only work."),
     }, 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.", {
+    server.tool("summer_cloud_checkpoints", "List the local pre-sync checkpoints taken before destructive applies. Use to find a checkpoint stamp to pass to summer_cloud_restore when recovering local-only work.", projectArg.shape, async (args) => textJson(await cloudCheckpoints({ project: args.project, face: "mcp" })));
+    server.tool("summer_cloud_conflicts", "List preserved Summer Cloud conflict sets (the losing bytes from concurrent edits, never discarded), or recover one by passing restorePath to re-enter it as a fresh edit. Use after a push or pull reports conflicts so the user can choose what to keep.", {
         ...projectArg.shape,
-        restorePath: z.string().optional().describe("Project-relative path to restore from the conflict sets."),
+        restorePath: z.string().optional().describe("Project-relative path to restore from the conflict sets, re-entered as a fresh edit."),
         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/debug-tools.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { withEngine } from "./with-engine.js";
 import { shapeEngineLogResponse } from "../../lib/log-filters.js";
+import { createDebugReportArtifact } from "../../lib/debug-report.js";
 export function registerDebugTools(server) {
     server.tool("summer_get_diagnostics", `Quick overview of all errors and warnings from both the editor console and the runtime debugger. Returns error counts and a guidance message.
 
@@ -92,11 +93,53 @@ After starting, use summer_get_diagnostics to check for runtime errors.
 You can run a specific scene instead of the main scene — useful for testing individual levels or UI screens.`, {
         scene: z.string().optional().describe("Scene to run instead of main scene, e.g. 'res://levels/test_level.tscn'"),
     }, async ({ scene }) => withEngine(async (client) => client.play(scene)));
-    server.tool("summer_stop", "Stop the running game. Call this before making scene changes — some operations require the game to not be running.", {}, async () => withEngine(async (client) => client.stop()));
+    server.tool("summer_stop", "Stop the running game. Use after runtime verification or when you intentionally need to restart the running instance; ordinary editor scene mutations do not require a blanket stop.", {}, async () => withEngine(async (client) => client.stop()));
     server.tool("summer_is_running", "Check if the game is currently running. Returns the active scene path if running.", {}, async () => withEngine(async (client) => client.executeOps([{ op: "IsGameRunning" }])));
     server.tool("summer_get_script_errors", `Check a GDScript file for parse/compile errors without running the game.
 
 Use after writing or editing a .gd file to verify it compiles. Returns line numbers, error messages, and severity. Much faster than running the game to discover script errors.`, {
         path: z.string().describe("Script path, e.g. 'res://scripts/player.gd' or 'res://player_controller.gd'"),
     }, async ({ path }) => withEngine(async (client) => client.getScriptErrors(path)));
+    server.tool("summer_create_debug_report", `Create a support-ready Markdown report for /summer debug.
+
+Use this when the user says "/summer debug", asks to send Summer a bug report,
+or needs a portable artifact from a failing Codex/cloud/agent session. The
+report includes Summer doctor checks, engine health, diagnostics, console
+output, debugger errors/warnings, and an agent handoff prompt. It omits auth
+tokens and project file contents, but the user should still review it before
+sending because local paths and stack traces may appear.`, {
+        issue: z.string().optional().describe("User-visible issue or repro summary."),
+        output_path: z.string().optional().describe("Where to write the Markdown report. Defaults to the open project root, or the current working directory if no project is open."),
+        include_play_session: z.boolean().optional().default(false).describe("Launch the game briefly and collect post-play diagnostics."),
+        play_wait_ms: z.number().optional().default(2500).describe("Milliseconds to wait after launching the game when include_play_session is true."),
+        max_console_lines: z.number().optional().default(200).describe("Console lines to include after filtering/deduping."),
+        max_debugger_entries: z.number().optional().default(100).describe("Debugger error/warning entries to include after filtering/deduping."),
+        include_doctor: z.boolean().optional().default(true).describe("Include summer doctor checks in the report."),
+    }, async ({ issue, output_path, include_play_session, play_wait_ms, max_console_lines, max_debugger_entries, include_doctor, }) => {
+        const artifact = await createDebugReportArtifact({
+            issue,
+            outputPath: output_path,
+            includePlaySession: include_play_session,
+            playWaitMs: play_wait_ms,
+            maxConsoleLines: max_console_lines,
+            maxDebuggerEntries: max_debugger_entries,
+            includeDoctor: include_doctor,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        ok: true,
+                        path: artifact.path,
+                        engineConnected: artifact.report.engine.connected,
+                        generatedAt: artifact.report.generatedAt,
+                        issue: artifact.report.issue,
+                        doctorSummary: artifact.report.doctor?.summary ?? null,
+                        reviewNote: "Report omits auth tokens, but the user should review local paths and stack traces before sending.",
+                    }, null, 2),
+                },
+            ],
+        };
+    });
 }

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

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