summer-engine 4.0.0 → 4.3.0

package/dist/installer/cli-permissions.js

@@ -0,0 +1,182 @@
+import { existsSync } from "node:fs";
+import { chmod, mkdir, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { CLI_AREAS } from "../core/ops/areas.js";
+import { localEntries } from "../core/ops/catalog.js";
+import { shippedCloudEntries } from "../core/ops/public-catalog.js";
+/**
+ * Allow rules for the CLI path, added only with `summer setup <agent> --cli
+ * --allow-rules --yes` (the flag is in the command the person approves), so
+ * the agent's read-only and dry-run summer commands do not each ask:
+ *
+ * - the reads in AUTO_ALLOWED_READS, as they are. The list is reviewed by
+ *   hand: a new read operation in the catalog does not join it, and
+ *   cli-permissions.test.ts fails until someone adds it on purpose;
+ * - every spend (generation and the rest) only as a dry run, `--dry-run`
+ *   right after the action. A call with that flag is a dry run whatever else
+ *   it says (parseCallFlags), so the rule cannot let a real spend through.
+ *
+ * Changes, publishing, prices, deletes and messages keep asking. Claude Code
+ * matches the command text (`Bash(summer jobs wait *)` matches the bare
+ * command and `summer jobs wait --job-id x`, not `summer jobs waitx`); Codex
+ * matches argument lists, in a rules file of Summer's own. Both get the
+ * `summer` and the `npx -y summer-engine@latest` forms.
+ */
+/**
+ * Reads that run without asking. Each one reads Summer data or the open
+ * editor's state; `jobs wait` and `assets get` also save the files a finished
+ * job names (media files only, never over an existing file). Left out on
+ * purpose: `engine capture-gameplay` (it starts Summer Engine on a project, so
+ * the project's own code runs, and writes to any --out folder) and
+ * `studio open` (it opens a page in the browser).
+ */
+export const AUTO_ALLOWED_READS = [
+    "whoami", "ops.search", "ops.describe",
+    "docs.search", "docs.read", "docs.engine_api", "docs.plan",
+    "jobs.get", "jobs.list", "jobs.wait",
+    "account.permissions", "profile.get", "team.list", "chats.list", "plugins.search",
+    "games.get", "games.list", "games.members", "jams.list", "pricing.get",
+    "store.get_listing", "store.status", "experiments.list", "experiments.results",
+    "analytics.event_limit", "analytics.events", "analytics.funnel", "analytics.overview", "analytics.summary", "analytics.trend",
+    "assets.choices", "assets.get", "assets.get_icon_collection", "assets.get_pack", "assets.list_comments", "assets.list_folders", "assets.list_icon_collections", "assets.search",
+    "apps.events", "apps.get", "apps.guide", "apps.list", "apps.page", "apps.read_data", "apps.screenshot", "apps.tools",
+    "plans.changes", "plans.chat", "plans.directions", "plans.get", "plans.links", "plans.list", "plans.presence", "plans.show",
+    "projects.builds", "projects.get", "projects.list", "projects.open_in_engine", "projects.preview_build",
+    "stories.get", "stories.list", "studio.map", "studio.page", "studio.read_form",
+    "marketing.applications", "marketing.content_feed", "marketing.content_videos", "marketing.get_brand_pack", "marketing.list_content_games",
+    "engine.debug_views", "engine.game_probe", "engine.get_console", "engine.get_debugger_errors", "engine.get_debugger_warnings", "engine.get_diagnostics",
+    "engine.get_project_context", "engine.get_runtime_tree", "engine.get_scene_tree", "engine.get_script_errors", "engine.grep", "engine.inspect_asset",
+    "engine.inspect_node", "engine.inspect_resource", "engine.inspect_runtime_node", "engine.is_running", "engine.list_camera_bookmarks", "engine.list_ui_actions",
+    "engine.measure", "engine.navigation_probe", "engine.raycast", "engine.read_file", "engine.recent_events", "engine.scene_audit", "engine.screenshot",
+    "engine.shot_sheet", "engine.snapshot_diff", "engine.starcast", "engine.test_placement", "engine.ui_screenshot", "engine.ui_tree", "engine.wait_for_event",
+    "engine.world_snapshot", "engine.zoom",
+];
+/** The shell words of a command, after the launcher: `assets.generate_image` -> `assets generate-image`. */
+const wordsOf = (op) => (op.includes(".") ? [op.split(".")[0], op.split(".")[1].replace(/_/g, "-")] : [op]);
+/** The commands allowed without asking: `summer status`, the reviewed reads, and a dry run of every spend in the catalog. */
+export function allowedCliCommands() {
+    const known = new Map([...localEntries(), ...shippedCloudEntries()].map((entry) => [entry.name, entry]));
+    const reads = AUTO_ALLOWED_READS.filter((op) => known.get(op)?.effect === "read").map((op) => ({ words: wordsOf(op), dryRun: false }));
+    const areas = new Set(CLI_AREAS);
+    const spends = [...known.values()]
+        .filter((entry) => entry.effect === "spend" && entry.status !== "deprecated" && areas.has(entry.name.split(".")[0]))
+        .map((entry) => ({ words: wordsOf(entry.name), dryRun: true }));
+    return [{ words: ["status"], dryRun: false }, ...reads, ...spends].sort((a, b) => a.words.join(" ").localeCompare(b.words.join(" ")) || Number(a.dryRun) - Number(b.dryRun));
+}
+export const LAUNCHERS = [["summer"], ["npx", "-y", "summer-engine@latest"]];
+/** Claude Code `permissions.allow` rules, for both launchers. */
+export function claudeAllowRules() {
+    return LAUNCHERS.flatMap((launcher) => allowedCliCommands().map(({ words, dryRun }) => `Bash(${[...launcher, ...words, ...(dryRun ? ["--dry-run"] : [])].join(" ")} *)`));
+}
+const starlark = (value) => (typeof value === "string" ? JSON.stringify(value) : `[${value.map((item) => JSON.stringify(item)).join(", ")}]`);
+const CODEX_HEADER = "# Written by summer setup codex --cli --allow-rules; setup rewrites this file and --remove-allow-rules deletes it.";
+/** Codex rules: one prefix_rule per launcher, area and kind, the actions as a union. */
+export function codexRules() {
+    const groups = new Map();
+    for (const launcher of LAUNCHERS) {
+        for (const { words, dryRun } of allowedCliCommands()) {
+            const head = words.length > 1 ? words.slice(0, 1) : [];
+            const key = `${launcher.join(" ")}|${head.join(" ")}|${dryRun}`;
+            const group = groups.get(key) ?? { launcher, head, actions: [], dryRun };
+            group.actions.push(words[words.length - 1]);
+            groups.set(key, group);
+        }
+    }
+    const rules = [...groups.values()].map(({ launcher, head, actions, dryRun }) => {
+        const pattern = [...launcher.map(starlark), ...head.map(starlark), starlark(actions.length === 1 ? actions[0] : actions), ...(dryRun ? [starlark("--dry-run")] : [])];
+        const example = [...launcher, ...head, actions[0], ...(dryRun ? ["--dry-run"] : [])].join(" ");
+        const why = dryRun ? "Summer dry run: checks the input, spends nothing" : "Summer read: changes no Summer data; jobs wait and assets get save the files they name";
+        return `prefix_rule(\n    pattern = [${pattern.join(", ")}],\n    decision = "allow",\n    justification = ${starlark(why)},\n    match = [${starlark(example)}],\n)`;
+    });
+    return `${CODEX_HEADER}\n# Reads, and spends only as dry runs. Changes, publishing, deletes and messages still ask.\n\n${rules.join("\n\n")}\n`;
+}
+/** The agents with clean per-command allow rules: Claude Code (settings.json) and Codex (rules files). */
+export function supportsAllowRules(agent) {
+    return agent === "claude-code" || agent === "codex";
+}
+/**
+ * Where the rules go. Claude Code: the user's settings, or with --scope
+ * project the project's personal settings.local.json (never the shared file).
+ * Codex: always the user's rules folder; a project's .codex/rules is shared
+ * through git, so Summer does not write there.
+ */
+export function allowRulesPath(agent, scope, ctx) {
+    if (agent === "codex")
+        return ctx.env.SUMMER_CODEX_RULES_FILE || join(ctx.env.CODEX_HOME || join(ctx.home, ".codex"), "rules", "summer.rules");
+    return ctx.env.SUMMER_CLAUDE_SETTINGS_FILE || (scope === "project" ? join(ctx.cwd, ".claude", "settings.local.json") : join(ctx.home, ".claude", "settings.json"));
+}
+/**
+ * Write next to the file, then rename over it, so Claude Code never reads
+ * half a file. A symlinked settings file (a dotfiles repo) is written through
+ * the link, in its real folder, and keeps its mode.
+ */
+async function writeAtomically(path, text) {
+    const target = existsSync(path) ? await realpath(path) : path;
+    await mkdir(dirname(target), { recursive: true });
+    const mode = existsSync(target) ? (await stat(target)).mode & 0o7777 : undefined;
+    const temp = `${target}.summer-${process.pid}.tmp`;
+    await writeFile(temp, text, mode === undefined ? {} : { mode });
+    if (mode !== undefined)
+        await chmod(temp, mode);
+    await rename(temp, target);
+}
+async function readClaudeSettings(path) {
+    let settings = {};
+    if (existsSync(path)) {
+        try {
+            settings = JSON.parse(await readFile(path, "utf8"));
+        }
+        catch {
+            throw new Error(`${path} is not valid JSON, so Summer left its allow rules alone. Fix the file, then run setup again.`);
+        }
+    }
+    if (!settings || typeof settings !== "object" || Array.isArray(settings))
+        throw new Error(`${path} is not a JSON object, so Summer left its allow rules alone.`);
+    const record = settings;
+    const permissions = record.permissions ?? {};
+    if (!permissions || typeof permissions !== "object" || Array.isArray(permissions))
+        throw new Error(`${path}: permissions is not an object, so Summer left its allow rules alone.`);
+    const allow = permissions.allow ?? [];
+    if (!Array.isArray(allow))
+        throw new Error(`${path}: permissions.allow is not a list, so Summer left its allow rules alone.`);
+    return { settings: record, permissions: permissions, allow };
+}
+/**
+ * Add the allow rules. Claude Code: merged into `permissions.allow`, nothing
+ * removed, every other setting kept. Codex: Summer's own rules file,
+ * rewritten. Writes nothing unless `write`.
+ */
+export async function addAllowRules(agent, path, write) {
+    if (agent === "codex") {
+        const text = codexRules();
+        const rules = text.split("\n").filter((line) => line.startsWith("    pattern = ")).map((line) => line.trim());
+        const changed = (existsSync(path) ? await readFile(path, "utf8") : "") !== text;
+        if (write && changed)
+            await writeAtomically(path, text);
+        return { agent, path, rules, changed: changed ? rules : [], wrote: write && changed };
+    }
+    const rules = claudeAllowRules();
+    const { settings, permissions, allow } = await readClaudeSettings(path);
+    const added = rules.filter((rule) => !allow.includes(rule));
+    if (write && added.length > 0)
+        await writeAtomically(path, `${JSON.stringify({ ...settings, permissions: { ...permissions, allow: [...allow, ...added] } }, null, 2)}\n`);
+    return { agent, path, rules, changed: added, wrote: write && added.length > 0 };
+}
+/** Remove exactly the rules Summer adds (Claude Code), or Summer's own rules file (Codex). Writes nothing unless `write`. */
+export async function removeAllowRules(agent, path, write) {
+    if (agent === "codex") {
+        const ours = existsSync(path) && (await readFile(path, "utf8")).startsWith("# Written by summer setup codex");
+        if (write && ours)
+            await rm(path);
+        return { agent, path, rules: [], changed: ours ? [path] : [], wrote: write && ours };
+    }
+    if (!existsSync(path))
+        return { agent, path, rules: [], changed: [], wrote: false };
+    const ours = new Set(claudeAllowRules());
+    const { settings, permissions, allow } = await readClaudeSettings(path);
+    const removed = allow.filter((rule) => typeof rule === "string" && ours.has(rule));
+    if (write && removed.length > 0) {
+        await writeAtomically(path, `${JSON.stringify({ ...settings, permissions: { ...permissions, allow: allow.filter((rule) => !removed.includes(rule)) } }, null, 2)}\n`);
+    }
+    return { agent, path, rules: [], changed: removed, wrote: write && removed.length > 0 };
+}

package/dist/installer/setup.d.ts

@@ -38,6 +38,8 @@ export interface SkillSetupOptions {
     stableOnly?: boolean;
     /** Install only the asset skills (`setup --assets-only`). */
     assetsOnly?: boolean;
+    /** false: no Claude Code slash commands (`setup --cli`; they start work through the MCP tools). */
+    commands?: boolean;
 }
 /**
  * The preview clause of the setup summary — one wording for the result message

package/dist/installer/setup.js

@@ -44,6 +44,7 @@ export function setupSkills(agent, options) {
         recommended,
         stableOnly,
         assetsOnly,
+        commands: options.commands !== false,
     });
     if (!invocation) {
         return {
@@ -145,6 +146,8 @@ function skillInstallInvocation(agent, opts) {
         baseArgs.push("--force");
     if (opts.stableOnly)
         baseArgs.push("--stable-only");
+    if (!opts.commands)
+        baseArgs.push("--no-commands");
     return {
         command,
         args: [...prefix, ...baseArgs],

package/dist/installer/skills-refresh.d.ts

@@ -0,0 +1,29 @@
+import { type SkillRegistryEntry } from "../core/skills-registry.js";
+export interface RefreshedFolder {
+    dir: string;
+    from: string;
+    to: string;
+    /** Skills replaced with this version's copy. */
+    updated: string[];
+    /** New library skills added to a full install. */
+    added: string[];
+    /** Summer's skills someone changed after install: left as they are. */
+    kept: string[];
+}
+export interface RefreshFailure {
+    dir: string;
+    skill?: string;
+    code: string;
+}
+export interface RefreshResult {
+    refreshed: RefreshedFolder[];
+    failures: RefreshFailure[];
+}
+/** User-scope skill folders with one folder per skill, each listed once. */
+export declare function skillFolderLocations(): string[];
+export declare function refreshInstalledSkills(cliVersion: string, options?: {
+    dirs?: string[];
+    registry?: readonly SkillRegistryEntry[];
+}): RefreshResult;
+/** The one message a person and their agent see after a refresh, or null when nothing changed. */
+export declare function refreshNotice(refreshed: readonly RefreshedFolder[], failures?: readonly RefreshFailure[]): string | null;

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;