summer-engine 2.6.6 → 2.7.0

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

@@ -145,6 +145,6 @@ Note the field name difference too: `LabelSettings.outline_color` (Label 2D) vs
 
 ## Scene Integration
 
-When the AI adds a node with Summer MCP tools and attaches a script, the script path is set via `summer_set_prop(path, "script", "res://path/to/script.gd")`. The script file must exist first. Create or edit `.gd` files with the host agent's normal file-editing tools, then use Summer MCP only to attach the script and connect scene signals.
+When the AI adds a node with Summer MCP tools and attaches a script, the script path is set via `summer_set_prop(path, "script", "res://path/to/script.gd")`. The script file must exist first. Create it with guarded `summer_write_file` or edit it with `summer_replace_text`, then attach the script and connect scene signals.
 
 For signal connections, the receiver must have the handler method. Create the script with the method stub before calling `summer_connect_signal`.

package/skills/workflow/mcpupdate/SKILL.md

@@ -111,7 +111,7 @@ and skills, make them teach this, and flag where they don't:
 
 1. **Understand** what the user wants (one pass, no tool spelunking first).
 2. **Outline** the plan fast and briefly; proceed once it's clearly right.
-3. **Execute in pure code**. Write GDScript by default (C# only if the project already uses it). Edit `.gd`/`.tscn`/`.tres` as **text files**; that's the default medium.
+3. **Execute through Summer's identity-bound tools**. Write GDScript by default (C# only if the project already uses it). Read and mutate `.gd`/`.tscn`/`.tres` with `summer_read_file`, `summer_replace_text`, or guarded `summer_write_file`.
 4. **Play & auto-iterate**. Run the scene/game, read console + script/debugger errors, fix, repeat until clean. Crucially: **play the scene you just made first**, so boot/parse crashes surface immediately instead of after the user navigates to the feature.
 
 ## Known bad path to fix first (from real sessions)
@@ -119,11 +119,11 @@ The MCP playbook over-steered agents into **ops-first** scene editing (open/save
 instantiate) when plain **file editing** is simpler and safer for a headless agent, causing
 wasted turns, scene "rename"/save-as churn, and editor-tab clobbering. Keep these fixed:
 
-- **File-first for `.tscn`/`.tres`:** edit scene/resource files as text by default; use scene-ops
-  only for live-engine needs (navmesh/light bake, play/observe, runtime inspect) or instancing
-  into an already-open scene. The MCP `WriteFile` refusing `.tscn` means "use host file tools," not "use scene ops."
-- **Clobber gotcha:** a `.tscn` open in the editor can be overwritten by the editor's tab on save.
-  reload/close the tab after external writes.
+- **Guarded files for `.tscn`/`.tres`:** use identity-bound MCP text tools for complete-file work;
+  use scene ops for live hierarchy/inspector changes, navmesh/light bake, play/observe, runtime
+  inspection, or instancing. New files are create-only; overwrites require a read sha256.
+- **External-host limitation:** host tools can still bypass these guards. Flag any doctrine that
+  recommends doing so while MCP is available.
 - **Constraint-based flow:** the playbook's flow is conditional (`buildFlow` for the default,
   `liveEngineFlow` only when you need the running engine), not a prescriptive always-open-the-editor loop.
 

package/skills/workflow/using-summer/SKILL.md

@@ -36,7 +36,7 @@ If `CLAUDE.md` says "skip the brainstorm, just build it" and a skill says "alway
 Two layers:
 
 - **Skills** — discipline guides that fire on specific situations: brainstorming a game, designing a mechanic, building an FPS controller, debugging a crash, shipping a build. Each one is a SKILL.md you load via the Skill tool.
-- **MCP tools** — `summer_*` tools that talk to the running Summer Engine on `localhost:6550`. Scene mutation (`summer_add_node`, `summer_set_prop`), inspection (`summer_get_scene_tree`, `summer_inspect_node`), play/diagnostics (`summer_play`, `summer_get_diagnostics`), asset import/generation (`summer_import_from_url`, `summer_generate_3d`), and 30+ more.
+- **MCP tools** — `summer_*` tools that talk to the running Summer Engine on `localhost:6550`. Scene mutation (`summer_add_node`, `summer_set_prop`), inspection (`summer_get_scene_tree`, `summer_inspect_node`), play/diagnostics (`summer_play`, `summer_get_diagnostics`), asset import/generation (`summer_import_from_url`, `summer_generate_3d`), whole-project sync to Summer Cloud (`summer_cloud_push`, `summer_cloud_pull`; see `summer:summer-cloud`), and 30+ more.
 
 **Scripting language:** Summer Engine is compatible with Godot 4.5. You can write game code in either:
 
@@ -90,6 +90,7 @@ These thoughts mean STOP. Check skills first.
 | "I'll write the GDScript myself, no skill" | `gdscript-patterns` encodes idioms that Claude/Codex/Cursor regularly get wrong (signal connection, type hints, `_ready` vs `_process`). |
 | "The engine isn't running, I'll just edit files" | Editing scene files directly while the engine is running silently overwrites in-memory state. Check the skill. |
 | "I remember this skill" | Skills evolve. Re-read the current version. |
+| "I'll just zip the project to move it to another machine" | `summer:summer-cloud` syncs the whole project (big assets included) by hash, with restorable versions. Load it whenever the user mentions sync, a second machine, sharing with a teammate, backing up assets, or restoring a version. |
 
 ## Skill Priority
 
@@ -128,6 +129,24 @@ If skills aren't found or the MCP server fails to start:
 2. If not, point them at: `npx -y summer-engine@latest setup <agent> --yes --force`.
 3. If `summer doctor` is available, run it: `summer doctor` reports auth, engine, port, project memory, and skill state.
 
+## When Summer Is Stale
+
+Run `summer doctor` early in a fresh Summer session when setup, MCP tools, slash commands, or skills behave oddly. If doctor reports `cli-version-current` or `skills-version-stale` as warning/fail, refresh before continuing:
+
+```
+npx clear-npx-cache && npx -y summer-engine@latest setup <agent> --yes --force
+```
+
+Use the real agent slug from doctor or the current environment (`claude-code`, `codex`, `cursor`, `gemini`, `github-copilot`, `vscode-copilot`, `opencode`, etc.).
+
+Why this exact command matters:
+
+- `@latest` forces npm/npx to resolve the current published Summer CLI instead of reusing a stale cached package.
+- `clear-npx-cache` clears old npx package material on machines that keep serving an older Summer.
+- `setup ... --force` rewrites copied skill/slash-command files, which do not update just because the MCP server restarted.
+
+After the refresh, restart or reload the agent/MCP session if tools were missing. MCP tool changes load on MCP reconnect; copied skills and slash commands load when the agent notices the rewritten files or starts a fresh session.
+
 ## User Instructions Trump Everything
 
 A direct user instruction ("skip the brainstorm", "just write the code", "don't use the MCP, edit files") overrides this skill. Surface the trade-off in one sentence ("Skipping brainstorm — heads up, scope creep is the most common reason game projects die.") and proceed as instructed.