summer-engine 2.8.2 → 3.1.0

package/references/mcp-tools-reference.md

@@ -1,199 +0,0 @@
-# Summer MCP Tools — Canonical Reference
-
-> Use this as the single source of truth for which Summer MCP tool to call. Skills should reference tool names exactly as written here.
-
-## When to use Summer MCP vs. host tools
-
-**Use Summer MCP for** anything that needs the live editor or Godot's import pipeline:
-- Scene graph mutation (`.tscn`)
-- Node properties and resources (`.tres`)
-- Project settings (`project.godot`) and InputMap
-- Asset import (Godot's import pipeline must run)
-- Play / stop / runtime state
-- Diagnostics, console, debugger output, script errors
-- Project text reads and guarded writes (`.gd`, `.cs`, `.tscn`, `.tres`, JSON, docs, config)
-
-**Use host tools for** git, shell, grep, and non-project work. External host file writes bypass Summer's project-identity, sha256, and editor-reload safeguards and should not be used for project mutations while MCP is available.
-
-**Rule of thumb:** project reads/writes go through Summer; live hierarchy/inspector changes use scene tools; process-level work remains with the host.
-
-## Tool surface (62 tools)
-
-### Project files (3)
-
-| Tool | Use |
-|---|---|
-| `summer_read_file` | Read project text plus a full-file sha256 receipt. |
-| `summer_write_file` | Create-only or sha256-guarded complete file write. |
-| `summer_replace_text` | Unique (or explicit replace-all) text mutation with read/sha guard. |
-
-### Scene graph (11)
-
-| Tool | Use |
-|---|---|
-| `summer_get_scene_tree` | Read current scene graph. Always do this before mutating. |
-| `summer_open_main_scene` | Open the project's main scene. |
-| `summer_open_scene` | Open a specific `.tscn`. |
-| `summer_create_scene` | Create a new scene. |
-| `summer_instantiate_scene` | Add an existing scene or 3D model as a child node. |
-| `summer_inspect_node` | Read a single node's properties. |
-| `summer_add_node` | Add a node to the explicit `scenePath`; the tab need not be open. |
-| `summer_remove_node` | Remove a node from the explicit `scenePath`. |
-| `summer_replace_node` | Swap a node's type in the explicit `scenePath`, preserving children. |
-| `summer_select_node` | Set editor selection (visual feedback for the user). |
-| `summer_save_scene` | Explicitly save/save-as a `scenePath`; mutation tools already append one final save. |
-
-### Properties / resources (4)
-
-| Tool | Use |
-|---|---|
-| `summer_set_prop` | Set a typed property in an explicit `scenePath` using Godot's `str_to_var()`. |
-| `summer_set_resource_property` | Set a nested resource property in an explicit `scenePath`. |
-| `summer_inspect_resource` | Read a resource's properties. |
-| `summer_connect_signal` | Wire a signal between nodes. |
-
-### Project & input (2)
-
-| Tool | Use |
-|---|---|
-| `summer_project_setting` | Modify `project.godot` settings (rendering, physics). |
-| `summer_input_map_bind` | Bind input actions in InputMap. Folds in the legacy `add_action` step. |
-
-### Import pipeline (2)
-
-| Tool | Use |
-|---|---|
-| `summer_import_from_url` | Download a `.glb`/`.png`/etc and run Godot's full import pipeline. |
-| `summer_import_from_url_batch` | Same, batched (single filesystem scan). |
-
-### Play / runtime (3)
-
-| Tool | Use |
-|---|---|
-| `summer_play` | Run the game. |
-| `summer_stop` | Stop the running game. |
-| `summer_is_running` | Check play state before deciding to call `summer_stop`. |
-
-### Visual capture (1)
-
-| Tool | Use |
-|---|---|
-| `summer_screenshot` | Capture a frame and return it as an image the agent sees directly — editor viewport (`target:"viewport"`, default; no play needed) or running game (`target:"game"`). Use to visually verify scene layout, asset placement, scale, framing, lighting, or runtime state. On macOS the running game is a floating window that can't be captured; prefer `viewport`. |
-
-### Diagnostics (7)
-
-| Tool | Use |
-|---|---|
-| `summer_create_debug_report` | Create a support-ready Markdown report for `/summer debug`. |
-| `summer_get_diagnostics` | Aggregate error/warning summary. Call after every change. |
-| `summer_get_console` | Engine output panel. |
-| `summer_clear_console` | Clear before a fresh play, so post-run output is clean. |
-| `summer_get_debugger_errors` | Runtime errors with stack traces. |
-| `summer_get_debugger_warnings` | Runtime warnings from the debugger panel. |
-| `summer_get_script_errors` | Script compilation errors. |
-
-### Asset library (6)
-
-| Tool | Use |
-|---|---|
-| `summer_search_assets` | Free public asset search (community library + user's own). Sources: `library`, `community`, `my_assets`, `all`. |
-| `summer_list_my_assets` | List/search the signed-in user's generated and uploaded assets. Empty query lists recent assets. |
-| `summer_get_asset` | Fetch one exact asset by ID with file URL, download URL, viewer URL, metadata, license, and visibility. |
-| `summer_get_asset_download_url` | Get the primary or thumbnail download URL for a specific asset. Stable shape for future signed URLs. |
-| `summer_import_asset` | Search, choose the top match, download, run Godot import, and optionally instantiate 3D models. |
-| `summer_import_asset_by_id` | Import one exact Summer asset ID. Use after generation jobs or when the user selects a specific asset. |
-
-### Asset generation (5 — metered)
-
-| Tool | Use |
-|---|---|
-| `summer_generate_image` | AI image gen. |
-| `summer_generate_3d` | Image-to-3D. |
-| `summer_generate_audio` | SFX / music gen. |
-| `summer_generate_video` | Video gen. |
-| `summer_generate_motion` | Generate/apply 3D skeletal motion from a rigged asset. |
-
-### Job tracking (2)
-
-| Tool | Use |
-|---|---|
-| `summer_check_job` | Poll a generation job. |
-| `summer_batch` | Run multiple ops as a transaction. |
-
-### Meta (3)
-
-| Tool | Use |
-|---|---|
-| `summer_start_game_task` | Route a user goal into the right workflow, skills, MCP tool groups, asset policy, gates, and verification path. |
-| `summer_get_project_context` | Project, scene, and `.summer` memory summary — call at start of session. |
-| `summer_get_agent_playbook` | Daily operating contract — call at start of session. |
-
-### Cloud sync (7)
-
-| Tool | Use |
-|---|---|
-| `summer_cloud_init` | Enable Summer Cloud for a project. |
-| `summer_cloud_status` | Show Summer Cloud sync status. |
-| `summer_cloud_push` | Push local project changes to Summer Cloud. |
-| `summer_cloud_pull` | Pull Summer Cloud changes into the local project. |
-| `summer_cloud_restore` | Restore a retained cloud version, or a local pre-sync checkpoint. |
-| `summer_cloud_checkpoints` | List local pre-sync checkpoints. |
-| `summer_cloud_conflicts` | List conflict sets, or restore a preserved conflict file. |
-
-### Creator platform (4)
-
-| Tool | Use |
-|---|---|
-| `summer_creator_publish` | Compute the exact `.pck` digest and size, require user confirmation, then run versioned prepare → write-once upload → finalize. The server independently verifies `publish` scope, ownership, bytes, and review state. |
-| `summer_creator_releases` | List real creator-owned releases from `summer.creator.v1`, with opaque cursor pagination. |
-| `summer_creator_logs` | Read runtime logs for a project or release. Remains fail-closed until a durable platform log source exists. |
-| `summer_creator_config` | Read or confirm updates to the shared non-secret `~/.summer/config.json`. It never accepts or returns tokens. |
-
-## Common pattern
-
-Every scene-touching skill should follow this loop:
-
-1. `summer_start_game_task` — route the goal into skills/tools/gates.
-2. `summer_get_project_context` — orient.
-3. `summer_get_agent_playbook` — read the rules.
-4. Resolve the exact `res://` scene path; open it only for an intentional current-tab read/UI action.
-5. Pass that `scenePath` to mutations (`summer_add_node`, `summer_set_prop`, `summer_connect_signal`, ...).
-6. Mutation tools append one final `SaveScene`; use `summer_save_scene` directly only for a standalone save/save-as.
-7. `summer_get_script_errors` — catch GDScript breakage.
-8. `summer_play` → `summer_get_debugger_errors` → `summer_screenshot` (see what's on screen) → `summer_stop` if verifying runtime.
-
-Every asset-generation skill should follow this loop:
-
-1. `summer_search_assets` or `summer_list_my_assets` — reuse before generating when reasonable.
-2. `summer_generate_image` / `summer_generate_3d` / `summer_generate_audio` — metered creation.
-3. `summer_check_job` if the generation was async.
-4. `summer_get_asset` — resolve the returned `assetId`, `rigAssetId`, or `animationAssetId`.
-5. `summer_import_asset_by_id` — import the exact result into Godot's pipeline.
-6. `summer_get_asset_download_url` — only when the user explicitly wants a downloadable file/link.
-
-## summer_set_resource_property — nested properties
-
-Use it to reach a property *of a resource attached to a node* — mesh size, shape radius, material colour — the thing `summer_set_prop` cannot reach.
-
-```
-summer_add_node(parent="/", type="MeshInstance3D", name="Box", scenePath="res://main.tscn")
-summer_set_prop(path="Box", key="mesh", value="BoxMesh", scenePath="res://main.tscn")
-summer_set_resource_property(
-    nodePath="Box", resourceProperty="mesh", subProperty="size",
-    value="Vector3(2, 2, 2)", scenePath="res://main.tscn")
-```
-
-`nodePath`, `resourceProperty` and `subProperty` are all required and canonical. There is no dotted `"mesh.size"` form.
-
-**Inline `sub_resource` targets work.** An earlier revision of this file claimed the op silently fails on an inline sub-resource and told you to save the resource as a standalone `.tres` first. That was wrong, and it propagated into nine skills. The implementation reads `node->get(resourceProperty)` and sets the sub-property on whatever comes back (`modules/1summer_engine/editor/ops/scene_ops.cpp:1273-1400`) — there is no inline-versus-external branch anywhere in it. The canonical example in the shipped `summer_batch` description does exactly this against an inline mesh.
-
-Failures are explicit, never silent:
-
-| Error | Meaning |
-|---|---|
-| `no edited scene` | Nothing open — pass `scenePath`. |
-| `node not found: <path>` | `nodePath` is wrong; it is relative to the scene root. |
-| `property is not a resource` | `resourceProperty` names a plain value, not a resource. |
-| `resource is null` | The node has the property but nothing is assigned yet. Assign it first. |
-
-If you get none of those and the value still did not change, that is a bug worth reporting — not expected behaviour to design around.

package/references/template-registry.md

@@ -1,73 +0,0 @@
-# Template Registry
-
-> Skills cross-link to template repos via the `template-id` frontmatter field.
->
-> **This file is a convenience snapshot, not the source of truth.** Templates are discovered live from the GitHub org, so this table goes stale the moment a template is added. Ask the CLI instead:
->
-> ```bash
-> summer list templates
-> ```
-
-## How discovery actually works
-
-`summer list templates` queries `github.com/SummerEngine` for repos named `template-*`, and **strips the `template-` prefix to produce the slug** (`src/lib/remote-templates.ts`). So the repo `template-2d-platformer` is created with:
-
-```bash
-summer create 2d-platformer my-game
-```
-
-There is no `summer template clone` command. `summer create <slug> [dir]` is the only bootstrap path, and it takes the stripped slug, not the repo name.
-
-## Snapshot — verified against `summer list templates`
-
-Built-in, no download required:
-
-| slug | Description |
-|---|---|
-| `empty` | Empty 3D project with just a root node |
-| `3d-basic` | 3D scene with camera, light, and floor |
-
-Community templates, all at `https://github.com/SummerEngine/template-<slug>`:
-
-| slug | Description |
-|---|---|
-| `2d-brario-platformer` | 2D platformer starter |
-| `2d-grid-puzzle` | Grid-based puzzle starter |
-| `2d-plants-and-zombies-tower-defense` | Lane tower-defense starter |
-| `2d-platformer` | 2D platformer starter (TileMap, CharacterBody2D, parallax) |
-| `2d-rpg` | 2D top-down RPG starter (built on GDQuest's open-source work) |
-| `2d-vampire-survivor-roguelike` | Survivors-like roguelike starter |
-| `3d-fps-old-school` | Retro first-person shooter starter |
-| `3d-fps-simple-animated-npc` | FPS starter with an animated NPC |
-| `3d-lan-multiplayer-starter` | 3D LAN multiplayer starter (built on GDQuest's open-source work) |
-| `3d-open-world-explore-tps` | Third-person open-world exploration starter |
-| `3d-racing-game` | Racing starter |
-| `3d-royale-clash-type` | Auto-battler / lane-pusher starter |
-| `3d-third-person-controller` | 3D third-person character controller (built on GDQuest's open-source work) |
-| `3d-voxel-sandbox` | Voxel sandbox (chunked world, face culling, mining/building, seeded gen) |
-
-If a slug you expect is missing here, it is this file that is out of date, not the CLI. Run `summer list templates`.
-
-## Convention
-
-Each template is its own GitHub repo under the `SummerEngine` org, MIT licensed, kept small (< 50 MB), and named `template-<slug>`. Templates ship working code; skills describe patterns. A skill links to the matching template via:
-
-```markdown
-## Want a working starter?
-
-This skill describes the pattern. For a runnable project, use the template:
-
-→ **template-id**: `template-2d-platformer`
-→ **Repo**: https://github.com/SummerEngine/template-2d-platformer
-→ **Bootstrap**: `summer create 2d-platformer my-game`
-```
-
-## Linter check
-
-The `workflow/skill-test/SKILL.md` static linter validates that any `template-id:` declared in a skill's frontmatter exists in the table above. Because the table is a snapshot, a linter failure may mean the table is stale rather than the skill being wrong — check `summer list templates` before editing the skill.
-
-## Adding a template
-
-1. Create a new repo under the `SummerEngine` org named `template-<slug>`, MIT license.
-2. It appears in `summer list templates` automatically — no registration step.
-3. Add it to the snapshot above and reference the `template-id` from any relevant skill.

package/skills/README.md

@@ -1,103 +0,0 @@
-# Summer Skill Library
-
-The canonical agent-readable game-dev knowledge source for Claude Code, Cursor, Codex, and Windsurf.
-
-When an agent is asked to make a game in Summer Engine, this is what it reads to learn how.
-
-## Layout
-
-```
-summer-cli/
-├── .claude-plugin/plugin.json    # the registry (skills: array). Sibling Codex/Cursor manifests mirror it.
-├── references/                   # cross-skill shared docs (sibling of skills/)
-│   ├── godot-version.md
-│   ├── mcp-tools-reference.md
-│   ├── collaborative-protocol.md
-│   ├── template-registry.md
-│   ├── summer-folder.md
-│   └── gd-style.md
-├── tests/
-│   ├── runner.md                 # how /skill-test works
-│   └── specs/                    # behavioral specs per skill
-└── skills/
-    ├── README.md                 # this file
-    ├── workflow/                 # process skills (brainstorming, debugging, planning, etc.)
-    │   ├── using-summer/
-    │   ├── skill-create/
-    │   ├── skill-improve/
-    │   ├── skill-test/
-    │   ├── brainstorming/
-    │   ├── investigating-bugs/
-    │   ├── verification-before-completion/
-    │   ├── writing-plans/
-    │   ├── dispatching-parallel-agents/
-    │   ├── writing-skills/
-    │   ├── playtesting-a-feature/
-    │   ├── debugging-game-feel/
-    │   └── diagnosing-perf-regressions/
-    └── <category>/<skill>/       # gamedev domain skills
-        ├── SKILL.md              # < 500 lines, frontmatter + body
-        ├── reference.md          # optional, loaded on demand
-        └── examples/             # optional, working snippets
-```
-
-## Categories (21)
-
-`workflow` (process discipline) plus 20 gamedev domains: `character-controllers`, `gameplay-mechanics`, `scripting-patterns`, `scene-and-project`, `rendering-and-lighting`, `shaders`, `visual-effects`, `post-processing`, `animation`, `audio`, `physics`, `multiplayer-and-networking`, `ai-and-npcs`, `level-design`, `performance`, `ui-and-ux`, `asset-pipeline`, `input-and-controls`, `debugging`, `deployment`.
-
-Folder structure is for humans only — Claude resolves skills as `summer:<skill-name>` regardless of category nesting.
-
-## Standard
-
-Adopts the **Anthropic Agent Skills open standard** (`agentskills.io`). Frontmatter:
-
-```yaml
----
-name: <kebab-case>
-description: <when-to-use, key trigger phrases first>
-license: MIT
-compatibility: [Cursor, Claude Code, Windsurf, Codex]
-category: <one of the 20>
-template-id: <optional, resolved against references/template-registry.md>
-allowed-tools: Read Grep summer_add_node summer_set_prop ...
-paths: ["**/*.gd", "**/*.tscn"]
----
-```
-
-Cross-portable. Cursor / Codex / Windsurf understand the same SKILL.md.
-
-## Authoring rules
-
-1. **SKILL.md ≤ 500 lines.** Push detail into `references/`. Progressive disclosure.
-2. **MCP-preferred + file-edit-fallback.** Every code-touching skill must show both paths so the skill works without Summer MCP installed.
-3. **Collaborative protocol.** "May I write…?" before any user-visible mutation. See `../references/collaborative-protocol.md`.
-4. **Template cross-link.** When a working starter exists, link via `template-id` and the section "Want a working starter?".
-5. **Test spec.** Every non-`_meta` skill ships `tests/spec.md` with at least one Test Case.
-
-## Adding a new skill
-
-```
-/skill-create
-```
-
-(See `workflow/skill-create/SKILL.md`.)
-
-## Testing
-
-```
-/skill-test <name>           # static lint
-/skill-test <name> spec      # behavioral spec runner
-/skill-test audit            # whole-library audit
-/skill-improve <name>        # parallel-eval harness for iteration
-```
-
-(See `workflow/skill-test/SKILL.md` and `tests/runner.md`.)
-
-## What ships today
-
-The `skills:` array in `.claude-plugin/plugin.json` is the registry — what ships, ships there. New skills are added via `/skill-create` (see `workflow/skill-create/SKILL.md`).
-
-## See also
-
-- [Architecture spec](../../../publicsummerengine/Docs/superpowers/specs/2026-05-05-skill-library-architecture.md) (lives in publicsummerengine for spec history)
-- [Research notes](../../../publicsummerengine/Docs/superpowers/research/2026-05-05-skill-library-research.md)

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

@@ -1,92 +0,0 @@
----
-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`.