summer-engine 4.0.0 → 4.2.0

package/.claude-plugin/marketplace.json

@@ -10,8 +10,8 @@
     {
       "name": "summer",
       "source": "./",
-      "version": "4.0.0",
-      "description": "Make real, playable games with Summer Engine. A first-run guide (/summer:start), game-dev skills, and two MCP servers: the bridge to the Summer Engine desktop app, and Summer's hosted cloud server for people without it.",
+      "version": "4.2.0",
+      "description": "The game engine built for AI. Any agent makes a multiplayer game and publishes it. A first-run guide (/summer:start), game-dev skills, and two MCP servers: the bridge to the Summer Engine desktop app, and Summer's hosted cloud server for people without it.",
       "author": {
         "name": "Summer Engine",
         "email": "founders@summerengine.com"

package/.claude-plugin/plugin.json

@@ -2,8 +2,8 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "summer",
   "displayName": "Summer Engine",
-  "version": "4.0.0",
-  "description": "Make real, playable games with Summer Engine. A first-run guide (/summer:start), game-dev skills, and two MCP servers: the bridge to the Summer Engine desktop app, and Summer's hosted cloud server for people without it.",
+  "version": "4.2.0",
+  "description": "The game engine built for AI. Any agent makes a multiplayer game and publishes it. A first-run guide (/summer:start), game-dev skills, and two MCP servers: the bridge to the Summer Engine desktop app, and Summer's hosted cloud server for people without it.",
   "author": {
     "name": "Summer Engine",
     "email": "founders@summerengine.com",
@@ -116,6 +116,7 @@
     "./library/skills/summer-apps/",
     "./library/skills/summer-apps-design/",
     "./library/skills/summer-assets/",
+    "./library/skills/summer-cli/",
     "./library/skills/summer-friends/",
     "./library/skills/summer-leaderboards/",
     "./library/skills/summer-match-results/",

package/.codex-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "_generated": "GENERATED from integrations/codex — do not edit; npm run generate:registry",
   "name": "summer",
-  "version": "4.0.0",
-  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 119-tool MCP bridge. Build games by talking.",
+  "version": "4.2.0",
+  "description": "The game engine built for AI. Any agent makes a multiplayer game and publishes it. Game-dev skills, lifecycle hooks, and a 119-tool MCP bridge to the Summer Engine desktop app.",
   "author": {
     "name": "Summer Engine",
     "email": "founders@summerengine.com",
@@ -106,6 +106,7 @@
     "./library/skills/summer-apps/",
     "./library/skills/summer-apps-design/",
     "./library/skills/summer-assets/",
+    "./library/skills/summer-cli/",
     "./library/skills/summer-friends/",
     "./library/skills/summer-leaderboards/",
     "./library/skills/summer-match-results/",
@@ -143,25 +144,28 @@
   "mcpServers": "./.mcp.json",
   "hooks": "./hooks/hooks.json",
   "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. Users make Summer games with the Summer SDK and GDScript. The plugin adds game-dev skills, lifecycle hooks, and a 119-tool MCP bridge for guarded project files, scene editing, asset import, play mode, diagnostics, generation, and creator workflows. Git, shell, and grep stay with the host agent. Summer follows its upstream technical base continuously; version-sensitive work uses the bundled compatibility reference instead of a fixed onboarding version. Session-start orients the session. Pre-commit doctor (opt-in) blocks bad commits.",
-    "developerName": "Summer Engine",
-    "category": "Coding",
+    "displayName": "Summer Engine",
+    "shortDescription": "Make games with AI",
+    "longDescription": "Summer Engine is the game engine built for AI. Codex builds a full multiplayer game in it, plays and tests it, and publishes it on summer.games. The plugin adds game-dev skills, lifecycle hooks, and a 119-tool MCP bridge to the Summer Engine desktop app: project files, scenes, asset import, play mode, screenshots, diagnostics, asset generation and the store. Git, shell, and grep stay with Codex. Session-start orients each session. The pre-commit doctor (opt-in) blocks bad commits.",
+    "developerName": "Summer Labs, Inc.",
+    "category": "Developer Tools",
     "capabilities": [
       "Interactive",
       "Read",
       "Write"
     ],
-    "websiteURL": "https://summerengine.com",
-    "privacyPolicyURL": "https://summerengine.com/privacy",
-    "termsOfServiceURL": "https://summerengine.com/terms",
+    "websiteURL": "https://www.summerengine.com",
+    "supportURL": "https://summer.games/support",
+    "privacyPolicyURL": "https://www.summerengine.com/privacy",
+    "termsOfServiceURL": "https://www.summerengine.com/terms",
     "defaultPrompt": [
       "I want to make a game.",
-      "/summer:brainstorm-game",
+      "Make a small multiplayer game and let me play it.",
       "Open this Summer Engine project and tell me what's broken."
     ],
     "brandColor": "#FF8F17",
+    "composerIcon": "./assets/icon.png",
+    "logo": "./assets/icon.png",
     "screenshots": []
   }
 }

package/.cursor-plugin/plugin.json

@@ -2,14 +2,15 @@
   "$schema": "https://cursor.com/schemas/cursor-plugin/plugin.json",
   "_generated": "GENERATED from integrations/cursor — do not edit; npm run generate:registry",
   "name": "summer",
-  "displayName": "Summer",
-  "version": "4.0.0",
-  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 119-tool MCP bridge to the local desktop app.",
+  "displayName": "Summer Engine",
+  "version": "4.2.0",
+  "description": "The game engine built for AI. Any agent makes a multiplayer game and publishes it. Game-dev skills, lifecycle hooks, and a 119-tool MCP bridge to the Summer Engine desktop app.",
   "author": {
     "name": "Summer Engine",
     "email": "founders@summerengine.com"
   },
   "publisher": "summer-engine",
+  "logo": "assets/icon.png",
   "homepage": "https://summerengine.com",
   "repository": "https://github.com/summerengine/summer",
   "license": "MIT",
@@ -118,6 +119,7 @@
     "./library/skills/summer-apps/",
     "./library/skills/summer-apps-design/",
     "./library/skills/summer-assets/",
+    "./library/skills/summer-cli/",
     "./library/skills/summer-friends/",
     "./library/skills/summer-leaderboards/",
     "./library/skills/summer-match-results/",

package/.factory-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "_generated": "GENERATED from integrations/factory — do not edit; npm run generate:registry",
   "name": "summer",
-  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 119-tool MCP bridge to the local desktop app.",
-  "version": "4.0.0",
+  "description": "The game engine built for AI. Any agent makes a multiplayer game and publishes it. Game-dev skills, lifecycle hooks, and a 119-tool MCP bridge to the Summer Engine desktop app.",
+  "version": "4.2.0",
   "author": {
     "name": "Summer Engine",
     "email": "founders@summerengine.com",
@@ -103,6 +103,7 @@
     "./library/skills/summer-apps/",
     "./library/skills/summer-apps-design/",
     "./library/skills/summer-assets/",
+    "./library/skills/summer-cli/",
     "./library/skills/summer-friends/",
     "./library/skills/summer-leaderboards/",
     "./library/skills/summer-match-results/",

package/AGENTS.md

@@ -95,7 +95,7 @@ Climb only as high as the change demands; the agent playbook has the full versio
 
 **Honesty:** never describe an image you did not receive. A failed capture is a result — report it, climb down a rung, or ask the user. Pass structured failures (`failure_reason`, `terminalState`, `identity_mismatch`) through verbatim. Ask the user to play only for what a probe cannot judge: feel, looks, fun.
 
-**Same tools from a shell.** Every MCP tool is also `summer tool <slug> --args '<json>'` (same implementation; `summer tool --list` for the slugs), and every operation is `summer <area> <action> --<field> <value>` (`summer ops search <words>` finds it; `--dry-run`, `--wait`, `--json`). Use them when the host has no MCP session or you want a one-off call in a script.
+**Same tools from a shell.** Every MCP tool is also `summer tool <slug> --args '<json>'` (same implementation; `summer tool --list` for the slugs), and every operation is `summer <area> <action> --<field> <value>` (`summer ops search <words>` finds it; `--dry-run`, `--wait`, `--json`). Use them when the host has no MCP session or you want a one-off call in a script. `summer setup <agent> --cli` installs the skills with no MCP server; the `summer-cli` skill teaches the commands, and each skill ends with a "From a shell" table of the command for every tool it names.
 
 **Engine capability pre-flight.** `summer_get_project_context` reads the engine's capability list; a tool whose op the running engine build provably lacks returns a structured `engine_lacks_op` result instead of running (for example, the runtime and spatial tools on engines older than 0.5.66). `SUMMER_CAPABILITY_PREFLIGHT=off` sends every call anyway — for engine developers testing unreleased builds, not for normal sessions.
 

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 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/).
 
+## [4.2.0] - 2026-10-16
+
+4.1.0 was not published to npm. 4.2.0 is the first release with everything in it (the [4.1.0] section below), plus these changes.
+
+Upgrades keep agents current: the installed Summer skills refresh themselves after an upgrade, every Summer project gets an AGENTS.md, the CLI path can let Claude Code and Codex run read-only commands without asking, and Gemini CLI installs come with the skills.
+
+- **The CLI path can ask less.** `summer setup claude-code --cli --allow-rules --yes` lets Claude Code run read-only and dry-run `summer` commands without asking: a reviewed list of reads (`summer ops search`, `summer jobs wait`, `summer engine screenshot`, ...; `jobs wait` and `assets get` also save the files they name) and every spend only as a dry run (`summer assets generate-image --dry-run ...`, the flag right after the action). It is opt-in: the flag is in the command the person approves, setup prints every rule, and without `--yes` it writes nothing. The rules, for both `summer` and `npx -y summer-engine@latest`, go into `permissions.allow` in `~/.claude/settings.json` (`.claude/settings.local.json` with `--scope project`); nothing else in the file changes. `summer setup codex --cli --allow-rules --yes` writes the same as Summer's own Codex rules file, `~/.codex/rules/summer.rules`. `--remove-allow-rules` takes exactly these rules out again. Changes, publishing, prices, deletes, messages and `engine capture-gameplay` (it runs the project's own code) still ask. A call with `--dry-run` is now a dry run whatever its input says (`--no-dry-run` or `"dryRun": false` in `--input` no longer undo it).
+- **Devin Desktop (formerly Windsurf): the MCP config moved** to `~/.config/devin/mcp_config.json` (`$XDG_CONFIG_HOME/devin`, Windows `%APPDATA%\devin`), per Devin's docs. `summer setup windsurf` writes it there and says when an earlier setup's entry is still in `~/.codeium/windsurf/mcp_config.json` (left as it is for older builds).
+- **Gemini CLI extensions get the skills.** `gemini extensions install https://github.com/SummerEngine/summer` and the Gemini CLI gallery install a release's only asset, and each GitHub Release now carries one: `summer-gemini-extension.tar.gz`, the extension with `skills/<slug>/` for every bundled skill (Gemini reads skills only from that folder; the repository keeps them in `library/skills/`). A clone of the repository gave no skills.
+- **A Claude plugin for Anthropic's plugin directory** in `plugins/claude/`: the same plugin from a folder of its own (292 files, under the directory's 512), with the server and every `summer-engine@latest` pinned to this version. `npm run generate:registry` writes it, `--check` fails when it drifts, and `claude plugin validate --strict plugins/claude` passes.
+- **Every Summer project has an AGENTS.md.** `summer create` writes a short AGENTS.md, the one file Codex, Cursor, Copilot, Amp and other agents read in every session: this is a Summer Engine game in GDScript, how to work on it with the MCP tools or the `summer` CLI, where Summer's skills are, the five most useful commands, and that publishing needs the owner's approval. It also writes a CLAUDE.md that only holds `@AGENTS.md`, for Claude Code. `summer setup --yes` run inside a project adds both when they are missing (without `--yes` it says what it would add; `--no-project-files` and `--assets-only` leave the project alone). The project is the nearest folder with `project.godot` at or above the working directory, no higher than the git top level and never the home folder. An existing AGENTS.md or CLAUDE.md is never overwritten: setup adds one marked Summer block once and later updates only that block, in the file's own line endings. A CLAUDE.md that already imports AGENTS.md stays as it is, a CLAUDE.md that is a link to AGENTS.md (or the reverse) gets the AGENTS.md block once, a link to a missing file or out of the project is left alone, and a file setup cannot write is reported with the reason. The five commands come from the `summer-cli` skill, and a test runs every command both teach.
+- **Upgrades refresh the installed skills.** The first `summer mcp` start (v4 surface) after an upgrade brings the Summer skills already installed on the computer to the new version, then says so once: in the session's instructions, so the agent can tell the person, and on stderr. Before, skills from 3.x stayed until someone ran `summer setup --force`. While they stayed, the local server kept the legacy toolset on, and agents kept calling 3.x tools; that undid about half of 4.0's smaller tool list. Now the legacy toolset is off from that first start; 3.x tool names still run through `summer_call`, and `--toolsets legacy` or `SUMMER_LEGACY_TOOLS=on` lists them again.
+  - Only Summer's own copies are replaced: real folders (not links) whose `resource.yaml` names that skill, in a skills folder with Summer's version marker. A skill from another pack with the same name, and a Summer skill someone changed after install, stay as they are, at this and every later release until `summer setup --force` (the version marker lists them); the notice names them. A pre-release never takes a release's skills back. Nothing is removed. New library skills are added only to a folder that holds nearly the whole library, so an assets-only install stays one.
+  - Each skill is copied beside the old one and swapped in with renames, under a lock per folder, and the version marker is written last. A killed start or a copy error leaves the old skill, and the next start finishes. A refresh error never stops `summer mcp`; it goes to the MCP log.
+  - Rule-file installs (Cline, Roo Code, old Cursor rules) are not refreshed; `summer doctor` still prints the command for them.
+- **`summer_call` on the local server takes `name` as well as `op`.** Agents copied the `name` field that `summer_search` answers with and got an input error. When both are given and differ, it answers `invalid_input`.
+
+## [4.1.0] - 2026-10-16
+
+Not published to npm: these changes ship in 4.2.0.
+
+Summer without MCP: any agent runs Summer from its shell with the `summer` CLI and the `summer-cli` skill. Every operation is found without a sign-in, search understands plain English, and Summer installs with Homebrew.
+
+- **`--json` on every read command.** `summer ops describe <op> --json` failed with "unknown option '--json'"; it now prints the same answer as the other operation commands (`{ok, status, result: {operation}}`, warnings inside). `summer status`, `summer list templates|projects`, `summer skills list`, `summer skills info`, `summer memory show`, `summer memory path` and `summer config get` take `--json` too. A test lists every CLI command and fails when a read command has no `--json`. `summer tool` keeps printing JSON; its `--json` is still the old alias of `--args`.
+- **`summer setup <agent> --cli`: Summer without MCP.** Installs the skills for the agent and writes no MCP entry and no Summer Games entry. The agent runs Summer as `summer <area> <action>` commands in its shell. `--no-mcp` is the same. With `--assets-only` it installs only the asset skills. Claude Code gets no slash commands (`/summer`, `/gameskill`, `/start` start work through the MCP tools; `summer skills install --no-commands` leaves them out too). An existing `summer-engine` entry from an earlier setup stays, and setup says so: a stdio or URL entry, and Claude Code's per-project ones. `--print`, `--profile`, `--local-dev` and `--channel` shape only the MCP entry, so `--cli` refuses them. It also refuses agents without a skills folder, Gemini CLI (its skills load only through its extension, which runs the MCP server) and Roo Code (its skills are rule files that tell it to use the MCP tools). When an agent's config lists no `summer-engine` and `--cli` can set the agent up, the skills refresh `summer doctor` recommends adds `--cli`, so it adds no MCP server.
+- **New skill `summer-cli`** (preview): sign in, find an operation (`summer ops search`, `summer ops describe`), run it (`--input`, `--dry-run`, `--json`, `--idempotency-key`), long jobs (`--wait`, `summer jobs wait`), approvals, saving files (`--out`), the engine, and the next step for each error code. It checks `summer --version` first and uses `npx -y summer-engine@latest` when `summer` is missing or older than 4.0. A test dry-runs every command it teaches, offline. `using-summer` sends sessions without `summer_*` tools to it.
+- **Each skill shows the command for every tool it names.** A skill that names an MCP tool or an operation ends with a generated "From a shell" table: `summer_play` is `summer engine play`, `assets.generate_image` is `summer assets generate-image`, a split 3.x tool lists each operation, a merged one keeps the input it fixes (`summer_list_my_assets` is `summer assets search --scope mine`), and a merged one that runs here runs as itself (`summer_get_agent_playbook` is `summer tool get-agent-playbook`). `npm run generate:registry` writes it from the operation catalog. `validate:library` fails when it is stale, and when a skill names a 4.0 tool whose operation the catalog does not have. Tests check that every command names an operation this package runs or the catalog knows, and run the rows with a fixed input that run here, offline. `.gitattributes` keeps Markdown LF, so the check also holds on Windows checkouts. MCP tool names do not change.
+- **README: CLI only** (summer-engine 4.1.0 or newer), next to the hosted MCP block.
+- `summer <area> <action> --max-characters <n>` on a local read (`summer docs read`, the engine reads) no longer fails with an unknown key: the CLI prints the whole answer and says so.
+- Shorter descriptions for `summer-cli`, `summer-assets` and `concept-to-level`, so the installed skill descriptions leave room under the 12,000-character budget.
+- **Every operation is found without a sign-in.** `summer ops search`, `summer ops describe` and `summer_search` list every cloud operation (`store.publish`, `pricing.set_base`, ...) signed out, from the hosted server's public catalog shipped in the package (`registry/operations/public-catalog.json`). A cloud operation found signed out says `(needs sign-in)` (`needsSignIn: true` in JSON) and runs after `summer login`. Signed in, the server's live rows replace the shipped ones. `ops describe` of a cloud operation answers from the shipped catalog when the server cannot. `npm run sync:catalog` refreshes the copy; `npm run sync:catalog -- --check` runs before each release, and a test fails when the copy and `legacy-names.json` disagree.
+- **Search understands plain English.** "publish my game" finds `store.publish` first, "how did my game do" `analytics.summary`, "lower my price" `pricing.set_base`, "invite a teammate" `team.invite`, "take a screenshot" `engine.screenshot`, and "add multiplayer" the library search (the CLI prints the `summer docs search` command for it). Rare words weigh more and everyday verbs less, an operation whose title or tag the query says nearly word for word wins, and plain words reach the catalog's words (picture is image, music is audio). Local and cloud operations rank in one list, the same signed in or out. A test holds 35 real phrases.
+- **Install with Homebrew:** `brew install summerengine/tap/summer` (the SummerEngine/homebrew-tap formula follows npm `latest` by itself, checked every hour). The README starts with the three ways to install: the hosted URL for chat apps, Homebrew and npm.
+- `npm publish` no longer fails on a busy machine when it runs the tests again (`prepublishOnly`). Every test has a 20 s limit instead of 5 s, and the slow ones have their own: the first import of the built package (60 s), the template fetch timeout and the trajectory log rotation (30 s each), the `setup --cli` installs (120 s) and the app bundle export (60 s).
+- **`content` is an area.** `summer content <action>` runs the content operations Summer's hosted server serves (`content.list_games`, `content.get_kit`, `content.list_references`, `content.search_library`, `content.save_piece`, `content.add_feedback`, ...). The 4.0.0 `marketing.*` content operations are renamed to them (`marketing.content_feed` is `content.list_references`, `marketing.get_brand_pack` is `content.get_kit`); `registry/operations/legacy-names.json` maps each old name to its new one.
+- **Directory listings lead with "The game engine built for AI."** The MCP Registry entry (`server.json`) gets the Summer sun icon. The Codex plugin is named Summer Engine, with the short description "Make games with AI" (OpenAI allows 30 characters), a logo, a composer icon and a support link. The Cursor plugin is named Summer Engine and gets a logo. The Claude, Cursor, Codex, Factory and Gemini descriptions open with the product line. `glama.json` lets the maintainers claim the Glama listing. The README links support, privacy and terms.
+
 ## [4.0.0] - 2026-10-15
 
 3.9.0 and 3.9.1 were not published to npm. 4.0.0 is the first release with everything in them (the [3.9.1] and [3.9.0] sections below), plus these changes.

package/README.md

@@ -1,4 +1,4 @@
-# Summer: MCP server, CLI and skills for Summer Engine
+# Summer Engine: MCP server, CLI and skills
 
 <div align="center">
 
@@ -18,6 +18,14 @@
 
 ---
 
+## Install
+
+- **Chat apps** (Claude, ChatGPT, Cursor...): add `https://mcp.summerengine.com/mcp`. Nothing to install.
+- **Homebrew:** `brew install summerengine/tap/summer`
+- **npm** (Node 20+): `npm install -g summer-engine`
+
+**CLI only** (summer-engine 4.2.0 or newer), no MCP server: `summer setup --cli`. `summer ops search "publish my game"` finds any operation, signed in or not.
+
 ## Connect
 
 **Cloud work: `https://mcp.summerengine.com/mcp`.** Nothing to install. Add the URL to your agent and sign in to your Summer account once. Your agent then makes assets (images, 3D models, motion, sound effects, music, voices, video), searches and downloads your Summer asset library, plans games, and runs your projects, the store, publishing, prices, analytics, A/B tests, your team and Studio. It has no engine tools: for those, use the local server below.
@@ -28,11 +36,13 @@
 | Codex | `codex mcp add summer-cloud --url https://mcp.summerengine.com/mcp`, then `codex mcp login summer-cloud` |
 | Cursor | [Add to Cursor](https://cursor.com/install-mcp?name=summer-cloud&config=eyJ1cmwiOiJodHRwczovL21jcC5zdW1tZXJlbmdpbmUuY29tL21jcCJ9), or add `"summer-cloud": {"url": "https://mcp.summerengine.com/mcp"}` under `mcpServers` in `~/.cursor/mcp.json` |
 | VS Code | [Add to VS Code](https://vscode.dev/redirect/mcp/install?name=summer-cloud&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.summerengine.com%2Fmcp%22%7D), or `code --add-mcp '{"name":"summer-cloud","type":"http","url":"https://mcp.summerengine.com/mcp"}'` |
-| Devin Desktop (formerly Windsurf) | add `"summer-cloud": {"serverUrl": "https://mcp.summerengine.com/mcp"}` under `mcpServers` in `~/.codeium/windsurf/mcp_config.json` |
+| Devin Desktop (formerly Windsurf) | add `"summer-cloud": {"serverUrl": "https://mcp.summerengine.com/mcp"}` under `mcpServers` in `~/.config/devin/mcp_config.json` (Windows `%APPDATA%\devin\mcp_config.json`) |
 | Claude Desktop, claude.ai | Settings > Connectors > Add custom connector, then paste the URL |
 
 **Engine work: `npx -y summer-engine@latest setup <agent> --yes`** (needs Node 20+). It writes the local server (`summer mcp`) into your agent's config with the skills. The local server drives the Summer Engine app on your machine: build scenes, write scripts, play the game, take screenshots, read errors. After `summer login` it also runs every cloud operation, so your agent needs one server. Or paste the prompt in [Get started](#get-started-one-prompt) and your agent does every step.
 
+**CLI only (summer-engine 4.2.0 or newer): `npx -y summer-engine@latest setup <agent> --cli --yes`.** No MCP server: your agent runs Summer as commands in its shell. Setup installs the skills for your agent, with `summer-cli`, the guide to the commands, and writes no MCP entry. Your agent signs you in with `summer login`, finds an operation with `summer ops search "<what you want>"` and runs it as `summer <area> <action> --<field> <value>`, with `--dry-run`, `--wait` and `--json`. Engine commands (`summer engine …`) drive the Summer Engine app on your machine. Each skill ends with a table of the command for every tool it names. Add `--assets-only` for only the asset skills. `--no-mcp` is the same as `--cli`.
+
 **ChatGPT and Claude's connector directory** use two reviewed store versions with a fixed tool list: `https://mcp.summerengine.com/chatgpt` (games, assets and generation; no publishing, no billing links) and `https://mcp.summerengine.com/directory` (the store, publishing and Grow reads; no image, 3D, audio or video generation). They keep their 3.x tool names and have no `summer_search` or `summer_call`. For everything else, use `/mcp`.
 
 ## What this is
@@ -303,9 +313,9 @@ Every capability is an operation named `<area>.<action>`: `assets.generate_image
 - **One answer shape**: `done` with a `result`, `running` with a job (`summer_jobs_wait` waits up to 50 seconds per call), `needs_approval` with a link for you, `dry_run` with a preview, or an error with a `code`, a `message` and exactly one `next` step.
 - **Safe to try**: every change takes `dryRun: true` (it changes nothing and spends nothing; a spend shows your own credit estimate) and an `idempotencyKey`, so a retry never runs twice.
 - **Error codes**: `invalid_input`, `not_signed_in`, `forbidden`, `not_found`, `conflict`, `idempotency_conflict`, `in_progress`, `rate_limited`, `no_credits`, `over_limit`, `engine_not_running`, `engine_lacks_op`, `unsupported`, `not_in_profile`, `moved`, `outcome_unknown`, `unavailable`, `internal`.
-- **3.x names keep working** for all of 4.x: `summer_call` accepts them on every server, `summer mcp --toolsets legacy` lists them on the local server, and the local server lists them by itself while your installed skills are older than 4.0. The map from old names to operations is [`registry/operations/legacy-names.json`](registry/operations/legacy-names.json).
+- **3.x names keep working** for all of 4.x: `summer_call` accepts them on every server, `summer mcp --toolsets legacy` lists them on the local server, and the local server lists them by itself while your installed skills are older than 4.0. Its first start after an upgrade refreshes the Summer skills you installed, so after an upgrade the legacy list stays off unless you ask for it. The map from old names to operations is [`registry/operations/legacy-names.json`](registry/operations/legacy-names.json).
 
-The same operations run from a shell: `summer <area> <action> --<field> <value>` (for example `summer assets generate-image --prompt "a cozy pixel-art tavern" --aspect-ratio 16:9`), with `--dry-run`, `--wait` (follows a job or an approval to the end) and `--json` (prints the answer only; exit code 0 for any `ok` answer, 1 for an error). `summer whoami` shows who is signed in. `summer ops search <words>` and `summer ops describe <op>` find an operation and its input.
+The same operations run from a shell: `summer <area> <action> --<field> <value>` (for example `summer assets generate-image --prompt "a cozy pixel-art tavern" --aspect-ratio 16:9`), with `--dry-run`, `--wait` (follows a job or an approval to the end) and `--json` (prints the answer only; exit code 0 for any `ok` answer, 1 for an error). `summer whoami` shows who is signed in. `summer ops search <words>` and `summer ops describe <op>` find an operation and its input. Every command that reads something takes `--json`.
 
 ## What's in this repo
 
@@ -430,18 +440,18 @@ Publishing to summer.games, multiplayer hosting, matchmaking and Grow are live.
 | `summer login --store` | Only the store sign-in (`store.upload_file` and the cloud operations: plans, the store, publishing and Grow). |
 | `summer whoami` | The signed-in account, its plan and credits. |
 | `summer <area> <action> [--<field> <value> …] [--input '<json>'] [--dry-run] [--idempotency-key <k>] [--wait] [--json]` | Run any operation from the shell, for example `summer assets generate-image --prompt "…"` or `summer store status --game-id <id>`. |
-| `summer ops search <words…>` / `summer ops describe <op>` | Find the operation for a job, or print one operation's input, effect and approval. |
+| `summer ops search <words…>` / `summer ops describe <op>` | Find the operation for a job, or print one operation's input, effect and approval. Works signed out: a cloud operation shows `(needs sign-in)`. |
 | `summer logout` | Clear auth tokens. |
 | `summer config [get\|set\|unset]` | Read or update the shared non-secret `~/.summer/config.json`. |
-| `summer status` | Engine state, port, auth. |
+| `summer status [--json]` | Engine state, port, auth. |
 | `summer doctor` | Diagnose Node, login, engine, project memory, MCP. |
 | `summer plan <goal>` | Route a game-building goal into skills, MCP tools, gates, and verification. |
 | `summer memory` | Inspect project memory in `.summer`. |
 | `summer memory show <file>` | Print a project memory Markdown file. |
 | `summer run [path] [--background\|--focus] [--bin <executable>]` | Launch the engine. Agents (no TTY) launch in the background by default so the window never steals focus; `--focus` brings it to the front. `--bin` (env `SUMMER_BIN`) launches a build that is not installed. |
 | `summer open <path \| target> [--print] [--list]` | A project directory opens in the running engine. Anything else is a navigation target — `billing`, `my-games`, `mcp-guide`, `scene`, `inspector`, an intent phrase, a `res://` path — opened in the browser or sent to the editor; `--print` resolves without opening. |
-| `summer create <template> [name]` | Scaffold a project from a pinned template. |
-| `summer list templates` / `projects` | Browse. |
+| `summer create <template> [name]` | Scaffold a project from a pinned template, with an AGENTS.md for your agent (and a CLAUDE.md that imports it). |
+| `summer list templates` / `projects` | Browse. `--json` for scripts. |
 | `summer events [--follow] [--kinds <csv>] [--since <seq>] [--json]` | The engine events channel (engine 0.5.66+): newest events, or stream them live. |
 | `summer debug [issue…]` | Support-ready Markdown debug report. |
 | `summer skills list` | Show all skills (`--by-domain` groups them; the same grouping is in [`library/skills/README.md`](library/skills/README.md)). |
@@ -450,7 +460,7 @@ Publishing to summer.games, multiplayer hosting, matchmaking and Grow are live.
 | `summer tool <name> --args '<json>'` | Run any Summer tool from the shell — the same implementation the MCP tool uses. `summer tool --list` prints them all. |
 | `summer mcp [--project <path> \| --instance <id>] [--profile <p>] [--toolsets <list>] [--surface v4\|v3]` | Start MCP; normally auto-binds from the agent's project directory. `--surface` (env `SUMMER_SURFACE`): `v4` (the default: engine tools, `summer_docs_search`, `summer_docs_read`, `summer_search` and `summer_call`) or `v3` (the 3.x tools). `--profile` (env `SUMMER_PROFILE`): `full` (every tool, the default), `engine` (engine, generation and store tools; fits the per-request tool cap of clients such as VS Code Copilot, which is 128), `assets` (generation and asset tools, no engine tools). `--toolsets` (env `SUMMER_TOOLSETS`) adds toolsets by name: `core`, `assets`, `tools`, `engine`, `ui`, `ship`, `uploads`, `apps`, `board`, `grow`, `studio`, `cloud`, `other`, or `all`. `--toolsets legacy` also lists every 3.x tool name. |
 | `summer mcp setup <agent>` | Deprecated alias of `summer setup <agent>`. |
-| `summer setup <agent> [--yes] [--force] [--recommended] [--stable-only] [--no-games] [--profile <p>] [--assets-only]` | One shot: MCP config + all skills, preview included (`--recommended` for the subset, `--stable-only` to skip preview) + doctor. Idempotent. `--profile` writes a tool profile into the agent's MCP entry (`SUMMER_PROFILE`); `vscode-copilot` gets `engine` unless you pass `--profile full`, every other agent gets every tool. `--assets-only` is the assets path: the `assets` profile, only the asset skills, no Summer Games. For most agents (not Claude Desktop, Visual Studio, Qoder, Rovo Dev, LM Studio or the legacy targets) it also adds `summer-games` (`https://mcp.summer.games/mcp`: friends, parties and messages as you) unless the same URL is already listed; you sign in once through summer.games. `--no-games` skips it. |
+| `summer setup <agent> [--yes] [--force] [--recommended] [--stable-only] [--no-games] [--profile <p>] [--assets-only] [--cli]` | One shot: MCP config + all skills, preview included (`--recommended` for the subset, `--stable-only` to skip preview) + doctor. Idempotent. `--cli` (or `--no-mcp`, 4.2.0 or newer) installs the skills and no MCP server: the agent runs `summer` commands in its shell. Inside a Summer project it also adds the Summer instructions to the project's AGENTS.md and CLAUDE.md; `--no-project-files` skips that. `--profile` writes a tool profile into the agent's MCP entry (`SUMMER_PROFILE`); `vscode-copilot` gets `engine` unless you pass `--profile full`, every other agent gets every tool. `--assets-only` is the assets path: the `assets` profile, only the asset skills, no Summer Games. For most agents (not Claude Desktop, Visual Studio, Qoder, Rovo Dev, LM Studio or the legacy targets) it also adds `summer-games` (`https://mcp.summer.games/mcp`: friends, parties and messages as you) unless the same URL is already listed; you sign in once through summer.games. `--no-games` skips it. |
 
 Agents: `claude-code`, `claude-desktop`, `codex`, `cursor`, `windsurf`, `antigravity`, `cline`, `cline-cli`, `kilo-code`, `github-copilot`, `vscode-copilot`, `visual-studio`, `copilot-jetbrains`, `opencode`, `zed`, `kiro`, `goose`, `hermes`, `trae`, `qwen-code`, `kimi-code`, `crush`, `amp`, `factory`, `junie`, `warp`, `rovo-dev`, `qoder`, `grok-build`, `mistral-vibe`, `lm-studio`. Legacy (still accepted, warn on use): `gemini`, `roo-code`. Aliases: `devin`/`devin-desktop` → `windsurf`, `agy` → `antigravity`, `droid` → `factory`, `copilot` → `github-copilot`, `vscode` → `vscode-copilot`, `kilo` → `kilo-code`, `qwen` → `qwen-code`, `kimi` → `kimi-code`. Scopes: `--scope user` (default), `--scope project`.
 
@@ -484,3 +494,4 @@ Some process skills (brainstorming, writing-plans, writing-skills, investigating
 - [Download Summer Engine](https://summerengine.com/download)
 - [Documentation](https://docs.summerengine.com)
 - [Issues](https://github.com/summerengine/summer/issues)
+- [Support](https://summer.games/support) · [Privacy policy](https://www.summerengine.com/privacy) · [Terms](https://www.summerengine.com/terms)

package/dist/cli/commands/config.js

@@ -24,13 +24,14 @@ configCommand
     .command("get")
     .description("Read one configuration value")
     .argument("<key>", `One of: ${CONFIG_KEYS.join(", ")}`)
-    .action(async (rawKey) => {
+    .option("--json", "Print the key and value as JSON")
+    .action(async (rawKey, opts) => {
     const key = requireKey(rawKey);
     const value = getConfigValue(await readSummerConfig(), key);
     if (value === undefined) {
         throw new Error(`${key} is not set. Recovery: run "summer config set ${key} <value>", or rely on the documented default.`);
     }
-    console.log(value);
+    console.log(opts.json ? JSON.stringify({ key, value }) : value);
 });
 configCommand
     .command("set")

package/dist/cli/commands/create.js

@@ -6,6 +6,7 @@ import { PACKAGE_ROOT } from "../../core/package-root.js";
 import { SUMMER_ENGINE_COMPATIBILITY } from "../../core/summer-compatibility.js";
 import { getTemplateRegistry, materializePinnedTemplate, resolveTemplate, TemplateDigestMismatchError, } from "../../core/templates.js";
 import { PROJECT_MANIFEST_RELPATH, writeProjectManifest } from "../../project-memory/project-manifest.js";
+import { writeAgentInstructions } from "../../project-memory/agent-instructions.js";
 import { TOOLKIT_VERSION as toolkitVersion } from "../../core/version.js";
 /** Summer Engine's version when it is reachable right now, else undefined —
  *  the manifest then omits engine_version rather than guessing. */
@@ -48,9 +49,17 @@ export function scaffoldAutopilot(projectDir) {
 /** What the scaffold's first run actually does — the "Next steps" line must not
  *  promise a verify when the first thing run.sh does is the one-off asset import. */
 export const AUTOPILOT_NEXT_STEP_HINT = "first run imports assets once, then verifies the game boots; no editor needed";
-function printNextSteps(fullPath, dirName, scaffolded) {
+function printNextSteps(fullPath, dirName, scaffolded, instructions) {
     console.log(`\nProject created at ${fullPath}`);
     console.log(`Recorded template pin in ${join(dirName, PROJECT_MANIFEST_RELPATH)}`);
+    // AGENTS.md (read by most agents) and CLAUDE.md (`@AGENTS.md`): each file says what happened to it.
+    const changed = instructions.filter((file) => file.action === "created" || file.action === "added" || file.action === "updated").map((file) => file.file);
+    if (changed.length)
+        console.log(`Wrote the Summer instructions for your agent in ${changed.join(" and ")}`);
+    for (const file of instructions) {
+        if (file.reason)
+            console.log(`${file.file} ${file.action === "skipped" ? "not written" : "left as it is"}: ${file.reason}`);
+    }
     console.log("\nNext steps:");
     console.log(`  summer run ${dirName}`);
     if (scaffolded) {
@@ -123,7 +132,7 @@ export const createCommand = new Command("create")
             toolkit_version: toolkitVersion,
             engine_version: await detectEngineVersion(),
         });
-        printNextSteps(fullPath, dirName, scaffolded);
+        printNextSteps(fullPath, dirName, scaffolded, writeAgentInstructions(fullPath));
         return;
     }
     const pin = entry.pin;
@@ -152,7 +161,7 @@ export const createCommand = new Command("create")
         engine_version: await detectEngineVersion(),
     });
     console.log(`Source: ${pin.repo} @ ${materialized.commit.slice(0, 12)} (tree digest verified)`);
-    printNextSteps(fullPath, dirName, scaffolded);
+    printNextSteps(fullPath, dirName, scaffolded, writeAgentInstructions(fullPath));
 });
 /**
  * project.godot uses C-style double-quoted strings; a project name containing

package/dist/cli/commands/list.d.ts

@@ -1,2 +1,7 @@
 import { Command } from "commander";
+import { type TemplateEntry } from "../../core/templates.js";
 export declare const listCommand: Command;
+/** `summer list templates --json`: what the text lists, one object per template. */
+export declare function templatesJson(): Array<Pick<TemplateEntry, "id" | "slug" | "version" | "summary" | "status" | "builtin" | "systems" | "do_not_use_when">>;
+/** Subdirectories of `dir` that hold a project.godot. */
+export declare function findProjects(dir: string): string[];

package/dist/cli/commands/list.js

@@ -5,18 +5,44 @@ import { getTemplateRegistry } from "../../core/templates.js";
 export const listCommand = new Command("list")
     .description("List available templates or local projects")
     .argument("<what>", "'templates' or 'projects'")
-    .action(async (what) => {
+    .option("--json", "Print the list as JSON")
+    .action(async (what, opts) => {
     if (what === "templates") {
-        listTemplates();
+        if (opts.json)
+            console.log(JSON.stringify({ templates: templatesJson() }));
+        else
+            listTemplates();
     }
     else if (what === "projects") {
-        listProjects();
+        if (opts.json)
+            console.log(JSON.stringify({ directory: process.cwd(), projects: findProjects(process.cwd()) }));
+        else
+            listProjects();
     }
     else {
         console.error(`Unknown: '${what}'. Use 'templates' or 'projects'.`);
         process.exit(1);
     }
 });
+/** `summer list templates --json`: what the text lists, one object per template. */
+export function templatesJson() {
+    return getTemplateRegistry().map(({ id, slug, version, summary, status, builtin, systems, do_not_use_when }) => ({
+        id,
+        slug,
+        version,
+        summary,
+        status,
+        builtin,
+        systems,
+        do_not_use_when,
+    }));
+}
+/** Subdirectories of `dir` that hold a project.godot. */
+export function findProjects(dir) {
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && existsSync(join(dir, entry.name, "project.godot")))
+        .map((entry) => entry.name);
+}
 /**
  * Registry-only listing (CONTRACT.md §7): every template shown here resolves
  * through its library pin manifest. There is no live GitHub-org listing —
@@ -49,16 +75,7 @@ function listTemplates() {
 }
 function listProjects() {
     const cwd = process.cwd();
-    const entries = readdirSync(cwd, { withFileTypes: true });
-    const projects = [];
-    for (const entry of entries) {
-        if (entry.isDirectory()) {
-            const projectFile = join(cwd, entry.name, "project.godot");
-            if (existsSync(projectFile)) {
-                projects.push(entry.name);
-            }
-        }
-    }
+    const projects = findProjects(cwd);
     if (projects.length === 0) {
         console.log("No Summer Engine projects found in current directory.");
         console.log("\nCreate one: summer create 3d-basic my-game");

package/dist/cli/commands/memory.js

@@ -36,6 +36,7 @@ memoryCommand
     .command("show <file>")
     .description("Print a .summer memory Markdown file")
     .option("--project <path>", "Project directory to inspect")
+    .option("--json", "Print the file path and content as JSON")
     .action(async (file, opts) => {
     const resolvedProject = await resolveMemoryProject(opts.project);
     if (!resolvedProject.projectPath) {
@@ -44,12 +45,14 @@ memoryCommand
         process.exit(1);
     }
     const filePath = resolveMemoryFilePath(resolvedProject.projectPath, file);
-    console.log(readFileSync(filePath, "utf-8"));
+    const content = readFileSync(filePath, "utf-8");
+    console.log(opts.json ? JSON.stringify({ path: filePath, content }) : content);
 });
 memoryCommand
     .command("path")
     .description("Print the .summer directory path for the current project")
     .option("--project <path>", "Project directory to inspect")
+    .option("--json", "Print the path as JSON")
     .action(async (opts) => {
     const resolvedProject = await resolveMemoryProject(opts.project);
     if (!resolvedProject.projectPath) {
@@ -57,7 +60,8 @@ memoryCommand
         console.error("Run from a project directory, pass --project <path>, or start Summer Engine.");
         process.exit(1);
     }
-    console.log(join(resolvedProject.projectPath, ".summer"));
+    const path = join(resolvedProject.projectPath, ".summer");
+    console.log(opts.json ? JSON.stringify({ path }) : path);
 });
 async function resolveMemoryProject(projectOption) {
     if (projectOption) {

package/dist/cli/commands/ops.d.ts

@@ -1,4 +1,5 @@
 import { Command } from "commander";
+import { CLI_AREAS } from "../../core/ops/areas.js";
 import { type HostedCall } from "../../core/ops/cloud.js";
 import { type Answer } from "../../core/ops/contract.js";
 import { FileSaver } from "../../core/ops/save-files.js";
@@ -14,8 +15,7 @@ import { dispatchTool } from "../../core/capabilities/tool-dispatch.js";
  * `summer tool` runs); cloud operations run on the hosted Summer server
  * through its summer_call, with the person's sign-in.
  */
-/** Areas with operations today; CLI command words stay out of this list. */
-export declare const CLI_AREAS: readonly ["team", "profile", "docs", "assets", "makers", "jobs", "projects", "plans", "games", "store", "jams", "pricing", "analytics", "experiments", "marketing", "players", "economy", "inbox", "apps", "studio", "chats", "stories", "plugins", "engine", "account"];
+export { CLI_AREAS };
 type JsonSchema = {
     type?: string | string[];
     properties?: Record<string, JsonSchema>;
@@ -43,5 +43,22 @@ export declare const defaultOpsCliDeps: OpsCliDeps;
 export declare function formatAnswer(answer: Answer, out?: string): string;
 /** Run one operation from the command line and print its answer; returns the exit code. */
 export declare function runOpFromCli(op: string, argv: readonly string[], deps?: OpsCliDeps): Promise<number>;
+/**
+ * `summer ops search <words...>`: every operation, local and cloud, signed in
+ * or not; a cloud one that needs a sign-in says so. A how-to (docs.search
+ * first) points at the library.
+ */
+export declare function searchFromCli(query: string, options: {
+    area?: string;
+    limit: number;
+    json: boolean;
+}, deps?: OpsCliDeps): Promise<void>;
+/**
+ * `summer ops describe <op>`: a local operation from this package; a cloud
+ * one from Summer's server, or from the shipped catalog when the server
+ * cannot answer (signed out, offline).
+ */
+export declare function describeFromCli(op: string, deps?: OpsCliDeps, options?: {
+    json?: boolean;
+}): Promise<number>;
 export declare function opsCliCommands(): Command[];
-export {};