summer-engine 2.8.1 → 3.0.0

package/dist/{commands → cli/commands}/setup.js

@@ -1,11 +1,10 @@
-import { spawnSync } from "child_process";
-import { createRequire } from "node:module";
-import { Command } from "commander";
-import { configureAgentMcp, parseAgent, parseScope, supportedAgents, } from "../lib/agent-config.js";
-import { printDoctorResult, runDoctor } from "./doctor.js";
-import { brandLine, c, sym, tildeify } from "../lib/format.js";
-const requireFromHere = createRequire(import.meta.url);
-const { version: cliVersion } = requireFromHere("../../package.json");
+import { Command, Option } from "commander";
+import { configureAgentMcp, resolveAgentSelection, resolveConfigScope, supportedAgents, } from "../../installer/agent-config.js";
+import { previewNote, setupSkills } from "../../installer/setup.js";
+import { printDoctorResult, runDoctor } from "../../core/capabilities/doctor.js";
+import { brandLine, c, sym, tildeify } from "../../core/format.js";
+import { TOOLKIT_VERSION as cliVersion } from "../../core/version.js";
+import { resolveDefaultChannel } from "../../installer/version-check.js";
 const AGENT_LABEL = {
     "claude-code": "Claude Code",
     codex: "Codex",
@@ -27,22 +26,37 @@ export const setupCommand = new Command("setup")
     .option("--scope <scope>", "Configuration scope: user or project", "user")
     .option("--dry-run", "Show planned changes without writing files")
     .option("--print", "Print the MCP config snippet instead of writing files")
+    .option("--local-dev", "Point the agent at this checkout's built CLI (node <repo>/dist/bin/summer.js mcp) instead of npx summer-engine@latest — for testing unpublished builds. SUMMER_DEV=1 does the same.")
+    .option("--channel <dist-tag>", "npm dist-tag the agent's MCP entry runs: npx -y summer-engine@<dist-tag> mcp (default latest; use next while a release soaks on the next tag). SUMMER_CHANNEL does the same.")
     .option("--yes", "Apply practical setup steps without prompting")
     .option("--json", "Print setup result as JSON")
     .option("--force", "Overwrite existing skill content (passes --force through to skills install)")
+    .option("--recommended", "Install only the recommended skill subset instead of the whole library")
+    .option("--stable-only", "Skip preview skills (installed by default; each is labelled preview in its guidance)")
+    // Pre-reversal opt-in, kept one release as a hidden no-op so old scripts still parse.
+    .addOption(new Option("--include-preview", "No-op: preview skills install by default").hideHelp())
     .action(async (agentArg, opts) => {
-    const agent = resolveAgent(agentArg, opts.agent);
-    const scope = resolveScope(opts.scope);
+    const agent = resolveAgentSelection(agentArg, opts.agent);
+    const scope = resolveConfigScope(opts.scope);
+    const defaultChannel = await resolveDefaultChannel(cliVersion);
     const config = await configureAgentMcp({
         agent,
         scope,
         dryRun: opts.dryRun,
         print: opts.print,
+        localDev: Boolean(opts.localDev) || process.env.SUMMER_DEV === "1",
+        channel: opts.channel ?? process.env.SUMMER_CHANNEL ?? defaultChannel.channel,
     });
-    const skills = setupRecommendedSkills(agent, {
+    if (!opts.channel && !process.env.SUMMER_CHANNEL && defaultChannel.note && !opts.print) {
+        console.log(`  ${c.dim(defaultChannel.note)}`);
+    }
+    const skills = setupSkills(agent, {
         dryRun: Boolean(opts.dryRun || opts.print),
         yes: Boolean(opts.yes),
         force: Boolean(opts.force),
+        scope,
+        recommended: Boolean(opts.recommended),
+        stableOnly: Boolean(opts.stableOnly),
     });
     const doctor = await runDoctor({ quiet: true });
     if (opts.json) {
@@ -60,80 +74,6 @@ export const setupCommand = new Command("setup")
         process.exit(1);
     }
 });
-function resolveAgent(agentArg, agentOpt) {
-    if (agentArg && agentOpt && parseAgent(agentArg) !== parseAgent(agentOpt)) {
-        throw new Error("Specify the agent either positionally or with --agent, not both.");
-    }
-    const parsed = parseAgent(agentOpt ?? agentArg);
-    if (!parsed) {
-        throw new Error(`Specify an agent: ${supportedAgents.join(", ")}`);
-    }
-    return parsed;
-}
-function resolveScope(scopeOpt) {
-    const parsed = parseScope(scopeOpt);
-    if (!parsed) {
-        throw new Error("Invalid --scope. Use user or project.");
-    }
-    return parsed;
-}
-function setupRecommendedSkills(agent, options) {
-    if (agent === "lm-studio") {
-        return {
-            status: "skipped",
-            message: "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.",
-        };
-    }
-    const invocation = skillInstallInvocation(agent, { force: options.force });
-    if (!invocation) {
-        return {
-            status: "skipped",
-            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.",
-        };
-    }
-    if (options.dryRun || !options.yes) {
-        return {
-            status: "planned",
-            command: invocation.display,
-            message: `Recommended skills can be installed with: ${invocation.display.join(" ")}`,
-        };
-    }
-    const result = spawnSync(invocation.command, invocation.args, {
-        env: process.env,
-        encoding: "utf-8",
-    });
-    if (result.status === 0) {
-        return {
-            status: "installed",
-            command: invocation.display,
-            message: "Recommended Summer skills installed.",
-            stdout: result.stdout.trim(),
-            stderr: result.stderr.trim(),
-        };
-    }
-    return {
-        status: "failed",
-        command: invocation.display,
-        message: `Recommended skill install failed with exit code ${result.status ?? "unknown"}.`,
-        stdout: result.stdout.trim(),
-        stderr: result.stderr.trim(),
-    };
-}
-function skillInstallInvocation(agent, opts = { force: false }) {
-    const cliPath = process.argv[1];
-    if (!cliPath)
-        return null;
-    const command = cliPath.endsWith(".js") ? process.execPath : cliPath;
-    const prefix = cliPath.endsWith(".js") ? [cliPath] : [];
-    const baseArgs = ["skills", "install", "--recommended", "--agent", agent];
-    if (opts.force)
-        baseArgs.push("--force");
-    return {
-        command,
-        args: [...prefix, ...baseArgs],
-        display: [cliPath, ...baseArgs],
-    };
-}
 function printSetupResult(config, skills, doctor) {
     if (config.print) {
         console.log(config.snippet.trimEnd());
@@ -152,11 +92,21 @@ function printSetupResult(config, skills, doctor) {
     else {
         console.log(`  ${sym.ok()}  Already linked to ${c.bold(agentLabel)}  ${c.dim(tildeify(config.path))}`);
     }
+    if (config.localDev) {
+        console.log(`  ${c.dim("(local dev)")}  MCP server command: ${c.dim(`${config.server.command} ${config.server.args.join(" ")}`)}`);
+    }
+    else if (config.channel !== "latest") {
+        console.log(`  ${c.dim(`(channel ${config.channel})`)}  MCP server command: ${c.dim(`${config.server.command} ${config.server.args.join(" ")}`)}`);
+    }
     if (skills.status === "installed") {
         const installed = parseInstalledSkills(skills.stdout);
         if (installed.length > 0) {
             const where = parseSkillTargetDir(skills.stdout);
-            console.log(`  ${sym.ok()}  Installed ${c.bold(String(installed.length) + " skills")}  ${where ? c.dim(tildeify(where)) : ""}`);
+            const note = previewNote(skills);
+            const tally = skills.installed
+                ? c.dim(` (${skills.installed.added} new, ${skills.installed.updated} updated${note ? `; ${note}` : ""})`)
+                : "";
+            console.log(`  ${sym.ok()}  Installed ${c.bold(String(installed.length) + " skills")}${tally}  ${where ? c.dim(tildeify(where)) : ""}`);
             const grouped = installed.reduce((rows, name, i) => {
                 const row = Math.floor(i / 3);
                 rows[row] = rows[row] ?? [];
@@ -168,9 +118,13 @@ function printSetupResult(config, skills, doctor) {
             }
         }
         else {
-            console.log(`  ${sym.ok()}  Installed recommended skills`);
+            console.log(`  ${sym.ok()}  ${skills.message}`);
         }
     }
+    else if (skills.status === "planned" && config.dryRun) {
+        const note = previewNote(skills);
+        console.log(`  ${c.dim("(dry run)")}  Would install ${c.bold(String(skills.count ?? "?") + " skills")}${note ? c.dim(` (${note})`) : ""}  ${c.dim(skills.destination ?? "")}`);
+    }
     else if (skills.status === "planned" || skills.status === "skipped") {
         console.log(`  ${sym.warn()}  Skills: ${c.dim(skills.message)}`);
     }
@@ -195,7 +149,7 @@ function parseInstalledSkills(stdout) {
     // Lines look like: "  Installed fps-controller -> /path/.../fps-controller"
     const names = [];
     for (const line of stdout.split("\n")) {
-        const m = line.match(/^\s*Installed\s+([a-z0-9-]+)\s+->/i);
+        const m = line.match(/^\s*(?:Installed|Updated|Generated)\s+([a-z0-9-]+)\s+->/i);
         if (m)
             names.push(m[1]);
     }
@@ -205,7 +159,7 @@ function parseSkillTargetDir(stdout) {
     if (!stdout)
         return null;
     for (const line of stdout.split("\n")) {
-        const m = line.match(/^\s*Installed\s+[a-z0-9-]+\s+->\s+(.+)$/i);
+        const m = line.match(/^\s*(?:Installed|Updated|Generated)\s+[a-z0-9-]+\s+->\s+(.+)$/i);
         if (m) {
             const path = m[1].trim();
             // Strip trailing /<skill-name> to get the parent dir

package/dist/{commands → cli/commands}/skills.js

@@ -1,123 +1,55 @@
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { existsSync, mkdirSync, readFileSync, cpSync, rmSync, writeFileSync, readdirSync, copyFileSync, } from "fs";
 import { join, dirname } from "path";
-import { fileURLToPath } from "url";
-import { homedir, platform } from "os";
-import { createRequire } from "node:module";
-import { AGENT_CLIENTS, SKILL_REGISTRY, } from "../lib/skills-registry.js";
-import { tildeify } from "../lib/format.js";
-import { writeSkillMarker } from "../lib/version-check.js";
-const requireFromHere = createRequire(import.meta.url);
-const { version: cliVersion } = requireFromHere("../../package.json");
-const __dirname = dirname(fileURLToPath(import.meta.url));
-// Resolve skills dir: from dist/commands/skills.js -> ../../skills
-const skillsDir = join(__dirname, "..", "..", "skills");
-// Resolve commands dir: same parent. Used by Claude Code installs to also copy
+import { homedir } from "os";
+import { AGENT_CLIENTS, getSkillRegistry, resolveSkillDir, selectSkillsForBulkInstall, } from "../../core/skills-registry.js";
+import { tildeify } from "../../core/format.js";
+import { writeSkillMarker } from "../../installer/version-check.js";
+import { pruneRetiredSkills } from "../../installer/legacy-skills.js";
+import { resolveInstallLocation, resolveSkillAgent, resolveSkillScope, } from "../../installer/skill-locations.js";
+import { PACKAGE_ROOT } from "../../core/package-root.js";
+import { TOOLKIT_VERSION as cliVersion } from "../../core/version.js";
+// Skill files live in library/skills/<slug>/ and are resolved through the
+// generated registry (registry/generated/skills-registry.json).
+// Resolve commands dir: from dist/cli/commands/skills.js -> ../../../commands.
+// Used by Claude Code installs to also copy
 // slash commands (e.g. /gameskill) to ~/.claude/commands/. Other agents don't
 // have an equivalent today, so the copy is gated to claude-code.
-const commandsDir = join(__dirname, "..", "..", "commands");
-const SKILL_SCOPES = ["user", "project"];
+const commandsDir = join(PACKAGE_ROOT, "commands");
 function getBuiltinSkills() {
-    const skills = [];
-    for (const entry of SKILL_REGISTRY) {
-        if (!entry.public)
-            continue;
-        const skillPath = join(skillsDir, entry.category, entry.name, "SKILL.md");
-        if (!existsSync(skillPath))
-            continue;
-        const frontmatter = parseSkillFrontmatter(skillPath);
-        if (!frontmatter)
-            continue;
-        skills.push({
-            ...entry,
-            name: entry.name,
-            description: frontmatter.description,
-        });
-    }
-    return skills;
-}
-function parseSkillFrontmatter(skillPath) {
-    try {
-        const content = readFileSync(skillPath, "utf-8");
-        const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
-        if (!match)
-            return null;
-        const front = match[1];
-        const name = front.match(/^name:\s*(.+)$/m)?.[1]?.trim();
-        const description = front.match(/^description:\s*(.+)$/m)?.[1]?.trim();
-        if (!name || !description)
-            return null;
-        return { name, description };
-    }
-    catch {
-        return null;
-    }
+    return getSkillRegistry().filter((entry) => existsSync(join(resolveSkillDir(entry), "SKILL.md")));
 }
 function getSkillMeta(name) {
     return getBuiltinSkills().find((skill) => skill.name === name) ?? null;
 }
 function getSkillPath(name) {
-    const entry = SKILL_REGISTRY.find((s) => s.name === name);
+    const entry = getSkillRegistry().find((s) => s.name === name);
     if (!entry)
         return null;
-    const path = join(skillsDir, entry.category, entry.name);
+    const path = resolveSkillDir(entry);
     if (!existsSync(path) || !existsSync(join(path, "SKILL.md")))
         return null;
     return path;
 }
 function getSkillBody(name) {
-    const entry = SKILL_REGISTRY.find((s) => s.name === name);
-    if (!entry)
+    const path = getSkillPath(name);
+    if (!path)
         throw new Error(`Unknown skill: ${name}`);
-    const skillPath = join(skillsDir, entry.category, entry.name, "SKILL.md");
-    const content = readFileSync(skillPath, "utf-8");
+    const content = readFileSync(join(path, "SKILL.md"), "utf-8");
     return content.replace(/^---\s*\n[\s\S]*?\n---\s*\n/, "").trim();
 }
 function die(message) {
     console.error(message);
     process.exit(1);
 }
-function isAgentClient(value) {
-    return AGENT_CLIENTS.includes(value);
-}
-function isSkillScope(value) {
-    return SKILL_SCOPES.includes(value);
-}
-function parseAgent(value) {
-    if (isAgentClient(value))
-        return value;
-    die(`Unknown agent: ${value}. Use one of: ${AGENT_CLIENTS.join(", ")}.`);
-}
-function parseScope(value) {
-    if (isSkillScope(value))
-        return value;
-    die(`Unknown scope: ${value}. Use user or project.`);
-}
-function resolveAgent(opts) {
-    if (opts.asClaudeSkill && opts.asCursorSkill) {
-        die("Use only one legacy alias: --as-claude-skill or --as-cursor-skill.");
-    }
-    const legacyAgent = opts.asClaudeSkill
-        ? "claude-code"
-        : opts.asCursorSkill
-            ? "cursor"
-            : undefined;
-    if (opts.agent && legacyAgent && opts.agent !== legacyAgent) {
-        die(`Conflicting agent options: --agent ${opts.agent} with legacy alias for ${legacyAgent}.`);
+/** Run an installer-layer option parser; its Error message becomes the CLI's exit line. */
+function orDie(parse) {
+    try {
+        return parse();
     }
-    return parseAgent(opts.agent ?? legacyAgent ?? "summer");
-}
-function resolveScope(agent, opts) {
-    if (opts.scope)
-        return parseScope(opts.scope);
-    if (agent === "cursor" ||
-        agent === "windsurf" ||
-        agent === "cline" ||
-        agent === "roo-code" ||
-        agent === "kilo-code") {
-        return "project";
+    catch (error) {
+        die(error instanceof Error ? error.message : String(error));
     }
-    return "user";
 }
 function agentLabel(agent) {
     switch (agent) {
@@ -147,98 +79,11 @@ function agentLabel(agent) {
             return "Summer";
     }
 }
-function resolveInstallLocation(agent, scope) {
-    const overrideDir = process.env.SUMMER_SKILLS_DIR;
-    if (overrideDir) {
-        if (agent === "cursor")
-            return { kind: "cursor-rule-dir", path: overrideDir };
-        if (agent === "windsurf") {
-            return { kind: "windsurf-rule-file", path: join(overrideDir, ".windsurfrules") };
-        }
-        if (agent === "cline" || agent === "roo-code" || agent === "kilo-code") {
-            return { kind: "cline-rule-dir", path: overrideDir };
-        }
-        if (agent === "gemini") {
-            return { kind: "gemini-skill-dir", path: overrideDir };
-        }
-        if (agent === "opencode") {
-            return { kind: "opencode-skill-dir", path: overrideDir };
-        }
-        return { kind: "skill-dir", path: overrideDir };
-    }
-    const root = scope === "user" ? homedir() : process.cwd();
-    switch (agent) {
-        case "codex":
-            return { kind: "skill-dir", path: join(root, ".agents", "skills") };
-        case "claude-code":
-            return { kind: "skill-dir", path: join(root, ".claude", "skills") };
-        case "cursor":
-            return { kind: "cursor-rule-dir", path: join(root, ".cursor", "rules") };
-        case "windsurf":
-            return { kind: "windsurf-rule-file", path: join(root, ".windsurfrules") };
-        case "cline":
-            return {
-                kind: "cline-rule-dir",
-                path: scope === "user"
-                    ? clineUserRulesDir()
-                    : join(process.cwd(), ".clinerules"),
-            };
-        case "roo-code":
-            return {
-                kind: "cline-rule-dir",
-                path: scope === "user"
-                    ? rooCodeUserRulesDir()
-                    : join(process.cwd(), ".clinerules"),
-            };
-        case "kilo-code":
-            return {
-                kind: "cline-rule-dir",
-                path: scope === "user"
-                    ? join(homedir(), ".kilocode", "rules")
-                    : join(process.cwd(), ".kilocode", "rules"),
-            };
-        case "gemini":
-            return {
-                kind: "gemini-skill-dir",
-                path: join(homedir(), ".gemini", "extensions", "summer-engine", "skills"),
-            };
-        case "github-copilot":
-        case "vscode-copilot":
-            return {
-                kind: "skill-dir",
-                path: scope === "user"
-                    ? join(homedir(), ".copilot", "skills")
-                    : join(process.cwd(), ".github", "skills"),
-            };
-        case "opencode":
-            return {
-                kind: "opencode-skill-dir",
-                path: scope === "user"
-                    ? opencodeUserAgentsDir()
-                    : join(process.cwd(), ".opencode", "agents", "summer"),
-            };
-        case "summer":
-            return { kind: "skill-dir", path: join(root, ".summer", "skills") };
-    }
-}
-function clineUserRulesDir() {
-    // Cline reads global rules from the user's Documents/Cline/Rules folder.
-    return join(homedir(), "Documents", "Cline", "Rules");
+function previewSkippedLine(count) {
+    return `  Skipped ${count} preview skill${count === 1 ? "" : "s"} (--stable-only).`;
 }
-function rooCodeUserRulesDir() {
-    // Roo Code reads global rules from the user's Documents/Roo/Rules folder.
-    return join(homedir(), "Documents", "Roo", "Rules");
-}
-function opencodeUserAgentsDir() {
-    // OpenCode's user-scope agent definition directory varies by OS.
-    // On Windows, OpenCode reads from %APPDATA%/opencode/agents/summer.
-    // On Linux/macOS, it reads from $XDG_CONFIG_HOME or ~/.config/opencode/agents/summer.
-    if (platform() === "win32") {
-        const appData = process.env.APPDATA ?? join(homedir(), "AppData", "Roaming");
-        return join(appData, "opencode", "agents", "summer");
-    }
-    const xdg = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
-    return join(xdg, "opencode", "agents", "summer");
+function previewIncludedLine(count) {
+    return `  ${count} preview skill${count === 1 ? "" : "s"} included — labelled in ${count === 1 ? "its" : "each skill's"} guidance; add --stable-only to skip.`;
 }
 function selectSkills(name, opts) {
     if (opts.all && opts.recommended) {
@@ -248,10 +93,16 @@ function selectSkills(name, opts) {
         die("Specify either a skill name or a bulk option, not both.");
     }
     const skills = getBuiltinSkills();
-    if (opts.all)
-        return skills;
-    if (opts.recommended)
-        return skills.filter((skill) => skill.recommended);
+    if (opts.all || opts.recommended) {
+        // Bulk installs take stable and preview skills (preview is a label, not a
+        // gate); --stable-only skips preview. An explicit name below installs
+        // regardless of status.
+        const { selected, previewIncluded, previewSkipped } = selectSkillsForBulkInstall(skills, {
+            recommended: Boolean(opts.recommended),
+            stableOnly: Boolean(opts.stableOnly),
+        });
+        return { skills: selected, previewIncluded, previewSkipped };
+    }
     if (!name) {
         console.error("Specify a skill name, --recommended, or --all.");
         printAvailableSkillNames();
@@ -263,7 +114,7 @@ function selectSkills(name, opts) {
         printAvailableSkillNames();
         process.exit(1);
     }
-    return [skill];
+    return { skills: [skill], previewIncluded: 0, previewSkipped: 0 };
 }
 function printAvailableSkillNames() {
     const skills = getBuiltinSkills();
@@ -275,9 +126,7 @@ function printAvailableSkillNames() {
     }
 }
 function installSkill(skill, agent, location, options) {
-    if (!skill.clients.includes(agent)) {
-        die(`${skill.name} does not support ${agentLabel(agent)}.`);
-    }
+    // Every library skill supports every agent client (registry clients: "all").
     switch (location.kind) {
         case "skill-dir":
             return copySkillDirectory(skill, location.path, options);
@@ -287,8 +136,6 @@ function installSkill(skill, agent, location, options) {
             return upsertWindsurfRule(skill, location.path);
         case "cline-rule-dir":
             return writeClineRule(skill, location.path);
-        case "gemini-skill-dir":
-            return writeGeminiSkill(skill, location.path);
         case "opencode-skill-dir":
             return writeOpencodeSkill(skill, location.path);
     }
@@ -299,13 +146,14 @@ function copySkillDirectory(skill, targetDir, options) {
         die(`Skill files missing: ${skill.name}`);
     mkdirSync(targetDir, { recursive: true });
     const dest = join(targetDir, skill.name);
-    if (options.force && existsSync(dest)) {
+    const existed = existsSync(dest);
+    if (options.force && existed) {
         // Wipe stale skill content so re-installs overwrite cleanly even if files
         // were renamed or removed upstream.
         rmSync(dest, { recursive: true, force: true });
     }
     cpSync(src, dest, { recursive: true, force: true });
-    return { action: "Installed", path: dest };
+    return { action: existed ? "Updated" : "Installed", path: dest };
 }
 function writeCursorRule(skill, rulesDir) {
     mkdirSync(rulesDir, { recursive: true });
@@ -335,16 +183,6 @@ function writeClineRule(skill, rulesDir) {
     writeFileSync(rulePath, renderRuleBody(skill) + "\n", "utf-8");
     return { action: "Generated", path: rulePath };
 }
-function writeGeminiSkill(skill, skillsDir) {
-    // Gemini extensions support a contextFileName, but skill discovery for
-    // arbitrary markdown is not standardized. We drop each SKILL.md alongside
-    // the extension so the agent can reference them by path; the install
-    // summary surfaces this so the user knows where to point Gemini.
-    mkdirSync(skillsDir, { recursive: true });
-    const rulePath = join(skillsDir, `${skill.name}.md`);
-    writeFileSync(rulePath, renderRuleBody(skill) + "\n", "utf-8");
-    return { action: "Generated", path: rulePath };
-}
 function writeOpencodeSkill(skill, skillsDir) {
     // OpenCode supports agent markdown definitions; the exact discovery
     // convention for ad-hoc skills isn't fully documented. We write each skill
@@ -383,6 +221,9 @@ function printInstallSummary(count, agent, scope, location) {
     console.log(`\n${count} skill${count === 1 ? "" : "s"} ready for ${label} (${scope} scope).`);
     if (location.kind === "skill-dir") {
         console.log(`${label} can read skills from ${tildeified}/<skill>/SKILL.md`);
+        if (agent === "gemini") {
+            console.log("Gemini loads them as extension skills; run `summer setup gemini` once so the extension manifest exists, then restart Gemini CLI.");
+        }
     }
     else if (location.kind === "cursor-rule-dir") {
         console.log(`Cursor rules are in ${tildeified}/summer-<skill>.mdc`);
@@ -391,10 +232,6 @@ function printInstallSummary(count, agent, scope, location) {
         console.log(`${label} rules are in ${tildeified}/summer-<skill>.md`);
         console.log("Restart VS Code to pick up new rules.");
     }
-    else if (location.kind === "gemini-skill-dir") {
-        console.log(`Skill files are in ${tildeified}/<skill>.md`);
-        console.log("Reference them from Gemini by path, or run `gemini extensions enable summer-engine` to load the bundled context.");
-    }
     else if (location.kind === "opencode-skill-dir") {
         console.log(`Skill files are in ${tildeified}/<skill>.md`);
         console.log("Restart OpenCode so it picks up the new agent definitions.");
@@ -420,7 +257,12 @@ skillsCommand
     console.log("Available public skills:\n");
     for (const s of skills) {
         const badge = s.recommended ? "recommended" : "optional";
-        console.log(`  ${s.name.padEnd(20)} ${s.category.padEnd(10)} ${badge.padEnd(11)} ${s.description}`);
+        const tag = s.status === "preview" ? "[preview] " : "";
+        console.log(`  ${s.name.padEnd(24)} ${badge.padEnd(11)} ${tag}${s.description}`);
+    }
+    const previewCount = skills.filter((s) => s.status === "preview").length;
+    if (previewCount > 0) {
+        console.log(`\n[preview] = not yet exercised in-engine by the Summer team (${previewCount}); labelled in the skill's guidance. --all / --recommended and summer setup install these like any other skill — add --stable-only to skip them.`);
     }
     console.log("\nInstall recommended: summer skills install --recommended");
     console.log("Install one:         summer skills install <name>");
@@ -430,27 +272,49 @@ skillsCommand
     .command("install [name]")
     .description("Install Summer skills for a target agent")
     .option("--all", "Install all available skills")
-    .option("--recommended", "Install recommended public skills (excludes make-game)")
+    .option("--recommended", "Install only the recommended skill subset (summer setup installs all by default)")
+    .option("--stable-only", "With --all / --recommended, skip preview skills (installed by default; labelled preview in their guidance)")
     .option("--agent <agent>", `Target agent: ${AGENT_CLIENTS.join("|")}`)
     .option("--scope <scope>", "Install scope: user or project")
-    .option("--as-claude-skill", "Legacy alias for --agent claude-code")
-    .option("--as-cursor-skill", "Legacy alias for --agent cursor")
+    // Legacy aliases: still accepted for old scripts, hidden from --help.
+    .addOption(new Option("--as-claude-skill", "Legacy alias for --agent claude-code").hideHelp())
+    .addOption(new Option("--as-cursor-skill", "Legacy alias for --agent cursor").hideHelp())
+    // Pre-reversal opt-in, kept one release as a hidden no-op so old scripts still parse.
+    .addOption(new Option("--include-preview", "No-op: preview skills install by default").hideHelp())
     .option("--force", "Overwrite existing skill files (wipe stale skill dirs before copying)")
     .action((name, opts) => {
-    const agent = resolveAgent(opts);
-    const scope = resolveScope(agent, opts);
+    const agent = orDie(() => resolveSkillAgent(opts));
+    const scope = orDie(() => resolveSkillScope(agent, opts));
     const location = resolveInstallLocation(agent, scope);
-    const skills = selectSkills(name, opts);
+    const { skills, previewIncluded, previewSkipped } = selectSkills(name, opts);
     if (skills.length === 0) {
         console.log("No skills found.");
+        if (previewSkipped > 0)
+            console.log(previewSkippedLine(previewSkipped));
         return;
     }
     for (const skill of skills) {
         const result = installSkill(skill, agent, location, {
             force: Boolean(opts.force),
         });
+        // Keep this line's shape: setup tallies it (Installed|Updated|Generated <name> -> <path>).
         console.log(`  ${result.action} ${skill.name} -> ${result.path}`);
     }
+    // Upgrades: with --force, remove the skills Summer installed in 2.8.x that
+    // v3 retired or renamed (summer-cloud, the un-prefixed vfx recipes, ...),
+    // so no host keeps a skill that points at removed tools.
+    if (opts.force && !name && (location.kind === "skill-dir" || location.kind === "opencode-skill-dir")) {
+        for (const pruned of pruneRetiredSkills(location.path, getSkillRegistry().map((entry) => entry.name))) {
+            console.log(`  Removed ${pruned.name} -> ${pruned.path} (retired in 3.0.0)`);
+        }
+    }
+    if (name && skills[0]?.status === "preview") {
+        console.log(`  Note: ${name} is a preview skill — not yet exercised in-engine by the Summer team; its guidance says so.`);
+    }
+    if (previewIncluded > 0)
+        console.log(previewIncludedLine(previewIncluded));
+    if (previewSkipped > 0)
+        console.log(previewSkippedLine(previewSkipped));
     // Claude Code: also install slash commands (`tools/summer-cli/commands/*.md`)
     // into `~/.claude/commands/`. Other agents don't have an equivalent today.
     if (agent === "claude-code") {
@@ -526,11 +390,10 @@ skillsCommand
     console.log(`\n${meta.name}`);
     console.log("-".repeat(40));
     console.log(meta.description);
-    console.log(`Category: ${meta.category}`);
+    console.log(`Id: ${meta.id}`);
     console.log(`Recommended: ${meta.recommended ? "yes" : "no"}`);
-    console.log(`Agents: ${meta.clients.join(", ")}`);
-    console.log(`MCP tools: ${meta.requiresMcpTools.length > 0 ? meta.requiresMcpTools.join(", ") : "none"}`);
-    console.log(`Test scenario: ${meta.testScenario}`);
+    console.log(`Status: ${meta.status}`);
+    console.log(`Agents: ${AGENT_CLIENTS.join(", ")}`);
     console.log("\n" + "-".repeat(40));
     const body = content.replace(/^---\s*\n[\s\S]*?\n---\s*\n/, "");
     const preview = body.split("\n").slice(0, 30).join("\n");

package/dist/{commands → cli/commands}/status.d.ts

@@ -1,2 +1,3 @@
 import { Command } from "commander";
 export declare const statusCommand: Command;
+export declare function runStatus(log: (message: string) => void): Promise<void>;