summer-engine 3.8.0 → 4.2.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/dist/project-memory/agent-instructions.d.ts

@@ -0,0 +1,47 @@
+/**
+ * AGENTS.md and CLAUDE.md in a Summer project. AGENTS.md is the one file
+ * Codex, Cursor, Copilot, Amp and other agents read in every session;
+ * Claude Code reads CLAUDE.md, which here only imports AGENTS.md.
+ * `summer create` writes both; `summer setup --yes` inside a project adds
+ * them when missing.
+ *
+ * An existing file is never overwritten: Summer adds one marked block once,
+ * and later runs replace only that block. A link is followed only to a file
+ * inside the project, and a CLAUDE.md that is the same file as AGENTS.md
+ * gets the AGENTS.md block only. The five commands are the list in the
+ * summer-cli skill (between its project-commands markers), so the two
+ * cannot drift; the skill's test runs every command both of them teach.
+ */
+export declare const SUMMER_BLOCK_START = "<!-- summer-engine:start. summer setup updates only this block; write your own notes outside it. -->";
+export declare const SUMMER_BLOCK_END = "<!-- summer-engine:end -->";
+/** The numbered command list from the summer-cli skill. */
+export declare function projectCommands(skill?: string): string;
+/** The Summer block of AGENTS.md, markers included. */
+export declare function renderAgentsBlock(commands?: string): string;
+export type InstructionAction = "created" | "added" | "updated" | "unchanged" | "skipped";
+export interface InstructionFileResult {
+    file: "AGENTS.md" | "CLAUDE.md";
+    path: string;
+    action: InstructionAction;
+    /** Why a file was skipped or left as it is. */
+    reason?: string;
+}
+/**
+ * Write or update AGENTS.md and CLAUDE.md in the project root. A new
+ * AGENTS.md is the Summer block; a new CLAUDE.md is `@AGENTS.md` only. An
+ * existing CLAUDE.md that already imports AGENTS.md is left as it is. Each
+ * file is its own step: a file that cannot be read or written is skipped
+ * with the reason, and the other is still done.
+ */
+export declare function writeAgentInstructions(projectDir: string, options?: {
+    dryRun?: boolean;
+    block?: string;
+}): InstructionFileResult[];
+/**
+ * The Summer project the working directory is in, for `summer setup`: the
+ * nearest folder with project.godot, looking up no further than the git
+ * top level, and never the home folder or the filesystem root (a stray
+ * project.godot there must not put an AGENTS.md or CLAUDE.md in every
+ * session). Null when there is none.
+ */
+export declare function findSetupProjectRoot(cwd?: string): string | null;

package/dist/project-memory/agent-instructions.js

@@ -0,0 +1,226 @@
+import { existsSync, lstatSync, readFileSync, readlinkSync, realpathSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { basename, dirname, join, parse, relative, resolve, isAbsolute } from "path";
+import { PACKAGE_ROOT } from "../core/package-root.js";
+/**
+ * AGENTS.md and CLAUDE.md in a Summer project. AGENTS.md is the one file
+ * Codex, Cursor, Copilot, Amp and other agents read in every session;
+ * Claude Code reads CLAUDE.md, which here only imports AGENTS.md.
+ * `summer create` writes both; `summer setup --yes` inside a project adds
+ * them when missing.
+ *
+ * An existing file is never overwritten: Summer adds one marked block once,
+ * and later runs replace only that block. A link is followed only to a file
+ * inside the project, and a CLAUDE.md that is the same file as AGENTS.md
+ * gets the AGENTS.md block only. The five commands are the list in the
+ * summer-cli skill (between its project-commands markers), so the two
+ * cannot drift; the skill's test runs every command both of them teach.
+ */
+export const SUMMER_BLOCK_START = "<!-- summer-engine:start. summer setup updates only this block; write your own notes outside it. -->";
+export const SUMMER_BLOCK_END = "<!-- summer-engine:end -->";
+const CLAUDE_IMPORTS = new Set(["@AGENTS.md", "@./AGENTS.md"]);
+const SKILL_PATH = ["library", "skills", "summer-cli", "SKILL.md"];
+const COMMANDS = /<!-- project-commands[^>]*-->\n([\s\S]*?)\n<!-- \/project-commands -->/;
+/** The numbered command list from the summer-cli skill. */
+export function projectCommands(skill = readFileSync(join(PACKAGE_ROOT, ...SKILL_PATH), "utf-8")) {
+    const match = COMMANDS.exec(skill);
+    if (!match)
+        throw new Error("The summer-cli skill has no project-commands list.");
+    return match[1].trim();
+}
+/** The Summer block of AGENTS.md, markers included. */
+export function renderAgentsBlock(commands = projectCommands()) {
+    return [
+        SUMMER_BLOCK_START,
+        "# Summer Engine game",
+        "",
+        "This is a game made with Summer Engine, the game engine built for AI. Game code is GDScript (`.gd`), scenes are `.tscn`, resources are `.tres`, and `project.godot` is the project file.",
+        "",
+        "## How to work on it",
+        "",
+        "- Change scenes through Summer while Summer Engine has the project open. The editor rewrites `.tscn` files when it saves, so hand edits get lost.",
+        "- With Summer's MCP server, call the `summer_*` tools and start with `summer_get_project_context`. Without it, run the same operations as `summer` commands in the shell (the `summer-cli` skill). If `summer` is missing or older than 4.0, use `npx -y summer-engine@latest` in its place.",
+        "- Summer's skills teach each part of a game. `npx -y summer-engine@latest setup <agent> --yes` installs them for your agent (add `--cli` for no MCP server). Start with `using-summer`, and find the right one with `summer docs search --query \"<the task>\"`.",
+        "- `.summer/` is the project's memory: `GameSoul.md` says what the game is, `memory/` holds the decisions to keep. Read them before you change the game's look, sound or story.",
+        "- Check your own work: script errors, a screenshot, a play run. Ask the person to play only for feel and fun.",
+        "",
+        "## The five commands",
+        "",
+        commands,
+        "",
+        "## Publishing",
+        "",
+        "The `publish-your-game` skill has the steps; `summer ops search \"publish my game\"` finds each operation. `summer store publish` sends the game to Summer's store review, and the game's owner approves it: give them the link it prints. Nothing goes live until they approve.",
+        SUMMER_BLOCK_END,
+    ].join("\n");
+}
+/** The text with `block` as its Summer block: replaced where it is, else appended. Keeps the file's line endings. */
+function withBlock(text, block) {
+    const eol = text.includes("\r\n") ? "\r\n" : "\n";
+    const ours = block.replace(/\r?\n/g, eol);
+    const start = text.indexOf(SUMMER_BLOCK_START);
+    if (start === -1) {
+        // Only trailing line breaks change outside the block; an empty file is the block alone.
+        return { text: text.trim() ? `${text.replace(/(\r?\n)*$/, eol)}${eol}${ours}${eol}` : `${ours}${eol}`, action: "added" };
+    }
+    const end = text.indexOf(SUMMER_BLOCK_END, start);
+    if (end === -1)
+        return { text, action: "skipped", reason: "its Summer block has no end marker" };
+    // Two blocks (a merge, or the markers quoted in the person's text): which
+    // one is Summer's is not knowable, so the person picks; nothing is deleted.
+    if (text.indexOf(SUMMER_BLOCK_START, end) !== -1)
+        return { text, action: "skipped", reason: "it has two Summer blocks; delete one and run setup again" };
+    const next = `${text.slice(0, start)}${ours}${text.slice(end + SUMMER_BLOCK_END.length)}`;
+    return { text: next, action: next === text ? "unchanged" : "updated" };
+}
+/** Does the text import AGENTS.md on a line of its own, outside code fences? */
+function importsAgents(text) {
+    let fence = false;
+    for (const line of text.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (/^(```|~~~)/.test(trimmed))
+            fence = !fence;
+        else if (!fence && CLAUDE_IMPORTS.has(trimmed))
+            return true;
+    }
+    return false;
+}
+function inside(root, path) {
+    const rel = relative(root, path);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+/**
+ * Where a file may be written, and `real`, the file a write lands in:
+ * "missing" (create it: here, or the missing target of a link inside the
+ * project), "file" (a file, or a link to one inside the project), or a
+ * reason to leave it alone (a link that points nowhere or out of the
+ * project). `real` is known before anything is written, so a link from one
+ * name to the other counts as one file even when its target is missing.
+ */
+function locate(path, realRoot) {
+    let isLink = false;
+    try {
+        isLink = lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return { kind: "missing", real: join(realRoot, basename(path)) };
+    }
+    let real;
+    try {
+        real = realpathSync(path);
+    }
+    catch {
+        const target = resolve(realRoot, readlinkSync(path));
+        return inside(realRoot, target) ? { kind: "missing", real: target } : { kind: "skip", reason: "it is a link to a file that does not exist" };
+    }
+    if (isLink && !inside(realRoot, real))
+        return { kind: "skip", reason: "it is a link to a file outside the project" };
+    return { kind: "file", real };
+}
+/**
+ * Write or update AGENTS.md and CLAUDE.md in the project root. A new
+ * AGENTS.md is the Summer block; a new CLAUDE.md is `@AGENTS.md` only. An
+ * existing CLAUDE.md that already imports AGENTS.md is left as it is. Each
+ * file is its own step: a file that cannot be read or written is skipped
+ * with the reason, and the other is still done.
+ */
+export function writeAgentInstructions(projectDir, options = {}) {
+    const agents = join(projectDir, "AGENTS.md");
+    const claude = join(projectDir, "CLAUDE.md");
+    let block;
+    let realRoot;
+    try {
+        block = options.block ?? renderAgentsBlock();
+        realRoot = realpathSync(projectDir);
+    }
+    catch (error) {
+        const reason = messageOf(error);
+        return [
+            { file: "AGENTS.md", path: agents, action: "skipped", reason },
+            { file: "CLAUDE.md", path: claude, action: "skipped", reason },
+        ];
+    }
+    const write = (path, text) => {
+        if (!options.dryRun)
+            writeFileSync(path, text, "utf-8");
+    };
+    const step = (file, path, run) => {
+        try {
+            return { file, path, ...run() };
+        }
+        catch (error) {
+            return { file, path, action: "skipped", reason: messageOf(error) };
+        }
+    };
+    const agentsAt = locate(agents, realRoot);
+    const agentsResult = step("AGENTS.md", agents, () => {
+        if (agentsAt.kind === "skip")
+            return { action: "skipped", reason: agentsAt.reason };
+        if (agentsAt.kind === "missing") {
+            write(agents, `${block}\n`);
+            return { action: "created" };
+        }
+        const next = withBlock(readFileSync(agents, "utf-8"), block);
+        if (next.action === "added" || next.action === "updated")
+            write(agents, next.text);
+        return { action: next.action, ...(next.reason ? { reason: next.reason } : {}) };
+    });
+    const claudeAt = locate(claude, realRoot);
+    const claudeResult = step("CLAUDE.md", claude, () => {
+        if (claudeAt.kind === "skip")
+            return { action: "skipped", reason: claudeAt.reason };
+        // CLAUDE.md -> AGENTS.md (or the reverse): one file, which already has the AGENTS.md block.
+        if (agentsAt.kind !== "skip" && claudeAt.real === agentsAt.real) {
+            return { action: "unchanged", reason: "it is the same file as AGENTS.md" };
+        }
+        if (claudeAt.kind === "missing") {
+            write(claude, "@AGENTS.md\n");
+            return { action: "created" };
+        }
+        const text = readFileSync(claude, "utf-8");
+        if (importsAgents(text) && !text.includes(SUMMER_BLOCK_START))
+            return { action: "unchanged" };
+        const next = withBlock(text, `${SUMMER_BLOCK_START}\n@AGENTS.md\n${SUMMER_BLOCK_END}`);
+        if (next.action === "added" || next.action === "updated")
+            write(claude, next.text);
+        return { action: next.action, ...(next.reason ? { reason: next.reason } : {}) };
+    });
+    return [agentsResult, claudeResult];
+}
+/**
+ * The Summer project the working directory is in, for `summer setup`: the
+ * nearest folder with project.godot, looking up no further than the git
+ * top level, and never the home folder or the filesystem root (a stray
+ * project.godot there must not put an AGENTS.md or CLAUDE.md in every
+ * session). Null when there is none.
+ */
+export function findSetupProjectRoot(cwd = process.cwd()) {
+    let current;
+    try {
+        current = realpathSync(resolve(cwd));
+    }
+    catch {
+        return null;
+    }
+    let home;
+    try {
+        home = realpathSync(homedir());
+    }
+    catch {
+        home = homedir();
+    }
+    while (current !== home && current !== parse(current).root) {
+        if (existsSync(join(current, "project.godot")))
+            return current;
+        if (existsSync(join(current, ".git")))
+            return null;
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+    return null;
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/gemini-extension.json

@@ -1,8 +1,8 @@
 {
   "_generated": "GENERATED from integrations/gemini — do not edit; npm run generate:registry",
   "name": "summer",
-  "version": "3.8.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.",
+  "version": "4.2.0",
+  "description": "The game engine built for AI. Any agent makes a multiplayer game and publishes it. The Summer Engine MCP server, context primer and game-dev skills.",
   "contextFileName": "GEMINI.md",
   "mcpServers": {
     "summer-engine": {
@@ -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,8 @@
     "./library/skills/summer-analytics/",
     "./library/skills/summer-apps/",
     "./library/skills/summer-apps-design/",
+    "./library/skills/summer-assets/",
+    "./library/skills/summer-cli/",
     "./library/skills/summer-friends/",
     "./library/skills/summer-leaderboards/",
     "./library/skills/summer-match-results/",
@@ -147,7 +141,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/README.md

@@ -58,7 +58,7 @@ are listed where they differ.
 | claude-desktop | — | MCP: `~/Library/Application Support/Claude/claude_desktop_config.json`; Linux `~/.config/Claude/claude_desktop_config.json`; Windows `%APPDATA%/Claude/claude_desktop_config.json`; no skills folder (MCP only) |
 | codex | `.codex-plugin/plugin.json` | MCP: `~/.codex/config.toml`; project `.codex/config.toml`; skills: `~/.agents/skills`; project `.agents/skills` (`<skill>/SKILL.md`) |
 | cursor | `.cursor-plugin/plugin.json` | MCP: `~/.cursor/mcp.json`; project `.cursor/mcp.json`; skills: `~/.agents/skills`; project `.agents/skills` (`<skill>/SKILL.md`) |
-| windsurf | — | MCP: `~/.codeium/windsurf/mcp_config.json`; skills: `~/.agents/skills`; project `.agents/skills` (`<skill>/SKILL.md`) |
+| windsurf | — | MCP: `~/.config/devin/mcp_config.json`; Windows `%APPDATA%/devin/mcp_config.json`; skills: `~/.agents/skills`; project `.agents/skills` (`<skill>/SKILL.md`) |
 | antigravity | — | MCP: `~/.gemini/config/mcp_config.json`; project `.agents/mcp_config.json`; skills: `~/.gemini/config/skills`; project `.agents/skills` (`<skill>/SKILL.md`) |
 | gemini (legacy) | `gemini-extension.json` | MCP: `~/.gemini/extensions/summer-engine/gemini-extension.json`; skills: `~/.gemini/extensions/summer-engine/skills` (`<skill>/SKILL.md`) |
 | cline | — | MCP: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`; Linux `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`; Windows `%APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`; skills: `~/.cline/skills`; project `.cline/skills` (`<skill>/SKILL.md`) |

package/integrations/claude/README.md

@@ -8,6 +8,12 @@ Generated by `scripts/generate-registry` from `library/**/resource.yaml`:
 - `registry/generated/marketplace.claude.json` -> `.claude-plugin/marketplace.json`
   (marketplace listing wrapper).
 
+- `registry/generated/plugin.claude-directory.json` -> `plugins/claude/.claude-plugin/plugin.json`,
+  plus the rest of `plugins/claude/` (`scripts/generate-registry/mirrors.ts`): the same
+  plugin for Anthropic's plugin directory, from a folder of its own (under 512 files,
+  no symlinks), with the server and every `summer-engine@latest` pinned to this
+  version. Submit `plugins/claude` as the plugin path.
+
 The MCP pointer `./.mcp.json` these manifests reference is generated as
 well (`registry/generated/mcp.json -> .mcp.json`, owned by the claude target).
 

package/integrations/claude/manifest-target.json

@@ -11,6 +11,10 @@
     {
       "generated": "mcp.json",
       "destination": ".mcp.json"
+    },
+    {
+      "generated": "plugin.claude-directory.json",
+      "destination": "plugins/claude/.claude-plugin/plugin.json"
     }
   ]
 }

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/gemini/README.md

@@ -21,6 +21,17 @@ Generated by `scripts/generate-registry` from `library/**/resource.yaml`:
   `skills install --all --agent gemini`); Gemini extensions are user-scoped, so
   `--scope project` falls back to user with a warning.
 
+`gemini extensions install https://github.com/SummerEngine/summer` (and the
+Gemini CLI gallery) installs a GitHub Release's only asset when it has one.
+`.github/workflows/gemini-extension.yml` attaches `summer-gemini-extension.tar.gz`
+to every release (`scripts/build-gemini-extension.ts`): the manifest without `settings` (no hooks ship) and without
+`skills`, `GEMINI.md`, `AGENTS.md` and `skills/<slug>/` for every bundled skill.
+Keep it the release's only asset, or Gemini falls back to the source tarball,
+which has no `skills/` folder: the workflow leaves a release that already has it
+alone and stops with an error on one that has other assets. Every packaged file
+comes from the tag itself (only the script comes from the workflow's commit), so
+dispatching it for an older tag packages that release as it was.
+
 Never edit the destination file by hand — edit `library/` resources or
 `scripts/generate-registry/manifests.ts`, then run
 `npm run generate:registry`. CI `--check` fails on any drift.