summer-engine 3.8.0 → 4.0.0

package/dist/core/telemetry.d.ts

@@ -1,3 +1,20 @@
+/**
+ * Usage beacons for the local MCP server. Fire-and-forget, never blocks, never throws.
+ *
+ * - One session ping per MCP server lifetime (mcp_session_start), on the
+ *   first tool call, with the host app's name from the MCP handshake.
+ * - One line per local tool call (mcp_tool_call): the tool name, the
+ *   Summer operation it ran, success, duration, the host app's name from the
+ *   MCP handshake, and the tool surface and profile. Nothing else: no
+ *   arguments, no results, no project or file names.
+ *
+ * Both go to /api/mcp/log-local-call, only when signed in (the account token
+ * attributes them), and never when SUMMER_NO_TELEMETRY=1 or DO_NOT_TRACK=1.
+ * The endpoint always returns allowed:true and never gates; the response is
+ * ignored.
+ */
+import { isTelemetryDisabled } from "./agent-host.js";
+export { isTelemetryDisabled };
 /**
  * Ping the telemetry endpoint once per MCP server lifetime.
  *
@@ -7,6 +24,21 @@
  * - Skips entirely if no auth token is on disk (anonymous users still work).
  */
 export declare function recordMcpSession(): void;
+export interface LocalToolCall {
+    tool: string;
+    ok: boolean;
+    durationMs: number;
+    /** The host app's name from the MCP handshake (clientInfo.name). */
+    mcpClient?: string;
+    /** The Summer operation the call ran (core/ops/contract.ts opForToolCall). */
+    op?: string | null;
+    /** The tool surface: v3 (3.x names) or v4 (the operation catalog). */
+    surfaceVersion?: "v3" | "v4";
+    /** The MCP profile: full, engine, assets or custom. */
+    profile?: string;
+}
+/** Report one local tool call: tool name, success, duration, host app name. */
+export declare function recordLocalToolCall(call: LocalToolCall): void;
 /**
  * Reset the once-per-session guard. Test-only.
  */

package/dist/core/telemetry.js

@@ -1,15 +1,25 @@
 /**
- * Pure-telemetry beacon for MCP usage. Fire-and-forget, never blocks, never throws.
- * One ping per MCP server lifetime — counts daily-active users, not per-tool calls.
+ * Usage beacons for the local MCP server. Fire-and-forget, never blocks, never throws.
  *
- * The endpoint /api/mcp/log-local-call always returns allowed:true and never gates.
- * No quota. The user account is the only thing being attributed; the response is
- * ignored entirely on the CLI side.
+ * - One session ping per MCP server lifetime (mcp_session_start), on the
+ *   first tool call, with the host app's name from the MCP handshake.
+ * - One line per local tool call (mcp_tool_call): the tool name, the
+ *   Summer operation it ran, success, duration, the host app's name from the
+ *   MCP handshake, and the tool surface and profile. Nothing else: no
+ *   arguments, no results, no project or file names.
+ *
+ * Both go to /api/mcp/log-local-call, only when signed in (the account token
+ * attributes them), and never when SUMMER_NO_TELEMETRY=1 or DO_NOT_TRACK=1.
+ * The endpoint always returns allowed:true and never gates; the response is
+ * ignored.
  */
+import { currentMcpClient, isTelemetryDisabled, summerRequestHeaders } from "./agent-host.js";
 import { getAuthToken } from "./auth.js";
 import { resolveGatewayUrl } from "./config.js";
+export { isTelemetryDisabled };
 const TELEMETRY_PATH = "/api/mcp/log-local-call";
 const TIMEOUT_MS = 5000;
+const TOOL_NAME = /^summer_[a-z0-9_]{1,64}$/;
 let pinged = false;
 /**
  * Ping the telemetry endpoint once per MCP server lifetime.
@@ -20,9 +30,29 @@ let pinged = false;
  * - Skips entirely if no auth token is on disk (anonymous users still work).
  */
 export function recordMcpSession() {
-    if (pinged)
+    if (pinged || isTelemetryDisabled())
         return;
     pinged = true;
+    const mcpClient = currentMcpClient()?.name;
+    send({ client: "summer-cli", event: "mcp_session_start", ...(mcpClient ? { mcpClient: mcpClient.slice(0, 64) } : {}) });
+}
+/** Report one local tool call: tool name, success, duration, host app name. */
+export function recordLocalToolCall(call) {
+    if (isTelemetryDisabled() || !TOOL_NAME.test(call.tool))
+        return;
+    send({
+        client: "summer-cli",
+        event: "mcp_tool_call",
+        ...(call.mcpClient ? { mcpClient: call.mcpClient.slice(0, 64) } : {}),
+        tool: call.tool,
+        ...(call.op ? { op: call.op } : {}),
+        ...(call.surfaceVersion ? { surfaceVersion: call.surfaceVersion } : {}),
+        ...(call.profile ? { profile: call.profile } : {}),
+        ok: call.ok,
+        durationMs: Math.max(0, Math.round(call.durationMs)),
+    });
+}
+function send(body) {
     // Wrap the entire async pipeline in a void-discarded promise so the caller
     // never accidentally awaits us.
     void (async () => {
@@ -40,13 +70,11 @@ export function recordMcpSession() {
                     method: "POST",
                     signal: ctrl.signal,
                     headers: {
+                        ...summerRequestHeaders(),
                         Authorization: `Bearer ${token}`,
                         "Content-Type": "application/json",
                     },
-                    body: JSON.stringify({
-                        client: "summer-cli",
-                        event: "mcp_session_start",
-                    }),
+                    body: JSON.stringify(body),
                 });
             }
             finally {

package/dist/core/tool-profiles.d.ts

@@ -0,0 +1,25 @@
+/**
+ * MCP tool profiles (`summer mcp --profile`, SUMMER_PROFILE) and the toolsets
+ * they pick. Shared by the MCP server (src/mcp/tool-surface.ts) and setup,
+ * which writes a profile into an agent's MCP entry. `full` is today's
+ * surface exactly and the default, so existing configs keep it.
+ */
+export declare const TOOLSETS: readonly ["core", "assets", "tools", "engine", "ui", "ship", "uploads", "apps", "board", "grow", "studio", "cloud", "other"];
+export type Toolset = (typeof TOOLSETS)[number];
+export declare const PROFILES: {
+    /** Every tool, local and hosted (today's surface). */
+    readonly full: readonly ["core", "assets", "tools", "engine", "ui", "ship", "uploads", "apps", "board", "grow", "studio", "cloud", "other"];
+    /** Summer Engine creators: engine, generation and the store. Fits clients with a 128-tool limit. */
+    readonly engine: readonly ["core", "assets", "engine", "ship"];
+    /** Any engine or none: generation, the asset library, account and library search. No engine tools. */
+    readonly assets: readonly ["core", "assets", "tools"];
+};
+export type Profile = keyof typeof PROFILES;
+/** Non-full profiles never register more tools than this (VS Code Copilot's per-request limit). */
+export declare const PROFILE_TOOL_LIMIT = 128;
+/** A profile name, or null when the value names none. */
+export declare function parseProfile(value: string | undefined): Profile | null;
+/** v4: the operation catalog (summer_search, summer_call, `summer <area> <action>`); v3: the 3.x tools. */
+export type SurfaceVersion = "v3" | "v4";
+/** `--surface` / SUMMER_SURFACE: v4 is the default since 4.0; v3 keeps the 3.x tools. */
+export declare function resolveSurface(value: string | undefined, env?: NodeJS.ProcessEnv): SurfaceVersion;

package/dist/core/tool-profiles.js

@@ -0,0 +1,41 @@
+/**
+ * MCP tool profiles (`summer mcp --profile`, SUMMER_PROFILE) and the toolsets
+ * they pick. Shared by the MCP server (src/mcp/tool-surface.ts) and setup,
+ * which writes a profile into an agent's MCP entry. `full` is today's
+ * surface exactly and the default, so existing configs keep it.
+ */
+export const TOOLSETS = [
+    "core",
+    "assets",
+    "tools",
+    "engine",
+    "ui",
+    "ship",
+    "uploads",
+    "apps",
+    "board",
+    "grow",
+    "studio",
+    "cloud",
+    "other",
+];
+export const PROFILES = {
+    /** Every tool, local and hosted (today's surface). */
+    full: TOOLSETS,
+    /** Summer Engine creators: engine, generation and the store. Fits clients with a 128-tool limit. */
+    engine: ["core", "assets", "engine", "ship"],
+    /** Any engine or none: generation, the asset library, account and library search. No engine tools. */
+    assets: ["core", "assets", "tools"],
+};
+/** Non-full profiles never register more tools than this (VS Code Copilot's per-request limit). */
+export const PROFILE_TOOL_LIMIT = 128;
+/** A profile name, or null when the value names none. */
+export function parseProfile(value) {
+    const name = (value ?? "").trim().toLowerCase();
+    return Object.hasOwn(PROFILES, name) ? name : null;
+}
+/** `--surface` / SUMMER_SURFACE: v4 is the default since 4.0; v3 keeps the 3.x tools. */
+export function resolveSurface(value, env = process.env) {
+    const asked = (value ?? env.SUMMER_SURFACE ?? "").trim().toLowerCase();
+    return asked === "v3" || asked === "3" ? "v3" : "v4";
+}

package/dist/installer/agent-config.d.ts

@@ -1,3 +1,4 @@
+import type { Profile } from "../core/tool-profiles.js";
 import { type ConfigScope, type McpFormat, type SupportedAgent } from "./agent-table.js";
 export { supportedAgents, type ConfigScope, type SupportedAgent } from "./agent-table.js";
 export declare const SUMMER_MCP_SERVER_NAME = "summer-engine";
@@ -12,9 +13,11 @@ export interface AgentConfigOptions {
     dryRun?: boolean;
     print?: boolean;
     localDev?: boolean;
-    /** npm dist-tag the generated MCP entry runs (`npx -y summer-engine@<channel> mcp`).
+    /** npm dist-tag or exact version the generated MCP entry runs (`npx -y summer-engine@<channel> mcp`).
      *  Default "latest"; "next" while a release soaks on the next tag. Ignored with localDev. */
     channel?: string;
+    /** MCP tool profile written as SUMMER_PROFILE; default the agent's own (full for most). */
+    profile?: Profile;
     cwd?: string;
     env?: NodeJS.ProcessEnv;
 }
@@ -31,8 +34,11 @@ export interface AgentConfigResult {
     dryRun: boolean;
     print: boolean;
     localDev: boolean;
-    /** The dist-tag the written entry runs ("latest" unless --channel / SUMMER_CHANNEL). */
+    /** The dist-tag or exact version the written entry runs ("latest" unless --channel /
+     *  SUMMER_CHANNEL, or a CLI ahead of npm latest: see resolveDefaultChannel). */
     channel: string;
+    /** The MCP tool profile the entry runs (full = every tool, no SUMMER_PROFILE written). */
+    profile: Profile;
     warnings: string[];
     nextSteps: string[];
 }
@@ -72,9 +78,16 @@ export interface RemoteMcpResult {
 export declare function configureSummerGamesMcp(options: Pick<AgentConfigOptions, "agent" | "scope" | "dryRun" | "cwd" | "env">): Promise<RemoteMcpResult | null>;
 export declare 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). */
+ *  an exact version (`3.9.1`, `3.9.1-rc.1`) pins the entry to that release, which
+ *  setup does for a CLI that is ahead of npm latest. Anything else, partial
+ *  versions and paths included, is refused. */
 export declare function normalizeChannel(channel: string | undefined): string;
+/**
+ * The profile rides in the entry's env, not its args: an older summer-engine
+ * that an agent still runs ignores the variable and serves every tool, where
+ * an unknown --profile flag would stop it from starting.
+ */
+export declare function withProfile(server: StdioMcpServerConfig, profile: Profile): StdioMcpServerConfig;
 export declare function createSummerMcpServerConfig(localDev: boolean, platform?: NodeJS.Platform, channel?: string): StdioMcpServerConfig;
 export declare function renderConfigSnippet(agent: SupportedAgent, server: StdioMcpServerConfig): string;
 /** The key under which the file lists MCP servers (see McpFormat in agent-table.ts). */

package/dist/installer/agent-config.js

@@ -27,9 +27,12 @@ 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);
+    const name = agentOpt ?? agentArg;
+    const parsed = parseAgent(name);
     if (!parsed) {
-        throw new Error(`Specify an agent: ${supportedAgents.join(", ")}`);
+        throw new Error(name
+            ? `Unknown agent "${name}". Supported: ${supportedAgents.join(", ")}`
+            : `Specify an agent: ${supportedAgents.join(", ")}`);
     }
     return parsed;
 }
@@ -45,8 +48,9 @@ export async function configureAgentMcp(options) {
     const env = options.env ?? process.env;
     const cwd = resolve(options.cwd ?? process.cwd());
     const channel = normalizeChannel(options.channel);
-    const server = createSummerMcpServerConfig(Boolean(options.localDev), process.platform, channel);
     const spec = agentSpec(options.agent);
+    const profile = options.profile ?? spec.mcpProfile ?? "full";
+    const server = withProfile(createSummerMcpServerConfig(Boolean(options.localDev), process.platform, channel), profile);
     const target = resolveConfigTarget(spec, options.scope, cwd, env);
     const snippet = renderConfigSnippet(options.agent, server);
     const dryRun = Boolean(options.dryRun);
@@ -69,6 +73,7 @@ export async function configureAgentMcp(options) {
         print,
         localDev: Boolean(options.localDev),
         channel,
+        profile,
         warnings: target.warnings,
         nextSteps: [`Updated ${target.path}.`, spec.restart],
     };
@@ -264,17 +269,28 @@ async function upsertConfig(format, path, server, write) {
 }
 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). */
+ *  an exact version (`3.9.1`, `3.9.1-rc.1`) pins the entry to that release, which
+ *  setup does for a CLI that is ahead of npm latest. Anything else, partial
+ *  versions and paths included, is refused. */
 export function normalizeChannel(channel) {
     const value = (channel ?? "").trim();
     if (value === "")
         return DEFAULT_CHANNEL;
+    if (/^\d+\.\d+\.\d+(?:-[0-9a-z][0-9a-z.-]*)?$/.test(value))
+        return value;
     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).`);
+        throw new Error(`Invalid channel "${channel}": use an npm dist-tag such as latest or next (lowercase letters, digits, hyphens), or an exact version such as 4.0.0.`);
     }
     return value;
 }
+/**
+ * The profile rides in the entry's env, not its args: an older summer-engine
+ * that an agent still runs ignores the variable and serves every tool, where
+ * an unknown --profile flag would stop it from starting.
+ */
+export function withProfile(server, profile) {
+    return profile === "full" ? server : { ...server, env: { ...server.env, SUMMER_PROFILE: profile } };
+}
 export function createSummerMcpServerConfig(localDev, platform = process.platform, channel = DEFAULT_CHANNEL) {
     const spec = `summer-engine@${normalizeChannel(channel)}`;
     if (localDev) {

package/dist/installer/agent-table.d.ts

@@ -1,3 +1,4 @@
+import type { Profile } from "../core/tool-profiles.js";
 /** Ids `summer setup <agent>` accepts. Legacy ids stay so old commands and
  *  configs keep resolving, but they are hidden from help and warn on use. */
 export declare const AGENT_IDS: readonly ["claude-code", "claude-desktop", "codex", "cursor", "windsurf", "antigravity", "gemini", "cline", "cline-cli", "roo-code", "kilo-code", "github-copilot", "vscode-copilot", "visual-studio", "copilot-jetbrains", "opencode", "zed", "kiro", "goose", "hermes", "trae", "qwen-code", "kimi-code", "crush", "amp", "factory", "junie", "warp", "rovo-dev", "qoder", "grok-build", "mistral-vibe", "lm-studio"];
@@ -70,6 +71,8 @@ export interface AgentSpec {
     /** Env var that overrides the MCP config path (tests, unusual installs). */
     envOverride: string;
     format: McpFormat;
+    /** MCP tool profile setup writes without --profile (default full: every tool). */
+    mcpProfile?: Profile;
     /**
      * The Summer Games player MCP (a remote server that signs in with OAuth on
      * its own) in this agent's file, under the same key as summer-engine.

package/dist/installer/agent-table.js

@@ -130,7 +130,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 +144,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.",
         },
@@ -316,6 +317,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 +338,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 +357,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 +479,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 +573,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 +655,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]));

package/dist/installer/setup.d.ts

@@ -36,6 +36,8 @@ 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;
 }
 /**
  * The preview clause of the setup summary — one wording for the result message

package/dist/installer/setup.js

@@ -37,11 +37,13 @@ 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,
     });
     if (!invocation) {
         return {
@@ -49,14 +51,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 +67,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 +135,7 @@ function skillInstallInvocation(agent, opts) {
     const baseArgs = [
         "skills",
         "install",
-        opts.recommended ? "--recommended" : "--all",
+        opts.assetsOnly ? "--assets" : opts.recommended ? "--recommended" : "--all",
         "--agent",
         agent,
         "--scope",

package/dist/installer/version-check.d.ts

@@ -52,6 +52,15 @@ export interface RegistryFetchFailure {
     message?: string;
 }
 export declare function fetchLatestRegistryVersion(options?: RegistryFetchOptions): Promise<RegistryFetchResult | RegistryFetchFailure>;
+export interface RegistryDistTagsResult {
+    ok: true;
+    /** dist-tag -> version, e.g. { latest: "3.8.0", next: "3.1.0" }. */
+    tags: Record<string, string>;
+}
+export declare function fetchRegistryDistTags(options?: RegistryFetchOptions): Promise<RegistryDistTagsResult | RegistryFetchFailure>;
+/** Whether npm has this exact version: true, false (registry says 404), or
+ *  null when the registry could not be asked. */
+export declare function isRegistryVersionPublished(version: string, options?: RegistryFetchOptions): Promise<boolean | null>;
 /**
  * Build the `cli-version-current` doctor check. Pure helper so tests can drive
  * registry responses through `fetchImpl` rather than touching the network.
@@ -100,16 +109,25 @@ export interface RecordedInstall {
      *  no readable Summer entry — the nature of the CLI running this check. */
     source: "agent-config" | "running-cli";
 }
-export type RefreshChannel = "latest" | "next";
-/** The npm dist-tag a refresh command should name. A CLI that is AHEAD of
- *  npm `latest` was installed from `next` (a soaking release); telling that
- *  user to run `summer-engine@latest` would silently downgrade the MCP server
- *  while leaving the newer skills in place (release review P1-3). */
-export declare function refreshChannel(installedVersion: string, latestVersion: string | undefined): RefreshChannel;
+/** An npm dist-tag (`latest`, `next`) or an exact version (`3.9.1`). */
+export type RefreshChannel = string;
+/** The npm spec a refresh command or a new MCP entry should name, so the agent
+ *  never runs an older release than this CLI (release review P1-3). `latest`
+ *  unless this CLI is AHEAD of npm latest; then `next` only when the next
+ *  dist-tag is this exact version, else this exact version. A CLI that is ahead
+ *  is not always on `next`: `next` stayed on 3.1.0 while latest moved to 3.8.0,
+ *  and pinning it dropped every option newer than 3.1.0 (SUMMER_PROFILE). */
+export declare function refreshChannel(installedVersion: string, latestVersion: string | undefined, nextVersion?: string): RefreshChannel;
+export interface DefaultChannelDeps {
+    fetchDistTags?: typeof fetchRegistryDistTags;
+    isPublished?: typeof isRegistryVersionPublished;
+}
 /** Default `summer setup` channel when neither --channel nor SUMMER_CHANNEL is
- *  given: `next` while this CLI is ahead of npm latest, else `latest`. Network
- *  failure means `latest` (never blocks setup). */
-export declare function resolveDefaultChannel(installedVersion: string): Promise<{
+ *  given: `latest`, unless this CLI is ahead of npm latest. Then `next` when
+ *  next is this exact version, this exact version when npm has it, and
+ *  otherwise (a checkout that was never published) `latest` with a note that
+ *  points at --local-dev. Network failure means `latest` (never blocks setup). */
+export declare function resolveDefaultChannel(installedVersion: string, deps?: DefaultChannelDeps): Promise<{
     channel: RefreshChannel;
     note?: string;
 }>;
@@ -118,6 +136,8 @@ export interface SkillsVersionCheckInput {
     candidates: SkillMarkerCandidate[];
     /** npm latest, when known, so the refresh command names the right dist-tag. */
     latestRegistryVersion?: string;
+    /** npm next, when known: the refresh names `next` only when it is this CLI. */
+    nextRegistryVersion?: string;
     /** Resolves how the stale agent's MCP entry was recorded; defaults to
      *  detectRecordedInstall. Seam for tests. */
     recordedInstall?: (agent: string) => Promise<RecordedInstall | null> | RecordedInstall | null;