summer-engine 2.8.1 → 3.0.0

package/dist/{lib → installer}/agent-config.js

@@ -1,7 +1,8 @@
-import { existsSync } from "fs";
-import { mkdir, readFile, writeFile } from "fs/promises";
+import { existsSync, readFileSync } from "fs";
+import { copyFile, mkdir, readFile, writeFile } from "fs/promises";
 import { dirname, join, resolve } from "path";
 import { fileURLToPath } from "url";
+import { PACKAGE_ROOT } from "../core/package-root.js";
 import { homedir, platform } from "os";
 export const SUMMER_MCP_SERVER_NAME = "summer-engine";
 export const supportedAgents = [
@@ -64,10 +65,31 @@ export function parseScope(value) {
         return normalized;
     return null;
 }
+/** `summer setup [agent] --agent <agent>`: positional and option must agree;
+ *  throws with a user-facing message when neither names a supported agent. */
+export function resolveAgentSelection(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;
+}
+/** `--scope` with a user-facing error; absent means "user". */
+export function resolveConfigScope(scopeOpt) {
+    const parsed = parseScope(scopeOpt);
+    if (!parsed) {
+        throw new Error("Invalid --scope. Use user or project.");
+    }
+    return parsed;
+}
 export async function configureAgentMcp(options) {
     const env = options.env ?? process.env;
     const cwd = resolve(options.cwd ?? process.cwd());
-    const server = createSummerMcpServerConfig(Boolean(options.localDev));
+    const channel = normalizeChannel(options.channel);
+    const server = createSummerMcpServerConfig(Boolean(options.localDev), process.platform, channel);
     const target = resolveConfigTarget(options.agent, options.scope, cwd, env);
     const snippet = renderConfigSnippet(options.agent, server);
     const dryRun = Boolean(options.dryRun);
@@ -99,20 +121,46 @@ export async function configureAgentMcp(options) {
         dryRun,
         print,
         localDev: Boolean(options.localDev),
+        channel,
         warnings: target.warnings,
         nextSteps: createNextSteps(options.agent, options.scope, target.path),
     };
 }
-export function createSummerMcpServerConfig(localDev) {
+export const DEFAULT_CHANNEL = "latest";
+/** npm dist-tags are lowercase words like `latest`, `next`, `beta`, `v3-preview`;
+ *  anything that could be read as a version or a path is refused (a bare
+ *  version belongs in a version bump, not a channel). */
+export function normalizeChannel(channel) {
+    const value = (channel ?? "").trim();
+    if (value === "")
+        return DEFAULT_CHANNEL;
+    if (!/^[a-z][a-z0-9-]*$/.test(value) || /^v?\d/.test(value)) {
+        throw new Error(`Invalid channel "${channel}": use an npm dist-tag such as latest or next (lowercase letters, digits, hyphens).`);
+    }
+    return value;
+}
+export function createSummerMcpServerConfig(localDev, platform = process.platform, channel = DEFAULT_CHANNEL) {
+    const spec = `summer-engine@${normalizeChannel(channel)}`;
     if (localDev) {
+        // node is a real executable on every platform; spawn("node") resolves fine.
         return {
             command: "node",
             args: [resolveLocalCliPath(), "mcp"],
         };
     }
+    // On Windows, npx is a .cmd/.ps1 shim, and Node's spawn() does not do PATHEXT
+    // resolution — hosts that spawn("npx") directly (Claude Code, Kimi Code,
+    // Cursor, ...) fail with ENOENT even though npx works in a terminal. Route
+    // through cmd.exe so the shim resolves. (User-reported: Imitater967, 2026-09-01.)
+    if (platform === "win32") {
+        return {
+            command: "cmd.exe",
+            args: ["/c", "npx", "-y", spec, "mcp"],
+        };
+    }
     return {
         command: "npx",
-        args: ["-y", "summer-engine@latest", "mcp"],
+        args: ["-y", spec, "mcp"],
     };
 }
 export function renderConfigSnippet(agent, server) {
@@ -142,7 +190,7 @@ export function renderConfigSnippet(agent, server) {
         }, null, 2) + "\n");
     }
     if (agent === "gemini") {
-        return (JSON.stringify(geminiExtensionManifest(server), null, 2) + "\n");
+        return renderJsonFile(geminiExtensionManifest(server, readBundledGeminiManifestSync()));
     }
     return (JSON.stringify({
         mcpServers: {
@@ -154,6 +202,14 @@ function resolveLocalCliPath() {
     const thisFile = fileURLToPath(import.meta.url);
     return resolve(dirname(thisFile), "..", "bin", "summer.js");
 }
+/** Installed package root (dist/ and src/ alike). */
+export function resolvePackageRoot() {
+    return PACKAGE_ROOT;
+}
+/** Directory name Gemini expects the extension under; the manifest `name` must match it. */
+export const GEMINI_EXTENSION_DIR_NAME = "summer-engine";
+/** Files copied next to the extension manifest so `contextFileName` (GEMINI.md, which imports AGENTS.md) resolves. */
+const GEMINI_CONTEXT_FILES = ["GEMINI.md", "AGENTS.md"];
 function resolveConfigTarget(agent, scope, cwd, env) {
     const override = getConfigPathOverride(agent, env);
     const warnings = [];
@@ -448,15 +504,98 @@ async function upsertVsCodeMcpConfig(path, server, write) {
 }
 async function upsertGeminiExtension(path, server, write) {
     const current = await readJsonConfig(path);
-    const next = geminiExtensionManifest(server, current);
+    const bundled = await readBundledGeminiManifest();
+    const next = geminiExtensionManifest(server, bundled, current);
     const currentRendered = renderJsonFile(current);
     const nextRendered = renderJsonFile(next);
-    const changed = currentRendered !== nextRendered;
+    let changed = currentRendered !== nextRendered;
     if (write && changed) {
         await writeTextFile(path, nextRendered);
     }
+    // GEMINI.md (the declared contextFileName) and AGENTS.md (which it imports)
+    // must sit next to the manifest or Gemini has no context file to load.
+    const extensionDir = dirname(path);
+    const packageRoot = resolvePackageRoot();
+    for (const name of GEMINI_CONTEXT_FILES) {
+        const src = join(packageRoot, name);
+        if (!existsSync(src))
+            continue;
+        const dest = join(extensionDir, name);
+        const srcText = await readFile(src, "utf-8");
+        const destText = existsSync(dest) ? await readFile(dest, "utf-8") : null;
+        if (destText === srcText)
+            continue;
+        changed = true;
+        if (write) {
+            await mkdir(extensionDir, { recursive: true, mode: 0o700 });
+            await copyFile(src, dest);
+        }
+    }
     return { changed };
 }
+/**
+ * The GENERATED gemini-extension.json shipped at the package root
+ * (registry/generated/gemini-extension.json -> gemini-extension.json). Absent
+ * only in broken installs; the installer then falls back to a minimal manifest.
+ */
+async function readBundledGeminiManifest() {
+    const path = join(resolvePackageRoot(), "gemini-extension.json");
+    if (!existsSync(path))
+        return {};
+    try {
+        return await readJsonConfig(path);
+    }
+    catch {
+        return {};
+    }
+}
+function readBundledGeminiManifestSync() {
+    const path = join(resolvePackageRoot(), "gemini-extension.json");
+    if (!existsSync(path))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        return isJsonObject(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Manifest written to ~/.gemini/extensions/summer-engine/gemini-extension.json.
+ *
+ * Starts from the generated package manifest (version, description, settings,
+ * contextFileName, ...) so the installed copy never drifts from the registry,
+ * then overrides what only makes sense at install time:
+ *  - `name` = the extension directory name (Gemini requires them to match;
+ *    geminicli.com/docs/extensions/reference), which is "summer-engine".
+ *  - `mcpServers` = the same launcher every other host gets (npx -y ...@latest,
+ *    cmd.exe-wrapped on Windows). The bundled entry runs from `${extensionPath}`
+ *    where no package is installed, and that only works inside the npm layout.
+ *  - `skills` is dropped: Gemini has no such manifest field; it discovers
+ *    <extension>/skills/<name>/SKILL.md, which `summer skills install --agent
+ *    gemini` writes.
+ *  - the `_generated` banner is dropped: this file is written by the installer.
+ * Unknown keys already present in the user's file (`base`) are preserved.
+ */
+function geminiExtensionManifest(server, bundled, base = {}) {
+    const { _generated: _banner, skills: _skills, ...fromPackage } = bundled;
+    const manifest = { ...base, ...fromPackage };
+    manifest.name = GEMINI_EXTENSION_DIR_NAME;
+    if (typeof manifest.description !== "string") {
+        manifest.description =
+            "Agent tooling for Summer Engine: MCP bridge, context primer, and game-dev skills.";
+    }
+    manifest.contextFileName = "GEMINI.md";
+    manifest.mcpServers = {
+        [SUMMER_MCP_SERVER_NAME]: {
+            command: server.command,
+            args: server.args,
+            ...(server.env && Object.keys(server.env).length > 0 ? { env: { ...server.env } } : {}),
+        },
+    };
+    return manifest;
+}
 function opencodeServerEntry(server) {
     const entry = {
         type: "local",
@@ -490,20 +629,6 @@ function vsCodeServerEntry(server) {
     }
     return entry;
 }
-function geminiExtensionManifest(server, base = {}) {
-    const manifest = { ...base };
-    manifest.name = "summer";
-    manifest.description =
-        "Superpowers for AI game dev. MCP bridge to the local Summer Engine plus a context primer that teaches Gemini the Summer skills.";
-    manifest.contextFileName = "GEMINI.md";
-    manifest.mcpServers = {
-        [SUMMER_MCP_SERVER_NAME]: {
-            command: server.command,
-            args: server.args,
-        },
-    };
-    return manifest;
-}
 async function readTextFileIfExists(path) {
     if (!existsSync(path))
         return "";
@@ -597,7 +722,7 @@ function createNextSteps(agent, scope, path) {
                             : agent === "lm-studio"
                                 ? "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."
                                 : agent === "gemini"
-                                    ? "Run `gemini extensions enable summer-engine` (if not already enabled), then restart Gemini CLI."
+                                    ? "Run `summer skills install --all --agent gemini` if skills were not installed, then restart Gemini CLI (or `gemini extensions enable summer-engine` if it is disabled)."
                                     : agent === "github-copilot"
                                         ? "Restart Copilot CLI, or run /mcp reload and /skills reload in the active session."
                                         : agent === "vscode-copilot"

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

@@ -0,0 +1,26 @@
+/**
+ * Skill directory names the 2.8.x package installed into hosts' skill folders
+ * (`~/.claude/skills/<name>` and the equivalents). v3 flattened and renamed
+ * the library, so a `summer setup --force` on an upgraded machine must remove
+ * the entries Summer itself installed that no longer exist — otherwise a
+ * retired skill such as `summer-cloud` stays behind and keeps telling agents
+ * to call tools that were removed (release review P1-2, 2026-09-11).
+ *
+ * The list is exactly the SKILL.md basenames shipped in summer-engine@2.8.2.
+ * Pruning removes a name ONLY when it is absent from the current registry, so
+ * a slug that returns to the library is never touched, and never removes a
+ * directory that has no SKILL.md (not a skill Summer wrote).
+ */
+export declare const LEGACY_SKILL_SLUGS_2_8_2: readonly string[];
+export interface PrunedSkill {
+    name: string;
+    path: string;
+}
+/** Names Summer installed in 2.8.x that the current registry no longer ships. */
+export declare function retiredSkillNames(currentSkillNames: Iterable<string>): string[];
+/**
+ * Remove retired Summer skill directories from one host skill folder. Only
+ * directories that still contain a SKILL.md are removed (that is what Summer
+ * wrote); anything else with a colliding name is left alone.
+ */
+export declare function pruneRetiredSkills(skillsDir: string, currentSkillNames: Iterable<string>): PrunedSkill[];

package/dist/installer/legacy-skills.js

@@ -0,0 +1,53 @@
+import { existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Skill directory names the 2.8.x package installed into hosts' skill folders
+ * (`~/.claude/skills/<name>` and the equivalents). v3 flattened and renamed
+ * the library, so a `summer setup --force` on an upgraded machine must remove
+ * the entries Summer itself installed that no longer exist — otherwise a
+ * retired skill such as `summer-cloud` stays behind and keeps telling agents
+ * to call tools that were removed (release review P1-2, 2026-09-11).
+ *
+ * The list is exactly the SKILL.md basenames shipped in summer-engine@2.8.2.
+ * Pruning removes a name ONLY when it is absent from the current registry, so
+ * a slug that returns to the library is never touched, and never removes a
+ * directory that has no SKILL.md (not a skill Summer wrote).
+ */
+export const LEGACY_SKILL_SLUGS_2_8_2 = [
+    "character-portrait", "concept-art", "create-asset-sheet", "instantiate-asset-pack", "pixel-art",
+    "skybox-panorama", "sprite-sheet", "tileable-texture", "ui-graphics", "use-widget-asset",
+    "character-model", "environment-kit", "organic-model", "prop-model", "vehicle-model",
+    "design-npc", "animation-tree", "facial-and-lipsync", "generate-motion", "procedural-animation",
+    "retarget", "asset-strategy", "adaptive-music", "ambient-bed", "audio-direction", "music-track",
+    "sound-effect", "voice-line", "fps-controller", "debug", "export-and-ship", "remote-deploy",
+    "auto-fire-targeting", "design-mechanic", "design-level", "scene-to-level",
+    "host-authoritative-state", "peer-to-peer-multiplayer", "setup-multiplayer", "tune-performance",
+    "3d-lighting", "art-direction", "brainstorm-game", "browse-templates", "make-game", "new-project",
+    "play", "scene-composition", "summer-cloud", "gdscript-patterns", "ui-basics", "animated-loop",
+    "cinematic-cutscene", "trailer-shot", "game-feel", "dissolve", "fire", "hit-spark", "lightning",
+    "magic-glow", "muzzle-flash", "smoke", "water-ripple", "brainstorming", "debugging-game-feel",
+    "diagnosing-perf-regressions", "dispatching-parallel-agents", "gameskill", "headless-scripting",
+    "investigating-bugs", "mcpupdate", "playtesting-a-feature", "skill-create", "skill-improve",
+    "skill-test", "using-summer", "verification-before-completion", "writing-plans", "writing-skills",
+];
+/** Names Summer installed in 2.8.x that the current registry no longer ships. */
+export function retiredSkillNames(currentSkillNames) {
+    const current = new Set(currentSkillNames);
+    return LEGACY_SKILL_SLUGS_2_8_2.filter((name) => !current.has(name));
+}
+/**
+ * Remove retired Summer skill directories from one host skill folder. Only
+ * directories that still contain a SKILL.md are removed (that is what Summer
+ * wrote); anything else with a colliding name is left alone.
+ */
+export function pruneRetiredSkills(skillsDir, currentSkillNames) {
+    const pruned = [];
+    for (const name of retiredSkillNames(currentSkillNames)) {
+        const dir = join(skillsDir, name);
+        if (!existsSync(join(dir, "SKILL.md")))
+            continue;
+        rmSync(dir, { recursive: true, force: true });
+        pruned.push({ name, path: dir });
+    }
+    return pruned;
+}

package/dist/installer/setup.d.ts

@@ -0,0 +1,76 @@
+import { SupportedAgent } from "./agent-config.js";
+export interface SkillSetupResult {
+    status: "installed" | "planned" | "skipped" | "failed";
+    message: string;
+    command?: string[];
+    stdout?: string;
+    stderr?: string;
+    /** Number of skills selected for install (all, or the recommended subset). */
+    count?: number;
+    /** Preview skills installed alongside the stable ones (the default). */
+    previewIncluded?: number;
+    /** Preview skills left out because --stable-only was given. */
+    previewSkipped?: number;
+    /** Where the skills land, e.g. "~/.claude/skills/<skill>/SKILL.md". */
+    destination?: string;
+    /** Post-install tallies parsed from `skills install` output. */
+    installed?: {
+        total: number;
+        added: number;
+        updated: number;
+    };
+}
+export interface SkillInstallInvocation {
+    command: string;
+    args: string[];
+    display: string[];
+}
+export interface SkillSetupOptions {
+    dryRun: boolean;
+    yes: boolean;
+    force: boolean;
+    /** Skills scope; defaults to the MCP scope so both land in the same place. */
+    scope?: "user" | "project";
+    /** Install only `recommended: true` skills instead of the whole library. */
+    recommended?: boolean;
+    /** 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;
+}
+/**
+ * The preview clause of the setup summary — one wording for the result message
+ * and the CLI line, e.g. "10 preview — labelled in each skill's guidance; use
+ * --stable-only to skip". Empty when there is nothing to say.
+ */
+export declare function previewNote(result: {
+    previewIncluded?: number;
+    previewSkipped?: number;
+}): string;
+/**
+ * Install the Summer skill library for an agent as part of `summer setup`.
+ *
+ * Installs EVERY library skill by default: skills are progressive-disclosure
+ * (name + description in context, body on activation), and the session entry
+ * skill `using-summer` is not in the recommended subset, so a
+ * recommended-only default left the documented starting point uninstalled.
+ * `--recommended` keeps the smaller subset as an opt-in; `--stable-only` drops
+ * the preview skills (installed by default, labelled in their guidance).
+ */
+export declare function setupSkills(agent: SupportedAgent, options: SkillSetupOptions): SkillSetupResult;
+/** @deprecated use setupSkills; kept for older callers. */
+export declare const setupRecommendedSkills: (agent: SupportedAgent, options: {
+    dryRun: boolean;
+    yes: boolean;
+    force: boolean;
+}) => SkillSetupResult;
+/**
+ * Count `skills install` result lines. Directory installs print
+ * "Installed <skill> -> <path>" for new copies and "Updated <skill> -> <path>"
+ * for re-installs; rule-file agents (Cursor, Cline, ...) always print
+ * "Generated <skill> -> <path>" and are counted as updated-or-new (added).
+ */
+export declare function tallyInstallOutput(stdout: string): {
+    total: number;
+    added: number;
+    updated: number;
+};

package/dist/installer/setup.js

@@ -0,0 +1,146 @@
+import { spawnSync } from "child_process";
+import { AGENT_CLIENTS, getSkillRegistry, selectSkillsForBulkInstall, } from "../core/skills-registry.js";
+import { describeInstallLocation, resolveInstallLocation } from "./skill-locations.js";
+/**
+ * The preview clause of the setup summary — one wording for the result message
+ * and the CLI line, e.g. "10 preview — labelled in each skill's guidance; use
+ * --stable-only to skip". Empty when there is nothing to say.
+ */
+export function previewNote(result) {
+    if (result.previewIncluded) {
+        return `${result.previewIncluded} preview — labelled in each skill's guidance; use --stable-only to skip`;
+    }
+    if (result.previewSkipped) {
+        return `${result.previewSkipped} preview skipped by --stable-only`;
+    }
+    return "";
+}
+/**
+ * Install the Summer skill library for an agent as part of `summer setup`.
+ *
+ * Installs EVERY library skill by default: skills are progressive-disclosure
+ * (name + description in context, body on activation), and the session entry
+ * skill `using-summer` is not in the recommended subset, so a
+ * recommended-only default left the documented starting point uninstalled.
+ * `--recommended` keeps the smaller subset as an opt-in; `--stable-only` drops
+ * the preview skills (installed by default, labelled in their guidance).
+ */
+export function setupSkills(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 scope = options.scope ?? "user";
+    const recommended = Boolean(options.recommended);
+    const stableOnly = Boolean(options.stableOnly);
+    const invocation = skillInstallInvocation(agent, {
+        force: options.force,
+        scope,
+        recommended,
+        stableOnly,
+    });
+    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.",
+        };
+    }
+    const { selected, previewIncluded, previewSkipped } = selectSkillsForBulkInstall(getSkillRegistry(), { recommended, stableOnly });
+    const count = selected.length;
+    const note = previewNote({ previewIncluded, previewSkipped });
+    const destination = isAgentClient(agent)
+        ? describeInstallLocation(resolveInstallLocation(agent, scope))
+        : undefined;
+    const subset = recommended ? "recommended " : "";
+    if (options.dryRun || !options.yes) {
+        return {
+            status: "planned",
+            command: invocation.display,
+            count,
+            previewIncluded,
+            previewSkipped,
+            destination,
+            message: `Would install ${count} ${subset}skills${note ? ` (${note})` : ""} to ${destination ?? "the agent's skills directory"} with: ${invocation.display.join(" ")}`,
+        };
+    }
+    const result = spawnSync(invocation.command, invocation.args, {
+        env: process.env,
+        encoding: "utf-8",
+    });
+    if (result.status === 0) {
+        const installed = tallyInstallOutput(result.stdout);
+        return {
+            status: "installed",
+            command: invocation.display,
+            count,
+            previewIncluded,
+            previewSkipped,
+            destination,
+            installed,
+            message: `Installed ${installed.total} ${subset}skills (${installed.added} new, ${installed.updated} updated${note ? `; ${note}` : ""}).`,
+            stdout: result.stdout.trim(),
+            stderr: result.stderr.trim(),
+        };
+    }
+    return {
+        status: "failed",
+        command: invocation.display,
+        count,
+        destination,
+        message: `Skill install failed with exit code ${result.status ?? "unknown"}.`,
+        stdout: result.stdout.trim(),
+        stderr: result.stderr.trim(),
+    };
+}
+/** @deprecated use setupSkills; kept for older callers. */
+export const setupRecommendedSkills = (agent, options) => setupSkills(agent, { ...options, recommended: true });
+function isAgentClient(agent) {
+    return AGENT_CLIENTS.includes(agent);
+}
+/**
+ * Count `skills install` result lines. Directory installs print
+ * "Installed <skill> -> <path>" for new copies and "Updated <skill> -> <path>"
+ * for re-installs; rule-file agents (Cursor, Cline, ...) always print
+ * "Generated <skill> -> <path>" and are counted as updated-or-new (added).
+ */
+export function tallyInstallOutput(stdout) {
+    let added = 0;
+    let updated = 0;
+    for (const line of stdout.split("\n")) {
+        const m = line.match(/^\s*(Installed|Updated|Generated)\s+([a-z0-9-]+)\s+->/i);
+        if (!m)
+            continue;
+        if (m[1].toLowerCase() === "updated")
+            updated += 1;
+        else
+            added += 1;
+    }
+    return { total: added + updated, added, updated };
+}
+function skillInstallInvocation(agent, opts) {
+    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",
+        opts.recommended ? "--recommended" : "--all",
+        "--agent",
+        agent,
+        "--scope",
+        opts.scope,
+    ];
+    if (opts.force)
+        baseArgs.push("--force");
+    if (opts.stableOnly)
+        baseArgs.push("--stable-only");
+    return {
+        command,
+        args: [...prefix, ...baseArgs],
+        display: [cliPath, ...baseArgs],
+    };
+}

package/dist/installer/skill-locations.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Where `summer skills install` puts skills for each agent client.
+ *
+ * Lives in the installer layer (not cli/) so `summer setup` can report the
+ * destination and count without importing the CLI (import-direction contract
+ * §2: shared layers never import cli or mcp).
+ */
+import { type AgentClient } from "../core/skills-registry.js";
+export declare const SKILL_SCOPES: readonly ["user", "project"];
+export type SkillScope = (typeof SKILL_SCOPES)[number];
+/** The agent/scope flags `summer skills install` accepts (legacy aliases included). */
+export interface SkillInstallSelection {
+    agent?: string;
+    scope?: string;
+    asClaudeSkill?: boolean;
+    asCursorSkill?: boolean;
+}
+/** Throws with a user-facing message on an unknown agent. */
+export declare function parseSkillAgent(value: string): AgentClient;
+/** Throws with a user-facing message on an unknown scope. */
+export declare function parseSkillScope(value: string): SkillScope;
+/** Pick the agent from --agent / legacy --as-claude-skill / --as-cursor-skill
+ *  (default "summer"); throws on conflicting flags. */
+export declare function resolveSkillAgent(opts: SkillInstallSelection): AgentClient;
+/** Explicit --scope wins; otherwise project-rooted agents default to "project". */
+export declare function resolveSkillScope(agent: AgentClient, opts: SkillInstallSelection): SkillScope;
+export type InstallLocation = {
+    kind: "skill-dir";
+    path: string;
+} | {
+    kind: "cursor-rule-dir";
+    path: string;
+} | {
+    kind: "windsurf-rule-file";
+    path: string;
+} | {
+    kind: "cline-rule-dir";
+    path: string;
+} | {
+    kind: "opencode-skill-dir";
+    path: string;
+};
+export declare function resolveInstallLocation(agent: AgentClient, scope: SkillScope): InstallLocation;
+/** One-line, human path pattern for where an install location puts skills. */
+export declare function describeInstallLocation(location: InstallLocation): string;