summer-engine 2.5.0 → 2.6.0

package/README.md

@@ -1,10 +1,10 @@
-# Summer Engine — the AI game engine
+# Summer Engine: the AI game engine
 
 Build real 2D and 3D games through conversation. No coding required. Export to Steam, desktop, mobile, and web. Built on the Godot team's work, customized and honed so AI agents and humans can collaborate on great games.
 
-**Summer** is the open-source plugin that connects your AI coding agent to Summer Engine. MIT licensed. First-class setup works in Claude Code, Cursor, Codex, Windsurf, Cline, Roo Code, Gemini CLI, GitHub Copilot CLI, GitHub Copilot in VS Code, and OpenCode. Factory Droid uses the plugin marketplace path.
+**Summer** is the MIT open-source agent layer that connects your AI coding agent to Summer Engine: CLI, MCP server, skills, hooks, and plugin manifests. First-class setup works in Claude Code, Cursor, Codex, Windsurf, Cline, Roo Code, Gemini CLI, GitHub Copilot CLI, GitHub Copilot in VS Code, and OpenCode. Factory Droid uses the plugin marketplace path.
 
-- **Source:** [github.com/SummerEngine/summer](https://github.com/SummerEngine/summer)
+- **Source:** [github.com/SummerEngine/summer-engine-agent](https://github.com/SummerEngine/summer-engine-agent)
 - **Docs:** [summerengine.com/docs](https://summerengine.com/docs)
 - **MCP setup:** [summerengine.com/mcp](https://summerengine.com/mcp)
 
@@ -12,7 +12,7 @@ It just works. Open your agent, say *"let's make an FPS in Summer Engine,"* and
 
 ---
 
-## Get started — one prompt
+## Get started: one prompt
 
 Open your AI agent (Claude Code, Cursor, Codex, Copilot, Windsurf, etc.) and paste:
 
@@ -22,8 +22,8 @@ That's it. The agent reads this README, detects what's already on your machine,
 
 The first run will:
 1. Install the `summer-engine` npm package (~3 MB) if it's not on `PATH`.
-2. Drop 60 skills into `~/.claude/skills/` (or your agent's user-skill directory) so the agent loads them next session.
-3. Download the Summer Engine app (~1 GB — bundles the engine binary plus Git and other runtime tools so users without them aren't blocked) if it's not installed.
+2. Install Summer's game-dev skills into `~/.claude/skills/` (or your agent's user-skill directory) so the agent loads them next session.
+3. Download the Summer Engine app (~1 GB, including the engine binary, Git, and other runtime tools so users without them aren't blocked) if it's not installed.
 4. Open your browser for one-click sign-in.
 5. Scaffold a starter project and open the engine.
 
@@ -31,19 +31,19 @@ At that point the agent has the skills, the MCP server, and your engine running.
 
 ---
 
-## AGENTS READING THIS — the install playbook
+## AGENTS READING THIS: install playbook
 
-You are an AI coding agent. The user told you to install Summer Engine. **Run this playbook via your shell** — Bash on macOS/Linux or PowerShell on Windows; `npx -y` is shell-agnostic and works identically in both. Detection first, then only install what's missing — never double-install.
+You are an AI coding agent. The user told you to install Summer Engine. **Run this playbook via your shell**: Bash on macOS/Linux or PowerShell on Windows. `npx -y` is shell-agnostic and works identically in both. Detection first, then only install what's missing.
 
-### Step −1 — Verify Node.js is on PATH
+### Step -1: Verify Node.js is on PATH
 
 ```bash
 node --version
 ```
 
-If this fails or returns a version below 18, **stop**. Tell the user: "Summer needs Node.js 18+. Install from https://nodejs.org and re-run the prompt." Do NOT try to install Node yourself.
+If this command does not print Node.js 18 or newer, **stop**. Tell the user: "Summer needs Node.js 18+. Install from https://nodejs.org and re-run the prompt." Do NOT try to install Node yourself.
 
-### Step 0 — Pre-detection (no commits to disk, just check state)
+### Step 0: Pre-detection (no commits to disk, just check state)
 
 ```bash
 npx -y summer-engine@latest doctor --json
@@ -51,29 +51,14 @@ npx -y summer-engine@latest doctor --json
 
 The first invocation downloads the npm package transparently to npx's cache (~3 MB, ~5 sec). Subsequent calls are fast. The `-y` flag auto-confirms npx's "ok to install summer-engine?" prompt so the call doesn't hang in a non-interactive shell.
 
-Parse the JSON output. Top-level `ok: true` means everything is installed and you can skip straight to Step 5. Otherwise iterate the `checks` array and skip any step whose check returned `status: "ok"`:
-
-```json
-{
-  "ok": true | false,
-  "checks": [
-    { "id": "node-version",        "status": "ok" | "warning" | "fail", ... },
-    { "id": "cli-version",         "status": "ok" | "warning" | "fail", ... },
-    { "id": "cli-version-current", "status": "ok" | "warning" | "fail", ... },
-    { "id": "skills-version-stale","status": "ok" | "warning" | "fail", ... },
-    { "id": "login",               "status": "ok" | "warning" | "fail", ... },
-    { "id": "engine-install",      "status": "ok" | "warning" | "fail", ... },
-    { "id": "local-api",           "status": "ok" | "warning" | "fail", ... },
-    { "id": "project-memory",      "status": "ok" | "warning" | "fail", ... },
-    { "id": "mcp-server",          "status": "ok" | "warning" | "fail", ... }
-  ]
-}
-```
+Read the JSON output. If top-level `ok` is `true`, everything is installed and you can skip straight to Step 5. Otherwise use the `checks` array to run only the remediation steps that need attention.
+
+The relevant check ids are `node-version`, `cli-version`, `cli-version-current`, `skills-version-stale`, `login`, `engine-install`, `local-api`, `project-memory`, and `mcp-server`. For any check that is not `ok`, run the action in the table below, then re-run doctor.
 
-| Check id | If `ok` | If not `ok` |
+| Check id | If `ok` | Action when attention is needed |
 |---|---|---|
-| `node-version` | continue | (Step −1 already covered this) |
-| `cli-version` | (always ok via npx) | — |
+| `node-version` | continue | Step -1 already covered this |
+| `cli-version` | always ok via npx | no action |
 | `cli-version-current` | continue | run `npx clear-npx-cache && npx -y summer-engine@latest doctor --json` (forces a fresh resolve) |
 | `skills-version-stale` | skip Step 1 | run Step 1 with `--force` |
 | `engine-install` | skip Step 2 | run Step 2 |
@@ -82,55 +67,55 @@ Parse the JSON output. Top-level `ok: true` means everything is installed and yo
 | `project-memory` | continue | if a project is open, run `summer:brainstorm-game` before building |
 | `mcp-server` | skip Step 1 | run Step 1 |
 
-**On version drift:** if either `cli-version-current` or `skills-version-stale` returns `warning` or `fail`, you should refresh before proceeding. Tell the user once: "There's a newer Summer (X.Y.Z → A.B.C); updating before we start." Then run the recommended action from `details.recommendedAction` and re-run doctor. Don't ask the user to choose — they paste 'install' and want the latest.
+**On version drift:** if either `cli-version-current` or `skills-version-stale` needs attention, refresh before proceeding. Tell the user once: "There's a newer Summer (X.Y.Z to A.B.C); updating before we start." Then run the recommended action from `details.recommendedAction` and re-run doctor. Don't ask the user to choose; they paste "install" and want the latest.
 
-### Step 1 — Install user-level skills (idempotent, fast)
+### Step 1: Install user-level skills (idempotent, fast)
 
 ```bash
 npx -y summer-engine@latest setup claude-code --yes --force
 ```
 
-Replace `claude-code` with the user's actual agent: `codex`, `cursor`, `windsurf`, `cline`, `roo-code`, `gemini`, `github-copilot`, `vscode-copilot`, or `opencode`. Use `github-copilot` for Copilot CLI and `vscode-copilot` for GitHub Copilot Chat/Agent in VS Code. Factory Droid still uses the plugin marketplace path in the install section below. This writes 60 skill files to `~/.claude/skills/<name>/SKILL.md` (or the agent's equivalent user-skill directory) AND writes the MCP server config so the agent can talk to the engine. The `--force` flag wipes any stale skill content first, so re-runs always end up with the latest copy.
+Replace `claude-code` with the user's actual agent: `codex`, `cursor`, `windsurf`, `cline`, `roo-code`, `gemini`, `github-copilot`, `vscode-copilot`, or `opencode`. Use `github-copilot` for Copilot CLI and `vscode-copilot` for GitHub Copilot Chat/Agent in VS Code. Factory Droid still uses the plugin marketplace path in the install section below. This writes the current Summer skill bundle to `~/.claude/skills/<name>/SKILL.md` (or the agent's equivalent user-skill directory) AND writes the MCP server config so the agent can talk to the engine. The `--force` flag wipes any stale skill content first, so re-runs always end up with the latest copy.
 
-**First-install detection:** if `~/.claude/skills/` didn't exist before this command, Claude Code wasn't watching it and won't auto-detect the new files this session. Tell the user **once**: "Skills installed — restart your agent so they load." On subsequent installs (directory already existed), skills auto-detect mid-session and no restart is needed. **You can detect first-install vs upgrade by checking if `~/.claude/skills/` existed before Step 1; record the result before running setup.**
+**First-install detection:** if `~/.claude/skills/` didn't exist before this command, Claude Code wasn't watching it and won't auto-detect the new files this session. Tell the user **once**: "Skills installed - restart your agent so they load." On subsequent installs (directory already existed), skills auto-detect mid-session and no restart is needed. **You can detect first-install vs upgrade by checking if `~/.claude/skills/` existed before Step 1; record the result before running setup.**
 
 **Do NOT run `/plugin install` or any slash command.** The CLI path is the canonical install. The marketplace path is an alternative for users who specifically prefer the official plugin TUI; we don't route agents there.
 
-### Step 2 — Install the engine app (only if `engine-install` check failed)
+### Step 2: Install the engine app (only if `engine-install` needs attention)
 
 ```bash
 npx -y summer-engine@latest install
 ```
 
-~1 GB. Downloads from Summer's signed releases. The bundle includes the engine binary plus Git and a handful of other runtime tools so users who don't already have them aren't blocked. The CLI prints the URL and size before touching disk. Tell the user **"downloading the engine app, ~1 GB — this takes a couple minutes"** so they don't bail thinking it stalled.
+~1 GB. Downloads from Summer's signed releases. The bundle includes the engine binary plus Git and a handful of other runtime tools so users who don't already have them aren't blocked. The CLI prints the URL and size before touching disk. Tell the user **"downloading the engine app, ~1 GB, this takes a couple minutes"** so they don't bail thinking it stalled.
 
-**Linux note:** the engine app currently supports macOS and Windows only. On Linux, `summer install` exits with a "Linux support coming soon" message. Surface the manual download URL to the user (https://summerengine.com/download) and stop — the rest of the playbook still works once they've installed manually.
+**Linux note:** the engine app currently supports macOS and Windows only. On Linux, `summer install` exits with a "Linux support coming soon" message. Surface the manual download URL to the user (https://summerengine.com/download) and stop. The rest of the playbook still works once they've installed manually.
 
-### Step 3 — Sign in (only if `login` check failed)
+### Step 3: Sign in (only if `login` needs attention)
 
 ```bash
 npx -y summer-engine@latest login
 ```
 
-This opens the user's default browser. **Tell the user**: "Your browser is opening now. Click sign-in once and come back to this terminal." The CLI waits up to 120 seconds for the auth callback, writes the token to `~/.summer/auth-token`, and returns. **If the user takes longer than 120s, the command exits with an error — just re-run `npx -y summer-engine@latest login` and tell them to be quicker.** Don't loop indefinitely. The same token is shared with the engine — they sign in once, both surfaces accept it.
+This opens the user's default browser. **Tell the user**: "Your browser is opening now. Click sign-in once and come back to this terminal." The CLI waits up to 120 seconds for the auth callback, writes the token to `~/.summer/auth-token`, and returns. **If the user takes longer than 120 seconds, re-run `npx -y summer-engine@latest login` and tell them to come back to the terminal quickly.** Don't loop indefinitely. The same token is shared with the engine; they sign in once, both surfaces accept it.
 
-### Step 4 — Re-run doctor to confirm
+### Step 4: Re-run doctor to confirm
 
 ```bash
 npx -y summer-engine@latest doctor --json
 ```
 
-Should now return `ok: true` for `cli-version`, `login`, and `engine-install`. (`local-api` will still be `warning` — that's expected; the engine isn't running yet.) If a setup check still fails, surface the specific message to the user — don't loop or paper over it.
+Should now return `ok: true` for `cli-version`, `login`, and `engine-install`. `local-api` may still need attention because the engine is not running yet. If a setup check still needs attention, surface the specific message to the user and do not loop or paper over it.
 
-### Step 5 — Scaffold a project and run
+### Step 5: Scaffold a project and run
 
-**Important:** `summer create` writes the project into the current working directory. **Pick a stable parent directory first** — the user's home, a Projects folder, etc. — and `cd` there before running `create`. Don't let it land in a temp dir or wherever the agent happened to start.
+**Important:** `summer create` writes the project into the current working directory. **Pick a stable parent directory first**, such as the user's home or a Projects folder, and `cd` there before running `create`. Don't let it land in a temp dir or wherever the agent happened to start.
 
 ```bash
 cd ~/Projects   # or wherever the user keeps code
 ```
 
-If the user said "let's make a game" without specifying a template, default to `3d-basic`. Pick a sensible project name from the user's request (e.g. "FPS" → `my-fps-game`). Avoid spaces in the name.
+If the user said "let's make a game" without specifying a template, default to `3d-basic`. Pick a sensible project name from the user's request, for example "FPS" to `my-fps-game`. Avoid spaces in the name.
 
 ```bash
 npx -y summer-engine@latest create 3d-basic my-fps-game
@@ -139,9 +124,9 @@ npx -y summer-engine@latest run my-fps-game
 
 `summer run` launches the engine app with the project loaded and polls the engine's local API for up to 20 seconds before returning.
 
-### Step 5b — Wait for the engine to be reachable (only if `summer run` printed "API not responding yet")
+### Step 5b: Wait for the engine to be reachable (only if `summer run` printed "API not responding yet")
 
-If the engine takes longer than 20s to boot (cold start, slow disk, etc.), `summer run` returns successfully but the local API isn't up yet. Calling `summer_get_scene_tree` or any other MCP tool will fail. Wait for it:
+If the engine takes longer than 20s to boot (cold start, slow disk, etc.), `summer run` returns successfully but the local API isn't up yet. MCP tools may not connect until the local API is ready. Wait for it:
 
 ```bash
 # Poll doctor until local-api flips to ok (max ~30s):
@@ -156,9 +141,9 @@ done
 
 Once `local-api` is `ok`, MCP tools are safe to call.
 
-### Step 6 — Brainstorm the game, then build
+### Step 6: Brainstorm the game, then build
 
-Now you have skills + MCP. **Don't jump into `summer create` content from a vague prompt** — invoke the `summer:brainstorm-game` skill via the `Skill` tool first. It scopes mechanics, art direction, and the V1 cut list, and writes the result to `.summer/GameSoul.md`. Every other Summer skill reads from that file.
+Now you have skills + MCP. **Don't jump into `summer create` content from a vague prompt**. Call `summer_start_game_task` with the user's goal, then invoke the recommended skill. For vague "make a game" requests, that should usually be `summer:brainstorm-game`. It scopes mechanics, art direction, and the V1 cut list, and writes the result to `.summer/GameSoul.md`. Every other Summer skill reads from that file.
 
 Project memory lives in `.summer/` as readable Markdown. Use `.summer/memory/` for locked facts that should not drift across sessions, such as character voice IDs, world canon, and provider bindings. Users can inspect it with `summer memory`; agents should read relevant memory surfaced by `summer_get_project_context` before changing creative/audio/dialogue/level/character work.
 
@@ -166,15 +151,15 @@ Only skip brainstorm if the user explicitly said "skip brainstorm" or "just buil
 
 ### Anti-patterns (do NOT do these)
 
-- **Don't run `npm install -g summer-engine`.** Use `npx -y summer-engine@latest ...` instead. `-g` requires `sudo` on most Mac/Linux setups — the user will get permission errors and you'll get stuck. `npx` works without root and the MCP config we ship already points at `npx summer-engine mcp`.
-- **Don't try to install Node.js for the user.** If `node --version` fails, point them at https://nodejs.org and stop.
-- **Don't ask the user "do you want the engine too?" or "do you also want the CLI?"** — there is one product, three pieces, all installed by this playbook.
+- **Don't run `npm install -g summer-engine`.** Use `npx -y summer-engine@latest ...` instead. `-g` requires `sudo` on most Mac/Linux setups, so the user will get permission errors and you'll get stuck. `npx` works without root and the MCP config we ship already points at `npx summer-engine mcp`.
+- **Don't try to install Node.js for the user.** If `node --version` is unavailable, point them at https://nodejs.org and stop.
+- **Don't ask the user "do you want the engine too?" or "do you also want the CLI?"** There is one product, three pieces, all installed by this playbook.
 - **Don't double-install.** Always run `npx -y summer-engine@latest doctor --json` first. Skip steps that already returned `status: ok`.
-- **Don't tell the user to type `/plugin marketplace add` or `/plugin install`.** The CLI path is the canonical install — those slash commands are an alternative for the marketplace TUI, not the primary flow.
+- **Don't tell the user to type `/plugin marketplace add` or `/plugin install`.** The CLI path is the canonical install. Those slash commands are an alternative for the marketplace TUI, not the primary flow.
 - **Don't run `summer install` or `summer login` in the background.** They print user-facing output (engine download progress, browser-opening notice). Run them in the foreground so the user sees what's happening.
-- **Don't skip the `--json` flag on `summer doctor`** — text output is fragile to parse and changes per version.
-- **Don't skip the `-y` flag on `npx`** — without it, npx prompts "ok to install summer-engine?" interactively and the call hangs in a non-interactive shell.
-- **Don't drop `@latest` from the npx commands.** `npx -y summer-engine` (no version pin) serves whatever's in npx's local cache, which can be a stale older version. The `@latest` tag forces npm to re-resolve from the registry. If a user reports "unknown command 'doctor'" or sees a much smaller skill list than expected, they got cache-served — tell them to run `npx clear-npx-cache` then retry with `@latest`.
+- **Don't skip the `--json` flag on `summer doctor`.** Text output is fragile to parse and changes per version.
+- **Don't skip the `-y` flag on `npx`.** Without it, npx prompts "ok to install summer-engine?" interactively and the call hangs in a non-interactive shell.
+- **Don't drop `@latest` from the npx commands.** `npx -y summer-engine` (no version pin) serves whatever's in npx's local cache, which can be a stale older version. The `@latest` tag forces npm to re-resolve from the registry. If a user reports "unknown command 'doctor'" or sees a much smaller skill list than expected, they got cache-served. Tell them to run `npx clear-npx-cache` then retry with `@latest`.
 - **Don't call MCP tools (`summer_get_scene_tree`, etc.) until `local-api` is `ok`.** The engine takes a few seconds to boot after `summer run`. Use Step 5b's wait-loop.
 - **Don't `summer create` without `cd`'ing to a stable parent directory first.** It writes into CWD; agents that start in a temp dir will leave the project there.
 - **Don't loop `summer login` if it times out at 120s.** Re-run it once and tell the user to be quicker; loop forever and the user is stuck.
@@ -186,12 +171,12 @@ Only skip brainstorm if the user explicitly said "skip brainstorm" or "just buil
 
 ---
 
-## Get started — alternative (manual install via plugin marketplace)
+## Get started: alternative manual install via plugin marketplace
 
 If you specifically prefer the official Claude Code plugin marketplace UI, you can install via:
 
 ```
-/plugin marketplace add SummerEngine/summer
+/plugin marketplace add SummerEngine/summer-engine-agent
 /plugin install summer@summer-engine
 ```
 
@@ -201,13 +186,13 @@ This is functionally equivalent to `npx -y summer-engine@latest setup claude-cod
 
 ## What just happened (the three pieces)
 
-You installed one product. It has three parts. You don't have to think about them — Summer wires them up — but here's what each does:
+You installed one product. It has three parts. You don't have to think about them because Summer wires them up, but here's what each does:
 
-- **Summer Engine** — the game engine app. Where you see, play, and debug your game. Installed by the agent via `npx -y summer-engine@latest install`. Proprietary, free to use.
-- **Summer plugin** — what Claude Code (or your agent) uses to know what game-dev skills to apply and which tools to call. Installed by `summer setup` or the marketplace path. MIT, open source.
-- **Summer CLI** — the terminal command layer that installs the engine, scaffolds projects, runs them, signs you in, and starts MCP. Usually invoked through `npx -y summer-engine@latest ...`, so no global install is needed. MIT, open source.
+- **Summer Engine**: the game engine app. Where you see, play, and debug your game. Installed by the agent via `npx -y summer-engine@latest install`. Proprietary, free to use.
+- **Summer agent layer**: the skills, hooks, and plugin manifests that tell Claude Code, Codex, Cursor, and other agents how to build games. Installed by `summer setup` or the marketplace path. MIT, open source.
+- **Summer CLI and MCP bridge**: the terminal command and local tool server that install the engine, scaffold projects, run them, sign you in, and let agents talk to the running engine. Usually invoked through `npx -y summer-engine@latest ...`, so no global install is needed. MIT, open source.
 
-The plugin gives the agent the skills. The CLI gives it hands to install and launch the engine. The engine is where the game actually lives.
+The agent layer gives the agent judgment. The CLI and MCP bridge give it hands. The engine is where the game actually lives.
 
 ---
 
@@ -219,7 +204,7 @@ We tell you before we touch your disk.
 |---|---|---|---|
 | `summer-engine` npm package (CLI + plugin source) | ~3 MB | first `npx -y summer-engine@latest ...` call | [npmjs.com/package/summer-engine](https://www.npmjs.com/package/summer-engine) |
 | Summer Engine app | ~1 GB (engine + bundled Git/runtime tools) | `npx -y summer-engine@latest install` | Summer's signed releases |
-| Auth token | ~1 KB | `npx -y summer-engine@latest login` | Browser → `~/.summer/auth-token` |
+| Auth token | ~1 KB | `npx -y summer-engine@latest login` | Browser to `~/.summer/auth-token` |
 | Skill files | < 50 KB | bundled in the npm package | no extra network call |
 | Generated assets (3D / image / audio / video) | varies | only on explicit `summer_generate_*` calls | Summer Engine Studio |
 | URL imports | varies | only on explicit `summer_import_from_url` calls | the URL you provide |
@@ -235,11 +220,11 @@ Not downloaded:
 
 | Thing | License | Source |
 |---|---|---|
-| **Summer** (this repo: skills, MCP server, CLI, hooks, plugin manifests) | **MIT** | [SummerEngine/summer](https://github.com/SummerEngine/summer) |
-| **Summer Engine** (the engine binary, editor, runtime) | proprietary, free to use | [summerengine.com/download](https://summerengine.com/download) |
-| **Summer Engine Studio** (asset generation, cloud) | proprietary, paid plans | [summerengine.com/pricing](https://summerengine.com/pricing) |
+| **Summer** (this repo: CLI, MCP server, skills, hooks, plugin manifests) | **MIT** | [SummerEngine/summer-engine-agent](https://github.com/SummerEngine/summer-engine-agent) |
+| **Summer Engine app** (the desktop editor and runtime) | free to download, closed source for now | [summerengine.com/download](https://summerengine.com/download) |
+| **Hosted Summer AI and cloud services** (asset generation, storage, multiplayer, orchestration) | paid Summer services | [summerengine.com/pricing](https://summerengine.com/pricing) |
 
-The engine is the moat. The agent layer is open so you can audit it, fork it, extend the skills, and contribute back.
+The desktop app is free to download. The AI-agent layer, meaning the CLI, MCP server, skills, and plugin manifests, is MIT open source. Hosted Summer AI, asset generation, storage, multiplayer, and cloud features are paid Summer services.
 
 ---
 
@@ -247,29 +232,29 @@ The engine is the moat. The agent layer is open so you can audit it, fork it, ex
 
 Two pieces, plus the glue.
 
-**Skills.** Twenty-four markdown files. Each one is a discipline guide for the agent. They auto-fire on natural language:
+**Skills.** A bundled set of markdown playbooks. Each one is a discipline guide for the agent. They auto-fire on natural language:
 
-- "Let's brainstorm a game" → `summer:brainstorm-game`
-- "It crashes when I press play" → `summer:debug`
-- "Add an FPS controller" → `summer:fps-controller`
-- "Make it look prettier" → `summer:art-direction`
-- "Set up multiplayer" → `summer:setup-multiplayer` → `summer:host-authoritative-state`
+- "Let's brainstorm a game" -> `summer:brainstorm-game`
+- "It crashes when I press play" -> `summer:debug`
+- "Add an FPS controller" -> `summer:fps-controller`
+- "Make it look prettier" -> `summer:art-direction`
+- "Set up multiplayer" -> `summer:setup-multiplayer` -> `summer:host-authoritative-state`
 
 Skills don't list steps. They encode the **order of operations**: diagnose before editing, scope before building, ask before guessing. [Agent Skills](https://agentskills.io) format, so any conformant tool picks them up.
 
-**MCP bridge.** The `summer-engine` MCP server gives the agent 37 tools that talk to your local engine on `localhost:6550`:
+**MCP bridge.** The `summer-engine` MCP server gives the agent 44 tools that talk to your local engine on `localhost:6550`:
 
 | | |
 |---|---|
-| Scene | `summer_add_node`, `summer_set_prop`, `summer_replace_node`, `summer_get_scene_tree`, `summer_inspect_node`, `summer_batch` |
-| Diagnostics | `summer_get_script_errors`, `summer_get_diagnostics`, `summer_get_console`, `summer_get_debugger_errors` |
+| Scene | `summer_add_node`, `summer_set_prop`, `summer_instantiate_scene`, `summer_replace_node`, `summer_get_scene_tree`, `summer_inspect_node`, `summer_batch` |
+| Diagnostics | `summer_get_script_errors`, `summer_get_diagnostics`, `summer_get_console`, `summer_get_debugger_errors`, `summer_get_debugger_warnings` |
 | Runtime | `summer_play`, `summer_stop`, `summer_is_running` |
 | Project | `summer_get_project_context`, `summer_open_main_scene`, `summer_project_setting`, `summer_input_map_bind` |
 | Assets | `summer_search_assets`, `summer_import_asset`, `summer_import_from_url`, `summer_generate_image`, `summer_generate_3d`, `summer_generate_audio`, `summer_generate_video` |
 
-File ops, git, shell, grep — your agent already has those. We don't shadow them.
+File ops, git, shell, and grep already belong to your agent. We don't shadow them.
 
-**Lifecycle hooks.** A `session-start` hook detects whether you're in a Summer Engine project and feeds the agent a one-line orientation. An opt-in `pre-commit doctor` runs `summer doctor` before `git commit` and blocks on failure.
+**Lifecycle hooks.** A `session-start` hook detects whether you're in a Summer Engine project and feeds the agent a one-line orientation. An opt-in `pre-commit doctor` runs `summer doctor` before `git commit` and blocks when the setup needs attention.
 
 For the full architecture, see [docs/OVERVIEW.md](docs/OVERVIEW.md).
 
@@ -286,27 +271,27 @@ For the full architecture, see [docs/OVERVIEW.md](docs/OVERVIEW.md).
 7. **debug** runs the cheapest diagnostic, forms one specific hypothesis, asks before editing, re-verifies after the fix.
 8. **export-and-ship** runs the pre-flight checklist before producing a release build.
 
-Twenty-four skills replace "agent flailing through tutorials" with measurable craft.
+The skill bundle replaces "agent flailing through tutorials" with measurable craft.
 
 ---
 
 ## What's inside
 
-**Process** — `using-summer`, `brainstorm-game`, `debug`, `play`
+**Process**: `using-summer`, `brainstorm-game`, `debug`, `play`
 
-**Project setup** — `new-project`, `browse-templates`, `make-game`, `scene-composition`
+**Project setup**: `new-project`, `browse-templates`, `make-game`, `scene-composition`
 
-**Build** — `fps-controller`, `design-mechanic`, `design-level`, `design-npc`
+**Build**: `fps-controller`, `design-mechanic`, `design-level`, `design-npc`
 
-**Multiplayer** — `setup-multiplayer`, `host-authoritative-state`, `peer-to-peer-multiplayer`
+**Multiplayer**: `setup-multiplayer`, `host-authoritative-state`, `peer-to-peer-multiplayer`
 
-**Look & feel** — `art-direction`, `audio-direction`, `3d-lighting`, `vfx`, `ui-basics`
+**Look & feel**: `art-direction`, `audio-direction`, `3d-lighting`, `vfx`, `ui-basics`
 
-**Code & assets** — `gdscript-patterns`, `asset-strategy`
+**Code & assets**: `gdscript-patterns`, `asset-strategy`
 
-**Performance & ship** — `tune-performance`, `export-and-ship`
+**Performance & ship**: `tune-performance`, `export-and-ship`
 
-**Skill authoring** — `skill-create`, `skill-improve`, `skill-test`
+**Skill authoring**: `skill-create`, `skill-improve`, `skill-test`
 
 C# is supported by the engine. A `summer:csharp-patterns` skill is on the roadmap; for now write C# from Godot 4.5 docs.
 
@@ -322,12 +307,12 @@ Full list of shipping skills: the `skills:` array in [`.claude-plugin/plugin.jso
 
 ---
 
-## Install — full instructions per harness
+## Install: full instructions per harness
 
 ### Claude Code
 
 ```bash
-claude /plugin marketplace add SummerEngine/summer
+claude /plugin marketplace add SummerEngine/summer-engine-agent
 claude /plugin install summer@summer-engine
 ```
 
@@ -347,7 +332,7 @@ Search `summer`, install.
 
 ### Codex App
 
-Sidebar → **Plugins** → **Coding** → click `+` next to **Summer**.
+Sidebar to **Plugins** to **Coding**, then click `+` next to **Summer**.
 
 ### Cursor
 
@@ -360,7 +345,7 @@ Or search `summer` in the Cursor plugin marketplace.
 ### Factory Droid
 
 ```bash
-droid plugin marketplace add https://github.com/SummerEngine/summer
+droid plugin marketplace add https://github.com/SummerEngine/summer-engine-agent
 droid plugin install summer@summer-engine
 ```
 
@@ -378,7 +363,7 @@ Writes the MCP server config to VS Code's globalStorage for the Cline extension
 npx -y summer-engine@latest setup roo-code --yes
 ```
 
-Same shape as Cline (Roo Code is a Cline fork) — writes globalStorage MCP config and `.clinerules/` files. **Restart VS Code** afterward.
+Same shape as Cline (Roo Code is a Cline fork): writes globalStorage MCP config and `.clinerules/` files. **Restart VS Code** afterward.
 
 ### Gemini CLI
 
@@ -386,7 +371,7 @@ Same shape as Cline (Roo Code is a Cline fork) — writes globalStorage MCP conf
 npx -y summer-engine@latest setup gemini --yes
 ```
 
-Drops a Summer extension manifest at `~/.gemini/extensions/summer-engine/`. If the extension isn't auto-enabled on next launch, run `gemini extensions enable summer-engine`. The marketplace path (`gemini extensions install https://github.com/SummerEngine/summer`) still works for users who prefer it — both end up at the same place.
+Drops a Summer extension manifest at `~/.gemini/extensions/summer-engine/`. If the extension isn't auto-enabled on next launch, run `gemini extensions enable summer-engine`. The marketplace path (`gemini extensions install https://github.com/SummerEngine/summer-engine-agent`) still works for users who prefer it. Both end up at the same place.
 
 ### GitHub Copilot CLI
 
@@ -425,11 +410,12 @@ npx -y summer-engine@latest doctor
 
 | Command | What it does |
 |---|---|
-| `summer install` | Download Summer Engine. Transparent — prints URL + size first. |
+| `summer install` | Download Summer Engine. Prints URL and size first. |
 | `summer login` | Browser-based sign-in. |
 | `summer logout` | Clear auth tokens. |
 | `summer status` | Engine state, port, auth. |
 | `summer doctor` | Diagnose Node, login, engine, project memory, MCP. |
+| `summer plan <goal>` | Route a game-building goal into skills, MCP tools, gates, and verification. |
 | `summer memory` | Inspect project memory in `.summer`. |
 | `summer memory show <file>` | Print a project memory Markdown file. |
 | `summer run [path]` | Launch the engine. |
@@ -501,4 +487,4 @@ MIT for everything in this repo. Summer Engine itself is proprietary. See [What'
 - [Download Summer Engine](https://summerengine.com/download)
 - [Documentation](https://summerengine.com/docs)
 - [Community](https://summerengine.com/community)
-- [Issues](https://github.com/SummerEngine/summer/issues)
+- [Issues](https://github.com/SummerEngine/summer-engine-agent/issues)

package/dist/bin/summer.js

@@ -15,6 +15,8 @@ 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 { getBanner } from "../lib/banner.js";
 import { c, sym } from "../lib/format.js";
 const require = createRequire(import.meta.url);
@@ -40,7 +42,9 @@ program.addCommand(skillsCommand);
 program.addCommand(mcpCommand);
 program.addCommand(setupCommand);
 program.addCommand(doctorCommand);
+program.addCommand(planCommand);
 program.addCommand(orchestratorCommand);
+program.addCommand(cloudCommand);
 program.parseAsync().catch((err) => {
     console.error(err instanceof Error ? err.message : String(err));
     process.exit(1);
@@ -58,6 +62,7 @@ function printIntro(version) {
     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 memory`);
     console.log(`     ${c.dim("$")} npx -y summer-engine@latest doctor`);
     console.log("");
@@ -66,6 +71,6 @@ function printIntro(version) {
     console.log(`     ${c.brand("/play")}    ${c.dim("Run the game and report state")}`);
     console.log("");
     console.log(`     ${c.dim("Docs:")} https://summerengine.com/docs`);
-    console.log(`     ${c.dim("Source:")} https://github.com/SummerEngine/summer`);
+    console.log(`     ${c.dim("Source:")} https://github.com/SummerEngine/summer-engine-agent`);
     console.log("");
 }

package/dist/commands/cloud.d.ts

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

package/dist/commands/cloud.js

@@ -0,0 +1,80 @@
+import { Command } from "commander";
+import { cloudCheckpoints, cloudConflicts, cloudInit, cloudPull, cloudPush, cloudRestore, cloudStatus, } from "../lib/cloud/sync.js";
+export const cloudCommand = new Command("cloud").description("Sync Summer Engine projects with Summer Cloud");
+cloudCommand
+    .command("init")
+    .description("Enable Summer Cloud for this project")
+    .option("--project <path>", "Project root path")
+    .option("--json", "Print JSON")
+    .action(async (opts) => printResult(await cloudInit(opts), opts.json));
+cloudCommand
+    .command("status")
+    .description("Show Summer Cloud sync status")
+    .option("--project <path>", "Project root path")
+    .option("--json", "Print JSON")
+    .action(async (opts) => printResult(await cloudStatus(opts), opts.json));
+cloudCommand
+    .command("push")
+    .description("Push local project changes to Summer Cloud")
+    .option("--project <path>", "Project root path")
+    .option("--json", "Print JSON")
+    .option("--confirm-deletes", "Allow guarded cloud deletions")
+    .option("--bootstrap <choice>", "No-base bootstrap choice: keep-cloud, keep-local, merge")
+    .option("--adopt-path", "Accept that the project folder moved and update the recorded path")
+    .action(async (opts) => printResult(await cloudPush(opts), opts.json));
+cloudCommand
+    .command("pull")
+    .description("Pull Summer Cloud changes into this project")
+    .option("--project <path>", "Project root path")
+    .option("--json", "Print JSON")
+    .option("--bootstrap <choice>", "No-base bootstrap choice: keep-cloud, keep-local, merge")
+    .option("--adopt-path", "Accept that the project folder moved and update the recorded path")
+    .action(async (opts) => printResult(await cloudPull(opts), opts.json));
+cloudCommand
+    .command("restore")
+    .description("Restore a retained cloud version (new head, then pull) or a local pre-sync checkpoint")
+    .option("--version <number>", "Cloud version number to restore", Number)
+    .option("--checkpoint <stamp>", "Local checkpoint stamp or full ref (see: summer cloud checkpoints)")
+    .option("--project <path>", "Project root path")
+    .option("--json", "Print JSON")
+    .action(async (opts) => printResult(await cloudRestore(opts), opts.json));
+cloudCommand
+    .command("checkpoints")
+    .description("List local pre-sync checkpoints")
+    .option("--project <path>", "Project root path")
+    .option("--json", "Print JSON")
+    .action(async (opts) => printResult(await cloudCheckpoints(opts), opts.json));
+const conflictsCommand = new Command("conflicts").description("Inspect and recover Summer Cloud conflict sets");
+conflictsCommand
+    .command("list", { isDefault: true })
+    .description("List local Summer Cloud conflict sets")
+    .option("--project <path>", "Project root path")
+    .option("--json", "Print JSON")
+    .action(async (opts) => printResult(await cloudConflicts(opts), opts.json));
+conflictsCommand
+    .command("restore <path>")
+    .description("Restore a preserved conflict file back into the project as a fresh edit")
+    .option("--set <stamp>", "Conflict set stamp (defaults to the newest set containing the path)")
+    .option("--project <path>", "Project root path")
+    .option("--json", "Print JSON")
+    .action(async (restorePath, opts) => printResult(await cloudConflicts({ ...opts, restorePath }), opts.json));
+cloudCommand.addCommand(conflictsCommand);
+function printResult(result, json) {
+    if (json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(result.message);
+    if (result.projectId)
+        console.log(`Project: ${result.projectId}`);
+    if (result.version !== undefined)
+        console.log(`Version: ${result.version}`);
+    for (const notice of result.notices ?? []) {
+        console.log(`notice: ${notice}`);
+    }
+    if (result.details) {
+        for (const [key, value] of Object.entries(result.details)) {
+            console.log(`${key}: ${Array.isArray(value) ? value.length : String(value)}`);
+        }
+    }
+}

package/dist/commands/doctor.js

@@ -4,6 +4,7 @@ import { createRequire } from "node:module";
 import { platform } from "os";
 import { Command } from "commander";
 import { getAuthToken, getUserInfo } from "../lib/auth.js";
+import { isGitAvailable } from "../lib/cloud/checkpoint.js";
 import { checkEngineHealth, getApiPort, getApiToken } from "../lib/engine.js";
 import { brandLine, c, pad, sym, tildeify } from "../lib/format.js";
 import { getProjectMemorySummary } from "../lib/project-memory.js";
@@ -48,6 +49,7 @@ export async function runDoctor(options = {}) {
     checks.push(checkSkillsVersion());
     checks.push(await checkLogin());
     checks.push(checkEngineInstall());
+    checks.push(await checkGitForCheckpoints());
     checks.push(await checkLocalApi());
     checks.push(await checkProjectMemory());
     checks.push(await checkMcpBoot());
@@ -144,6 +146,23 @@ function checkEngineInstall() {
         message: "not installed (run: summer install)",
     };
 }
+async function checkGitForCheckpoints() {
+    const available = await isGitAvailable();
+    if (available) {
+        return {
+            id: "git",
+            label: "Git (cloud checkpoints)",
+            status: "ok",
+            message: "git found on PATH",
+        };
+    }
+    return {
+        id: "git",
+        label: "Git (cloud checkpoints)",
+        status: "warning",
+        message: "git not found; Summer Cloud sync needs git for pre-sync safety checkpoints",
+    };
+}
 async function checkLocalApi() {
     const token = await getApiToken();
     const port = await getApiPort();

package/dist/commands/login.js

@@ -1,7 +1,7 @@
 import { Command } from "commander";
 import { randomUUID } from "crypto";
 import open from "open";
-import { getAuthToken, saveAuthToken, saveUserInfo } from "../lib/auth.js";
+import { getAuthToken, saveAuthToken, saveCloudToken, saveUserInfo } from "../lib/auth.js";
 const GATEWAY_URL = process.env.SUMMER_GATEWAY_URL || "https://www.summerengine.com";
 const POLL_INTERVAL_MS = 2000;
 const POLL_TIMEOUT_MS = 120000;
@@ -52,6 +52,9 @@ async function doLogin() {
                 continue;
             if (data.status === "complete" && data.token) {
                 await saveAuthToken(data.token);
+                if (data.cloudToken) {
+                    await saveCloudToken(data.cloudToken);
+                }
                 if (data.user) {
                     await saveUserInfo(data.user);
                 }

package/dist/commands/logout.js

@@ -6,7 +6,7 @@ export const logoutCommand = new Command("logout")
     .description("Sign out and clear stored auth tokens")
     .action(async () => {
     const dir = getSummerDir();
-    const files = ["auth-token", "user.json"];
+    const files = ["auth-token", "cloud-token", "user.json"];
     let cleared = false;
     for (const file of files) {
         try {

package/dist/commands/open.js

@@ -28,5 +28,5 @@ export const openCommand = new Command("open")
     }
     console.log(`Opening project: ${fullPath}`);
     console.log("Note: To switch projects, close the current one in Summer Engine first,\n" +
-        "or run: summer run " + fullPath);
+        "then run: summer run " + fullPath);
 });