Improve MCP onboarding for local and weak models

.opencode/INSTALL.md

@@ -1,75 +1,191 @@
-# Installing Summer in OpenCode
+# OpenCode setup
 
-OpenCode loads plugins as JavaScript modules from `node_modules`, so installation = `npm install` of this package into your OpenCode project.
+Summer Engine works in OpenCode through MCP. Installing `summer-engine` as an
+OpenCode plugin is not required.
 
-## Quick install
+## Fast path for OpenCode
 
-From your OpenCode project root, run:
+From the Summer project root, configure OpenCode itself:
 
 ```bash
-npm install --save-dev summer-engine
+npx -y summer-engine@latest setup opencode --yes --force --project "$PWD"
 ```
 
-Then add the plugin to your `opencode.json`:
+This writes project-scoped MCP config and Summer guidance, preserves unrelated
+OpenCode config, and does not add or change any model provider. OpenCode
+receives the same complete Summer MCP tool registry as every other client.
 
-```json
-{
-  "plugin": ["summer-engine"]
-}
+Restart OpenCode after setup. A running OpenCode process does not discover a
+new MCP server or newly installed guidance from config written mid-session.
+
+## Optional recipe: OpenCode with LM Studio
+
+1. In LM Studio, load a tool-calling model, set its context to at least 64k,
+   and start the local server.
+2. From the Summer project root, get the exact loaded model ID:
+
+   ```bash
+   curl -fsS http://127.0.0.1:1234/v1/models
+   ```
+
+3. Configure both the LM Studio provider and Summer MCP in one command. Replace
+   the example model ID with the `id` returned above:
+
+   ```bash
+   npx -y summer-engine@latest setup opencode --yes \
+     --project "$PWD" \
+     --lm-studio-model "google/gemma-4-26b-a4b-qat" \
+     --lm-studio-vision \
+     --json
+   ```
+
+When OpenCode setup receives `--project` and no explicit `--scope`, it writes
+`./opencode.json`. The generated config:
+
+- selects the loaded LM Studio model through its OpenAI-compatible endpoint;
+- declares image input when `--lm-studio-vision` is present, allowing OpenCode
+  to pass Summer screenshot results to a vision-capable model;
+- uses a 131k context and disables hidden reasoning by default so small local
+  models do not spend their output budget before calling a tool;
+- starts Summer MCP with the complete tool registry and an absolute project
+  binding;
+- preserves unrelated OpenCode providers, models, plugins, and MCP servers.
+
+When testing a local npm tarball, use the local package name rather than the
+published `@latest` spec:
+
+```bash
+npm install --save-dev ./summer-engine-2.7.0.tgz
+npx summer setup opencode --yes \
+  --project "$PWD" \
+  --lm-studio-model "google/gemma-4-26b-a4b-qat" \
+  --lm-studio-vision \
+  --local-dev \
+  --json
 ```
 
-OpenCode resolves `summer-engine` via the package's `main` field, which points to the Summer plugin entry. You can also pin to git for unreleased changes:
+The project must have its own `package.json`. The generated MCP command will
+point at that installed candidate instead of an npx cache or
+`summer-engine@latest`.
 
-```json
-{
-  "plugin": ["summer-engine@git+https://github.com/SummerEngine/summer.git"]
-}
+## OpenCode with any existing model provider
+
+If OpenCode already has a working model provider, configure only Summer MCP:
+
+```bash
+npx -y summer-engine@latest setup opencode --yes \
+  --project "$PWD" \
+  --json
 ```
 
-Restart OpenCode. The orientation banner ("Summer Engine is loaded. N skills available…") will appear at the top of every new session, and skills will auto-discover from `node_modules/summer-engine/skills/`.
+Use `--scope user` explicitly if one Summer MCP entry should be shared by all
+OpenCode projects. Keep `--project` even for user scope so scene tools bind to
+the intended Summer editor.
+
+## Verify before changing a scene
+
+After restarting OpenCode in the project, use this first prompt:
 
-## What this gives you
+> Call `summer_get_agent_playbook` and read the result. Then call
+> `summer_get_project_context` and inspect my scene without changing it. Report
+> the MCP server version, bound project, scene root, and any diagnostics. Do not claim
+> success unless those Summer tools returned results.
 
-- **24 auto-trigger skills** under the `summer:` namespace, including `using-summer`, `brainstorm-game`, `debug`, `play`, `fps-controller`, `gdscript-patterns`, `scene-composition`, `art-direction`, and more.
-- **A `summer-engine` MCP server** — start it with `npx summer-engine mcp` and OpenCode will route scene/diagnostics/asset tools to your local Summer Engine running on `localhost:6550`.
-- **Session-start orientation** — first user message of every session is prefixed with the using-summer primer so the model invokes skills before responding.
+Only after that succeeds should the model mutate the scene. For a reversible
+smoke test, ask it to add one uniquely named node, inspect it, run the project,
+capture editor and game screenshots, check diagnostics, then remove that node
+and verify cleanup.
 
-## Configure the MCP server
+## Manual MCP-only `opencode.json`
 
-Add this block to your `opencode.json` so OpenCode launches the MCP server on demand:
+If the CLI cannot write the config, start with this provider-neutral shape:
 
 ```json
 {
+  "$schema": "https://opencode.ai/config.json",
   "mcp": {
     "summer-engine": {
-      "command": "npx",
-      "args": ["summer-engine", "mcp"]
+      "type": "local",
+      "command": [
+        "npx",
+        "-y",
+        "summer-engine@latest",
+        "mcp",
+        "--project",
+        "/absolute/path/to/project"
+      ]
     }
   }
 }
 ```
 
-## Verify
+This is the complete OpenCode MCP setup; no provider block is required.
 
-In a fresh OpenCode session, ask:
+## Manual optional OpenCode + LM Studio recipe
 
-> Let's make an FPS in Summer Engine.
+Use this larger shape only when you explicitly want Summer setup to also add an
+LM Studio provider. Replace both the model ID and project path. OpenCode
+requires the MCP command as an array.
 
-The model should auto-invoke the `summer:fps-controller` skill before writing any code. If it doesn't, the plugin isn't loaded — check `opencode.json` and your `node_modules/summer-engine/` install.
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "lmstudio/google/gemma-4-26b-a4b-qat",
+  "small_model": "lmstudio/google/gemma-4-26b-a4b-qat",
+  "provider": {
+    "lmstudio": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "LM Studio (local)",
+      "options": {
+        "baseURL": "http://127.0.0.1:1234/v1"
+      },
+      "models": {
+        "google/gemma-4-26b-a4b-qat": {
+          "name": "google/gemma-4-26b-a4b-qat (local)",
+          "limit": {
+            "context": 131072,
+            "output": 8192
+          },
+          "modalities": {
+            "input": ["text", "image"],
+            "output": ["text"]
+          },
+          "options": {
+            "reasoningEffort": "none"
+          }
+        }
+      }
+    }
+  },
+  "mcp": {
+    "summer-engine": {
+      "type": "local",
+      "command": [
+        "npx",
+        "-y",
+        "summer-engine@latest",
+        "mcp",
+        "--project",
+        "/absolute/path/to/project"
+      ]
+    }
+  }
+}
+```
 
 ## Troubleshooting
 
-| Symptom | Fix |
+| Symptom | Check |
 |---|---|
-| No orientation banner appears | Verify `plugin` array in `opencode.json` and that `summer-engine` is installed in `node_modules/`. |
-| MCP tools return "not connected" | Run `summer run` to launch the engine. The MCP server lazy-connects on the first tool call. |
-| `summer` command not found | Use `npx -y summer-engine@latest <command>` or install the CLI globally only if you want a persistent `summer` command. |
-| Skills don't auto-trigger | The using-summer skill loads on first user message; if that message is empty (e.g. a startup probe), they'll trigger on the second. |
-
-## Uninstall
-
-```bash
-npm uninstall summer-engine
-```
-
-Remove the `plugin` and `mcp` entries from `opencode.json`.
+| LM Studio model is missing | `curl -fsS http://127.0.0.1:1234/v1/models` must return its exact ID. |
+| Summer tools are missing | Restart OpenCode, then inspect `opencode debug config` and `opencode mcp list`. |
+| Tools exist but scene calls fail | Open the same project in Summer Engine and confirm the absolute `--project` path. |
+| Model talks about tools but never calls them | Use a model trained for multi-turn tool use, raise its context to at least 64k, enable only the Summer integration for the first test, and require playbook/context results before mutation. |
+| Screenshot is returned but OpenCode says the model cannot see it | Re-run setup with `--lm-studio-vision` only if the loaded model actually accepts image input, then restart OpenCode. |
+| LM Studio reports `Unknown ArrayValue filter: upper` or `Unknown test: sequence` | The model's embedded Jinja tool template is incompatible with that LM Studio runtime. In **My Models → gear → Inference → Prompt Template**, replace it with the model package's bundled `chat_template.jinja`, restart OpenCode, and retry the playbook prompt. Use **Reset** to restore the prior template. |
+| `npx` is not found | Put the absolute path from `command -v npx` in the MCP command array. |
+
+The optional npm plugin is separate from MCP. OpenCode discovers installed
+Summer skills from its standard `.opencode/skills`, `.claude/skills`, or
+`.agents/skills` locations; the MCP server itself exposes
+`summer_get_agent_playbook` for clients that do not load skills.

AGENTS.md

@@ -40,8 +40,9 @@ technical compatibility reference for version-sensitive upstream APIs.
 - 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`.
+- Generation: `summer_get_studio_workflow`, `summer_generate_image`, `summer_slice_asset_sheet`, `summer_generate_3d`, `summer_generate_audio`, `summer_generate_video`, `summer_generate_motion`, `summer_check_job`.
 - Meta: `summer_start_game_task`.
+- Cloud: `summer_cloud_init`, `summer_cloud_status`, `summer_cloud_push`, `summer_cloud_pull`, `summer_cloud_restore`, `summer_cloud_checkpoints`, `summer_cloud_conflicts`.
 - Creator: `summer_creator_publish`, `summer_creator_releases`, `summer_creator_logs`, `summer_creator_config`.
 
 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.

CHANGELOG.md

@@ -4,13 +4,23 @@ All notable changes to summer-engine will be documented here. Following [Keep a
 
 ## [Unreleased]
 
+## [2.8.0] — 2026-08-03 — "One-command MCP onboarding"
+
 ### Added
+- The complete MCP registry grows from the 58 tools registered by the published 2.7.0 package to 62 tools. The only new registrations are `summer_creator_publish`, `summer_creator_releases`, `summer_creator_logs`, and `summer_creator_config`.
 - MCP discovers every live Summer editor through `~/.summer/instances/` and automatically binds local tools to the editor whose project contains the agent's current working directory.
 - `summer mcp --project <path>` and `summer mcp --instance <id>` provide explicit selection for hosts that do not start the MCP server from a project directory.
+- OpenCode setup can configure a loaded LM Studio model alongside the unchanged complete Summer MCP tool registry with `--lm-studio-model <id>`, with opt-in screenshot input through `--lm-studio-vision`.
+- `summer setup antigravity` writes Antigravity's current project or user MCP configuration and installs Summer skills into its native `.agents` or `~/.gemini/config` directories.
 
 ### Changed
+- The onboarding and routing work in this release does not add or remove MCP registrations relative to its 2.8 development base: both the base and this change expose the same 62-tool registry. It changes client setup, editor selection, compatibility handling, and documentation.
 - Multiple live editors are now a fail-closed state when no project can be inferred. MCP lists the non-secret project/instance choices instead of following the machine-global last-opened editor pointer.
 - Selected MCP sessions keep following the same project across editor restarts and validate registry identity against `/api/health` before connecting.
+- OpenCode setup now treats `--project` as project scope unless `--scope user` is explicit, and the OpenCode guide includes a complete local-model configuration and verification path.
+- OpenCode, direct LM Studio, and Antigravity setup are independent client targets. Plain OpenCode and Antigravity setup preserve the user's existing model provider.
+- `summer_remove_node` keeps the preferred exact `path` argument and also accepts the common small-model `parent` + `name` shape for one direct child.
+- `summer_batch` infers unambiguous op-less AddNode and SetProp items emitted in individual-tool form by smaller models while keeping explicit `op` as the preferred shape.
 
 ## [2.7.0] — 2026-07-24 — "Reliable project mutations"