summer-engine 3.4.0 → 3.5.0

package/dist/core/library-read.js

@@ -13,8 +13,7 @@
  *   reference  the markdown body
  *   example / collection   README.md / collection.yaml when present
  *
- * The LAST line of every load is the feedback footer
- * (SELF_IMPROVING_LIBRARY.md §3.1 "trigger placement"):
+ * The LAST line of every load is the feedback footer:
  *   — entry_id: <id>@<content_hash first 12>. If this entry is wrong, stale,
  *   or you deviate from it, report via summer_library_feedback.
  * The agent copies that entry_id verbatim into summer_library_feedback, so
@@ -32,11 +31,18 @@
  * ships it; and `reference/<slug>` that is no entry falls back to the one
  * `references/<slug>.md` an entry ships. A body render ends with its links and
  * the id that loads each. A linked file's footer names its entry.
+ *
+ * Hosted skills: a skill whose resource.yaml names a `hosted_resource`
+ * (summer://skills/<slug>) keeps its current text on the hosted Summer Engine
+ * MCP, the text the Studio agent reads. The body is read from there with the
+ * store sign-in; without it the local SKILL.md renders with the reason and how
+ * to load the full text. The entry also resolves by that resource URI.
  */
 import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { join, posix, sep } from "node:path";
 import { z } from "zod";
 import { LIBRARY_KIND_DIRS, loadLibraryIndex, searchLibrary, } from "./library-search.js";
+import { withHostedMcp } from "./hosted-mcp.js";
 import { PACKAGE_ROOT } from "./package-root.js";
 import { getTemplateRegistry } from "./templates.js";
 export const READ_PARTS = ["skill", "resource", "all"];
@@ -61,6 +67,8 @@ export const LINKED_FILE_EXTENSIONS = new Set([
 ]);
 /** A linked file larger than this is refused rather than dumped. */
 export const LINKED_FILE_MAX_BYTES = 256 * 1024;
+/** How long a hosted skill read waits for the hosted Summer Engine MCP. */
+export const HOSTED_READ_TIMEOUT_MS = 8_000;
 export const readLibraryInputShape = {
     id: z
         .string()
@@ -82,13 +90,13 @@ export function entryIdWithHash(id, contentHash) {
     return hash ? `${id}@${hash}` : id;
 }
 // ── Resolution ─────────────────────────────────────────────────────────────
-/** Exact id, an id with an @hash suffix (as the footer prints it), or a bare
- *  slug that names exactly one entry. */
+/** Exact id, an id with an @hash suffix (as the footer prints it), a hosted
+ *  skill's resource URI, or a bare slug that names exactly one entry. */
 function resolveEntry(requested, entries) {
     const bare = requested.trim().replace(/@[a-f0-9]+$/i, "");
     if (!bare)
         return null;
-    const exact = entries.find((entry) => entry.id === bare);
+    const exact = entries.find((entry) => entry.id === bare || entry.hosted_resource === bare);
     if (exact)
         return exact;
     if (!bare.includes("/")) {
@@ -325,7 +333,7 @@ function relatedMap(entry) {
     }
     return out;
 }
-function header(entry, slug, related) {
+function header(entry, slug, related, hostedLoaded) {
     const lines = [];
     lines.push(`${entry.id} — ${entry.kind} v${entry.version ?? "?"} (${entry.status ?? "stable"})`);
     if (entry.summary)
@@ -339,7 +347,10 @@ function header(entry, slug, related) {
     const relatedIds = Object.values(related).flat();
     if (relatedIds.length > 0)
         lines.push(`related: ${relatedIds.join(", ")}`);
-    if (entry.kind === "skill") {
+    if (hostedLoaded) {
+        lines.push(`The body is the current text from the hosted Summer Engine MCP (also the \`${slug}\` MCP prompt and the resource ${entry.hosted_resource}). Follow it, do not paraphrase it.`);
+    }
+    else if (entry.kind === "skill") {
         lines.push(`Invoke: the \`${slug}\` skill in your host (Claude Code: /${slug}); installed under its bare slug by \`summer setup\`. The body follows — follow it, do not paraphrase it.`);
     }
     return lines.join("\n");
@@ -452,7 +463,21 @@ export async function readLibraryEntry(requestedId, part = "all", deps = {}) {
     let bodyTitle;
     let body;
     let links = [];
-    if (kind === "tool") {
+    let hostedText = null;
+    let hostedError;
+    if (kind === "skill" && entry.hosted_resource && part !== "resource") {
+        try {
+            hostedText = (await (deps.readHostedResource ?? readHostedSkill)(entry.hosted_resource)).replace(/\s+$/, "");
+        }
+        catch (error) {
+            hostedError = error instanceof Error ? error.message : String(error);
+        }
+    }
+    if (hostedText !== null) {
+        bodyTitle = `${entry.hosted_resource} (hosted Summer Engine MCP)`;
+        body = hostedText;
+    }
+    else if (kind === "tool") {
         bodyTitle = "how to call";
         body = toolBody(entry, slug);
     }
@@ -475,11 +500,14 @@ export async function readLibraryEntry(requestedId, part = "all", deps = {}) {
             body = `(no body file shipped for this ${kind}; the descriptor below is all there is)`;
         }
     }
-    const sections = [header(entry, slug, related)];
+    const sections = [header(entry, slug, related, hostedText !== null)];
     if (part === "skill" || part === "all") {
         sections.push(`--- ${bodyTitle} ---\n${body}`);
         if (links.length > 0)
             sections.push(linksSection(links));
+        if (hostedError !== undefined) {
+            sections.push(`--- hosted text not loaded ---\nThe full current text of this skill is the resource ${entry.hosted_resource} on the hosted Summer Engine MCP, and it could not be read: ${hostedError}\nThe body above is only the local summary: load the full text before you act (here after the fix, or as the \`${slug}\` MCP prompt or resource in a host connected to the hosted Summer Engine MCP).`);
+        }
     }
     if (part === "resource" || part === "all")
         sections.push(`--- ${relPath}/resource.yaml ---\n${resourceYaml}`);
@@ -487,6 +515,10 @@ export async function readLibraryEntry(requestedId, part = "all", deps = {}) {
     const result = { ...base, text: sections.join("\n\n") };
     if (bodyFile)
         result.body_file = bodyFile;
+    if (entry.hosted_resource)
+        result.hosted_resource = entry.hosted_resource;
+    if (hostedError !== undefined)
+        result.hosted_error = hostedError;
     if (links.length > 0 && part !== "resource")
         result.links = links;
     if (kind === "tool") {
@@ -500,6 +532,25 @@ export async function readLibraryEntry(requestedId, part = "all", deps = {}) {
     }
     return result;
 }
+/** A hosted skill's text, read from the hosted Summer Engine MCP with the store sign-in. */
+async function readHostedSkill(uri) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`the hosted Summer Engine MCP did not answer within ${HOSTED_READ_TIMEOUT_MS / 1000} s.`)), HOSTED_READ_TIMEOUT_MS);
+        timer.unref?.();
+    });
+    try {
+        const result = await Promise.race([withHostedMcp((client) => client.readResource({ uri })), timeout]);
+        const contents = Array.isArray(result.contents) ? result.contents : [];
+        const text = contents.map((content) => (typeof content.text === "string" ? content.text : "")).join("\n").trim();
+        if (!text)
+            throw new Error("the hosted Summer Engine MCP returned no text for it.");
+        return text;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 function safeTemplates() {
     try {
         return getTemplateRegistry();

package/dist/core/library-search.d.ts

@@ -49,6 +49,8 @@ export interface LibraryIndexEntry {
     cli_command?: string;
     authority?: Record<string, boolean>;
     recommended?: boolean;
+    /** The hosted Summer Engine MCP resource holding the skill's current text. */
+    hosted_resource?: string;
 }
 export type MatchedBy = "lexical" | "semantic";
 export interface LibrarySearchHit {

package/dist/core/templates.d.ts

@@ -53,8 +53,7 @@ export declare function getTemplateRegistry(): readonly TemplateEntry[];
  */
 export declare function resolveTemplate(query: string, entries: readonly TemplateEntry[]): TemplateResolution;
 /** Seconds a network git call (`fetch`) may take before it is killed.
- *  `summer create` once hung 42 minutes inside a fetch
- *  (docs/design/archive/TK-VS-FOLD-2026-09-07.md, gap 4). */
+ *  `summer create` once hung 42 minutes inside a fetch. */
 export declare const FETCH_TIMEOUT_ENV = "SUMMER_FETCH_TIMEOUT_S";
 export declare const DEFAULT_FETCH_TIMEOUT_S = 120;
 /** The bound in force: FETCH_TIMEOUT_ENV when it is a positive number of

package/dist/core/templates.js

@@ -109,8 +109,7 @@ export function resolveTemplate(query, entries) {
 }
 // ---------- git ----------
 /** Seconds a network git call (`fetch`) may take before it is killed.
- *  `summer create` once hung 42 minutes inside a fetch
- *  (docs/design/archive/TK-VS-FOLD-2026-09-07.md, gap 4). */
+ *  `summer create` once hung 42 minutes inside a fetch. */
 export const FETCH_TIMEOUT_ENV = "SUMMER_FETCH_TIMEOUT_S";
 export const DEFAULT_FETCH_TIMEOUT_S = 120;
 /** The bound in force: FETCH_TIMEOUT_ENV when it is a positive number of

package/dist/installer/agent-config.d.ts

@@ -45,6 +45,31 @@ export declare function resolveAgentSelection(agentArg: string | undefined, agen
 /** `--scope` with a user-facing error; absent means "user". */
 export declare function resolveConfigScope(scopeOpt: string | undefined): ConfigScope;
 export declare function configureAgentMcp(options: AgentConfigOptions): Promise<AgentConfigResult>;
+/** The Summer Games player MCP: friends, parties, messages and the player's
+ *  inbox, as the signed-in player. A remote server; the agent signs in to it
+ *  with OAuth in the browser, so setup writes no credential. */
+export declare const SUMMER_GAMES_MCP_SERVER_NAME = "summer-games";
+export declare const SUMMER_GAMES_MCP_URL = "https://mcp.summer.games/mcp";
+export interface RemoteMcpResult {
+    /** The entry's name: summer-games, or the name the person already gave it. */
+    serverName: string;
+    url: string;
+    path: string;
+    changed: boolean;
+    wrote: boolean;
+    /** Set when the server was already listed under another name (e.g. a
+     *  hand-added "summer"); setup then leaves the file alone. */
+    existingName?: string;
+    /** What the person does once to sign in (the agent opens summer.games). */
+    signIn: string;
+}
+/**
+ * Adds the Summer Games MCP next to summer-engine in the same config file.
+ * An entry that already points at the same URL, under any name, counts as
+ * added and is left as it is. Returns null for agents without a remote-server
+ * entry in agent-table.ts.
+ */
+export declare function configureSummerGamesMcp(options: Pick<AgentConfigOptions, "agent" | "scope" | "dryRun" | "cwd" | "env">): Promise<RemoteMcpResult | null>;
 export declare const DEFAULT_CHANNEL = "latest";
 /** npm dist-tags are lowercase words like `latest`, `next`, `beta`, `v3-preview`;
  *  anything that could be read as a version or a path is refused (a bare

package/dist/installer/agent-config.js

@@ -73,6 +73,116 @@ export async function configureAgentMcp(options) {
         nextSteps: [`Updated ${target.path}.`, spec.restart],
     };
 }
+/** The Summer Games player MCP: friends, parties, messages and the player's
+ *  inbox, as the signed-in player. A remote server; the agent signs in to it
+ *  with OAuth in the browser, so setup writes no credential. */
+export const SUMMER_GAMES_MCP_SERVER_NAME = "summer-games";
+export const SUMMER_GAMES_MCP_URL = "https://mcp.summer.games/mcp";
+/**
+ * Adds the Summer Games MCP next to summer-engine in the same config file.
+ * An entry that already points at the same URL, under any name, counts as
+ * added and is left as it is. Returns null for agents without a remote-server
+ * entry in agent-table.ts.
+ */
+export async function configureSummerGamesMcp(options) {
+    const spec = agentSpec(options.agent);
+    if (!spec.remoteMcp)
+        return null;
+    const env = options.env ?? process.env;
+    const target = resolveConfigTarget(spec, options.scope, resolve(options.cwd ?? process.cwd()), env);
+    const write = !options.dryRun;
+    const url = SUMMER_GAMES_MCP_URL;
+    let existing;
+    let changed = false;
+    if (spec.remoteMcp.format === "toml-url") {
+        const current = await readTextFileIfExists(target.path);
+        existing = findTomlServerByUrl(current, url);
+        if (!existing) {
+            const name = SUMMER_GAMES_MCP_SERVER_NAME;
+            const next = upsertTomlTable(current, `[mcp_servers.${name}]\nurl = ${tomlString(url)}\n`, name);
+            changed = current !== next;
+            if (write && changed)
+                await writeTextFile(target.path, next);
+        }
+    }
+    else {
+        const current = await readJsonConfig(target.path);
+        existing = findJsonServerByUrl(current, url);
+        if (!existing) {
+            const next = copyJsonObject(current);
+            next.mcpServers = mergeNamedObject(next.mcpServers, SUMMER_GAMES_MCP_SERVER_NAME, { type: "http", url }, "mcpServers");
+            const nextRendered = renderJsonFile(next);
+            changed = renderJsonFile(current) !== nextRendered;
+            if (write && changed)
+                await writeTextFile(target.path, nextRendered);
+        }
+    }
+    const serverName = existing ?? SUMMER_GAMES_MCP_SERVER_NAME;
+    return {
+        serverName,
+        url,
+        path: target.path,
+        changed,
+        wrote: write && changed,
+        ...(existing && existing !== SUMMER_GAMES_MCP_SERVER_NAME ? { existingName: existing } : {}),
+        signIn: spec.remoteMcp.signIn(serverName),
+    };
+}
+function sameMcpUrl(a, b) {
+    if (typeof a !== "string")
+        return false;
+    const normalize = (value) => {
+        try {
+            const parsed = new URL(value.trim());
+            return `${parsed.protocol}//${parsed.host}${parsed.pathname.replace(/\/+$/, "")}`.toLowerCase();
+        }
+        catch {
+            return value.trim().toLowerCase();
+        }
+    };
+    return normalize(a) === normalize(b);
+}
+/** The name of a server with this URL in mcpServers. Claude Code's
+ *  ~/.claude.json also keeps per-project servers (`claude mcp add` without
+ *  --scope user) under projects.<dir>.mcpServers; those count too. */
+function findJsonServerByUrl(config, url) {
+    const maps = [config.mcpServers];
+    if (isJsonObject(config.projects)) {
+        for (const project of Object.values(config.projects)) {
+            if (isJsonObject(project))
+                maps.push(project.mcpServers);
+        }
+    }
+    for (const map of maps) {
+        if (!isJsonObject(map))
+            continue;
+        for (const [name, entry] of Object.entries(map)) {
+            if (isJsonObject(entry) && sameMcpUrl(entry.url, url))
+                return name;
+        }
+    }
+    return undefined;
+}
+/** The name of a [mcp_servers.<name>] table whose url is this URL. */
+function findTomlServerByUrl(content, url) {
+    let table;
+    for (const line of content.split(/\r?\n/)) {
+        const header = /^\s*\[([^\[\]]+)\]\s*(?:#.*)?$/.exec(line);
+        if (header) {
+            const server = /^mcp_servers\.(?:"([^"]+)"|([A-Za-z0-9_-]+))$/.exec(header[1].trim());
+            table = server ? (server[1] ?? server[2]) : undefined;
+            continue;
+        }
+        if (/^\s*\[/.test(line)) {
+            table = undefined;
+            continue;
+        }
+        const value = /^\s*url\s*=\s*(?:"([^"]*)"|'([^']*)')/.exec(line);
+        if (table && value && sameMcpUrl(value[1] ?? value[2], url))
+            return table;
+    }
+    return undefined;
+}
 async function upsertConfig(format, path, server, write) {
     switch (format) {
         case "toml":
@@ -470,10 +580,11 @@ async function readTextFileIfExists(path) {
         throw new Error(`Could not read ${path}: ${formatError(error)}`);
     }
 }
-function upsertTomlTable(content, table) {
+function upsertTomlTable(content, table, name = SUMMER_MCP_SERVER_NAME) {
     const lines = content.split(/\r?\n/);
-    const serverHeader = /^\s*\[mcp_servers\.(?:"summer-engine"|summer-engine)(?:\.|\])/;
-    const start = lines.findIndex((line) => /^\s*\[mcp_servers\.(?:"summer-engine"|summer-engine)\]\s*(?:#.*)?$/.test(line));
+    const key = name.replace(/[.*+?^${}()|[\]\\-]/g, "\\$&");
+    const serverHeader = new RegExp(`^\\s*\\[mcp_servers\\.(?:"${key}"|${key})(?:\\.|\\])`);
+    const start = lines.findIndex((line) => new RegExp(`^\\s*\\[mcp_servers\\.(?:"${key}"|${key})\\]\\s*(?:#.*)?$`).test(line));
     if (start === -1) {
         const trimmed = content.endsWith("\n") || content === "" ? content : `${content}\n`;
         return `${trimmed}${trimmed === "" ? "" : "\n"}${table}`;

package/dist/installer/agent-table.d.ts

@@ -22,6 +22,7 @@ export type ConfigScope = "user" | "project";
  *  json-gemini   the Gemini extension manifest (legacy)
  */
 export type McpFormat = "json" | "json-stdio" | "json-vscode" | "json-copilot" | "json-opencode" | "json-servers" | "json-zed" | "json-amp" | "json-crush" | "json-transport" | "toml" | "toml-array" | "yaml-goose" | "yaml-hermes" | "json-gemini";
+export type RemoteMcpFormat = "json-http" | "toml-url";
 export type SkillLocationKind = "skill-dir" | "cursor-rule-dir" | "windsurf-rule-file" | "cline-rule-dir" | "opencode-skill-dir";
 export interface PathContext {
     home: string;
@@ -70,6 +71,17 @@ export interface AgentSpec {
     /** Env var that overrides the MCP config path (tests, unusual installs). */
     envOverride: string;
     format: McpFormat;
+    /**
+     * How this agent lists a remote MCP server that signs in with OAuth on its
+     * own (the Summer Games player MCP). Absent: setup links the engine only.
+     *  json-http { mcpServers: { <name>: { type: "http", url } } }   (Claude Code)
+     *  toml-url  [mcp_servers.<name>] url                            (Codex)
+     * signIn tells the person how to sign in once, for the entry's name.
+     */
+    remoteMcp?: {
+        format: RemoteMcpFormat;
+        signIn: (name: string) => string;
+    };
     mcp: {
         /** null: user-level servers are managed in the app's UI; a user request writes the project file with a warning. */
         user: ((ctx: PathContext) => string) | null;

package/dist/installer/agent-table.js

@@ -108,6 +108,7 @@ const SPECS = [
         status: "active",
         envOverride: "SUMMER_CLAUDE_CONFIG_FILE",
         format: "json-stdio",
+        remoteMcp: { format: "json-http", signIn: (name) => `In Claude Code, run /mcp, choose ${name} and sign in.` },
         mcp: { user: home(".claude.json"), project: project(".mcp.json") },
         restart: "Restart Claude Code or run /mcp in a new session.",
         skills: skillDirs(home(".claude", "skills"), project(".claude", "skills")),
@@ -134,6 +135,10 @@ const SPECS = [
         status: "active",
         envOverride: "SUMMER_CODEX_CONFIG_FILE",
         format: "toml",
+        remoteMcp: {
+            format: "toml-url",
+            signIn: (name) => `In Codex, run /mcp login ${name} (or \`codex mcp login ${name}\` in a terminal) and sign in.`,
+        },
         mcp: {
             user: home(".codex", "config.toml"),
             project: project(".codex", "config.toml"),
@@ -149,6 +154,10 @@ const SPECS = [
         status: "active",
         envOverride: "SUMMER_CURSOR_MCP_CONFIG_FILE",
         format: "json-stdio",
+        // No remoteMcp (Summer Games) yet: Cursor's fallback OAuth flow registers
+        // cursor://anysphere.cursor-mcp/oauth/callback, which api.summer.games
+        // refuses (summer-platform#1681 allows it). Add { format: "json-url" }
+        // ({ mcpServers: { <name>: { url } } }) once that is live.
         mcp: { user: home(".cursor", "mcp.json"), project: project(".cursor", "mcp.json") },
         restart: "Restart Cursor and enable the summer-engine MCP server if prompted.",
         skills: sharedSkills({

package/dist/mcp/server.d.ts

@@ -6,8 +6,8 @@ export declare const getCachedBootDriftNotice: typeof getCachedNotice;
 /**
  * Server `instructions` in the MCP initialize response (SDK ServerOptions,
  * @modelcontextprotocol/sdk >= 1.x). Hosts hand this to the model once per
- * session, before any tool call — the place for the five habits the E2E run
- * (docs/design/archive/E2E-2026-09-03.md, F-17) showed an agent needs on the first
+ * session, before any tool call — the place for the five habits an end-to-end run
+ * 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. The last

package/dist/mcp/server.js

@@ -34,8 +34,8 @@ export const getCachedBootDriftNotice = getCachedNotice;
 /**
  * Server `instructions` in the MCP initialize response (SDK ServerOptions,
  * @modelcontextprotocol/sdk >= 1.x). Hosts hand this to the model once per
- * session, before any tool call — the place for the five habits the E2E run
- * (docs/design/archive/E2E-2026-09-03.md, F-17) showed an agent needs on the first
+ * session, before any tool call — the place for the five habits an end-to-end run
+ * 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. The last

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

@@ -40,7 +40,7 @@ async function creatorResult(operation) {
     }
 }
 export function registerCreatorTools(server) {
-    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.", {
+    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). A target the installed engine cannot build (android needs 0.7.1) is left out: the other targets export, and skippedTargets plus a warning name it. A game with a server declares its platforms in summer.build.json; when they differ from the exported targets a warning says so (summer_publish_build would be refused), and alignDeclaration:true aligns them. 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
@@ -53,7 +53,11 @@ export function registerCreatorTools(server) {
             .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 } : {}) })));
+        alignDeclaration: z
+            .boolean()
+            .optional()
+            .describe("A game with a server: set summer.build.json targetPlatforms to targets before exporting. The store refuses an upload whose declaration differs from the exported platforms (declaration_mismatch) and that spends the version."),
+    }, async ({ project, out, targets, format, debug, timeoutSeconds, alignDeclaration }) => creatorResult(() => exportGame({ project, out, targets, format, debug, alignDeclaration, ...(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
@@ -66,7 +70,7 @@ export function registerCreatorTools(server) {
             .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.", {
+    server.tool("summer_capture_gameplay", "Capture real gameplay frames without a running editor: starts the game in Summer Engine's offscreen verify instance (--summer-offscreen: a real renderer, a window parked offscreen with no focus, never on screen), lets it run waitSeconds, runs steps, and saves PNG frames of what the game draws, HUD included. Use for store screenshots (1920x1080 landscape or 1080x1920 portrait). The main scene is often a title menu: pass the game's own flags in args (after \"--\", e.g. [\"--autostart\"]), a gameplay scene, or steps that play like a player: [{press:\"Play\"}, {wait:3000}, {key:\"Space\"}, {action:\"jump\"}, {click:[960,540]}, {drag:{from:[400,800],to:[1400,800]}}, {shot:true}]. With a shot step, only shot steps save frames; without one, frames are saved after the steps. A step that cannot run (no such button, key or action) becomes a warning. 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)."),
@@ -74,6 +78,31 @@ export function registerCreatorTools(server) {
         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)."),
+        args: z
+            .array(z.string())
+            .max(32)
+            .optional()
+            .describe('The game\'s own command-line flags, passed after "--" (OS.get_cmdline_user_args()), e.g. ["--autostart", "--solo"] to skip the title screen.'),
+        steps: z
+            .array(z
+            .object({
+            press: z.string().optional().describe("Press the visible button with this text (or node name); waits up to timeoutSeconds (default 10) for it."),
+            timeoutSeconds: z.number().min(0).max(60).optional(),
+            key: z.string().optional().describe("Press a key by Godot name: Space, Enter, Escape, A, Up."),
+            action: z.string().optional().describe("Press an input action from the project's InputMap, e.g. jump."),
+            holdMs: z.number().min(0).max(10000).optional().describe("How long key or action is held (default 100)."),
+            click: z.tuple([z.number(), z.number()]).optional().describe("Left-click at [x, y] in frame pixels."),
+            drag: z
+                .object({ from: z.tuple([z.number(), z.number()]), to: z.tuple([z.number(), z.number()]), ms: z.number().min(0).max(10000).optional() })
+                .optional()
+                .describe("Drag with the left button from [x, y] to [x, y] over ms (default 300)."),
+            wait: z.number().min(0).max(60000).optional().describe("Wait this many milliseconds."),
+            shot: z.boolean().optional().describe("true: save a frame now."),
+        })
+            .strict())
+            .max(50)
+            .optional()
+            .describe("What to do after waitSeconds, in order; exactly one of press, key, action, click, drag, wait, shot per step."),
     }, 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."),
@@ -100,7 +129,7 @@ export function registerCreatorTools(server) {
         ...args,
         face: "mcp",
     })));
-    server.tool("summer_creator_releases", "List real creator-owned releases from the versioned Summer Platform creator API. The server independently verifies the exact publish scope and project ownership.", {
+    server.tool("summer_creator_releases", "Deprecated: lists releases on the legacy Summercraft creator API (separate sc_ token), not summer.games. For what players get on summer.games, and which upload can be released, use summer_store_releases.", {
         projectId: z.string().optional().describe("Creator project ID. Defaults to ~/.summer/config.json."),
         limit: z.number().int().min(1).max(100).default(20),
         cursor: z.string().optional().describe("Opaque nextCursor from the previous page."),

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

@@ -178,7 +178,7 @@ Use this when summer_get_diagnostics shows a non-zero \`debugger.warnings\` coun
     }, async ({ max_warnings, include_stack, raw }) => withEngine(async (client) => {
         // Reuses the existing GetDebuggerErrors op with type: "warning" filter.
         // Engine-side change: ScriptEditorDebugger::get_errors_data() supports
-        // include_warnings; debug_ops::get_debugger_errors honours `type` to
+        // include_warnings; the engine's GetDebuggerErrors honours `type` to
         // return warnings only. Diagnostics also exposes `warnings_data`.
         const op = {
             op: "GetDebuggerErrors",

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

@@ -1,10 +1,7 @@
 import { z } from "zod";
 import { BOARD_ENDPOINT, boardArgsSchema, boardContent, boardQuery } from "../../core/capabilities/board.js";
-import { imageGenerationArgsSchema } from "../../core/capabilities/image-generation.js";
+import { IMAGE_GENERATION_TIMEOUT_MS, imageGenerationArgsSchema, saveGeneratedImage } from "../../core/capabilities/image-generation.js";
 import { buildMotionRequestBody, motionErrorHint, motionGenerationArgsSchema, motionJobFailureHint, } from "../../core/capabilities/motion-generation.js";
-import { writeFile, mkdir } from "fs/promises";
-import { tmpdir } from "os";
-import { join } from "path";
 import { getAuthToken } from "../../core/auth.js";
 import { resolveGatewayUrl } from "../../core/config.js";
 import { readJsonResponse } from "../../core/util/http.js";
@@ -151,26 +148,6 @@ async function mcpGet(endpoint, searchParams, timeoutMs = 30_000) {
     }
     return { data, status: res.status };
 }
-/**
- * Download an image URL to a temp file so the AI can Read it and show the user.
- */
-async function downloadToTemp(url, prefix, ext = "png") {
-    try {
-        const dir = join(tmpdir(), "summer-gen");
-        await mkdir(dir, { recursive: true });
-        const filename = `${prefix}-${Date.now()}.${ext}`;
-        const filepath = join(dir, filename);
-        const res = await fetch(url, { signal: AbortSignal.timeout(30_000) });
-        if (!res.ok)
-            return null;
-        const buffer = Buffer.from(await res.arrayBuffer());
-        await writeFile(filepath, buffer);
-        return filepath;
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * Poll a job until completed, failed, or timeout.
  * Returns the final job status object.
@@ -281,7 +258,8 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, boardA
     server.tool("summer_generate_image", `Generate an image using AI models via Summer Engine Studio.
 
 Known models:
-  - "nano-banana-2" (default) — High quality, supports txt2img and img2img
+  - "nano-banana-2" — High quality, supports txt2img and img2img (used when no
+    model and no size is asked)
   - "gemini-flash" — Google Gemini 2.5 Flash, fast
   - "flux-2" — FLUX.2, good for specific styles
 
@@ -300,17 +278,20 @@ guarantee transparency; background removal runs server-side after generation.
 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.
+that size when model is omitted, or refuses a named model that cannot, before
+anything is spent. Larger models can take over a minute; the call waits up to
+3 minutes.
 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).
+Returns the asset with fileUrl (hosted) and localPath: the file on disk, in
+'out' (a folder, or a .png/.jpg/.webp path) or else <TMPDIR>/summer-gen/.
 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, aspectRatio, width, height, options }) => {
+Requires authentication: run 'npx -y summer-engine@latest login' first.`, imageGenerationArgsSchema.shape, async ({ prompt, model, style, referenceImageUrl, removeBackground, aspectRatio, width, height, options, out }) => {
         const result = await mcpGenerate("/api/mcp/generate/image", {
             prompt,
             model,
@@ -321,7 +302,7 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, imageG
             width,
             height,
             options,
-        });
+        }, IMAGE_GENERATION_TIMEOUT_MS);
         if (result.error) {
             return errorResult(result.error, result.data);
         }
@@ -329,7 +310,7 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, imageG
         const imageUrl = result.data?.asset?.fileUrl || result.data?.asset?.thumbnailUrl;
         let localPath = null;
         if (imageUrl) {
-            localPath = await downloadToTemp(imageUrl, "img");
+            localPath = await saveGeneratedImage(imageUrl, out);
         }
         return successResult({
             ...result.data,
@@ -467,7 +448,7 @@ Optional rig pass (image-to-3d only):
   Set options.rig = true to add an auto-rig pass via Meshy v6. The result
   job (poll via summer_check_job) will include rigAssetId — the asset ID
   of the rigged glb. Use that rigAssetId with summer_generate_motion to
-  add animation clips. Adds ~$0.30 and ~60s to the job.
+  add animation clips. Adds ~60s to the job.
 
 Example:
   summer_generate_3d({
@@ -593,11 +574,11 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
     server.tool("summer_generate_video", `Generate a video using AI models via Summer Engine Studio.
 
 Known models (text-to-video):
-  - "ltx" (default) — LTX Video, fast (~$0.10)
-  - "kling" — Kling 2 Master, high quality (~$0.50)
-  - "kling-turbo" — Kling 2.5 Turbo Pro (~$0.30)
-  - "minimax" — MiniMax (~$0.25)
-  - "veo3" — Google Veo 3, premium (~$1.00)
+  - "ltx" (default) — LTX Video, fast
+  - "kling" — Kling 2 Master, high quality
+  - "kling-turbo" — Kling 2.5 Turbo Pro
+  - "minimax" — MiniMax
+  - "veo3" — Google Veo 3, premium
 
 Known models (image-to-video, when imageUrl provided):
   - "ltx" (default), "kling", "minimax"
@@ -698,7 +679,7 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
 Backends (pick one):
   - "meshy-library" (default) — a curated mocap clip by motionName on a
     Summer-rigged humanoid (rigAssetId from summer_generate_3d with
-    options.rig=true). Fast (~30s), cheap (~$0.10), real mocap quality.
+    options.rig=true). Fast (~30s), real mocap quality.
     Names that always work: idle, walk, run, jump, attack; anything else must
     be an exact library name.
   - "text-to-motion" — custom 2-second clips (60 frames) from text prompts on