summer-engine 4.5.0 → 4.6.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "summer",
       "source": "./",
-      "version": "4.5.0",
+      "version": "4.6.0",
       "description": "The game engine built for AI. Any agent makes a multiplayer game and publishes it. A first-run guide (/summer:start), game-dev skills, and two MCP servers: the bridge to the Summer Engine desktop app, and Summer's hosted cloud server for people without it.",
       "author": {
         "name": "Summer Engine",

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "summer",
   "displayName": "Summer Engine",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "description": "The game engine built for AI. Any agent makes a multiplayer game and publishes it. A first-run guide (/summer:start), game-dev skills, and two MCP servers: the bridge to the Summer Engine desktop app, and Summer's hosted cloud server for people without it.",
   "author": {
     "name": "Summer Engine",

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "_generated": "GENERATED from integrations/codex — do not edit; npm run generate:registry",
   "name": "summer",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "description": "The game engine built for AI. Any agent makes a multiplayer game and publishes it. Game-dev skills, lifecycle hooks, and a 125-tool MCP bridge to the Summer Engine desktop app.",
   "author": {
     "name": "Summer Engine",

package/.cursor-plugin/plugin.json

@@ -3,7 +3,7 @@
   "_generated": "GENERATED from integrations/cursor — do not edit; npm run generate:registry",
   "name": "summer",
   "displayName": "Summer Engine",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "description": "The game engine built for AI. Any agent makes a multiplayer game and publishes it. Game-dev skills, lifecycle hooks, and a 125-tool MCP bridge to the Summer Engine desktop app.",
   "author": {
     "name": "Summer Engine",

package/.factory-plugin/plugin.json

@@ -2,7 +2,7 @@
   "_generated": "GENERATED from integrations/factory — do not edit; npm run generate:registry",
   "name": "summer",
   "description": "The game engine built for AI. Any agent makes a multiplayer game and publishes it. Game-dev skills, lifecycle hooks, and a 125-tool MCP bridge to the Summer Engine desktop app.",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "author": {
     "name": "Summer Engine",
     "email": "founders@summerengine.com",

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to summer-engine will be documented here. Following [Keep a
 
 ## [Unreleased]
 
+## [4.6.0] - 2026-10-21
+
+A first game that looks finished, and `summer setup` for the Summer desktop app's one-click agent connect.
+
+- **`summer setup` for installers: find the agents, read each step, run a bundled Node.js.** For the Summer desktop app's installer, which connects the person's coding agent in one click and ships its own Node.js (Claude Code and Codex install without one).
+  - **`summer setup --detect --json`** lists every supported agent: whether it is installed (`installed`, `programFound` and each hit in `detectedBy`: a command on PATH or in the usual install folders, a macOS app or Windows program, the agent's own folder, a VS Code extension), its MCP config file, and whether that file already lists `summer-engine`. It writes nothing.
+  - **`summer setup <agent> --yes --json` reports each step** in `steps`: the MCP entry, Summer Games, skills, project files and doctor, each with `ok`, a `status` and, on failure, an `error` with a `code` (`config_invalid`, `config_not_writable`, `skills_install_failed`, `runtime_not_found`, ...). A failed step no longer stops the others, and any failure exits 1. An error before setup starts (an unknown agent, a bad option) is one JSON document too. The output for people is unchanged.
+  - **`--runtime <node> --package-dir <dir>`** writes the MCP entry as `<node> <dir>/dist/bin/summer.js mcp` instead of `npx`, in every agent's file format. Setup checks that both exist and that the folder is the summer-engine package. Doctor's skills refresh keeps the bundled runtime.
+- **First game: make it look finished.** A first game used to come out as grey boxes: the `make-game` skill told agents to build the first playable from shapes and add art later, and nothing an agent always reads said anything about looks. Now the rule sits where agents read it without choosing to:
+  - **MCP server instructions** open with it, inside the first 512 characters (Codex keeps the first 512): keep the features the person asked for and raise the look (sky and sun with shadows, fog, a texture on every surface, real models from the starter project and `summer_assets_search` first, never capsules or boxes as final art, one palette, a styled UI font), then play it and check a screenshot of the running game. They no longer open with "call summer_get_project_context first".
+  - **The project's `AGENTS.md` block** (written by `summer create` and `summer setup --yes`) has a "First game: make it look finished" section. It now says to write GDScript files directly and to create scenes and import assets through Summer, and its publishing line matches the store: a game goes live when Summer's automated checks pass, with no wait for a review.
+  - **`make-game`:** the first playable already looks good; generation still never blocks the first play (starter and library art first).
+
 ## [4.5.0] - 2026-10-19
 
 4.4.0 was not published to npm. 4.5.0 is the first release with everything in it (the [4.4.0] section below), plus these changes.

package/dist/cli/commands/setup.js

@@ -2,8 +2,10 @@ import { spawnSync } from "child_process";
 import { existsSync, readFileSync } from "fs";
 import { relative } from "path";
 import { Command, Option } from "commander";
-import { configureAgentMcp, configureSummerGamesMcp, resolveAgentSelection, resolveConfigScope, supportedAgents, } from "../../installer/agent-config.js";
+import { configureAgentMcp, configureSummerGamesMcp, resolveAgentSelection, resolveBundledRuntime, resolveConfigScope, supportedAgents, } from "../../installer/agent-config.js";
 import { previewNote, setupSkills } from "../../installer/setup.js";
+import { detectAgents } from "../../installer/agent-detect.js";
+import { SetupError, toStepError } from "../../installer/setup-error.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";
@@ -23,6 +25,8 @@ const MCP_ENTRY_FLAGS = [
     ["localDev", "--local-dev"],
     ["channel", "--channel"],
     ["profile", "--profile"],
+    ["runtime", "--runtime"],
+    ["packageDir", "--package-dir"],
 ];
 export const setupCommand = new Command("setup")
     .description("Configure Summer Engine for an AI agent and run diagnostics. For agents that can sign in to it, it also adds Summer Games (summer-games). --cli installs the skills only: the agent runs summer commands in its shell, with no MCP server.")
@@ -32,6 +36,9 @@ export const setupCommand = new Command("setup")
     .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("--runtime <node>", "Run the MCP server with this node executable instead of npx: <node> <package-dir>/dist/bin/summer.js mcp. Needs --package-dir. For installers that ship their own Node.js")
+    .option("--package-dir <dir>", "The summer-engine package folder (package.json and dist/bin/summer.js) that --runtime runs")
+    .option("--detect", "List every supported agent: installed or not, its MCP config file, and whether it already lists summer-engine. Writes nothing; takes no agent. Use with --json")
     .option("--channel <dist-tag>", "npm dist-tag or exact version the agent's MCP entry runs: npx -y summer-engine@<dist-tag> mcp (default latest; a CLI newer than npm latest pins next when next is this version, else this version). SUMMER_CHANNEL does the same.")
     .option("--yes", "Apply practical setup steps without prompting")
     .option("--no-games", "Do not add the Summer Games MCP (summer-games: friends, parties and messages as you, signed in through summer.games)")
@@ -49,8 +56,52 @@ export const setupCommand = new Command("setup")
     // 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);
+    if (opts.detect) {
+        runDetect(agentArg, opts);
+        return;
+    }
+    if (!opts.json) {
+        await setupAgent(agentArg, opts);
+        return;
+    }
+    // --json: one JSON document on stdout, also when setup cannot start.
+    try {
+        await setupAgent(agentArg, opts);
+    }
+    catch (error) {
+        console.log(JSON.stringify({ ok: false, error: toStepError(error, "setup_failed"), steps: [] }, null, 2));
+        process.exit(1);
+    }
+});
+/**
+ * Runs one step. With --json a throw becomes the step's coded error and the
+ * other steps still run; without it the throw ends setup as it always did.
+ */
+async function runStep(json, fallbackCode, run) {
+    if (!json)
+        return { value: await run() };
+    try {
+        return { value: await run() };
+    }
+    catch (error) {
+        return { value: null, error: toStepError(error, fallbackCode) };
+    }
+}
+async function setupAgent(agentArg, opts) {
+    let agent;
+    try {
+        agent = resolveAgentSelection(agentArg, opts.agent);
+    }
+    catch (error) {
+        throw new SetupError("unknown_agent", error instanceof Error ? error.message : String(error));
+    }
+    let scope;
+    try {
+        scope = resolveConfigScope(opts.scope);
+    }
+    catch (error) {
+        throw new SetupError("invalid_scope", error instanceof Error ? error.message : String(error));
+    }
     if (opts.removeAllowRules) {
         await removeCliAllowRules(agent, scope, opts);
         return;
@@ -63,8 +114,14 @@ export const setupCommand = new Command("setup")
     if (opts.allowRules)
         console.error(`  ${sym.warn()}  ${c.yellow("--allow-rules works with --cli only (the MCP server asks through the agent's own tool approvals); no rules were added.")}`);
     const profile = resolveSetupProfile(opts);
-    const defaultChannel = await resolveDefaultChannel(cliVersion);
-    const config = await configureAgentMcp({
+    const runtime = resolveBundledRuntime(opts.runtime, opts.packageDir);
+    if (runtime && (opts.localDev || opts.channel)) {
+        throw new SetupError("invalid_option", `--runtime runs a bundled summer-engine; leave out ${opts.localDev ? "--local-dev" : "--channel"}.`);
+    }
+    const json = Boolean(opts.json);
+    // A bundled runtime runs the package beside it, so npm's tags do not matter (and no network call is made).
+    const defaultChannel = runtime ? { channel: "latest" } : await resolveDefaultChannel(cliVersion);
+    const mcp = await runStep(json, "mcp_entry_failed", () => configureAgentMcp({
         agent,
         scope,
         dryRun: opts.dryRun,
@@ -72,14 +129,19 @@ export const setupCommand = new Command("setup")
         localDev: Boolean(opts.localDev) || process.env.SUMMER_DEV === "1",
         channel: opts.channel ?? process.env.SUMMER_CHANNEL ?? defaultChannel.channel,
         profile,
-    });
-    const games = opts.games === false || opts.assetsOnly || opts.print
-        ? null
-        : await configureSummerGamesMcp({ agent, scope, dryRun: opts.dryRun });
-    if (!opts.channel && !process.env.SUMMER_CHANNEL && defaultChannel.note && !opts.print) {
-        console.log(`  ${c.dim(defaultChannel.note)}`);
-    }
-    const skills = setupSkills(agent, {
+        runtime: runtime ?? undefined,
+    }));
+    const config = mcp.value;
+    const gamesSkipped = opts.games === false || opts.assetsOnly || opts.print;
+    const gamesStep = gamesSkipped
+        ? { value: null }
+        : await runStep(json, "summer_games_failed", () => configureSummerGamesMcp({ agent, scope, dryRun: opts.dryRun }));
+    const games = gamesStep.value;
+    if (!runtime && !opts.channel && !process.env.SUMMER_CHANNEL && defaultChannel.note && !opts.print) {
+        // On stderr with --json, so stdout stays one JSON document.
+        (json ? console.error : console.log)(`  ${c.dim(defaultChannel.note)}`);
+    }
+    const skillsStep = await runStep(json, "skills_install_failed", () => setupSkills(agent, {
         dryRun: Boolean(opts.dryRun || opts.print),
         yes: Boolean(opts.yes),
         force: Boolean(opts.force),
@@ -87,26 +149,104 @@ export const setupCommand = new Command("setup")
         recommended: Boolean(opts.recommended),
         stableOnly: Boolean(opts.stableOnly),
         assetsOnly: Boolean(opts.assetsOnly),
-    });
-    const projectFiles = setupProjectInstructions(opts);
+    }));
+    const skills = skillsStep.value ?? { status: "failed", message: skillsStep.error?.message ?? "Skill install failed." };
+    const projectStep = await runStep(json, "project_files_failed", () => setupProjectInstructions(opts));
+    const projectFiles = projectStep.value;
     const doctor = await runDoctor({ quiet: true });
-    if (opts.json) {
-        console.log(JSON.stringify({
-            ok: doctor.ok && skills.status !== "failed",
-            config,
-            games,
-            skills,
-            projectFiles,
-            doctor,
-        }, null, 2));
-    }
-    else {
-        printSetupResult(config, games, skills, doctor, projectFiles);
+    if (json) {
+        const steps = [
+            mcpEntryStep(config, mcp.error),
+            summerGamesStep(agent, games, gamesSkipped ? "skipped" : null, gamesStep.error, Boolean(opts.dryRun)),
+            skillsStepResult(skills, skillsStep.error),
+            projectFilesStep(projectFiles, projectStep.error, opts),
+            doctorStep(doctor),
+        ];
+        const ok = steps.every((step) => step.ok);
+        console.log(JSON.stringify({ ok, agent, scope, steps, config, games, skills, projectFiles, doctor }, null, 2));
+        if (!ok)
+            process.exit(1);
+        return;
     }
+    printSetupResult(config, games, skills, doctor, projectFiles);
     if (!doctor.ok || skills.status === "failed") {
         process.exit(1);
     }
-});
+}
+function mcpEntryStep(config, error) {
+    if (!config)
+        return { step: "mcp_entry", ok: false, status: "failed", error: error ?? { code: "mcp_entry_failed", message: "The MCP entry was not written." } };
+    const status = config.print ? "printed" : config.dryRun ? (config.changed ? "planned" : "unchanged") : config.wrote ? "written" : "unchanged";
+    return { step: "mcp_entry", ok: true, status, path: config.path, ...(config.warnings.length ? { warnings: config.warnings } : {}) };
+}
+function summerGamesStep(agent, games, skipped, error, dryRun) {
+    if (error)
+        return { step: "summer_games", ok: false, status: "failed", error };
+    if (skipped)
+        return { step: "summer_games", ok: true, status: "skipped" };
+    // configureSummerGamesMcp returns null only for agents without a Summer Games entry shape.
+    if (!games)
+        return { step: "summer_games", ok: true, status: "not_supported", warnings: [`${agentLabel(agent)} gets no Summer Games entry from setup.`] };
+    const status = games.existingName ? "exists" : dryRun ? (games.changed ? "planned" : "unchanged") : games.wrote ? "written" : "unchanged";
+    return { step: "summer_games", ok: true, status, path: games.path };
+}
+function skillsStepResult(skills, error) {
+    if (skills.status === "failed") {
+        return {
+            step: "skills",
+            ok: false,
+            status: "failed",
+            error: error ?? { code: "skills_install_failed", message: [skills.message, skills.stderr].filter(Boolean).join(" ") },
+        };
+    }
+    return { step: "skills", ok: true, status: skills.status, ...(skills.destination ? { path: skills.destination } : {}) };
+}
+function projectFilesStep(project, error, opts) {
+    if (error)
+        return { step: "project_files", ok: false, status: "failed", error };
+    if (!project) {
+        const skipped = opts.projectFiles === false || opts.print || opts.assetsOnly;
+        return { step: "project_files", ok: true, status: skipped ? "skipped" : "not_in_project" };
+    }
+    // A file setup leaves alone (a link out of the project, a broken Summer block) is a warning, as in the human output.
+    const warnings = project.files.filter((file) => file.reason).map((file) => `${file.path}: ${file.reason}`);
+    return { step: "project_files", ok: true, status: project.written ? "written" : "planned", path: project.root, ...(warnings.length ? { warnings } : {}) };
+}
+function doctorStep(doctor) {
+    if (doctor.ok)
+        return { step: "doctor", ok: true, status: "passed" };
+    const failed = doctor.checks.filter((check) => check.status === "fail");
+    return {
+        step: "doctor",
+        ok: false,
+        status: "failed",
+        error: { code: "doctor_failed", message: failed.map((check) => `${check.label}: ${check.message}`).join("; ") || "Doctor found a problem." },
+    };
+}
+/** `summer setup --detect`: every agent, installed or not, and whether it is linked. Writes nothing. */
+function runDetect(agentArg, opts) {
+    if (agentArg || opts.agent) {
+        const message = "--detect lists every agent; leave out the agent name.";
+        if (!opts.json)
+            throw new Error(message);
+        console.log(JSON.stringify({ ok: false, error: { code: "invalid_option", message }, agents: [] }, null, 2));
+        process.exit(1);
+        return;
+    }
+    const agents = detectAgents();
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: true, os: process.platform, agents }, null, 2));
+        return;
+    }
+    console.log("");
+    for (const agent of agents) {
+        if (agent.status === "legacy" && !agent.installed)
+            continue;
+        const mark = agent.installed ? sym.ok() : c.dim("-");
+        const linked = agent.mcpEntry ? c.dim(`linked  ${tildeify(agent.configPath)}`) : agent.installed ? c.dim(`not linked: summer setup ${agent.id}`) : c.dim("not found");
+        console.log(`  ${mark}  ${agent.label}  ${linked}`);
+    }
+}
 /**
  * `summer setup <agent> --cli`: the skills (the asset skills with --assets-only)
  * and no MCP server, so the agent runs Summer as `summer <area> <action>` in its
@@ -117,7 +257,7 @@ async function setupCliOnly(agent, scope, opts) {
     const spec = agentSpec(agent);
     const mcpFlags = MCP_ENTRY_FLAGS.filter(([key]) => opts[key] !== undefined && opts[key] !== false).map(([, flag]) => flag);
     if (mcpFlags.length > 0) {
-        throw new Error(`${mcpFlags.join(", ")} sets up the MCP entry, and --cli writes none. Leave ${mcpFlags.length === 1 ? "it" : "them"} out, or leave out --cli.`);
+        throw new SetupError("invalid_option", `${mcpFlags.join(", ")} sets up the MCP entry, and --cli writes none. Leave ${mcpFlags.length === 1 ? "it" : "them"} out, or leave out --cli.`);
     }
     const refusal = cliSetupRefusal(spec);
     if (refusal)
@@ -278,11 +418,11 @@ async function recordedMcpEntry(agent, scope) {
 function resolveSetupProfile(opts) {
     const profile = opts.profile === undefined ? undefined : parseProfile(opts.profile);
     if (profile === null) {
-        throw new Error(`Unknown --profile "${opts.profile}". Use one of: ${Object.keys(PROFILES).join(", ")}.`);
+        throw new SetupError("invalid_option", `Unknown --profile "${opts.profile}". Use one of: ${Object.keys(PROFILES).join(", ")}.`);
     }
     if (opts.assetsOnly) {
         if (profile && profile !== "assets")
-            throw new Error("--assets-only uses the assets profile; leave out --profile.");
+            throw new SetupError("invalid_option", "--assets-only uses the assets profile; leave out --profile.");
         return "assets";
     }
     return profile;
@@ -305,7 +445,10 @@ function printSetupResult(config, games, skills, doctor, projectFiles) {
     else {
         console.log(`  ${sym.ok()}  Already linked to ${c.bold(label)}  ${c.dim(tildeify(config.path))}`);
     }
-    if (config.localDev) {
+    if (config.runtime) {
+        console.log(`  ${c.dim("(bundled runtime)")}  MCP server command: ${c.dim(`${config.server.command} ${config.server.args.join(" ")}`)}`);
+    }
+    else 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") {

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

@@ -18,6 +18,10 @@ export interface AgentConfigOptions {
     channel?: string;
     /** MCP tool profile written as SUMMER_PROFILE; default the agent's own (full for most). */
     profile?: Profile;
+    /** A bundled Node runtime and summer-engine package (the Summer desktop installer):
+     *  the entry runs `<node> <packageDir>/dist/bin/summer.js mcp` instead of npx.
+     *  Check it with resolveBundledRuntime first. Ignores localDev and channel. */
+    runtime?: BundledRuntime;
     cwd?: string;
     env?: NodeJS.ProcessEnv;
 }
@@ -39,6 +43,8 @@ export interface AgentConfigResult {
     channel: string;
     /** The MCP tool profile the entry runs (full = every tool, no SUMMER_PROFILE written). */
     profile: Profile;
+    /** Set when the entry runs a bundled Node runtime (--runtime, --package-dir). */
+    runtime: BundledRuntime | null;
     warnings: string[];
     nextSteps: string[];
 }
@@ -89,6 +95,29 @@ export declare function normalizeChannel(channel: string | undefined): string;
  */
 export declare function withProfile(server: StdioMcpServerConfig, profile: Profile): StdioMcpServerConfig;
 export declare function createSummerMcpServerConfig(localDev: boolean, platform?: NodeJS.Platform, channel?: string): StdioMcpServerConfig;
+/**
+ * A Node runtime and a summer-engine package shipped next to each other (the
+ * Summer desktop installer bundles both, so the person needs no Node.js of
+ * their own). Both are absolute paths.
+ */
+export interface BundledRuntime {
+    /** The node executable (node, or node.exe on Windows). */
+    node: string;
+    /** The summer-engine package folder: the one with package.json and dist/bin/summer.js. */
+    packageDir: string;
+}
+/** The CLI entry point inside a summer-engine package folder. */
+export declare function bundledCliPath(packageDir: string): string;
+/**
+ * --runtime <node> and --package-dir <dir>: both or neither, and both must
+ * exist. The runtime must be an executable file (any file on Windows); the
+ * package folder must hold summer-engine's package.json and its built CLI.
+ * Returns absolute paths, so the agent's entry works from any folder.
+ */
+export declare function resolveBundledRuntime(node: string | undefined, packageDir: string | undefined, cwd?: string): BundledRuntime | null;
+/** The entry for a bundled runtime: `<node> <packageDir>/dist/bin/summer.js mcp`.
+ *  node is a real executable, so no cmd.exe wrapper is needed on Windows. */
+export declare function bundledRuntimeServerConfig(runtime: BundledRuntime): 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). */
 export declare function topLevelKey(format: McpFormat): string;

package/dist/installer/agent-config.js

@@ -1,9 +1,10 @@
-import { existsSync, readFileSync } from "fs";
+import { accessSync, constants as fsConstants, existsSync, readFileSync, statSync } from "fs";
 import { copyFile, mkdir, readFile, writeFile } from "fs/promises";
 import { dirname, join, resolve } from "path";
 import { fileURLToPath } from "url";
 import { Document, isMap, parseDocument } from "yaml";
 import { PACKAGE_ROOT } from "../core/package-root.js";
+import { SetupError } from "./setup-error.js";
 import { agentAliasMap, agentSpec, defaultPathContext, resolveMcpPath, supportedAgents, } from "./agent-table.js";
 export { supportedAgents } from "./agent-table.js";
 export const SUMMER_MCP_SERVER_NAME = "summer-engine";
@@ -50,7 +51,8 @@ export async function configureAgentMcp(options) {
     const channel = normalizeChannel(options.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 runtime = options.runtime ?? null;
+    const server = withProfile(runtime ? bundledRuntimeServerConfig(runtime) : createSummerMcpServerConfig(Boolean(options.localDev), process.platform, channel), profile);
     const target = resolveConfigTarget(spec, options.scope, cwd, env);
     // An entry an earlier setup wrote where the agent no longer reads (Devin Desktop moved from ~/.codeium/windsurf).
     const moved = spec.mcp.movedFrom ? spec.mcp.movedFrom(defaultPathContext(env, cwd)) : null;
@@ -76,9 +78,10 @@ export async function configureAgentMcp(options) {
         wrote: shouldWrite && update.changed,
         dryRun,
         print,
-        localDev: Boolean(options.localDev),
+        localDev: !runtime && Boolean(options.localDev),
         channel,
         profile,
+        runtime,
         warnings: target.warnings,
         nextSteps: [`Updated ${target.path}.`, spec.restart],
     };
@@ -320,6 +323,67 @@ export function createSummerMcpServerConfig(localDev, platform = process.platfor
         args: ["-y", spec, "mcp"],
     };
 }
+/** The CLI entry point inside a summer-engine package folder. */
+export function bundledCliPath(packageDir) {
+    return join(packageDir, "dist", "bin", "summer.js");
+}
+/**
+ * --runtime <node> and --package-dir <dir>: both or neither, and both must
+ * exist. The runtime must be an executable file (any file on Windows); the
+ * package folder must hold summer-engine's package.json and its built CLI.
+ * Returns absolute paths, so the agent's entry works from any folder.
+ */
+export function resolveBundledRuntime(node, packageDir, cwd = process.cwd()) {
+    if (node === undefined && packageDir === undefined)
+        return null;
+    if (!node || !packageDir) {
+        throw new SetupError("runtime_incomplete", "--runtime and --package-dir go together: name the node executable and the summer-engine package folder.");
+    }
+    const nodePath = resolve(cwd, node);
+    const nodeStat = statIfExists(nodePath);
+    if (!nodeStat)
+        throw new SetupError("runtime_not_found", `--runtime ${nodePath} does not exist.`);
+    if (!nodeStat.isFile())
+        throw new SetupError("runtime_not_found", `--runtime ${nodePath} is not a file. Name the node executable itself.`);
+    if (process.platform !== "win32") {
+        try {
+            accessSync(nodePath, fsConstants.X_OK);
+        }
+        catch {
+            throw new SetupError("runtime_not_executable", `--runtime ${nodePath} is not executable.`);
+        }
+    }
+    const dir = resolve(cwd, packageDir);
+    if (!statIfExists(dir)?.isDirectory())
+        throw new SetupError("package_dir_not_found", `--package-dir ${dir} is not a folder.`);
+    let name;
+    try {
+        name = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")).name;
+    }
+    catch {
+        name = undefined;
+    }
+    if (name !== "summer-engine") {
+        throw new SetupError("package_dir_invalid", `--package-dir ${dir} is not the summer-engine package: it has no package.json named summer-engine.`);
+    }
+    if (!statIfExists(bundledCliPath(dir))?.isFile()) {
+        throw new SetupError("package_dir_invalid", `--package-dir ${dir} has no built CLI at dist/bin/summer.js.`);
+    }
+    return { node: nodePath, packageDir: dir };
+}
+/** The entry for a bundled runtime: `<node> <packageDir>/dist/bin/summer.js mcp`.
+ *  node is a real executable, so no cmd.exe wrapper is needed on Windows. */
+export function bundledRuntimeServerConfig(runtime) {
+    return { command: runtime.node, args: [bundledCliPath(runtime.packageDir), "mcp"] };
+}
+function statIfExists(path) {
+    try {
+        return statSync(path);
+    }
+    catch {
+        return null;
+    }
+}
 export function renderConfigSnippet(agent, server) {
     const format = agentSpec(agent).format;
     if (format === "toml")
@@ -449,14 +513,14 @@ async function upsertYamlConfig(path, keyPath, entry, write) {
     // would make the root a flow mapping and the whole file would render as {}.
     const doc = current.trim() === "" ? new Document({}) : parseDocument(current);
     if (doc.errors.length > 0) {
-        throw new Error(`Could not parse YAML in ${path}: ${doc.errors[0].message}`);
+        throw new SetupError("config_invalid", `Could not parse YAML in ${path}: ${doc.errors[0].message}`);
     }
     if (!isMap(doc.contents)) {
-        throw new Error(`Expected ${path} to contain a YAML mapping.`);
+        throw new SetupError("config_invalid", `Expected ${path} to contain a YAML mapping.`);
     }
     const parent = doc.getIn(keyPath.slice(0, -1));
     if (parent !== undefined && parent !== null && !isMap(parent)) {
-        throw new Error(`Existing ${keyPath[0]} value in ${path} must be a mapping.`);
+        throw new SetupError("config_invalid", `Existing ${keyPath[0]} value in ${path} must be a mapping.`);
     }
     doc.setIn(keyPath, doc.createNode(entry));
     const next = doc.toString();
@@ -474,7 +538,7 @@ async function readJsonConfig(path) {
         content = await readFile(path, "utf-8");
     }
     catch (error) {
-        throw new Error(`Could not read ${path}: ${formatError(error)}`);
+        throw new SetupError("config_unreadable", `Could not read ${path}: ${formatError(error)}`);
     }
     if (content.trim() === "")
         return {};
@@ -483,10 +547,10 @@ async function readJsonConfig(path) {
         parsed = JSON.parse(content);
     }
     catch (error) {
-        throw new Error(`Could not parse JSON in ${path}: ${formatError(error)}`);
+        throw new SetupError("config_invalid", `Could not parse JSON in ${path}: ${formatError(error)}`);
     }
     if (!isJsonObject(parsed)) {
-        throw new Error(`Expected ${path} to contain a JSON object.`);
+        throw new SetupError("config_invalid", `Expected ${path} to contain a JSON object.`);
     }
     return parsed;
 }
@@ -662,7 +726,7 @@ async function readTextFileIfExists(path) {
         return await readFile(path, "utf-8");
     }
     catch (error) {
-        throw new Error(`Could not read ${path}: ${formatError(error)}`);
+        throw new SetupError("config_unreadable", `Could not read ${path}: ${formatError(error)}`);
     }
 }
 function upsertTomlTable(content, table, name = SUMMER_MCP_SERVER_NAME) {
@@ -716,7 +780,7 @@ function copyJsonObject(value) {
 }
 function mergeNamedObject(value, key, entry, label) {
     if (value !== undefined && !isJsonObject(value)) {
-        throw new Error(`Existing ${label} value must be a JSON object.`);
+        throw new SetupError("config_invalid", `Existing ${label} value must be a JSON object.`);
     }
     return {
         ...(isJsonObject(value) ? value : {}),

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

@@ -0,0 +1,44 @@
+import { type ConfigScope, type McpFormat, type PathContext, type SupportedAgent } from "./agent-table.js";
+import { type SetupStepError } from "./setup-error.js";
+import type { StdioMcpServerConfig } from "./agent-config.js";
+export interface DetectHit {
+    kind: "bin" | "app" | "folder" | "extension";
+    path: string;
+}
+export interface DetectedAgent {
+    id: SupportedAgent;
+    label: string;
+    /** legacy: the product was retired or renamed; setup still writes it, with a warning. */
+    status: "active" | "legacy";
+    installed: boolean;
+    /** A command, app or extension was found, not only a folder. A folder can outlive the
+     *  program, or be one an earlier Summer setup made for its skills or config. */
+    programFound: boolean;
+    /** Every place that showed the agent is installed (empty when not installed). */
+    detectedBy: DetectHit[];
+    /** The MCP config file `summer setup <id>` writes at user scope (project scope for agents with no user file). */
+    configPath: string;
+    configScope: ConfigScope;
+    configFormat: McpFormat;
+    configExists: boolean;
+    /** The config file lists a summer-engine MCP server, in any shape. */
+    mcpEntry: boolean;
+    /** The command the summer-engine entry runs, when it is a local (stdio) entry. */
+    mcpServer: StdioMcpServerConfig | null;
+    /** Setup also adds the Summer Games MCP for this agent. */
+    summerGames: boolean;
+    /** Setup also installs skills for this agent. */
+    skills: boolean;
+    /** Set when the config file exists but cannot be read. */
+    configError?: SetupStepError;
+}
+export interface DetectOptions {
+    ctx?: PathContext;
+    /** Folders searched for macOS app bundles; default /Applications and ~/Applications. */
+    macAppDirs?: string[];
+    /** Shared command folders outside home searched on macOS and Linux; default Homebrew's /opt/homebrew/bin and /usr/local/bin. */
+    systemBinDirs?: string[];
+}
+export declare function detectAgents(options?: DetectOptions): DetectedAgent[];
+/** PATH first, then the install folders a GUI-launched process's PATH leaves out. */
+export declare function searchedBinDirs(ctx: PathContext, systemBinDirs?: string[]): string[];