summer-engine 1.3.0 → 1.3.1

package/README.md

@@ -32,9 +32,14 @@ Verify:
 summer doctor
 ```
 
-Then open your agent and try the verification prompt:
+Then open your agent and try one of the slash commands:
 
-> Use Summer Engine MCP. First call `summer_get_project_context` and `summer_get_agent_playbook`, then add a `DirectionalLight3D` and `Camera3D` to the main scene, save it, and check diagnostics.
+| Command | What it does |
+|---|---|
+| `/debug` | Triage and fix a bug end-to-end (reads engine errors, locates code, proposes fix) |
+| `/play` | Run the game and report state (clean run, warnings, or crash) |
+
+Or just describe what you want — the specialist skills (FPS controller, lighting, GDScript patterns, scene composition, UI, asset strategy) auto-trigger on natural language: "make me an FPS", "add lighting", "I need a HUD".
 
 ## Commands
 

package/dist/bin/summer.js

@@ -14,13 +14,18 @@ import { skillsCommand } from "../commands/skills.js";
 import { orchestratorCommand } from "../commands/orchestrator.js";
 import { setupCommand } from "../commands/setup.js";
 import { doctorCommand } from "../commands/doctor.js";
+import { getBanner } from "../lib/banner.js";
+import { c, sym } from "../lib/format.js";
 const require = createRequire(import.meta.url);
 const { version } = require("../../package.json");
 const program = new Command();
 program
     .name("summer")
     .description("CLI and MCP tools for Summer Engine — the AI-native game engine")
-    .version(version);
+    .version(version)
+    .action(() => {
+    printIntro(version);
+});
 program.addCommand(installCommand);
 program.addCommand(loginCommand);
 program.addCommand(logoutCommand);
@@ -38,3 +43,21 @@ program.parseAsync().catch((err) => {
     console.error(err instanceof Error ? err.message : String(err));
     process.exit(1);
 });
+function printIntro(version) {
+    console.log("");
+    console.log(getBanner());
+    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("");
+    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("");
+}

package/dist/commands/doctor.js

@@ -5,6 +5,7 @@ import { platform } from "os";
 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";
 const require = createRequire(import.meta.url);
 const { version } = require("../../package.json");
 const MAC_ENGINE_PATHS = [
@@ -17,11 +18,17 @@ const WIN_ENGINE_PATHS = [
     `${process.env.PROGRAMFILES}\\Summer Engine\\Summer.exe`,
 ];
 export const doctorCommand = new Command("doctor")
-    .description("Run setup and connection diagnostics")
+    .description("Diagnose Node, login, engine, local API, and MCP boot")
     .option("--json", "Print diagnostics as JSON")
-    .option("--human", "Print diagnostics in a human-readable format")
     .action(async (opts) => {
-    const result = await runDoctor({ json: opts.json || !opts.human });
+    if (!opts.json) {
+        const { createRequire: req } = await import("node:module");
+        const ver = req(import.meta.url)("../../package.json").version;
+        console.log("");
+        console.log(brandLine(ver));
+        console.log("");
+    }
+    const result = await runDoctor({ json: Boolean(opts.json) });
     if (!result.ok) {
         process.exit(1);
     }
@@ -33,7 +40,7 @@ export async function runDoctor(options = {}) {
         id: "cli-version",
         label: "Summer CLI",
         status: "ok",
-        message: `summer-engine CLI v${version}`,
+        message: `v${version}`,
     });
     checks.push(await checkLogin());
     checks.push(checkEngineInstall());
@@ -57,14 +64,14 @@ function checkNodeVersion() {
             id: "node-version",
             label: "Node.js",
             status: "ok",
-            message: `Node ${process.version}`,
+            message: process.version,
         };
     }
     return {
         id: "node-version",
         label: "Node.js",
         status: "fail",
-        message: `Node ${process.version} found; Summer CLI requires Node 18 or newer.`,
+        message: `${process.version} (need 18+)`,
     };
 }
 async function checkLogin() {
@@ -75,32 +82,34 @@ async function checkLogin() {
             id: "login",
             label: "Login",
             status: "warning",
-            message: "Not logged in. Run: summer login",
+            message: "not signed in (run: summer login)",
         };
     }
     return {
         id: "login",
         label: "Login",
         status: "ok",
-        message: user ? `Logged in as ${user.email}` : "Auth token found.",
+        message: user ? user.email : "signed in",
     };
 }
 function checkEngineInstall() {
     const binary = findEngineBinary();
     if (binary) {
+        // Shorten /Applications/Summer.app/Contents/MacOS/Summer -> /Applications/Summer.app
+        const display = binary.replace(/\/Contents\/MacOS\/Summer$/, "");
         return {
             id: "engine-install",
-            label: "Engine Install",
+            label: "Engine",
             status: "ok",
-            message: `Summer Engine binary found at ${binary}`,
+            message: tildeify(display),
             details: { path: binary },
         };
     }
     return {
         id: "engine-install",
-        label: "Engine Install",
+        label: "Engine",
         status: "warning",
-        message: "Summer Engine binary was not found in the default install locations.",
+        message: "not installed (run: summer install)",
     };
 }
 async function checkLocalApi() {
@@ -111,7 +120,7 @@ async function checkLocalApi() {
             id: "local-api",
             label: "Local API",
             status: "warning",
-            message: "Engine API token not found; Summer Engine is probably not running.",
+            message: "engine not running",
             details: { port },
         };
     }
@@ -121,7 +130,7 @@ async function checkLocalApi() {
             id: "local-api",
             label: "Local API",
             status: "warning",
-            message: `API token found, but Summer Engine is not responding on port ${port}.`,
+            message: `not responding on :${port}`,
             details: { port },
         };
     }
@@ -129,7 +138,7 @@ async function checkLocalApi() {
         id: "local-api",
         label: "Local API",
         status: "ok",
-        message: `Summer Engine API is responding on port ${port}.`,
+        message: `:${port}`,
         details: {
             port,
             version: health.version,
@@ -182,7 +191,7 @@ async function checkMcpBoot() {
                     id: "mcp-boot",
                     label: "MCP Server",
                     status: "ok",
-                    message: "MCP stdio server starts successfully.",
+                    message: "ready",
                 });
             }
         });
@@ -225,12 +234,27 @@ function summarizeChecks(checks) {
     };
 }
 export function printDoctorResult(result) {
-    console.log("Summer Doctor\n");
+    console.log(c.bold("Doctor"));
+    console.log("");
+    const labelWidth = 14;
     for (const check of result.checks) {
-        const mark = check.status === "ok" ? "OK" : check.status === "warning" ? "WARN" : "FAIL";
-        console.log(`  ${mark.padEnd(4)} ${check.label}: ${check.message}`);
+        const mark = check.status === "ok"
+            ? sym.ok()
+            : check.status === "warning"
+                ? sym.warn()
+                : sym.fail();
+        console.log(`  ${mark}  ${pad(c.bold(check.label), labelWidth)}${c.dim(check.message)}`);
+    }
+    console.log("");
+    if (result.summary.failures > 0) {
+        console.log(c.red(`${result.summary.failures} ${result.summary.failures === 1 ? "issue" : "issues"} to fix.`));
+    }
+    else if (result.summary.warnings > 0) {
+        console.log(c.yellow(`${result.summary.warnings} ${result.summary.warnings === 1 ? "warning" : "warnings"}, ${result.summary.ok} OK.`));
+    }
+    else {
+        console.log(c.green("Everything's wired up."));
     }
-    console.log(`\n${result.summary.ok} ok, ${result.summary.warnings} warnings, ${result.summary.failures} failures`);
 }
 function findEngineBinary() {
     const paths = platform() === "darwin" ? MAC_ENGINE_PATHS : WIN_ENGINE_PATHS;

package/dist/commands/setup.js

@@ -1,7 +1,17 @@
 import { spawnSync } from "child_process";
+import { createRequire } from "node:module";
 import { Command } from "commander";
 import { configureAgentMcp, parseAgent, parseScope, supportedAgents, } from "../lib/agent-config.js";
 import { printDoctorResult, runDoctor } from "./doctor.js";
+import { brandLine, c, sym, tildeify } from "../lib/format.js";
+const requireFromHere = createRequire(import.meta.url);
+const { version: cliVersion } = requireFromHere("../../package.json");
+const AGENT_LABEL = {
+    "claude-code": "Claude Code",
+    codex: "Codex",
+    cursor: "Cursor",
+    windsurf: "Windsurf",
+};
 export const setupCommand = new Command("setup")
     .description("Configure Summer Engine for an AI agent and run diagnostics")
     .argument("[agent]", `Agent to configure: ${supportedAgents.join(", ")}`)
@@ -109,20 +119,81 @@ function skillInstallInvocation(agent) {
 function printSetupResult(config, skills, doctor) {
     if (config.print) {
         console.log(config.snippet.trimEnd());
+        return;
     }
-    else if (config.dryRun) {
-        console.log(`Would update ${config.path} for ${config.agent} (${config.scope}).`);
+    console.log("");
+    console.log(brandLine(cliVersion));
+    console.log("");
+    const agentLabel = AGENT_LABEL[config.agent] ?? config.agent;
+    if (config.dryRun) {
+        console.log(`  ${c.dim("(dry run)")}  Would link to ${agentLabel}  ${c.dim(tildeify(config.path))}`);
     }
     else if (config.wrote) {
-        console.log(`Configured Summer Engine MCP for ${config.agent} (${config.scope}) at ${config.path}.`);
+        console.log(`  ${sym.ok()}  Linked to ${c.bold(agentLabel)}  ${c.dim(tildeify(config.path))}`);
     }
     else {
-        console.log(`Summer Engine MCP already configured for ${config.agent} (${config.scope}) at ${config.path}.`);
+        console.log(`  ${sym.ok()}  Already linked to ${c.bold(agentLabel)}  ${c.dim(tildeify(config.path))}`);
+    }
+    if (skills.status === "installed") {
+        const installed = parseInstalledSkills(skills.stdout);
+        if (installed.length > 0) {
+            const where = parseSkillTargetDir(skills.stdout);
+            console.log(`  ${sym.ok()}  Installed ${c.bold(String(installed.length) + " skills")}  ${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(" · "))}`);
+            }
+        }
+        else {
+            console.log(`  ${sym.ok()}  Installed recommended skills`);
+        }
+    }
+    else if (skills.status === "planned" || skills.status === "skipped") {
+        console.log(`  ${sym.warn()}  Skills: ${c.dim(skills.message)}`);
+    }
+    else if (skills.status === "failed") {
+        console.log(`  ${sym.fail()}  Skills install failed`);
+        if (skills.stderr)
+            console.log(`     ${c.dim(skills.stderr)}`);
     }
     for (const warning of config.warnings) {
-        console.warn(`Warning: ${warning}`);
+        console.log(`  ${sym.warn()}  ${c.yellow(warning)}`);
     }
-    console.log(`Skills: ${skills.message}`);
     console.log("");
     printDoctorResult(doctor);
+    if (doctor.ok && skills.status !== "failed" && !config.dryRun) {
+        console.log("");
+        console.log(`${c.dim("Try it:")} open ${AGENT_LABEL[config.agent] ?? config.agent} and ask: ${c.bold("\"add a DirectionalLight3D and Camera3D to my scene\"")}`);
+    }
+}
+function parseInstalledSkills(stdout) {
+    if (!stdout)
+        return [];
+    // Lines look like: "  Installed fps-controller -> /path/.../fps-controller"
+    const names = [];
+    for (const line of stdout.split("\n")) {
+        const m = line.match(/^\s*Installed\s+([a-z0-9-]+)\s+->/i);
+        if (m)
+            names.push(m[1]);
+    }
+    return names;
+}
+function parseSkillTargetDir(stdout) {
+    if (!stdout)
+        return null;
+    for (const line of stdout.split("\n")) {
+        const m = line.match(/^\s*Installed\s+[a-z0-9-]+\s+->\s+(.+)$/i);
+        if (m) {
+            const path = m[1].trim();
+            // Strip trailing /<skill-name> to get the parent dir
+            const parent = path.replace(/\/[a-z0-9-]+$/i, "/");
+            return parent;
+        }
+    }
+    return null;
 }

package/dist/commands/skills.js

@@ -4,6 +4,7 @@ import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { homedir } from "os";
 import { AGENT_CLIENTS, SKILL_REGISTRY, } from "../lib/skills-registry.js";
+import { tildeify } from "../lib/format.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // Resolve skills dir: from dist/commands/skills.js -> ../../skills
 const skillsDir = join(__dirname, "..", "..", "skills");
@@ -242,15 +243,16 @@ function escapeRegExp(value) {
 }
 function printInstallSummary(count, agent, scope, location) {
     const label = agentLabel(agent);
+    const tildeified = tildeify(location.path);
     console.log(`\n${count} skill${count === 1 ? "" : "s"} ready for ${label} (${scope} scope).`);
     if (location.kind === "skill-dir") {
-        console.log(`${label} can read skills from ${location.path}/<skill>/SKILL.md`);
+        console.log(`${label} can read skills from ${tildeified}/<skill>/SKILL.md`);
     }
     else if (location.kind === "cursor-rule-dir") {
-        console.log(`Cursor rules are in ${location.path}/summer-<skill>.mdc`);
+        console.log(`Cursor rules are in ${tildeified}/summer-<skill>.mdc`);
     }
     else {
-        console.log(`Windsurf rules are in ${location.path}`);
+        console.log(`Windsurf rules are in ${tildeified}`);
     }
 }
 export const skillsCommand = new Command("skills")

package/dist/lib/format.d.ts

@@ -0,0 +1,23 @@
+export declare function useColor(): boolean;
+export declare const c: {
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    red: (s: string) => string;
+    green: (s: string) => string;
+    yellow: (s: string) => string;
+    cyan: (s: string) => string;
+    brand: (s: string) => string;
+};
+export declare const sym: {
+    ok: () => string;
+    warn: () => string;
+    fail: () => string;
+    arrow: () => string;
+};
+export declare function tildeify(path: string | undefined | null): string;
+export declare function brandLine(version: string): string;
+export declare function stripAnsi(s: string): string;
+/**
+ * Pad a string to a visible width, accounting for ANSI codes.
+ */
+export declare function pad(s: string, width: number): string;

package/dist/lib/format.js

@@ -0,0 +1,60 @@
+import { homedir } from "os";
+const ANSI = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    red: "\x1b[31m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    cyan: "\x1b[36m",
+    // Summer brand orange (matches banner.ts mid gradient)
+    brand: "\x1b[38;2;255;143;23m",
+};
+export function useColor() {
+    if (process.env.NO_COLOR)
+        return false;
+    if (process.env.FORCE_COLOR)
+        return true;
+    return Boolean(process.stdout.isTTY);
+}
+function paint(code, s) {
+    return useColor() ? `${code}${s}${ANSI.reset}` : s;
+}
+export const c = {
+    bold: (s) => paint(ANSI.bold, s),
+    dim: (s) => paint(ANSI.dim, s),
+    red: (s) => paint(ANSI.red, s),
+    green: (s) => paint(ANSI.green, s),
+    yellow: (s) => paint(ANSI.yellow, s),
+    cyan: (s) => paint(ANSI.cyan, s),
+    brand: (s) => paint(ANSI.brand, s),
+};
+export const sym = {
+    ok: () => c.green("✓"),
+    warn: () => c.yellow("⚠"),
+    fail: () => c.red("✗"),
+    arrow: () => c.brand("▶"),
+};
+export function tildeify(path) {
+    if (!path)
+        return "";
+    const home = homedir();
+    if (path === home)
+        return "~";
+    if (path.startsWith(home + "/"))
+        return "~" + path.slice(home.length);
+    return path;
+}
+export function brandLine(version) {
+    return `${sym.arrow()} ${c.bold("Summer Engine")} ${c.dim("v" + version)}`;
+}
+export function stripAnsi(s) {
+    return s.replace(/\x1b\[[0-9;]*m/g, "");
+}
+/**
+ * Pad a string to a visible width, accounting for ANSI codes.
+ */
+export function pad(s, width) {
+    const visLen = stripAnsi(s).length;
+    return s + " ".repeat(Math.max(0, width - visLen));
+}

package/dist/lib/format.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/format.test.js

@@ -0,0 +1,36 @@
+import { homedir } from "os";
+import { describe, expect, it } from "vitest";
+import { stripAnsi, tildeify } from "./format.js";
+describe("tildeify", () => {
+    it("replaces home directory prefix with ~", () => {
+        const home = homedir();
+        expect(tildeify(home + "/.claude.json")).toBe("~/.claude.json");
+        expect(tildeify(home + "/projects/foo")).toBe("~/projects/foo");
+    });
+    it("returns ~ when path is the home directory exactly", () => {
+        expect(tildeify(homedir())).toBe("~");
+    });
+    it("does not touch non-home paths", () => {
+        expect(tildeify("/Applications/Summer.app")).toBe("/Applications/Summer.app");
+        expect(tildeify("/tmp/foo")).toBe("/tmp/foo");
+    });
+    it("does not partial-match (e.g. /Users/Mat vs /Users/MathiasWork)", () => {
+        const home = homedir();
+        const sibling = home.slice(0, -2) + "Other";
+        expect(tildeify(sibling + "/file")).toBe(sibling + "/file");
+    });
+    it("handles empty/null/undefined input", () => {
+        expect(tildeify(undefined)).toBe("");
+        expect(tildeify(null)).toBe("");
+        expect(tildeify("")).toBe("");
+    });
+});
+describe("stripAnsi", () => {
+    it("removes ANSI color codes", () => {
+        expect(stripAnsi("\x1b[31mhello\x1b[0m")).toBe("hello");
+        expect(stripAnsi("\x1b[1;32mbold green\x1b[0m text")).toBe("bold green text");
+    });
+    it("leaves clean strings untouched", () => {
+        expect(stripAnsi("hello")).toBe("hello");
+    });
+});

package/dist/lib/skills-registry.d.ts

@@ -17,6 +17,22 @@ export interface SkillRegistryEntry {
  * with shippable content). When a NEXT skill ships, mirror it here.
  */
 export declare const SKILL_REGISTRY: readonly [{
+    readonly name: "debug";
+    readonly category: "debugging";
+    readonly public: true;
+    readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf"];
+    readonly recommended: true;
+    readonly requiresMcpTools: readonly ["summer_get_console", "summer_get_debugger_errors", "summer_get_script_errors", "summer_get_diagnostics", "summer_clear_console", "summer_play", "summer_stop", "summer_inspect_node"];
+    readonly testScenario: "Triage a runtime crash end-to-end: read errors, locate code, propose fix, apply on approval, verify.";
+}, {
+    readonly name: "play";
+    readonly category: "scene-and-project";
+    readonly public: true;
+    readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf"];
+    readonly recommended: true;
+    readonly requiresMcpTools: readonly ["summer_is_running", "summer_play", "summer_stop", "summer_clear_console", "summer_get_diagnostics", "summer_get_debugger_errors", "summer_get_script_errors"];
+    readonly testScenario: "Run the game from a clean state, wait for first frame, report whether it runs cleanly or has errors.";
+}, {
     readonly name: "gdscript-patterns";
     readonly category: "scripting-patterns";
     readonly public: true;

package/dist/lib/skills-registry.js

@@ -35,6 +35,41 @@ const ALL_CLIENTS = AGENT_CLIENTS;
  * with shippable content). When a NEXT skill ships, mirror it here.
  */
 export const SKILL_REGISTRY = [
+    {
+        name: "debug",
+        category: "debugging",
+        public: true,
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: [
+            "summer_get_console",
+            "summer_get_debugger_errors",
+            "summer_get_script_errors",
+            "summer_get_diagnostics",
+            "summer_clear_console",
+            "summer_play",
+            "summer_stop",
+            "summer_inspect_node",
+        ],
+        testScenario: "Triage a runtime crash end-to-end: read errors, locate code, propose fix, apply on approval, verify.",
+    },
+    {
+        name: "play",
+        category: "scene-and-project",
+        public: true,
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: [
+            "summer_is_running",
+            "summer_play",
+            "summer_stop",
+            "summer_clear_console",
+            "summer_get_diagnostics",
+            "summer_get_debugger_errors",
+            "summer_get_script_errors",
+        ],
+        testScenario: "Run the game from a clean state, wait for first frame, report whether it runs cleanly or has errors.",
+    },
     {
         name: "gdscript-patterns",
         category: "scripting-patterns",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "summer-engine",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "CLI and MCP tools for Summer Engine — the AI-native game engine",
   "keywords": [
     "game-engine",

package/skills/_tests/specs/debug.md

@@ -0,0 +1,94 @@
+# Skill Spec: /debug
+
+## Fixture
+
+- A Godot/Summer project with one or more reproducible bugs.
+- Summer Engine running, MCP available.
+- Host file tools available (Read, Edit, Write).
+
+## Case 1: Happy Path — runtime error with clear stack trace
+
+**Fixture:** `scripts/player.gd` has `velocity.y -= GRAVTY * delta` (typo: GRAVTY instead of GRAVITY). Player crashes on `_physics_process` first frame.
+
+**Input:** "Debug my game. The player crashes the moment I press play."
+
+**Expected MCP tool sequence (in order):**
+
+1. (Skill asks the user one clarifying question and waits.)
+2. `summer_get_script_errors` — finds `Identifier "GRAVTY" not declared` at scripts/player.gd:14
+3. (Optional: `summer_get_console` to confirm no other errors hiding)
+4. `Read scripts/player.gd` — read 20–40 lines around line 14
+5. (Skill states hypothesis: typo, GRAVTY → GRAVITY)
+6. (Skill asks: "May I edit `scripts/player.gd` to rename GRAVTY → GRAVITY?")
+7. `Edit scripts/player.gd` — apply fix on user OK
+8. `summer_get_script_errors` — verify clean
+
+**Assertions:**
+
+- [ ] Skill asks for the user's description before any tool call.
+- [ ] First diagnostic tool called is `summer_get_script_errors` (cheapest).
+- [ ] Skill does NOT grep the whole codebase before reading the error.
+- [ ] Skill reads only the file + lines indicated by the error, not the whole file.
+- [ ] Skill states a single specific hypothesis before proposing a fix.
+- [ ] Skill asks "May I edit …" before writing.
+- [ ] After the fix, skill re-runs `summer_get_script_errors` to verify.
+- [ ] Skill never calls `summer_set_resource_property` on an inline sub-resource (silent-fail trap).
+
+## Case 2: Failure Path — bug only reproduces at runtime
+
+**Fixture:** Game compiles fine but crashes when player picks up a coin: `Invalid call. Nonexistent function 'play' in base 'Nil'.` AudioStreamPlayer node was deleted in editor but pickup script still references it.
+
+**Input:** "When I pick up a coin, the game crashes."
+
+**Expected behavior:**
+
+- Skill calls `summer_get_script_errors` first → clean.
+- Skill realizes it's runtime: `summer_clear_console`, `summer_play`.
+- Skill asks user: "Reproduce the bug now — pick up a coin."
+- After confirmation, calls `summer_get_debugger_errors`.
+- Stack trace points to `coin.gd:32`, function `_on_body_entered`, calling `audio.play()` where `audio` is `null`.
+- Skill calls `summer_inspect_node "./Coin/AudioStreamPlayer"` to confirm the node is missing.
+- Skill proposes: re-add the AudioStreamPlayer (via `summer_add_node`) OR null-check in code.
+- Asks the user which.
+
+**Assertions:**
+
+- [ ] Skill recognizes that script-errors-clean + crash-on-runtime = runtime-only bug.
+- [ ] Skill explicitly invokes the play→reproduce→read-debugger loop, not just one shot.
+- [ ] Skill verifies the missing-node hypothesis with `summer_inspect_node` BEFORE editing code.
+- [ ] Skill offers BOTH options (fix scene OR fix code) instead of unilaterally picking.
+
+## Case 3: Edge Case — user gives a vague description
+
+**Fixture:** Same as Case 1.
+
+**Input:** "Something's broken."
+
+**Expected behavior:**
+
+- Skill asks one focused follow-up: "What's happening, and when?"
+- Does NOT start grepping code or running tools blindly.
+
+**Assertions:**
+
+- [ ] No tool calls happen until the user gives a concrete symptom.
+- [ ] Skill's follow-up is one short question, not a checklist.
+
+## Case 4: No Summer MCP — fallback path
+
+**Fixture:** Same as Case 1, but Summer MCP is unavailable (engine not connected).
+
+**Input:** "Debug my game."
+
+**Expected behavior:**
+
+- Skill detects MCP unavailable.
+- Asks the user to copy-paste from Godot's Output and Debugger panels.
+- Reasons over the pasted text the same way it would over MCP output.
+- Continues with the rest of the workflow (read code, hypothesize, propose fix).
+
+**Assertions:**
+
+- [ ] Skill does not blindly call `summer_*` tools and fail.
+- [ ] Skill explicitly asks for the panel output instead of guessing.
+- [ ] The rest of the loop (hypothesis → "May I edit?" → verify) still runs.

package/skills/_tests/specs/play.md

@@ -0,0 +1,88 @@
+# Skill Spec: /play
+
+## Fixture
+
+- A Godot/Summer project with a main scene set in `project.godot`.
+- Summer Engine running, MCP available.
+
+## Case 1: Happy Path — clean run
+
+**Fixture:** Project compiles cleanly. Game is not currently running.
+
+**Input:** "Play."
+
+**Expected MCP tool sequence (in order):**
+
+1. `summer_is_running` — false
+2. `summer_get_script_errors` — clean
+3. `summer_clear_console`
+4. `summer_play`
+5. (~2 second wait)
+6. `summer_get_diagnostics`
+7. `summer_get_debugger_errors`
+8. (Skill reports "Running. No errors or warnings.")
+
+**Assertions:**
+
+- [ ] First call is `summer_is_running` to avoid double-launch.
+- [ ] `summer_get_script_errors` runs BEFORE `summer_play` (avoid noisy fail).
+- [ ] `summer_clear_console` runs before `summer_play` (so post-run output is clean).
+- [ ] Skill waits before reading post-play state (≥1 second).
+- [ ] Skill does NOT call `summer_stop` on its own.
+- [ ] Skill reports state in one short sentence, doesn't dump raw tool output.
+
+## Case 2: Failure — game is already running
+
+**Fixture:** Game already running.
+
+**Input:** "Play."
+
+**Expected behavior:**
+
+- `summer_is_running` returns true.
+- Skill asks: "It's already playing. Stop and restart, or leave it?"
+- Waits for user.
+- On "leave it": no further calls. On "stop and restart": `summer_stop`, then continues from step 2.
+
+**Assertions:**
+
+- [ ] Skill does not unilaterally restart.
+- [ ] Skill does not unilaterally `summer_stop` without asking.
+
+## Case 3: Compile error before play
+
+**Fixture:** Script error in `scripts/player.gd:14` (typo). Game not running.
+
+**Input:** "Play."
+
+**Expected behavior:**
+
+- `summer_is_running` → false.
+- `summer_get_script_errors` → returns error.
+- Skill stops, surfaces the error, suggests `/debug`.
+- Does NOT call `summer_play` (would just produce more noise).
+
+**Assertions:**
+
+- [ ] No `summer_play` call when script errors are present.
+- [ ] Error message is one line, not raw tool output.
+- [ ] Skill explicitly mentions `/debug` as the next move.
+
+## Case 4: Runtime crash
+
+**Fixture:** Compiles fine. Game crashes on first frame (e.g. null pointer in `_ready`).
+
+**Input:** "Play."
+
+**Expected behavior:**
+
+- Steps 1–5 run normally.
+- `summer_get_debugger_errors` returns a stack trace.
+- Skill reports the crash in one line and offers `/debug`.
+- Does NOT auto-`summer_stop` — the user might want to inspect.
+
+**Assertions:**
+
+- [ ] Skill detects the crash via `summer_get_debugger_errors`, not by absence of output.
+- [ ] Crash report is concise: error class, location, message.
+- [ ] Skill explicitly mentions `/debug` as the next move.

package/skills/asset-pipeline/asset-strategy/SKILL.md

@@ -4,6 +4,7 @@ description: Decision guide for how to create different game asset types — gen
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: asset-pipeline
+user-invocable: false
 allowed-tools: Read Grep summer_search_assets summer_import_asset summer_generate_image summer_generate_3d summer_generate_audio summer_import_from_url
 ---
 

package/skills/catalog.yaml

@@ -138,6 +138,13 @@ skills:
     public: true
     recommended: true
     last-tested: 2026-05-05
+  - name: play
+    category: scene-and-project
+    status: HAVE
+    public: true
+    recommended: true
+    user-invocable: true
+    last-tested: 2026-05-05
   - name: make-game
     category: scene-and-project
     status: HAVE
@@ -600,11 +607,14 @@ skills:
     public: true
 
   # ── debugging ──
-  - name: debugger-basics
+  - name: debug
     category: debugging
-    status: NEXT
+    status: HAVE
     public: true
-  - name: error-triage-via-summer-mcp
+    recommended: true
+    user-invocable: true
+    last-tested: 2026-05-05
+  - name: debugger-basics
     category: debugging
     status: NEXT
     public: true

package/skills/character-controllers/fps-controller/SKILL.md

@@ -4,6 +4,7 @@ description: First-person character controller with WASD movement, mouse look, j
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: character-controllers
+user-invocable: false
 template-id: template-3d-fps
 allowed-tools: Read Grep summer_add_node summer_set_prop summer_set_resource_property summer_input_map_bind summer_save_scene summer_get_script_errors
 paths: ["**/*.gd", "**/*.tscn"]

package/skills/debugging/debug/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: debug
+description: Use when the user reports their game is broken, crashing, behaving unexpectedly, or says "debug", "fix", "something's wrong", or "it's not working". Triages the bug end-to-end via Summer Engine's diagnostic tools (console, debugger errors, script errors), locates the offending code, proposes a fix, and verifies the fix.
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: debugging
+user-invocable: true
+allowed-tools: Read Grep Glob Edit summer_get_console summer_get_debugger_errors summer_get_script_errors summer_get_diagnostics summer_clear_console summer_play summer_stop summer_is_running summer_get_scene_tree summer_inspect_node
+paths: ["**/*.gd", "**/*.tscn", "**/*.cs"]
+---
+
+# /debug — Triage and Fix a Bug
+
+## Overview
+
+A bug in a Godot/Summer game can hide in three places: scripts (GDScript/C# compile or runtime errors), the engine console (printed messages, warnings), or the scene/resource state (wrong property, missing collider, broken signal connection). This skill walks all three before guessing.
+
+**Core principle:** read what the engine actually saw, not what the code looks like it does.
+
+## Steps
+
+### 1. Get the user's description first
+
+Ask one short question:
+
+> What's happening? Briefly: when does it go wrong, and what do you expect vs. what you see?
+
+Wait for the answer before doing anything else. Don't start grepping code yet — the user's words narrow the search 10x.
+
+### 2. Read the engine's actual error state
+
+Always do this in order. Each tool answers a different question.
+
+**Preferred (Summer MCP):**
+
+```
+summer_get_script_errors        # Compile errors? (cheapest, do first)
+summer_get_console              # Print() output, warnings, info
+summer_get_debugger_errors      # Runtime errors with stack traces
+summer_get_diagnostics          # Aggregated count + summary
+```
+
+If the bug is reproducible only at runtime and the engine isn't currently playing:
+
+```
+summer_clear_console            # Clean slate
+summer_play                     # Run it
+                                # (let the user reproduce the bug)
+summer_get_debugger_errors      # Now read what blew up
+summer_stop                     # When done
+```
+
+**Fallback (no MCP — engine isn't connected):**
+
+Ask the user to copy-paste the engine's Output panel and Debugger errors. Inspect manually.
+
+### 3. Locate the offending code
+
+For each error, follow the stack trace to the file + line. Use host file tools:
+
+```
+Read <file>:<line-near-error>
+```
+
+Read 20–40 lines around the error site. Don't open the whole file unless you need to — context budget matters.
+
+If the error mentions a node path (e.g. `./World/Player/Camera`), inspect it:
+
+```
+summer_inspect_node "./World/Player/Camera"
+```
+
+### 4. Form a hypothesis and propose the fix
+
+State it in one sentence:
+
+> The error happens because <root cause>. The fix is <one-line summary>.
+
+Then ask:
+
+> May I edit `<file>` to <do exactly this>?
+
+Don't guess at multiple fixes at once. Pick one. If wrong, the next iteration is cheap.
+
+### 5. Apply the fix
+
+On user yes, edit the file with host tools (`Edit`/`Write`). Single focused change.
+
+### 6. Verify
+
+Re-run the relevant check:
+
+```
+summer_get_script_errors        # If it was a compile error
+summer_play → summer_get_debugger_errors → summer_stop   # If runtime
+```
+
+Report:
+
+> Fixed. <One-line description of what changed.>
+
+If still broken: go back to step 4 with the new error state. State explicitly that the first hypothesis was wrong.
+
+## Common bug patterns and how to spot them
+
+| Symptom | Likely cause | First check |
+|---|---|---|
+| `Invalid set index 'X' (on base: Nil)` | Node path resolved to null | `summer_inspect_node` the path |
+| `Identifier not declared` (script error) | Missing `class_name` or wrong scope | `summer_get_script_errors` |
+| Game runs but sprite doesn't appear | Node added but not visible (transform / parent / layer) | `summer_get_scene_tree` + inspect parent |
+| Signal handler never fires | Connection not made, or connected to wrong instance | `summer_inspect_node` of emitter, check connections |
+| Player falls through floor | CollisionShape3D has no shape, or shape is inline sub_resource | `summer_inspect_resource` on the CollisionShape |
+| Mouse capture stuck | `Input.set_mouse_mode` not paired with release on focus loss | `summer_get_console` for warnings |
+| Game hangs on start | Infinite loop in `_ready()` or `_process()` | `summer_get_debugger_errors` after a forced stop |
+
+## Anti-patterns (don't do these)
+
+- **Don't** start by reading the user's whole codebase. The error tells you where to look.
+- **Don't** propose a sweeping refactor for a single bug. One file, one change, verify.
+- **Don't** call `summer_set_resource_property` on an inline `sub_resource` — it silently fails. See `_shared/mcp-tools-reference.md` § "Trap".
+- **Don't** call `summer_play` without `summer_clear_console` first if you want clean output to read.
+- **Don't** skip the user's description in step 1. "What were you trying to do" beats "what does the code do" 9/10 times.
+
+## Collaborative protocol
+
+This skill writes files. Always ask before each edit step. See `_shared/collaborative-protocol.md`.
+
+## Want a working starter?
+
+No template — this is a workflow, not a project scaffold. It works against any Godot/Summer project that has Summer MCP wired up.
+
+## See also
+
+- `_shared/mcp-tools-reference.md` — full tool list
+- `_shared/godot-version.md` — engine version + LLM cutoff risks
+- `scripting-patterns/gdscript-patterns/SKILL.md` — what good GDScript looks like
+- `scene-and-project/play/SKILL.md` — running the game

package/skills/rendering-and-lighting/3d-lighting/SKILL.md

@@ -4,6 +4,7 @@ description: Lighting setup, WorldEnvironment, sky, and shadows for 3D scenes. U
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: rendering-and-lighting
+user-invocable: false
 allowed-tools: Read Grep summer_add_node summer_set_prop summer_set_resource_property summer_save_scene
 paths: ["**/*.tscn", "**/*.tres"]
 ---

package/skills/scene-and-project/make-game/SKILL.md

@@ -4,6 +4,7 @@ description: End-to-end game creation workflow that orchestrates project setup,
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: scene-and-project
+user-invocable: false
 allowed-tools: Read Grep Glob Write Edit summer_get_project_context summer_get_agent_playbook summer_create_scene summer_open_scene summer_save_scene summer_add_node summer_set_prop summer_set_resource_property summer_instantiate_scene summer_play summer_stop summer_get_diagnostics
 paths: ["**/*.gd", "**/*.tscn", "**/project.godot"]
 ---

package/skills/scene-and-project/play/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: play
+description: Use when the user says "play", "run it", "test it", "let me see it", or "start the game". Runs the project in Summer Engine, briefly waits, then reports what's happening — clean run, errors, or warnings.
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: scene-and-project
+user-invocable: true
+allowed-tools: summer_is_running summer_play summer_stop summer_clear_console summer_get_console summer_get_debugger_errors summer_get_script_errors summer_get_diagnostics
+paths: ["**/project.godot", "**/*.tscn"]
+---
+
+# /play — Run the Game
+
+## Overview
+
+Press play. Watch what happens. Report it back.
+
+## Steps
+
+### 1. Check if it's already running
+
+```
+summer_is_running
+```
+
+If running:
+> The game is already playing. Stop and restart, or leave it?
+
+Wait for the user. Don't unilaterally stop.
+
+If not running, continue.
+
+### 2. Pre-check for compile errors
+
+Cheapest call. If the script won't compile, play will fail with a noisy error — better to surface that clearly first.
+
+```
+summer_get_script_errors
+```
+
+If errors found:
+> Won't run yet — there's a script error: `<one-line summary>`. Want me to /debug it?
+
+Stop here on user's no.
+
+### 3. Clear and play
+
+```
+summer_clear_console
+summer_play
+```
+
+### 4. Brief wait, then read state
+
+Wait ~2 seconds (so the engine has time to process at least one frame). Then:
+
+```
+summer_get_diagnostics
+summer_get_debugger_errors
+```
+
+### 5. Report
+
+Three outcomes:
+
+**Clean:** `summer_get_diagnostics` shows zero errors and zero warnings.
+
+> Running. No errors or warnings. Tell me what you see and I'll dig in if needed.
+
+**Warnings only:**
+
+> Running. <N> warnings — `<one-line summary of the most important one>`. Want me to look at them?
+
+**Runtime error:**
+
+> Crashed: `<error class>` at `<file>:<line>` — `<message>`. Want me to /debug?
+
+### 6. Don't auto-stop
+
+Leave the game running. The user wants to play it. Stop only on explicit ask.
+
+## Common patterns
+
+| Situation | Right move |
+|---|---|
+| User says "play" with no context | Steps 1–5 above |
+| User says "play and watch it for me" | After step 5, set a timer / poll `summer_get_debugger_errors` every few seconds for the duration the user specifies |
+| User says "play the boss fight scene" | Open the specific scene first (`summer_open_scene "scenes/boss_fight.tscn"`), then steps 1–5 |
+| Game is already running and user says "play" again | Step 1's check covers it — ask before restarting |
+
+## Anti-patterns
+
+- **Don't** auto-stop a running game just because the user said "play". They probably mean "make sure it's playing", not "stop and restart".
+- **Don't** call `summer_get_console` instead of `summer_get_debugger_errors` for runtime errors. Console has print() output and warnings; debugger errors has the stack traces.
+- **Don't** report "no errors" before waiting for the engine to actually run a frame. A 0-frame snapshot is meaningless.
+
+## Collaborative protocol
+
+This skill mutates engine state (clearing console, starting play). It's a read-side workflow with one safe write (`summer_play`). No "May I" needed — this is what the user asked for. Do confirm before stopping a running game.
+
+## Want a working starter?
+
+No template — works against any Godot/Summer project that has a main scene set in `project.godot`.
+
+## See also
+
+- `_shared/mcp-tools-reference.md` — full tool list
+- `debugging/debug/SKILL.md` — what to do when /play surfaces an error

package/skills/scene-and-project/scene-composition/SKILL.md

@@ -4,6 +4,7 @@ description: How to structure scenes, when to use sub-scenes, node hierarchy con
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: scene-and-project
+user-invocable: false
 allowed-tools: Read Grep summer_create_scene summer_open_scene summer_get_scene_tree summer_add_node summer_instantiate_scene summer_save_scene
 paths: ["**/*.tscn"]
 ---

package/skills/scripting-patterns/gdscript-patterns/SKILL.md

@@ -4,6 +4,7 @@ description: Common GDScript idioms — type hints, signals, exports, onready, l
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: scripting-patterns
+user-invocable: false
 allowed-tools: Read Grep summer_get_script_errors
 paths: ["**/*.gd"]
 ---

package/skills/ui-and-ux/ui-basics/SKILL.md

@@ -4,6 +4,7 @@ description: HUD, menus, health bars, progress bars, and Control-based UI layout
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: ui-and-ux
+user-invocable: false
 allowed-tools: Read Grep summer_add_node summer_set_prop summer_connect_signal summer_save_scene
 paths: ["**/*.tscn", "**/*.gd"]
 ---