summer-engine 3.8.0 → 4.0.0

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

@@ -1,11 +1,12 @@
 import { z } from "zod";
 import { withEngine, missingEngineOpResult, withOldEngineHint } from "./with-engine.js";
 import { lookupApiDocs } from "../../core/capabilities/api-docs.js";
-import { RUN_EDITOR_SCRIPT_FALLBACK, RUN_SCRIPT_FALLBACK, buildRunEditorScriptOp, buildRunSceneScriptOp, } from "../../core/capabilities/scene-script.js";
+import { RUN_EDITOR_SCRIPT_FALLBACK, RUN_SCRIPT_FALLBACK, buildRunEditorScriptOp, } from "../../core/capabilities/scene-script.js";
+import { runSceneScriptOn } from "../../core/capabilities/scene-script-target.js";
 // Re-exported so existing tests keep importing the lookup from the tool module.
 export { API_DOCS_NOT_INSTALLED, isApiDocsBundleInstalled, lookupApiDocs, resetApiDocsForTests, } from "../../core/capabilities/api-docs.js";
 export function registerScriptTools(server) {
-    server.tool("summer_run_script", `Run a GDScript snippet INSIDE the live editor, against the currently OPEN scene. This is the scene-scripting workhorse: one script replaces long chains of add-node/set-prop calls, and it can compute (loops, randomness, math, procedural meshes) what individual CRUD ops cannot.
+    server.tool("summer_run_script", `Run a GDScript snippet INSIDE the live editor, against the scene named by scenePath (opened first when it is not the edited one; the person's tab comes back after the run). Without scenePath it runs against the currently OPEN scene. This is the scene-scripting workhorse: one script replaces long chains of add-node/set-prop calls, and it can compute (loops, randomness, math, procedural meshes) what individual CRUD ops cannot.
 
 SCRIPT CONTRACT — write ONLY the body below; do not add extends/@tool lines (missing ones are prepended and reported in 'normalizations'):
 
@@ -33,6 +34,10 @@ WHEN TO USE: 3+ related ops, anything with computed placement (scatter, grids, r
 THE LOOP: summer_world_snapshot (keep snapshot_id) -> summer_run_script -> summer_snapshot_diff + summer_screenshot -> inspect -> iterate. Never claim visual success without the screenshot.
 
 Returns {ok, ran, result, reports, output, errors, duration_ms, checkpoint} — newer engines add rolled_back (a runtime error rolled the whole undo action back; the scene is untouched) and budget_enforced (max_seconds was a HARD deadline; when the budget hits, the script errors with "Summer script budget exceeded" — split the work into smaller scripts, never resubmit the same oversized one). Read 'errors' even when ok — with undo:'none', a partially-failed script may have mutated the scene. If this engine build predates RunSceneScript, the result is a structured engine_lacks_op failure (nothing is sent): use summer_run_editor_script or update Summer Engine.`, {
+        scenePath: z
+            .string()
+            .optional()
+            .describe("The scene to run against, e.g. 'res://main.tscn'. Opened first when it is not the edited scene, then the person's tab is restored. Omit only to run against whatever scene is open."),
         source: z.string().describe("GDScript source containing `func run(ctx):`. No extends/@tool line — just the function (plus any helpers)."),
         max_seconds: z
             .number()
@@ -46,12 +51,11 @@ Returns {ok, ran, result, reports, output, errors, duration_ms, checkpoint} —
             .enum(["action", "none"])
             .optional()
             .describe("Transaction mode (newer engines). 'action' (engine default): the whole run is ONE named undo action, and a mid-script runtime error rolls it back before returning (result rolled_back:true) — no half-mutated scene. 'none': v1 behavior, checkpoint only. Older engines ignore this."),
-    }, async ({ source, max_seconds, checkpoint, undo }) => withEngine(async (client) => {
+    }, async ({ scenePath, source, max_seconds, checkpoint, undo }) => withEngine(async (client) => {
         const missing = missingEngineOpResult(client, "RunSceneScript", RUN_SCRIPT_FALLBACK);
         if (missing)
             return missing;
-        const { op, timeoutMs } = buildRunSceneScriptOp({ source, max_seconds, checkpoint, undo });
-        const result = await client.executeIdentityBoundOps([op], undefined, timeoutMs);
+        const result = await runSceneScriptOn(client, { scenePath, source, max_seconds, checkpoint, undo });
         return withOldEngineHint(result, "RunSceneScript", "use summer_run_editor_script instead");
     }));
     server.tool("summer_run_editor_script", `Run a GDScript EditorScript in a FRESH HEADLESS editor spawned against the ON-DISK project. Cold path: a whole child editor boots, runs your script once, and exits — seconds to tens of seconds depending on the project and the script (about 2 s end to end on a small template project; large projects can spend 30 s+ just booting).

package/dist/mcp/tools/with-engine.d.ts

@@ -1,4 +1,5 @@
 import { getClient } from "../server.js";
+import { EngineNotRunningError } from "../../core/error-codes.js";
 import { extractOpError, withOldEngineHint } from "../../core/capabilities/engine-receipt.js";
 export { extractOpError, withOldEngineHint };
 export { missingEngineOpResult, type CapabilityAdvertisingClient, } from "../../core/capability-skew.js";
@@ -57,6 +58,11 @@ export interface WithEngineOptions<T> {
  */
 export declare function isAuthError(err: unknown): boolean;
 export declare function withEngine<T>(fn: (client: Awaited<ReturnType<typeof getClient>>) => Promise<T>, opts?: WithEngineOptions<T>): Promise<ToolResult>;
+/** No editor reachable: `{ok:false, code:"engine_not_running", error,
+ *  recovery, hint}` as JSON, so agents branch on the code instead of
+ *  scraping the sentence. Exported for the tools that call getClient()
+ *  outside withEngine. */
+export declare function engineNotRunningResult(error: EngineNotRunningError): ToolResult;
 /** Every transport-level failure must TEACH recovery, not just name the error.
  *  getClient()'s connect failure already carries its own instructions; anything
  *  else (fetch failed / abort / HTTP status thrown mid-call) gets the generic

package/dist/mcp/tools/with-engine.js

@@ -1,6 +1,7 @@
 import { getClient, resetClient } from "../server.js";
 import { recordMcpSession } from "../../core/telemetry.js";
 import { thrownErrorClass } from "../../core/tool-errors.js";
+import { codedFailure, ENGINE_FREE_NOTE, EngineNotRunningError } from "../../core/error-codes.js";
 import { extractOpError, getFailureReason, withOldEngineHint, } from "../../core/capabilities/engine-receipt.js";
 export { extractOpError, withOldEngineHint };
 export { missingEngineOpResult, } from "../../core/capability-skew.js";
@@ -143,9 +144,27 @@ export async function withEngine(fn, opts) {
             break;
         }
     }
+    if (lastError instanceof EngineNotRunningError) {
+        return attachMeta(engineNotRunningResult(lastError), {
+            errorClass: "transport",
+            failureReason: "engine_not_running",
+            retried,
+            boundProjectIdHash,
+        });
+    }
     const msg = lastError instanceof Error ? lastError.message : String(lastError);
     return attachMeta({ content: [{ type: "text", text: withTransportRecovery(msg) }], isError: true }, { errorClass: "transport", retried, boundProjectIdHash });
 }
+/** No editor reachable: `{ok:false, code:"engine_not_running", error,
+ *  recovery, hint}` as JSON, so agents branch on the code instead of
+ *  scraping the sentence. Exported for the tools that call getClient()
+ *  outside withEngine. */
+export function engineNotRunningResult(error) {
+    return {
+        isError: true,
+        content: [{ type: "text", text: JSON.stringify(codedFailure(error.code, error.message, { hint: ENGINE_FREE_NOTE }), null, 2) }],
+    };
+}
 const PRE_APPLY_FAILURE_REASON = {
     input: "invalid_input",
     unsupported: "unsupported_operation",

package/gemini-extension.json

@@ -1,7 +1,7 @@
 {
   "_generated": "GENERATED from integrations/gemini — do not edit; npm run generate:registry",
   "name": "summer",
-  "version": "3.8.0",
+  "version": "4.0.0",
   "description": "Agent tooling for Summer Engine: MCP bridge, context primer, and game-dev skills. Use with the npm CLI for skill files on disk.",
   "contextFileName": "GEMINI.md",
   "mcpServers": {
@@ -40,7 +40,6 @@
     "./library/skills/brainstorming/",
     "./library/skills/browse-templates/",
     "./library/skills/camera-rigs/",
-    "./library/skills/celeste-momentum-platforming/",
     "./library/skills/character-animation-wiring/",
     "./library/skills/character-model/",
     "./library/skills/character-movement/",
@@ -49,6 +48,7 @@
     "./library/skills/combat-basics/",
     "./library/skills/compatibility-renderer-traps/",
     "./library/skills/concept-art/",
+    "./library/skills/concept-to-level/",
     "./library/skills/create-asset-sheet/",
     "./library/skills/debug/",
     "./library/skills/debugging-game-feel/",
@@ -67,13 +67,11 @@
     "./library/skills/gameskill/",
     "./library/skills/gdscript-patterns/",
     "./library/skills/generate-motion/",
-    "./library/skills/godogen-visual-proof-game-generation/",
     "./library/skills/grow-analytics/",
     "./library/skills/headless-scripting/",
     "./library/skills/in-game-purchases/",
     "./library/skills/instantiate-asset-pack/",
     "./library/skills/investigating-bugs/",
-    "./library/skills/lumera-single-image-scene-reconstruction/",
     "./library/skills/make-game/",
     "./library/skills/multiplayer/",
     "./library/skills/multiplayer-movement/",
@@ -90,9 +88,7 @@
     "./library/skills/playtesting-a-feature/",
     "./library/skills/procedural-animation/",
     "./library/skills/prop-model/",
-    "./library/skills/psx-retro-rendering/",
     "./library/skills/publish-your-game/",
-    "./library/skills/realtime-wet-surfaces/",
     "./library/skills/release-readiness/",
     "./library/skills/remote-deploy/",
     "./library/skills/retarget/",
@@ -102,10 +98,6 @@
     "./library/skills/scene-hierarchy-design/",
     "./library/skills/scene-scripting/",
     "./library/skills/scene-to-level/",
-    "./library/skills/skill-create/",
-    "./library/skills/skill-improve/",
-    "./library/skills/skill-test/",
-    "./library/skills/skintokens-auto-rigging/",
     "./library/skills/skybox-panorama/",
     "./library/skills/sound-effect/",
     "./library/skills/spatial-placement/",
@@ -115,6 +107,7 @@
     "./library/skills/summer-analytics/",
     "./library/skills/summer-apps/",
     "./library/skills/summer-apps-design/",
+    "./library/skills/summer-assets/",
     "./library/skills/summer-friends/",
     "./library/skills/summer-leaderboards/",
     "./library/skills/summer-match-results/",
@@ -147,7 +140,6 @@
     "./library/skills/web-and-touch-input/",
     "./library/skills/web-compatibility-look/",
     "./library/skills/world-building-3d/",
-    "./library/skills/writing-plans/",
-    "./library/skills/writing-skills/"
+    "./library/skills/writing-plans/"
   ]
 }

package/hooks/pre-commit-doctor.sh

@@ -9,9 +9,10 @@
 # Status:   OPT-IN. The hook is always registered but exits 0 immediately
 #           unless one of these is set:
 #             CLAUDE_PLUGIN_OPTION_ENABLE_PRE_COMMIT_DOCTOR=true
-#               Claude Code exports every plugin userConfig value to hook
-#               processes as CLAUDE_PLUGIN_OPTION_<KEY>; this is the
-#               `enable_pre_commit_doctor` toggle from plugin.json.
+#               The `enable_pre_commit_doctor` plugin option of older
+#               plugin versions (Claude Code exports userConfig values to
+#               hooks as CLAUDE_PLUGIN_OPTION_<KEY>). The plugin no longer
+#               declares it: every option opens a dialog on enable.
 #             SUMMER_PRE_COMMIT_DOCTOR=1
 #               Manual / other-host opt-in (also the envVar Gemini's
 #               gemini-extension.json `settings` entry maps to).
@@ -111,7 +112,7 @@ if [ "$HAS_FAIL" -eq 1 ]; then
         echo "$FAIL_MSGS"
         echo ""
         echo "Fix the failures above, or run: summer doctor"
-        echo "To bypass: turn off the plugin option enable_pre_commit_doctor (or unset SUMMER_PRE_COMMIT_DOCTOR)."
+        echo "To bypass: unset SUMMER_PRE_COMMIT_DOCTOR (or turn off the enable_pre_commit_doctor option where your host has it)."
         echo "============================================"
     } >&2
     exit 2

package/hooks/session-start.sh

@@ -3,8 +3,8 @@
 #
 # Event:    SessionStart (matcher: startup|clear|compact)
 # Purpose:  Orient Claude on every fresh Summer-enabled session.
-#           Detect Summer project + GameSoul + doctor health and surface a short
-#           greeting as additional context.
+#           Detect Summer project + GameSoul + first-run state and surface a
+#           short greeting as additional context.
 #
 # Input:    JSON on stdin with { session_id, source, model, cwd, ... }
 #           Common Claude Code env vars: $CLAUDE_PROJECT_DIR, $CLAUDE_PLUGIN_ROOT
@@ -13,8 +13,8 @@
 # Exit:     Always 0 — never block session start.
 #
 # Portability: bash 3.2+ (macOS default), POSIX-friendly, works on Git Bash.
-#              Uses `grep -E` not `grep -P`. Falls back gracefully when jq
-#              and `summer` are missing.
+#              Uses `grep -E` not `grep -P`. File checks only: no network,
+#              no child processes beyond grep/awk/find, so it returns at once.
 
 set +e  # Hooks must never kill the session.
 
@@ -64,30 +64,26 @@ if [ -f "${PROJECT_DIR}/project.godot" ]; then
     fi
 fi
 
-# Line 3: doctor fail one-liner (only on status "fail" — silent on ok/warning).
-# Doctor JSON (src/core/capabilities/doctor.ts): checks[].status is lowercase
-# "ok" | "warning" | "fail". Only runs when a `summer` CLI is on PATH: the
-# documented npx install never puts one there, and a cold `npx summer-engine`
-# fetch would exceed the 10s SessionStart budget, so we degrade silently.
-if command -v summer >/dev/null 2>&1; then
-    DOCTOR_OUT=$(summer doctor --json 2>/dev/null)
-    if [ -n "$DOCTOR_OUT" ]; then
-        FAIL_REASON=""
-        if command -v jq >/dev/null 2>&1; then
-            FAIL_REASON=$(printf '%s' "$DOCTOR_OUT" \
-                | jq -r 'first(.checks[]? | select((.status // "" | ascii_downcase) == "fail") | .message) // empty' 2>/dev/null)
-        else
-            # Crude fallback: first "message" near a "fail"
-            FAIL_REASON=$(printf '%s' "$DOCTOR_OUT" \
-                | grep -oE '"status"[[:space:]]*:[[:space:]]*"(FAIL|fail)"[^}]*"message"[[:space:]]*:[[:space:]]*"[^"]*"' \
-                | head -1 \
-                | grep -oE '"message"[[:space:]]*:[[:space:]]*"[^"]*"' \
-                | sed 's/.*"message"[[:space:]]*:[[:space:]]*"//;s/"$//')
-        fi
-        if [ -n "$FAIL_REASON" ]; then
-            LINES+=("Summer setup needs attention: ${FAIL_REASON}. Run: summer doctor")
-        fi
-    fi
+# Line 3: first-run / sign-in hint, from local files only. No network and no
+# `summer doctor` here: SessionStart blocks the session until it returns, and a
+# doctor run (npm registry, engine probe, MCP boot) can take seconds. The full
+# check is one call away (`summer doctor`, or /summer:start on a first run).
+SUMMER_HOME="${HOME}/.summer"
+ENGINE_FOUND=""
+for candidate in "/Applications/Summer.app" "${HOME}/Applications/Summer.app" \
+    "${LOCALAPPDATA:-}/Programs/Summer" "${LOCALAPPDATA:-}/SummerEngine" "${HOME}/.local/share/summer-engine"; do
+    if [ -e "$candidate" ]; then ENGINE_FOUND=1; break; fi
+done
+if [ -n "${SUMMER_BIN:-}${SUMMER_ENGINE_BINARY:-}" ]; then ENGINE_FOUND=1; fi
+# /summer:start is the Claude Code plugin command; other hosts get the CLI.
+START_HINT="run: npx -y summer-engine@latest setup"
+if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -z "${CURSOR_PLUGIN_ROOT:-}" ]; then
+    START_HINT="suggest /summer:start (sets up Summer and makes a first playable game in about five minutes)"
+fi
+if [ ! -d "$SUMMER_HOME" ] && [ -z "$ENGINE_FOUND" ] && [ -z "${SUMMER_TOKEN:-}" ]; then
+    LINES+=("Summer is not set up on this machine yet. When the user wants to make a game, ${START_HINT}.")
+elif [ ! -f "${SUMMER_HOME}/auth-token" ] && [ -z "${SUMMER_TOKEN:-}" ]; then
+    LINES+=("Summer CLI is not signed in: asset and publishing tools need \`summer login\` (or sign in to the summer-cloud server in /mcp).")
 fi
 
 # ---------- Compose context ----------

package/integrations/claude-desktop/README.md

@@ -6,7 +6,7 @@ is intentionally empty. Support is delivered at install time by
 
 - MCP config: `~/Library/Application Support/Claude/claude_desktop_config.json`; Linux `~/.config/Claude/claude_desktop_config.json`; Windows `%APPDATA%/Claude/claude_desktop_config.json` (user); user scope only (project requests fall back with a warning).
   Shape: `mcpServers.summer-engine = { command, args }`.
-- Skills: none. Claude Desktop has no skills folder. The MCP server ships summer_get_agent_playbook, so the model can pull Summer guidance in-chat.
+- Skills: none. Claude Desktop has no skills folder. The MCP server ships summer_docs_search and summer_docs_read, so the model can pull Summer guidance in-chat.
 - After: Quit and reopen Claude Desktop; the summer-engine tools appear under the tools menu in a new chat.
 
 Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/copilot-jetbrains/README.md

@@ -6,7 +6,7 @@ is intentionally empty. Support is delivered at install time by
 
 - MCP config: `~/.config/github-copilot/intellij/mcp.json`; Windows `%APPDATA%/github-copilot/intellij/mcp.json` (user); user scope only (project requests fall back with a warning).
   Shape: `servers.summer-engine = { command, args }`.
-- Skills: none. Copilot in JetBrains documents no skills folder; the MCP server ships summer_get_agent_playbook for in-chat guidance.
+- Skills: none. Copilot in JetBrains documents no skills folder; the MCP server ships summer_docs_search and summer_docs_read for in-chat guidance.
 - After: Restart the JetBrains IDE and open Copilot Chat in Agent mode; summer-engine shows in the tools list.
 
 Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/junie/README.md

@@ -6,7 +6,7 @@ is intentionally empty. Support is delivered at install time by
 
 - MCP config: `~/.junie/mcp/mcp.json`; Windows `%USERPROFILE%/.junie/mcp/mcp.json` (user); `.junie/mcp/mcp.json` (project).
   Shape: `mcpServers.summer-engine = { command, args }`.
-- Skills: none. Junie has no skills folder; put project guidance in .junie/guidelines.md. The MCP server ships summer_get_agent_playbook for in-chat guidance.
+- Skills: none. Junie has no skills folder; put project guidance in .junie/guidelines.md. The MCP server ships summer_docs_search and summer_docs_read for in-chat guidance.
 - After: Restart the JetBrains IDE so Junie reloads its MCP config.
 
 Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/lm-studio/README.md

@@ -6,7 +6,7 @@ is intentionally empty. Support is delivered at install time by
 
 - MCP config: `~/.lmstudio/mcp.json`; Windows `%USERPROFILE%/.lmstudio/mcp.json` (user); user scope only (project requests fall back with a warning).
   Shape: `mcpServers.summer-engine = { command, args }`.
-- Skills: none. LM Studio has no rules or skills folder. The MCP server ships summer_get_agent_playbook, so the model can pull Summer guidance in-chat.
+- Skills: none. LM Studio has no rules or skills folder. The MCP server ships summer_docs_search and summer_docs_read, so the model can pull Summer guidance in-chat.
 - After: Open LM Studio, toggle on the summer-engine MCP server in the Program tab, and raise the loaded model's context length to 32k or higher.
 
 Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/trae/README.md

@@ -6,7 +6,7 @@ is intentionally empty. Support is delivered at install time by
 
 - MCP config: `.trae/mcp.json` (project only; Trae manages user-level servers in its UI, so a user-scope request writes the project file with a warning).
   Shape: `mcpServers.summer-engine = { command, args }`.
-- Skills: none. Trae documents no skills folder; the MCP server ships summer_get_agent_playbook for in-chat guidance.
+- Skills: none. Trae documents no skills folder; the MCP server ships summer_docs_search and summer_docs_read for in-chat guidance.
 - After: Restart Trae and open the MCP settings; summer-engine should show as connected.
 
 Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/visual-studio/README.md

@@ -6,7 +6,7 @@ is intentionally empty. Support is delivered at install time by
 
 - MCP config: `~/.mcp.json`; Windows `%USERPROFILE%/.mcp.json` (user); `.mcp.json` (project).
   Shape: `servers.summer-engine = { type: "stdio", command, args }`.
-- Skills: none. Visual Studio's Copilot has no skills folder yet; the MCP server ships summer_get_agent_playbook for in-chat guidance.
+- Skills: none. Visual Studio's Copilot has no skills folder yet; the MCP server ships summer_docs_search and summer_docs_read for in-chat guidance.
 - After: Restart Visual Studio, open Copilot Chat in Agent mode, and enable summer-engine in the tools picker.
 
 Source of truth: `src/installer/agent-table.ts` (one row per agent).

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

@@ -2,6 +2,8 @@
 
 > Which Summer MCP tool to call. Skills reference tool names exactly as written here.
 
+**Operations.** Summer's cloud work is named by operation (`area.action`): `assets.generate_3d`, `jobs.wait`. A call written `area.action({...})` is one operation: use the tool `summer_area_action` when your client lists it, else `summer_call({ op: "area.action", input: {...} })`. `summer_search` finds any operation and its exact input. Engine tools keep their `summer_*` names below. Every answer has one shape: `done` with a `result`, `running` with a `job`, `needs_approval` with a link for the person, `dry_run` with a `preview`, or an `error` with a `code` and one `next` step. The person decides once what their agent may do: publishing (including `assets.make_public`), spending and building run at once by default, and deleting for good asks. An operation whose group they have not granted answers `needs_approval` with a link: give the link to the person, then `jobs.wait` on the `apr:` job.
+
 ## When to use Summer MCP vs. host tools
 
 **Use Summer MCP for** anything that needs the live editor or the engine's import pipeline:
@@ -35,7 +37,7 @@
 | `summer_get_scene_tree` | Read current scene graph. Always do this before mutating. |
 | `summer_open_main_scene` | Open the project's main scene. |
 | `summer_open_scene` | Open a specific `.tscn`. |
-| `summer_open` | Navigate for the user: open a summerengine.com page (billing, my games, pricing, an MCP guide) or an editor surface (scene, node, script, file, a dock) by intent name, or `print` the URL / op. Destinations: the `product-map` reference; when to use it: the `navigate-summer` skill. |
+| `studio.open` (3.x `summer_open`; through `summer_call`) | Navigate for the user: open a summerengine.com page (billing, my games, pricing, an MCP guide) or an editor surface (scene, node, script, file, a dock) by intent name (`target`), or `open: false` to get the URL / op only. Runs in the Summer MCP on this computer. Destinations: the `product-map` reference; when to use it: the `navigate-summer` skill. |
 | `summer_create_scene` | Create a new scene. |
 | `summer_instantiate_scene` | Add an existing scene or 3D model as a child node; `position` / `rotation_degrees` / `scale` (or `transform`) place it in the same call. |
 | `summer_inspect_node` | Read a single node's properties (about 5 KB). `fields` keeps only named properties/globs plus derived `transform`, `global_transform`, `scene_file_path`, `aabb`, `warnings` — e.g. `fields:['transform','global_transform','scene_file_path']`. |
@@ -198,47 +200,58 @@ Preview. One fast, read-only call that walks every node of a 3D scene and lists
 | `summer_get_debugger_warnings` | Runtime warnings from the debugger panel. |
 | `summer_get_script_errors` | Script compilation errors. |
 
-### Asset library (8)
+### Asset library (6)
 
-| Tool | Use |
+| Tool or operation | Use |
 |---|---|
-| `summer_search_assets` | Free public asset search (community library + user's own). Sources: `library`, `community`, `my_assets`, `all`. `style` keeps one art direction (realistic, stylized-lowpoly, toon, pixel, hand-painted, voxel); `preview` returns a numbered picture of the first 9 results; curated packs first unless `includeCommunity`. |
-| `summer_list_my_assets` | List/search the signed-in user's generated and uploaded assets. Empty query lists recent assets. |
-| `summer_get_asset` | Fetch one exact asset by ID with file URL, download URL, viewer URL, metadata, license, and visibility. |
-| `summer_get_asset_download_url` | Get the primary or thumbnail download URL for a specific asset. Stable shape for future signed URLs. |
+| `assets.search` | Free asset search: `query`, `scope` (`library` = the public Summer library, the default; `mine` = the person's own generated and uploaded assets, where an empty query lists the newest; `all`), `assetType` (`2d_image`, `animation`, `3d_model`, `audio`, `music`, `all`), `style` (realistic, stylized-lowpoly, toon, pixel, hand-painted, voxel: keeps one art direction), `limit` (at most 20), `cursor`. Answers `items` (`assetId`, `title`, `type`, `source`, `fileUrl`, `thumbnailUrl`, `format`, `license`) and `nextCursor`. There is no picture preview of the results and no community toggle. |
+| `assets.get` | One exact asset by `assetId`: `fileUrl`, `downloadUrl`, `viewerUrl`, `status` (`expired`: regenerate it), file name, type and size, visibility, license, tags and `parentAssetId`. |
 | `summer_import_asset` | Search, choose the top match, download, run the engine import, and optionally instantiate 3D models. |
 | `summer_import_asset_by_id` | Import one exact Summer asset ID. Use after generation jobs or when the user selects a specific asset. |
 | `summer_import_hdri` | Search Poly Haven's CC0 HDRIs (public API, no Summer login), import the `.hdr`/`.exr` into `res://sky/`, and get the exact `summer_run_script` snippet that wires it as the WorldEnvironment sky. |
-| `summer_slice_asset_sheet` | Detect and crop every distinct asset from a generated sheet image into named individual assets (works without the engine; import the results afterwards). |
+| `assets.slice_sheet` | Detect and crop every distinct item of a sheet image the person owns: `slices` with `url`, `name`, `category`, `bbox` (works without the engine; import the URLs afterwards with `summer_import_from_url_batch`). Spends credits. |
 
-### Asset generation (7 — metered)
+### Asset generation (metered)
 
-| Tool | Use |
+Each spends the person's credits. `dryRun: true` returns `preview.estimate` (`credits`, `balance`, `enough`) and makes nothing; never quote prices. Model lists are the enums in each operation's input (`summer_search` returns it).
+
+| Operation | Use |
+|---|---|
+| `assets.generate_image` | Draw or edit an image: `prompt`, `model`, `style`, `aspectRatio`, `width` + `height` (minimum size), `numImages`, `referenceImageUrl` (edit), `removeBackground`, `seed`. Answers `assets` (`assetId`, `fileUrl`, real `width`/`height`). |
+| `assets.generate_3d` | Text-, image- or multi-view-to-3D, optionally rigged and animated: `kind`, `prompt`, `imageUrl` / `imageUrls`, `model`, `rig`, `animationNames`, `targetPolycount`, `topology`. **Always a job.** |
+| `assets.generate_audio` | Speech, sound effect, music or dialogue: `capability`, `text` / `prompt` / `inputs`, `voiceId` (a game-cast voice), `modelId`, `durationSeconds`, `loop`, `voiceSettings`. Sound effects without `modelId` use the person's approved default. |
+| `assets.generate_sfx_choices` | One sound effect from 2-4 models, shown on a Summer Studio page where the person approves one or more. Answers `choiceSetId` and `reviewUrl`. |
+| `assets.choices` | Read the person's picks for a choice set (`approved`, `note`, `audioUrl`, `assetId`); `waitSeconds` waits for them. Free. |
+| `assets.generate_video` | Text- or image-to-video: `prompt`, `imageUrl`, `model`, `duration`, `aspectRatio`, `resolution`, `negativePrompt`. **Always a job.** |
+| `assets.generate_motion` | Animate a rigged model: `rigAssetId`, `backend`, `motionNames` (library) or `prompts` (text to motion). **Always a job**, except clips the rig already has (`reused`). |
+| `makers.<tool>` | One-shot recipes (MCP names `summer_tool_<tool>`): `makers.npc_voice`, `makers.trailer_forge`, ... `summer_search` lists them with their input. |
+
+### Your assets
+
+| Operation | Use |
 |---|---|
-| `summer_generate_image` | AI image gen. |
-| `summer_generate_3d` | Image-to-3D. |
-| `summer_generate_audio` | SFX / music gen. Sound effects: `modelId` picks ElevenLabs SFX v2, Sonilo SFX 1.1 or Stable Audio 3 SFX; omitted = the person's approved default. |
-| `summer_generate_sfx_choices` | One sound effect from several models, shown on a Summer Studio page where the person approves one or more. |
-| `summer_get_choices` | Read which sound-effect versions the person approved (audioUrl, assetId, note). |
-| `summer_generate_video` | Video gen. |
-| `summer_generate_motion` | Generate/apply 3D skeletal motion from a rigged asset. |
+| `assets.remove_background` | Transparent copies of up to 8 of the person's images (originals stay). Spends credits. |
+| `assets.update` | Title, description, tags, and `private` or `team` visibility. To list an asset for everyone, `assets.make_public`. |
+| `assets.make_public` | Lists one of the person's assets for everyone in Summer's asset store (publishing). Runs at once when the person lets their agent publish (the default), else answers `needs_approval` with a link. |
+| `assets.delete` | Deletes one of their assets for good. Asks the person unless they let their agent delete: it answers `needs_approval` with a link, and nothing is deleted until they confirm. |
+| `assets.upload_begin` → `assets.upload_complete` | Upload a PNG/JPEG/WebP from disk: a signed form to POST the file to, then the confirm step that makes the asset. |
 
-### Job tracking (2)
+### Jobs and batches
 
 | Tool | Use |
 |---|---|
-| `summer_check_job` | Poll a generation job. |
+| `jobs.wait` | Wait up to `timeoutSeconds` (at most 50) for a job from any operation that answered `running` or `needs_approval`; call again until `finished`. The finished job's `result` holds the asset ids. `jobs.get` reads it once. |
 | `summer_batch` | Run multiple ops as a transaction. `InstantiateScene` ops may carry `position` / `rotation_degrees` / `scale` / `transform`; `receipt: "summary"` returns counts, failures with op index and created paths under 5 KB. A `ReparentNode` keeps the moved node's scene-owned children and grandchildren (the engine op drops them from the saved file) and is verified from the saved `.tscn` (`persisted:true` / `verified:true`, else `failure_reason: not_persisted`); a raw `ConnectSignal` is refused — use `summer_connect_signal`. `scenePersistence.saved` only means the SaveScene ran. |
 
 ### Meta (5)
 
 | Tool | Use |
 |---|---|
-| `summer_start_game_task` | Route a user goal into the right workflow, skills, MCP tool groups, asset policy, gates, and verification path. |
-| `summer_get_studio_workflow` | Discover Summer Studio's guided workflow recipes (starter prompts, ordered steps, required tools) for a goal. |
+| `summer_call` `{"op":"docs.plan"}` | Route a user goal into the right workflow, skills, MCP tool groups, asset policy, gates, and verification path. Shell: `summer plan "<goal>"`. (3.x: `summer_start_game_task`.) |
+| `summer_call` `{"op":"docs.workflows"}` | Discover Summer Studio's guided workflow recipes (starter prompts, ordered steps, required tools) for a goal. (3.x: `summer_get_studio_workflow`.) |
 | `summer_get_project_context` | Project, scene, and `.summer` memory summary — call at start of session. Binds the session to the open project and surfaces a `capabilitySkewWarning` when the engine build and CLI have drifted; tools whose op the engine provably lacks return a structured `engine_lacks_op` result instead of running. Compact by default (a few KB: `sceneSummary`, scalar `health` with capability counts); `include:['scene_tree','capabilities','settings']` adds the heavy blocks, `omitted` says how. |
-| `summer_get_agent_playbook` | Daily operating contract (observe-first loop, content routing, invariants, verification ritual) — call at start of session. Also served natively as the `summer_agent_playbook` MCP prompt. |
-| `summer_get_board` | Read the person's approved planning board (look, characters, place, storyboard, picks), with the look and picked cards as images to compare screenshots against. Needs the project id from the build brief; works without the engine. |
+| `summer_call` `{"op":"summer_get_agent_playbook"}` | Daily operating contract (observe-first loop, content routing, invariants, verification ritual) — read at start of session. Also served natively as the `summer_agent_playbook` MCP prompt. |
+| `plans.get` (3.x `summer_get_board`) | Read the person's game plan (look, characters, place, storyboard, picks): every item with its id, picture URL and revision, to compare screenshots against. `projects.get({ projectId })` gives the project's `planId` from the project id in the build brief; works without the engine. |
 
 ### Creator platform (4)
 
@@ -246,51 +259,64 @@ Preview. One fast, read-only call that walks every node of a 3D scene and lists
 |---|---|
 | `summer_export_game` | Export the game in the file the Summer Games store takes, headless (no window), no running editor needed. `format:"bundle"` (default): the `summer.games` `.zip` the Summer apps run; `targets` picks `ios`, `android`, `macos`, `windows` (a game without a server: phones only) through a named `summer.games <targets>` preset in `export_presets.cfg`. `format:"download"` with one target: `web` (HTML5 `.zip` on Summer's WebGPU Forward+ template; refuses Compatibility projects), `macos` (ad hoc signed `.app` zip, `macos-universal`) or `windows` (`.exe` with embedded pack, zipped, `windows-x64`). Returns path, sha256, size, bundle manifest or store platform, warnings. |
 | `summer_export_templates` | `list` or `install` export templates from Summer's CDN (`downloads.summer.games/engine-templates/<summerVersion>/manifest.json`) into the engine's user template folder (`<data>/Godot/export_templates/<FULL_CONFIG>/`), sha256-checked. Only download exports need them; store bundles need none. `summerVersion` is read on macOS, passed elsewhere. |
-| `summer_publish_build` | Upload that `.zip` to the creator's game through Studio's store upload: confirm-gated preview first, then declare, part upload from disk, seal, wait for the Build, name its client pack; `publish:true` also approves it. Needs `summer login --store`; a retry with the same file and version continues the same upload. |
+| `store.upload_file` (3.x `summer_publish_build`; through `summer_call`) | Upload that `.zip` to the creator's game through Studio's store upload: confirm-gated preview first, then declare, part upload from disk, seal, wait for the Build; `publish:true` also approves it. Needs `summer login --store`; a retry with the same file and version continues the same upload. Without a shell, `store.upload_begin`, `store.upload_sign_parts` and `store.upload_complete` take the bytes in parts. |
 | `summer_capture_gameplay` | Real gameplay frames without a running editor: starts the game (main scene or `scene`) in the engine's offscreen verify instance (`--summer-verify`, real renderer, window parked offscreen, no focus) (`--summer-offscreen`) at `resolution` (default `1920x1080`), waits `waitSeconds`, runs `steps` (`press` a button by text, `key`, `action`, `click`, `drag`, `wait`, `shot`), saves `frames` PNGs (HUD included; with a `shot` step, one per shot) to `<project>/.summer/captures/<time>/`. `args` are the game's own flags, passed after `--` (e.g. `["--autostart"]` to skip the title screen). Imports the project first when `.godot/` is missing. Returns each path with its real width and height; warns when the stretch settings render another size. For store screenshots. |
 
+### Hosted store, publishing and Grow tools
+
+These come from the hosted Summer server (the one ChatGPT and Claude connect to) and are mounted into the local MCP after `summer login`; `summer tool <name>` reaches them too.
+
+- **Store page:** `summer_store_list_games`, `summer_store_create_game`, `summer_store_get_listing` (the page, the checklist and `availableTags`), `summer_store_update_listing` (text, tags, long description, support contact, release date, content rating), `summer_store_set_art`, `summer_store_set_trailer`, `summer_store_set_sound`, `summer_store_preview_link`, `summer_store_jams` and `summer_store_enter_jam`.
+- **Builds and release:** `summer_build_begin_upload` / `_sign_parts` / `_complete_upload` / `_status` (the local `summer_publish_build` does these from disk), `summer_store_version_*` for web and native downloads, `summer_store_submit` (one approval link for the owner), `summer_store_cancel_submission`, `summer_store_review`, `summer_store_releases`, `summer_build_release`.
+- **Grow:** `summer_grow_overview` and `summer_grow_analytics` (store page views, launches, play sessions, play time, custom events), `summer_grow_event_catalog`, `summer_grow_event_trend`, `summer_grow_event_funnel`, `summer_grow_members`, `summer_grow_ab_tests`, `summer_grow_prices`, `summer_grow_event_limit`, `summer_grow_apply` and `summer_grow_applications`.
+- **Guides:** the `publish-your-game`, `store-listing`, `store-art` and `grow-analytics` skills (`summer_docs_read`).
+
 ### Library search (2)
 
 | Tool | Use |
 |---|---|
-| `summer_search_library` | Search the library (skills, tools, templates, references, examples, collections) by describing the task in plain words; ranked ids with `matched_by` (lexical / semantic). The first move for any task; works without the engine. |
-| `summer_read_library` | Load one entry by id: a skill's SKILL.md plus metadata, a tool's call recipe, a template's pin, a reference's body. A body ends with its relative links and the id that loads each; a linked file loads by `<entry id>/<link as written>` (e.g. `skill/spatial-placement/references/kit-placement-tools.md`). The last line is the `entry_id` footer to report through `summer_library_feedback`. |
+| `summer_docs_search` | Search the library (skills, tools, templates, references, examples, collections) by describing the task in plain words; ranked ids with `matched_by` (lexical / semantic). The first move for any task; works without the engine. |
+| `summer_docs_read` | Load one entry by id: a skill's SKILL.md plus metadata, a tool's call recipe, a template's pin, a reference's body. A body ends with its relative links and the id that loads each; a linked file loads by `<entry id>/<link as written>` (e.g. `skill/spatial-placement/references/kit-placement-tools.md`). The last line is the `entry_id` footer to report through `docs.feedback`. |
 
 ### Library feedback (1)
 
 | Tool | Use |
 |---|---|
-| `summer_library_feedback` | Report library-entry outcomes (worked/wrong/outdated/...) so entries get fixed and re-ranked. Fire-and-forget with a 1s cap; enum-first schema with no field for project files, chat content, or code; honors `SUMMER_NO_TELEMETRY=1` and `DO_NOT_TRACK=1`. |
+| `summer_call` `{"op":"docs.feedback"}` | Report library-entry outcomes (worked/wrong/outdated/...) so entries get fixed and re-ranked. Fire-and-forget with a 1s cap; enum-first schema with no field for project files, chat content, or code; honors `SUMMER_NO_TELEMETRY=1` and `DO_NOT_TRACK=1`. |
 
-### Summer Apps (13)
+### Summer Apps
 
-Team tools inside Summer Studio that agents build: shared, live on the team's data and engine. Load the `summer-apps` and `summer-apps-design` skills first.
+Team tools inside Summer Studio that agents build: shared, live on the team's data and engine. Load the `summer-apps` and `summer-apps-design` skills first. A call written `apps.action({...})` is the tool `summer_apps_action` when your client lists it, else `summer_call({ op: "apps.action", input: {...} })`.
 
-| Tool | Use |
+| Operation | Use |
 |---|---|
-| `summer_app_guide` | The build guide: when to build, Layout vs code, build loop, manifest, SDK, UI kit, layout format, design rules, worked examples. |
-| `summer_app_list` | The apps in the person's workspaces. |
-| `summer_app_create` | New scratch app; the person's Studio tab opens it. |
-| `summer_app_publish` | New immutable version from a local `dir`, `files` or a `layout`, plus the manifest. |
-| `summer_app_get` | Manifest, current files and a data summary. |
-| `summer_app_update` | Rename, move to a folder, keep, archive or restore an app. |
-| `summer_app_events` | Long-poll (up to 50 s) what the app sends agents, errors, feedback and tool calls. |
-| `summer_app_page` | Read, fill and press the open app's declared fields and buttons. |
-| `summer_app_screenshot` | See the app without the person: a headless, read-only render (PNG) with console, errors, refused calls and the declared page; `width` 390 for a phone, `theme` dark, `out` saves the PNG. |
-| `summer_app_data` | Read or write the app's shared collections; no app needs to be open, the team sees writes live. |
-| `summer_app_tools` | The app's declared agent tools. |
-| `summer_app_call` | Run an agent tool inside the person's open app; `app_not_open` otherwise. |
-| `summer_app_report_gap` | Report an SDK capability an app needed and did not have. |
-| `summer_app_dock` | Dock an app in the editor (left, right, bottom), close it, list docks; `engine_lacks_op` on engines without app docks. |
+| `apps.guide` | The build guide by `section`: when to build, Layout vs code, build loop, manifest, SDK, UI kit, layout format, design rules, worked examples. |
+| `apps.list` | The apps in the person's workspaces (`workspaceId`, `q`, `limit`, `cursor`). |
+| `apps.create` | New scratch app; the person's Studio tab opens it. |
+| `apps.publish` | New immutable version from `files` (`{ path, content, encoding }`, `index.html` at the root) or a `layout`, plus the `manifest`. |
+| `apps.get` | Manifest, current files and a data summary. |
+| `apps.update` | Rename, move to a folder, keep, archive, restore or pin an app (`name`, `folder`, `status`, `pinned`). |
+| `apps.duplicate` / `apps.add_starter` | Copy an app (to another team too); add one of Summer's starter apps to a team. |
+| `apps.delete` | Delete an app for good. Asks the person: answers `needs_approval` with a link. |
+| `apps.rollback` / `apps.update_starter` | Make an older version the live one; update a changed starter app to the newest starter. Each asks the app's owner (`needs_approval` with a link). |
+| `apps.events` | Long-poll (up to 50 s) what the app sends agents, errors, feedback and tool calls; pass the `cursor` back as `after`. |
+| `apps.page` / `apps.use_page` | Read the open app's declared fields and buttons; fill (`fill`) and press (`press`) them. Critical ones are the person's. |
+| `apps.screenshot` | See the app without the person: a headless, read-only render (the picture) with console, errors, refused calls and the declared page; `width` 390 for a phone, `theme` dark. |
+| `apps.read_data` / `apps.write_data` | Read (`items`, `nextCursor`) or write (`ops`, up to 100) the app's shared collections; no app needs to be open, the team sees writes live. |
+| `apps.tools` | The app's declared agent tools and collections. |
+| `apps.call` | Run an agent tool inside the person's open app; a `conflict` error with the app's link when it is not open. |
+| `apps.feedback` | Tell the app's makers it works (`thumbs: "up"`) or needs work, with a `note`. |
+| `apps.report_gap` | Report an SDK capability an app needed and did not have. |
+| `apps.dock` (3.x `summer_app_dock`; through `summer_call`) | Dock an app in the editor (left, right, bottom), close it, list docks; runs in the Summer MCP on this computer; `engine_lacks_op` on engines without app docks. |
 | `summer_enable_plugin` | Enable an editor plugin (`res://addons/<name>/`) and get the real load result (`enabled`, autoloads, or a failure `code`); older engines answer `queued: true, enabled: null` instead of claiming success. |
 
 ## Common pattern
 
 Every scene-touching skill should follow this loop:
 
-1. `summer_start_game_task` — route the goal into skills/tools/gates.
+1. `summer_call` `{"op":"docs.plan","input":{"goal":"..."}}` — route the goal into skills/tools/gates.
 2. `summer_get_project_context` — orient.
-3. `summer_get_agent_playbook` — read the rules.
+3. `summer_call` `{"op":"summer_get_agent_playbook"}` — read the rules.
 4. Resolve the exact `res://` scene path; open it only for an intentional current-tab read/UI action.
 5. Pass that `scenePath` to mutations (`summer_add_node`, `summer_set_prop`, `summer_connect_signal`, ...).
 6. Mutation tools append one final `SaveScene`; use `summer_save_scene` directly only for a standalone save/save-as.
@@ -306,12 +332,14 @@ Read big things in parts, never whole:
 
 Every asset-generation skill should follow this loop:
 
-1. `summer_search_assets` or `summer_list_my_assets` — reuse before generating when reasonable.
-2. `summer_generate_image` / `summer_generate_3d` / `summer_generate_audio` — metered creation.
-3. `summer_check_job` if the generation was async.
-4. `summer_get_asset` — resolve the returned `assetId`, `rigAssetId`, or `animationAssetId`.
+1. `assets.search` (`scope: "all"`, or `"mine"` for the person's own) — reuse before generating when reasonable.
+2. `assets.generate_image` / `assets.generate_3d` / `assets.generate_audio` — metered creation (`dryRun: true` first when the person should see the credits).
+3. `jobs.wait` when the answer was `running` (3D, video, animation), until the job is finished.
+4. `assets.get` — resolve the returned `assetId`, `rigAssetId`, or `animationAssetId`.
 5. `summer_import_asset_by_id` — import the exact result through the engine's import pipeline.
-6. `summer_get_asset_download_url` — only when the user explicitly wants a downloadable file/link.
+6. The `downloadUrl` from `assets.get` — only when the user explicitly wants a downloadable file/link.
+
+`whoami()` shows the signed-in account: plan, `credits` (their balance) and whether generation is unlocked.
 
 ## summer_set_resource_property — nested properties
 

package/library/references/mcp-tools-reference/resource.yaml

@@ -1,6 +1,6 @@
 id: reference/mcp-tools-reference
 kind: reference
-version: 1.4.1
+version: 1.4.2
 summary: Canonical reference for which Summer MCP tool to call — skills should reference tool names exactly as written here.
 use_when:
   - choosing between Summer MCP tools and host tools for an operation

package/library/references/product-map/resource.yaml

@@ -4,10 +4,10 @@ version: 1.0.0
 summary: The product map — every summerengine.com page and editor surface an agent can open for the user, with intent phrases, URL or op, required context, and status.
 use_when:
   - resolving where a user intent lives — "where do I change my plan", "where are my published games", "how do I get to the MCP guide for Codex"
-  - deciding whether a destination needs login, a running engine, or a parameter (gameId, path, node) before calling summer_open
+  - deciding whether a destination needs login, a running engine, or a parameter (gameId, path, node) before calling studio.open (3.x `summer_open`)
   - checking whether an editor surface (assistant dock, project settings, 2D/3D switch) can be opened on this engine build or is still planned
 do_not_use_when:
-  - you already know the target id — call summer_open directly (the tool carries the same table)
+  - you already know the target id — call studio.open directly (it carries the same table)
   - looking up which Summer MCP tool performs a change — that is the mcp-tools-reference
 facets:
   lifecycle: