summer-engine 3.3.0 → 3.4.1

package/commands/gameskill.md

@@ -5,10 +5,10 @@ allowed-tools: Read Write Edit Glob Grep Bash Skill
 
 # /gameskill — capture session learnings
 
-Activate the library skill `summer:gameskill` and follow it exactly; this command is only the entry point. If the `Skill` tool cannot find it, read `library/skills/gameskill/SKILL.md` from the Summer package (the plugin root, or `node_modules/summer-engine/`) and follow that file.
+Activate the library skill `gameskill` and follow it exactly; this command is only the entry point. If the `Skill` tool cannot find it, read `library/skills/gameskill/SKILL.md` from the Summer package (the plugin root, or `node_modules/summer-engine/`) and follow that file.
 
 Ground rules the skill enforces, so you do not drift while it loads:
 
-- Default home is the game project's own skills directory for the agent you are in (`.claude/skills/<slug>/`, `.agents/skills/<slug>/`, `.cursor/rules/`). Only inside a checkout of the summer-engine agent repo do you add to `library/skills/<slug>/` (`resource.yaml` + `SKILL.md`, flat slugs); everything in `registry/generated/` and every plugin manifest is generated from it, so run `npm run generate:registry` after editing and never hand-edit those files. From anywhere else, send general lessons through `summer_library_feedback`.
+- Default home is the game project's own skills directory for the agent you are in (`.claude/skills/<slug>/`, `.agents/skills/<slug>/`). Only inside a checkout of the Summer repo (`summerengine/summer`) do you add to `library/skills/<slug>/` (`resource.yaml` + `SKILL.md`, flat slugs); everything in `registry/generated/` and every plugin manifest is generated from it, so run `npm run generate:registry` after editing and never hand-edit those files. From anywhere else, send general lessons through `summer_library_feedback`.
 - Capture only learnings that are non-obvious AND general. Lead with the why. Real working code from the active project beats invented examples. VFX is shader + GDScript + node setup, never an image-generation pipeline.
 - It is fine to report "session was tactical, no durable learnings." Do not manufacture skills.

package/commands/summer.md

@@ -20,43 +20,43 @@ You know the engine cold. Scenes are `.tscn`, resources are `.tres`, scripts are
 
 You are opinionated about scope. When the user describes three features in one sentence, ask which one is the playable demo and defer the other two. "Wouldn't it be cool if" gets "yes, after the core loop runs." Get the core loop into the player's hands by the end of the session, then iterate. Polish happens after the game is playable, not before.
 
-You speak game-dev shorthand (PCs, NPCs, juice, hit-stop, root motion, blendspace, navmesh, kinematic vs rigid) and assume the user knows it. You are confident about cost: every generation has a number, and you say the number before spending the user's money.
+You speak game-dev shorthand (PCs, NPCs, juice, hit-stop, root motion, blendspace, navmesh, kinematic vs rigid) and assume the user knows it. Asset generation spends the user's credits, so you say what you will generate before you spend them.
 
 ## What to do
 
 1. Detect the request shape (new game / new feature / new asset / bug / discussion / build).
-2. Confirm Summer Engine context. Call `summer_get_project_context` if available. If it returns nothing, the user is not in a Summer project yet — route to `summer:brainstorm-game`.
+2. Confirm Summer Engine context. Call `summer_get_project_context` if available. If it returns nothing, the user is not in a Summer project yet — route to the `brainstorm-game` skill.
 3. Invoke the right Summer skill with the `Skill` tool. Do not paraphrase the skill; let the specialist run and follow it exactly.
-4. State the estimated cost (dollars and seconds) before any generation call.
+4. Before any generation call, say what you will generate and roughly how long it takes, and wait for an OK.
 
 ## Routing
 
-Skills are flat slugs under the `summer:` namespace (`summer:<slug>`); there are no category paths.
+Skills are invoked by their bare slug, such as `brainstorm-game`. There is no `summer:` prefix and there are no category paths.
 
 | Request shape | First skill |
 |---|---|
-| brainstorm a [genre] game / let's make a [genre] / I'm stuck / what should I work on | `summer:brainstorm-game` |
-| start a new project | `summer:new-project` |
-| make me a game from scratch | `summer:make-game` |
-| add a [character / enemy / NPC / prop / vehicle] | `summer:asset-strategy` |
-| add a sound for [event] | `summer:sound-effect` |
-| add ambient music | `summer:music-track` |
-| make me fire / smoke / lightning / muzzle flash / magic glow / hit spark / dissolve / water ripple | `summer:vfx-fire`, `summer:vfx-smoke`, `summer:vfx-lightning`, `summer:vfx-muzzle-flash`, `summer:vfx-magic-glow`, `summer:vfx-hit-spark`, `summer:vfx-dissolve`, `summer:vfx-water-ripple` |
-| build the FPS controller | `summer:fps-controller` |
-| debug / the game crashes when [X] / broken behavior / cloud or Codex failure / send this to support | `summer:debug` (support-report mode first: call `summer_create_debug_report` when available and tell the user where the Markdown report was written; keep fixing only if they also asked for a fix) |
-| add an animation to [character] | `summer:generate-motion` |
-| wire up a state machine for [character] | `summer:animation-tree` |
-| the game feels mushy / add juice | `summer:game-feel` |
-| ship a trailer | `summer:trailer-shot` |
-| cutscene for [X] | `summer:cinematic-cutscene` |
-| let me play it | `summer:play` |
-
-If nothing fits, activate `summer:using-summer` and call `summer_search_library` (then `summer_read_library`) to find the closest skill. Never invent a skill name; verify it exists first.
+| brainstorm a [genre] game / let's make a [genre] / I'm stuck / what should I work on | `brainstorm-game` |
+| start a new project | `new-project` |
+| make me a game from scratch | `make-game` |
+| add a [character / enemy / NPC / prop / vehicle] | `asset-strategy` |
+| add a sound for [event] | `sound-effect` |
+| add ambient music | `music-track` |
+| make me fire / smoke / lightning / muzzle flash / magic glow / hit spark / dissolve / water ripple | `vfx-fire`, `vfx-smoke`, `vfx-lightning`, `vfx-muzzle-flash`, `vfx-magic-glow`, `vfx-hit-spark`, `vfx-dissolve`, `vfx-water-ripple` |
+| build the FPS controller | `fps-controller` |
+| debug / the game crashes when [X] / broken behavior / cloud or Codex failure / send this to support | `debug` (support-report mode first: call `summer_create_debug_report` when available and tell the user where the Markdown report was written; keep fixing only if they also asked for a fix) |
+| add an animation to [character] | `generate-motion` |
+| wire up a state machine for [character] | `animation-tree` |
+| the game feels mushy / add juice | `game-feel` |
+| ship a trailer | `trailer-shot` |
+| cutscene for [X] | `cinematic-cutscene` |
+| let me play it | `play` |
+
+If nothing fits, activate `using-summer` and call `summer_search_library` (then `summer_read_library`) to find the closest skill. Never invent a skill name; verify it exists first.
 
 ## Tone rules
 
 - No corporate hedging. "I'd recommend" becomes "do this." "It might be worth considering" becomes "next step is."
-- Cost-aware: "Generating with kling. 5s, ~$0.50. OK?" — never "I'll generate a video now."
+- Ask before spending: "Generating a 5s clip with kling, about 3 minutes. OK?" Never "I'll generate a video now."
 - Scope-aware: the cut list goes in `.summer/GameSoul.md`, not in V1.
 - Confirm before destructive moves: replacing nodes, deleting assets, regenerating expensive outputs.
 - Do not redirect users to external docs; solve it in-conversation.
@@ -70,12 +70,12 @@ If nothing fits, activate `summer:using-summer` and call `summer_search_library`
 
 > User: /summer make a knight
 >
-> Summer: Knight character. asset-strategy first to lock the look (concept image), then character-model for the rigged mesh. ~$0.10 for the concept, ~$0.40 for the 3D pass. OK?
+> Summer: Knight character. asset-strategy first to lock the look (concept image), then character-model for the rigged mesh. Two generations. OK?
 >
-> [invokes `summer:asset-strategy`]
+> [invokes `asset-strategy`]
 
 > User: /summer the game crashes when I pick up the sword
 >
 > Summer: Going to debug. Writing the support report first, then the fix.
 >
-> [invokes `summer:debug`]
+> [invokes `debug`]

package/dist/cli/commands/install.d.ts

@@ -44,6 +44,16 @@ export declare function replaceMacApp(mountPoint: string, destApp: string, exec:
  *  setup.exe CLI). The old NSIS flags (/S, /D=) are rejected by the Velopack
  *  installer with "unexpected argument '/S' found" — this is the wizard bug. */
 export declare function windowsInstallerArgs(customPath?: string): string;
+/** Printed after an install: the first start of a new engine is slow and silent. */
+export declare const FIRST_START_NOTE: string;
+/** Where the Velopack installer put Summer.exe: <dir>/current/Summer.exe for --path, else the default locations. */
+export declare function windowsInstalledBinary(customPath?: string, exists?: (path: string) => boolean): string | null;
+/**
+ * Download progress: rewrites one line on a terminal; elsewhere (an agent,
+ * a log file) one line per 10%, so a 1 GB download is about ten lines
+ * instead of hundreds of kilobytes.
+ */
+export declare function createProgressReporter(isTTY: boolean, write: (text: string) => void): (downloaded: number, total: number) => void;
 export declare const installCommand: Command;
 export declare function downloadFile(url: string, dest: string): Promise<{
     sha256: string;

package/dist/cli/commands/install.js

@@ -6,8 +6,8 @@ import { chmodSync, createWriteStream, existsSync, mkdirSync, readdirSync, renam
 import { pipeline } from "stream/promises";
 import { Readable } from "stream";
 import { tmpdir, platform } from "os";
-import { join, resolve } from "path";
-import { ENGINE_BINARY_ENV, LINUX_ENGINE_BINARY_NAME, findExtractedEngineBinary, linuxArchiveKind, linuxEngineInstallDir, pickLinuxReleaseAsset, resolveLinuxInstallSource, } from "../../core/engine-install.js";
+import { dirname, join, resolve } from "path";
+import { ENGINE_BINARY_ENV, LINUX_ENGINE_BINARY_NAME, macInstallDestination, recordEngineInstall, windowsEnginePaths, findExtractedEngineBinary, linuxArchiveKind, linuxEngineInstallDir, pickLinuxReleaseAsset, resolveLinuxInstallSource, } from "../../core/engine-install.js";
 const RELEASES_URL = "https://www.summerengine.com/api/desktop/releases";
 /** Guard a download URL from the releases endpoint. A missing/empty URL (an
  *  outdated or misconfigured endpoint) otherwise becomes a cryptic
@@ -116,9 +116,42 @@ async function confirm(question) {
 export function windowsInstallerArgs(customPath) {
     return customPath ? `--silent --installto "${customPath}"` : "--silent";
 }
+/** Printed after an install: the first start of a new engine is slow and silent. */
+export const FIRST_START_NOTE = "The first start of a new engine version can take several minutes with no output " +
+    "(the system checks the new app and the engine builds its caches). Later starts are fast.";
+/** Where the Velopack installer put Summer.exe: <dir>/current/Summer.exe for --path, else the default locations. */
+export function windowsInstalledBinary(customPath, exists = existsSync) {
+    const candidates = customPath
+        ? [join(customPath, "current", "Summer.exe"), join(customPath, "Summer.exe")]
+        : windowsEnginePaths();
+    return candidates.find((path) => exists(path)) ?? null;
+}
+/**
+ * Download progress: rewrites one line on a terminal; elsewhere (an agent,
+ * a log file) one line per 10%, so a 1 GB download is about ten lines
+ * instead of hundreds of kilobytes.
+ */
+export function createProgressReporter(isTTY, write) {
+    let lastStep = -1;
+    return (downloaded, total) => {
+        if (total <= 0)
+            return;
+        const pct = Math.min(100, Math.floor((downloaded / total) * 100));
+        const mb = (downloaded / 1024 / 1024).toFixed(1);
+        if (isTTY) {
+            write(`\r  ${pct}% (${mb}MB)`);
+            return;
+        }
+        const step = Math.floor(pct / 10);
+        if (step > lastStep) {
+            lastStep = step;
+            write(`  ${pct}% (${mb}MB)\n`);
+        }
+    };
+}
 export const installCommand = new Command("install")
     .description("Download and install Summer Engine")
-    .option("--path <dir>", "Custom install directory")
+    .option("--path <dir>", "Custom install directory (macOS: the engine goes in <dir>/Summer.app). summer remembers it, so later commands find this engine")
     .option("--yes", "Replace an already-installed engine without prompting")
     .action(async (opts) => {
     const os = platform();
@@ -160,7 +193,8 @@ async function installMac(releases, customPath, yes = false) {
     }
     const dmgUrl = requireDownloadUrl(info.dmg_url, "macOS DMG");
     console.log(`Latest version: ${info.version}`);
-    const destApp = customPath || "/Applications/Summer.app";
+    const destApp = macInstallDestination(customPath);
+    const destBinary = join(destApp, "Contents", "MacOS", "Summer");
     const exists = existsSync(destApp);
     const installedVersion = exists ? readMacBundleVersion(destApp) : null;
     const plan = planMacInstall({
@@ -171,6 +205,7 @@ async function installMac(releases, customPath, yes = false) {
         isTTY: Boolean(process.stdin.isTTY),
     });
     if (plan.action === "up-to-date") {
+        await recordEngineInstall(destBinary, plan.version);
         console.log(`Summer Engine v${plan.version} is already installed at ${destApp} (up to date).`);
         return;
     }
@@ -218,6 +253,7 @@ async function installMac(releases, customPath, yes = false) {
     }
     try {
         console.log("Installing to " + destApp + "...");
+        mkdirSync(dirname(destApp), { recursive: true });
         replaceMacApp(mountPoint, destApp, (command) => execSync(command, { stdio: "ignore" }));
         console.log("Done!");
     }
@@ -235,7 +271,9 @@ async function installMac(releases, customPath, yes = false) {
         catch { }
         releaseSignals();
     }
+    await recordEngineInstall(destBinary, info.version);
     console.log(`\nSummer Engine v${info.version} installed to ${destApp}`);
+    console.log(FIRST_START_NOTE);
     console.log("\nNext steps:");
     console.log("  summer login    # Sign in to your account");
     console.log("  summer run      # Launch the engine");
@@ -276,7 +314,11 @@ async function installWindows(releases, customPath) {
         execSync(`del "${exePath}"`, { stdio: "ignore" });
     }
     catch { }
-    console.log(`\nSummer Engine v${info.version} installed!`);
+    const installed = windowsInstalledBinary(customPath);
+    if (installed)
+        await recordEngineInstall(installed, info.version);
+    console.log(`\nSummer Engine v${info.version} installed${installed ? ` to ${installed}` : "!"}`);
+    console.log(FIRST_START_NOTE);
     console.log("\nNext steps:");
     console.log("  summer login    # Sign in to your account");
     console.log("  summer run      # Launch the engine");
@@ -338,6 +380,7 @@ async function installLinux(customPath) {
     const source = resolveLinuxInstallSource();
     if (source.kind === "binary") {
         registerExistingLinuxBinary(source.path, destDir, destBinary);
+        await recordEngineInstall(destBinary, null);
         printLinuxNextSteps(destBinary);
         return;
     }
@@ -409,7 +452,9 @@ async function installLinux(customPath) {
     finally {
         rmSync(downloadPath, { force: true });
     }
+    await recordEngineInstall(destBinary, versionLabel === "custom" ? null : versionLabel);
     console.log(`\nSummer Engine (${versionLabel}) installed to ${destBinary}`);
+    console.log(FIRST_START_NOTE);
     printLinuxNextSteps(destBinary);
 }
 function printLinuxNextSteps(binary) {
@@ -433,15 +478,15 @@ export async function downloadFile(url, dest) {
     const hash = createHash("sha256");
     let downloaded = 0;
     const total = parseInt(res.headers.get("content-length") || "0", 10);
+    const isTTY = Boolean(process.stdout.isTTY);
+    const report = createProgressReporter(isTTY, (text) => process.stdout.write(text));
     readable.on("data", (chunk) => {
         hash.update(chunk);
         downloaded += chunk.length;
-        if (total > 0) {
-            const pct = Math.round((downloaded / total) * 100);
-            process.stdout.write(`\r  ${pct}% (${(downloaded / 1024 / 1024).toFixed(1)}MB)`);
-        }
+        report(downloaded, total);
     });
     await pipeline(readable, fileStream);
-    process.stdout.write("\n");
+    if (isTTY)
+        process.stdout.write("\n");
     return { sha256: hash.digest("hex") };
 }

package/dist/cli/commands/open.d.ts

@@ -7,7 +7,7 @@ import { type OpenDeps, type OpenResult, type OpenSurface } from "../../core/cap
  *    Summer Engine (launching it when it is not running). Any argument that is
  *    an existing directory or looks like a filesystem path takes this branch,
  *    so nothing that worked before changes.
- * 2. `summer open <target>` — navigation (docs/design/NAVIGATION-DESIGN.md):
+ * 2. `summer open <target>` — navigation:
  *    a product-map id ("billing"), an intent phrase ("change my plan"), a
  *    res:// path, or a summerengine.com path. Same behavior as the
  *    summer_open MCP tool and `summer tool open` (core/capabilities/navigation).

package/dist/cli/commands/run.d.ts

@@ -13,7 +13,7 @@ export type RunBinaryResolution = {
  * (findEngineBinary, which also honours the older SUMMER_ENGINE_BINARY).
  * An explicit override is never silently swapped for the installed engine:
  * a missing path or a bare `.app` bundle is an error, because the caller
- * asked for THAT build (docs/design/archive/TK-VS-FOLD-2026-09-07.md, gap 5).
+ * asked for THAT build.
  */
 export declare function resolveRunBinary(binFlag: string | undefined, env?: NodeJS.ProcessEnv): RunBinaryResolution;
 export declare const runCommand: Command;

package/dist/cli/commands/run.js

@@ -79,7 +79,7 @@ async function withLaunchLock(fn) {
  * (findEngineBinary, which also honours the older SUMMER_ENGINE_BINARY).
  * An explicit override is never silently swapped for the installed engine:
  * a missing path or a bare `.app` bundle is an error, because the caller
- * asked for THAT build (docs/design/archive/TK-VS-FOLD-2026-09-07.md, gap 5).
+ * asked for THAT build.
  */
 export function resolveRunBinary(binFlag, env = process.env) {
     const fromEnv = engineBinaryOverride(env);

package/dist/cli/commands/skills.js

@@ -340,7 +340,7 @@ skillsCommand
         console.log(previewIncludedLine(previewIncluded));
     if (previewSkipped > 0)
         console.log(previewSkippedLine(previewSkipped));
-    // Claude Code: also install slash commands (`tools/summer-cli/commands/*.md`)
+    // Claude Code: also install slash commands (`commands/*.md`)
     // into `~/.claude/commands/`. Other agents don't have an equivalent today.
     if (agent === "claude-code") {
         const commandResults = installClaudeCommands(scope, Boolean(opts.force));
@@ -352,7 +352,7 @@ skillsCommand
     printInstallSummary(skills.length, agent, scope, location);
 });
 /**
- * Copy every `.md` file in `tools/summer-cli/commands/` to the user's
+ * Copy every `.md` file in the package's `commands/` to the user's
  * `~/.claude/commands/` directory so the slash commands (e.g. `/gameskill`)
  * are available on every machine that runs `summer skills install`.
  *

package/dist/cli/commands/tool.d.ts

@@ -1,5 +1,12 @@
 import { Command } from "commander";
 import { type ToolDispatchEntry } from "../../core/capabilities/tool-dispatch.js";
+import { callHostedToolForCli, listHostedToolsForCli, type HostedToolsListing } from "../../core/hosted-mcp.js";
+/** The hosted store and publishing tools (Summer Engine MCP); replaceable in tests. */
+export declare const hostedCli: {
+    list: typeof listHostedToolsForCli;
+    call: typeof callHostedToolForCli;
+};
+export declare function formatHostedToolList(listing: HostedToolsListing): string;
 /** Resolve a name through the compiled registry index when it exists —
  *  accepts full ids ("tool/add-node") and legacy aliases, returning the slug
  *  the dispatch table knows. Returns null when the index is absent or the

package/dist/cli/commands/tool.js

@@ -14,6 +14,25 @@ import { PACKAGE_ROOT } from "../../core/package-root.js";
 import { Command, Option } from "commander";
 import { ToolDispatchError, ToolResultError, dispatchTool, listToolDispatches, resolveToolDispatch, } from "../../core/capabilities/tool-dispatch.js";
 import { c } from "../../core/format.js";
+import { callHostedToolForCli, hostedResultPayload, listHostedToolsForCli, } from "../../core/hosted-mcp.js";
+/** The hosted store and publishing tools (Summer Engine MCP); replaceable in tests. */
+export const hostedCli = { list: listHostedToolsForCli, call: callHostedToolForCli };
+const STORE_SIGN_IN_HINT = "Store and publishing tools (summer_store_*, summer_upload_image_*, summer_list_projects, ...) come from the hosted Summer Engine MCP: run 'summer login --store' to use them here.";
+export function formatHostedToolList(listing) {
+    if (listing.status === "not_signed_in")
+        return c.dim(STORE_SIGN_IN_HINT);
+    if (listing.status === "unavailable")
+        return c.dim(`Store and publishing tools: the hosted Summer Engine MCP did not answer (${listing.message}).`);
+    const local = new Set(listToolDispatches().map((entry) => `summer_${entry.slug.replace(/-/g, "_")}`));
+    const tools = listing.tools.filter((tool) => !local.has(tool.name)).sort((a, b) => a.name.localeCompare(b.name));
+    if (!tools.length)
+        return c.dim("Store and publishing tools: none listed by the hosted Summer Engine MCP.");
+    const width = Math.max(...tools.map((tool) => tool.name.length));
+    return [
+        c.bold(`Store and publishing tools (${tools.length}, hosted, with your store sign-in)`),
+        ...tools.map((tool) => `  ${tool.name.padEnd(width)}  ${(tool.description ?? "").split(/(?<=\.)\s/)[0].slice(0, 120)}`),
+    ].join("\n");
+}
 /** Resolve a name through the compiled registry index when it exists —
  *  accepts full ids ("tool/add-node") and legacy aliases, returning the slug
  *  the dispatch table knows. Returns null when the index is absent or the
@@ -86,6 +105,8 @@ export const toolCommand = new Command("tool")
     .action(async (name, options) => {
     if (options.list || name === undefined) {
         console.log(formatToolList(listToolDispatches()));
+        console.log("");
+        console.log(formatHostedToolList(await hostedCli.list()));
         if (name === undefined && !options.list) {
             console.log("");
             console.log(c.dim("Pass a tool name to run one."));
@@ -94,7 +115,21 @@ export const toolCommand = new Command("tool")
     }
     const entry = resolveToolForCli(name);
     if (!entry) {
-        throw new ToolDispatchError(`Unknown tool "${name}". Run 'summer tool --list' to see all ${listToolDispatches().length} tools.`);
+        // Not a local tool: the hosted store and publishing tools, with the store sign-in.
+        const hosted = await hostedCli.call(name, parseJsonArgs(options.args ?? options.json));
+        if (hosted.status === "called") {
+            const payload = hostedResultPayload(hosted.result);
+            console.log(payload.json ? JSON.stringify(payload.json, null, 2) : payload.text);
+            if (payload.isError)
+                process.exitCode = 1;
+            return;
+        }
+        const why = hosted.status === "not_signed_in"
+            ? ` ${STORE_SIGN_IN_HINT}`
+            : hosted.status === "unavailable"
+                ? ` The hosted Summer Engine MCP did not answer: ${hosted.message}.`
+                : "";
+        throw new ToolDispatchError(`Unknown tool "${name}". Run 'summer tool --list' to see every tool.${why}`);
     }
     if (options.json !== undefined && options.args === undefined) {
         console.error("Note: 'summer tool --json <args>' is deprecated; use --args <json>.");

package/dist/core/api-client.d.ts

@@ -22,7 +22,7 @@ export type EngineSnapshot = {
     /** Structured failure classifier the engine returns on a game snapshot over
      *  local HTTP (409 `bridge_required`) — surfaced verbatim so the tool can give
      *  an honest, actionable message instead of a truncated generic 409 string.
-     *  When P4.4 lands (game snapshots answer 200/202 over HTTP) this simply
+     *  Once game snapshots answer 200/202 over HTTP this simply
      *  never fires and the tool works. */
     failureReason?: string;
     /** Scene-preview confession fields (P4.3). Populated only for target:"scene".
@@ -194,8 +194,8 @@ export declare class EngineApiClient {
     private _parseSnapshotResponse;
     /**
      * Turn a 409 from /api/snapshot/game into a structured failure. The engine's
-     * structural refusal carries `bridge_required` / `unsupported_transport`
-     * (tool_net_thread.cpp:495-503); a 409 without that shape is surfaced as a
+     * structural refusal carries `bridge_required` / `unsupported_transport`;
+     * a 409 without that shape is surfaced as a
      * plain error rather than silently claiming "bridge required".
      */
     private _bridgeRequiredFromResponse;
@@ -246,9 +246,8 @@ export declare class EngineApiClient {
     getPort(): number;
     /**
      * Cheap drift probe for the MCP client cache. The engine mints a fresh
-     * api-token on every launch (local_api_server.cpp::_generate_api_token) and can
-     * bind a different port (tool_net_thread.cpp::start increments 6550..6565 when
-     * the old socket lingers), so a client built before an engine restart holds
+     * api-token on every launch and can bind a different port (it increments
+     * 6550..6565 when the old socket lingers), so a client built before an engine restart holds
      * dead credentials. Re-read the on-disk creds and report whether they no longer
      * match this client's snapshot.
      *

package/dist/core/api-client.js

@@ -492,8 +492,7 @@ export class EngineApiClient {
     async getSceneState(scenePath, options) {
         // depth/limit/root only take effect on targeted (scene=) reads: the engine
         // routes those through the live command queue and forwards every query
-        // param into StateProvider::scene_state (tool_net_thread.cpp
-        // _parse_state_args). An UNtargeted read is answered from a pre-published
+        // param into the engine's scene-state reader. An UNtargeted read is answered from a pre-published
         // snapshot built with the defaults (depth 2, limit 200) and its query
         // params are ignored — callers who need depth/limit must pass scenePath
         // (summer_get_scene_tree resolves the current scene path for this).
@@ -515,9 +514,8 @@ export class EngineApiClient {
     async getProjectState(prefix) {
         // ?prefix= is sent for forward-compatibility, but current engine builds
         // IGNORE it: /api/state/project is always served from the snapshot, which
-        // is published with empty args (local_api_server.cpp
-        // _maybe_publish_snapshot), so StateProvider::project_state never sees the
-        // query. Callers that need a prefix subset must also filter client-side
+        // is published with empty args, so the engine's project-state reader never
+        // sees the query. Callers that need a prefix subset must also filter client-side
         // (summer_get_project_context does).
         const query = prefix ? `?prefix=${encodeURIComponent(prefix)}` : "";
         return this.request("GET", `/api/state/project${query}`);
@@ -542,13 +540,13 @@ export class EngineApiClient {
         if (pins) {
             // Determinism params (seed / fixed_fps / time_scale) — the /api/play rung
             // copies ONLY `scene` from options into the PlayGame op
-            // (local_api_server.cpp play branch), so a pinned launch travels as an
+            // (the engine's /api/play handler), so a pinned launch travels as an
             // explicit PlayGame op through /api/ops. executeOps stamps the bound
             // identity like every other op. An engine that predates the params
             // ignores the extra keys and answers the v1 result (no `determinism`).
             return this.executeOps([{ op: "PlayGame", ...(scene ? { scene } : {}), ...pins }], undefined, 60_000);
         }
-        // The engine reads play params from body.options (tool_net_thread.cpp:503),
+        // The engine reads play params from body.options,
         // and the play handler reads options["scene"] — a top-level { scene } is
         // dropped, so the scene MUST be nested inside options. The bound identity
         // rides in the same options dict so play is refused on a mismatched project.
@@ -593,10 +591,10 @@ export class EngineApiClient {
         // with the same payload shape — _requestQueued resolves both.
         //
         // Game capture over local HTTP structurally 409s today with a STRUCTURED
-        // reason (`failure_reason:"unsupported_transport"`, `bridge_required:true`,
-        // tool_net_thread.cpp:495-503). Detect that specific shape and return it
+        // reason (`failure_reason:"unsupported_transport"`, `bridge_required:true`).
+        // Detect that specific shape and return it
         // verbatim so the tool can give an honest message — do NOT hardcode "game
-        // always fails": once the engine answers 200/202 (P4.4), the same response
+        // always fails": once the engine answers 200/202, the same response
         // flows into the normal queued path. ONE request either way: a probe that
         // discarded a 200 (or orphaned an accepted 202 requestId) and then asked
         // again would capture the game twice.
@@ -681,8 +679,8 @@ export class EngineApiClient {
     }
     /**
      * Turn a 409 from /api/snapshot/game into a structured failure. The engine's
-     * structural refusal carries `bridge_required` / `unsupported_transport`
-     * (tool_net_thread.cpp:495-503); a 409 without that shape is surfaced as a
+     * structural refusal carries `bridge_required` / `unsupported_transport`;
+     * a 409 without that shape is surfaced as a
      * plain error rather than silently claiming "bridge required".
      */
     async _bridgeRequiredFromResponse(res) {
@@ -777,9 +775,8 @@ export class EngineApiClient {
     }
     /**
      * Cheap drift probe for the MCP client cache. The engine mints a fresh
-     * api-token on every launch (local_api_server.cpp::_generate_api_token) and can
-     * bind a different port (tool_net_thread.cpp::start increments 6550..6565 when
-     * the old socket lingers), so a client built before an engine restart holds
+     * api-token on every launch and can bind a different port (it increments
+     * 6550..6565 when the old socket lingers), so a client built before an engine restart holds
      * dead credentials. Re-read the on-disk creds and report whether they no longer
      * match this client's snapshot.
      *

package/dist/core/auth.js

@@ -161,8 +161,8 @@ export async function saveLoginSession(session) {
     // those exact files. credential-metadata.json adds audience/scope information
     // without changing or duplicating the secret.
     // Write order: user.json, then auth-token, then the advisory metadata. The
-    // desktop engine cross-checks token.sub against user.json's id
-    // (summerengine auth_manager.cpp, inspect_cli_bootstrap_credential), so a
+    // desktop engine cross-checks token.sub against user.json's id when it
+    // adopts the CLI credential, so a
     // write interrupted between the first two files fails closed instead of
     // adopting a mismatched identity. The metadata write is last and is NOT a
     // gate: the token is already live by then, and its contents are re-derived

package/dist/core/capabilities/asset-import.d.ts

@@ -2,7 +2,6 @@
  * Asset import into the engine-bound project (Kenney texture pairing + path
  * inference + optional scene placement). ONE copy shared by the MCP asset tools
  * and the CLI dispatch table.
- * See: publicsummerengine/Docs/ASSET_IMPORT_END_TO_END.md
  */
 import type { EngineApiClient } from "../api-client.js";
 /** An asset record as returned by the Summer gateway asset APIs. */

package/dist/core/capabilities/camera-view.d.ts

@@ -4,7 +4,7 @@ export type CameraBookmarkAction = (typeof CAMERA_BOOKMARK_ACTIONS)[number];
 export declare const CAMERA_BOOKMARK_OPS: Record<CameraBookmarkAction, string>;
 /** What the engine_lacks_op result tells the model to do instead. */
 export declare const CAMERA_BOOKMARK_FALLBACK = "pass the pose explicitly on every capture with summer_screenshot framing:\"free\" (camera_position + camera_look_at), or render through a Camera3D placed in the scene with framing:\"camera\"";
-/** Bookmark name grammar (preview_ops.cpp): 1-64 of [A-Za-z0-9_-]. */
+/** Bookmark name grammar (same as the engine's): 1-64 of [A-Za-z0-9_-]. */
 export declare const BOOKMARK_NAME_PATTERN: RegExp;
 export interface CameraBookmarkArgs {
     action: CameraBookmarkAction;

package/dist/core/capabilities/camera-view.js

@@ -4,7 +4,7 @@
  * and the CLI dispatcher so both faces validate the same way and send the same
  * op.
  *
- * Engine contract (doc/SUMMER/SCENE_SCRIPTING_CONTRACTS.md, "Wave I"):
+ * Engine contract:
  *   SaveCameraBookmark { name, position?, look_at?, fov? }  -> pose_source
  *   ListCameraBookmarks {}                                   -> names, bookmarks
  *   DeleteCameraBookmark { name }                            -> remaining
@@ -25,7 +25,7 @@ export const CAMERA_BOOKMARK_OPS = {
 };
 /** What the engine_lacks_op result tells the model to do instead. */
 export const CAMERA_BOOKMARK_FALLBACK = "pass the pose explicitly on every capture with summer_screenshot framing:\"free\" (camera_position + camera_look_at), or render through a Camera3D placed in the scene with framing:\"camera\"";
-/** Bookmark name grammar (preview_ops.cpp): 1-64 of [A-Za-z0-9_-]. */
+/** Bookmark name grammar (same as the engine's): 1-64 of [A-Za-z0-9_-]. */
 export const BOOKMARK_NAME_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
 function requireBookmarkName(name, action) {
     const trimmed = name?.trim() ?? "";

package/dist/core/capabilities/capture-gameplay.d.ts

@@ -0,0 +1,69 @@
+import { type EngineRun } from "./engine-run.js";
+/**
+ * summer_capture_gameplay: real gameplay frames without a running editor.
+ *
+ * Reuses the engine's offscreen verify instance (the one RunVerification and
+ * tests/autopilot spawn): a real renderer in a window parked offscreen with no
+ * focus, so it never shows on screen, unlike --headless, which has no pixels.
+ *
+ *   <engine> --disable-crash-handler --summer-no-api --path <project> --resolution WxH
+ *            [--scene res://...] --summer-verify <probe.gd>
+ *            --summer-verify-out <dir> --summer-verify-max <s>
+ *
+ * The stock probe waits for the scene to draw and settle, saves PNG frames of
+ * the game viewport, and writes results.json. The frames are what the game
+ * really draws, HUD included: use them as store screenshots.
+ */
+export interface CaptureGameplayInput {
+    /** Project root (has project.godot). Defaults to the MCP's --project, then the working directory. */
+    project?: string;
+    /** Scene to start (res:// or uid://). Default: the project's main scene. */
+    scene?: string;
+    /** Window size, WIDTHxHEIGHT. Default 1920x1080; 1080x1920 for portrait. */
+    resolution?: string;
+    /** Frames to save. Default 1. */
+    frames?: number;
+    /** Seconds to let the game run before the first frame. Default 3. */
+    waitSeconds?: number;
+    /** Seconds between frames. Default 1. */
+    intervalSeconds?: number;
+    /** Output folder. Default <project>/.summer/captures/<time>/. */
+    out?: string;
+}
+export interface CapturedFrame {
+    path: string;
+    width: number;
+    height: number;
+}
+export interface CaptureGameplayResult {
+    ok: true;
+    project: string;
+    scene: string;
+    resolution: string;
+    frames: CapturedFrame[];
+    out: string;
+    engine: string;
+    imported: boolean;
+    durationMs: number;
+    warnings?: string[];
+    next: string;
+}
+export interface CaptureGameplayDependencies {
+    findBinary: () => string | null;
+    run: (binary: string, args: string[], timeoutMs: number) => Promise<EngineRun>;
+    now: () => Date;
+}
+/** Width and height from a PNG's IHDR chunk, or null when the file is not a PNG. */
+export declare function pngSize(bytes: Buffer): {
+    width: number;
+    height: number;
+} | null;
+/**
+ * The stock probe. Self-contained (extends Node, no base class to copy into the
+ * project); follows the verify-instance contract of assets/autopilot/probe_base.gd:
+ * the engine sets summer_out_dir and summer_max_seconds before _ready(), the
+ * first frames are empty until the scene has drawn twice, results.json is
+ * always written.
+ */
+export declare function captureProbeSource(frames: number, waitSeconds: number, intervalSeconds: number): string;
+export declare function captureGameplay(input: CaptureGameplayInput, overrides?: Partial<CaptureGameplayDependencies>): Promise<CaptureGameplayResult>;