summer-engine 2.3.0 → 2.5.0

package/dist/bin/summer.js

@@ -10,6 +10,7 @@ import { openCommand } from "../commands/open.js";
 import { installCommand } from "../commands/install.js";
 import { createCommand } from "../commands/create.js";
 import { listCommand } from "../commands/list.js";
+import { memoryCommand } from "../commands/memory.js";
 import { skillsCommand } from "../commands/skills.js";
 import { orchestratorCommand } from "../commands/orchestrator.js";
 import { setupCommand } from "../commands/setup.js";
@@ -34,6 +35,7 @@ program.addCommand(runCommand);
 program.addCommand(openCommand);
 program.addCommand(createCommand);
 program.addCommand(listCommand);
+program.addCommand(memoryCommand);
 program.addCommand(skillsCommand);
 program.addCommand(mcpCommand);
 program.addCommand(setupCommand);
@@ -49,15 +51,21 @@ function printIntro(version) {
     console.log("");
     console.log(`     ${sym.arrow()} ${c.bold("Summer Engine")} ${c.dim("v" + version)}  ${c.dim("·")}  AI-native game engine`);
     console.log("");
-    console.log(`     ${c.bold("Get started")}`);
-    console.log(`     ${c.dim("$")} summer setup claude-code      ${c.dim("Configure Claude Code (or codex/cursor/windsurf)")}`);
-    console.log(`     ${c.dim("$")} summer create 3d-basic my-game ${c.dim("Start a project")}`);
-    console.log(`     ${c.dim("$")} summer doctor                  ${c.dim("Check setup")}`);
+    console.log(`     ${c.bold("Setup wizard")}`);
+    console.log(`     Open Claude Code, Cursor, Codex, Copilot, Windsurf, or another supported agent and paste:`);
+    console.log(`     ${c.brand("\"Install Summer Engine and let's make a game.\"")}`);
+    console.log("");
+    console.log(`     ${c.bold("Manual commands")}`);
+    console.log(`     ${c.dim("$")} npx -y summer-engine@latest setup claude-code --yes`);
+    console.log(`     ${c.dim("$")} npx -y summer-engine@latest create 3d-basic my-game`);
+    console.log(`     ${c.dim("$")} npx -y summer-engine@latest memory`);
+    console.log(`     ${c.dim("$")} npx -y summer-engine@latest doctor`);
     console.log("");
     console.log(`     ${c.bold("Slash commands")} ${c.dim("(in your AI agent)")}`);
     console.log(`     ${c.brand("/debug")}   ${c.dim("Triage and fix a bug end-to-end")}`);
     console.log(`     ${c.brand("/play")}    ${c.dim("Run the game and report state")}`);
     console.log("");
     console.log(`     ${c.dim("Docs:")} https://summerengine.com/docs`);
+    console.log(`     ${c.dim("Source:")} https://github.com/SummerEngine/summer`);
     console.log("");
 }

package/dist/commands/create.js

@@ -42,6 +42,7 @@ export const createCommand = new Command("create")
         console.log(`\nProject created at ${fullPath}`);
         console.log("\nNext steps:");
         console.log(`  summer run ${dirName}`);
+        console.log("  Ask your agent to run summer:brainstorm-game to create .summer/GameSoul.md");
         return;
     }
     // Fall back to remote template lookup
@@ -86,6 +87,7 @@ export const createCommand = new Command("create")
     console.log("Source: " + remote.url);
     console.log("\nNext steps:");
     console.log(`  summer run ${dirName}`);
+    console.log("  Ask your agent to run summer:brainstorm-game to create .summer/GameSoul.md");
 });
 function projectGodot(name, mainScene) {
     return `; Summer Engine Project

package/dist/commands/doctor.js

@@ -6,6 +6,8 @@ import { Command } from "commander";
 import { getAuthToken, getUserInfo } from "../lib/auth.js";
 import { checkEngineHealth, getApiPort, getApiToken } from "../lib/engine.js";
 import { brandLine, c, pad, sym, tildeify } from "../lib/format.js";
+import { getProjectMemorySummary } from "../lib/project-memory.js";
+import { buildCliVersionCheck, buildSkillsVersionCheck, defaultSkillMarkerCandidates, fetchLatestRegistryVersion, } from "../lib/version-check.js";
 const require = createRequire(import.meta.url);
 const { version } = require("../../package.json");
 const MAC_ENGINE_PATHS = [
@@ -18,7 +20,7 @@ const WIN_ENGINE_PATHS = [
     `${process.env.PROGRAMFILES}\\Summer Engine\\Summer.exe`,
 ];
 export const doctorCommand = new Command("doctor")
-    .description("Diagnose Node, login, engine, local API, and MCP boot")
+    .description("Diagnose Node, login, engine, project memory, local API, and MCP boot")
     .option("--json", "Print diagnostics as JSON")
     .action(async (opts) => {
     if (!opts.json) {
@@ -42,9 +44,12 @@ export async function runDoctor(options = {}) {
         status: "ok",
         message: `v${version}`,
     });
+    checks.push(await checkCliVersionCurrent());
+    checks.push(checkSkillsVersion());
     checks.push(await checkLogin());
     checks.push(checkEngineInstall());
     checks.push(await checkLocalApi());
+    checks.push(await checkProjectMemory());
     checks.push(await checkMcpBoot());
     const result = summarizeChecks(checks);
     if (!options.quiet) {
@@ -74,6 +79,33 @@ function checkNodeVersion() {
         message: `${process.version} (need 18+)`,
     };
 }
+async function checkCliVersionCurrent() {
+    const registry = await fetchLatestRegistryVersion();
+    const result = buildCliVersionCheck({
+        installedVersion: version,
+        registry,
+    });
+    return {
+        id: "cli-version-current",
+        label: "CLI up to date",
+        status: result.status,
+        message: result.message,
+        details: result.details,
+    };
+}
+function checkSkillsVersion() {
+    const result = buildSkillsVersionCheck({
+        installedCliVersion: version,
+        candidates: defaultSkillMarkerCandidates(),
+    });
+    return {
+        id: "skills-version-stale",
+        label: "Skills up to date",
+        status: result.status,
+        message: result.message,
+        details: result.details,
+    };
+}
 async function checkLogin() {
     const token = await getAuthToken();
     const user = await getUserInfo();
@@ -147,6 +179,44 @@ async function checkLocalApi() {
         },
     };
 }
+async function checkProjectMemory() {
+    const port = await getApiPort();
+    const health = await checkEngineHealth(port);
+    if (!health?.project_path) {
+        return {
+            id: "project-memory",
+            label: "Project Memory",
+            status: "ok",
+            message: "no project open",
+        };
+    }
+    const summary = getProjectMemorySummary(health.project_path);
+    if (!summary.present) {
+        return {
+            id: "project-memory",
+            label: "Project Memory",
+            status: "warning",
+            message: ".summer not created yet",
+            details: {
+                projectPath: health.project_path,
+                reason: summary.reason,
+                recommendedAction: "Ask your agent to run summer:brainstorm-game.",
+            },
+        };
+    }
+    return {
+        id: "project-memory",
+        label: "Project Memory",
+        status: "ok",
+        message: `${summary.files.length} files, ${summary.structured.fileCount} memory, ${summary.structured.lockedCount} locked`,
+        details: {
+            projectPath: health.project_path,
+            files: summary.files.length,
+            memoryFiles: summary.structured.fileCount,
+            locked: summary.structured.lockedCount,
+        },
+    };
+}
 async function checkMcpBoot() {
     const cliPath = process.argv[1];
     if (!cliPath) {

package/dist/commands/install.d.ts

@@ -1,2 +1,19 @@
 import { Command } from "commander";
+/** Guard a download URL from the releases endpoint. A missing/empty URL (an
+ *  outdated or misconfigured endpoint) otherwise becomes a cryptic
+ *  fetch(undefined) failure — surface it clearly with a manual fallback. */
+export declare function requireDownloadUrl(value: string | undefined, label: string): string;
+/** Verify a downloaded file's sha256 against the expected hash from the releases
+ *  endpoint. Skipped when no expected hash is published. Catches a truncated or
+ *  corrupted download (a ~1GB install over a flaky network) before it becomes a
+ *  confusing DMG-mount / installer failure downstream. */
+export declare function verifyChecksum(actual: string, expected: string | undefined, label: string): void;
+/** Velopack Setup.exe install args. Velopack is NOT NSIS: silent install is
+ *  `--silent` and a custom directory is `--installto <dir>` (per Velopack's
+ *  setup.exe CLI). The old NSIS flags (/S, /D=) are rejected by the Velopack
+ *  installer with "unexpected argument '/S' found" — this is the wizard bug. */
+export declare function windowsInstallerArgs(customPath?: string): string;
 export declare const installCommand: Command;
+export declare function downloadFile(url: string, dest: string): Promise<{
+    sha256: string;
+}>;

package/dist/commands/install.js

@@ -1,11 +1,41 @@
 import { Command } from "commander";
 import { execSync } from "child_process";
+import { createHash } from "crypto";
 import { createWriteStream, existsSync, mkdirSync } from "fs";
 import { pipeline } from "stream/promises";
 import { Readable } from "stream";
 import { tmpdir, platform } from "os";
 import { join } from "path";
 const RELEASES_URL = "https://www.summerengine.com/api/desktop/releases";
+/** Guard a download URL from the releases endpoint. A missing/empty URL (an
+ *  outdated or misconfigured endpoint) otherwise becomes a cryptic
+ *  fetch(undefined) failure — surface it clearly with a manual fallback. */
+export function requireDownloadUrl(value, label) {
+    if (!value || value.trim().length === 0) {
+        throw new Error(`Release info is missing the ${label} download URL — the releases endpoint may be ` +
+            `outdated. Download manually from https://summerengine.com/download`);
+    }
+    return value;
+}
+/** Verify a downloaded file's sha256 against the expected hash from the releases
+ *  endpoint. Skipped when no expected hash is published. Catches a truncated or
+ *  corrupted download (a ~1GB install over a flaky network) before it becomes a
+ *  confusing DMG-mount / installer failure downstream. */
+export function verifyChecksum(actual, expected, label) {
+    if (!expected || expected.trim().length === 0)
+        return; // nothing published to verify against
+    if (actual.toLowerCase() !== expected.toLowerCase()) {
+        throw new Error(`${label} checksum mismatch — the download was corrupted or incomplete ` +
+            `(expected ${expected.slice(0, 12)}…, got ${actual.slice(0, 12)}…). Re-run \`summer install\`.`);
+    }
+}
+/** Velopack Setup.exe install args. Velopack is NOT NSIS: silent install is
+ *  `--silent` and a custom directory is `--installto <dir>` (per Velopack's
+ *  setup.exe CLI). The old NSIS flags (/S, /D=) are rejected by the Velopack
+ *  installer with "unexpected argument '/S' found" — this is the wizard bug. */
+export function windowsInstallerArgs(customPath) {
+    return customPath ? `--silent --installto "${customPath}"` : "--silent";
+}
 export const installCommand = new Command("install")
     .description("Download and install Summer Engine")
     .option("--path <dir>", "Custom install directory")
@@ -42,6 +72,7 @@ async function installMac(releases, customPath) {
         console.error("No macOS release found.");
         process.exit(1);
     }
+    const dmgUrl = requireDownloadUrl(info.dmg_url, "macOS DMG");
     console.log(`Latest version: ${info.version}`);
     const destApp = customPath || "/Applications/Summer.app";
     if (existsSync(destApp)) {
@@ -50,7 +81,18 @@ async function installMac(releases, customPath) {
     }
     const dmgPath = join(tmpdir(), `Summer-v${info.version}.dmg`);
     console.log(`Downloading Summer Engine v${info.version} (~1 GB, includes bundled Git + runtime)...`);
-    await downloadFile(info.dmg_url, dmgPath);
+    try {
+        const { sha256 } = await downloadFile(dmgUrl, dmgPath);
+        verifyChecksum(sha256, info.dmg_sha256, "DMG");
+    }
+    catch (err) {
+        try {
+            execSync(`rm -f "${dmgPath}"`, { stdio: "ignore" });
+        }
+        catch { /* best effort */ }
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
     console.log("Mounting DMG...");
     const mountOutput = execSync(`hdiutil attach "${dmgPath}" -nobrowse -noverify -noautoopen`, {
         encoding: "utf-8",
@@ -88,13 +130,25 @@ async function installWindows(releases, customPath) {
         console.error("No Windows release found.");
         process.exit(1);
     }
+    const exeUrl = requireDownloadUrl(info.url, "Windows installer");
     console.log(`Latest version: ${info.version}`);
     const exePath = join(tmpdir(), `Summer-v${info.version}.exe`);
     console.log(`Downloading Summer Engine v${info.version} (~1 GB, includes bundled Git + runtime)...`);
-    await downloadFile(info.url, exePath);
+    try {
+        const { sha256 } = await downloadFile(exeUrl, exePath);
+        verifyChecksum(sha256, info.sha256, "installer");
+    }
+    catch (err) {
+        try {
+            execSync(`del "${exePath}"`, { stdio: "ignore" });
+        }
+        catch { /* best effort */ }
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
     console.log("Running installer...");
     try {
-        execSync(`"${exePath}" /S${customPath ? ` /D=${customPath}` : ""}`, {
+        execSync(`"${exePath}" ${windowsInstallerArgs(customPath)}`, {
             stdio: "inherit",
         });
     }
@@ -111,7 +165,7 @@ async function installWindows(releases, customPath) {
     console.log("  summer login    # Sign in to your account");
     console.log("  summer run      # Launch the engine");
 }
-async function downloadFile(url, dest) {
+export async function downloadFile(url, dest) {
     const res = await fetch(url);
     if (!res.ok || !res.body) {
         throw new Error(`Download failed: HTTP ${res.status}`);
@@ -121,9 +175,13 @@ async function downloadFile(url, dest) {
         mkdirSync(dir, { recursive: true });
     const fileStream = createWriteStream(dest);
     const readable = Readable.fromWeb(res.body);
+    // Hash while streaming (the 'data' listener and the pipe both see every chunk
+    // in flowing mode), so we get integrity for free without a second read pass.
+    const hash = createHash("sha256");
     let downloaded = 0;
     const total = parseInt(res.headers.get("content-length") || "0", 10);
     readable.on("data", (chunk) => {
+        hash.update(chunk);
         downloaded += chunk.length;
         if (total > 0) {
             const pct = Math.round((downloaded / total) * 100);
@@ -132,4 +190,5 @@ async function downloadFile(url, dest) {
     });
     await pipeline(readable, fileStream);
     process.stdout.write("\n");
+    return { sha256: hash.digest("hex") };
 }

package/dist/commands/memory.d.ts

@@ -0,0 +1,14 @@
+import { Command } from "commander";
+import { type ProjectMemorySummary } from "../lib/project-memory.js";
+interface ResolvedMemoryProject {
+    projectPath: string | null;
+    source: "option" | "engine" | "cwd" | "none";
+    reason?: string;
+}
+export declare const memoryCommand: Command;
+export declare function resolveMemoryProject(projectOption?: string): Promise<ResolvedMemoryProject>;
+export declare function findProjectRoot(startDir: string): string | null;
+export declare function resolveMemoryFilePath(projectPath: string, requested: string): string;
+export declare function formatMemorySummary(projectPath: string, summary: ProjectMemorySummary): string;
+export declare function formatStatusMemoryLine(summary: ProjectMemorySummary): string;
+export {};

package/dist/commands/memory.js

@@ -0,0 +1,196 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { Command } from "commander";
+import { checkEngineHealth, getApiPort } from "../lib/engine.js";
+import { getProjectMemorySummary, } from "../lib/project-memory.js";
+import { c, pad, tildeify } from "../lib/format.js";
+export const memoryCommand = new Command("memory")
+    .description("Inspect project memory in .summer")
+    .option("--project <path>", "Project directory to inspect")
+    .option("--json", "Print memory summary as JSON")
+    .action(async (opts) => {
+    const resolvedProject = await resolveMemoryProject(opts.project);
+    if (!resolvedProject.projectPath) {
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: false, ...resolvedProject }, null, 2));
+        }
+        else {
+            console.error(resolvedProject.reason ?? "Could not find a Summer project.");
+            console.error("Run from a project directory, pass --project <path>, or start Summer Engine.");
+        }
+        process.exit(1);
+    }
+    const summary = getProjectMemorySummary(resolvedProject.projectPath);
+    if (opts.json) {
+        console.log(JSON.stringify({
+            ok: true,
+            projectPath: resolvedProject.projectPath,
+            source: resolvedProject.source,
+            memory: summary,
+        }, null, 2));
+        return;
+    }
+    console.log(formatMemorySummary(resolvedProject.projectPath, summary));
+});
+memoryCommand
+    .command("show <file>")
+    .description("Print a .summer memory Markdown file")
+    .option("--project <path>", "Project directory to inspect")
+    .action(async (file, opts) => {
+    const resolvedProject = await resolveMemoryProject(opts.project);
+    if (!resolvedProject.projectPath) {
+        console.error(resolvedProject.reason ?? "Could not find a Summer project.");
+        console.error("Run from a project directory, pass --project <path>, or start Summer Engine.");
+        process.exit(1);
+    }
+    const filePath = resolveMemoryFilePath(resolvedProject.projectPath, file);
+    console.log(readFileSync(filePath, "utf-8"));
+});
+memoryCommand
+    .command("path")
+    .description("Print the .summer directory path for the current project")
+    .option("--project <path>", "Project directory to inspect")
+    .action(async (opts) => {
+    const resolvedProject = await resolveMemoryProject(opts.project);
+    if (!resolvedProject.projectPath) {
+        console.error(resolvedProject.reason ?? "Could not find a Summer project.");
+        console.error("Run from a project directory, pass --project <path>, or start Summer Engine.");
+        process.exit(1);
+    }
+    console.log(join(resolvedProject.projectPath, ".summer"));
+});
+export async function resolveMemoryProject(projectOption) {
+    if (projectOption) {
+        const projectPath = resolve(projectOption);
+        if (!existsSync(projectPath)) {
+            return {
+                projectPath: null,
+                source: "option",
+                reason: `Project directory not found: ${projectPath}`,
+            };
+        }
+        if (!existsSync(join(projectPath, "project.godot"))) {
+            return {
+                projectPath: null,
+                source: "option",
+                reason: `No project.godot found in ${projectPath}.`,
+            };
+        }
+        return { projectPath, source: "option" };
+    }
+    const cwdProject = findProjectRoot(process.cwd());
+    if (cwdProject)
+        return { projectPath: cwdProject, source: "cwd" };
+    const port = await getApiPort();
+    const health = await checkEngineHealth(port);
+    if (health?.project_path && existsSync(join(health.project_path, "project.godot"))) {
+        return { projectPath: health.project_path, source: "engine" };
+    }
+    return {
+        projectPath: null,
+        source: "none",
+        reason: "No Summer project found from engine state or current directory.",
+    };
+}
+export function findProjectRoot(startDir) {
+    let current = resolve(startDir);
+    while (true) {
+        if (existsSync(join(current, "project.godot")))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+export function resolveMemoryFilePath(projectPath, requested) {
+    const summerDir = resolve(projectPath, ".summer");
+    const rawPath = requested.startsWith(".summer/")
+        ? resolve(projectPath, requested)
+        : resolve(summerDir, requested);
+    const withinSummer = isPathInside(summerDir, rawPath);
+    if (!withinSummer) {
+        throw new Error("Memory files must be inside the project's .summer directory.");
+    }
+    if (!existsSync(rawPath)) {
+        throw new Error(`Memory file not found: ${requested}`);
+    }
+    if (!statSync(rawPath).isFile()) {
+        throw new Error(`Memory path is not a file: ${requested}`);
+    }
+    return rawPath;
+}
+export function formatMemorySummary(projectPath, summary) {
+    const lines = [];
+    lines.push(c.bold("Project Memory"));
+    lines.push("");
+    lines.push(`  Project: ${tildeify(projectPath)}`);
+    lines.push(`  Folder:  ${tildeify(join(projectPath, ".summer"))}`);
+    lines.push("");
+    if (!summary.present) {
+        lines.push(`  ${summary.reason ?? "No .summer memory found yet."}`);
+        lines.push("");
+        lines.push("  Agents create this through Summer skills.");
+        lines.push("  Start with .summer/GameSoul.md for the project brief.");
+        lines.push("  Use .summer/memory/ for locked facts like voice IDs and world canon.");
+        return lines.join("\n");
+    }
+    const totalFiles = summary.files.length;
+    const structured = summary.structured;
+    lines.push(`  Status:  ${totalFiles} .summer Markdown file${totalFiles === 1 ? "" : "s"}, ` +
+        `${structured.fileCount} structured memory file${structured.fileCount === 1 ? "" : "s"}, ` +
+        `${structured.lockedCount} locked`);
+    lines.push("");
+    const canonicalRows = canonicalRowsFromSummary(summary);
+    if (canonicalRows.length > 0) {
+        lines.push(c.bold("Canonical"));
+        for (const [label, file] of canonicalRows) {
+            lines.push(formatMemoryFileLine(label, file));
+        }
+        lines.push("");
+    }
+    if (structured.files.length > 0) {
+        lines.push(c.bold("Structured"));
+        for (const file of structured.files) {
+            lines.push(formatMemoryFileLine(file.kind, file));
+        }
+        if (structured.truncated) {
+            lines.push("  ...more files omitted from summary");
+        }
+        lines.push("");
+    }
+    lines.push("Read a file:");
+    lines.push("  summer memory show .summer/memory/casting/voices.md");
+    lines.push("");
+    lines.push("Rule:");
+    lines.push("  Markdown is canonical. Changing priority: locked memory requires explicit user confirmation.");
+    return lines.join("\n");
+}
+export function formatStatusMemoryLine(summary) {
+    if (!summary.present)
+        return "Memory: No .summer folder yet";
+    const fileCount = summary.files.length;
+    const structuredCount = summary.structured.fileCount;
+    const lockedCount = summary.structured.lockedCount;
+    return `Memory: ${fileCount} .summer file${fileCount === 1 ? "" : "s"}, ${structuredCount} memory file${structuredCount === 1 ? "" : "s"}, ${lockedCount} locked`;
+}
+function canonicalRowsFromSummary(summary) {
+    const rows = [
+        ["brief", summary.canonical.gameSoul],
+        ["art", summary.canonical.artBible],
+        ["audio", summary.canonical.audioBible],
+        ["build", summary.canonical.buildPlan],
+        ["legacy-casting", summary.canonical.legacyVoiceCast],
+    ];
+    return rows.filter((row) => row[1] !== null);
+}
+function formatMemoryFileLine(label, file) {
+    const lock = file.locked ? "locked" : "";
+    const title = file.title ? ` - ${file.title}` : "";
+    return `  ${pad(label, 15)} ${pad(file.path, 42)} ${lock}${title}`;
+}
+function isPathInside(parent, child) {
+    const relativePath = relative(parent, child);
+    return (relativePath === "" ||
+        (!relativePath.startsWith("..") && !isAbsolute(relativePath)));
+}

package/dist/commands/setup.js

@@ -14,6 +14,8 @@ const AGENT_LABEL = {
     cline: "Cline",
     "roo-code": "Roo Code",
     gemini: "Gemini CLI",
+    "github-copilot": "GitHub Copilot CLI",
+    "vscode-copilot": "GitHub Copilot in VS Code",
     opencode: "OpenCode",
 };
 export const setupCommand = new Command("setup")
@@ -25,6 +27,7 @@ export const setupCommand = new Command("setup")
     .option("--print", "Print the MCP config snippet instead of writing files")
     .option("--yes", "Apply practical setup steps without prompting")
     .option("--json", "Print setup result as JSON")
+    .option("--force", "Overwrite existing skill content (passes --force through to skills install)")
     .action(async (agentArg, opts) => {
     const agent = resolveAgent(agentArg, opts.agent);
     const scope = resolveScope(opts.scope);
@@ -37,6 +40,7 @@ export const setupCommand = new Command("setup")
     const skills = setupRecommendedSkills(agent, {
         dryRun: Boolean(opts.dryRun || opts.print),
         yes: Boolean(opts.yes),
+        force: Boolean(opts.force),
     });
     const doctor = await runDoctor({ quiet: true });
     if (opts.json) {
@@ -72,7 +76,7 @@ function resolveScope(scopeOpt) {
     return parsed;
 }
 function setupRecommendedSkills(agent, options) {
-    const invocation = skillInstallInvocation(agent);
+    const invocation = skillInstallInvocation(agent, { force: options.force });
     if (!invocation) {
         return {
             status: "skipped",
@@ -107,13 +111,15 @@ function setupRecommendedSkills(agent, options) {
         stderr: result.stderr.trim(),
     };
 }
-function skillInstallInvocation(agent) {
+function skillInstallInvocation(agent, opts = { force: false }) {
     const cliPath = process.argv[1];
     if (!cliPath)
         return null;
     const command = cliPath.endsWith(".js") ? process.execPath : cliPath;
     const prefix = cliPath.endsWith(".js") ? [cliPath] : [];
     const baseArgs = ["skills", "install", "--recommended", "--agent", agent];
+    if (opts.force)
+        baseArgs.push("--force");
     return {
         command,
         args: [...prefix, ...baseArgs],