summer-engine 3.4.0 → 3.5.0

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/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/setup.js

@@ -1,5 +1,5 @@
 import { Command, Option } from "commander";
-import { configureAgentMcp, resolveAgentSelection, resolveConfigScope, supportedAgents, } from "../../installer/agent-config.js";
+import { configureAgentMcp, configureSummerGamesMcp, resolveAgentSelection, resolveConfigScope, supportedAgents, } from "../../installer/agent-config.js";
 import { previewNote, setupSkills } from "../../installer/setup.js";
 import { printDoctorResult, runDoctor } from "../../core/capabilities/doctor.js";
 import { brandLine, c, sym, tildeify } from "../../core/format.js";
@@ -7,7 +7,7 @@ import { TOOLKIT_VERSION as cliVersion } from "../../core/version.js";
 import { resolveDefaultChannel } from "../../installer/version-check.js";
 import { agentLabel } from "../../installer/agent-table.js";
 export const setupCommand = new Command("setup")
-    .description("Configure Summer Engine for an AI agent and run diagnostics")
+    .description("Configure Summer Engine for an AI agent and run diagnostics. For Claude Code and Codex it also adds Summer Games (summer-games).")
     .argument("[agent]", `Agent to configure: ${supportedAgents.join(", ")}`)
     .option("--agent <agent>", `Agent to configure: ${supportedAgents.join(", ")}`)
     .option("--scope <scope>", "Configuration scope: user or project", "user")
@@ -16,6 +16,7 @@ export const setupCommand = new Command("setup")
     .option("--local-dev", "Point the agent at this checkout's built CLI (node <repo>/dist/bin/summer.js mcp) instead of npx summer-engine@latest — for testing unpublished builds. SUMMER_DEV=1 does the same.")
     .option("--channel <dist-tag>", "npm dist-tag the agent's MCP entry runs: npx -y summer-engine@<dist-tag> mcp (default latest; use next while a release soaks on the next tag). SUMMER_CHANNEL does the same.")
     .option("--yes", "Apply practical setup steps without prompting")
+    .option("--no-games", "Do not add the Summer Games MCP (summer-games: friends, parties and messages as you, signed in through summer.games; Claude Code and Codex)")
     .option("--json", "Print setup result as JSON")
     .option("--force", "Overwrite existing skill content (passes --force through to skills install)")
     .option("--recommended", "Install only the recommended skill subset instead of the whole library")
@@ -34,6 +35,9 @@ export const setupCommand = new Command("setup")
         localDev: Boolean(opts.localDev) || process.env.SUMMER_DEV === "1",
         channel: opts.channel ?? process.env.SUMMER_CHANNEL ?? defaultChannel.channel,
     });
+    const games = opts.games === false || opts.print
+        ? null
+        : await configureSummerGamesMcp({ agent, scope, dryRun: opts.dryRun });
     if (!opts.channel && !process.env.SUMMER_CHANNEL && defaultChannel.note && !opts.print) {
         console.log(`  ${c.dim(defaultChannel.note)}`);
     }
@@ -50,18 +54,19 @@ export const setupCommand = new Command("setup")
         console.log(JSON.stringify({
             ok: doctor.ok && skills.status !== "failed",
             config,
+            games,
             skills,
             doctor,
         }, null, 2));
     }
     else {
-        printSetupResult(config, skills, doctor);
+        printSetupResult(config, games, skills, doctor);
     }
     if (!doctor.ok || skills.status === "failed") {
         process.exit(1);
     }
 });
-function printSetupResult(config, skills, doctor) {
+function printSetupResult(config, games, skills, doctor) {
     if (config.print) {
         console.log(config.snippet.trimEnd());
         return;
@@ -85,6 +90,21 @@ function printSetupResult(config, skills, doctor) {
     else if (config.channel !== "latest") {
         console.log(`  ${c.dim(`(channel ${config.channel})`)}  MCP server command: ${c.dim(`${config.server.command} ${config.server.args.join(" ")}`)}`);
     }
+    if (games) {
+        const name = c.bold("Summer Games");
+        const url = c.dim(games.url);
+        if (games.existingName) {
+            console.log(`  ${sym.ok()}  ${name} already added as ${c.bold(games.existingName)}  ${url}`);
+        }
+        else if (config.dryRun) {
+            console.log(`  ${c.dim("(dry run)")}  ${games.changed ? "Would add" : "Already added"} ${name}  ${url}`);
+        }
+        else {
+            console.log(`  ${sym.ok()}  ${games.wrote ? "Added" : "Already added"} ${name}  ${url}`);
+        }
+        if (!config.dryRun)
+            console.log(`     ${c.dim(`Sign in once: ${games.signIn}`)}`);
+    }
     if (skills.status === "installed") {
         const installed = parseInstalledSkills(skills.stdout);
         if (installed.length > 0) {

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/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

@@ -7,12 +7,15 @@ import { type EngineRun } from "./engine-run.js";
  * 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>
+ *            [--scene res://...] --summer-offscreen --summer-verify <probe.gd>
+ *            --summer-verify-out <dir> --summer-verify-max <s> [-- <args>]
  *
- * 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.
+ * The stock probe waits for the scene to draw and settle, runs the steps (press
+ * a button, a key or an input action, click, drag, wait, shot) from inside the
+ * game, 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. `args` reach the game as OS.get_cmdline_user_args(), so a game
+ * that skips its title screen on a flag starts in play.
  */
 export interface CaptureGameplayInput {
     /** Project root (has project.godot). Defaults to the MCP's --project, then the working directory. */
@@ -29,6 +32,49 @@ export interface CaptureGameplayInput {
     intervalSeconds?: number;
     /** Output folder. Default <project>/.summer/captures/<time>/. */
     out?: string;
+    /** The game's own command-line args, passed after "--" (OS.get_cmdline_user_args()). */
+    args?: string[];
+    /** What to do after waitSeconds, in order. With a shot step, only shot steps save frames. */
+    steps?: CaptureStep[];
+}
+/**
+ * One capture step, run from inside the game. Coordinates are frame pixels
+ * (the saved PNG's space). press finds a visible, enabled button by its text,
+ * then its node name, then a partial match, waiting up to timeoutSeconds for
+ * it to appear; it clicks the button's centre, and emits pressed when the
+ * click did not reach it. key takes Godot key names (Space, Enter, Escape, A).
+ */
+export type CaptureStep = {
+    press: string;
+    timeoutSeconds?: number;
+} | {
+    key: string;
+    holdMs?: number;
+} | {
+    action: string;
+    holdMs?: number;
+} | {
+    click: [number, number];
+} | {
+    drag: {
+        from: [number, number];
+        to: [number, number];
+        ms?: number;
+    };
+} | {
+    wait: number;
+} | {
+    shot: true;
+};
+/** A step as the probe reads it (one shape, all fields named). */
+export interface ProbeStep {
+    type: "press" | "key" | "action" | "click" | "drag" | "wait" | "shot";
+    text?: string;
+    timeout?: number;
+    hold_ms?: number;
+    at?: [number, number];
+    to?: [number, number];
+    ms?: number;
 }
 export interface CapturedFrame {
     path: string;
@@ -44,6 +90,8 @@ export interface CaptureGameplayResult {
     out: string;
     engine: string;
     imported: boolean;
+    /** Why the project was imported before the capture. */
+    importReason?: string;
     durationMs: number;
     warnings?: string[];
     next: string;
@@ -53,6 +101,20 @@ export interface CaptureGameplayDependencies {
     run: (binary: string, args: string[], timeoutMs: number) => Promise<EngineRun>;
     now: () => Date;
 }
+/** Validate the steps and turn them into the probe's one shape. */
+export declare function probeSteps(steps: unknown): ProbeStep[];
+/**
+ * Whether the project's import caches are stale: an imported file (texture,
+ * model, sound, font) that has no .import sidecar or cache yet, or whose
+ * content changed since it was imported (a pull, or LFS files fetched after
+ * the first import). Also names files that are still Git LFS pointers, which no
+ * import can fix.
+ */
+export declare function importState(project: string): {
+    needed: boolean;
+    reason?: string;
+    lfsPointers: string[];
+};
 /** 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;
@@ -63,7 +125,10 @@ export declare function pngSize(bytes: Buffer): {
  * 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.
+ * always written. The steps are generated as typed calls, and nothing reads a
+ * Variant, so projects that treat every GDScript warning as an error
+ * (untyped_declaration, unsafe_call_argument, unsafe_cast, integer_division)
+ * still load it.
  */
-export declare function captureProbeSource(frames: number, waitSeconds: number, intervalSeconds: number): string;
+export declare function captureProbeSource(frames: number, waitSeconds: number, intervalSeconds: number, steps?: ProbeStep[]): string;
 export declare function captureGameplay(input: CaptureGameplayInput, overrides?: Partial<CaptureGameplayDependencies>): Promise<CaptureGameplayResult>;