summer-engine 3.3.0 → 3.4.1

package/dist/mcp/hosted-mount.js

@@ -1,10 +1,8 @@
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
+import { connectHostedMcp } from "../core/hosted-mcp.js";
 import { getStoreAccessToken, OAuthError, resolveMcpResourceUrl } from "../core/oauth.js";
 import { appendMcpLogEvent } from "../core/mcp-log.js";
-import { TOOLKIT_VERSION } from "../core/version.js";
 /**
  * One Summer Engine MCP. The cloud tools a creator's agent needs to publish
  * (projects, store page, build upload, submit for the owner's approval, the
@@ -16,38 +14,20 @@ import { TOOLKIT_VERSION } from "../core/version.js";
  * that server). A name the local MCP already has stays local (the engine and
  * generation tools keep their CLI-token path).
  *
- * Mounting is lazy: the server answers with the engine tools at once, and the
- * hosted tools appear when the mount finishes (tools/list_changed). Without a
- * store sign-in one tool, summer_store_tools, says how to sign in and mounts
- * on the next call.
+ * Mounting runs after connect. The first tools/list waits for a mount in
+ * progress (up to FIRST_LIST_WAIT_MS), so a host that lists tools once still
+ * sees the store tools; a slower mount adds them later (tools/list_changed).
+ * Without a store sign-in the mount fails at once, and one tool,
+ * summer_store_tools, says how to sign in and mounts on the next call.
  */
 export const STORE_TOOLS_STATUS = "summer_store_tools";
-const CALL_TIMEOUT_MS = 120_000;
+/** How long the first tools/list waits for a mount in progress, so hosts that list once see the store tools. */
+export const FIRST_LIST_WAIT_MS = 5_000;
 const passthroughArgs = z.object({}).passthrough();
 export const defaultHostedMountDependencies = {
     url: () => resolveMcpResourceUrl(),
     token: () => getStoreAccessToken(),
-    connect: async (url, token) => {
-        const transport = new StreamableHTTPClientTransport(new URL(url), {
-            // A fresh (refreshed when near expiry) token on every request.
-            fetch: async (input, init) => {
-                const headers = new Headers(init?.headers);
-                headers.set("authorization", `Bearer ${await token()}`);
-                return fetch(input, { ...init, headers });
-            },
-        });
-        const client = new Client({ name: "summer-engine-local", version: TOOLKIT_VERSION });
-        await client.connect(transport);
-        const timeout = { timeout: CALL_TIMEOUT_MS };
-        return {
-            listTools: (params) => client.listTools(params),
-            callTool: (params) => client.callTool(params, undefined, timeout),
-            listPrompts: (params) => client.listPrompts(params),
-            getPrompt: (params) => client.getPrompt(params),
-            listResources: (params) => client.listResources(params),
-            readResource: (params) => client.readResource(params),
-        };
-    },
+    connect: connectHostedMcp,
 };
 async function listAll(page, key) {
     const out = [];
@@ -70,7 +50,9 @@ function errorText(error) {
  * reports each mounted tool's own JSON Schema rather than the passthrough one.
  * Returns mount(), which callers run after connect without awaiting it.
  */
-export function prepareHostedMount(server, deps = defaultHostedMountDependencies) {
+export function prepareHostedMount(server, deps = defaultHostedMountDependencies, options = {}) {
+    const firstListWaitMs = options.firstListWaitMs ?? FIRST_LIST_WAIT_MS;
+    let listed = false;
     const state = { status: "idle", tools: [], prompts: [], resources: [], collisions: [] };
     const schemas = new Map();
     const registries = server;
@@ -82,6 +64,10 @@ export function prepareHostedMount(server, deps = defaultHostedMountDependencies
     const listTools = handlers.get("tools/list");
     if (listTools) {
         server.server.setRequestHandler(ListToolsRequestSchema, async (request, extra) => {
+            if (!listed) {
+                listed = true;
+                await waitForMount(firstListWaitMs);
+            }
             const result = await listTools(request, extra);
             return {
                 ...result,
@@ -94,6 +80,14 @@ export function prepareHostedMount(server, deps = defaultHostedMountDependencies
     }
     let statusTool = null;
     let running = null;
+    /** Wait for a mount in progress, at most ms; returns at once when none runs. */
+    async function waitForMount(ms) {
+        if (!running || ms <= 0)
+            return;
+        let timer;
+        await Promise.race([running, new Promise((done) => (timer = setTimeout(done, ms)))]);
+        clearTimeout(timer);
+    }
     const showStatusTool = () => {
         if (statusTool || STORE_TOOLS_STATUS in registries._registeredTools)
             return;

package/dist/mcp/server.d.ts

@@ -6,8 +6,8 @@ export declare const getCachedBootDriftNotice: typeof getCachedNotice;
 /**
  * Server `instructions` in the MCP initialize response (SDK ServerOptions,
  * @modelcontextprotocol/sdk >= 1.x). Hosts hand this to the model once per
- * session, before any tool call — the place for the five habits the E2E run
- * (docs/design/archive/E2E-2026-09-03.md, F-17) showed an agent needs on the first
+ * session, before any tool call — the place for the five habits an end-to-end run
+ * showed an agent needs on the first
  * turn and would otherwise learn the hard way. Kept under 600 characters so
  * it costs a few hundred tokens once; the full operating guide stays in the
  * summer_agent_playbook prompt / summer_get_agent_playbook tool. The last

package/dist/mcp/server.js

@@ -34,8 +34,8 @@ export const getCachedBootDriftNotice = getCachedNotice;
 /**
  * Server `instructions` in the MCP initialize response (SDK ServerOptions,
  * @modelcontextprotocol/sdk >= 1.x). Hosts hand this to the model once per
- * session, before any tool call — the place for the five habits the E2E run
- * (docs/design/archive/E2E-2026-09-03.md, F-17) showed an agent needs on the first
+ * session, before any tool call — the place for the five habits an end-to-end run
+ * showed an agent needs on the first
  * turn and would otherwise learn the hard way. Kept under 600 characters so
  * it costs a few hundred tokens once; the full operating guide stays in the
  * summer_agent_playbook prompt / summer_get_agent_playbook tool. The last
@@ -356,8 +356,9 @@ export async function startMcpServer(options = {}) {
         appendMcpLogEvent("mcp:boot_drift_probe_failed", errorDetails(error));
     });
     // Hosted Summer Engine MCP tools (store, publishing, board, Grow): ready
-    // before connect, mounted after it without blocking the engine tools.
-    const hosted = prepareHostedMount(server);
+    // before connect, mounted after it. The first tools/list waits a few
+    // seconds for the mount (not under summer doctor, which times the list).
+    const hosted = prepareHostedMount(server, undefined, process.env.SUMMER_MCP_DOCTOR === "1" ? { firstListWaitMs: 0 } : {});
     const transport = new StdioServerTransport();
     await server.connect(transport);
     void hosted.mount();

package/dist/mcp/tools/creator-tools.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { CreatorOperationError, listCreatorReleases, publishCreator, } from "../../core/capabilities/creator.js";
+import { captureGameplay } from "../../core/capabilities/capture-gameplay.js";
 import { exportGame } from "../../core/capabilities/export-game.js";
 import { STORE_TARGETS } from "../../core/capabilities/export-presets.js";
 import { exportTemplates, TEMPLATE_PLATFORMS } from "../../core/capabilities/export-templates.js";
@@ -39,7 +40,7 @@ async function creatorResult(operation) {
     }
 }
 export function registerCreatorTools(server) {
-    server.tool("summer_export_game", "Export the game in the exact file the Summer Games store takes, with the installed Summer Engine headless (no window). format \"bundle\" (default): the summer.games .zip the Summer apps run on iPhone, Android, macOS and Windows; targets picks the platforms (a game without a server: ios and android only); upload it with summer_publish_build. format \"download\" with one target: web (an HTML5 .zip on Summer's WebGPU Forward+ web template, played on summer.games), macos (.app zip, macos-universal) or windows (.exe zip, windows-x64); these need the export template from summer_export_templates and are uploaded as store versions. Works without the editor running. Returns path, sha256, size, the manifest or store platform, and warnings.", {
+    server.tool("summer_export_game", "Export the game in the exact file the Summer Games store takes, with the installed Summer Engine headless (no window). format \"bundle\" (default): the summer.games .zip the Summer apps run on iPhone, Android, macOS and Windows; targets picks the platforms (a game without a server: ios and android only); upload it with summer_publish_build. format \"download\" with one target: web (an HTML5 .zip on Summer's WebGPU Forward+ web template, played on summer.games), macos (.app zip, macos-universal) or windows (.exe zip, windows-x64); these need the export template from summer_export_templates and are uploaded as store versions. Needs Summer Engine 0.7.0 or newer: an older engine is refused before anything is written (code engine_too_old). Works without the editor running. Returns path, sha256, size, the manifest or store platform, and warnings.", {
         project: z.string().optional().describe("Project folder with project.godot. Defaults to the MCP's bound project, then the working directory."),
         out: z.string().optional().describe("Output .zip path. Defaults to <project>/.summer/exports/."),
         targets: z
@@ -65,8 +66,17 @@ export function registerCreatorTools(server) {
             .optional()
             .describe("The installed Summer Engine version (Help > About, e.g. 0.7.1). Read automatically on macOS; needed on Windows and Linux."),
     }, async ({ action, platforms, includeDebug, summerVersion }) => creatorResult(() => exportTemplates({ action, platforms, includeDebug, summerVersion })));
-    server.tool("summer_publish_build", "Upload an export from summer_export_game to the creator's game on summer.games, through the same store upload Studio uses, straight from disk. A store bundle (format bundle): declare, upload parts, seal, wait until Summer makes the Build, name its client pack, and with publish=true approve it. A web build or native download (format download): upload it as the game's store version for its platform (web, macos-universal, windows-x64, linux-x64; read from the last export) and wait until Summer has checked it. First call with confirm=false and show the user the returned target; set confirm only after they approve. Needs \"summer login --store\". A retry with the same file and clientVersion continues the same upload. Nothing here makes a game live: the owner approves publishing (summer_store_submit).", {
-        gameId: z.string().optional().describe("The store game id (Studio store page URL). Omit to get the list of your games."),
+    server.tool("summer_capture_gameplay", "Capture real gameplay frames without a running editor: starts the game in Summer Engine's offscreen verify instance (a real renderer, a window parked offscreen with no focus, never on screen), lets it run waitSeconds, and saves PNG frames of what the game draws, HUD included. Use for store screenshots (1920x1080 landscape or 1080x1920 portrait). With an editor open, summer_screenshot target game also works. Returns each frame's path, width and height; look at them before using them.", {
+        project: z.string().optional().describe("Project folder with project.godot. Defaults to the MCP's bound project, then the working directory."),
+        scene: z.string().optional().describe("Scene to start (res://... or uid://...). Default: the project's main scene, which is often a title menu; pass the gameplay scene for gameplay frames."),
+        resolution: z.string().optional().describe("Window size WIDTHxHEIGHT (default 1920x1080; 1080x1920 for portrait)."),
+        frames: z.number().int().min(1).max(10).optional().describe("Frames to save (default 1)."),
+        waitSeconds: z.number().min(0).max(120).optional().describe("Seconds the game runs before the first frame (default 3)."),
+        intervalSeconds: z.number().min(0.1).max(60).optional().describe("Seconds between frames (default 1)."),
+        out: z.string().optional().describe("Output folder. Defaults to <project>/.summer/captures/<time>/ (ignored by git)."),
+    }, async (args) => creatorResult(() => captureGameplay(args)));
+    server.tool("summer_publish_build", "Upload an export from summer_export_game to the creator's game on summer.games, through the same store upload Studio uses, straight from disk. A store bundle (format bundle): declare, upload parts, seal, wait until Summer makes the Build, name its client pack, and with publish=true approve it. A web build or native download (format download): upload it as the game's store version for its platform (web, macos-universal, windows-x64, linux-x64; read from the last export) and wait until Summer has checked it. First call with confirm=false: it checks that the game exists for this account and warns when its store page does not list the export's platforms, then returns the target (game name and id, file, digest, size, version) to show the user; set confirm only after they approve. Needs \"summer login --store\". A retry with the same file and clientVersion continues the same upload. Nothing here makes a game live: the owner approves publishing (summer_store_submit).", {
+        gameId: z.string().optional().describe("The store game id (from summer_store_list_games, or the Studio store page URL). Without it the call fails with game_required and lists your store games, or says why the store did not list them."),
         file: z.string().optional().describe("Exported .zip. Defaults to the last summer_export_game result."),
         clientVersion: z.string().describe("Build version, vMAJOR.MINOR.PATCH (e.g. v1.0.0); a new upload needs a new version."),
         publish: z.boolean().default(false).describe("Bundles only: also approve the Build for players. A game that has not passed review keeps it as a preview; an agent needs the owner's approval."),
@@ -90,7 +100,7 @@ export function registerCreatorTools(server) {
         ...args,
         face: "mcp",
     })));
-    server.tool("summer_creator_releases", "List real creator-owned releases from the versioned Summer Platform creator API. The server independently verifies the exact publish scope and project ownership.", {
+    server.tool("summer_creator_releases", "Deprecated: lists releases on the legacy Summercraft creator API (separate sc_ token), not summer.games. For what players get on summer.games, and which upload can be released, use summer_store_releases.", {
         projectId: z.string().optional().describe("Creator project ID. Defaults to ~/.summer/config.json."),
         limit: z.number().int().min(1).max(100).default(20),
         cursor: z.string().optional().describe("Opaque nextCursor from the previous page."),

package/dist/mcp/tools/debug-tools.js

@@ -178,7 +178,7 @@ Use this when summer_get_diagnostics shows a non-zero \`debugger.warnings\` coun
     }, async ({ max_warnings, include_stack, raw }) => withEngine(async (client) => {
         // Reuses the existing GetDebuggerErrors op with type: "warning" filter.
         // Engine-side change: ScriptEditorDebugger::get_errors_data() supports
-        // include_warnings; debug_ops::get_debugger_errors honours `type` to
+        // include_warnings; the engine's GetDebuggerErrors honours `type` to
         // return warnings only. Diagnostics also exposes `warnings_data`.
         const op = {
             op: "GetDebuggerErrors",

package/dist/mcp/tools/generate-tools.js

@@ -297,19 +297,29 @@ Style presets: "realistic" (default), "cartoon", "anime", "none"
 For an alpha PNG, set removeBackground: true. Prompt wording alone does not
 guarantee transparency; background removal runs server-side after generation.
 
-The 'options' object is passed directly to the AI provider for full control.
+Size: aspectRatio (1:1, 16:9, 9:16, 4:3, 3:4, ...) or width + height (the
+smallest size you need). For store art ask width 1920 height 1080 (key art)
+or width 1080 height 1920 (tall cover): the server picks a model that reaches
+that size, or refuses a named model that cannot, before anything is spent.
+Each result reports the real width and height and the model that ran.
+
+'options' carries extra model params (seed, negative_prompt, ...); the result
+lists any the server did not use in ignoredOptions.
 
 Returns the asset with fileUrl (hosted) and localPath (temp file on disk).
 Use the Read tool on localPath to show the image to the user for approval.
 
 Cloud tool — runs on Summer's servers and works WITHOUT the Summer Engine app open.
-Requires authentication: run 'npx -y summer-engine@latest login' first.`, imageGenerationArgsSchema.shape, async ({ prompt, model, style, referenceImageUrl, removeBackground, options }) => {
+Requires authentication: run 'npx -y summer-engine@latest login' first.`, imageGenerationArgsSchema.shape, async ({ prompt, model, style, referenceImageUrl, removeBackground, aspectRatio, width, height, options }) => {
         const result = await mcpGenerate("/api/mcp/generate/image", {
             prompt,
             model,
             style,
             referenceImageUrl,
             removeBackground,
+            aspectRatio,
+            width,
+            height,
             options,
         });
         if (result.error) {
@@ -457,7 +467,7 @@ Optional rig pass (image-to-3d only):
   Set options.rig = true to add an auto-rig pass via Meshy v6. The result
   job (poll via summer_check_job) will include rigAssetId — the asset ID
   of the rigged glb. Use that rigAssetId with summer_generate_motion to
-  add animation clips. Adds ~$0.30 and ~60s to the job.
+  add animation clips. Adds ~60s to the job.
 
 Example:
   summer_generate_3d({
@@ -583,11 +593,11 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
     server.tool("summer_generate_video", `Generate a video using AI models via Summer Engine Studio.
 
 Known models (text-to-video):
-  - "ltx" (default) — LTX Video, fast (~$0.10)
-  - "kling" — Kling 2 Master, high quality (~$0.50)
-  - "kling-turbo" — Kling 2.5 Turbo Pro (~$0.30)
-  - "minimax" — MiniMax (~$0.25)
-  - "veo3" — Google Veo 3, premium (~$1.00)
+  - "ltx" (default) — LTX Video, fast
+  - "kling" — Kling 2 Master, high quality
+  - "kling-turbo" — Kling 2.5 Turbo Pro
+  - "minimax" — MiniMax
+  - "veo3" — Google Veo 3, premium
 
 Known models (image-to-video, when imageUrl provided):
   - "ltx" (default), "kling", "minimax"
@@ -688,7 +698,7 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
 Backends (pick one):
   - "meshy-library" (default) — a curated mocap clip by motionName on a
     Summer-rigged humanoid (rigAssetId from summer_generate_3d with
-    options.rig=true). Fast (~30s), cheap (~$0.10), real mocap quality.
+    options.rig=true). Fast (~30s), real mocap quality.
     Names that always work: idle, walk, run, jump, attack; anything else must
     be an exact library name.
   - "text-to-motion" — custom 2-second clips (60 frames) from text prompts on

package/dist/mcp/tools/navigation-tools.d.ts

@@ -2,6 +2,6 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 /**
  * summer_open — the MCP face of `summer open`. Same behavior as the CLI
  * (src/core/capabilities/navigation/open.ts runOpen); this file only supplies
- * the engine client and the browser launcher. Design: docs/design/NAVIGATION-DESIGN.md §3.
+ * the engine client and the browser launcher.
  */
 export declare function registerNavigationTools(server: McpServer): void;

package/dist/mcp/tools/navigation-tools.js

@@ -6,7 +6,7 @@ import { openArgsShape, runOpen } from "../../core/capabilities/navigation/open.
 /**
  * summer_open — the MCP face of `summer open`. Same behavior as the CLI
  * (src/core/capabilities/navigation/open.ts runOpen); this file only supplies
- * the engine client and the browser launcher. Design: docs/design/NAVIGATION-DESIGN.md §3.
+ * the engine client and the browser launcher.
  */
 export function registerNavigationTools(server) {
     server.tool("summer_open", `Open the exact summerengine.com page or Summer Engine editor surface the user wants to LOOK at, by intent name — or, with open:false, return the URL / engine op without opening anything. The result ALWAYS carries the resolved url or op, also after opening, so you can tell the user where they landed.

package/dist/mcp/tools/spatial-tools.js

@@ -16,7 +16,7 @@ const NODE_PATH_LIMIT_BYTES = 256;
 const MIN_PLACEMENT_FLOOR_DISTANCE = 0.001;
 /** Mirrors the engine's SnapToSurface direction guard (length² > 1e-5). */
 const MIN_SNAP_DIRECTION_LENGTH_SQUARED = 0.00001;
-/** Starcast's own ceilings (engine spatial_ops.cpp starcast_3d): the engine
+/** Starcast's own ceilings in the engine: the engine
  *  measures the compact receipt as UTF-8 JSON, downgrades full -> summary
  *  above 12 KiB, and strips secondary paths above 5 KiB, so a receipt past the
  *  ceiling for its returnedDetail is one this CLI does not understand. Unlike

package/dist/mcp/tools/visual-tools.js

@@ -353,8 +353,8 @@ Static frame only — one moment, not motion. For a SEQUENCE of frames over time
                     if (snap.sceneHadLight === false) {
                         warnings.push("WARNING: this scene has no light — lit materials may appear black when played.");
                     }
-                    // The engine ALWAYS synthesizes the preview camera (preview_ops.cpp
-                    // sets used_synthetic_camera unconditionally) — the flag says nothing
+                    // The engine ALWAYS synthesizes the preview camera (it sets
+                    // used_synthetic_camera unconditionally) — the flag says nothing
                     // about the scene's own cameras. sceneHasCamera above is the
                     // authoritative "does this scene have a camera" answer.
                     if (snap.usedSyntheticCamera) {

package/dist/mcp/tools/with-engine.d.ts

@@ -41,8 +41,7 @@ export interface WithEngineOptions<T> {
 }
 /**
  * An auth failure is the ONE class of thrown error that is provably pre-apply:
- * the engine rejects on the Bearer-token check (tool_net_thread.cpp::_validate_auth)
- * BEFORE the op is queued or applied, so reconnecting with the fresh api-token and
+ * the engine rejects on the Bearer-token check BEFORE the op is queued or applied, so reconnecting with the fresh api-token and
  * retrying cannot double-apply a mutation. This is exactly the stale-token case
  * after the engine rotates its api-token on relaunch.
  *

package/dist/mcp/tools/with-engine.js

@@ -30,8 +30,7 @@ function readClassifiers(result) {
 }
 /**
  * An auth failure is the ONE class of thrown error that is provably pre-apply:
- * the engine rejects on the Bearer-token check (tool_net_thread.cpp::_validate_auth)
- * BEFORE the op is queued or applied, so reconnecting with the fresh api-token and
+ * the engine rejects on the Bearer-token check BEFORE the op is queued or applied, so reconnecting with the fresh api-token and
  * retrying cannot double-apply a mutation. This is exactly the stale-token case
  * after the engine rotates its api-token on relaunch.
  *

package/gemini-extension.json

@@ -1,7 +1,7 @@
 {
   "_generated": "GENERATED from integrations/gemini — do not edit; npm run generate:registry",
   "name": "summer",
-  "version": "3.3.0",
+  "version": "3.4.1",
   "description": "Agent tooling for Summer Engine: MCP bridge, context primer, and game-dev skills. Use with the npm CLI for skill files on disk.",
   "contextFileName": "GEMINI.md",
   "mcpServers": {
@@ -35,6 +35,7 @@
     "./library/skills/asset-strategy/",
     "./library/skills/audio-direction/",
     "./library/skills/auto-fire-targeting/",
+    "./library/skills/bounded-engine-runs/",
     "./library/skills/brainstorm-game/",
     "./library/skills/brainstorming/",
     "./library/skills/browse-templates/",
@@ -46,6 +47,7 @@
     "./library/skills/character-portrait/",
     "./library/skills/cinematic-cutscene/",
     "./library/skills/combat-basics/",
+    "./library/skills/compatibility-renderer-traps/",
     "./library/skills/concept-art/",
     "./library/skills/create-asset-sheet/",
     "./library/skills/debug/",

package/hooks/session-start.sh

@@ -3,8 +3,8 @@
 #
 # Event:    SessionStart (matcher: startup|clear|compact)
 # Purpose:  Orient Claude on every fresh Summer-enabled session.
-#           Detect Summer project + GameSoul + doctor health, surface a one-line
-#           Bob-style greeting as additional context.
+#           Detect Summer project + GameSoul + doctor health and surface a short
+#           greeting as additional context.
 #
 # Input:    JSON on stdin with { session_id, source, model, cwd, ... }
 #           Common Claude Code env vars: $CLAUDE_PROJECT_DIR, $CLAUDE_PLUGIN_ROOT

package/integrations/README.md

@@ -1,94 +1,88 @@
-# integrations/ — the complete, honest map of agent support
+# integrations/: which agents Summer supports
 
-One folder per supported client. This directory is the single place that
-says which agents Summer supports and how each one consumes the library.
-Adding a new agent = one row in `src/installer/agent-table.ts` + one folder
-here + an empty entry in `scripts/generate-registry/targets.ts` (plus, if it
-has a manifest file, a builder in `scripts/generate-registry/manifests.ts`) +
-`npm run generate:registry` — never hand-editing root files. Tests fail when
-the table, this directory, and targets.ts disagree.
+One folder per supported client. Each folder says how that client consumes
+the library.
+
+Adding an agent: one row in `src/installer/agent-table.ts`, one folder here,
+an empty entry in `scripts/generate-registry/targets.ts` (plus a builder in
+`scripts/generate-registry/manifests.ts` if the client has a manifest file),
+then `npm run generate:registry`. Never hand-edit root files. Tests fail when
+the table, this directory and `targets.ts` disagree.
 
 Each folder contains:
 
-- `README.md` — what gets generated where, or (for clients with no manifest
-  file in this repo) exactly what `summer setup <client>` writes at install
-  time: MCP config path and skills destination.
+- `README.md`: what gets generated where, or (for clients with no manifest
+  file in this repo) what `summer setup <client>` writes at install time.
+- `manifest-target.json`: generated file -> repo-root destination (empty when
+  nothing is generated). Mirrors `scripts/generate-registry/targets.ts`; a test
+  fails if they drift.
 
-`summer setup <client>` (default `--scope user`) writes the MCP config AND
-installs every skill (`skills install --all`, preview included; `--stable-only`
-skips preview) in the SAME scope,
-so a user-scope MCP config never ends up beside project-scope skills.
-`--scope project` moves both; `--recommended` installs only the recommended
-subset. Clients whose MCP config is user-only (see the table) fall back to user
-scope with a warning. `.mcp.json` at the repo root
-(the MCP pointer the claude / codex / cursor / factory manifests share) is
-generated too — `registry/generated/mcp.json -> .mcp.json`.
-- `manifest-target.json` — mapping of generated file -> repo-root destination
-  (empty when nothing is generated). Mirrors
-  `scripts/generate-registry/targets.ts`; a test fails if they drift.
+`summer setup <client>` (default `--scope user`) writes the MCP config and
+installs every skill (`skills install --all`, preview included;
+`--stable-only` skips preview) in the same scope, so a user-scope MCP config
+never sits beside project-scope skills. `--scope project` moves both;
+`--recommended` installs only the recommended subset. Clients whose MCP config
+is user-only fall back to user scope with a warning.
 
-Generated root dot-files (`.claude-plugin/plugin.json`, `gemini-extension.json`,
-…) are build artifacts of `integrations/<agent>` + `library/` — their
-`_generated` banner says so ("GENERATED from integrations/<agent> — do not
-edit; npm run generate:registry"). CI `--check` fails on any drift between
-`library/`, `registry/generated/`, and the applied root files.
+Generated root files (`.claude-plugin/plugin.json`, `gemini-extension.json`,
+`.mcp.json`, …) are build artifacts of `integrations/<agent>` + `library/`.
+Their `_generated` banner says so. CI `--check` fails on any drift between
+`library/`, `registry/generated/` and the applied root files.
 
 How the plugin manifests reference skills, and what is verified:
 
-- **Claude Code** — the plugin-manifest `skills` field accepts a string or an
-  array of `./`-relative directory paths and *extends* the default `skills/`
-  scan (Claude Code plugins reference, "Plugin manifest schema"). The
-  generated `.claude-plugin/plugin.json` lists one entry per skill
-  (`./library/skills/<slug>/`). The docs do not say whether a listed
-  directory is loaded as one skill or scanned for skill subfolders, and this
-  repo has not yet loaded the generated manifest through the real plugin
-  path (the smoke tests exercise the `summer setup` install path, not the
-  marketplace one) — treat the marketplace install as unverified until that
-  run exists.
-- **Codex** — `.codex-plugin/plugin.json` carries the same per-skill `skills`
-  array. Whether Codex reads that field, and with which type, is
-  **unverified**; the v2 manifest carried it and nobody has confirmed a load.
-- **Factory** — reads skills only from a root `skills/` directory; the
-  manifest's `skills` array is not read (open gap, see the table).
+- **Claude Code**: the plugin-manifest `skills` field accepts a string or an
+  array of `./`-relative directory paths and extends the default `skills/`
+  scan. The generated `.claude-plugin/plugin.json` lists one entry per skill
+  (`./library/skills/<slug>/`). The docs do not say whether a listed directory
+  loads as one skill or is scanned for skill subfolders, and the smoke tests
+  cover the `summer setup` path, not the marketplace one. Treat the
+  marketplace install as unverified.
+- **Codex**: `.codex-plugin/plugin.json` carries the same `skills` array.
+  Whether Codex reads that field is **unverified**.
+- **Factory**: a plugin install reads skills only from a root `skills/`
+  directory, so it exposes no skills. `summer setup factory` installs them.
+
+Paths below are for macOS; `~` is `%USERPROFILE%` on Windows. Other OS paths
+are listed where they differ.
 
 | Client | Manifest generated in this repo | `summer setup` writes |
 |---|---|---|
-| claude | `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `.mcp.json` | MCP: `~/.claude.json`; Windows `%USERPROFILE%/.claude.json` / `.mcp.json`; skills: `~/.claude/skills` / `.claude/skills` (`<skill>/SKILL.md`) |
+| claude | `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `.mcp.json` | MCP: `~/.claude.json`; project `.mcp.json`; skills: `~/.claude/skills`; project `.claude/skills` (`<skill>/SKILL.md`) |
 | claude-desktop | — | MCP: `~/Library/Application Support/Claude/claude_desktop_config.json`; Linux `~/.config/Claude/claude_desktop_config.json`; Windows `%APPDATA%/Claude/claude_desktop_config.json`; no skills folder (MCP only) |
-| codex | `.codex-plugin/plugin.json` | MCP: `~/.codex/config.toml`; Windows `%USERPROFILE%/.codex/config.toml` / `.codex/config.toml`; skills: `~/.agents/skills` / `.agents/skills` (`<skill>/SKILL.md`) |
-| cursor | `.cursor-plugin/plugin.json` | MCP: `~/.cursor/mcp.json`; Windows `%USERPROFILE%/.cursor/mcp.json` / `.cursor/mcp.json`; skills: `~/.cursor/skills` / `.cursor/skills` (`<skill>/SKILL.md`) |
-| windsurf | — | MCP: `~/.codeium/windsurf/mcp_config.json`; Windows `%USERPROFILE%/.codeium/windsurf/mcp_config.json`; skills: `~/.codeium/windsurf/skills` / `.windsurf/skills` (`<skill>/SKILL.md`) |
-| antigravity | — | MCP: `~/.gemini/config/mcp_config.json`; Windows `%USERPROFILE%/.gemini/config/mcp_config.json` / `.agents/mcp_config.json`; skills: `~/.gemini/config/skills` / `.agents/skills` (`<skill>/SKILL.md`) |
-| gemini (legacy) | `gemini-extension.json` | MCP: `~/.gemini/extensions/summer-engine/gemini-extension.json`; Windows `%USERPROFILE%/.gemini/extensions/summer-engine/gemini-extension.json`; skills: `~/.gemini/extensions/summer-engine/skills` (`<skill>/SKILL.md`) |
-| cline | — | MCP: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`; Linux `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`; Windows `%APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`; skills: `~/.cline/skills` / `.cline/skills` (`<skill>/SKILL.md`) |
-| cline-cli | — | MCP: `~/.cline/data/settings/cline_mcp_settings.json`; Windows `%USERPROFILE%/.cline/data/settings/cline_mcp_settings.json`; skills: `~/.cline/skills` / `.cline/skills` (`<skill>/SKILL.md`) |
-| roo-code (legacy) | — | MCP: `~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json`; Linux `~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json`; Windows `%APPDATA%/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json`; skills: `~/Documents/Roo/Rules` / `.clinerules` (rule files `summer-<skill>.md`) |
-| kilo-code | — | MCP: `~/.config/kilo/kilo.json`; Windows `%APPDATA%/kilo/kilo.json` / `kilo.json`; skills: `~/.kilo/skills` / `.kilo/skills` (`<skill>/SKILL.md`) |
-| github-copilot | — | MCP: `~/.copilot/mcp-config.json`; Windows `%USERPROFILE%/.copilot/mcp-config.json` / `.mcp.json`; skills: `~/.copilot/skills` / `.github/skills` (`<skill>/SKILL.md`) |
-| vscode-copilot | — | MCP: `~/Library/Application Support/Code/User/mcp.json`; Linux `~/.config/Code/User/mcp.json`; Windows `%APPDATA%/Code/User/mcp.json` / `.vscode/mcp.json`; skills: `~/.copilot/skills` / `.github/skills` (`<skill>/SKILL.md`) |
-| visual-studio | — | MCP: `~/.mcp.json`; Windows `%USERPROFILE%/.mcp.json` / `.mcp.json`; no skills folder (MCP only) |
+| codex | `.codex-plugin/plugin.json` | MCP: `~/.codex/config.toml`; project `.codex/config.toml`; skills: `~/.agents/skills`; project `.agents/skills` (`<skill>/SKILL.md`) |
+| cursor | `.cursor-plugin/plugin.json` | MCP: `~/.cursor/mcp.json`; project `.cursor/mcp.json`; skills: `~/.agents/skills`; project `.agents/skills` (`<skill>/SKILL.md`) |
+| windsurf | — | MCP: `~/.codeium/windsurf/mcp_config.json`; skills: `~/.agents/skills`; project `.agents/skills` (`<skill>/SKILL.md`) |
+| antigravity | — | MCP: `~/.gemini/config/mcp_config.json`; project `.agents/mcp_config.json`; skills: `~/.gemini/config/skills`; project `.agents/skills` (`<skill>/SKILL.md`) |
+| gemini (legacy) | `gemini-extension.json` | MCP: `~/.gemini/extensions/summer-engine/gemini-extension.json`; skills: `~/.gemini/extensions/summer-engine/skills` (`<skill>/SKILL.md`) |
+| cline | — | MCP: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`; Linux `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`; Windows `%APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`; skills: `~/.cline/skills`; project `.cline/skills` (`<skill>/SKILL.md`) |
+| cline-cli | — | MCP: `~/.cline/data/settings/cline_mcp_settings.json`; skills: `~/.cline/skills`; project `.cline/skills` (`<skill>/SKILL.md`) |
+| roo-code (legacy) | — | MCP: `~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json`; Linux `~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json`; Windows `%APPDATA%/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json`; skills: `~/Documents/Roo/Rules`; project `.clinerules` (rule files `summer-<skill>.md`) |
+| kilo-code | — | MCP: `~/.config/kilo/kilo.json`; Windows `%APPDATA%/kilo/kilo.json`; project `kilo.json`; skills: `~/.kilo/skills`; project `.kilo/skills` (`<skill>/SKILL.md`) |
+| github-copilot | — | MCP: `~/.copilot/mcp-config.json`; project `.mcp.json`; skills: `~/.copilot/skills`; project `.github/skills` (`<skill>/SKILL.md`) |
+| vscode-copilot | — | MCP: `~/Library/Application Support/Code/User/mcp.json`; Linux `~/.config/Code/User/mcp.json`; Windows `%APPDATA%/Code/User/mcp.json`; project `.vscode/mcp.json`; skills: `~/.agents/skills`; project `.agents/skills` (`<skill>/SKILL.md`) |
+| visual-studio | — | MCP: `~/.mcp.json`; project `.mcp.json`; no skills folder (MCP only) |
 | copilot-jetbrains | — | MCP: `~/.config/github-copilot/intellij/mcp.json`; Windows `%APPDATA%/github-copilot/intellij/mcp.json`; no skills folder (MCP only) |
-| opencode | — | MCP: `~/.config/opencode/opencode.json`; Windows `%APPDATA%/opencode/opencode.json` / `opencode.json`; skills: `~/.config/opencode/skills` / `.opencode/skills` (`<skill>/SKILL.md`) |
-| zed | — | MCP: `~/.config/zed/settings.json`; Windows `%APPDATA%/zed/settings.json`; skills: `~/.agents/skills` / `.agents/skills` (`<skill>/SKILL.md`) |
-| kiro | — | MCP: `~/.kiro/settings/mcp.json`; Windows `%USERPROFILE%/.kiro/settings/mcp.json` / `.kiro/settings/mcp.json`; skills: `~/.kiro/skills` / `.kiro/skills` (`<skill>/SKILL.md`) |
-| goose | — | MCP: `~/.config/goose/config.yaml`; Windows `%APPDATA%/Block/goose/config/config.yaml`; skills: `~/.config/agents/skills` / `.agents/skills` (`<skill>/SKILL.md`) |
-| hermes | — | MCP: `~/.hermes/config.yaml`; Windows `%USERPROFILE%/.hermes/config.yaml`; skills: `~/.hermes/skills` / `.hermes/skills` (`<skill>/SKILL.md`) |
-| trae | — | MCP: `.trae/mcp.json` / `.trae/mcp.json`; no skills folder (MCP only) |
-| qwen-code | — | MCP: `~/.qwen/settings.json`; Windows `%USERPROFILE%/.qwen/settings.json` / `.qwen/settings.json`; skills: `~/.qwen/skills` / `.qwen/skills` (`<skill>/SKILL.md`) |
-| kimi-code | — | MCP: `~/.kimi-code/mcp.json`; Windows `%USERPROFILE%/.kimi-code/mcp.json` / `.kimi-code/mcp.json`; skills: `~/.kimi-code/skills` / `.kimi-code/skills` (`<skill>/SKILL.md`) |
-| crush | — | MCP: `~/.config/crush/crushrc`; Windows `%USERPROFILE%/.config/crush/crushrc` / `.crushrc`; skills: `~/.config/crush/skills` / `.crush/skills` (`<skill>/SKILL.md`) |
-| amp | — | MCP: `~/.config/amp/settings.json`; Windows `%APPDATA%/amp/settings.json`; skills: `~/.config/amp/skills` / `.agents/skills` (`<skill>/SKILL.md`) |
-| factory | `.factory-plugin/plugin.json` | MCP: `~/.factory/mcp.json`; Windows `%USERPROFILE%/.factory/mcp.json` / `.factory/mcp.json`; skills: `~/.factory/skills` / `.factory/skills` (`<skill>/SKILL.md`) |
-| junie | — | MCP: `~/.junie/mcp/mcp.json`; Windows `%USERPROFILE%/.junie/mcp/mcp.json` / `.junie/mcp/mcp.json`; no skills folder (MCP only) |
-| warp | — | MCP: `~/.warp/.mcp.json`; Windows `%USERPROFILE%/.warp/.mcp.json` / `.warp/.mcp.json`; skills: `~/.warp/skills` / `.warp/skills` (`<skill>/SKILL.md`) |
-| rovo-dev | — | MCP: `~/.rovodev/mcp.json`; Windows `%USERPROFILE%/.rovodev/mcp.json`; skills: `~/.rovodev/skills` / `.rovodev/skills` (`<skill>/SKILL.md`) |
-| qoder | — | MCP: `~/.qoder/settings.json`; Windows `%USERPROFILE%/.qoder/settings.json` / `.mcp.json`; skills: `~/.qoder/skills` / `.qoder/skills` (`<skill>/SKILL.md`) |
-| grok-build | — | MCP: `~/.grok/config.toml`; Windows `%USERPROFILE%/.grok/config.toml` / `.grok/config.toml`; skills: `~/.grok/skills` / `.grok/skills` (`<skill>/SKILL.md`) |
-| mistral-vibe | — | MCP: `~/.vibe/config.toml`; Windows `%USERPROFILE%/.vibe/config.toml` / `.vibe/config.toml`; skills: `~/.vibe/skills` / `.vibe/skills` (`<skill>/SKILL.md`) |
-| lm-studio | — | MCP: `~/.lmstudio/mcp.json`; Windows `%USERPROFILE%/.lmstudio/mcp.json`; no skills folder (MCP only) |
+| opencode | — | MCP: `~/.config/opencode/opencode.json`; Windows `%APPDATA%/opencode/opencode.json`; project `opencode.json`; skills: `~/.agents/skills`; project `.agents/skills` (`<skill>/SKILL.md`) |
+| zed | — | MCP: `~/.config/zed/settings.json`; Windows `%APPDATA%/zed/settings.json`; skills: `~/.agents/skills`; project `.agents/skills` (`<skill>/SKILL.md`) |
+| kiro | — | MCP: `~/.kiro/settings/mcp.json`; project `.kiro/settings/mcp.json`; skills: `~/.kiro/skills`; project `.kiro/skills` (`<skill>/SKILL.md`) |
+| goose | — | MCP: `~/.config/goose/config.yaml`; Windows `%APPDATA%/Block/goose/config/config.yaml`; skills: `~/.config/agents/skills`; project `.agents/skills` (`<skill>/SKILL.md`) |
+| hermes | — | MCP: `~/.hermes/config.yaml`; skills: `~/.hermes/skills`; project `.agents/skills` (`<skill>/SKILL.md`) |
+| trae | — | MCP: `.trae/mcp.json` (project only); no skills folder (MCP only) |
+| qwen-code | — | MCP: `~/.qwen/settings.json`; project `.qwen/settings.json`; skills: `~/.qwen/skills`; project `.qwen/skills` (`<skill>/SKILL.md`) |
+| kimi-code | — | MCP: `~/.kimi-code/mcp.json`; project `.kimi-code/mcp.json`; skills: `~/.agents/skills`; project `.agents/skills` (`<skill>/SKILL.md`) |
+| crush | — | MCP: `~/.config/crush/crushrc`; project `.crushrc`; skills: `~/.agents/skills`; project `.agents/skills` (`<skill>/SKILL.md`) |
+| amp | — | MCP: `~/.config/amp/settings.json`; Windows `%APPDATA%/amp/settings.json`; skills: `~/.agents/skills`; project `.agents/skills` (`<skill>/SKILL.md`) |
+| factory | `.factory-plugin/plugin.json` | MCP: `~/.factory/mcp.json`; project `.factory/mcp.json`; skills: `~/.agents/skills`; project `.agents/skills` (`<skill>/SKILL.md`) |
+| junie | — | MCP: `~/.junie/mcp/mcp.json`; project `.junie/mcp/mcp.json`; no skills folder (MCP only) |
+| warp | — | MCP: `~/.warp/.mcp.json`; project `.warp/.mcp.json`; skills: `~/.agents/skills`; project `.agents/skills` (`<skill>/SKILL.md`) |
+| rovo-dev | — | MCP: `~/.rovodev/mcp.json`; skills: `~/.agents/skills`; project `.agents/skills` (`<skill>/SKILL.md`) |
+| qoder | — | MCP: `~/.qoder/settings.json`; project `.mcp.json`; skills: `~/.qoder/skills`; project `.qoder/skills` (`<skill>/SKILL.md`) |
+| grok-build | — | MCP: `~/.grok/config.toml`; project `.grok/config.toml`; skills: `~/.agents/skills`; project `.agents/skills` (`<skill>/SKILL.md`) |
+| mistral-vibe | — | MCP: `~/.vibe/config.toml`; project `.vibe/config.toml`; skills: `~/.vibe/skills`; project `.agents/skills` (`<skill>/SKILL.md`) |
+| lm-studio | — | MCP: `~/.lmstudio/mcp.json`; no skills folder (MCP only) |
 
-Source of truth for the setup paths: `src/installer/agent-config.ts` and
-`src/cli/commands/skills.ts`.
+Source of truth for the setup paths: `src/installer/agent-table.ts`.
 
 Not supported on purpose (checked 2026-09-11): OpenHands CLI (its `[mcp] stdio_servers`
 inline-table array has a known upstream write bug), Xcode's agent folders (Apple

package/integrations/claude/README.md

@@ -11,9 +11,6 @@ Generated by `scripts/generate-registry` from `library/**/resource.yaml`:
 The MCP pointer `./.mcp.json` these manifests reference is generated as
 well (`registry/generated/mcp.json -> .mcp.json`, owned by the claude target).
 
-The MCP pointer `./.mcp.json` these manifests reference is generated as
-well (`registry/generated/mcp.json -> .mcp.json`).
-
 Never edit the destination files by hand — edit `library/` resources or the
 manifest builders in `scripts/generate-registry/manifests.ts`, then run
 `npm run generate:registry`. CI `--check` fails on any drift.

package/integrations/codex/README.md

@@ -4,8 +4,7 @@ Generated by `scripts/generate-registry` from `library/**/resource.yaml`:
 
 - `registry/generated/plugin.codex.json` -> `.codex-plugin/plugin.json`
   (plugin manifest with the Codex app-store `interface` block; full skill
-  list at `./library/skills/<slug>/` — the pre-v3 four-skill gap was a bug and
-  is fixed by generation; version stamped from `package.json`).
+  list at `./library/skills/<slug>/`; version stamped from `package.json`).
 
 The MCP pointer `./.mcp.json` these manifests reference is generated as
 well (`registry/generated/mcp.json -> .mcp.json`, owned by the claude target).

package/integrations/copilot-jetbrains/README.md

@@ -5,7 +5,7 @@ is intentionally empty. Support is delivered at install time by
 `summer setup copilot-jetbrains` (aliases: `jetbrains-copilot`, `intellij-copilot`, `copilot-intellij`), which writes:
 
 - MCP config: `~/.config/github-copilot/intellij/mcp.json`; Windows `%APPDATA%/github-copilot/intellij/mcp.json` (user); user scope only (project requests fall back with a warning).
-  Shape: undefined.
+  Shape: `servers.summer-engine = { command, args }`.
 - Skills: none. Copilot in JetBrains documents no skills folder; the MCP server ships summer_get_agent_playbook for in-chat guidance.
 - After: Restart the JetBrains IDE and open Copilot Chat in Agent mode; summer-engine shows in the tools list.
 

package/integrations/cursor/README.md

@@ -5,8 +5,7 @@ Generated by `scripts/generate-registry` from `library/**/resource.yaml`:
 - `registry/generated/plugin.cursor.json` -> `.cursor-plugin/plugin.json`
   (Cursor plugin manifest: displayName/publisher/category, cursor-specific
   hooks file `./hooks/hooks-cursor.json`, full skill list at
-  `./library/skills/<slug>/` — the pre-v3 four-skill gap was a bug and is fixed
-  by generation; version stamped from `package.json`).
+  `./library/skills/<slug>/`; version stamped from `package.json`).
 
 The MCP pointer `./.mcp.json` these manifests reference is generated as
 well (`registry/generated/mcp.json -> .mcp.json`, owned by the claude target).