summer-engine 4.0.0 → 4.3.0

package/dist/installer/version-check.js

@@ -13,7 +13,7 @@
  */
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { parse as parseYaml } from "yaml";
-import { allAgentSpecs, defaultPathContext, resolveSkillPath } from "./agent-table.js";
+import { agentSpec, allAgentSpecs, cliSetupRefusal, defaultPathContext, resolveSkillPath } from "./agent-table.js";
 import { join, sep } from "node:path";
 import { PACKAGE_ROOT } from "../core/package-root.js";
 import { configureAgentMcp, parseAgent, SUMMER_MCP_SERVER_NAME, topLevelKey, } from "./agent-config.js";
@@ -219,11 +219,28 @@ export function readSkillMarker(dir) {
         return null;
     }
 }
-export function writeSkillMarker(dir, version, now = new Date()) {
+/** The skills the upgrade refresh left in this folder (the raw marker; readSkillMarker keeps setup's fields). */
+export function readKeptSkills(dir) {
+    try {
+        const kept = JSON.parse(readFileSync(join(dir, SKILL_VERSION_MARKER_FILENAME), "utf-8")).kept;
+        return Array.isArray(kept) ? kept.filter((name) => typeof name === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Write the folder's marker. The skills an upgrade refresh left stay listed
+ * (so later refreshes keep leaving them), except the ones this install just
+ * wrote: `installed` names them; leave it out to keep every one.
+ */
+export function writeSkillMarker(dir, version, now = new Date(), installed) {
     const path = join(dir, SKILL_VERSION_MARKER_FILENAME);
+    const kept = readKeptSkills(dir).filter((name) => !installed?.includes(name));
     const payload = {
         version,
         installedAt: now.toISOString(),
+        ...(kept.length > 0 ? { kept } : {}),
     };
     writeFileSync(path, JSON.stringify(payload, null, 2) + "\n", "utf-8");
     return path;
@@ -378,9 +395,16 @@ async function resolveRecordedInstall(resolver, agent) {
  * The command that refreshes an agent's skills without changing how its MCP
  * entry was recorded: the local-dev form re-links the same checkout
  * (`setup --local-dev --force` re-copies the checkout's skills); the npx form
- * is for installs that already run the published package.
+ * is for installs that already run the published package. An agent with no
+ * summer-engine entry refreshes with `--cli`, so the refresh adds no MCP server.
  */
 export function skillsRefreshCommand(agent, install, channel = "latest") {
+    if (install?.cliOnly) {
+        // No MCP entry to keep: --local-dev and --channel shape only that entry.
+        return install.localDev && install.cliPath
+            ? `node ${install.cliPath} setup ${agent} --cli --yes --force`
+            : `npx clear-npx-cache && npx -y summer-engine@${channel} setup ${agent} --cli --yes --force`;
+    }
     if (install?.localDev && install.cliPath) {
         return `node ${install.cliPath} setup ${agent} --local-dev --yes --force`;
     }
@@ -473,6 +497,37 @@ export function readRecordedMcpServer(text, format) {
     }
     return null;
 }
+/**
+ * Does the agent's config list a summer-engine server in any shape: the stdio
+ * entry setup writes, a URL entry under that name, or (Claude Code) a
+ * per-project entry under projects.<dir>.mcpServers?
+ */
+export function listsSummerEngine(text, format) {
+    if (readRecordedMcpServer(text, format))
+        return true;
+    if (!text.trim())
+        return false;
+    if (format === "toml")
+        return new RegExp(`^\\s*\\[mcp_servers\\.(?:"${SUMMER_MCP_SERVER_NAME}"|${SUMMER_MCP_SERVER_NAME})[\\].]`, "m").test(text);
+    if (format === "toml-array")
+        return new RegExp(`^\\s*name\\s*=\\s*"${SUMMER_MCP_SERVER_NAME}"`, "m").test(text);
+    let parsed;
+    try {
+        parsed = format === "yaml-goose" || format === "yaml-hermes" ? parseYaml(text) : JSON.parse(text);
+    }
+    catch {
+        return false;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return false;
+    const root = parsed;
+    const projects = root.projects && typeof root.projects === "object" ? Object.values(root.projects) : [];
+    const maps = [
+        ...[topLevelKey(format), "mcpServers", "servers", "mcp", "context_servers", "extensions", "mcp_servers", "amp.mcpServers"].map((key) => root[key]),
+        ...projects.map((project) => (project && typeof project === "object" ? project.mcpServers : undefined)),
+    ];
+    return maps.some((map) => Boolean(map) && typeof map === "object" && SUMMER_MCP_SERVER_NAME in map);
+}
 /** Is the CLI running this check a source checkout rather than an installed
  *  package? npm/npx/global installs all live under a node_modules directory. */
 export function runningCliIsCheckout(packageRoot = PACKAGE_ROOT) {
@@ -488,16 +543,17 @@ export function runningCliIsCheckout(packageRoot = PACKAGE_ROOT) {
  */
 export async function detectRecordedInstall(agent) {
     const supported = parseAgent(agent);
+    let cliOnly = false;
     if (supported) {
         try {
             const target = await configureAgentMcp({ agent: supported, scope: "user", print: true });
-            if (existsSync(target.path)) {
-                const recorded = readRecordedMcpServer(readFileSync(target.path, "utf-8"), target.format);
-                if (recorded) {
-                    const localDev = isLocalDevServerConfig(recorded);
-                    return { localDev, cliPath: localDev ? recorded.args[0] ?? null : null, source: "agent-config" };
-                }
+            const text = existsSync(target.path) ? readFileSync(target.path, "utf-8") : "";
+            const recorded = readRecordedMcpServer(text, target.format);
+            if (recorded) {
+                const localDev = isLocalDevServerConfig(recorded);
+                return { localDev, cliPath: localDev ? recorded.args[0] ?? null : null, source: "agent-config" };
             }
+            cliOnly = !listsSummerEngine(text, target.format) && cliSetupRefusal(agentSpec(supported)) === null;
         }
         catch {
             // Unreadable config: fall through to the running-CLI answer.
@@ -508,6 +564,7 @@ export async function detectRecordedInstall(agent) {
         localDev: checkout,
         cliPath: checkout ? [PACKAGE_ROOT, "dist", "bin", "summer.js"].join(sep) : null,
         source: "running-cli",
+        ...(cliOnly ? { cliOnly } : {}),
     };
 }
 export function buildBootDriftNotice(installedVersion, registry, agent) {

package/dist/mcp/ops-surface.js

@@ -1,7 +1,7 @@
 import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import { localEntries, localInputSchema, localWireForm, missingInput } from "../core/ops/catalog.js";
-import { answerOfHosted, hostedCallFailure, searchEverywhere } from "../core/ops/cloud.js";
+import { answerOfHosted, describeFromShipped, hostedCallFailure, searchEverywhere } from "../core/ops/cloud.js";
 import { errorAnswer, isLocalOp, legacyNames, localToolsFor, mcpNameOf, resolveOpName } from "../core/ops/contract.js";
 import { ENGINE_SPLIT_OPS, engineOpDef, isSplitOp, renderOpRefs, splitToolArgs } from "../core/ops/engine.js";
 import { answerOfEngineResult, engineFailure, textsOf } from "../core/ops/engine-answer.js";
@@ -343,12 +343,20 @@ export function applyOpsSurface(server, options) {
         limit: z.number().int().min(1).max(20).optional().describe("Most results (default 5)."),
     }, { title: "Find a Summer operation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }, (async ({ query, area, limit }) => toolResult(await search(query, area, limit ?? 5))));
     server.tool(SUMMER_CALL, "Run any Summer operation by name (from summer_search) with its input. Engine operations run here; cloud ones run on Summer's server with the same approvals: money, publishing and live changes answer needs_approval with a link. 3.x tool names work too.", {
-        op: z.string().min(1).max(80).describe("The operation name, e.g. engine.add_node or pricing.set_base (or a 3.x tool name)."),
+        op: z.string().min(1).max(80).optional().describe("The operation name, e.g. engine.add_node or pricing.set_base (or a 3.x tool name)."),
+        // Agents reach for `name` (the field summer_search answers with); it means op.
+        name: z.string().min(1).max(80).optional().describe("Same as op."),
         input: z.record(z.unknown()).optional().describe("The operation's input, matching the schema summer_search returned."),
         dryRun: z.boolean().optional().describe("Check and describe the call without doing it."),
         idempotencyKey: z.string().min(1).max(128).optional().describe("Retry key for writes; reuse it only to retry the identical call."),
-    }, { title: "Run a Summer operation", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }, (async ({ op, input, dryRun, idempotencyKey }, extra) => {
-        const name = op.trim();
+    }, { title: "Run a Summer operation", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }, (async ({ op, name: opAlias, input, dryRun, idempotencyKey }, extra) => {
+        const name = (op ?? opAlias ?? "").trim();
+        if (!name) {
+            return toolResult(errorAnswer("invalid_input", "Pass op: the operation name from summer_search, e.g. engine.add_node.", { next: { op: "ops.search" } }));
+        }
+        if (op !== undefined && opAlias !== undefined && op.trim() !== opAlias.trim()) {
+            return toolResult(errorAnswer("invalid_input", `op ("${op}") and name ("${opAlias}") differ; pass one operation name.`, { next: { op: "ops.search" }, details: { path: "name" } }));
+        }
         const args = input ?? {};
         // A split operation's own tool name, or a mixed 3.x tool whose action picks the operation.
         const action = typeof args.action === "string" ? args.action : typeof args.mode === "string" ? args.mode : undefined;
@@ -378,13 +386,15 @@ export function applyOpsSurface(server, options) {
         // `out` stays here: this package saves the files (core/ops/save-files.ts).
         const { input: sent, out } = options.files.take(resolved, args);
         let raw;
+        // Describing a cloud operation works signed out: the shipped catalog has it.
+        const describe = (answer) => (resolved === "ops.describe" && typeof args.name === "string" ? describeFromShipped(args.name, answer) : null) ?? answer;
         try {
             raw = await options.cloud.call(SUMMER_CALL, { op: name, ...(input ? { input: sent } : {}), ...(dryRun ? { dryRun } : {}), ...(idempotencyKey ? { idempotencyKey } : {}) });
         }
         catch (error) {
-            return toolResult(hostedCallFailure(error, { op: resolved, dryRun: dryRun === true, idempotencyKey }));
+            return toolResult(describe(hostedCallFailure(error, { op: resolved, dryRun: dryRun === true, idempotencyKey })));
         }
-        return toolResult(await options.files.finish(resolved, answerOfHosted(raw), out));
+        return toolResult(describe(await options.files.finish(resolved, answerOfHosted(raw), out)));
     }));
 }
 /** A split operation's input shape: its fields from the 3.x tool's shape, the required ones required. */

package/dist/mcp/server.d.ts

@@ -38,6 +38,8 @@ export interface CreateMcpServerOptions {
     cloud?: CloudCaller;
     /** v4 only: list every local 3.x name too (the legacy toolset, legacy-toolset.ts). */
     legacy?: boolean;
+    /** One line for this session only, after the instructions (e.g. the installed skills were refreshed). */
+    notice?: string | null;
 }
 export declare function createMcpServer(selection?: ToolSelection, options?: CreateMcpServerOptions): {
     server: McpServer;
@@ -45,6 +47,14 @@ export declare function createMcpServer(selection?: ToolSelection, options?: Cre
     /** v4: saves generated files on this machine (the mounted hosted tools share it). */
     files: FileSaver;
 };
+/**
+ * First v4 start after an upgrade: bring the installed Summer skills to this
+ * version before the legacy decision, which stays on while they are 3.x (and
+ * whenever the config asks for it). Not on the v3 surface, whose people chose
+ * the 3.x tools, and not under summer doctor's boot probe, whose session would
+ * swallow the one notice. A fault here never stops the server.
+ */
+export declare function refreshSkillsAfterUpgrade(surface: SurfaceVersion): string | null;
 export interface StartMcpServerOptions {
     projectPath?: string;
     instanceId?: string;

package/dist/mcp/server.js

@@ -31,12 +31,14 @@ import { defaultHostedMountDependencies, prepareHostedMount } from "./hosted-mou
 import { applyOpsSurface, hostedFileTools, OPS_MCP_ASSETS_INSTRUCTIONS, OPS_MCP_INSTRUCTIONS, SUMMER_CALL, SUMMER_SEARCH } from "./ops-surface.js";
 import { FileSaver } from "../core/ops/save-files.js";
 import { opForToolCall } from "../core/ops/contract.js";
+import { knownOp } from "../core/ops/catalog.js";
 import { v4HostedUrl } from "../core/ops/cloud.js";
 import { serveProviderSafeToolSchemas } from "./provider-safe-schema.js";
 import { legacyHostedDescription, resolveLegacy, takeLegacyToolset } from "./legacy-toolset.js";
+import { refreshInstalledSkills, refreshNotice } from "../installer/skills-refresh.js";
 import { OUTPUT_CAPS, PROFILE_TOOL_LIMIT, PROFILES, TOOLSETS, annotationsFor, registryAuthorities, resolveToolSelection, selectionIncludes, withMaxCharactersArg, } from "./tool-surface.js";
 import { shapeToolResult, singleEditCounter } from "./tool-results.js";
-import { recordLocalToolCall, recordMcpSession } from "../core/telemetry.js";
+import { recordLocalToolCall, recordMcpSession, toolErrorCode } from "../core/telemetry.js";
 import { currentToolContext, registerMcpClientSource, runWithToolContext } from "../core/agent-host.js";
 import { buildBootDriftNotice, fetchLatestRegistryVersion, } from "../installer/version-check.js";
 import { TOOLKIT_VERSION as version } from "../core/version.js";
@@ -233,9 +235,9 @@ function installToolCallWrapper(server, surfaceMeta) {
             // A tool another tool runs (summer_call, a v4 operation over its 3.x
             // tool) is part of that call: only the outer call sends a usage line.
             const nested = currentToolContext() !== undefined;
-            const recordUsage = (ok, durationMs) => {
+            const recordUsage = (ok, durationMs, error) => {
                 if (!nested)
-                    recordLocalToolCall({ tool: name, op: opForToolCall(name, handlerArgs[0]), ...surfaceMeta, ok, durationMs, mcpClient: hostApp() });
+                    recordLocalToolCall({ tool: name, op: knownOp(opForToolCall(name, handlerArgs[0])), ...surfaceMeta, ok, durationMs, mcpClient: hostApp(), error });
             };
             let result;
             try {
@@ -253,7 +255,7 @@ function installToolCallWrapper(server, surfaceMeta) {
                     exception: error instanceof Error ? error.message : String(error),
                     durationMs,
                 });
-                recordUsage(false, durationMs);
+                recordUsage(false, durationMs, "exception");
                 throw error;
             }
             const durationMs = Date.now() - startedAt;
@@ -272,7 +274,7 @@ function installToolCallWrapper(server, surfaceMeta) {
             }
             try {
                 recordMcpSession();
-                recordUsage(!isError, durationMs);
+                recordUsage(!isError, durationMs, isError ? toolErrorCode(result, meta?.failureReason ?? meta?.errorClass) : null);
                 // Opt-in local trajectory capture: one JSONL line per tool call when
                 // SUMMER_TRAJECTORY_DIR is set. recordToolCall never throws and is a
                 // no-op when the env var is unset.
@@ -363,9 +365,10 @@ export function createMcpServer(selection = FULL_SELECTION, options = {}) {
         name: "summer-engine",
         version,
     }, {
-        instructions: surface === "v4"
+        instructions: (surface === "v4"
             ? engine ? OPS_MCP_INSTRUCTIONS : OPS_MCP_ASSETS_INSTRUCTIONS
-            : engine ? SUMMER_MCP_INSTRUCTIONS : SUMMER_MCP_ASSETS_INSTRUCTIONS,
+            : engine ? SUMMER_MCP_INSTRUCTIONS : SUMMER_MCP_ASSETS_INSTRUCTIONS) +
+            (options.notice ? ` ${options.notice} Tell the person once.` : ""),
     });
     const getWrappedToolCount = installToolCallWrapper(server, { surfaceVersion: surface, profile: selection.profile });
     // Requests to Summer's servers name the agent app from the initialize handshake.
@@ -426,6 +429,32 @@ function hostedToolsLabel(toolsets) {
         return "Tool Factory tools (summer_tool_*) and asset editing tools";
     return undefined;
 }
+/**
+ * First v4 start after an upgrade: bring the installed Summer skills to this
+ * version before the legacy decision, which stays on while they are 3.x (and
+ * whenever the config asks for it). Not on the v3 surface, whose people chose
+ * the 3.x tools, and not under summer doctor's boot probe, whose session would
+ * swallow the one notice. A fault here never stops the server.
+ */
+export function refreshSkillsAfterUpgrade(surface) {
+    if (surface !== "v4" || process.env.SUMMER_MCP_DOCTOR === "1")
+        return null;
+    try {
+        const { refreshed, failures } = refreshInstalledSkills(version);
+        if (failures.length > 0)
+            appendMcpLogEvent("mcp:skills_refresh_failed", { version, failures });
+        const notice = refreshNotice(refreshed, failures);
+        if (notice) {
+            appendMcpLogEvent("mcp:skills_refreshed", { version, notice });
+            process.stderr.write(`[summer-mcp] ${notice}\n`);
+        }
+        return notice;
+    }
+    catch (error) {
+        appendMcpLogEvent("mcp:skills_refresh_failed", { version, ...errorDetails(error) });
+        return null;
+    }
+}
 export async function startMcpServer(options = {}) {
     configureMcpEngineSelection({
         instanceId: options.instanceId ?? process.env.SUMMER_ENGINE_INSTANCE_ID,
@@ -445,6 +474,7 @@ export async function startMcpServer(options = {}) {
         },
     });
     const surface = resolveSurface(options.surface);
+    const skillsNotice = refreshSkillsAfterUpgrade(surface);
     // `legacy` is not a toolset of its own: it lists the 3.x names on the v4 surface.
     const toolsetList = takeLegacyToolset(options.toolsets ?? process.env.SUMMER_TOOLSETS);
     const legacy = surface === "v4" ? resolveLegacy(toolsetList.requested) : { on: false, reason: "off" };
@@ -459,7 +489,7 @@ export async function startMcpServer(options = {}) {
     // v4 runs cloud operations through the hosted mount below, once it exists.
     let hostedCall = null;
     const cloud = { call: (name, args) => (hostedCall ? hostedCall(name, args) : NO_CLOUD.call(name, args)) };
-    const { server, getRegisteredToolCount, files } = createMcpServer(selection, { surface, cloud, legacy: legacy.on });
+    const { server, getRegisteredToolCount, files } = createMcpServer(selection, { surface, cloud, legacy: legacy.on, notice: skillsNotice });
     // Fire-and-forget — never block tool registration on the npm registry.
     void probeBootDrift().catch((error) => {
         setCachedBootDriftNotice(null);

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": "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.",
+  "version": "4.3.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": {
@@ -108,6 +108,7 @@
     "./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/",

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"
     }
   ]
 }