summer-engine 3.8.0 → 4.2.0

package/dist/installer/agent-table.js

@@ -54,7 +54,8 @@ function appData(ctx) {
     return ctx.env.APPDATA ?? join(ctx.home, "AppData", "Roaming");
 }
 function xdgConfig(ctx) {
-    return ctx.env.XDG_CONFIG_HOME ?? join(ctx.home, ".config");
+    // An empty XDG_CONFIG_HOME counts as unset (XDG Base Directory spec).
+    return ctx.env.XDG_CONFIG_HOME || join(ctx.home, ".config");
 }
 /** ~/.config on Linux, %APPDATA% on Windows, ~/Library/Application Support on macOS. */
 function appConfigRoot(ctx) {
@@ -130,7 +131,7 @@ const SPECS = [
         },
         restart: "Quit and reopen Claude Desktop; the summer-engine tools appear under the tools menu in a new chat.",
         skills: null,
-        noSkillsNote: "Claude Desktop has no skills folder. The MCP server ships summer_get_agent_playbook, so the model can pull Summer guidance in-chat.",
+        noSkillsNote: "Claude Desktop has no skills folder. The MCP server ships summer_docs_search and summer_docs_read, so the model can pull Summer guidance in-chat.",
     },
     {
         id: "codex",
@@ -144,7 +145,8 @@ const SPECS = [
             signIn: (name) => `In Codex, run /mcp login ${name} (or \`codex mcp login ${name}\` in a terminal) and sign in.`,
         },
         mcp: {
-            user: home(".codex", "config.toml"),
+            // Codex reads its config from $CODEX_HOME (default ~/.codex).
+            user: (ctx) => join(ctx.env.CODEX_HOME || join(ctx.home, ".codex"), "config.toml"),
             project: project(".codex", "config.toml"),
             projectNote: "Codex only loads project .codex/config.toml from trusted projects.",
         },
@@ -182,8 +184,10 @@ const SPECS = [
             signIn: (name) => `Devin Desktop opens summer.games in your browser the first time ${name} connects; sign in there.`,
         },
         mcp: {
-            user: home(".codeium", "windsurf", "mcp_config.json"),
+            // docs.devin.ai/desktop/cascade/mcp (2026-10-16): ~/.config/devin (or $XDG_CONFIG_HOME/devin), %APPDATA%\devin on Windows.
+            user: (ctx) => join(xdgOrAppData(ctx), "devin", "mcp_config.json"),
             project: null,
+            movedFrom: home(".codeium", "windsurf", "mcp_config.json"),
         },
         restart: "Restart Devin Desktop (formerly Windsurf) and refresh MCP servers from the agent settings. Devin's docs say mcp_config.json configures the Cascade agent; for the Devin agent add the server in the app's MCP settings with the same command.",
         skills: sharedSkills({ legacyDirs: { user: home(".codeium", "windsurf", "skills"), project: project(".windsurf", "skills") } }),
@@ -316,6 +320,8 @@ const SPECS = [
         status: "active",
         envOverride: "SUMMER_VSCODE_COPILOT_CONFIG_FILE",
         format: "json-vscode",
+        // VS Code Copilot sends at most 128 tools per request; the full surface is over that.
+        mcpProfile: "engine",
         remoteMcp: {
             entry: (url) => ({ type: "http", url }),
             signIn: (name) => `In VS Code, click Allow when ${name} asks to authenticate, then sign in on summer.games.`,
@@ -335,7 +341,7 @@ const SPECS = [
         mcp: { user: home(".mcp.json"), project: project(".mcp.json") },
         restart: "Restart Visual Studio, open Copilot Chat in Agent mode, and enable summer-engine in the tools picker.",
         skills: null,
-        noSkillsNote: "Visual Studio's Copilot has no skills folder yet; the MCP server ships summer_get_agent_playbook for in-chat guidance.",
+        noSkillsNote: "Visual Studio's Copilot has no skills folder yet; the MCP server ships summer_docs_search and summer_docs_read for in-chat guidance.",
     },
     {
         id: "copilot-jetbrains",
@@ -354,7 +360,7 @@ const SPECS = [
         },
         restart: "Restart the JetBrains IDE and open Copilot Chat in Agent mode; summer-engine shows in the tools list.",
         skills: null,
-        noSkillsNote: "Copilot in JetBrains documents no skills folder; the MCP server ships summer_get_agent_playbook for in-chat guidance.",
+        noSkillsNote: "Copilot in JetBrains documents no skills folder; the MCP server ships summer_docs_search and summer_docs_read for in-chat guidance.",
     },
     {
         id: "opencode",
@@ -476,7 +482,7 @@ const SPECS = [
         },
         restart: "Restart Trae and open the MCP settings; summer-engine should show as connected.",
         skills: null,
-        noSkillsNote: "Trae documents no skills folder; the MCP server ships summer_get_agent_playbook for in-chat guidance.",
+        noSkillsNote: "Trae documents no skills folder; the MCP server ships summer_docs_search and summer_docs_read for in-chat guidance.",
     },
     {
         id: "qwen-code",
@@ -570,7 +576,7 @@ const SPECS = [
         mcp: { user: home(".junie", "mcp", "mcp.json"), project: project(".junie", "mcp", "mcp.json") },
         restart: "Restart the JetBrains IDE so Junie reloads its MCP config.",
         skills: null,
-        noSkillsNote: "Junie has no skills folder; put project guidance in .junie/guidelines.md. The MCP server ships summer_get_agent_playbook for in-chat guidance.",
+        noSkillsNote: "Junie has no skills folder; put project guidance in .junie/guidelines.md. The MCP server ships summer_docs_search and summer_docs_read for in-chat guidance.",
     },
     {
         id: "warp",
@@ -652,7 +658,7 @@ const SPECS = [
         mcp: { user: home(".lmstudio", "mcp.json"), project: null },
         restart: "Open LM Studio, toggle on the summer-engine MCP server in the Program tab, and raise the loaded model's context length to 32k or higher.",
         skills: null,
-        noSkillsNote: "LM Studio has no rules or skills folder. The MCP server ships summer_get_agent_playbook, so the model can pull Summer guidance in-chat.",
+        noSkillsNote: "LM Studio has no rules or skills folder. The MCP server ships summer_docs_search and summer_docs_read, so the model can pull Summer guidance in-chat.",
     },
 ];
 const BY_ID = new Map(SPECS.map((spec) => [spec.id, spec]));
@@ -682,6 +688,24 @@ export function agentAliasMap() {
     }
     return map;
 }
+/**
+ * Why `summer setup <agent> --cli` cannot set this agent up, or null. --cli
+ * installs the skills and no MCP server, so the agent needs a skills folder,
+ * and one that takes SKILL.md files: rule files (Roo Code) and the Gemini
+ * extension assume the MCP tools.
+ */
+export function cliSetupRefusal(spec) {
+    if (!spec.skills) {
+        return `${spec.label} has no skills folder, so --cli has nothing to install. Run summer setup ${spec.id} without --cli for the MCP server.`;
+    }
+    if (spec.format === "json-gemini") {
+        return `Gemini CLI loads Summer's skills only through its extension, which runs the MCP server. Run summer setup ${spec.id} without --cli, or use antigravity.`;
+    }
+    if (spec.skills.kind !== "skill-dir" && spec.skills.kind !== "opencode-skill-dir") {
+        return `${spec.label} gets Summer's skills as rule files that tell it to use the MCP tools. Run summer setup ${spec.id} without --cli.`;
+    }
+    return null;
+}
 export function agentLabel(id) {
     return agentSpec(id).label;
 }

package/dist/installer/cli-permissions.d.ts

@@ -0,0 +1,65 @@
+import type { PathContext, SupportedAgent } from "./agent-table.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 declare const AUTO_ALLOWED_READS: readonly string[];
+export type CliCommand = {
+    words: string[];
+    dryRun: boolean;
+};
+/** The commands allowed without asking: `summer status`, the reviewed reads, and a dry run of every spend in the catalog. */
+export declare function allowedCliCommands(): CliCommand[];
+export declare const LAUNCHERS: ReadonlyArray<readonly string[]>;
+/** Claude Code `permissions.allow` rules, for both launchers. */
+export declare function claudeAllowRules(): string[];
+/** Codex rules: one prefix_rule per launcher, area and kind, the actions as a union. */
+export declare function codexRules(): string;
+export interface AllowRulesResult {
+    agent: SupportedAgent;
+    path: string;
+    /** Every rule Summer wants there (Codex: its patterns); empty for a removal. */
+    rules: string[];
+    /** What this run added, or removed with --remove-allow-rules. */
+    changed: string[];
+    wrote: boolean;
+}
+/** The agents with clean per-command allow rules: Claude Code (settings.json) and Codex (rules files). */
+export declare function supportsAllowRules(agent: SupportedAgent): boolean;
+/**
+ * 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 declare function allowRulesPath(agent: SupportedAgent, scope: "user" | "project", ctx: PathContext): string;
+/**
+ * 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 declare function addAllowRules(agent: SupportedAgent, path: string, write: boolean): Promise<AllowRulesResult>;
+/** Remove exactly the rules Summer adds (Claude Code), or Summer's own rules file (Codex). Writes nothing unless `write`. */
+export declare function removeAllowRules(agent: SupportedAgent, path: string, write: boolean): Promise<AllowRulesResult>;

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

@@ -36,6 +36,10 @@ export interface SkillSetupOptions {
     /** Skip `status: preview` skills. By default they install like any other
      *  skill — preview is a label carried in the skill's guidance, not a gate. */
     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

@@ -37,11 +37,14 @@ export function setupSkills(agent, options) {
     const scope = options.scope ?? "user";
     const recommended = Boolean(options.recommended);
     const stableOnly = Boolean(options.stableOnly);
+    const assetsOnly = Boolean(options.assetsOnly);
     const invocation = skillInstallInvocation(agent, {
         force: options.force,
         scope,
         recommended,
         stableOnly,
+        assetsOnly,
+        commands: options.commands !== false,
     });
     if (!invocation) {
         return {
@@ -49,14 +52,15 @@ export function setupSkills(agent, options) {
             message: "No automatic skill installer is available for this agent yet. Run `summer skills install --all` and point the agent at the installed SKILL.md files.",
         };
     }
-    const { selected, previewIncluded, previewSkipped } = selectSkillsForBulkInstall(getSkillRegistry(), { recommended, stableOnly });
+    const { selected, previewIncluded, previewSkipped } = selectSkillsForBulkInstall(getSkillRegistry(), { recommended, stableOnly, assetsOnly });
     const count = selected.length;
     const note = previewNote({ previewIncluded, previewSkipped });
     const destination = isAgentClient(agent)
         ? describeInstallLocation(resolveInstallLocation(agent, scope))
         : undefined;
-    const subset = recommended ? "recommended " : "";
+    const subset = assetsOnly ? "asset " : recommended ? "recommended " : "";
     if (options.dryRun || !options.yes) {
+        const where = destination ?? "the agent's skills directory";
         return {
             status: "planned",
             command: invocation.display,
@@ -64,7 +68,9 @@ export function setupSkills(agent, options) {
             previewIncluded,
             previewSkipped,
             destination,
-            message: `Would install ${count} ${subset}skills${note ? ` (${note})` : ""} to ${destination ?? "the agent's skills directory"} with: ${invocation.display.join(" ")}`,
+            message: options.dryRun
+                ? `Would install ${count} ${subset}skills${note ? ` (${note})` : ""} to ${where} with: ${invocation.display.join(" ")}`
+                : `Not installed. Run the same setup command again with --yes to install ${count} ${subset}skills${note ? ` (${note})` : ""} to ${where}.`,
         };
     }
     const result = spawnSync(invocation.command, invocation.args, {
@@ -130,7 +136,7 @@ function skillInstallInvocation(agent, opts) {
     const baseArgs = [
         "skills",
         "install",
-        opts.recommended ? "--recommended" : "--all",
+        opts.assetsOnly ? "--assets" : opts.recommended ? "--recommended" : "--all",
         "--agent",
         agent,
         "--scope",
@@ -140,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;