summer-engine 2.8.2 → 3.0.0

package/dist/installer/skill-locations.js

@@ -0,0 +1,170 @@
+/**
+ * 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 { join } from "path";
+import { homedir, platform } from "os";
+import { AGENT_CLIENTS } from "../core/skills-registry.js";
+import { tildeify } from "../core/format.js";
+export const SKILL_SCOPES = ["user", "project"];
+function isAgentClient(value) {
+    return AGENT_CLIENTS.includes(value);
+}
+function isSkillScope(value) {
+    return SKILL_SCOPES.includes(value);
+}
+/** Throws with a user-facing message on an unknown agent. */
+export function parseSkillAgent(value) {
+    if (isAgentClient(value))
+        return value;
+    throw new Error(`Unknown agent: ${value}. Use one of: ${AGENT_CLIENTS.join(", ")}.`);
+}
+/** Throws with a user-facing message on an unknown scope. */
+export function parseSkillScope(value) {
+    if (isSkillScope(value))
+        return value;
+    throw new Error(`Unknown scope: ${value}. Use user or project.`);
+}
+/** Pick the agent from --agent / legacy --as-claude-skill / --as-cursor-skill
+ *  (default "summer"); throws on conflicting flags. */
+export function resolveSkillAgent(opts) {
+    if (opts.asClaudeSkill && opts.asCursorSkill) {
+        throw new Error("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) {
+        throw new Error(`Conflicting agent options: --agent ${opts.agent} with legacy alias for ${legacyAgent}.`);
+    }
+    return parseSkillAgent(opts.agent ?? legacyAgent ?? "summer");
+}
+/** Explicit --scope wins; otherwise project-rooted agents default to "project". */
+export function resolveSkillScope(agent, opts) {
+    if (opts.scope)
+        return parseSkillScope(opts.scope);
+    if (agent === "cursor" ||
+        agent === "windsurf" ||
+        agent === "cline" ||
+        agent === "roo-code" ||
+        agent === "kilo-code") {
+        return "project";
+    }
+    return "user";
+}
+export 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: "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":
+            // Gemini discovers extension skills from <extension>/skills/<name>/SKILL.md
+            // (geminicli.com/docs/extensions/reference), so copy the skill directories
+            // as-is. The extension dir itself is written by `summer setup gemini`.
+            return {
+                kind: "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 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");
+}
+/** One-line, human path pattern for where an install location puts skills. */
+export function describeInstallLocation(location) {
+    const p = tildeify(location.path);
+    switch (location.kind) {
+        case "skill-dir":
+            return `${p}/<skill>/SKILL.md`;
+        case "cursor-rule-dir":
+            return `${p}/summer-<skill>.mdc`;
+        case "cline-rule-dir":
+        case "opencode-skill-dir":
+            return `${p}/summer-<skill>.md`;
+        case "windsurf-rule-file":
+            return p;
+    }
+}

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

@@ -0,0 +1,174 @@
+/**
+ * Version drift detection helpers used by `summer doctor` and the MCP server
+ * boot path.
+ *
+ * Two checks are exposed:
+ *   - cli-version-current: compares installed package.json version against the
+ *     latest published `summer-engine` on the npm registry.
+ *   - skills-version-stale: reads a `.summer-version` marker written into the
+ *     skill install dir (per-agent) and compares against the current CLI.
+ *
+ * Both are designed to be silent on offline / network errors — we never want
+ * to false-alarm a user just because their wifi is flaky.
+ */
+import { type StdioMcpServerConfig } from "./agent-config.js";
+export interface SemverParts {
+    major: number;
+    minor: number;
+    patch: number;
+}
+export type DriftSeverity = "ok" | "warning" | "fail";
+export interface DriftClassification {
+    severity: DriftSeverity;
+    reason: "current" | "ahead" | "patch-only" | "minor-drift" | "major-drift" | "behind";
+}
+export declare function parseSemver(version: string): SemverParts | null;
+export declare function compareSemver(a: SemverParts, b: SemverParts): number;
+/**
+ * Classify drift between an installed and a target version.
+ *
+ *   ok        installed >= target, OR installed is behind only on patch
+ *             OR installed differs only in pre-release/build metadata.
+ *   warning   one minor version behind on the same major.
+ *   fail      two or more minors behind, or any major-version drift behind.
+ */
+export declare function classifyDrift(installed: SemverParts, target: SemverParts): DriftClassification;
+export interface RegistryFetchOptions {
+    /** Override the default fetch (used in tests). Must implement the global fetch shape. */
+    fetchImpl?: typeof fetch;
+    /** Override the timeout. */
+    timeoutMs?: number;
+    /** Override the URL (used in tests). */
+    url?: string;
+}
+export interface RegistryFetchResult {
+    ok: true;
+    version: string;
+}
+export interface RegistryFetchFailure {
+    ok: false;
+    reason: "registry-unreachable";
+    message?: string;
+}
+export declare function fetchLatestRegistryVersion(options?: RegistryFetchOptions): Promise<RegistryFetchResult | RegistryFetchFailure>;
+/**
+ * Build the `cli-version-current` doctor check. Pure helper so tests can drive
+ * registry responses through `fetchImpl` rather than touching the network.
+ */
+export interface CliVersionCheckInput {
+    installedVersion: string;
+    registry: RegistryFetchResult | RegistryFetchFailure;
+}
+export interface CliVersionCheckOutput {
+    status: DriftSeverity;
+    message: string;
+    details: Record<string, unknown>;
+}
+export declare function buildCliVersionCheck(input: CliVersionCheckInput): CliVersionCheckOutput;
+export declare const SKILL_VERSION_MARKER_FILENAME = ".summer-version";
+export interface SkillVersionMarker {
+    version: string;
+    installedAt: string;
+}
+export declare function readSkillMarker(dir: string): SkillVersionMarker | null;
+export declare function writeSkillMarker(dir: string, version: string, now?: Date): string;
+/**
+ * Candidate locations for skill-version markers. Listed roughly in order of
+ * how likely a Summer user is to have them populated. We probe every candidate,
+ * not just the first one — if multiple agents have markers, the most-stale one
+ * wins so we surface the worst case to the user.
+ */
+export interface SkillMarkerCandidate {
+    agent: string;
+    dir: string;
+}
+export declare function defaultSkillMarkerCandidates(): SkillMarkerCandidate[];
+/**
+ * How the agent's Summer MCP entry was recorded by `summer setup`
+ * (agent-config.ts createSummerMcpServerConfig): a `--local-dev` link runs
+ * `node <checkout>/dist/bin/summer.js mcp`; a normal install runs
+ * `npx -y summer-engine@latest mcp`. The refresh command doctor recommends
+ * must keep that shape — the npx form on a local-dev machine would replace
+ * the checkout link with the published package (E2E 2026-09-03 F-09).
+ */
+export interface RecordedInstall {
+    localDev: boolean;
+    /** The CLI entry point the agent runs, when local-dev. */
+    cliPath: string | null;
+    /** Where the answer came from: the agent's config file, or — when it has
+     *  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;
+/** 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<{
+    channel: RefreshChannel;
+    note?: string;
+}>;
+export interface SkillsVersionCheckInput {
+    installedCliVersion: string;
+    candidates: SkillMarkerCandidate[];
+    /** npm latest, when known, so the refresh command names the right dist-tag. */
+    latestRegistryVersion?: 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;
+}
+export interface SkillsVersionCheckOutput {
+    /** "ok" or "warning" — stale skills never fail doctor (TESTING.md §d). */
+    status: DriftSeverity;
+    message: string;
+    details: Record<string, unknown>;
+}
+export declare function buildSkillsVersionCheck(input: SkillsVersionCheckInput): Promise<SkillsVersionCheckOutput>;
+/**
+ * The command that refreshes an agent's skills without changing how its MCP
+ * entry was recorded: the local-dev form re-links the same checkout
+ * (`setup --local-dev --force` re-copies the checkout's skills); the npx form
+ * is for installs that already run the published package.
+ */
+export declare function skillsRefreshCommand(agent: string, install: RecordedInstall | null, channel?: RefreshChannel): string;
+/** The shape `summer setup --local-dev` writes: `node <…>/dist/bin/summer.js mcp`
+ *  (createSummerMcpServerConfig(true)). */
+export declare function isLocalDevServerConfig(server: StdioMcpServerConfig): boolean;
+/**
+ * Read the Summer MCP entry an agent's config records, shape-tolerantly
+ * (this is the read side of agent-config.ts's per-format writers):
+ *   json           {"mcpServers": {"summer-engine": {command, args}}}     Claude Code, Cursor, …
+ *   json-copilot   {"mcpServers": {"summer-engine": {type, command, args}}}
+ *   json-vscode    {"servers":    {"summer-engine": {type, command, args}}}
+ *   json-opencode  {"mcp":        {"summer-engine": {type, command: [cmd, ...args]}}}
+ *   toml (codex)   [mcp_servers.summer-engine]\ncommand = "…"\nargs = ["…", …]
+ * Returns null when the file is missing, unparsable, or has no Summer entry.
+ */
+export declare function readRecordedMcpServer(text: string, format: "json" | "toml" | "json-opencode" | "json-copilot" | "json-vscode"): StdioMcpServerConfig | null;
+/** Is the CLI running this check a source checkout rather than an installed
+ *  package? npm/npx/global installs all live under a node_modules directory. */
+export declare function runningCliIsCheckout(packageRoot?: string): boolean;
+/**
+ * How `summer setup` recorded the agent's Summer MCP entry. Resolves the
+ * agent's user-scope config path through agent-config's own target
+ * resolution (print mode: no file is written or read there), then reads the
+ * entry. Marker agents without an agent config ("summer") and agents whose
+ * config has no readable Summer entry fall back to the nature of the running
+ * CLI: a checkout recommends re-linking itself, an installed package the npx form.
+ */
+export declare function detectRecordedInstall(agent: string): Promise<RecordedInstall | null>;
+/**
+ * Helper used by the MCP server boot path to render a one-line drift notice.
+ * Returns null when no notice is needed (fresh, ahead, patch-only, offline).
+ */
+export interface BootDriftNotice {
+    installedVersion: string;
+    latestVersion: string;
+    agent?: string;
+    text: string;
+}
+export declare function buildBootDriftNotice(installedVersion: string, registry: RegistryFetchResult | RegistryFetchFailure, agent?: string): BootDriftNotice | null;

package/dist/{lib → installer}/version-check.js

@@ -11,9 +11,11 @@
  * Both are designed to be silent on offline / network errors — we never want
  * to false-alarm a user just because their wifi is flaky.
  */
-import { existsSync, readFileSync, writeFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
-import { join } from "node:path";
+import { join, sep } from "node:path";
+import { PACKAGE_ROOT } from "../core/package-root.js";
+import { configureAgentMcp, parseAgent, SUMMER_MCP_SERVER_NAME, } from "./agent-config.js";
 const NPM_REGISTRY_LATEST_URL = "https://registry.npmjs.org/summer-engine/latest";
 const REGISTRY_FETCH_TIMEOUT_MS = 3000;
 export function parseSemver(version) {
@@ -224,7 +226,30 @@ export function defaultSkillMarkerCandidates() {
     }
     return candidates;
 }
-export function buildSkillsVersionCheck(input) {
+/** 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 function refreshChannel(installedVersion, latestVersion) {
+    const installed = parseSemver(installedVersion);
+    const latest = latestVersion ? parseSemver(latestVersion) : null;
+    if (!installed || !latest)
+        return "latest";
+    return classifyDrift(installed, latest).reason === "ahead" ? "next" : "latest";
+}
+/** 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 async function resolveDefaultChannel(installedVersion) {
+    const registry = await fetchLatestRegistryVersion();
+    if (!registry.ok)
+        return { channel: "latest" };
+    const channel = refreshChannel(installedVersion, registry.version);
+    return channel === "next"
+        ? { channel, note: `This CLI (${installedVersion}) is ahead of npm latest (${registry.version}); the MCP entry is pinned to summer-engine@next so the agent keeps running this release. Pass --channel latest to override.` }
+        : { channel };
+}
+export async function buildSkillsVersionCheck(input) {
     const cliParsed = parseSemver(input.installedCliVersion);
     if (!cliParsed) {
         return {
@@ -274,35 +299,153 @@ export function buildSkillsVersionCheck(input) {
         installedAt: worst.marker.installedAt,
         cliVersion: input.installedCliVersion,
     };
-    switch (worst.drift.severity) {
-        case "ok":
-            return {
-                status: "ok",
-                message: `skills v${worst.marker.version} match CLI`,
-                details: baseDetails,
-            };
-        case "warning":
-            return {
-                status: "warning",
-                message: `skills v${worst.marker.version} are one minor version behind v${input.installedCliVersion}`,
-                details: {
-                    ...baseDetails,
-                    recommendedAction: skillsRefreshCommand(worst.agent),
-                },
-            };
-        case "fail":
-            return {
-                status: "fail",
-                message: `skills v${worst.marker.version} are significantly behind v${input.installedCliVersion}`,
-                details: {
-                    ...baseDetails,
-                    recommendedAction: skillsRefreshCommand(worst.agent),
-                },
-            };
+    if (worst.drift.severity === "ok") {
+        return {
+            status: "ok",
+            message: `skills v${worst.marker.version} match CLI`,
+            details: baseDetails,
+        };
     }
+    // Skills that lag the CLI still work — the toolkit is not broken, the
+    // library it installed is older than the one it ships. That is a warning
+    // with a refresh command, never an exit-1 failure; a "fail"-grade drift
+    // (two minors or a major behind) only changes the wording.
+    const install = await resolveRecordedInstall(input.recordedInstall, worst.agent);
+    return {
+        status: "warning",
+        message: worst.drift.severity === "fail"
+            ? `skills v${worst.marker.version} are significantly behind v${input.installedCliVersion}`
+            : `skills v${worst.marker.version} are one minor version behind v${input.installedCliVersion}`,
+        details: {
+            ...baseDetails,
+            drift: worst.drift.reason,
+            ...(install ? { install } : {}),
+            recommendedAction: skillsRefreshCommand(worst.agent, install, refreshChannel(input.installedCliVersion, input.latestRegistryVersion)),
+        },
+    };
 }
-function skillsRefreshCommand(agent) {
-    return `npx clear-npx-cache && npx -y summer-engine@latest setup ${agent} --yes --force`;
+async function resolveRecordedInstall(resolver, agent) {
+    try {
+        return (await (resolver ?? detectRecordedInstall)(agent)) ?? null;
+    }
+    catch {
+        // A detection failure must not break doctor; the npx form is the
+        // conservative default only when nothing says local-dev.
+        return null;
+    }
+}
+/**
+ * The command that refreshes an agent's skills without changing how its MCP
+ * entry was recorded: the local-dev form re-links the same checkout
+ * (`setup --local-dev --force` re-copies the checkout's skills); the npx form
+ * is for installs that already run the published package.
+ */
+export function skillsRefreshCommand(agent, install, channel = "latest") {
+    if (install?.localDev && install.cliPath) {
+        return `node ${install.cliPath} setup ${agent} --local-dev --yes --force`;
+    }
+    const tag = channel === "next" ? "next" : "latest";
+    return `npx clear-npx-cache && npx -y summer-engine@${tag} setup ${agent} --yes --force${channel === "next" ? " --channel next" : ""}`;
+}
+/** The shape `summer setup --local-dev` writes: `node <…>/dist/bin/summer.js mcp`
+ *  (createSummerMcpServerConfig(true)). */
+export function isLocalDevServerConfig(server) {
+    const entry = server.args[0] ?? "";
+    return (server.command === "node" &&
+        /(^|[\\/])bin[\\/]summer\.js$/.test(entry) &&
+        server.args[1] === "mcp");
+}
+/**
+ * Read the Summer MCP entry an agent's config records, shape-tolerantly
+ * (this is the read side of agent-config.ts's per-format writers):
+ *   json           {"mcpServers": {"summer-engine": {command, args}}}     Claude Code, Cursor, …
+ *   json-copilot   {"mcpServers": {"summer-engine": {type, command, args}}}
+ *   json-vscode    {"servers":    {"summer-engine": {type, command, args}}}
+ *   json-opencode  {"mcp":        {"summer-engine": {type, command: [cmd, ...args]}}}
+ *   toml (codex)   [mcp_servers.summer-engine]\ncommand = "…"\nargs = ["…", …]
+ * Returns null when the file is missing, unparsable, or has no Summer entry.
+ */
+export function readRecordedMcpServer(text, format) {
+    if (!text.trim())
+        return null;
+    if (format === "toml") {
+        const table = text.match(new RegExp(`^\\[mcp_servers\\.${SUMMER_MCP_SERVER_NAME.replace(/[-.]/g, "\\$&")}\\]\\s*$([\\s\\S]*?)(?=^\\[|(?![\\s\\S]))`, "m"));
+        if (!table)
+            return null;
+        const command = table[1].match(/^command\s*=\s*"((?:[^"\\]|\\.)*)"/m)?.[1];
+        const argsText = table[1].match(/^args\s*=\s*\[([^\]]*)\]/m)?.[1] ?? "";
+        if (!command)
+            return null;
+        const args = [...argsText.matchAll(/"((?:[^"\\]|\\.)*)"/g)].map((m) => m[1].replace(/\\(.)/g, "$1"));
+        return { command: command.replace(/\\(.)/g, "$1"), args };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const root = parsed;
+    for (const container of ["mcpServers", "servers", "mcp"]) {
+        const servers = root[container];
+        if (!servers || typeof servers !== "object")
+            continue;
+        const entry = servers[SUMMER_MCP_SERVER_NAME];
+        if (!entry || typeof entry !== "object")
+            continue;
+        const record = entry;
+        if (Array.isArray(record.command)) {
+            const [command, ...args] = record.command.filter((part) => typeof part === "string");
+            return command ? { command, args } : null;
+        }
+        if (typeof record.command === "string") {
+            const args = Array.isArray(record.args)
+                ? record.args.filter((part) => typeof part === "string")
+                : [];
+            return { command: record.command, args };
+        }
+    }
+    return null;
+}
+/** Is the CLI running this check a source checkout rather than an installed
+ *  package? npm/npx/global installs all live under a node_modules directory. */
+export function runningCliIsCheckout(packageRoot = PACKAGE_ROOT) {
+    return !packageRoot.split(/[\\/]/).includes("node_modules");
+}
+/**
+ * How `summer setup` recorded the agent's Summer MCP entry. Resolves the
+ * agent's user-scope config path through agent-config's own target
+ * resolution (print mode: no file is written or read there), then reads the
+ * entry. Marker agents without an agent config ("summer") and agents whose
+ * config has no readable Summer entry fall back to the nature of the running
+ * CLI: a checkout recommends re-linking itself, an installed package the npx form.
+ */
+export async function detectRecordedInstall(agent) {
+    const supported = parseAgent(agent);
+    if (supported) {
+        try {
+            const target = await configureAgentMcp({ agent: supported, scope: "user", print: true });
+            if (existsSync(target.path)) {
+                const recorded = readRecordedMcpServer(readFileSync(target.path, "utf-8"), target.format);
+                if (recorded) {
+                    const localDev = isLocalDevServerConfig(recorded);
+                    return { localDev, cliPath: localDev ? recorded.args[0] ?? null : null, source: "agent-config" };
+                }
+            }
+        }
+        catch {
+            // Unreadable config: fall through to the running-CLI answer.
+        }
+    }
+    const checkout = runningCliIsCheckout();
+    return {
+        localDev: checkout,
+        cliPath: checkout ? [PACKAGE_ROOT, "dist", "bin", "summer.js"].join(sep) : null,
+        source: "running-cli",
+    };
 }
 export function buildBootDriftNotice(installedVersion, registry, agent) {
     if (!registry.ok)
@@ -324,15 +467,3 @@ export function buildBootDriftNotice(installedVersion, registry, agent) {
         text,
     };
 }
-// Re-export for tests / callers that want to know the install marker's mtime.
-export function markerMtime(dir) {
-    const path = join(dir, SKILL_VERSION_MARKER_FILENAME);
-    if (!existsSync(path))
-        return null;
-    try {
-        return statSync(path).mtimeMs;
-    }
-    catch {
-        return null;
-    }
-}

package/dist/{lib/mcp-boot-notice.d.ts → mcp/boot-notice.d.ts}

@@ -1,3 +1,3 @@
-import type { BootDriftNotice } from "./version-check.js";
+import type { BootDriftNotice } from "../installer/version-check.js";
 export declare function getCachedBootDriftNotice(): BootDriftNotice | null;
 export declare function setCachedBootDriftNotice(notice: BootDriftNotice | null): void;

package/dist/{commands/mcp.js → mcp/command.js}

@@ -1,6 +1,6 @@
-import { Command } from "commander";
-import { configureAgentMcp, parseAgent, parseScope, supportedAgents, } from "../lib/agent-config.js";
-import { startMcpServer } from "../mcp/server.js";
+import { Command, Option } from "commander";
+import { configureAgentMcp, parseAgent, parseScope, supportedAgents, } from "../installer/agent-config.js";
+import { startMcpServer } from "./server.js";
 export const mcpCommand = new Command("mcp")
     .description("Start the MCP server for AI tool integration (Cursor, Claude Code, etc.)")
     .option("--project <path>", "Bind local engine tools to the editor running this project")
@@ -11,13 +11,22 @@ export const mcpCommand = new Command("mcp")
         instanceId: opts.instance,
     });
 });
+// Deprecated alias. `summer setup <agent>` (src/cli/commands/setup.ts) is the
+// one setup path: the same configureAgentMcp() write plus skills + doctor.
+// This stays for one release so existing docs/scripts keep working; it cannot
+// delegate to the cli layer (contract §2: mcp never imports cli), so it calls
+// the shared installer directly and says where to go.
 mcpCommand
     .command("setup <agent>")
-    .description("Configure an AI agent to use the Summer Engine MCP server")
+    .description("Deprecated alias of `summer setup <agent>`: write only the MCP config for an agent")
     .option("--scope <scope>", "Configuration scope: user or project", "user")
     .option("--print", "Print the MCP config snippet instead of writing files")
     .option("--dry-run", "Show planned changes without writing files")
-    .option("--local-dev", "Use the local built CLI instead of npx summer-engine")
+    .addOption(
+// Contributor-only: point the config at this checkout's built CLI instead
+// of npx summer-engine. Hidden from the public surface; also honoured
+// when SUMMER_DEV=1 is set.
+new Option("--local-dev", "Use the local built CLI instead of npx summer-engine").hideHelp())
     .option("--json", "Print the setup result as JSON")
     .action(async (agentValue, opts) => {
     const agent = parseAgent(agentValue);
@@ -33,12 +42,15 @@ mcpCommand
         scope,
         print: opts.print,
         dryRun: opts.dryRun,
-        localDev: opts.localDev,
+        localDev: opts.localDev || process.env.SUMMER_DEV === "1",
     });
     if (opts.json) {
         console.log(JSON.stringify(result, null, 2));
         return;
     }
+    if (!opts.print) {
+        console.warn(`Note: 'summer mcp setup' is deprecated; use 'summer setup ${agent}' (same MCP config, plus skills and doctor).`);
+    }
     if (result.print) {
         console.log(result.snippet.trimEnd());
     }