summer-engine 2.8.2 → 3.1.0

package/commands/gameskill.md

@@ -1,112 +1,14 @@
-You are capturing what we just learned in this game-development session into Summer Engine's skill library, so the next agent (and every Summer user) gets to start where we ended.
+---
+description: Capture what this game-development session taught as a reusable skill (project, user or Summer library) so the next agent starts where you ended.
+allowed-tools: Read Write Edit Glob Grep Bash Skill
+---
 
-This is the meta-skill: the loop that turns ad-hoc fixes into durable, reusable expertise.
+# /gameskill — capture session learnings
 
-## What "Summer Engine" is, so you're grounded
+Activate the library skill `summer:gameskill` and follow it exactly; this command is only the entry point. If the `Skill` tool cannot find it, read `library/skills/gameskill/SKILL.md` from the Summer package (the plugin root, or `node_modules/summer-engine/`) and follow that file.
 
-Three repos, one ecosystem:
+Ground rules the skill enforces, so you do not drift while it loads:
 
-1. **`~/development/SummerEngine`** — the Summer Engine desktop source and the
-   canonical CLI. The C++ engine is maintained against the upstream Godot
-   Engine codebase; the Summer-owned module lives at `modules/1summer_engine/`.
-   The Summer CLI lives at `tools/summer-cli/` and is normally invoked with
-   `npx -y summer-engine@latest`. It installs, signs in, creates, and runs Summer
-   projects and can install the current Summer skill bundle for supported
-   agents.
-2. **`~/development/PublicSummerEngine`** — the web app at summerengine.com. Has its own AI skill stores at `src/lib/ai/skills/bundled/` and `public/knowledge/summer/skills/` for the in-browser chat agent. ALSO has its own MCP-style consumers of the engine API (`src/lib/bridge/direct-executor.ts`, `src/lib/ai/tools/run-and-verify.ts`) which call the same engine endpoints the CLI does.
-3. **The active Summer game project** — usually
-   `~/development/<game-name>` or whatever game we were just working on. The
-   live compatibility line comes from Summer Engine, not this prompt. Real
-   working code in this repo is the gold standard for examples.
-
-The skill system is the value flywheel: every game we ship teaches lessons → the lessons become skills → the next user (or AI) starts smarter. Your job here is to close that loop for what we just did.
-
-## Cross-repo change awareness — read this before any non-trivial fix
-
-When the lesson is "the engine should expose more / behave differently," the change usually crosses repo boundaries. Map the layers before you edit:
-
-```
-[active game] → calls MCP / web app
-                       ↓
-[summer-cli MCP server (TypeScript)] → calls /api/ops + /api/state/* on the engine
-                       ↓
-[Summer Engine binary (C++ in SummerEngine repo)] — source of truth for what the API can return
-
-[PublicSummerEngine web app (TypeScript)] → also calls the same engine endpoints via direct-executor or Redis bridge
-```
-
-Implications:
-
-- **A C++ change in `SummerEngine/modules/1summer_engine/` or `SummerEngine/editor/` reaches everyone** (CLI MCP, web app, future tools). Most powerful, also highest blast radius.
-- **A TypeScript change in `tools/summer-cli/src/mcp/`** only changes what the CLI exposes. The web app has its own TypeScript layer in `PublicSummerEngine/src/lib/bridge/` — same engine endpoints, different glue. Don't assume your CLI tool change is web-app-aware.
-- **A skill update in `tools/summer-cli/skills/`** affects every agent that runs `summer skills install`. The web app's skill store is separate (`PublicSummerEngine/src/lib/ai/skills/bundled/`) and currently uses a different format (template wizards, not Markdown discipline guides). Don't try to mirror skills there blindly.
-
-When you change an engine endpoint's response shape (add fields, rename fields, change semantics):
-
-1. Grep both `tools/summer-cli/src/` and `PublicSummerEngine/src/lib/` for consumers of that endpoint.
-2. Confirm the change is **additive** (new fields, no removed/renamed) so existing consumers still work without modification.
-3. If the change is breaking, update both consumers in the same logical commit set.
-4. Note in TOOLING-TODO.md what's now possible that wasn't before.
-
-Engine binary changes ship via a rebuild + new release. The user has to pull the new engine for the change to take effect. CLI/web TypeScript changes ship via npm publish or web deploy. State this delivery cost in your report so the user knows what they're getting today vs after a release.
-
-## The four skill stores (probe each before doing anything)
-
-1. **Canonical source** — `~/development/SummerEngine/tools/summer-cli/skills/`
-   - Single source of truth. Domains: `ui-and-ux`, `gameplay-mechanics`, `character-controllers`, `scripting-patterns`, `visual-effects`, `debugging`, `rendering-and-lighting`, `scene-and-project`, `level-design`, `audio`, `ai-and-npcs`, `asset-pipeline`, `performance`, `deployment`, `multiplayer-and-networking`, plus `workflow` for process skills.
-   - The `skills:` array in `.claude-plugin/plugin.json` is the registry. Sibling shared docs live at top-level `references/`; test specs at top-level `tests/`.
-2. **Claude auto-discovery** — `~/.claude/skills/` (currently 7 skills, written here by `summer skills install --as-claude-skill`).
-3. **Web-app stores** — `~/development/PublicSummerEngine/src/lib/ai/skills/` and `public/knowledge/summer/skills/`. Mirror only if the learning applies to the web chat agent too — check what's there before assuming.
-4. **The active game** — read it as ground truth. Working code from the real project beats invented examples.
-
-## What to do, in order
-
-1. **One short sentence to the user.** "Capturing learnings from this session into the skill library." That's it. No plan dump.
-
-2. **Probe the stores.** Glob each path above. Note what exists and what's empty. Print a tight summary (one line per domain with skill count).
-
-3. **Recap the session.** Look back over the conversation. Pull out the learnings that are non-obvious AND general — things a future agent or user would benefit from but couldn't derive from reading the codebase. Examples that count:
-   - A working shader (the actual code) → `visual-effects`
-   - A GDScript idiom that beat the obvious approach → `scripting-patterns`
-   - A UI layout that survived the design pass → `ui-and-ux`
-   - A bug + root cause + fix that wasn't in any docs → `debugging`
-   - A Godot 4.6 quirk (type inference, `.keys()` weirdness, signal gotchas) → `scripting-patterns`
-   - A spawning/AI/enemy pattern that worked → `ai-and-npcs` or `gameplay-mechanics`
-   - A perf fix with measured before/after → `performance`
-   - An asset-creation workflow that beat alternatives → `asset-pipeline`
-
-   Examples that DON'T count:
-   - One-off code with no general lesson
-   - Stuff already documented in `CLAUDE.md` or an existing skill
-   - Personal preference with no reasoning behind it
-   - Anything you have to manufacture to fill space
-
-4. **Decide placement.** For each learning:
-   - **Update existing skill** — name the file, quote the section, draft the addition.
-   - **Create new skill** — pick the domain, name the file, draft the full skill markdown.
-   Match the format of existing skills in the same domain exactly. Read one if you're unsure.
-
-5. **One tight pause for the user.** Five-to-ten lines max: what files you'll touch, what each one captures, what gets left out. Wait for OK or redirect. Don't ask multiple questions.
-
-6. **Apply.**
-   - Write/edit `.md` files under `tools/summer-cli/skills/<domain>/`.
-   - Register a new skill in `.claude-plugin/plugin.json` (plus `.codex-plugin/`, `.cursor-plugin/`) AND in `src/lib/skills-registry.ts` `SKILL_REGISTRY`. Both are required.
-   - If the skill belongs in the curated Claude set, also write it to `~/.claude/skills/<name>/` so it's live in the current session — and tell the user to consider adding it to the CLI's default install set.
-   - If the learning applies to the web chat agent, mirror to `PublicSummerEngine` skill stores too.
-   - Run `git status` in `~/development/SummerEngine` (and `PublicSummerEngine` if touched) so the diff is visible.
-
-7. **Report.** One short message. Files changed, the future-agent payoff in one sentence per skill, and what (if anything) is still uncaptured.
-
-## Style rules — non-negotiable
-
-- **Tight. No slop. No glazing.** Mathias hates filler.
-- **Capture the why, not just the what.** "Use X" rots. "Use X because Y breaks under Z (we hit this in PRUT chest reveal, 2026-05)" survives. Always lead skill updates with the reason.
-- **Real working code from the active project beats invented examples.** Lift from PRUT or whatever we were in.
-- **VFX is code** — shaders + GDScript + node setup. Never image-generation pipelines or Meshy prompts.
-- **No em dashes** (—) in any user-facing copy you write into skills. Use periods or restructure the sentence.
-- **`[SUMMER]` markers on core Godot engine file edits** — but skill `.md` files don't need them.
-- **Verify before claiming.** If a skill says "Summer Engine does X" or "Stripe is configured Y way", verify in the actual code/DB before writing it down.
-
-## When there's nothing worth capturing
-
-It's totally fine to come back with "session was tactical, no durable learnings worth a skill update." Don't manufacture skills from thin air. Better to ship nothing into the skill library than ship noise.
+- Default home is the game project's own skills directory for the agent you are in (`.claude/skills/<slug>/`, `.agents/skills/<slug>/`, `.cursor/rules/`). Only inside a checkout of the summer-engine agent repo do you add to `library/skills/<slug>/` (`resource.yaml` + `SKILL.md`, flat slugs); everything in `registry/generated/` and every plugin manifest is generated from it, so run `npm run generate:registry` after editing and never hand-edit those files. From anywhere else, send general lessons through `summer_library_feedback`.
+- Capture only learnings that are non-obvious AND general. Lead with the why. Real working code from the active project beats invented examples. VFX is shader + GDScript + node setup, never an image-generation pipeline.
+- It is fine to report "session was tactical, no durable learnings." Do not manufacture skills.

package/commands/summer.md

@@ -1,4 +1,12 @@
-You are the Summer Engine command router. The user invoked `/summer` because they want game-development help inside Summer Engine, not generic software advice.
+---
+description: Summer Engine game-dev persona and command router. Use for "/summer <anything>" — routes the request to the right Summer skill and starts the game-dev workflow.
+argument-hint: <what you want to build, fix, or ship>
+allowed-tools: Read Glob Grep Edit Write Skill Bash summer_get_project_context summer_get_scene_tree summer_get_diagnostics summer_search_assets summer_create_debug_report
+---
+
+# /summer — Summer Engine persona
+
+You are now Summer's in-engine collaborator. The user typed `/summer` because they want game-dev-shaped help inside Summer Engine, not generic software advice. Drop the SaaS-PM voice. You ship games.
 
 Arguments:
 
@@ -6,8 +14,68 @@ Arguments:
 $ARGUMENTS
 ```
 
-First, route the request to the closest Summer skill. Use `summer:using-summer` if you need base context before choosing.
+## Voice
+
+You know the engine cold. Scenes are `.tscn`, resources are `.tres`, scripts are GDScript unless the user said C#. The `summer-engine` MCP server drives the running editor. Read every file in the project freely with Read / Glob / Grep — code, scenes, resources, configs; that is how you understand the project. The one rule: do not hand-edit `.tscn` / `.tres` files with Write / Edit while the editor has that scene open — the editor's in-memory state overwrites you on save. Mutate scenes through `summer_*` MCP tools. Scripts, configs, and any closed scene are fine to edit directly.
+
+You are opinionated about scope. When the user describes three features in one sentence, ask which one is the playable demo and defer the other two. "Wouldn't it be cool if" gets "yes, after the core loop runs." Get the core loop into the player's hands by the end of the session, then iterate. Polish happens after the game is playable, not before.
+
+You speak game-dev shorthand (PCs, NPCs, juice, hit-stop, root motion, blendspace, navmesh, kinematic vs rigid) and assume the user knows it. You are confident about cost: every generation has a number, and you say the number before spending the user's money.
+
+## What to do
+
+1. Detect the request shape (new game / new feature / new asset / bug / discussion / build).
+2. Confirm Summer Engine context. Call `summer_get_project_context` if available. If it returns nothing, the user is not in a Summer project yet — route to `summer:brainstorm-game`.
+3. Invoke the right Summer skill with the `Skill` tool. Do not paraphrase the skill; let the specialist run and follow it exactly.
+4. State the estimated cost (dollars and seconds) before any generation call.
+
+## Routing
+
+Skills are flat slugs under the `summer:` namespace (`summer:<slug>`); there are no category paths.
+
+| Request shape | First skill |
+|---|---|
+| brainstorm a [genre] game / let's make a [genre] / I'm stuck / what should I work on | `summer:brainstorm-game` |
+| start a new project | `summer:new-project` |
+| make me a game from scratch | `summer:make-game` |
+| add a [character / enemy / NPC / prop / vehicle] | `summer:asset-strategy` |
+| add a sound for [event] | `summer:sound-effect` |
+| add ambient music | `summer:music-track` |
+| make me fire / smoke / lightning / muzzle flash / magic glow / hit spark / dissolve / water ripple | `summer:vfx-fire`, `summer:vfx-smoke`, `summer:vfx-lightning`, `summer:vfx-muzzle-flash`, `summer:vfx-magic-glow`, `summer:vfx-hit-spark`, `summer:vfx-dissolve`, `summer:vfx-water-ripple` |
+| build the FPS controller | `summer:fps-controller` |
+| debug / the game crashes when [X] / broken behavior / cloud or Codex failure / send this to support | `summer:debug` (support-report mode first: call `summer_create_debug_report` when available and tell the user where the Markdown report was written; keep fixing only if they also asked for a fix) |
+| add an animation to [character] | `summer:generate-motion` |
+| wire up a state machine for [character] | `summer:animation-tree` |
+| the game feels mushy / add juice | `summer:game-feel` |
+| ship a trailer | `summer:trailer-shot` |
+| cutscene for [X] | `summer:cinematic-cutscene` |
+| let me play it | `summer:play` |
+
+If nothing fits, activate `summer:using-summer` and call `summer_search_library` (then `summer_read_library`) to find the closest skill. Never invent a skill name; verify it exists first.
+
+## Tone rules
+
+- No corporate hedging. "I'd recommend" becomes "do this." "It might be worth considering" becomes "next step is."
+- Cost-aware: "Generating with kling. 5s, ~$0.50. OK?" — never "I'll generate a video now."
+- Scope-aware: the cut list goes in `.summer/GameSoul.md`, not in V1.
+- Confirm before destructive moves: replacing nodes, deleting assets, regenerating expensive outputs.
+- Do not redirect users to external docs; solve it in-conversation.
+
+## Engine awareness
+
+- If any MCP call returns "Summer Engine is not running": tell the user `summer run` (or open the Summer Engine app and load the project). Meanwhile do non-MCP work: read code, plan, draft GDScript. The MCP server reconnects on the next call.
+- If `.summer/GameSoul.md` exists, read it before any creative work. It is the source of truth for art direction, audio direction, and the cut list.
+
+## Examples
 
-If the arguments start with `debug`, or the user is reporting a crash, error, broken behavior, cloud/Codex failure, or anything they want to send to Summer support, use `summer:debugging/debug`. In that support-report mode, call `summer_create_debug_report` when available and tell the user where the Markdown report was written. Continue fixing the issue only if the user also asked for a fix.
+> User: /summer make a knight
+>
+> Summer: Knight character. asset-strategy first to lock the look (concept image), then character-model for the rigged mesh. ~$0.10 for the concept, ~$0.40 for the 3D pass. OK?
+>
+> [invokes `summer:asset-strategy`]
 
-For all other requests, follow the `/summer` persona routing table from the Summer skill family and start the appropriate game-dev workflow.
+> User: /summer the game crashes when I pick up the sword
+>
+> Summer: Going to debug. Writing the support report first, then the fix.
+>
+> [invokes `summer:debug`]

package/dist/bin/summer.js

@@ -1,88 +1,7 @@
 #!/usr/bin/env node
-import { createRequire } from "node:module";
-import { Command } from "commander";
-import { mcpCommand } from "../commands/mcp.js";
-import { loginCommand } from "../commands/login.js";
-import { logoutCommand } from "../commands/logout.js";
-import { statusCommand } from "../commands/status.js";
-import { runCommand } from "../commands/run.js";
-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";
-import { doctorCommand } from "../commands/doctor.js";
-import { planCommand } from "../commands/plan.js";
-import { cloudCommand } from "../commands/cloud.js";
-import { debugCommand } from "../commands/debug.js";
-import { configCommand } from "../commands/config.js";
-import { publishCommand } from "../commands/publish.js";
-import { releasesCommand } from "../commands/releases.js";
-import { logsCommand } from "../commands/logs.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)
-    .action(() => {
-    printIntro(version);
-});
-program.addCommand(installCommand);
-program.addCommand(loginCommand);
-program.addCommand(logoutCommand);
-program.addCommand(statusCommand);
-program.addCommand(runCommand);
-program.addCommand(openCommand);
-program.addCommand(createCommand);
-program.addCommand(listCommand);
-program.addCommand(memoryCommand);
-program.addCommand(skillsCommand);
-program.addCommand(mcpCommand);
-program.addCommand(setupCommand);
-program.addCommand(doctorCommand);
-program.addCommand(debugCommand);
-program.addCommand(planCommand);
-program.addCommand(orchestratorCommand);
-program.addCommand(cloudCommand);
-program.addCommand(configCommand);
-program.addCommand(publishCommand);
-program.addCommand(releasesCommand);
-program.addCommand(logsCommand);
-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("Setup wizard")}`);
-    console.log(`     Open Claude Code, Cursor, Codex, Copilot, Devin Desktop (formerly 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 plan make a small arena shooter`);
-    console.log(`     ${c.dim("$")} npx -y summer-engine@latest debug "player crashes on pickup"`);
-    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("/summer debug")}   ${c.dim("Create a support-ready debug report")}`);
-    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-engine-agent`);
-    console.log("");
-}
+// Composition root: the only module allowed to import both the cli and mcp
+// layers. All command wiring lives in src/cli; the MCP server and its
+// `summer mcp` command live in src/mcp.
+import { runCli } from "../cli/index.js";
+import { mcpCommand } from "../mcp/command.js";
+runCli(mcpCommand);

package/dist/cli/banner.d.ts

@@ -0,0 +1 @@
+export declare function getBanner(version?: string): string;

package/dist/cli/banner.js

@@ -0,0 +1,33 @@
+export function getBanner(version) {
+    const reset = "\x1b[0m";
+    // Vertical gradient for SUMMER ENGINE
+    const colors = [
+        "\x1b[38;2;255;223;137m", // row 1
+        "\x1b[38;2;255;203;107m", // row 2
+        "\x1b[38;2;255;183;78m", // row 3
+        "\x1b[38;2;255;163;49m", // row 4
+        "\x1b[38;2;255;143;23m", // row 5
+        "\x1b[38;2;255;123;0m", // row 6
+        "\x1b[38;2;242;104;0m", // row 7
+        "\x1b[38;2;229;85;0m", // row 8
+        "\x1b[38;2;215;67;0m", // row 9
+        "\x1b[38;2;201;50;0m", // row 10
+        "\x1b[38;2;187;34;0m", // row 11
+        "\x1b[38;2;173;20;0m", // row 12
+    ];
+    const headerLines = [
+        "      ██████╗ ██╗   ██╗███╗   ███╗███╗   ███╗███████╗██████╗ ",
+        "     ██╔════╝ ██║   ██║████╗ ████║████╗ ████║██╔════╝██╔══██╗",
+        "     ███████╗ ██║   ██║██╔████╔██║██╔████╔██║█████╗  ██████╔╝",
+        "     ╚════██║ ██║   ██║██║╚██╔╝██║██║╚██╔╝██║██╔══╝  ██╔══██╗",
+        "     ███████║ ╚██████╔╝██║ ╚═╝ ██║██║ ╚═╝ ██║███████╗██║  ██║",
+        "     ╚══════╝  ╚═════╝ ╚═╝     ╚═╝╚═╝     ╚═╝╚══════╝╚═╝  ╚═╝",
+        "      ███████╗███╗   ██╗ ██████╗ ██╗███╗   ██╗███████╗       ",
+        "      ██╔════╝████╗  ██║██╔════╝ ██║████╗  ██║██╔════╝       ",
+        "      █████╗  ██╔██╗ ██║██║  ███╗██║██╔██╗ ██║█████╗         ",
+        "      ██╔══╝  ██║╚██╗██║██║   ██║██║██║╚██╗██║██╔══╝         ",
+        "      ███████╗██║ ╚████║╚██████╔╝██║██║ ╚████║███████╗       ",
+        "      ╚══════╝╚═╝  ╚═══╝ ╚═════╝ ╚═╝╚═╝  ╚═══╝╚══════╝       ",
+    ];
+    return headerLines.map((line, i) => `${colors[i]}${line}${reset}`).join("\n");
+}

package/dist/{commands → cli/commands}/config.js

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-import { CONFIG_KEYS, getConfigValue, isConfigKey, readSummerConfig, setConfigValue, unsetConfigValue, } from "../lib/config.js";
+import { CONFIG_KEYS, getConfigValue, isConfigKey, readSummerConfig, setConfigValue, unsetConfigValue, } from "../../core/config.js";
 function requireKey(value) {
     if (isConfigKey(value))
         return value;

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

@@ -0,0 +1,30 @@
+import { Command } from "commander";
+/**
+ * Built-in templates are generated in-process — no download, no pin. Their
+ * library manifests (`library/templates/<slug>/resource.yaml`) declare
+ * `builtin: true`; this map supplies the generator for each such slug.
+ */
+type BuiltinGenerator = (dir: string, projectName: string) => void;
+export declare const BUILTIN_GENERATORS: Readonly<Record<string, BuiltinGenerator>>;
+/**
+ * Copy the autopilot verification scaffold into a fresh project.
+ *
+ * Every project gets a working example of how to prove its own gameplay: a probe
+ * that drives the player with real input, saves rendered frames, asserts, and
+ * exits. Without it every agent reinvents verification from scratch, and most
+ * settle for asking the user to play the game instead.
+ *
+ * Never overwrites — an existing tests/autopilot/ is the user's, not ours.
+ */
+export declare function scaffoldAutopilot(projectDir: string): boolean;
+/** What the scaffold's first run actually does — the "Next steps" line must not
+ *  promise a verify when the first thing run.sh does is the one-off asset import. */
+export declare const AUTOPILOT_NEXT_STEP_HINT = "first run imports assets once, then verifies the game boots; no editor needed";
+export declare const createCommand: Command;
+/**
+ * project.godot uses C-style double-quoted strings; a project name containing
+ * `"` or `\` must be escaped or the file does not parse.
+ */
+export declare function escapeGodotString(value: string): string;
+export declare function renderProjectSettings(name: string, mainScene: string): string;
+export {};

package/dist/cli/commands/create.js

@@ -0,0 +1,212 @@
+import { Command } from "commander";
+import { cpSync, existsSync, mkdirSync, writeFileSync } from "fs";
+import { join, resolve } from "path";
+import { checkEngineHealth, getApiPort } from "../../core/engine.js";
+import { PACKAGE_ROOT } from "../../core/package-root.js";
+import { SUMMER_ENGINE_COMPATIBILITY } from "../../core/summer-compatibility.js";
+import { getTemplateRegistry, materializePinnedTemplate, resolveTemplate, TemplateDigestMismatchError, } from "../../core/templates.js";
+import { PROJECT_MANIFEST_RELPATH, writeProjectManifest } from "../../project-memory/project-manifest.js";
+import { TOOLKIT_VERSION as toolkitVersion } from "../../core/version.js";
+/** Summer Engine's version when it is reachable right now, else undefined —
+ *  the manifest then omits engine_version rather than guessing. */
+async function detectEngineVersion() {
+    try {
+        return (await checkEngineHealth(await getApiPort()))?.version;
+    }
+    catch {
+        return undefined;
+    }
+}
+export const BUILTIN_GENERATORS = {
+    empty: (dir, name) => {
+        writeFileSync(join(dir, "project.godot"), renderProjectSettings(name, "res://main.tscn"));
+        writeFileSync(join(dir, "main.tscn"), emptyScene());
+    },
+    "3d-basic": (dir, name) => {
+        writeFileSync(join(dir, "project.godot"), renderProjectSettings(name, "res://main.tscn"));
+        writeFileSync(join(dir, "main.tscn"), basicScene3D());
+    },
+};
+/**
+ * Copy the autopilot verification scaffold into a fresh project.
+ *
+ * Every project gets a working example of how to prove its own gameplay: a probe
+ * that drives the player with real input, saves rendered frames, asserts, and
+ * exits. Without it every agent reinvents verification from scratch, and most
+ * settle for asking the user to play the game instead.
+ *
+ * Never overwrites — an existing tests/autopilot/ is the user's, not ours.
+ */
+export function scaffoldAutopilot(projectDir) {
+    const source = join(PACKAGE_ROOT, "assets", "autopilot");
+    const target = join(projectDir, "tests", "autopilot");
+    if (!existsSync(source) || existsSync(target))
+        return false;
+    cpSync(source, target, { recursive: true });
+    return true;
+}
+/** What the scaffold's first run actually does — the "Next steps" line must not
+ *  promise a verify when the first thing run.sh does is the one-off asset import. */
+export const AUTOPILOT_NEXT_STEP_HINT = "first run imports assets once, then verifies the game boots; no editor needed";
+function printNextSteps(fullPath, dirName, scaffolded) {
+    console.log(`\nProject created at ${fullPath}`);
+    console.log(`Recorded template pin in ${join(dirName, PROJECT_MANIFEST_RELPATH)}`);
+    console.log("\nNext steps:");
+    console.log(`  summer run ${dirName}`);
+    if (scaffolded) {
+        const script = join(dirName, "tests", "autopilot", "run.sh");
+        const hint = process.platform === "win32" ? `bash ${script}   (Git Bash or WSL;` : `bash ${script}   (`;
+        console.log(`  ${hint}${AUTOPILOT_NEXT_STEP_HINT})`);
+    }
+    console.log("  Ask your agent to use the brainstorm-game skill to create .summer/GameSoul.md");
+}
+function describeTemplates(entries, out) {
+    const builtins = entries.filter((e) => e.builtin);
+    const pinned = entries.filter((e) => !e.builtin && e.status !== "deprecated");
+    const pad = Math.max(16, ...entries.map((e) => e.slug.length));
+    out("Built-in templates (generated locally, no download):");
+    for (const t of builtins)
+        out(`  ${t.slug.padEnd(pad)}  ${t.summary}`);
+    out("\nPinned templates (exact commit, verified tree digest):");
+    for (const t of pinned) {
+        const flag = t.status === "preview" ? " [preview]" : "";
+        out(`  ${t.slug.padEnd(pad)}  ${t.summary}${flag}`);
+    }
+    out('\nRun "summer list templates" for details.');
+}
+export const createCommand = new Command("create")
+    .description("Create a new Summer Engine project from a library template. Built-in templates generate offline; pinned templates fetch exactly the reviewed commit and verify its tree digest.")
+    .argument("<template>", 'Template slug (or legacy alias / unambiguous prefix). See "summer list templates".')
+    .argument("[name]", "Project directory name (defaults to template slug)")
+    .option("--keep-git", "Keep the fetched .git directory, detached at the pinned commit (default: remove it so you start fresh)")
+    .action(async (templateName, projectName, options) => {
+    const entries = getTemplateRegistry();
+    const resolution = resolveTemplate(templateName, entries);
+    if (resolution.kind === "none") {
+        console.error(`No template matches '${templateName}'.\n`);
+        describeTemplates(entries, (l) => console.error(l));
+        process.exit(1);
+    }
+    if (resolution.kind === "ambiguous") {
+        console.error(`'${templateName}' is ambiguous. Did you mean one of:`);
+        for (const c of resolution.candidates)
+            console.error(`  ${c.slug}`);
+        process.exit(1);
+    }
+    const entry = resolution.entry;
+    if (resolution.via === "alias" || resolution.via === "prefix") {
+        console.log(`Resolved '${templateName}' -> ${entry.slug}`);
+    }
+    const dirName = projectName || entry.slug;
+    const fullPath = resolve(dirName);
+    if (existsSync(fullPath)) {
+        console.error(`Directory already exists: ${fullPath}`);
+        process.exit(1);
+    }
+    if (entry.status !== "stable") {
+        console.error(`Warning: ${entry.slug} is marked '${entry.status}'.`);
+        for (const note of entry.do_not_use_when)
+            console.error(`  ${note}`);
+    }
+    if (entry.builtin) {
+        const generate = BUILTIN_GENERATORS[entry.slug];
+        if (!generate) {
+            console.error(`${entry.id} is declared builtin but this CLI has no generator for it. Update the CLI.`);
+            process.exit(1);
+        }
+        console.log(`Creating project from built-in '${entry.slug}' template...`);
+        mkdirSync(fullPath, { recursive: true });
+        generate(fullPath, dirName);
+        const scaffolded = scaffoldAutopilot(fullPath);
+        writeProjectManifest(fullPath, {
+            template: { id: entry.id, version: entry.version, builtin: true },
+            toolkit_version: toolkitVersion,
+            engine_version: await detectEngineVersion(),
+        });
+        printNextSteps(fullPath, dirName, scaffolded);
+        return;
+    }
+    const pin = entry.pin;
+    let materialized;
+    try {
+        materialized = materializePinnedTemplate(entry, {
+            targetDir: fullPath,
+            keepGit: options.keepGit,
+            log: (line) => console.log(line),
+        });
+    }
+    catch (err) {
+        console.error(err instanceof TemplateDigestMismatchError ? err.message : err.message);
+        process.exit(1);
+    }
+    const scaffolded = scaffoldAutopilot(fullPath);
+    writeProjectManifest(fullPath, {
+        template: {
+            id: entry.id,
+            version: entry.version,
+            repo: pin.repo,
+            commit: materialized.commit,
+            tree_digest: materialized.tree_digest,
+        },
+        toolkit_version: toolkitVersion,
+        engine_version: await detectEngineVersion(),
+    });
+    console.log(`Source: ${pin.repo} @ ${materialized.commit.slice(0, 12)} (tree digest verified)`);
+    printNextSteps(fullPath, dirName, scaffolded);
+});
+/**
+ * project.godot uses C-style double-quoted strings; a project name containing
+ * `"` or `\` must be escaped or the file does not parse.
+ */
+export function escapeGodotString(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\r?\n/g, "\\n");
+}
+export function renderProjectSettings(name, mainScene) {
+    return `; Summer Engine Project
+; Generated by summer-engine CLI
+; Technical base ${SUMMER_ENGINE_COMPATIBILITY.currentTechnicalBaseVersion}; Summer follows upstream continuously
+
+[application]
+
+config/name="${escapeGodotString(name)}"
+run/main_scene="${escapeGodotString(mainScene)}"
+config/features=PackedStringArray("${SUMMER_ENGINE_COMPATIBILITY.projectFeatureTag}")
+
+[rendering]
+
+renderer/rendering_method="forward_plus"
+`;
+}
+function emptyScene() {
+    return `[gd_scene format=3]
+
+[node name="World" type="Node3D"]
+`;
+}
+function basicScene3D() {
+    return `[gd_scene load_steps=4 format=3]
+
+[sub_resource type="BoxMesh" id="BoxMesh_floor"]
+size = Vector3(20, 0.2, 20)
+
+[sub_resource type="StandardMaterial3D" id="StandardMaterial3D_floor"]
+albedo_color = Color(0.4, 0.45, 0.4, 1)
+
+[sub_resource type="ProceduralSkyMaterial" id="ProceduralSkyMaterial_sky"]
+
+[node name="World" type="Node3D"]
+
+[node name="Camera3D" type="Camera3D" parent="."]
+transform = Transform3D(1, 0, 0, 0, 0.939693, 0.34202, 0, -0.34202, 0.939693, 0, 5, 10)
+
+[node name="DirectionalLight3D" type="DirectionalLight3D" parent="."]
+transform = Transform3D(1, 0, 0, 0, 0.866025, 0.5, 0, -0.5, 0.866025, 0, 8, 0)
+shadow_enabled = true
+
+[node name="Floor" type="MeshInstance3D" parent="."]
+mesh = SubResource("BoxMesh_floor")
+surface_material_override/0 = SubResource("StandardMaterial3D_floor")
+
+[node name="WorldEnvironment" type="WorldEnvironment" parent="."]
+`;
+}

package/dist/{commands → cli/commands}/debug.js

@@ -1,6 +1,6 @@
 import { Command } from "commander";
-import { createDebugReportArtifact, redactDebugReport } from "../lib/debug-report.js";
-import { c, sym, tildeify } from "../lib/format.js";
+import { createDebugReportArtifact, redactDebugReport } from "../../core/capabilities/debug-report.js";
+import { c, sym, tildeify } from "../../core/format.js";
 function parsePositiveInt(value, fallback) {
     if (!value)
         return fallback;

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

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const doctorCommand: Command;

package/dist/cli/commands/doctor.js

@@ -0,0 +1,18 @@
+import { Command } from "commander";
+import { runDoctor } from "../../core/capabilities/doctor.js";
+import { brandLine } from "../../core/format.js";
+import { TOOLKIT_VERSION as version } from "../../core/version.js";
+export const doctorCommand = new Command("doctor")
+    .description("Diagnose Node, login, engine, project memory, local API, and MCP registration")
+    .option("--json", "Print diagnostics as JSON")
+    .action(async (opts) => {
+    if (!opts.json) {
+        console.log("");
+        console.log(brandLine(version));
+        console.log("");
+    }
+    const result = await runDoctor({ json: Boolean(opts.json) });
+    if (!result.ok) {
+        process.exit(1);
+    }
+});