summer-engine 3.2.1 → 3.4.0

package/dist/mcp/hosted-mount.js

@@ -0,0 +1,200 @@
+import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { connectHostedMcp } from "../core/hosted-mcp.js";
+import { getStoreAccessToken, OAuthError, resolveMcpResourceUrl } from "../core/oauth.js";
+import { appendMcpLogEvent } from "../core/mcp-log.js";
+/**
+ * One Summer Engine MCP. The cloud tools a creator's agent needs to publish
+ * (projects, store page, build upload, submit for the owner's approval, the
+ * board, Grow) live on the hosted Summer Engine MCP at mcp.summerengine.com,
+ * the same server ChatGPT and Claude connect to. This module mounts them into
+ * the local MCP so a local agent sees one server: each hosted tool, prompt
+ * and resource is registered here under its own name and forwarded with the
+ * person's store sign-in ("summer login --store"; the token's audience is
+ * that server). A name the local MCP already has stays local (the engine and
+ * generation tools keep their CLI-token path).
+ *
+ * Mounting runs after connect. The first tools/list waits for a mount in
+ * progress (up to FIRST_LIST_WAIT_MS), so a host that lists tools once still
+ * sees the store tools; a slower mount adds them later (tools/list_changed).
+ * Without a store sign-in the mount fails at once, and one tool,
+ * summer_store_tools, says how to sign in and mounts on the next call.
+ */
+export const STORE_TOOLS_STATUS = "summer_store_tools";
+/** How long the first tools/list waits for a mount in progress, so hosts that list once see the store tools. */
+export const FIRST_LIST_WAIT_MS = 5_000;
+const passthroughArgs = z.object({}).passthrough();
+export const defaultHostedMountDependencies = {
+    url: () => resolveMcpResourceUrl(),
+    token: () => getStoreAccessToken(),
+    connect: connectHostedMcp,
+};
+async function listAll(page, key) {
+    const out = [];
+    let cursor;
+    for (let pages = 0; pages < 20; pages++) {
+        const result = await page(cursor);
+        out.push(...(result[key] ?? []));
+        if (!result.nextCursor)
+            break;
+        cursor = result.nextCursor;
+    }
+    return out;
+}
+function errorText(error) {
+    return { content: [{ type: "text", text: JSON.stringify({ ok: false, ...error }) }], isError: true };
+}
+/**
+ * Get the server ready for hosted tools before the transport connects (the
+ * SDK fixes capabilities at connect): resource handlers exist, and tools/list
+ * reports each mounted tool's own JSON Schema rather than the passthrough one.
+ * Returns mount(), which callers run after connect without awaiting it.
+ */
+export function prepareHostedMount(server, deps = defaultHostedMountDependencies, options = {}) {
+    const firstListWaitMs = options.firstListWaitMs ?? FIRST_LIST_WAIT_MS;
+    let listed = false;
+    const state = { status: "idle", tools: [], prompts: [], resources: [], collisions: [] };
+    const schemas = new Map();
+    const registries = server;
+    // Declare the resources capability now: registering one and removing it
+    // keeps the handlers (and capability) without listing anything yet.
+    server.registerResource("summer-hosted-placeholder", "summer://hosted/placeholder", {}, async () => ({ contents: [] })).remove();
+    // tools/list as the SDK builds it, with mounted tools carrying their hosted schema.
+    const handlers = server.server._requestHandlers;
+    const listTools = handlers.get("tools/list");
+    if (listTools) {
+        server.server.setRequestHandler(ListToolsRequestSchema, async (request, extra) => {
+            if (!listed) {
+                listed = true;
+                await waitForMount(firstListWaitMs);
+            }
+            const result = await listTools(request, extra);
+            return {
+                ...result,
+                tools: result.tools.map((tool) => {
+                    const hosted = schemas.get(tool.name);
+                    return hosted ? { ...tool, inputSchema: hosted.inputSchema, ...(hosted.annotations ? { annotations: hosted.annotations } : {}), ...(hosted.title ? { title: hosted.title } : {}) } : tool;
+                }),
+            };
+        });
+    }
+    let statusTool = null;
+    let running = null;
+    /** Wait for a mount in progress, at most ms; returns at once when none runs. */
+    async function waitForMount(ms) {
+        if (!running || ms <= 0)
+            return;
+        let timer;
+        await Promise.race([running, new Promise((done) => (timer = setTimeout(done, ms)))]);
+        clearTimeout(timer);
+    }
+    const showStatusTool = () => {
+        if (statusTool || STORE_TOOLS_STATUS in registries._registeredTools)
+            return;
+        statusTool = server.registerTool(STORE_TOOLS_STATUS, {
+            description: "The Summer store, publishing, board and Grow tools come from the hosted Summer Engine MCP and are not loaded. Call this to see why and how to fix it (usually: run \"summer login --store\" in a terminal); it loads them when the sign-in works.",
+            inputSchema: passthroughArgs,
+        }, async () => {
+            const after = await mount();
+            if (after.status === "mounted") {
+                return { content: [{ type: "text", text: JSON.stringify({ ok: true, loaded: after.tools.length, tools: after.tools }) }] };
+            }
+            return errorText(after.error ?? { code: "store_tools_unavailable", message: "The hosted tools are not loaded.", recovery: 'Recovery: run "summer login --store", then call this again.' });
+        });
+    };
+    async function attempt() {
+        let client;
+        try {
+            const url = deps.url();
+            await deps.token();
+            client = await deps.connect(url, deps.token);
+        }
+        catch (error) {
+            state.status = "unavailable";
+            state.error =
+                error instanceof OAuthError
+                    ? { code: error.code, message: error.message.replace(` ${error.recovery}`, ""), recovery: error.recovery }
+                    : {
+                        code: "store_tools_unreachable",
+                        message: `The hosted Summer Engine MCP did not answer: ${error instanceof Error ? error.message : String(error)}.`,
+                        recovery: 'Recovery: check the network; if it says unauthorized, run "summer login --store --force". Then call summer_store_tools.',
+                    };
+            appendMcpLogEvent("mcp:hosted_mount_failed", { code: state.error.code });
+            showStatusTool();
+            return state;
+        }
+        const [tools, prompts, resources] = await Promise.all([
+            listAll((cursor) => client.listTools(cursor ? { cursor } : undefined), "tools"),
+            listAll((cursor) => client.listPrompts(cursor ? { cursor } : undefined), "prompts").catch(() => []),
+            listAll((cursor) => client.listResources(cursor ? { cursor } : undefined), "resources").catch(() => []),
+        ]);
+        for (const tool of tools) {
+            if (tool.name in registries._registeredTools && !schemas.has(tool.name)) {
+                if (tool.name !== STORE_TOOLS_STATUS)
+                    state.collisions.push(tool.name);
+                continue;
+            }
+            if (schemas.has(tool.name))
+                continue;
+            schemas.set(tool.name, tool);
+            server.registerTool(tool.name, { description: tool.description ?? "", inputSchema: passthroughArgs, ...(tool.annotations ? { annotations: tool.annotations } : {}) }, async (args) => {
+                try {
+                    return (await client.callTool({ name: tool.name, arguments: args }));
+                }
+                catch (error) {
+                    return errorText({
+                        code: "store_tool_failed",
+                        message: `The hosted Summer Engine MCP did not complete ${tool.name}: ${error instanceof Error ? error.message : String(error)}.`,
+                        recovery: 'Recovery: retry; if it says unauthorized, run "summer login --store --force".',
+                    });
+                }
+            });
+            state.tools.push(tool.name);
+        }
+        for (const prompt of prompts) {
+            if (prompt.name in registries._registeredPrompts) {
+                if (!state.prompts.includes(prompt.name))
+                    state.collisions.push(`prompt:${prompt.name}`);
+                continue;
+            }
+            const shape = Object.fromEntries((prompt.arguments ?? []).map((arg) => [arg.name, arg.required ? z.string().describe(arg.description ?? "") : z.string().optional().describe(arg.description ?? "")]));
+            server.registerPrompt(prompt.name, { ...(prompt.title ? { title: prompt.title } : {}), ...(prompt.description ? { description: prompt.description } : {}), ...(prompt.arguments?.length ? { argsSchema: shape } : {}) }, (async (args = {}) => client.getPrompt({ name: prompt.name, arguments: Object.fromEntries(Object.entries(args).filter((entry) => typeof entry[1] === "string")) })));
+            state.prompts.push(prompt.name);
+        }
+        for (const resource of resources) {
+            if (resource.uri in registries._registeredResources) {
+                if (!state.resources.includes(resource.uri))
+                    state.collisions.push(`resource:${resource.uri}`);
+                continue;
+            }
+            server.registerResource(resource.name, resource.uri, { ...(resource.title ? { title: resource.title } : {}), ...(resource.description ? { description: resource.description } : {}), ...(resource.mimeType ? { mimeType: resource.mimeType } : {}) }, async (uri) => (await client.readResource({ uri: uri.href })));
+            state.resources.push(resource.uri);
+        }
+        statusTool?.remove();
+        statusTool = null;
+        state.status = "mounted";
+        delete state.error;
+        appendMcpLogEvent("mcp:hosted_mounted", { tools: state.tools.length, prompts: state.prompts.length, resources: state.resources.length, collisions: state.collisions.length });
+        return state;
+    }
+    /** Mount once; a failed mount runs again on the next call. */
+    function mount() {
+        if (state.status === "mounted")
+            return Promise.resolve(state);
+        if (!running) {
+            state.status = "mounting";
+            running = attempt()
+                .catch((error) => {
+                state.status = "unavailable";
+                state.error = { code: "store_tools_unreachable", message: error instanceof Error ? error.message : String(error), recovery: "Recovery: call summer_store_tools to retry." };
+                showStatusTool();
+                return state;
+            })
+                .finally(() => {
+                running = null;
+            });
+        }
+        return running;
+    }
+    return { mount, state };
+}

package/dist/mcp/server.d.ts

@@ -10,7 +10,8 @@ export declare const getCachedBootDriftNotice: typeof getCachedNotice;
  * (docs/design/archive/E2E-2026-09-03.md, F-17) showed an agent needs on the first
  * turn and would otherwise learn the hard way. Kept under 600 characters so
  * it costs a few hundred tokens once; the full operating guide stays in the
- * summer_agent_playbook prompt / summer_get_agent_playbook tool.
+ * summer_agent_playbook prompt / summer_get_agent_playbook tool. The last
+ * sentence names the publishing path and the owner-approval rule.
  */
 export declare const SUMMER_MCP_INSTRUCTIONS: string;
 export declare function configureMcpEngineSelection(selection?: EngineSelection): void;

package/dist/mcp/server.js

@@ -26,6 +26,7 @@ import { registerNavigationTools } from "./tools/navigation-tools.js";
 import { registerLibraryTools } from "./tools/library-tools.js";
 import { getCachedBootDriftNotice as getCachedNotice, setCachedBootDriftNotice, } from "./boot-notice.js";
 import { appendMcpLogEvent } from "../core/mcp-log.js";
+import { prepareHostedMount } from "./hosted-mount.js";
 import { buildBootDriftNotice, fetchLatestRegistryVersion, } from "../installer/version-check.js";
 import { TOOLKIT_VERSION as version } from "../core/version.js";
 let processDiagnosticsInstalled = false;
@@ -37,13 +38,15 @@ export const getCachedBootDriftNotice = getCachedNotice;
  * (docs/design/archive/E2E-2026-09-03.md, F-17) showed an agent needs on the first
  * turn and would otherwise learn the hard way. Kept under 600 characters so
  * it costs a few hundred tokens once; the full operating guide stays in the
- * summer_agent_playbook prompt / summer_get_agent_playbook tool.
+ * summer_agent_playbook prompt / summer_get_agent_playbook tool. The last
+ * sentence names the publishing path and the owner-approval rule.
  */
-export const SUMMER_MCP_INSTRUCTIONS = "Summer Engine MCP. Call summer_get_project_context first: it binds this session to the open project and returns mainScene, projectMemory (GameSoul, template pin) and any capabilitySkewWarning, compactly. " +
-    "Before building or fixing, summer_search_library then summer_read_library the hit: skills, examples, templates live there. " +
-    "After a playthrough read summer_get_diagnostics, not summer_get_console alone (runtime errors live in the debugger). " +
-    "An all-black screenshot means the viewport had not redrawn — recapture before concluding. " +
-    "Report entries you verified in-engine via summer_library_feedback.";
+export const SUMMER_MCP_INSTRUCTIONS = "Summer Engine MCP. Call summer_get_project_context first: it binds the open project and returns mainScene, projectMemory and any capabilitySkewWarning. " +
+    "Before building or fixing, summer_search_library then summer_read_library the hit. " +
+    "After a playthrough read summer_get_diagnostics, not summer_get_console alone. " +
+    "An all-black screenshot means the viewport had not redrawn: recapture. " +
+    "Report verified entries via summer_library_feedback. " +
+    "Publishing: summer_export_game, summer_publish_build, summer_store_*; an agent never publishes alone: summer_store_submit returns the owner's approval link.";
 /**
  * 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
@@ -352,8 +355,13 @@ export async function startMcpServer(options = {}) {
         setCachedBootDriftNotice(null);
         appendMcpLogEvent("mcp:boot_drift_probe_failed", errorDetails(error));
     });
+    // Hosted Summer Engine MCP tools (store, publishing, board, Grow): ready
+    // before connect, mounted after it. The first tools/list waits a few
+    // seconds for the mount (not under summer doctor, which times the list).
+    const hosted = prepareHostedMount(server, undefined, process.env.SUMMER_MCP_DOCTOR === "1" ? { firstListWaitMs: 0 } : {});
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    void hosted.mount();
     appendMcpLogEvent("mcp:ready", {
         version,
         pid: process.pid,

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

@@ -1,5 +1,11 @@
 import { z } from "zod";
 import { CreatorOperationError, listCreatorReleases, publishCreator, } from "../../core/capabilities/creator.js";
+import { captureGameplay } from "../../core/capabilities/capture-gameplay.js";
+import { exportGame } from "../../core/capabilities/export-game.js";
+import { STORE_TARGETS } from "../../core/capabilities/export-presets.js";
+import { exportTemplates, TEMPLATE_PLATFORMS } from "../../core/capabilities/export-templates.js";
+import { publishBuild } from "../../core/capabilities/publish-build.js";
+import { BuildToolError } from "../../core/capabilities/summer-bundle.js";
 import { CONFIG_KEYS, getConfigValue, isConfigKey, readSummerConfig, setConfigValue, unsetConfigValue, } from "../../core/config.js";
 import { textJson } from "./text-json.js";
 async function creatorResult(operation) {
@@ -16,6 +22,16 @@ async function creatorResult(operation) {
                 recovery: error.recovery,
             }, true);
         }
+        if (error instanceof BuildToolError) {
+            return textJson({
+                ok: false,
+                code: error.code,
+                message: error.message.replace(` ${error.recovery}`, ""),
+                recovery: error.recovery,
+                ...(error.status ? { status: error.status } : {}),
+                ...error.detail,
+            }, true);
+        }
         return textJson({
             ok: false,
             code: "creator_request_invalid",
@@ -24,7 +40,54 @@ async function creatorResult(operation) {
     }
 }
 export function registerCreatorTools(server) {
-    server.tool("summer_creator_publish", "Publish an exact exported Summer .pck through the versioned Summer Platform creator API. First call with confirm=false and present the returned project, version, digest, size, artifact path, channel, and notes; set confirm only after the user approves that exact target. The server independently verifies token scope, ownership, bytes, and review state.", {
+    server.tool("summer_export_game", "Export the game in the exact file the Summer Games store takes, with the installed Summer Engine headless (no window). format \"bundle\" (default): the summer.games .zip the Summer apps run on iPhone, Android, macOS and Windows; targets picks the platforms (a game without a server: ios and android only); upload it with summer_publish_build. format \"download\" with one target: web (an HTML5 .zip on Summer's WebGPU Forward+ web template, played on summer.games), macos (.app zip, macos-universal) or windows (.exe zip, windows-x64); these need the export template from summer_export_templates and are uploaded as store versions. Needs Summer Engine 0.7.0 or newer: an older engine is refused before anything is written (code engine_too_old). Works without the editor running. Returns path, sha256, size, the manifest or store platform, and warnings.", {
+        project: z.string().optional().describe("Project folder with project.godot. Defaults to the MCP's bound project, then the working directory."),
+        out: z.string().optional().describe("Output .zip path. Defaults to <project>/.summer/exports/."),
+        targets: z
+            .array(z.enum(STORE_TARGETS))
+            .optional()
+            .describe("Store platforms. Bundle: any of macos, windows, ios, android (omit to use every platform the project declares). Download: exactly one of web, macos, windows."),
+        format: z
+            .enum(["bundle", "download"])
+            .optional()
+            .describe("bundle (default): the summer.games store build. download: a web build or native download; the default when targets is [\"web\"]."),
+        debug: z.boolean().default(false).describe("Export a debug build (--export-debug)."),
+        timeoutSeconds: z.number().int().min(10).max(7200).optional().describe("Stop the engine after this many seconds (default 900; a first export imports every asset)."),
+    }, async ({ project, out, targets, format, debug, timeoutSeconds }) => creatorResult(() => exportGame({ project, out, targets, format, debug, ...(timeoutSeconds ? { timeoutMs: timeoutSeconds * 1000 } : {}) })));
+    server.tool("summer_export_templates", "List, download and install Summer Engine export templates from Summer's CDN into the folder the installed engine reads, checking each file's sha256. Needed only for summer_export_game format \"download\": web (Summer's WebGPU Forward+ template), macos, windows. Store bundles (format \"bundle\") need no template. action list shows what is installed and published; action install fetches the platforms asked (default web).", {
+        action: z.enum(["list", "install"]).describe("list: installed and published templates. install: download and install."),
+        platforms: z
+            .array(z.enum(TEMPLATE_PLATFORMS))
+            .optional()
+            .describe("Template platforms to install (default [\"web\"])."),
+        includeDebug: z.boolean().default(false).describe("Also install the debug templates (for exports with debug true)."),
+        summerVersion: z
+            .string()
+            .optional()
+            .describe("The installed Summer Engine version (Help > About, e.g. 0.7.1). Read automatically on macOS; needed on Windows and Linux."),
+    }, async ({ action, platforms, includeDebug, summerVersion }) => creatorResult(() => exportTemplates({ action, platforms, includeDebug, summerVersion })));
+    server.tool("summer_capture_gameplay", "Capture real gameplay frames without a running editor: starts the game in Summer Engine's offscreen verify instance (a real renderer, a window parked offscreen with no focus, never on screen), lets it run waitSeconds, and saves PNG frames of what the game draws, HUD included. Use for store screenshots (1920x1080 landscape or 1080x1920 portrait). With an editor open, summer_screenshot target game also works. Returns each frame's path, width and height; look at them before using them.", {
+        project: z.string().optional().describe("Project folder with project.godot. Defaults to the MCP's bound project, then the working directory."),
+        scene: z.string().optional().describe("Scene to start (res://... or uid://...). Default: the project's main scene, which is often a title menu; pass the gameplay scene for gameplay frames."),
+        resolution: z.string().optional().describe("Window size WIDTHxHEIGHT (default 1920x1080; 1080x1920 for portrait)."),
+        frames: z.number().int().min(1).max(10).optional().describe("Frames to save (default 1)."),
+        waitSeconds: z.number().min(0).max(120).optional().describe("Seconds the game runs before the first frame (default 3)."),
+        intervalSeconds: z.number().min(0.1).max(60).optional().describe("Seconds between frames (default 1)."),
+        out: z.string().optional().describe("Output folder. Defaults to <project>/.summer/captures/<time>/ (ignored by git)."),
+    }, async (args) => creatorResult(() => captureGameplay(args)));
+    server.tool("summer_publish_build", "Upload an export from summer_export_game to the creator's game on summer.games, through the same store upload Studio uses, straight from disk. A store bundle (format bundle): declare, upload parts, seal, wait until Summer makes the Build, name its client pack, and with publish=true approve it. A web build or native download (format download): upload it as the game's store version for its platform (web, macos-universal, windows-x64, linux-x64; read from the last export) and wait until Summer has checked it. First call with confirm=false: it checks that the game exists for this account and warns when its store page does not list the export's platforms, then returns the target (game name and id, file, digest, size, version) to show the user; set confirm only after they approve. Needs \"summer login --store\". A retry with the same file and clientVersion continues the same upload. Nothing here makes a game live: the owner approves publishing (summer_store_submit).", {
+        gameId: z.string().optional().describe("The store game id (from summer_store_list_games, or the Studio store page URL). Without it the call fails with game_required and lists your store games, or says why the store did not list them."),
+        file: z.string().optional().describe("Exported .zip. Defaults to the last summer_export_game result."),
+        clientVersion: z.string().describe("Build version, vMAJOR.MINOR.PATCH (e.g. v1.0.0); a new upload needs a new version."),
+        publish: z.boolean().default(false).describe("Bundles only: also approve the Build for players. A game that has not passed review keeps it as a preview; an agent needs the owner's approval."),
+        platform: z
+            .enum(["web", "macos-universal", "windows-x64", "linux-x64"])
+            .optional()
+            .describe("Web builds and native downloads: the store platform. Defaults to the last export's platform; omit for a store bundle."),
+        confirm: z.boolean().default(false).describe("Set true only after the user approves the exact upload."),
+        waitSeconds: z.number().int().min(0).max(1800).optional().describe("How long to wait for Summer to make the Build (default 600). On timeout, call again to keep waiting."),
+    }, async (args) => creatorResult(() => publishBuild({ ...args, face: "mcp" })));
+    server.tool("summer_creator_publish", "Deprecated: use summer_export_game, then summer_publish_build, which upload the summer.games .zip to the game's store listing. This old path publishes a .pck to the legacy Summercraft creator API with a separate sc_ token and will be removed. First call with confirm=false and present the returned project, version, digest, size, artifact path, channel, and notes; set confirm only after the user approves that exact target. The server independently verifies token scope, ownership, bytes, and review state.", {
         project: z.string().optional().describe("Project root. Defaults to the current working directory."),
         artifact: z.string().describe("Exact path to the exported Summer .pck artifact."),
         version: z.string().describe("Immutable release version."),

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

@@ -297,19 +297,29 @@ Style presets: "realistic" (default), "cartoon", "anime", "none"
 For an alpha PNG, set removeBackground: true. Prompt wording alone does not
 guarantee transparency; background removal runs server-side after generation.
 
-The 'options' object is passed directly to the AI provider for full control.
+Size: aspectRatio (1:1, 16:9, 9:16, 4:3, 3:4, ...) or width + height (the
+smallest size you need). For store art ask width 1920 height 1080 (key art)
+or width 1080 height 1920 (tall cover): the server picks a model that reaches
+that size, or refuses a named model that cannot, before anything is spent.
+Each result reports the real width and height and the model that ran.
+
+'options' carries extra model params (seed, negative_prompt, ...); the result
+lists any the server did not use in ignoredOptions.
 
 Returns the asset with fileUrl (hosted) and localPath (temp file on disk).
 Use the Read tool on localPath to show the image to the user for approval.
 
 Cloud tool — runs on Summer's servers and works WITHOUT the Summer Engine app open.
-Requires authentication: run 'npx -y summer-engine@latest login' first.`, imageGenerationArgsSchema.shape, async ({ prompt, model, style, referenceImageUrl, removeBackground, options }) => {
+Requires authentication: run 'npx -y summer-engine@latest login' first.`, imageGenerationArgsSchema.shape, async ({ prompt, model, style, referenceImageUrl, removeBackground, aspectRatio, width, height, options }) => {
         const result = await mcpGenerate("/api/mcp/generate/image", {
             prompt,
             model,
             style,
             referenceImageUrl,
             removeBackground,
+            aspectRatio,
+            width,
+            height,
             options,
         });
         if (result.error) {

package/gemini-extension.json

@@ -1,7 +1,7 @@
 {
   "_generated": "GENERATED from integrations/gemini — do not edit; npm run generate:registry",
   "name": "summer",
-  "version": "3.2.1",
+  "version": "3.4.0",
   "description": "Agent tooling for Summer Engine: MCP bridge, context primer, and game-dev skills. Use with the npm CLI for skill files on disk.",
   "contextFileName": "GEMINI.md",
   "mcpServers": {
@@ -35,6 +35,7 @@
     "./library/skills/asset-strategy/",
     "./library/skills/audio-direction/",
     "./library/skills/auto-fire-targeting/",
+    "./library/skills/bounded-engine-runs/",
     "./library/skills/brainstorm-game/",
     "./library/skills/brainstorming/",
     "./library/skills/browse-templates/",
@@ -46,6 +47,7 @@
     "./library/skills/character-portrait/",
     "./library/skills/cinematic-cutscene/",
     "./library/skills/combat-basics/",
+    "./library/skills/compatibility-renderer-traps/",
     "./library/skills/concept-art/",
     "./library/skills/create-asset-sheet/",
     "./library/skills/debug/",

package/library/references/mcp-tools-reference/mcp-tools-reference.md

@@ -17,7 +17,7 @@
 
 **Rule of thumb:** project reads/writes go through Summer; live hierarchy/inspector changes use scene tools; process-level work remains with the host.
 
-## Tool surface (101 tools)
+## Tool surface (105 tools)
 
 ### Project files (4)
 
@@ -237,13 +237,17 @@ Preview. One fast, read-only call that walks every node of a 3D scene and lists
 | `summer_get_project_context` | Project, scene, and `.summer` memory summary — call at start of session. Binds the session to the open project and surfaces a `capabilitySkewWarning` when the engine build and CLI have drifted; tools whose op the engine provably lacks return a structured `engine_lacks_op` result instead of running. Compact by default (a few KB: `sceneSummary`, scalar `health` with capability counts); `include:['scene_tree','capabilities','settings']` adds the heavy blocks, `omitted` says how. |
 | `summer_get_agent_playbook` | Daily operating contract (observe-first loop, content routing, invariants, verification ritual) — call at start of session. Also served natively as the `summer_agent_playbook` MCP prompt. |
 
-### Creator platform (3)
+### Creator platform (7)
 
 | Tool | Use |
 |---|---|
-| `summer_creator_publish` | Compute the exact `.pck` digest and size, require user confirmation, then run versioned prepare → write-once upload → finalize. The server independently verifies `publish` scope, ownership, bytes, and review state. |
+| `summer_export_game` | Export the game in the file the Summer Games store takes, headless (no window), no running editor needed. `format:"bundle"` (default): the `summer.games` `.zip` the Summer apps run; `targets` picks `ios`, `android`, `macos`, `windows` (a game without a server: phones only) through a named `summer.games <targets>` preset in `export_presets.cfg`. `format:"download"` with one target: `web` (HTML5 `.zip` on Summer's WebGPU Forward+ template; refuses Compatibility projects), `macos` (ad hoc signed `.app` zip, `macos-universal`) or `windows` (`.exe` with embedded pack, zipped, `windows-x64`). Returns path, sha256, size, bundle manifest or store platform, warnings. |
+| `summer_export_templates` | `list` or `install` export templates from Summer's CDN (`downloads.summer.games/engine-templates/<summerVersion>/manifest.json`) into the engine's user template folder (`<data>/Godot/export_templates/<FULL_CONFIG>/`), sha256-checked. Only download exports need them; store bundles need none. `summerVersion` is read on macOS, passed elsewhere. |
+| `summer_publish_build` | Upload that `.zip` to the creator's game through Studio's store upload: confirm-gated preview first, then declare, part upload from disk, seal, wait for the Build, name its client pack; `publish:true` also approves it. Needs `summer login --store`; a retry with the same file and version continues the same upload. |
+| `summer_creator_publish` | **Deprecated** (use the two tools above). Compute the exact `.pck` digest and size, require user confirmation, then run versioned prepare → write-once upload → finalize. The server independently verifies `publish` scope, ownership, bytes, and review state. |
 | `summer_creator_releases` | List real creator-owned releases from `summer.creator.v1`, with opaque cursor pagination. |
 | `summer_creator_config` | Read or confirm updates to the shared non-secret `~/.summer/config.json`. It never accepts or returns tokens. |
+| `summer_capture_gameplay` | Real gameplay frames without a running editor: starts the game (main scene or `scene`) in the engine's offscreen verify instance (`--summer-verify`, real renderer, window parked offscreen, no focus) at `resolution` (default `1920x1080`), waits `waitSeconds`, saves `frames` PNGs (HUD included) to `<project>/.summer/captures/<time>/`. Imports the project first when `.godot/` is missing. Returns each path with its real width and height; warns when the stretch settings render another size. For store screenshots. |
 
 ### Library search (2)
 

package/library/skills/README.md

@@ -1,6 +1,6 @@
 # Summer skills
 
-> 116 skills, grouped by their primary domain. **Generated** by `npm run generate:registry` from each skill's `resource.yaml`; `--check` fails when this file and the library disagree. Do not edit by hand.
+> 118 skills, grouped by their primary domain. **Generated** by `npm run generate:registry` from each skill's `resource.yaml`; `--check` fails when this file and the library disagree. Do not edit by hand.
 
 The folder is flat on purpose (`docs/design/DECISIONS.md`, D3): a skill usually belongs to several domains, so categories live in each skill's `facets.domains` and this index is rendered from them. The first domain listed is the primary one. `summer skills list --by-domain` prints the same grouping; `summer skills info <slug>` shows one skill.
 
@@ -10,7 +10,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 
 - [2d](#2d) (10)
 - [3d](#3d) (6)
-- [agent-workflow](#agent-workflow) (17)
+- [agent-workflow](#agent-workflow) (18)
 - [ai](#ai) (2)
 - [animation](#animation) (7)
 - [assets](#assets) (3)
@@ -24,7 +24,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 - [multiplayer](#multiplayer) (16)
 - [navigation](#navigation) (1)
 - [performance](#performance) (1)
-- [rendering](#rendering) (5)
+- [rendering](#rendering) (6)
 - [runtime](#runtime) (1)
 - [scenes](#scenes) (12)
 - [scripting](#scripting) (2)
@@ -62,6 +62,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 
 | skill | when to use | also |
 |---|---|---|
+| [*bounded-engine-runs*](./bounded-engine-runs/SKILL.md) ★ (preview) | Run Summer headless or offscreen safely from an agent: time limits, one engine per project, muted runs, import passes, tests that fail on crashes. | headless, verification |
 | [brainstorming](./brainstorming/SKILL.md) ★ | Explore user intent, requirements, and design before implementation — must run before any creative work: features, components, mechanics, behavior. | game-design |
 | [debugging-game-feel](./debugging-game-feel/SKILL.md) | Debug features that work but feel wrong — floaty jumps, mushy combat, sluggish camera — subjective bugs living in tuning, timing, and feedback layers. | gameplay |
 | [diagnosing-perf-regressions](./diagnosing-perf-regressions/SKILL.md) | Find why frame rate, frame time, or load time got worse since a known-good state — regression hunting, not general performance tuning. | performance |
@@ -152,7 +153,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 | [*celeste-momentum-platforming*](./celeste-momentum-platforming/SKILL.md) (preview) | Celeste-style 2D precision platformer movement — momentum running, coyote time, variable jumps, dash, wall jump/slide, climb stamina, pixel corner correction. | character-controller, game-design |
 | [*combat-basics*](./combat-basics/SKILL.md) (preview) | Damage in Summer Engine: hitbox and hurtbox Areas on opposing layers, a reusable Health component, damage signals, knockback, hit feedback, projectiles. | scripting, game-design |
 | [design-mechanic](./design-mechanic/SKILL.md) ★ | Design one game mechanic in detail — input, response, feedback, failure modes, depth, tunables — outputs a design doc, node-graph sketch, GDScript stub. | game-design |
-| [*in-game-purchases*](./in-game-purchases/SKILL.md) (preview) | Sell items for Sparks and let short players buy Sparks in game via the Summer purchase sheet: checkout, Sparks purchase, results, testing, store policy. | scripting, game-design |
+| [*in-game-purchases*](./in-game-purchases/SKILL.md) (preview) | Sell items for Sparks in a game shop via the Summer purchase sheet: checkout, results, not enough Sparks, inventory unlocks, authority grants, store policy. | scripting, game-design |
 | [*web-and-touch-input*](./web-and-touch-input/SKILL.md) ★ (preview) | Input for the browser and phones: the first-click rule for sound and mouse capture, focus, and touch buttons or a virtual stick on the same actions. | ui |
 
 ## level-design
@@ -201,6 +202,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 |---|---|---|
 | [3d-lighting](./3d-lighting/SKILL.md) ★ | Set up 3D scene lighting — DirectionalLight3D vs Omni vs Spot, WorldEnvironment, sky, shadow tuning, ambient — per current Summer conventions. | lighting |
 | [art-direction](./art-direction/SKILL.md) ★ | Define the game's visual style — references, palette, mood, lighting plan, post-processing, do/don't list — output as an art bible at .summer/art-bible.md. | lighting |
+| [*compatibility-renderer-traps*](./compatibility-renderer-traps/SKILL.md) ★ (preview) | Make a Forward+ Summer game also look right on the Compatibility renderer: instance-uniform budget, black MultiMesh colors, sRGB vertex colors. | performance |
 | [*psx-retro-rendering*](./psx-retro-rendering/SKILL.md) (preview) | Hardware-informed PlayStation 1 rendering in Godot 4 — low-res output, RGB5 and exact dither, affine textures, vertex snapping, blend modes, fog; limits named. | 3d |
 | [*realtime-wet-surfaces*](./realtime-wet-surfaces/SKILL.md) (preview) | Real-time wetness on existing Godot 4 materials without losing their values — value-copying wet shader, geometry-driven wet mask, instance-uniform wet amount. | vfx |
 | [*web-compatibility-look*](./web-compatibility-look/SKILL.md) ★ (preview) | Make a web or browser game look high-end in the Compatibility renderer (WebGL 2): what works, what to avoid, 2D and 3D recipes, web performance. | 2d, 3d |

package/library/skills/bounded-engine-runs/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: bounded-engine-runs
+description: "Run Summer headless or offscreen safely from an agent: time limits, one engine per project, muted runs, import passes, tests that fail on crashes."
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: workflow
+user-invocable: true
+allowed-tools: Read Grep Glob Edit Write Bash
+paths: ["project.godot", "tests/**/*.gd", "tools/**/*.gd"]
+---
+
+# Bounded engine runs for agents
+
+Agents verify games by running the engine many times: imports, tests, captures, multiplayer bots. Each run
+that hangs, overlaps another, makes noise or hides an error costs time and trust. These rules come from a
+day of several agents sharing one project on one Mac.
+
+## 1. Every run is bounded, muted and alone
+
+- **Bound it.** macOS has no `timeout`. Wrap runs so the engine itself gets killed:
+  ```sh
+  perl -e 'alarm shift; exec @ARGV' 180 <summer> --headless --path . -s res://tests/run_tests.gd
+  ```
+  `alarm` survives `exec`; exit code 142 means the limit hit.
+- **One engine per project at a time.** Two engines writing the same `.godot/` import cache corrupt it or
+  freeze each other's captures. Serialize with a lock file held by the engine process:
+  ```sh
+  perl -e 'use Fcntl qw(:flock); $^F=255; open(my $l,">>",shift) or die; flock($l,LOCK_EX); alarm shift; exec @ARGV' \
+    <project>/.engine.lock 180 <summer> ...
+  ```
+  Put this in one wrapper script and make every agent use it.
+- **Cap its memory.** A time limit does not stop a run from eating all memory first. One day of several agents
+  running builds, renders and a browser load of a large web export at once kernel-panicked the Mac
+  (compressor full, swap unable to grow). The wrapper should run the command as a child, sum the resident
+  memory of its whole process tree (browsers spawn GPU/renderer helpers), kill the tree past a cap (e.g.
+  3 GB), and also stop when system free memory falls low (`sysctl -n kern.memorystatus_level` < 15 on macOS),
+  because GPU memory on Apple Silicon is system memory but is not counted in RSS. Refuse to start when the
+  system is already short (< 35).
+- **Mute it.** `--audio-driver Dummy`. Someone is working next to you.
+- **Render only when you must, and offscreen.** `--headless` for logic (no pixels). For visual checks use
+  `--summer-offscreen` with a fixed `--resolution` and a capture script that saves PNGs and quits. Visible
+  windows only when a human asked to watch.
+
+## 2. Imports and parse errors
+
+- New `class_name` scripts are unknown to `-s` scripts until an import pass registers them:
+  `<summer> --headless --audio-driver Dummy --path . --import`.
+- The first import may rewrite `project.godot` (reorder keys, add a `[summer]` section; one trial saw a
+  hand-written `[rendering]` section dropped). Check `git diff project.godot` after it, and pass renderer
+  choices on the command line (`--rendering-method ...`) when a run depends on them.
+- One broken `class_name` script cascades into "Could not parse global class" and dozens of unrelated
+  "cannot infer type" errors. Get the real line with:
+  `<summer> --headless --path . --check-only -s res://path/to/file.gd`
+- Compile every script before booting the game: a tiny `SceneTree` script that `load()`s each `.gd` under
+  a folder and reports `can_instantiate()` failures, exit code = failures.
+
+## 3. Tests that can't lie
+
+- A runtime script error inside a test does not fail it by default; the test just stops and counts as
+  passed. Register a logger and fail the test when its error count rises:
+  ```gdscript
+  class ErrorCounter extends Logger:
+  	var script_errors := 0
+  	func _log_error(_f: String, file: String, _line: int, _c: String, _r: String, _n: bool, type: int, _bt: Array[ScriptBacktrace]) -> void:
+  		if type == Logger.ERROR_TYPE_SCRIPT or file.ends_with(".gd"):
+  			script_errors += 1
+  	func _log_message(_m: String, _e: bool) -> void:
+  		pass
+  # in the runner: OS.add_logger(counter); compare counter.script_errors before and after each test
+  ```
+- Exit 0 is not success. Always grep the log for `SCRIPT ERROR`, `Parse Error` and `ERROR:`, and print
+  one explicit success line (`TESTS passed=N failed=0`) you can check for.
+
+## 4. Typed GDScript traps agents hit repeatedly
+
+- `var x := dict["k"]` cannot infer a type (Dictionary values are Variant). Write `var x: int = dict["k"]`.
+- A loop variable that shadows an outer variable is a parse error that takes the whole class down.
+- Don't name a class after an engine class (`SummerSession`); the error only says it "hides a native class".
+
+## 5. Web exports on a dev machine
+
+- Check the `.pck` size before opening it in a browser; the browser holds all of it in memory. A project that
+  exports every imported asset of a large scene can pass 250 MB. Ship only what the game uses first.
+- Load it in a browser only under the same memory-capped wrapper, one at a time, never next to other engine runs.
+
+## 6. Captures you can trust
+
+- Read every PNG you produce. If several files are identical (`md5 -r *.png`), the run froze; rerun alone.
+- Keep evidence outside the project (logs, PNGs) so imports never pick it up. If it must live inside, put an
+  empty `.gdignore` file in that folder so the editor and imports skip it.
+
+## See also
+
+- `headless-scripting` (writing the SceneTree scripts these runs execute)
+- `multiplayer-testing` (Local Play bot runs)
+- `compatibility-renderer-traps` (dual-renderer captures)

package/library/skills/bounded-engine-runs/resource.yaml

@@ -0,0 +1,29 @@
+id: skill/bounded-engine-runs
+kind: skill
+version: 1.0.0
+summary: "Run Summer headless or offscreen safely from an agent: time limits, one engine per project, muted runs, import passes, tests that fail on crashes."
+use_when:
+  - running the engine from a shell or agent for tests, imports, captures or bots
+  - several agents or processes share one project
+  - a run hangs, a capture freezes, or errors cascade across unrelated scripts
+facets:
+  lifecycle:
+    - build
+  domains:
+    - agent-workflow
+    - headless
+    - verification
+  modalities:
+    - project
+    - scripts
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/headless-scripting
+    - skill/multiplayer-testing
+    - skill/compatibility-renderer-traps
+source: official
+license: MIT
+status: preview
+recommended: true