summer-engine 3.7.0 → 4.0.0

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

@@ -268,42 +268,31 @@ The full read is about 5 KB. To read only what you need, pass fields: property n
 Two forms, pass exactly one:
 - path: a resource FILE ('res://materials/ground.tres', a mesh 'res://kit/meshes/wall_01.res', 'res://models/player.glb'), loaded read-only in the editor. A Mesh returns its AABB, surface_count and per surface the primitive, vertex and index counts, attributes, triangles and material (class, path or embedded, albedo for standard materials), plus the unique materials and blend shapes. A scene or model (.tscn/.glb/.gltf) returns its node count, the first 40 nodes with type, instanced scene and mesh, and its meshes; summer_inspect_asset measures it (AABB, planes, ports). Every other resource (and a mesh) returns its editor properties that differ from the class default (props), with props_at_default counting the rest.
 - nodePath + property: a resource a node of the ACTIVE scene tab holds, e.g. nodePath 'Floor', property 'mesh'. For example, summer_inspect_node tells you a MeshInstance3D has a "StandardMaterial3D" material_override — this form returns its albedo_color, metallic, roughness, etc.`, inspectResourceInputShape, async (args) => withEngine(async (client) => inspectResource(client, args)));
-    server.tool("summer_batch", `Execute multiple operations in a single call. Each op is forwarded to the engine VERBATIM, so this is also how you reach engine ops that have no dedicated tool.
+    server.tool("summer_batch", `Execute multiple operations (a multi-node build) in a single call. Each op is forwarded to the engine VERBATIM: this is also how you reach engine ops without a dedicated tool.
 
-UNDO: when nothing in the list forces a split (see the single-op contract below), the whole batch is ONE undo step — the user undoes everything with a single Ctrl+Z. When single-only ops are present the list is split into sequential requests and EACH chunk is its own undo step (one Ctrl+Z per chunk; the receipt shows the chunks). Use this when building something that involves multiple nodes and properties — e.g., creating a player character with collision, camera, and properties.
+UNDO: when nothing in the list forces a split (see SPLITS), the whole batch is ONE undo step (one Ctrl+Z). Single-only ops split the list into sequential requests, and EACH chunk is its own undo step (the receipt shows the chunks).
 
-Each op in the array uses the same format as the individual tools:
+Ops use the individual tools' format:
 - {"op": "AddNode", "parent": "/", "type": "MeshInstance3D", "name": "Floor"}
 - {"op": "SetProp", "path": "Floor", "key": "position", "value": "Vector3(0, -1, 0)"}
 - {"op": "SetProp", "path": "Floor", "key": "mesh", "value": "PlaneMesh"}
 - {"op": "SetResourceProperty", "nodePath": "Floor", "resourceProperty": "mesh", "subProperty": "size", "value": "Vector2(20, 20)"}
 
-RAW RUNTIME OPS (interactive verification — structured failure_reason passes through verbatim):
-- RunVerification — spawn a hidden, disposable game instance that runs a GDScript probe and dies (never touches the editor): {"op": "RunVerification", "probe_source": "...", "max_seconds": 20}. Returns {ok, results, frames, out_dir}. Probe API: report(name, value) / save_frame(name) / press(action) / key(keycode) / finish(). save_frame REQUIRES a name argument — save_frame() with no args is a script error. Mount scenes deferred: get_tree().root.add_child.call_deferred(instance); await get_tree().process_frame; await settle() — a direct add_child in _ready can hit the parent-busy guard and capture a black frame.
-- SimulateInput — inject an action/key/mouse/axis into the RUNNING game (summer_play first): {"op": "SimulateInput", "type": "action", "action": "jump", "pressed": true}. It MUST be sent alone (single-op batch). failure_reason "not_running" = start the game first; "unsupported" = the running game build predates the handler — fall back to RunVerification or ask the user.
+SPLITS AND SAVE: scenePath selects every mutation target. Send OpenScene (a UI action) separately, never mixed with scene mutations. The tool appends one final SaveScene when the batch mutates a scene; a SaveScene you supply must appear exactly once, as the final op. The engine requires SaveScene, InstantiateScene, ReplaceNode, SimulateInput, the runtime reads (GetRuntimeSceneTree/GetRuntimeNode) and the Run*/Import* ops to travel alone, so the tool splits the list around them; if a later chunk fails, the receipt names the earlier ops that already applied.
 
-A raw ReplaceNode with scene is refused (it saves the old scene reference); use summer_replace_node.
-A raw ConnectSignal is refused (the engine connects without CONNECT_PERSIST, so the file never holds it); use summer_connect_signal.
+RAW RUNTIME OPS (structured failure_reason passes through verbatim):
+- RunVerification: a hidden, disposable game instance runs a GDScript probe and dies, never touching the editor: {"op": "RunVerification", "probe_source": "...", "max_seconds": 20} returns {ok, results, frames, out_dir}. Probe API: report(name, value) / save_frame(name) / press(action) / key(keycode) / finish(); save_frame() without a name is a script error. Mount scenes deferred (add_child.call_deferred) or the capture can be black; summer_get_agent_playbook has the probe rules.
+- SimulateInput: inject an action/key/mouse/axis into the RUNNING game (summer_play first), sent ALONE: {"op": "SimulateInput", "type": "action", "action": "jump", "pressed": true}. failure_reason "not_running" = start the game first; "unsupported" = the game build predates the handler: use RunVerification or ask the user.
 
-REPARENTNODE KEEPS ITS SUBTREE AND IS VERIFIED: the engine's ReparentNode re-owns only the moved node, so its children and grandchildren were dropped from the saved file. A batch with ReparentNode saves first, reads the saved .tscn, sends each ReparentNode in its own request with an in-place ReparentNode (same parent, same index) per scene-owned descendant to give it back to the scene, then reads the saved file again: persisted:true / verified:true only when every moved node and descendant is at its new path; otherwise an error with failure_reason not_persisted. A move onto a parent that already has a child of that name is refused (failure_reason name_collision). The scenePath must be a .tscn, and Undo cannot share the batch.
+REFUSED: a raw ReplaceNode with scene (it saves the old scene reference; use summer_replace_node) and a raw ConnectSignal (no CONNECT_PERSIST, so the file never holds it; use summer_connect_signal).
 
-Do not mix OpenScene with scene mutations in one batch. OpenScene is a UI action;
-send it separately. scenePath selects every mutation target. The tool appends one
-final SaveScene when the batch mutates a scene; if supplied explicitly, SaveScene
-must appear exactly once and be the final operation. The engine requires
-SaveScene, InstantiateScene, ReplaceNode, SimulateInput, the runtime reads
-(GetRuntimeSceneTree/GetRuntimeNode), and the Run*/Import*
-ops to travel as their own request, so this tool automatically splits your op
-list into sequential requests around them — each split chunk is its own undo
-step (NOT one step for the whole batch), and if a later chunk fails the receipt
-reports exactly which earlier ops already applied.
+REPARENTNODE KEEPS ITS SUBTREE AND IS VERIFIED: the engine op re-owns only the moved node and drops its descendants from the saved file, so the tool saves, sends each ReparentNode alone plus an in-place ReparentNode per scene-owned descendant, then reads the saved .tscn back: persisted:true / verified:true only when every moved node and descendant is at its new path, else failure_reason not_persisted. A move onto a parent with a same-named child is refused (name_collision). scenePath must be a .tscn; Undo cannot share the batch.
 
-PLACED INSTANCES: an InstantiateScene op may also carry position, rotation_degrees, scale ([x, y, z] or "Vector3(...)") or transform ("Transform3D(...)"); the tool sets them on the created node. One op per piece. Other ops are forwarded verbatim. Cost: each InstantiateScene is its own engine request (the engine requires it); the transforms of a run of InstantiateScene ops are then sent together (up to 200 per request) before the next other op, so N placed pieces plus the save cost about N + 2 requests and N + 2 undo steps. Every later op (a SetProp, SnapToSurface, the save) sees the pieces already placed; if an InstantiateScene fails, the pieces created before it still get their transforms.
+PLACED INSTANCES: an InstantiateScene op may carry position, rotation_degrees, scale ([x, y, z] or "Vector3(...)") or transform ("Transform3D(...)"), set on the created node; one op per piece. Each InstantiateScene is its own request and the transforms of a run follow together (up to 200 per request), so N pieces plus the save cost about N + 2 requests and undo steps. Later ops (SetProp, SnapToSurface, the save) see the pieces placed; if one fails, the pieces before it still get their transforms.
 
-RECEIPTS: receipt "summary" returns only counts, failures [{index, op, error}] (index = position in your ops list), created node paths and renames, under 5 KB with any cut declared. Use it for any batch over a few ops; the full receipt of a large batch overflows the tool-output limit.
+RECEIPTS: receipt "summary" returns only counts, failures [{index, op, error}] (index into your ops), created node paths and renames, under 5 KB with any cut declared. Use it for any batch over a few ops: a large full receipt overflows the tool-output limit.
 
-scenePersistence.saved means the SaveScene ran; it does not prove what the file
-holds. verified:true is set only where the tool read the saved file back.`, {
+scenePersistence.saved means the SaveScene ran, not what the file holds; verified:true is set only where the tool read the file back.`, {
         scenePath: z.string().optional().describe("Required when ops contains scene mutations; exact res:// target scene path"),
         ops: z.array(z.record(z.unknown())).describe("Array of operation objects, each with 'op' plus its parameters"),
         receipt: z

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.7.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/",
@@ -113,6 +105,9 @@
     "./library/skills/store-art/",
     "./library/skills/store-listing/",
     "./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/",
@@ -145,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).