summer-engine 4.0.0 → 4.2.0

package/dist/installer/skills-refresh.js

@@ -0,0 +1,261 @@
+import { closeSync, cpSync, existsSync, lstatSync, openSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getSkillRegistry, resolveSkillDir } from "../core/skills-registry.js";
+import { allAgentSpecs, defaultPathContext, resolveSkillPath } from "./agent-table.js";
+import { compareSemver, parseSemver, readKeptSkills, readSkillMarker, SKILL_VERSION_MARKER_FILENAME } from "./version-check.js";
+/**
+ * After an upgrade, bring the Summer skills already installed on this
+ * computer up to this CLI's version. Skills written for 3.x name 3.x tools,
+ * and while their marker says 3.x the MCP server keeps the legacy toolset on
+ * (legacy-toolset.ts), which gives back most of 4.0's smaller tool list.
+ *
+ * Only what Summer installed and nobody changed is replaced, in a skills
+ * folder that carries Summer's `.summer-version` marker older than this CLI:
+ * a real folder (not a link) whose `resource.yaml` says `id: skill/<name>`
+ * (every Summer release ships it; other packs reuse names such as
+ * `brainstorming`), with no file changed after the marker was written, and
+ * not one an earlier refresh already left for that reason (the marker lists
+ * them, so the protection lasts until `summer setup --force`). A copy that
+ * already matches the library counts as current, not as changed. Each
+ * replacement is a copy beside it and two renames, so a kill or a copy error
+ * leaves the old skill in place. One process per folder (a lock file).
+ * Nothing is removed. Missing library skills are added only to a folder that
+ * holds nearly the whole library, so an assets-only install stays one.
+ * Rule-file installs (Cline, Roo Code, old Cursor rules) keep the refresh
+ * command `summer doctor` prints.
+ */
+const LOCK_FILE = ".summer-refresh.lock";
+const STALE_LOCK_MS = 60_000;
+/** Setup writes the marker right after its copy; a file changed later than this was changed by someone. */
+const EDIT_GRACE_MS = 60_000;
+/** A folder holding this share of the bundled library is a full install: new library skills join it. */
+const FULL_INSTALL_SHARE = 0.9;
+const TEMP_PREFIX = ".summer-refresh-";
+const OLD_PREFIX = ".summer-old-";
+/** User-scope skill folders with one folder per skill, each listed once. */
+export function skillFolderLocations() {
+    const ctx = defaultPathContext();
+    const dirs = new Set([join(ctx.home, ".summer", "skills")]);
+    for (const spec of allAgentSpecs()) {
+        const home = resolveSkillPath(spec, "user", ctx);
+        if (home?.kind === "skill-dir")
+            dirs.add(home.path);
+    }
+    return [...dirs];
+}
+const isPrerelease = (version) => /^\d+\.\d+\.\d+-/.test(version.trim());
+/** Refresh when the marker is older, or a pre-release of this release (4.2.0-next.1 -> 4.2.0, never back). */
+function isBehind(marker, cliVersion) {
+    const installed = parseSemver(marker.version);
+    const current = parseSemver(cliVersion);
+    if (!installed || !current)
+        return false;
+    const order = compareSemver(installed, current);
+    return order < 0 || (order === 0 && isPrerelease(marker.version) && !isPrerelease(cliVersion));
+}
+const errorCode = (error) => error?.code ?? (error instanceof Error ? error.message : String(error));
+/** Summer's own copy: a real folder (not a link) whose resource.yaml names this skill. */
+function isSummersSkill(dest, name) {
+    try {
+        if (!lstatSync(dest).isDirectory())
+            return false;
+        const id = readFileSync(join(dest, "resource.yaml"), "utf-8").match(/^id:\s*["']?([^"'\s]+)["']?\s*$/m)?.[1];
+        return id === `skill/${name}`;
+    }
+    catch {
+        return false;
+    }
+}
+/** The folder, or any file in it, changed after `since` (ms); the folder's own time covers a deleted file. Links are not followed. */
+function changedSince(dir, since) {
+    if (lstatSync(dir).mtimeMs > since)
+        return true;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const path = join(dir, entry.name);
+        if (lstatSync(path).mtimeMs > since)
+            return true;
+        if (entry.isDirectory() && changedSince(path, since))
+            return true;
+    }
+    return false;
+}
+/** Relative paths of every file under `dir`. */
+function filesUnder(dir, prefix = "") {
+    return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => entry.isDirectory() ? filesUnder(join(dir, entry.name), `${prefix}${entry.name}/`) : [`${prefix}${entry.name}`]);
+}
+/** The installed folder holds exactly the library's files with the library's bytes (a refresh a kill interrupted already wrote it). */
+function sameAsLibrary(dest, src) {
+    try {
+        const installed = filesUnder(dest).sort();
+        const library = filesUnder(src).sort();
+        return (installed.length === library.length &&
+            installed.every((file, index) => file === library[index] && readFileSync(join(dest, file)).equals(readFileSync(join(src, file)))));
+    }
+    catch {
+        return false;
+    }
+}
+/** Copy beside, rename the old one aside, rename the new one in; the old one comes back on any error. */
+function replaceSkill(dir, name, src) {
+    const dest = join(dir, name);
+    const temp = join(dir, `${TEMP_PREFIX}${name}-${process.pid}`);
+    const old = join(dir, `${OLD_PREFIX}${name}-${process.pid}`);
+    rmSync(temp, { recursive: true, force: true });
+    try {
+        cpSync(src, temp, { recursive: true });
+    }
+    catch (error) {
+        rmSync(temp, { recursive: true, force: true });
+        throw error;
+    }
+    const hadOld = existsSync(dest);
+    if (hadOld)
+        renameSync(dest, old);
+    try {
+        renameSync(temp, dest);
+    }
+    catch (error) {
+        if (hadOld)
+            renameSync(old, dest);
+        rmSync(temp, { recursive: true, force: true });
+        throw error;
+    }
+    if (hadOld)
+        rmSync(old, { recursive: true, force: true });
+}
+/** What a killed refresh left: half copies go, a skill renamed aside comes back. */
+function recoverInterrupted(dir) {
+    for (const entry of readdirSync(dir)) {
+        const path = join(dir, entry);
+        if (entry.startsWith(TEMP_PREFIX))
+            rmSync(path, { recursive: true, force: true });
+        if (!entry.startsWith(OLD_PREFIX))
+            continue;
+        const name = entry.slice(OLD_PREFIX.length).replace(/-\d+$/, "");
+        if (existsSync(join(dir, name)))
+            rmSync(path, { recursive: true, force: true });
+        else
+            renameSync(path, join(dir, name));
+    }
+}
+/** The folder's lock, or null while another process holds a fresh one. */
+function takeLock(dir) {
+    const path = join(dir, LOCK_FILE);
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            closeSync(openSync(path, "wx"));
+            return () => rmSync(path, { force: true });
+        }
+        catch (error) {
+            if (errorCode(error) !== "EEXIST")
+                throw error;
+            try {
+                if (Date.now() - statSync(path).mtimeMs < STALE_LOCK_MS)
+                    return null;
+                unlinkSync(path);
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    return null;
+}
+function refreshFolder(dir, marker, cliVersion, registry, failures) {
+    const release = takeLock(dir);
+    if (!release)
+        return null;
+    try {
+        recoverInterrupted(dir);
+        // The marker must be writable before anything is copied, or every start would copy again.
+        const markerTemp = join(dir, `${SKILL_VERSION_MARKER_FILENAME}.tmp`);
+        writeFileSync(markerTemp, "", "utf-8");
+        const installedAt = Date.parse(marker.installedAt);
+        const editedAfter = (Number.isFinite(installedAt) ? installedAt : 0) + EDIT_GRACE_MS;
+        const folder = { dir, from: marker.version, to: cliVersion, updated: [], added: [], kept: [] };
+        const keptBefore = new Set(readKeptSkills(dir));
+        const owned = registry.filter((entry) => isSummersSkill(join(dir, entry.name), entry.name));
+        for (const entry of owned) {
+            const dest = join(dir, entry.name);
+            if (sameAsLibrary(dest, resolveSkillDir(entry))) {
+                folder.updated.push(entry.name);
+                continue;
+            }
+            if (keptBefore.has(entry.name) || changedSince(dest, editedAfter)) {
+                folder.kept.push(entry.name);
+                continue;
+            }
+            try {
+                replaceSkill(dir, entry.name, resolveSkillDir(entry));
+                folder.updated.push(entry.name);
+            }
+            catch (error) {
+                failures.push({ dir, skill: entry.name, code: errorCode(error) });
+            }
+        }
+        const bundled = registry.filter((entry) => entry.bundled !== false && entry.status !== "deprecated");
+        if (bundled.length > 0 && owned.length >= FULL_INSTALL_SHARE * bundled.length) {
+            for (const entry of bundled) {
+                if (existsSync(join(dir, entry.name)))
+                    continue;
+                try {
+                    replaceSkill(dir, entry.name, resolveSkillDir(entry));
+                    folder.added.push(entry.name);
+                }
+                catch (error) {
+                    failures.push({ dir, skill: entry.name, code: errorCode(error) });
+                }
+            }
+        }
+        // Written last, through a rename: a kill before this leaves the old marker, and the next start finishes.
+        const next = { version: cliVersion, installedAt: new Date().toISOString(), ...(folder.kept.length > 0 ? { kept: folder.kept } : {}) };
+        writeFileSync(markerTemp, JSON.stringify(next, null, 2) + "\n", "utf-8");
+        renameSync(markerTemp, join(dir, SKILL_VERSION_MARKER_FILENAME));
+        return folder;
+    }
+    finally {
+        release();
+    }
+}
+export function refreshInstalledSkills(cliVersion, options = {}) {
+    const result = { refreshed: [], failures: [] };
+    if (!parseSemver(cliVersion))
+        return result;
+    for (const dir of options.dirs ?? skillFolderLocations()) {
+        const marker = readSkillMarker(dir);
+        if (!marker || !isBehind(marker, cliVersion))
+            continue;
+        try {
+            const folder = refreshFolder(dir, marker, cliVersion, options.registry ?? getSkillRegistry(), result.failures);
+            if (folder)
+                result.refreshed.push(folder);
+        }
+        catch (error) {
+            // A folder we cannot lock or write keeps its skills and its marker; doctor still names the refresh.
+            result.failures.push({ dir, code: errorCode(error) });
+        }
+    }
+    return result;
+}
+const listed = (names) => names.length > 5 ? `${names.slice(0, 5).join(", ")} and ${names.length - 5} more` : names.join(", ");
+/** The one message a person and their agent see after a refresh, or null when nothing changed. */
+export function refreshNotice(refreshed, failures = []) {
+    const skills = new Set(refreshed.flatMap((folder) => [...folder.updated, ...folder.added])).size;
+    const kept = [...new Set(refreshed.flatMap((folder) => folder.kept))];
+    const failed = [...new Set(failures.flatMap((failure) => (failure.skill ? [failure.skill] : [])))];
+    if (skills === 0 && kept.length === 0)
+        return null;
+    const changedFolders = refreshed.filter((folder) => folder.updated.length + folder.added.length > 0).length;
+    const from = [...new Set(refreshed.map((folder) => folder.from))].join(", ");
+    const to = refreshed[0].to;
+    return [
+        skills > 0 ? `Summer updated its ${skills} installed skills (${changedFolders === 1 ? "1 folder" : `${changedFolders} folders`}) from ${from} to ${to}.` : "",
+        kept.length > 0
+            ? `It left ${kept.length} Summer skills you changed as they are (${listed(kept)}); summer setup <agent> --force replaces them.`
+            : "",
+        failed.length > 0 ? `${failed.length} could not be updated (${listed(failed)}); summer setup <agent> --force retries them.` : "",
+        "3.x tool names still run through summer_call; summer mcp --toolsets legacy lists them again.",
+    ]
+        .filter(Boolean)
+        .join(" ");
+}

package/dist/installer/version-check.d.ts

@@ -79,9 +79,18 @@ export declare const SKILL_VERSION_MARKER_FILENAME = ".summer-version";
 export interface SkillVersionMarker {
     version: string;
     installedAt: string;
+    /** Summer skills the upgrade refresh left because someone changed them (installer/skills-refresh.ts). */
+    kept?: string[];
 }
 export declare function readSkillMarker(dir: string): SkillVersionMarker | null;
-export declare function writeSkillMarker(dir: string, version: string, now?: Date): string;
+/** The skills the upgrade refresh left in this folder (the raw marker; readSkillMarker keeps setup's fields). */
+export declare function readKeptSkills(dir: string): string[];
+/**
+ * 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 declare function writeSkillMarker(dir: string, version: string, now?: Date, installed?: readonly string[]): string;
 /**
  * Candidate locations for skill-version markers. Listed roughly in order of
  * how likely a Summer user is to have them populated. We probe every candidate,
@@ -108,6 +117,10 @@ export interface RecordedInstall {
     /** Where the answer came from: the agent's config file, or — when it has
      *  no readable Summer entry — the nature of the CLI running this check. */
     source: "agent-config" | "running-cli";
+    /** The agent's config lists no summer-engine server in any shape (`setup
+     *  --cli`, or skills installed alone) and `setup --cli` can set the agent
+     *  up: the refresh keeps it without an MCP server. */
+    cliOnly?: boolean;
 }
 /** An npm dist-tag (`latest`, `next`) or an exact version (`3.9.1`). */
 export type RefreshChannel = string;
@@ -153,7 +166,8 @@ export declare function buildSkillsVersionCheck(input: SkillsVersionCheckInput):
  * 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 declare function skillsRefreshCommand(agent: string, install: RecordedInstall | null, channel?: RefreshChannel): string;
 /** The shape `summer setup --local-dev` writes: `node <…>/dist/bin/summer.js mcp`
@@ -173,6 +187,12 @@ export declare function isLocalDevServerConfig(server: StdioMcpServerConfig): bo
  * Returns null when the file is missing, unparsable, or has no Summer entry.
  */
 export declare function readRecordedMcpServer(text: string, format: McpFormat): StdioMcpServerConfig | 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 declare function listsSummerEngine(text: string, format: McpFormat): boolean;
 /** 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 declare function runningCliIsCheckout(packageRoot?: string): boolean;

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

@@ -34,6 +34,7 @@ import { opForToolCall } from "../core/ops/contract.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";
@@ -363,9 +364,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 +428,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 +473,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 +488,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;