summer-engine 2.6.5 → 2.7.0

package/skills/2d-assets/create-asset-sheet/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 2d-assets
 user-invocable: true
-allowed-tools: Read Grep Glob Write Edit summer_generate_image summer_search_assets summer_import_from_url
+allowed-tools: Read Grep Glob Write Edit summer_get_studio_workflow summer_generate_image summer_slice_asset_sheet summer_search_assets summer_import_asset_by_id summer_import_from_url
 paths: ["assets/**", "art/**", "sprites/**"]
 ---
 
@@ -58,13 +58,16 @@ Direct the user there if they're working in the browser. The wizard:
 - Has per-slice HD upscale + bulk "Upscale all"
 - Saves as a pack ArtAsset visible in the user's library
 
-If the user is in a chat / agent context and can't open the browser, fall back to the programmatic path below.
+If the user is in a chat / agent context, use the programmatic path below. It
+now calls the same server-side slicer as the Studio wizard.
 
 ## Programmatic path (chat / agent driving the engine)
 
-The slicing + classification endpoints are not yet exposed as `summer_*` MCP tools. Until they are, the agent can replicate the flow manually:
+1. **Load the exact current recipe.** Call
+   `summer_get_studio_workflow({workflowId: "asset-pack"})`. Follow its ordered
+   steps and report any `manual` handoff instead of pretending it ran.
 
-1. **Generate the sheet.** Call `summer_generate_image` with a prompt like:
+2. **Generate the sheet.** Call `summer_generate_image` with a prompt like:
 
    ```
    <theme> asset sheet: <comma-separated list of items>. Each item isolated with empty space around it, transparent or neutral background.
@@ -74,21 +77,18 @@ The slicing + classification endpoints are not yet exposed as `summer_*` MCP too
    - 1024x1024 is the sweet spot. Larger sheets fragment in the slicer when individual assets get below ~64px.
    - Keep the asset list to 6–20 items per sheet. Past 20, model attention degrades and slices get muddy.
 
-2. **Remove background.** Call `fal-ai/bria/background/remove` on the generated URL. Cost: $0.05.
-
-3. **Detect + name + classify.** Send the transparent PNG to a vision LLM (Gemini 3 Pro is currently the strongest at bbox + category in one shot). Use this system prompt structure:
+3. **Slice, remove background, detect, name, classify, crop, and save.** Pass
+   the returned image asset id to:
 
    ```
-   Output strict JSON array, no prose:
-   [{"name":"snake_case_name","category":"character|terrain|nature|lighting|water|decorative|buildings|ui|vfx","x":<0-100>,"y":<0-100>,"w":<0-100>,"h":<0-100>}]
-
-   Coordinates are percentages of image dimensions, top-left origin.
-   Names are 1-3 words, snake_case, specific (stone_lantern, not lamp).
+   summer_slice_asset_sheet({ assetId: "<generated asset id>" })
    ```
 
-4. **Crop** each region with sharp / PIL / equivalent. Pad bboxes by 4px to leave breathing room.
+   This is the same cloud slicing pipeline used by the Studio flow. Keep the
+   returned slice ids/names/categories; do not reimplement the vision boxes
+   locally.
 
-5. **Optional upscale.** For any crop where longest side < 256px, send through fal flux-2/edit i2i with prompt:
+4. **Optional upscale.** For any crop where longest side < 256px, send through fal flux-2/edit i2i with prompt:
 
    ```
    Recreate this exact <name> at high resolution. Preserve every detail, the exact pose, the exact style. Sharper edges, more detail. Transparent background. Single isolated asset, no scene.
@@ -97,7 +97,9 @@ The slicing + classification endpoints are not yet exposed as `summer_*` MCP too
    - Scale longest side to 1024, preserve aspect ratio (FLUX requires multiples of 32).
    - Don't blindly upscale everything — high-res slices get diminishing returns and you spend $0.04/slice.
 
-6. **Save** as a pack record in `art_assets`: `isPack: true`, `packFiles: [{url, name, type: "image/png"}]`, `metadata.sliceBboxes`, `parentAssetId` pointing to the source sheet.
+5. **Import what the game needs.** Use the returned asset ids with
+   `summer_import_asset_by_id`. Keep the source pack in My Assets so the agent
+   and the human Studio session see the same result.
 
 ## Prompt patterns that work
 

package/skills/debugging/debug/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
 category: debugging
 user-invocable: true
-allowed-tools: Read Edit Grep summer_get_diagnostics summer_get_script_errors summer_get_console summer_clear_console summer_get_debugger_errors summer_play summer_stop summer_is_running summer_inspect_node summer_inspect_resource summer_get_scene_tree
+allowed-tools: Read Edit Grep summer_create_debug_report summer_get_diagnostics summer_get_script_errors summer_get_console summer_clear_console summer_get_debugger_errors summer_play summer_stop summer_is_running summer_inspect_node summer_inspect_resource summer_get_scene_tree
 paths: ["**/*.gd", "**/*.cs", "**/*.tscn", "**/*.tres", "project.godot"]
 ---
 
@@ -18,6 +18,7 @@ The disciplined debugging loop for Godot/Summer projects. Read the error before
 ## When to use this skill
 
 - The user says "it crashes", "it broke", "throws an error", "doesn't work", "freezes", "wrong behavior".
+- The user invokes `/summer debug`, asks for a support report, or wants something they can send to Summer.
 - The user pastes a stack trace.
 - A previous build or test step failed and the user wants to fix it.
 
@@ -35,6 +36,27 @@ The disciplined debugging loop for Godot/Summer projects. Read the error before
 
 Do not skip steps. Do not loop back to "Hypothesize" without re-running the cheap diagnostic.
 
+### 0. Support report mode
+
+If the user asks for `/summer debug`, "send this to Summer", "make a report", or they are stuck in Codex/cloud/another agent environment, create a portable report first:
+
+```
+summer_create_debug_report({
+  issue: "<one-sentence user symptom>",
+  include_play_session: <true only when the issue appears during runtime>
+})
+```
+
+Tell the user where the Markdown file was written and remind them to review local paths and stack traces before sending. Then continue the normal debug loop only if they also asked you to fix the bug.
+
+Fallback when the MCP tool is not available but shell is available:
+
+```
+summer debug "<one-sentence user symptom>"
+```
+
+Add `--play` only when the issue appears after pressing Play.
+
 ### 1. Listen
 
 Ask the user **one** focused question and wait for the answer:

package/skills/deployment/remote-deploy/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: remote-deploy
+description: Use when the user wants to run or test the game on a real target instead of the editor — a phone, tablet, or another computer ("deploy to my phone", "run on device", "test on Android/iOS", "remote deploy", "one-click deploy", "play on hardware"). Covers the topnav Remote Deploy button, runnable export presets, export templates, and on-device remote debugging. Use when the Remote Deploy button is greyed out and the user wants to know why.
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: deployment
+user-invocable: true
+allowed-tools: Read Grep Edit summer_project_setting summer_get_diagnostics summer_get_console summer_get_script_errors
+paths: ["project.godot", "export_presets.cfg"]
+---
+
+# /remote-deploy — Test the Game on a Real Device
+
+## Overview
+
+Remote Deploy runs the game on an actual target device — a phone, tablet, or another machine — instead of inside the editor. It exports a **debug** build, installs and launches it on the device, and connects the running game back to the editor's debugger so the Output panel, errors, breakpoints, and profiler all work exactly like a local run.
+
+**Core principle:** Remote Deploy is "Play, but on the hardware." Same debug loop, real device.
+
+It is **not** the same as two neighbours:
+
+| Action | What it does | Use it for |
+|---|---|---|
+| **Play** (▶) | Runs in the editor (embedded or windowed) | Fast iteration on the dev machine |
+| **Remote Deploy** | Debug build → installs + runs on a device, remote-debugged | Testing real input/perf/screen on hardware |
+| **export-and-ship** (`summer:export-and-ship`) | Final, signed distribution builds | Submitting to stores |
+
+If the user wants a release build for Steam / itch / the App Store, that is `summer:export-and-ship`, not this.
+
+## Where it is in the UI
+
+- **Agent-layout topnav:** the button with the remote-play icon, immediately right of the **Play/Stop** button and the **`▾`** run-options dropdown. Hover tooltip reads **"Remote Deploy"**.
+- Clicking it opens a **dropdown of detected targets**, grouped by platform (e.g. an `Android` header with each connected device under it). Picking a target deploys and runs there.
+- It is **disabled (greyed out)** with the tooltip **"No Remote Deploy export presets configured."** until the prerequisites below are met. A greyed button is the #1 thing users ask about — it almost always means "no runnable preset or no device detected," not a bug.
+
+## Prerequisites — what makes the button light up
+
+The button auto-enables the moment a runnable preset **and** at least one detected target both exist for the same platform.
+
+| Requirement | How to satisfy it | Why it matters |
+|---|---|---|
+| A **runnable export preset** for the platform | Project → Export → add a preset (Android / iOS / Web / desktop) → toggle **Runnable** on | The dropdown only lists platforms that have a *runnable* preset. A preset that exists but isn't marked Runnable does **not** count. |
+| **Export templates** installed for that platform/engine version | Export dialog → **Manage Export Templates…** → download | Needed to actually build the debug build when you deploy. |
+| The platform **toolchain** | Android: Android SDK + `adb` + a debug keystore. iOS: Xcode + signing. Web: any browser. | The deploy step shells out to these; without them the build can't be installed/run. |
+| A **detected target** | Android: a device with USB debugging enabled (and authorized), or a running emulator. iOS: a connected, trusted device. Web: the built-in **"Run in Browser"** target. | The button enables only when ≥1 target is reported for a runnable platform. |
+
+**Important nuance:** the button does **not** pre-check that templates/toolchain are installed. Enable state is gated only on *runnable preset + detected target*. If templates or the toolchain are missing, the deploy **fails at run time** and the errors appear in a result dialog. So:
+
+> **Runnable preset + a detected device make the button appear/enable. Installed export templates make the deploy actually succeed.**
+
+This matters when guiding a user mid-setup (e.g. building out a mobile flow): you can see the button enable as soon as a phone is plugged in and the preset is Runnable, even before templates finish downloading.
+
+## How it works (the flow)
+
+1. The editor continuously polls the export platforms and rebuilds the dropdown: each runnable platform, with each of its detected devices listed underneath.
+2. The user picks a target. Godot exports a **debug** build for that preset.
+3. The build is installed and launched on the device (e.g. `adb install` + launch for Android).
+4. The running game opens a **remote-debug** connection back to the editor — Output, the debugger, and the profiler reflect the on-device session. Stop it from the editor like any normal run.
+5. Any export/deploy error (missing template, no toolchain, unsigned build, device went away) is surfaced in a **result dialog**. Read it; it names the prerequisite to fix.
+
+## Mobile quick paths
+
+**Android**
+1. Enable Developer Options → USB debugging on the phone; plug it in; accept the "Allow USB debugging?" prompt.
+2. Confirm `adb devices` lists it as `device` (not `unauthorized`).
+3. Project → Export → Android preset → **Runnable** on; install Android export templates.
+4. The phone appears in the Remote Deploy dropdown → pick it.
+
+**iOS**
+1. Connect and trust the device; ensure a valid signing team in the iOS preset.
+2. Xcode command-line tools installed; iOS export templates installed.
+3. The device appears in the dropdown → pick it.
+
+**Web (sanity check on the target browser)**
+1. Web (HTML5) preset → **Runnable** on; Web export templates installed.
+2. Pick **"Run in Browser"** from the dropdown.
+
+## Guiding the user (orchestrator playbook)
+
+When a user says "deploy to my phone" / "run this on device" and the button is greyed:
+
+1. **Check the build is healthy first** — a project with script errors won't export.
+   - `summer_get_script_errors` and `summer_get_diagnostics` clean? If not, fix those before anything else.
+   - `summer_get_console` for "import failed" noise.
+2. **Confirm a runnable preset exists** for the target platform — Read/Grep `export_presets.cfg` for the platform and a `runnable=true` entry. If missing, walk them through Project → Export → add preset → mark Runnable.
+3. **Confirm the main scene is set** — `summer_project_setting` / `project.godot` `application/run/main_scene`. A deploy to a blank main scene launches to nothing.
+4. **Confirm export templates + toolchain** for the platform are installed (Manage Export Templates; adb/Xcode/browser).
+5. **Confirm a device is detected** — plugged in, debugging enabled, authorized.
+6. Then point them at the topnav **Remote Deploy** button → pick the device.
+
+Order matters: preset → templates/toolchain → device. Resolve them top-down; the button enables as soon as preset + device are both true, and the deploy succeeds once templates/toolchain are present.
+
+## Common mistakes
+
+- **Confusing it with shipping.** Remote Deploy makes *debug* builds for testing. Store/distribution builds are `summer:export-and-ship`.
+- **Preset exists but isn't Runnable** → button stays greyed. The Runnable toggle is the gate, not the preset's existence.
+- **Expecting it to work without export templates** → button may be enabled (device detected) but the deploy then fails in the result dialog. Install templates.
+- **Android device `unauthorized`** in `adb devices` → the device won't show as a target. Re-accept the USB-debugging prompt on the phone.
+- **Trying to script it via MCP** — there is no `summer_*` tool that triggers Remote Deploy; it is a UI action. The orchestrator's job is to get the prerequisites green and point the user at the button.
+
+## Quick reference
+
+| Button state | Meaning | Fix |
+|---|---|---|
+| Greyed, "No Remote Deploy export presets configured." | No runnable preset **or** no detected device | Add a Runnable preset; connect/authorize a device |
+| Enabled, dropdown lists devices | Ready to deploy | Pick a device to build + run |
+| Deploy fails in result dialog | Templates/toolchain/signing/device issue | Read the dialog; install the named missing piece |

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

@@ -146,21 +146,21 @@ Compose the 1-page brief. Format:
 
 ### 9. Ask permission and write
 
-**Preferred (Summer MCP + host file write):**
+**Preferred (Summer MCP):**
 
 > May I create `.summer/GameSoul.md` with this brief?
 
-On yes, use `Write` (host file tool) — `.summer/GameSoul.md` is plain markdown, no engine import needed:
+On yes, use guarded `summer_write_file` — `.summer/GameSoul.md` is plain markdown but still belongs to the bound project:
 
 ```
-Write .summer/GameSoul.md
+summer_write_file path="res://.summer/GameSoul.md" create_only=true content="<brief>"
 ```
 
 If `.summer/GameSoul.md` already exists, read it first, show what would change, ask:
 
 > `.summer/GameSoul.md` already exists. May I overwrite it, or merge into a "Revision 2" section below the existing brief?
 
-**Fallback (no host write tool — agent is read-only):**
+**Fallback (Summer MCP unavailable — agent is read-only):**
 
 Print the full brief to the user with the explicit instruction:
 

package/skills/scene-and-project/summer-cloud/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: summer-cloud
+description: Use when the user wants to sync a Summer Engine project, move it to another machine or laptop, share the exact bytes with a collaborator, back up big generated assets that do not belong in git, restore an earlier version, or wants a safety net before a risky bulk operation. Trigger on "sync", "Summer Cloud", "cloud push", "cloud pull", "move to another machine", "other computer", "second machine", "share project", "back up assets", "big assets", "collaborator", "teammate", "restore a version", "checkpoint", "conflict".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: scene-and-project
+user-invocable: true
+allowed-tools: Read summer_cloud_init summer_cloud_status summer_cloud_push summer_cloud_pull summer_cloud_restore summer_cloud_checkpoints summer_cloud_conflicts
+paths: ["summer-cloud.json"]
+---
+
+# Summer Cloud: Project Sync
+
+## What Summer Cloud is
+
+Summer Cloud is content-addressed sync for a whole Summer Engine project. Every tracked file is identified by its sha256 hash, so identical bytes upload once and dedupe across versions and projects. It syncs the entire project tree at once (code, scenes, resources, import sidecars, and the heavy binary assets), not a hand-picked folder. The only git-tracked cloud artifact is a tiny `summer-cloud.json` binding at the project root; all real sync state lives under `.summer/local/cloud/` and is never committed.
+
+This is not a folder backup and it is not a git replacement. Code that lives happily in git can stay in git. What Cloud adds is a way to move the large generated binaries (models, textures, audio, video) that do not belong in a git repo, and to keep a project byte-identical across machines and collaborators. Git and Cloud can run side by side; the binding file merges trivially.
+
+## When to offer it (proactive triggers)
+
+Surface Cloud, do not wait to be asked, when any of these are true:
+
+- The project has heavy generated assets (large `.glb`, `.png`, `.wav`, `.ogg`, `.mp4` under `assets/`) that should not go into git. Cloud is how those travel.
+- The user mentions a second machine, a laptop, "my other computer", or working from somewhere else. Cloud is how the same bytes show up there.
+- A teammate or collaborator needs the exact same project state. Add them as a collaborator and they pull.
+- A risky bulk operation is about to run (mass asset import, a large refactor, a destructive cleanup). A push first gives a restorable version to fall back to.
+
+If none of these apply, do not push Cloud on the user. It is a tool for a real need, not a default step.
+
+## Command and tool surface
+
+| Action | CLI | MCP tool |
+|---|---|---|
+| Enable Cloud for this project | `summer cloud init` | `summer_cloud_init` |
+| Show what would push/pull | `summer cloud status` | `summer_cloud_status` |
+| Upload local changes | `summer cloud push` | `summer_cloud_push` |
+| Download remote changes | `summer cloud pull` | `summer_cloud_pull` |
+| Restore an earlier version or a local checkpoint | `summer cloud restore --version N` / `--checkpoint <stamp>` | `summer_cloud_restore` |
+| List local pre-sync checkpoints | `summer cloud checkpoints` | `summer_cloud_checkpoints` |
+| List or recover conflict sets | `summer cloud conflicts list` / `restore <path>` | `summer_cloud_conflicts` |
+
+Run `summer cloud status` before any push or pull. It reports the file counts, what would move in each direction, and whether any conflict sets are waiting. Never push blind.
+
+## The safety model (respect this)
+
+The whole point of Cloud is that user data is never destroyed silently. The rules below are how that holds. Do not work around them.
+
+- **Every push is a restorable version.** The server keeps the version history within the retention window. Version numbers are never reused. If a bad push lands, `summer cloud restore --version N` brings the project back as a new head version, then pulls it locally.
+- **Local checkpoints come before destructive applies.** Before a pull modifies or deletes any existing file, the client writes a full-tree checkpoint into the project's local SummerGit repo. `summer cloud checkpoints` lists them; `summer cloud restore --checkpoint <stamp>` rolls back. Note the honest caveat the restore prints: it restores bytes but does not delete files a bad sync added, so review and remove any extras it lists.
+- **Large deletions are gated.** A push that would delete many cloud files (more than 10 files, or at least 20% of the tracked tree, or the entire tree) requires `confirmDeletes: true` on the MCP tool (or `--confirm-deletes` on the CLI). Never pass it blindly. First run `summer cloud status`, read the delete count out loud to the user, and only set the flag once they confirm that count is what they intend. If the local tree reads as completely empty against a non-empty base (a wrong directory or an unmounted volume), the push aborts outright and no flag can force it.
+- **Conflicts become conflict sets, never silent overwrites.** Concurrent edits to the same file are resolved deterministically: the first sync to land wins the canonical path (this is "first to sync wins", not "most recent save wins", because there are no wall clocks). The losing bytes are preserved, never discarded, in a local conflict set and backed up to the cloud. Surface them with `summer cloud conflicts list` and recover any with `summer cloud conflicts restore <path>`, which re-enters the file as a fresh edit. `project.godot` is the one file merged key by key rather than whole-file, so input actions and autoloads from both sides survive.
+- **A modify always beats a delete.** If one side edited a file and the other deleted it, the edited file is kept and the deletion is dropped, with a notice. Offline work is never lost to someone else's delete.
+
+## First sync and the bootstrap choice
+
+When a project already has files on both the local disk and in the cloud but this machine has no sync base (for example a fresh git clone of a project that was cloud-enabled elsewhere), auto-sync will not run. The tool returns a bootstrap choice. Present it to the user and let them pick:
+
+- `keep-cloud` (pull): replace local divergent files with the cloud version. Local divergent files are checkpointed first.
+- `keep-local` (push): make the local tree the new cloud version.
+- `merge`: converge automatically where hashes already match (usually most files); the rest get normal conflict treatment.
+
+If the project folder was moved or Finder-copied, sync blocks until you confirm whether to adopt the new path (`adoptPath: true`) or fork it into a separate cloud project. Two folders must never fight over one project.
+
+## Honest v1 limits
+
+State these plainly when they are relevant; do not paper over them.
+
+- **One linear head per project. No branches yet.** There is a single history line. If a user wants an isolated line to experiment with assets, fork to a separate cloud project: delete `summer-cloud.json` and run `summer cloud init` to create a new binding. Because storage is content-addressed and dedupes, the fork is nearly free in storage.
+- **Per-file cap is 4.995 GiB.** A single file larger than that is rejected with a clear error. There is no multipart path in v1.
+- **No resumable uploads.** A dropped connection mid-upload on a multi-GiB file restarts that file from zero. For large pushes, prefer a stable connection.
+- **No locking or presence.** Two people editing the same binary at once produces a conflict (recoverable, never lost), not a lock.
+- **Git branch switches read as edits.** Switching git branches on a cloud-synced project looks like local edits to Cloud and will push as such. Guidance: sync before and after branch operations, or keep cloud projects on one branch.
+- **Storage rides the plan tiers.** Free, Pro, Pro Plus, and Ultra each have a storage cap. A push past the cap returns a quota error pointing at the upgrade path; surface that to the user rather than retrying.
+
+## Hard rule: drive everything through the CLI or MCP
+
+Never hand-edit anything under `.summer/local/cloud/` (base, journal, hash cache, staging, checkpoints, conflict sets). That state is the integrity model; editing it by hand can corrupt the 3-way base and cause data loss on the next sync. The only file you ever touch directly is the tiny git-tracked `summer-cloud.json` binding, and even then only to remove `pinnedVersion` for a read-only checkout or to delete it when intentionally forking. Every real operation goes through `summer cloud ...` or the `summer_cloud_*` tools.
+
+## Typical flows
+
+- **Move to a second machine.** On machine A: `summer cloud init`, then `summer cloud push`. Commit `summer-cloud.json` so it travels with git, or share the project id. On machine B: get the project (git clone or copy), then `summer cloud pull`. If both sides already had files, take the bootstrap choice.
+- **Back up big assets before a bulk import.** `summer cloud status`, then `summer cloud push`. The resulting version is the restore point.
+- **Recover from a bad change.** `summer cloud checkpoints` (or `summer cloud status` for cloud versions), then `summer cloud restore --checkpoint <stamp>` for local-only work or `--version N` for a pushed version. Remove any extra files the restore lists.
+
+## Fallback
+
+If the MCP tools are unavailable, run the `summer cloud ...` CLI commands directly. The CLI and MCP tools are one to one and share the same engine. If neither is available, the project is not set up; point the user at `summer login` (Cloud auth comes from the login token) and `summer cloud init`.
+
+## Collaborative protocol
+
+Push and pull move bytes and can replace files. Always run `summer cloud status` and say what will move before you push or pull: "Push will upload 4 files and delete 0. OK to push?" For any gated deletion, state the exact count and get explicit confirmation before setting `confirmDeletes`. See `../../references/collaborative-protocol.md`.

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.