summer-engine 2.8.2 → 3.1.0

package/dist/cli/commands/setup.js

@@ -0,0 +1,158 @@
+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";
+import { agentLabel } from "../../installer/agent-table.js";
+export const setupCommand = new Command("setup")
+    .description("Configure Summer Engine for an AI agent and run diagnostics")
+    .argument("[agent]", `Agent to configure: ${supportedAgents.join(", ")}`)
+    .option("--agent <agent>", `Agent to configure: ${supportedAgents.join(", ")}`)
+    .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 = 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,
+    });
+    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) {
+        console.log(JSON.stringify({
+            ok: doctor.ok && skills.status !== "failed",
+            config,
+            skills,
+            doctor,
+        }, null, 2));
+    }
+    else {
+        printSetupResult(config, skills, doctor);
+    }
+    if (!doctor.ok || skills.status === "failed") {
+        process.exit(1);
+    }
+});
+function printSetupResult(config, skills, doctor) {
+    if (config.print) {
+        console.log(config.snippet.trimEnd());
+        return;
+    }
+    console.log("");
+    console.log(brandLine(cliVersion));
+    console.log("");
+    const label = agentLabel(config.agent);
+    if (config.dryRun) {
+        console.log(`  ${c.dim("(dry run)")}  Would link to ${label}  ${c.dim(tildeify(config.path))}`);
+    }
+    else if (config.wrote) {
+        console.log(`  ${sym.ok()}  Linked to ${c.bold(label)}  ${c.dim(tildeify(config.path))}`);
+    }
+    else {
+        console.log(`  ${sym.ok()}  Already linked to ${c.bold(label)}  ${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);
+            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] ?? [];
+                rows[row].push(name);
+                return rows;
+            }, []);
+            for (const row of grouped) {
+                console.log(`     ${c.dim(row.join(" · "))}`);
+            }
+        }
+        else {
+            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)}`);
+    }
+    else if (skills.status === "failed") {
+        console.log(`  ${sym.fail()}  Skills install failed`);
+        if (skills.stderr)
+            console.log(`     ${c.dim(skills.stderr)}`);
+    }
+    for (const warning of config.warnings) {
+        console.log(`  ${sym.warn()}  ${c.yellow(warning)}`);
+    }
+    console.log("");
+    printDoctorResult(doctor);
+    if (doctor.ok && skills.status !== "failed" && !config.dryRun) {
+        console.log("");
+        console.log(`${c.dim("Try it:")} open ${label} and ask: ${c.bold("\"add a DirectionalLight3D and Camera3D to my scene\"")}`);
+    }
+}
+function parseInstalledSkills(stdout) {
+    if (!stdout)
+        return [];
+    // Lines look like: "  Installed fps-controller -> /path/.../fps-controller"
+    const names = [];
+    for (const line of stdout.split("\n")) {
+        const m = line.match(/^\s*(?:Installed|Updated|Generated)\s+([a-z0-9-]+)\s+->/i);
+        if (m)
+            names.push(m[1]);
+    }
+    return names;
+}
+function parseSkillTargetDir(stdout) {
+    if (!stdout)
+        return null;
+    for (const line of stdout.split("\n")) {
+        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
+            const parent = path.replace(/\/[a-z0-9-]+$/i, "/");
+            return parent;
+        }
+    }
+    return null;
+}

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

@@ -1,244 +1,65 @@
-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 { agentLabel as tableAgentLabel, agentSpec, defaultPathContext, legacyRuleFiles } from "../../installer/agent-table.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) {
-        case "claude-code":
-            return "Claude Code";
-        case "codex":
-            return "Codex";
-        case "cursor":
-            return "Cursor";
-        case "windsurf":
-            return "Devin Desktop (Windsurf)";
-        case "cline":
-            return "Cline";
-        case "roo-code":
-            return "Roo Code";
-        case "kilo-code":
-            return "Kilo Code";
-        case "gemini":
-            return "Gemini CLI";
-        case "github-copilot":
-            return "GitHub Copilot CLI";
-        case "vscode-copilot":
-            return "GitHub Copilot in VS Code";
-        case "opencode":
-            return "OpenCode";
-        case "summer":
-            return "Summer";
-    }
+    return agent === "summer" ? "Summer" : tableAgentLabel(agent);
 }
-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 previewSkippedLine(count) {
+    return `  Skipped ${count} preview skill${count === 1 ? "" : "s"} (--stable-only).`;
 }
-function clineUserRulesDir() {
-    // Cline reads global rules from the user's Documents/Cline/Rules folder.
-    return join(homedir(), "Documents", "Cline", "Rules");
-}
-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 +69,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 +90,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 +102,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 +112,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 +122,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 +159,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
@@ -381,8 +195,11 @@ function printInstallSummary(count, agent, scope, location) {
     const label = agentLabel(agent);
     const tildeified = tildeify(location.path);
     console.log(`\n${count} skill${count === 1 ? "" : "s"} ready for ${label} (${scope} scope).`);
+    const reloadHint = agent === "summer" ? undefined : agentSpec(agent).skills?.reloadHint;
     if (location.kind === "skill-dir") {
         console.log(`${label} can read skills from ${tildeified}/<skill>/SKILL.md`);
+        if (reloadHint)
+            console.log(reloadHint);
     }
     else if (location.kind === "cursor-rule-dir") {
         console.log(`Cursor rules are in ${tildeified}/summer-<skill>.mdc`);
@@ -391,10 +208,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.");
@@ -411,16 +224,40 @@ export const skillsCommand = new Command("skills")
 skillsCommand
     .command("list")
     .description("List available skills")
-    .action(() => {
+    .option("--by-domain", "Group skills by their primary domain (same grouping as library/skills/README.md)")
+    .action((opts) => {
     const skills = getBuiltinSkills();
     if (skills.length === 0) {
         console.log("No skills found.");
         return;
     }
-    console.log("Available public skills:\n");
-    for (const s of skills) {
+    const line = (s) => {
         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] " : "";
+        return `  ${s.name.padEnd(24)} ${badge.padEnd(11)} ${tag}${s.description}`;
+    };
+    if (opts.byDomain) {
+        const groups = new Map();
+        for (const s of skills) {
+            const primary = s.domains[0] ?? "uncategorised";
+            groups.set(primary, [...(groups.get(primary) ?? []), s]);
+        }
+        console.log(`${skills.length} skills by primary domain (full index: library/skills/README.md):`);
+        for (const domain of [...groups.keys()].sort()) {
+            const group = groups.get(domain);
+            console.log(`\n${domain} (${group.length})`);
+            for (const s of group)
+                console.log(line(s));
+        }
+    }
+    else {
+        console.log("Available public skills:\n");
+        for (const s of skills)
+            console.log(line(s));
+    }
+    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 +267,61 @@ 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)`);
+        }
+        // Agents that moved from generated rule files to SKILL.md skills in 3.1
+        // (Cursor, OpenCode): drop the rule files 3.0 wrote so the agent does not
+        // load both for the same slug. Only files with Summer's own naming go.
+        if (agent !== "summer" && !process.env.SUMMER_SKILLS_DIR) {
+            const legacy = legacyRuleFiles(agentSpec(agent), scope, defaultPathContext(), skills.map((skill) => skill.name)) ?? [];
+            for (const file of legacy) {
+                if (!existsSync(file))
+                    continue;
+                rmSync(file, { force: true });
+                console.log(`  Removed ${tildeify(file)} (rule file from Summer 3.0; now a skill)`);
+            }
+        }
+    }
+    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 +397,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");