summer-engine 3.8.0 → 4.2.0

package/dist/cli/commands/setup.js

@@ -1,22 +1,47 @@
+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 { previewNote, setupSkills } from "../../installer/setup.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";
-import { resolveDefaultChannel } from "../../installer/version-check.js";
-import { agentLabel } from "../../installer/agent-table.js";
+import { listsSummerEngine, resolveDefaultChannel } from "../../installer/version-check.js";
+import { agentLabel, agentSpec, cliSetupRefusal, defaultPathContext } from "../../installer/agent-table.js";
+import { addAllowRules, allowRulesPath, removeAllowRules, supportsAllowRules } from "../../installer/cli-permissions.js";
+import { PROFILES, parseProfile } from "../../core/tool-profiles.js";
+import { findSetupProjectRoot, writeAgentInstructions } from "../../project-memory/agent-instructions.js";
+const PROFILE_NOTES = {
+    full: "Every Summer tool.",
+    engine: "Engine, generation and store tools. Every tool: summer setup <agent> --profile full",
+    assets: "Generation and asset tools, no engine tools. Every tool: summer setup <agent> --profile full",
+};
+/** The options that only shape the MCP entry, which --cli does not write. */
+const MCP_ENTRY_FLAGS = [
+    ["print", "--print"],
+    ["localDev", "--local-dev"],
+    ["channel", "--channel"],
+    ["profile", "--profile"],
+];
 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).")
+    .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.")
     .argument("[agent]", `Agent to configure: ${supportedAgents.join(", ")}`)
     .option("--agent <agent>", `Agent to configure: ${supportedAgents.join(", ")}`)
     .option("--scope <scope>", "Configuration scope: user or project", "user")
     .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("--channel <dist-tag>", "npm dist-tag the agent's MCP entry runs: npx -y summer-engine@<dist-tag> mcp (default latest; use next while a release soaks on the next tag). SUMMER_CHANNEL does the same.")
+    .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)")
+    .option("--profile <profile>", "MCP tool profile: full (every tool, the default), engine (engine, generation and the store; under 128 tools; the default for VS Code Copilot), assets (generation and the asset library, no engine tools)")
+    .option("--assets-only", "Set up for making assets without Summer Engine: the assets profile, only the asset skills, and no Summer Games")
+    .option("--cli", "CLI only: install the skills and no MCP server (and no Summer Games). The agent runs Summer as summer <area> <action> commands in its shell; the summer-cli skill teaches it")
+    .option("--no-mcp", "Same as --cli")
+    .option("--allow-rules", "With --cli, for Claude Code and Codex: let the agent run read-only summer commands, and dry runs of spends, without asking. Prints every rule; written only with --yes")
+    .option("--remove-allow-rules", "Remove the allow rules --allow-rules added (Claude Code, Codex), and nothing else")
+    .option("--no-project-files", "Inside a Summer project, do not add the Summer instructions to its AGENTS.md and CLAUDE.md (added with --yes by default)")
     .option("--json", "Print setup result as JSON")
     .option("--force", "Overwrite existing skill content (passes --force through to skills install)")
     .option("--recommended", "Install only the recommended skill subset instead of the whole library")
@@ -26,6 +51,18 @@ export const setupCommand = new Command("setup")
     .action(async (agentArg, opts) => {
     const agent = resolveAgentSelection(agentArg, opts.agent);
     const scope = resolveConfigScope(opts.scope);
+    if (opts.removeAllowRules) {
+        await removeCliAllowRules(agent, scope, opts);
+        return;
+    }
+    if (opts.cli || opts.mcp === false) {
+        await setupCliOnly(agent, scope, opts);
+        return;
+    }
+    // On stderr, so --json output stays one JSON document.
+    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({
         agent,
@@ -34,8 +71,9 @@ export const setupCommand = new Command("setup")
         print: opts.print,
         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.print
+    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) {
@@ -48,7 +86,9 @@ export const setupCommand = new Command("setup")
         scope,
         recommended: Boolean(opts.recommended),
         stableOnly: Boolean(opts.stableOnly),
+        assetsOnly: Boolean(opts.assetsOnly),
     });
+    const projectFiles = setupProjectInstructions(opts);
     const doctor = await runDoctor({ quiet: true });
     if (opts.json) {
         console.log(JSON.stringify({
@@ -56,17 +96,198 @@ export const setupCommand = new Command("setup")
             config,
             games,
             skills,
+            projectFiles,
             doctor,
         }, null, 2));
     }
     else {
-        printSetupResult(config, games, skills, doctor);
+        printSetupResult(config, games, skills, doctor, projectFiles);
     }
     if (!doctor.ok || skills.status === "failed") {
         process.exit(1);
     }
 });
-function printSetupResult(config, games, skills, doctor) {
+/**
+ * `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
+ * shell. Writes no agent config file; an existing summer-engine entry from an
+ * earlier setup is left as it is and named in a warning.
+ */
+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.`);
+    }
+    const refusal = cliSetupRefusal(spec);
+    if (refusal)
+        throw new Error(refusal);
+    const warnings = spec.status === "legacy" && spec.legacyNote ? [spec.legacyNote] : [];
+    const existing = await recordedMcpEntry(agent, scope);
+    if (existing) {
+        warnings.push(`${tildeify(existing)} still lists the summer-engine MCP server from an earlier setup. Remove that entry to use the CLI only.`);
+    }
+    const dryRun = Boolean(opts.dryRun);
+    const skills = setupSkills(agent, {
+        dryRun,
+        yes: Boolean(opts.yes),
+        force: Boolean(opts.force),
+        scope,
+        recommended: Boolean(opts.recommended),
+        stableOnly: Boolean(opts.stableOnly),
+        assetsOnly: Boolean(opts.assetsOnly),
+        commands: false,
+    });
+    // Read-only and dry-run summer commands run without asking, where the agent has clean allow rules.
+    // Opt-in: the flag is in the command the person approves.
+    let allowRules = null;
+    if (opts.allowRules && !supportsAllowRules(agent)) {
+        warnings.push(`--allow-rules is for Claude Code and Codex; ${agentLabel(agent)} manages command approvals in its own settings.`);
+    }
+    else if (opts.allowRules) {
+        try {
+            allowRules = await addAllowRules(agent, allowRulesPath(agent, scope, defaultPathContext()), Boolean(opts.yes) && !dryRun);
+            const shared = agent === "claude-code" && scope === "project" ? notGitIgnored(allowRules.path) : false;
+            if (shared)
+                warnings.push(`${tildeify(allowRules.path)} is not in .gitignore, so git would share these personal allow rules. Add .claude/settings.local.json to .gitignore.`);
+        }
+        catch (error) {
+            warnings.push(error instanceof Error ? error.message : String(error));
+        }
+    }
+    const projectFiles = setupProjectInstructions(opts);
+    const doctor = await runDoctor({ quiet: true });
+    const ok = doctor.ok && skills.status !== "failed";
+    if (opts.json) {
+        console.log(JSON.stringify({ ok, mcp: false, agent, scope, config: null, games: null, existingMcpEntry: existing, skills, allowRules, projectFiles, doctor, warnings }, null, 2));
+    }
+    else {
+        const label = agentLabel(agent);
+        console.log("");
+        console.log(brandLine(cliVersion));
+        console.log("");
+        console.log(`  ${dryRun ? c.dim("(dry run)") : sym.ok()}  ${c.bold(`CLI only for ${label}`)}: no MCP server`);
+        console.log(`     ${c.dim("The agent runs Summer in its shell: summer <area> <action>, or npx -y summer-engine@latest <area> <action>. The summer-cli skill teaches it.")}`);
+        printSkillsLine(skills, dryRun);
+        if (allowRules)
+            printAllowRules(allowRules, label, Boolean(opts.yes) && !dryRun);
+        else if (supportsAllowRules(agent) && !opts.allowRules) {
+            console.log(`  ${sym.arrow()}  ${c.dim(`${label} asks before each summer command. To run read-only and dry-run ones without asking: summer setup ${agent} --cli --allow-rules --yes (it prints every rule).`)}`);
+        }
+        printProjectFiles(projectFiles);
+        for (const warning of warnings)
+            console.log(`  ${sym.warn()}  ${c.yellow(warning)}`);
+        console.log("");
+        printDoctorResult(doctor);
+        if (ok && !dryRun)
+            printTryIt(label, Boolean(opts.assetsOnly));
+    }
+    if (!ok)
+        process.exit(1);
+}
+/** The allow rules, each on its line: what the agent now runs without asking, or would with --yes. */
+function printAllowRules(result, label, write) {
+    const where = c.dim(tildeify(result.path));
+    if (!write) {
+        console.log(`  ${sym.arrow()}  ${label} would run these summer commands without asking. Add them: run the same command with --yes.  ${where}`);
+    }
+    else if (result.changed.length === 0) {
+        console.log(`  ${sym.ok()}  ${label} already runs read-only and dry-run summer commands without asking  ${where}`);
+        return;
+    }
+    else {
+        console.log(`  ${sym.ok()}  ${label} runs these summer commands without asking (${result.changed.length} rules added)  ${where}`);
+    }
+    for (const rule of result.rules)
+        console.log(`     ${c.dim(rule)}`);
+    console.log(`     ${c.dim("Changes, publishing, prices, deletes and messages still ask. jobs wait and assets get save the files they name. Put --dry-run right after the action: summer assets generate-image --dry-run --prompt ... Undo: --remove-allow-rules")}`);
+}
+/** True when `path` sits in a git repository that does not ignore it (false outside git, or without git). */
+export function notGitIgnored(path, cwd = process.cwd()) {
+    const run = (args) => spawnSync("git", args, { cwd, stdio: "ignore" }).status;
+    if (run(["rev-parse", "--is-inside-work-tree"]) !== 0)
+        return false;
+    return run(["check-ignore", "-q", relative(cwd, path)]) === 1;
+}
+/** `summer setup <agent> --remove-allow-rules`: take out exactly the rules --allow-rules added. */
+async function removeCliAllowRules(agent, scope, opts) {
+    if (!supportsAllowRules(agent))
+        throw new Error(`--remove-allow-rules is for Claude Code and Codex; Summer adds no allow rules for ${agentLabel(agent)}.`);
+    const result = await removeAllowRules(agent, allowRulesPath(agent, scope, defaultPathContext()), !opts.dryRun);
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: true, agent, scope, allowRules: result }, null, 2));
+        return;
+    }
+    const where = c.dim(tildeify(result.path));
+    if (result.changed.length === 0)
+        console.log(`  ${sym.ok()}  No Summer allow rules for ${agentLabel(agent)}  ${where}`);
+    else
+        console.log(`  ${opts.dryRun ? c.dim("(dry run)") : sym.ok()}  ${opts.dryRun ? "Would remove" : "Removed"} ${result.changed.length} Summer allow rules for ${agentLabel(agent)}  ${where}`);
+}
+/**
+ * Inside a Summer project (findSetupProjectRoot: project.godot at or above the
+ * working directory, no higher than the git top level, never home): its
+ * AGENTS.md and CLAUDE.md, added when missing and never overwritten
+ * (project-memory/agent-instructions.ts). Like the skills, they are only
+ * planned without --yes. Null outside a project, with --no-project-files,
+ * --print, and --assets-only (the block is about building in Summer Engine).
+ */
+function setupProjectInstructions(opts) {
+    if (opts.projectFiles === false || opts.print || opts.assetsOnly)
+        return null;
+    const root = findSetupProjectRoot();
+    if (!root)
+        return null;
+    const dryRun = Boolean(opts.dryRun);
+    const written = Boolean(opts.yes) && !dryRun;
+    return { root, written, dryRun, files: writeAgentInstructions(root, { dryRun: !written }) };
+}
+function printProjectFiles(project) {
+    if (!project)
+        return;
+    const changed = project.files.filter((file) => file.action === "created" || file.action === "added" || file.action === "updated");
+    if (changed.length) {
+        const where = c.dim(changed.map((file) => tildeify(file.path)).join(", "));
+        if (project.written)
+            console.log(`  ${sym.ok()}  Added the Summer instructions for agents  ${where}`);
+        else if (project.dryRun)
+            console.log(`  ${c.dim("(dry run)")}  Would add the Summer instructions for agents  ${where}`);
+        else
+            console.log(`  ${sym.warn()}  Instructions for agents not added. Run the same setup command again with --yes to add them  ${where}`);
+    }
+    for (const file of project.files) {
+        if (!file.reason)
+            continue;
+        const what = file.action === "skipped" ? "not written" : "left as it is";
+        console.log(`  ${sym.warn()}  ${c.yellow(`${tildeify(file.path)} ${what}: ${file.reason}`)}`);
+    }
+}
+/** The config file that already lists summer-engine for this agent and scope, or null. */
+async function recordedMcpEntry(agent, scope) {
+    try {
+        const target = await configureAgentMcp({ agent, scope, print: true });
+        if (!existsSync(target.path))
+            return null;
+        return listsSummerEngine(readFileSync(target.path, "utf-8"), target.format) ? target.path : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** --assets-only means the assets profile; --profile must name a profile and agree with it. */
+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(", ")}.`);
+    }
+    if (opts.assetsOnly) {
+        if (profile && profile !== "assets")
+            throw new Error("--assets-only uses the assets profile; leave out --profile.");
+        return "assets";
+    }
+    return profile;
+}
+function printSetupResult(config, games, skills, doctor, projectFiles) {
     if (config.print) {
         console.log(config.snippet.trimEnd());
         return;
@@ -90,6 +311,9 @@ function printSetupResult(config, games, skills, doctor) {
     else if (config.channel !== "latest") {
         console.log(`  ${c.dim(`(channel ${config.channel})`)}  MCP server command: ${c.dim(`${config.server.command} ${config.server.args.join(" ")}`)}`);
     }
+    if (config.profile !== "full") {
+        console.log(`  ${c.dim(`(profile ${config.profile})`)}  ${c.dim(PROFILE_NOTES[config.profile])}`);
+    }
     if (games) {
         const name = c.bold("Summer Games");
         const url = c.dim(games.url);
@@ -105,6 +329,22 @@ function printSetupResult(config, games, skills, doctor) {
         if (!config.dryRun)
             console.log(`     ${c.dim(`Sign in once: ${games.signIn}`)}`);
     }
+    printSkillsLine(skills, config.dryRun);
+    printProjectFiles(projectFiles);
+    for (const warning of config.warnings) {
+        console.log(`  ${sym.warn()}  ${c.yellow(warning)}`);
+    }
+    console.log("");
+    printDoctorResult(doctor);
+    if (doctor.ok && skills.status !== "failed" && !config.dryRun)
+        printTryIt(label, config.profile === "assets");
+}
+function printTryIt(label, assets) {
+    console.log("");
+    const ask = assets ? "make a sword clash sound effect" : "add a DirectionalLight3D and Camera3D to my scene";
+    console.log(`${c.dim("Try it:")} open ${label} and ask: ${c.bold(`"${ask}"`)}`);
+}
+function printSkillsLine(skills, dryRun) {
     if (skills.status === "installed") {
         const installed = parseInstalledSkills(skills.stdout);
         if (installed.length > 0) {
@@ -114,21 +354,13 @@ function printSetupResult(config, games, skills, doctor) {
                 ? c.dim(` (${skills.installed.added} new, ${skills.installed.updated} updated${note ? `; ${note}` : ""})`)
                 : "";
             console.log(`  ${sym.ok()}  Installed ${c.bold(String(installed.length) + " skills")}${tally}  ${where ? c.dim(tildeify(where)) : ""}`);
-            const grouped = installed.reduce((rows, name, i) => {
-                const row = Math.floor(i / 3);
-                rows[row] = rows[row] ?? [];
-                rows[row].push(name);
-                return rows;
-            }, []);
-            for (const row of grouped) {
-                console.log(`     ${c.dim(row.join(" · "))}`);
-            }
+            console.log(`     ${c.dim(skillNamesSample(installed))}`);
         }
         else {
             console.log(`  ${sym.ok()}  ${skills.message}`);
         }
     }
-    else if (skills.status === "planned" && config.dryRun) {
+    else if (skills.status === "planned" && dryRun) {
         const note = previewNote(skills);
         console.log(`  ${c.dim("(dry run)")}  Would install ${c.bold(String(skills.count ?? "?") + " skills")}${note ? c.dim(` (${note})`) : ""}  ${c.dim(skills.destination ?? "")}`);
     }
@@ -140,15 +372,11 @@ function printSetupResult(config, games, skills, doctor) {
         if (skills.stderr)
             console.log(`     ${c.dim(skills.stderr)}`);
     }
-    for (const warning of config.warnings) {
-        console.log(`  ${sym.warn()}  ${c.yellow(warning)}`);
-    }
-    console.log("");
-    printDoctorResult(doctor);
-    if (doctor.ok && skills.status !== "failed" && !config.dryRun) {
-        console.log("");
-        console.log(`${c.dim("Try it:")} open ${label} and ask: ${c.bold("\"add a DirectionalLight3D and Camera3D to my scene\"")}`);
-    }
+}
+/** One line instead of a row per three skills: the first few names and how many more. `--json` keeps the full list. */
+export function skillNamesSample(names, max = 8) {
+    const shown = names.slice(0, max).join(" · ");
+    return names.length > max ? `${shown} · and ${names.length - max} more` : shown;
 }
 function parseInstalledSkills(stdout) {
     if (!stdout)

package/dist/cli/commands/skills.js

@@ -62,25 +62,26 @@ function previewIncludedLine(count) {
     return `  ${count} preview skill${count === 1 ? "" : "s"} included — labelled in ${count === 1 ? "its" : "each skill's"} guidance; add --stable-only to skip.`;
 }
 function selectSkills(name, opts) {
-    if (opts.all && opts.recommended) {
-        die("Use only one bulk option: --all or --recommended.");
+    if ([opts.all, opts.recommended, opts.assets].filter(Boolean).length > 1) {
+        die("Use only one bulk option: --all, --recommended or --assets.");
     }
-    if (name && (opts.all || opts.recommended)) {
+    if (name && (opts.all || opts.recommended || opts.assets)) {
         die("Specify either a skill name or a bulk option, not both.");
     }
     const skills = getBuiltinSkills();
-    if (opts.all || opts.recommended) {
+    if (opts.all || opts.recommended || opts.assets) {
         // Bulk installs take stable and preview skills (preview is a label, not a
         // gate); --stable-only skips preview. An explicit name below installs
         // regardless of status.
         const { selected, previewIncluded, previewSkipped } = selectSkillsForBulkInstall(skills, {
             recommended: Boolean(opts.recommended),
             stableOnly: Boolean(opts.stableOnly),
+            assetsOnly: Boolean(opts.assets),
         });
         return { skills: selected, previewIncluded, previewSkipped };
     }
     if (!name) {
-        console.error("Specify a skill name, --recommended, or --all.");
+        console.error("Specify a skill name, --recommended, --assets, or --all.");
         printAvailableSkillNames();
         process.exit(1);
     }
@@ -233,8 +234,13 @@ skillsCommand
     .command("list")
     .description("List available skills")
     .option("--by-domain", "Group skills by their primary domain (same grouping as library/skills/README.md)")
+    .option("--json", "Print the skills as JSON")
     .action((opts) => {
     const skills = getBuiltinSkills();
+    if (opts.json) {
+        console.log(JSON.stringify({ skills }));
+        return;
+    }
     if (skills.length === 0) {
         console.log("No skills found.");
         return;
@@ -276,7 +282,8 @@ skillsCommand
     .description("Install Summer skills for a target agent")
     .option("--all", "Install all available skills")
     .option("--recommended", "Install only the recommended skill subset (summer setup installs all by default)")
-    .option("--stable-only", "With --all / --recommended, skip preview skills (installed by default; labelled preview in their guidance)")
+    .option("--assets", "Install only the asset skills (sound, music, voice, images, 3D, animation, video) for agents that make assets without the engine")
+    .option("--stable-only", "With --all / --recommended / --assets, skip preview skills (installed by default; labelled preview in their guidance)")
     .option("--agent <agent>", `Target agent: ${AGENT_CLIENTS.join("|")}`)
     .option("--scope <scope>", "Install scope: user or project")
     // Legacy aliases: still accepted for old scripts, hidden from --help.
@@ -285,6 +292,7 @@ skillsCommand
     // 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())
     .option("--force", "Overwrite existing skill files (wipe stale skill dirs before copying)")
+    .option("--no-commands", "Claude Code: skip the slash commands (/summer, /gameskill, /start), which start work through the MCP tools")
     .action((name, opts) => {
     const agent = orDie(() => resolveSkillAgent(opts));
     const scope = orDie(() => resolveSkillScope(agent, opts));
@@ -342,13 +350,16 @@ skillsCommand
         console.log(previewSkippedLine(previewSkipped));
     // Claude Code: also install slash commands (`commands/*.md`)
     // into `~/.claude/commands/`. Other agents don't have an equivalent today.
-    if (agent === "claude-code") {
+    // The commands start and route game work in the engine through the MCP
+    // tools, so the asset skills (--assets, setup --assets-only) and a setup
+    // without MCP (--no-commands, setup --cli) leave them out.
+    if (agent === "claude-code" && !opts.assets && opts.commands !== false) {
         const commandResults = installClaudeCommands(scope, Boolean(opts.force));
         for (const r of commandResults) {
             console.log(`  ${r.action} command ${r.name} -> ${r.path}`);
         }
     }
-    writeMarkerForLocation(location);
+    writeMarkerForLocation(location, skills.map((skill) => skill.name));
     printInstallSummary(skills.length, agent, scope, location);
 });
 /**
@@ -386,12 +397,13 @@ function installClaudeCommands(scope, force) {
  * `skills-version-stale` check can detect drift later. Devin Desktop (formerly Windsurf) writes a
  * single rules file with no surrounding dir, so we skip it there.
  */
-function writeMarkerForLocation(location) {
+function writeMarkerForLocation(location, installed) {
     if (location.kind === "windsurf-rule-file")
         return;
     try {
         mkdirSync(location.path, { recursive: true });
-        writeSkillMarker(location.path, cliVersion);
+        // Skills the upgrade refresh left stay protected, unless this install just replaced them.
+        writeSkillMarker(location.path, cliVersion, new Date(), installed);
     }
     catch {
         // Marker is purely informational. If the FS rejects it (e.g. permission
@@ -401,7 +413,8 @@ function writeMarkerForLocation(location) {
 skillsCommand
     .command("info <name>")
     .description("Show skill description and preview")
-    .action((name) => {
+    .option("--json", "Print the skill and its full SKILL.md body as JSON")
+    .action((name, opts) => {
     const meta = getSkillMeta(name);
     if (!meta) {
         console.error(`Unknown skill: ${name}`);
@@ -412,6 +425,10 @@ skillsCommand
         die(`Skill files missing: ${name}`);
     const skillPath = join(src, "SKILL.md");
     const content = readFileSync(skillPath, "utf-8");
+    if (opts.json) {
+        console.log(JSON.stringify({ ...meta, file: skillPath, body: content.replace(/^---\s*\n[\s\S]*?\n---\s*\n/, "") }));
+        return;
+    }
     console.log(`\n${meta.name}`);
     console.log("-".repeat(40));
     console.log(meta.description);

package/dist/cli/commands/status.d.ts

@@ -1,3 +1,29 @@
 import { Command } from "commander";
 export declare const statusCommand: Command;
+/** What `summer status` reports; `--json` prints exactly this. */
+export interface StatusReport {
+    auth: {
+        signedIn: false;
+        loginUrl: string;
+    } | {
+        signedIn: true;
+        source: "env";
+    } | {
+        signedIn: true;
+        source: "stored";
+        email?: string;
+        identityError?: string;
+    };
+    engine: {
+        state: "not_running";
+    } | {
+        state: "not_responding";
+        port: number;
+    } | {
+        state: "running";
+        port: number;
+        version: string;
+    };
+}
+export declare function readStatus(): Promise<StatusReport>;
 export declare function runStatus(log: (message: string) => void): Promise<void>;

package/dist/cli/commands/status.js

@@ -4,52 +4,67 @@ import { resolveGatewayUrl } from "../../core/config.js";
 import { getApiToken, getApiPort, checkEngineHealth } from "../../core/engine.js";
 export const statusCommand = new Command("status")
     .description("Check Summer Engine status, connection, and auth state")
-    .action(async () => {
-    await runStatus(console.log);
+    .option("--json", "Print the status as JSON")
+    .action(async (opts) => {
+    if (opts.json)
+        console.log(JSON.stringify(await readStatus()));
+    else
+        await runStatus(console.log);
 });
+export async function readStatus() {
+    const authToken = await getAuthToken();
+    // The env credential is what every gateway call uses; a stored identity
+    // (if any) is not the one in effect, so it is not reported.
+    const auth = !authToken
+        ? { signedIn: false, loginUrl: await loginPageHint() }
+        : hasEnvAuthToken()
+            ? { signedIn: true, source: "env" }
+            : { signedIn: true, source: "stored", ...(await storedIdentity()) };
+    if (!(await getApiToken()))
+        return { auth, engine: { state: "not_running" } };
+    const port = await getApiPort();
+    const health = await checkEngineHealth(port);
+    // /api/health carries no project name/path/scene (see EngineHealth in
+    // core/engine.ts); summer_get_project_context is the read for those.
+    return { auth, engine: health ? { state: "running", port, version: health.version } : { state: "not_responding", port } };
+}
 export async function runStatus(log) {
+    const { auth, engine } = await readStatus();
     log("Summer Engine Status\n");
-    const authToken = await getAuthToken();
-    if (!authToken) {
+    if (!auth.signedIn) {
         log("  Auth: Not logged in");
         log("        Run: npx -y summer-engine@latest login");
-        log(`        Or: ${await loginPageHint()}`);
+        log(`        Or: ${auth.loginUrl}`);
     }
-    else if (hasEnvAuthToken()) {
-        // The env credential is what every gateway call uses; a stored identity
-        // (if any) is not the one in effect, so it is not printed.
+    else if (auth.source === "env") {
         log("  Auth: SUMMER_TOKEN (env) — logout does not affect it");
     }
     else {
-        log(`  Auth: Logged in${await storedIdentitySuffix()}`);
+        const identity = auth.identityError ? ` (identity unreadable: ${auth.identityError})` : auth.email ? ` as ${auth.email}` : "";
+        log(`  Auth: Logged in${identity}`);
     }
-    const apiToken = await getApiToken();
-    const port = await getApiPort();
-    if (!apiToken) {
+    if (engine.state === "not_running") {
         log("  Engine: Not running (no api-token found)");
         log("\n  To start: summer run");
         return;
     }
     log("  API Token: Found (~/.summer/api-token)");
-    log(`  Port: ${port}`);
-    const health = await checkEngineHealth(port);
-    if (!health) {
+    log(`  Port: ${engine.port}`);
+    if (engine.state === "not_responding") {
         log("  Engine: Not responding (may have closed since last launch)");
         log("\n  To start: summer run");
         return;
     }
-    // /api/health carries no project name/path/scene (see EngineHealth in
-    // core/engine.ts); summer_get_project_context is the read for those.
-    log(`  Engine: Running (v${health.version})`);
+    log(`  Engine: Running (v${engine.version})`);
 }
 /** A corrupt user.json must not take `summer status` down with it. */
-async function storedIdentitySuffix() {
+async function storedIdentity() {
     try {
         const userInfo = await getUserInfo();
-        return userInfo?.email ? ` as ${userInfo.email}` : "";
+        return userInfo?.email ? { email: userInfo.email } : {};
     }
     catch (error) {
-        return ` (identity unreadable: ${error instanceof Error ? error.message : String(error)})`;
+        return { identityError: error instanceof Error ? error.message : String(error) };
     }
 }
 async function loginPageHint() {

package/dist/cli/index.js

@@ -16,9 +16,11 @@ import { debugCommand } from "./commands/debug.js";
 import { configCommand } from "./commands/config.js";
 import { eventsCommand } from "./commands/events.js";
 import { toolCommand } from "./commands/tool.js";
+import { opsCliCommands } from "./commands/ops.js";
 import { getBanner } from "./banner.js";
 import { runRootAction } from "./root-action.js";
 import { c, sym } from "../core/format.js";
+import { resolveSurface } from "../core/tool-profiles.js";
 import { TOOLKIT_VERSION as version } from "../core/version.js";
 /**
  * Build and run the summer CLI. The `mcp` command is injected by the bin
@@ -51,6 +53,11 @@ export function runCli(mcpCommand) {
     program.addCommand(configCommand);
     program.addCommand(eventsCommand);
     program.addCommand(toolCommand);
+    // The 4.0 operation catalog (`summer <area> <action>`); SUMMER_SURFACE=v3 leaves it out.
+    if (resolveSurface(undefined) === "v4") {
+        for (const command of opsCliCommands())
+            program.addCommand(command);
+    }
     program.parseAsync().catch((err) => {
         console.error(err instanceof Error ? err.message : String(err));
         process.exit(1);