summer-engine 2.6.5 → 2.7.0

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
       "name": "summer",
       "source": "./",
       "version": "2.5.1",
-      "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 44-tool MCP bridge to the local desktop app.",
+      "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 50+ tool MCP bridge to the local desktop app.",
       "author": { "name": "Summer Engine", "email": "founders@summerengine.com" },
       "category": "game-development",
       "tags": ["game-dev", "godot", "ai-game-engine"],

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "summer",
   "version": "2.5.1",
-  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 52-tool MCP bridge to the local desktop app.",
+  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 56-tool MCP bridge to the local desktop app.",
   "author": {
     "name": "Summer Engine",
     "email": "founders@summerengine.com",
@@ -46,6 +46,7 @@
     "./skills/scene-and-project/browse-templates/",
     "./skills/scene-and-project/play/",
     "./skills/scene-and-project/scene-composition/",
+    "./skills/scene-and-project/summer-cloud/",
     "./skills/scene-and-project/make-game/",
     "./skills/debugging/debug/",
     "./skills/gameplay-mechanics/design-mechanic/",
@@ -62,6 +63,7 @@
     "./skills/multiplayer-and-networking/host-authoritative-state/",
     "./skills/multiplayer-and-networking/peer-to-peer-multiplayer/",
     "./skills/deployment/export-and-ship/",
+    "./skills/deployment/remote-deploy/",
     "./skills/character-controllers/fps-controller/",
     "./skills/scripting-patterns/gdscript-patterns/",
     "./skills/ui-and-ux/ui-basics/",

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "summer",
   "version": "2.5.1",
-  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 52-tool MCP bridge. Build games by talking.",
+  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 56-tool MCP bridge. Build games by talking.",
   "author": {
     "name": "Summer Engine",
     "email": "founders@summerengine.com",
@@ -35,6 +35,7 @@
     "./skills/scene-and-project/browse-templates/",
     "./skills/scene-and-project/play/",
     "./skills/scene-and-project/scene-composition/",
+    "./skills/scene-and-project/summer-cloud/",
     "./skills/scene-and-project/make-game/",
     "./skills/debugging/debug/",
     "./skills/gameplay-mechanics/design-mechanic/",
@@ -49,6 +50,7 @@
     "./skills/multiplayer-and-networking/host-authoritative-state/",
     "./skills/multiplayer-and-networking/peer-to-peer-multiplayer/",
     "./skills/deployment/export-and-ship/",
+    "./skills/deployment/remote-deploy/",
     "./skills/character-controllers/fps-controller/",
     "./skills/scripting-patterns/gdscript-patterns/",
     "./skills/ui-and-ux/ui-basics/",
@@ -59,6 +61,7 @@
     "./skills/2d-assets/ui-graphics/",
     "./skills/2d-assets/tileable-texture/",
     "./skills/2d-assets/sprite-sheet/",
+    "./skills/2d-assets/create-asset-sheet/",
     "./skills/2d-assets/skybox-panorama/",
     "./skills/3d-assets/prop-model/",
     "./skills/3d-assets/character-model/",
@@ -92,7 +95,7 @@
   "interface": {
     "displayName": "Summer",
     "shortDescription": "Superpowers for AI game dev. Build games by talking.",
-    "longDescription": "Summer turns Codex into a game-dev studio for Summer Engine, the AI-native game engine. It adds game-dev skills, a using-summer workflow skill, lifecycle hooks, and a 52-tool MCP bridge for scene editing, asset import, play mode, diagnostics, and generation. File, git, shell, and grep stay with the host agent. Summer Engine is compatible with Godot 4.5. Write code in GDScript and drive the engine through MCP. Session-start orients the session. Pre-commit doctor (opt-in) blocks bad commits.",
+    "longDescription": "Summer turns Codex into a game-dev studio for Summer Engine, the AI-native game engine. It adds game-dev skills, lifecycle hooks, and a 56-tool MCP bridge for guarded project files, scene editing, asset import, play mode, diagnostics, and generation. Git, shell, and grep stay with the host agent. Summer Engine is compatible with Godot 4.5. Write code in GDScript and drive project mutations through MCP. Session-start orients the session. Pre-commit doctor (opt-in) blocks bad commits.",
     "developerName": "Summer Engine",
     "category": "Coding",
     "capabilities": ["Interactive", "Read", "Write"],

package/.cursor-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "summer",
   "displayName": "Summer",
   "version": "2.5.1",
-  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 52-tool MCP bridge to the local desktop app.",
+  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 56-tool MCP bridge to the local desktop app.",
   "author": { "name": "Summer Engine", "email": "founders@summerengine.com" },
   "publisher": "summer-engine",
   "homepage": "https://summerengine.com",
@@ -37,6 +37,7 @@
     "./skills/scene-and-project/browse-templates/",
     "./skills/scene-and-project/play/",
     "./skills/scene-and-project/scene-composition/",
+    "./skills/scene-and-project/summer-cloud/",
     "./skills/scene-and-project/make-game/",
     "./skills/debugging/debug/",
     "./skills/gameplay-mechanics/design-mechanic/",
@@ -51,6 +52,7 @@
     "./skills/multiplayer-and-networking/host-authoritative-state/",
     "./skills/multiplayer-and-networking/peer-to-peer-multiplayer/",
     "./skills/deployment/export-and-ship/",
+    "./skills/deployment/remote-deploy/",
     "./skills/character-controllers/fps-controller/",
     "./skills/scripting-patterns/gdscript-patterns/",
     "./skills/ui-and-ux/ui-basics/",
@@ -61,6 +63,7 @@
     "./skills/2d-assets/ui-graphics/",
     "./skills/2d-assets/tileable-texture/",
     "./skills/2d-assets/sprite-sheet/",
+    "./skills/2d-assets/create-asset-sheet/",
     "./skills/2d-assets/skybox-panorama/",
     "./skills/3d-assets/prop-model/",
     "./skills/3d-assets/character-model/",

package/.opencode/plugins/summer.js

@@ -20,7 +20,7 @@ Process skills (run before building): brainstorm-game, debug, play.
 Discipline skills (shape what you build): gdscript-patterns, scene-composition, art-direction, audio-direction, asset-strategy.
 Build skills (produce artifacts): fps-controller, design-mechanic, design-level, setup-multiplayer, host-authoritative-state, peer-to-peer-multiplayer, design-npc, 3d-lighting, ui-basics, vfx, tune-performance, export-and-ship, make-game.
 
-Always check for a relevant skill before responding. The summer-engine MCP server (npx summer-engine mcp) provides scene mutation, asset import, render, play, and diagnostics tools — file ops, git, shell, and grep are NOT exposed (use OpenCode's native tools).
+Always check for a relevant skill before responding. The summer-engine MCP server (npx summer-engine mcp) provides identity-bound project file mutations plus scene, asset, render, play, and diagnostics tools. Git, shell, and grep remain native; do not bypass Summer's file guards when MCP is available.
 </EXTREMELY_IMPORTANT>`;
 
 export const SummerPlugin = async ({ client, directory }) => {

package/AGENTS.md

@@ -13,6 +13,9 @@ This file is for any AI agent that loads context from `AGENTS.md` (Codex CLI, Fa
 3. **Don't grep the whole project before reading the actual error.** Use `summer_get_script_errors` first.
 4. **Don't edit `.tscn` files directly while the engine is running.** Use the `summer_*` MCP tools — direct edits get overwritten when the editor saves.
 5. **Never call `summer_set_resource_property` against an inline `sub_resource`** — it silently drops the value. Instantiate via `summer_set_prop` with a class-name string first.
+6. **Every scene mutation names its target.** Pass the exact `res://...tscn` as `scenePath` to add/set/remove/replace/connect/instantiate/save tools and mutation batches. `summer_open_scene` is a user-visible tab action, not a prerequisite or target selector.
+7. **Never mix `OpenScene` with scene mutations in one batch.** Send the UI action separately; `scenePath` already selects the mutation target.
+8. **Save once at the transaction boundary.** Dedicated scene mutation tools and `summer_batch` append one final `SaveScene`. Raw engine batches must include one final `SaveScene` themselves.
 
 ## Skill priority
 
@@ -22,18 +25,19 @@ This file is for any AI agent that loads context from `AGENTS.md` (Codex CLI, Fa
 
 ## MCP tool palette (engine on `localhost:6550`)
 
-52 tools total. Categories:
+56 tools total. Categories:
 
 - Scene: `summer_get_scene_tree`, `summer_open_scene`, `summer_create_scene`, `summer_add_node`, `summer_set_prop`, `summer_set_resource_property`, `summer_remove_node`, `summer_save_scene`, `summer_instantiate_scene`, `summer_replace_node`, `summer_select_node`, `summer_inspect_node`, `summer_inspect_resource`, `summer_connect_signal`, `summer_batch`.
-- Diagnostics: `summer_get_script_errors`, `summer_get_diagnostics`, `summer_get_console`, `summer_clear_console`, `summer_get_debugger_errors`, `summer_get_debugger_warnings`.
+- Diagnostics: `summer_create_debug_report`, `summer_get_script_errors`, `summer_get_diagnostics`, `summer_get_console`, `summer_clear_console`, `summer_get_debugger_errors`, `summer_get_debugger_warnings`.
 - Runtime: `summer_play`, `summer_stop`, `summer_is_running`.
 - Visual: `summer_screenshot` (capture the editor viewport or running game as an image to verify it).
 - Project: `summer_get_project_context`, `summer_open_main_scene`, `summer_project_setting`, `summer_input_map_bind`, `summer_get_agent_playbook`.
+- Files: `summer_read_file`, `summer_write_file`, `summer_replace_text` (identity-bound; create-only or sha256-guarded writes).
 - Assets: `summer_search_assets`, `summer_list_my_assets`, `summer_get_asset`, `summer_get_asset_download_url`, `summer_import_asset`, `summer_import_asset_by_id`, `summer_import_from_url`, `summer_import_from_url_batch`.
 - Generation: `summer_generate_image`, `summer_generate_3d`, `summer_generate_audio`, `summer_generate_video`, `summer_generate_motion`, `summer_check_job`.
 - Meta: `summer_start_game_task`.
 
-File ops, git, shell, and grep are NOT exposed — use the host's native tools.
+Git, shell, and grep are not exposed. Project file reads and writes are exposed through identity-bound Summer tools; do not bypass them with host writes when MCP is available. External host tools cannot be technically blocked, so the agent must follow this rule.
 
 ## Type-system gotchas
 
@@ -50,5 +54,5 @@ Resources are class names: `"BoxMesh"`, `"StandardMaterial3D"`, `"CapsuleShape3D
 |---|---|
 | MCP tool returns "Summer Engine is not running" | Tell user `summer run`. Continue with non-MCP work. |
 | Skill loads but seems wrong | Re-read it. Skills evolve. |
-| Skill not found | Check `summer skills list`, then `summer setup <agent> --yes`. |
+| Skill not found or stale | Run `summer doctor`; if `cli-version-current` or `skills-version-stale` warns, run `npx clear-npx-cache && npx -y summer-engine@latest setup <agent> --yes --force`. |
 | Generic engine errors on launch | Run `summer doctor` first — usually reveals auth/port/path issues. |

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 All notable changes to summer-engine will be documented here. Following [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [Semantic Versioning](https://semver.org/).
 
+## [2.7.0] — 2026-07-24 — "Reliable project mutations"
+
+### Added
+- `summer_read_file`, `summer_write_file`, and `summer_replace_text` expose engine-routed project file access, including `.tscn` and `.tres`. New files require `create_only:true`; overwrites require an engine sha256 receipt.
+- File mutations fail closed unless the MCP client has a complete engine/project identity and use the bound project hash even if caller options attempt to override it.
+
+### Changed
+- Agent playbooks now route project file mutations through Summer MCP instead of recommending host writes that bypass identity, content guards, and editor reload handling.
+- Scene mutation tools require an explicit `scenePath`; the target scene does not need to be the visible editor tab.
+- `summer_open_scene` is navigation only and no longer acts as implicit mutation targeting.
+- Dedicated scene mutations and mutation batches append one final `SaveScene` at the transaction boundary.
+- Agent guidance no longer claims that routine scene edits require stopping the running game.
+
+### Fixed
+- Bridge/project identity rejections now return one correlated `not_sent`
+  terminal, allowing the web harness to retry safely instead of waiting for a
+  mutation receipt that cannot exist.
+- Same-file MCP mutations now serialize the complete read-to-write transaction,
+  preventing concurrent replacements from racing on a stale file preimage.
+- Accepted engine operations preserve their request identity and report whether
+  they are still queued, still running, or uncertain instead of claiming that
+  nothing was applied after a client wait deadline.
+- `summer_batch` no longer permits raw file mutations that bypass the guarded
+  `summer_write_file` and `summer_replace_text` tools.
+- Scene operations return target/persistence evidence and concrete dependency errors instead of relying on ambient open-scene state.
+- Asset placement reports success only after both the import and explicit target-scene mutation are confirmed.
+
+### Limitations
+- The package cannot intercept an external agent's native filesystem tools. A host can still mutate files outside MCP, and a non-atomic external write can race the engine between validation and write; those cases remain technically unenforceable.
+
+## [2.6.6] — 2026-07-15 — "Project-bound engine requests"
+
+### Fixed
+- Every local engine request now carries the engine instance ID, stable project ID, project ID hash, and identity protocol version captured when the CLI connects. This lets compatible engine builds reject stale requests after a project or engine switch instead of acting on the wrong target.
+- An explicit project rebind now refreshes the complete engine and project identity, while keeping the existing project-hash mutation guard and screenshot drift checks.
+- Summer Cloud's engine bridge now binds its save, rescan, and scene reload requests to the project it verified on disk.
+
+### Changed
+- Summer Cloud is documented as an optional Research Preview instead of part of the core local CLI and MCP workflow.
+- Release metadata and the manual npm runbook now pin the public registry and require a clean, reviewed public source checkout.
+
 ## [2.6.5] — 2026-07-04 — "Cloud tools don't need the engine"
 
 ### Fixed

package/GEMINI.md

@@ -20,17 +20,18 @@ The single most important skill to know is `summer:using-summer` — it explains
 
 ## MCP tools (when the engine is running on `localhost:6550`)
 
-The `summer-engine` MCP server exposes 52 focused tools. The most important:
+The `summer-engine` MCP server exposes 56 focused tools. The most important:
 
-- **Scene mutation**: `summer_add_node`, `summer_set_prop`, `summer_set_resource_property`, `summer_remove_node`, `summer_save_scene`, `summer_replace_node`, `summer_batch`.
+- **Scene mutation**: `summer_add_node`, `summer_set_prop`, `summer_set_resource_property`, `summer_remove_node`, `summer_save_scene`, `summer_replace_node`, `summer_batch`. Every scene mutation requires the exact `res://...tscn` `scenePath`; opening a scene is a user-visible UI action, not a mutation prerequisite. Mutation tools append one final `SaveScene`; raw engine batches must do the same.
 - **Scene inspection**: `summer_get_scene_tree`, `summer_inspect_node`, `summer_inspect_resource`.
-- **Diagnostics**: `summer_get_script_errors` (cheapest), `summer_get_diagnostics`, `summer_get_console`, `summer_get_debugger_errors`, `summer_get_debugger_warnings`.
+- **Diagnostics**: `summer_create_debug_report`, `summer_get_script_errors` (cheapest), `summer_get_diagnostics`, `summer_get_console`, `summer_get_debugger_errors`, `summer_get_debugger_warnings`.
 - **Run game**: `summer_play`, `summer_stop`, `summer_is_running`.
 - **Visual**: `summer_screenshot` (capture the viewport or running game as an image you can see).
 - **Project**: `summer_get_project_context`, `summer_open_main_scene`, `summer_project_setting`, `summer_input_map_bind`.
+- **Files**: `summer_read_file`, `summer_write_file`, `summer_replace_text` (identity-bound, create-only or sha256-guarded mutations).
 - **Assets**: `summer_search_assets`, `summer_import_asset`, `summer_import_from_url`, `summer_generate_image`, `summer_generate_3d`, `summer_generate_audio`, `summer_generate_video`, `summer_check_job`.
 
-File ops (Read/Write/Edit), git, shell, and grep are deliberately **not** exposed via MCP — Gemini already has those natively.
+Git, shell, and grep remain host-native. Use the Summer file tools for project reads and writes whenever MCP is available; host file writes bypass engine identity, sha guards, and reload handling and cannot be technically prevented by this package.
 
 ## Type-system traps
 

package/README.md

@@ -1,5 +1,7 @@
 # Summer Engine: the AI game engine
 
+> **Engine mirror only.** This directory is intentionally marked `private` and must never be published to npm. Review and reconcile changes into [SummerEngine/summer-engine-agent](https://github.com/SummerEngine/summer-engine-agent), which is the only npm release source.
+
 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 MIT open-source agent layer that connects your AI coding agent to Summer Engine. It is the **Summer CLI**, the **Summer MCP** server, and the **Summer agent** skills, hooks, and plugin manifests, all in one package. First-class setup works in Claude Code, Cursor, Codex, Devin Desktop (formerly Windsurf), Cline, Roo Code, Gemini CLI, GitHub Copilot CLI, GitHub Copilot in VS Code, and OpenCode. Factory Droid uses the plugin marketplace path.
@@ -18,27 +20,11 @@ It just works. Open your agent, say *"let's make an FPS in Summer Engine,"* and
 Three names, one npm package (`summer-engine`):
 
 - **Summer CLI** (`npx -y summer-engine@latest`): installs the engine, signs you in, scaffolds and runs projects, and writes your agent's config. See [www.summerengine.com/cli](https://www.summerengine.com/cli).
-- **Summer MCP**: the local MCP server that gives your agent 52 engine tools to build, run, and debug a real game. See [www.summerengine.com/mcp](https://www.summerengine.com/mcp).
+- **Summer MCP**: the local MCP server that gives your agent 56 engine tools to build, run, and debug a real game. See [www.summerengine.com/mcp](https://www.summerengine.com/mcp).
 - **Summer agent layer**: the game-dev skills, hooks, and plugin manifests that give your AI agent judgment, not just a chat box.
 
 All MIT, all free to use. One paste sets up all three.
 
-## Summer Cloud (new in 2.6.0)
-
-`summer cloud` syncs your whole game project across machines: scenes, scripts, settings, and the big binary assets that never fit in git. Files are stored by content hash, every push becomes a restorable version, and local checkpoints are taken before anything destructive touches your disk.
-
-```bash
-summer cloud init      # bind this project to your account
-summer cloud push      # upload what changed (only missing bytes travel)
-summer cloud pull      # make this machine match the cloud, verified by hash
-summer cloud status    # what differs between here and the cloud
-summer cloud restore   # roll the project back to any version
-```
-
-The same operations are available to agents as MCP tools (`summer_cloud_push`, `summer_cloud_pull`, and friends). See [www.summerengine.com/cloud](https://www.summerengine.com/cloud).
-
----
-
 ## Get started: one prompt
 
 Open your AI agent (Claude Code, Cursor, Codex, Copilot, Devin Desktop, etc.) and paste:
@@ -269,19 +255,20 @@ Two pieces, plus the glue.
 
 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 52 tools that talk to your local engine on `localhost:6550`:
+**MCP bridge.** The `summer-engine` MCP server gives the agent 56 tools that talk to your local engine on `localhost:6550`:
 
 | | |
 |---|---|
 | 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` |
+| Diagnostics | `summer_create_debug_report`, `summer_get_script_errors`, `summer_get_diagnostics`, `summer_get_console`, `summer_clear_console`, `summer_get_debugger_errors`, `summer_get_debugger_warnings` |
 | Runtime | `summer_play`, `summer_stop`, `summer_is_running` |
 | Visual | `summer_screenshot` (see the editor viewport, an offscreen scene render, or the running game) |
 | Interactive | `SimulateInput` / `RunVerification` raw ops via `summer_batch` — drive the running game or run a hidden GDScript probe (engine-build dependent) |
 | Project | `summer_get_project_context`, `summer_open_main_scene`, `summer_project_setting`, `summer_input_map_bind` |
+| Files | `summer_read_file`, `summer_write_file`, `summer_replace_text` — identity-bound, create-only or sha256-guarded mutations |
 | 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, and grep already belong to your agent. We don't shadow them.
+Git, shell, and grep remain host-native. Project file reads and writes use Summer's identity-bound tools so compatible engine builds can reject wrong-project and stale-content mutations. A host agent can still bypass these safeguards with its own file tools; the package cannot technically intercept that external process.
 
 **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.
 
@@ -556,6 +543,24 @@ Skills evolve fast. Two ways to help:
 
 ---
 
+## Research Preview: Summer Cloud
+
+Summer Cloud is an experimental R&D preview. It is optional, it may change or break, and it is **not** the core Summer CLI or MCP workflow. You do not need it to install or run Summer Engine, work with local projects, or use the local MCP server. The stable workflow is the local engine, CLI, MCP bridge, and agent skills described above.
+
+The preview explores content-addressed project sync across machines, including large assets that do not fit comfortably in git:
+
+```bash
+summer cloud init
+summer cloud status
+summer cloud push
+summer cloud pull
+summer cloud restore
+```
+
+Matching `summer_cloud_*` MCP tools are also experimental. Keep an independent backup and do not use this preview as the only recovery path for an important project. See [www.summerengine.com/cloud](https://www.summerengine.com/cloud).
+
+---
+
 ## License
 
 MIT for everything in this repo. Summer Engine itself is proprietary. See [What's open and what's not](#whats-open-and-whats-not).

package/_persona/summer/SKILL.md

@@ -41,6 +41,7 @@ When the user invokes `/summer`, you:
 | "/summer add ambient music" | `summer:audio/music-track` |
 | "/summer make me [a VFX effect]" | `summer:visual-effects/recipes/<closest>` (e.g., "make me fire" -> `recipes/fire`; "lightning" -> `recipes/lightning`; "muzzle flash" -> `recipes/muzzle-flash`; "smoke" -> `recipes/smoke`; "magic glow" -> `recipes/magic-glow`; "hit spark" -> `recipes/hit-spark`; "dissolve" -> `recipes/dissolve`; "water ripple" -> `recipes/water-ripple`) |
 | "/summer build the FPS controller" | `summer:character-controllers/fps-controller` |
+| "/summer debug" or "/summer debug [issue]" | `summer:debugging/debug` (support report mode first) |
 | "/summer the game crashes when [X]" | `summer:debugging/debug` |
 | "/summer add an animation to [character]" | `summer:animation/generate-motion` |
 | "/summer wire up a state machine for [character]" | `summer:animation/animation-tree` |

package/commands/summer.md

@@ -0,0 +1,13 @@
+You are the Summer Engine command router. The user invoked `/summer` because they want game-development help inside Summer Engine, not generic software advice.
+
+Arguments:
+
+```
+$ARGUMENTS
+```
+
+First, route the request to the closest Summer skill. Use `summer:using-summer` if you need base context before choosing.
+
+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.
+
+For all other requests, follow the `/summer` persona routing table from the Summer skill family and start the appropriate game-dev workflow.

package/dist/bin/summer.js

@@ -17,6 +17,7 @@ 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 { getBanner } from "../lib/banner.js";
 import { c, sym } from "../lib/format.js";
 const require = createRequire(import.meta.url);
@@ -42,6 +43,7 @@ program.addCommand(skillsCommand);
 program.addCommand(mcpCommand);
 program.addCommand(setupCommand);
 program.addCommand(doctorCommand);
+program.addCommand(debugCommand);
 program.addCommand(planCommand);
 program.addCommand(orchestratorCommand);
 program.addCommand(cloudCommand);
@@ -63,10 +65,12 @@ function printIntro(version) {
     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("");

package/dist/commands/debug.d.ts

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

package/dist/commands/debug.js

@@ -0,0 +1,44 @@
+import { Command } from "commander";
+import { createDebugReportArtifact, redactDebugReport } from "../lib/debug-report.js";
+import { c, sym, tildeify } from "../lib/format.js";
+function parsePositiveInt(value, fallback) {
+    if (!value)
+        return fallback;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+export const debugCommand = new Command("debug")
+    .description("Create a support-ready Markdown debug report")
+    .argument("[issue...]", "What is broken or surprising?")
+    .option("-o, --output <path>", "Write the report to this path")
+    .option("--json", "Print JSON with the report path and collected data")
+    .option("--play", "Also launch the game briefly and collect post-play diagnostics")
+    .option("--no-doctor", "Skip summer doctor checks")
+    .option("--max-console-lines <n>", "Console lines to collect", "200")
+    .option("--max-debugger-entries <n>", "Debugger entries to collect", "100")
+    .option("--play-wait-ms <n>", "Milliseconds to wait after --play starts", "2500")
+    .action(async (issueParts, opts) => {
+    const issue = issueParts.join(" ").trim();
+    const artifact = await createDebugReportArtifact({
+        issue,
+        outputPath: opts.output,
+        includePlaySession: Boolean(opts.play),
+        includeDoctor: opts.doctor !== false,
+        maxConsoleLines: parsePositiveInt(opts.maxConsoleLines, 200),
+        maxDebuggerEntries: parsePositiveInt(opts.maxDebuggerEntries, 100),
+        playWaitMs: parsePositiveInt(opts.playWaitMs, 2500),
+    });
+    if (opts.json) {
+        console.log(JSON.stringify({
+            ok: true,
+            path: artifact.path,
+            report: redactDebugReport(artifact.report),
+        }, null, 2));
+        return;
+    }
+    console.log("");
+    console.log(`${sym.ok()} ${c.bold("Summer debug report created")}`);
+    console.log(`   ${tildeify(artifact.path)}`);
+    console.log("");
+    console.log("Review it before sending. It omits auth tokens, but may include local paths and stack traces.");
+});

package/dist/commands/doctor.js

@@ -3,14 +3,23 @@ import { existsSync } from "fs";
 import { createRequire } from "node:module";
 import { platform } from "os";
 import { Command } from "commander";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 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 { getMcpLogPath } from "../lib/mcp-log.js";
 import { getProjectMemorySummary } from "../lib/project-memory.js";
 import { buildCliVersionCheck, buildSkillsVersionCheck, defaultSkillMarkerCandidates, fetchLatestRegistryVersion, } from "../lib/version-check.js";
 const require = createRequire(import.meta.url);
 const { version } = require("../../package.json");
+const MIN_EXPECTED_MCP_TOOLS = 50;
+const REQUIRED_MCP_TOOLS = [
+    "summer_get_project_context",
+    "summer_generate_image",
+    "summer_create_debug_report",
+];
 const MAC_ENGINE_PATHS = [
     "/Applications/Summer.app/Contents/MacOS/Summer",
     `${process.env.HOME}/Applications/Summer.app/Contents/MacOS/Summer`,
@@ -21,7 +30,7 @@ const WIN_ENGINE_PATHS = [
     `${process.env.PROGRAMFILES}\\Summer Engine\\Summer.exe`,
 ];
 export const doctorCommand = new Command("doctor")
-    .description("Diagnose Node, login, engine, project memory, local API, and MCP boot")
+    .description("Diagnose Node, login, engine, project memory, local API, and MCP registration")
     .option("--json", "Print diagnostics as JSON")
     .action(async (opts) => {
     if (!opts.json) {
@@ -53,6 +62,7 @@ export async function runDoctor(options = {}) {
     checks.push(await checkLocalApi());
     checks.push(await checkProjectMemory());
     checks.push(await checkMcpBoot());
+    checks.push(await checkMcpToolsList());
     const result = summarizeChecks(checks);
     if (!options.quiet) {
         if (options.json) {
@@ -237,8 +247,8 @@ async function checkProjectMemory() {
     };
 }
 async function checkMcpBoot() {
-    const cliPath = process.argv[1];
-    if (!cliPath) {
+    const resolved = resolveCurrentMcpCommand();
+    if (!resolved) {
         return {
             id: "mcp-boot",
             label: "MCP Server",
@@ -247,9 +257,7 @@ async function checkMcpBoot() {
         };
     }
     return new Promise((resolve) => {
-        const command = cliPath.endsWith(".js") ? process.execPath : cliPath;
-        const args = cliPath.endsWith(".js") ? [cliPath, "mcp"] : ["mcp"];
-        const child = spawn(command, args, {
+        const child = spawn(resolved.command, resolved.args, {
             env: process.env,
             stdio: ["pipe", "pipe", "pipe"],
         });
@@ -269,7 +277,7 @@ async function checkMcpBoot() {
                 label: "MCP Server",
                 status: "fail",
                 message: "MCP server did not finish startup within 3 seconds.",
-                details: trimOutput({ stdout, stderr }),
+                details: { ...trimOutput({ stdout, stderr }), ...resolved },
             });
         }, 3000);
         child.stderr.on("data", (chunk) => {
@@ -281,6 +289,7 @@ async function checkMcpBoot() {
                     label: "MCP Server",
                     status: "ok",
                     message: "ready",
+                    details: { ...resolved },
                 });
             }
         });
@@ -294,6 +303,7 @@ async function checkMcpBoot() {
                 label: "MCP Server",
                 status: "fail",
                 message: `Could not start MCP server: ${error.message}`,
+                details: { ...resolved },
             });
         });
         child.on("exit", (code) => {
@@ -304,12 +314,106 @@ async function checkMcpBoot() {
                     label: "MCP Server",
                     status: "fail",
                     message: `MCP server exited before reporting readiness${code === null ? "" : ` (code ${code})`}.`,
-                    details: trimOutput({ stdout, stderr }),
+                    details: { ...trimOutput({ stdout, stderr }), ...resolved },
                 });
             }
         });
     });
 }
+function resolveCurrentMcpCommand() {
+    const cliPath = process.argv[1];
+    if (!cliPath)
+        return null;
+    return cliPath.endsWith(".js")
+        ? { command: process.execPath, args: [cliPath, "mcp"] }
+        : { command: cliPath, args: ["mcp"] };
+}
+function inheritedEnv(extra = {}) {
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value !== undefined)
+            env[key] = value;
+    }
+    return { ...env, ...extra };
+}
+async function checkMcpToolsList() {
+    const resolved = resolveCurrentMcpCommand();
+    if (!resolved) {
+        return {
+            id: "mcp-tools-list",
+            label: "MCP Tools",
+            status: "fail",
+            message: "Could not resolve the current Summer CLI entrypoint.",
+        };
+    }
+    const client = new Client({ name: "summer-doctor", version });
+    const transport = new StdioClientTransport({
+        ...resolved,
+        env: inheritedEnv({ SUMMER_MCP_DOCTOR: "1" }),
+        stderr: "pipe",
+    });
+    let stderr = "";
+    transport.stderr?.on("data", (chunk) => {
+        stderr += Buffer.isBuffer(chunk) ? chunk.toString("utf-8") : String(chunk);
+    });
+    try {
+        await client.connect(transport, { timeout: 5000 });
+        const listed = await client.listTools(undefined, { timeout: 5000 });
+        const toolNames = listed.tools.map((tool) => tool.name).sort();
+        const missing = REQUIRED_MCP_TOOLS.filter((tool) => !toolNames.includes(tool));
+        const details = {
+            ...resolved,
+            toolCount: toolNames.length,
+            requiredTools: REQUIRED_MCP_TOOLS,
+            missing,
+            server: client.getServerVersion(),
+            stderr: stderr.trim().slice(-1000),
+            logPath: getMcpLogPath(),
+        };
+        if (missing.length > 0) {
+            return {
+                id: "mcp-tools-list",
+                label: "MCP Tools",
+                status: "fail",
+                message: `missing required tools: ${missing.join(", ")}`,
+                details,
+            };
+        }
+        if (toolNames.length < MIN_EXPECTED_MCP_TOOLS) {
+            return {
+                id: "mcp-tools-list",
+                label: "MCP Tools",
+                status: "fail",
+                message: `only ${toolNames.length} tools listed; expected ${MIN_EXPECTED_MCP_TOOLS}+`,
+                details,
+            };
+        }
+        return {
+            id: "mcp-tools-list",
+            label: "MCP Tools",
+            status: "ok",
+            message: `${toolNames.length} tools registered`,
+            details,
+        };
+    }
+    catch (error) {
+        return {
+            id: "mcp-tools-list",
+            label: "MCP Tools",
+            status: "fail",
+            message: `protocol handshake/list failed: ${error instanceof Error ? error.message : String(error)}`,
+            details: {
+                ...resolved,
+                stderr: stderr.trim().slice(-1000),
+                logPath: getMcpLogPath(),
+            },
+        };
+    }
+    finally {
+        await client.close().catch(() => undefined);
+        await transport.close().catch(() => undefined);
+    }
+}
 function summarizeChecks(checks) {
     const summary = {
         ok: checks.filter((check) => check.status === "ok").length,

package/dist/commands/skills.js

@@ -367,7 +367,7 @@ function renderRuleBody(skill) {
 
 ${skill.description}
 
-Use Summer MCP tools for scene, editor, asset, play, and diagnostics operations. Use the host agent's normal file editing tools for scripts and other text files.
+Use Summer MCP tools for project files, scenes, editor state, assets, play, and diagnostics. Read project text with summer_read_file and mutate it with summer_replace_text or guarded summer_write_file.
 
 ## Skill