summer-engine 3.6.0 → 3.8.0

package/dist/mcp/server.js

@@ -16,6 +16,7 @@ import { registerEventTools } from "./tools/event-tools.js";
 import { registerFabricateTools } from "./tools/fabricate-tools.js";
 import { registerUiTools } from "./tools/ui-tools.js";
 import { registerRuntimeTools } from "./tools/runtime-tools.js";
+import { registerAppTools } from "./tools/app-tools.js";
 import { recordToolCall, registrationHasInputSchema, trajectoryArgsFor, } from "../core/trajectory.js";
 import { registerFileTools } from "./tools/file-tools.js";
 import { registerAssetTools } from "./tools/asset-tools.js";
@@ -40,14 +41,15 @@ export const getCachedBootDriftNotice = getCachedNotice;
  * 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
- * sentence names the publishing path and the owner-approval rule.
+ * sentence names the publishing path, the owner-approval rule and where
+ * review feedback is read.
  */
-export const SUMMER_MCP_INSTRUCTIONS = "Summer Engine MCP. Call summer_get_project_context first: it binds the open project and returns mainScene, projectMemory and any capabilitySkewWarning. " +
+export const SUMMER_MCP_INSTRUCTIONS = "Summer Engine MCP. Call summer_get_project_context first: it binds the open project, returns mainScene, projectMemory, any capabilitySkewWarning. " +
     "Before building or fixing, summer_search_library then summer_read_library the hit. " +
-    "After a playthrough read summer_get_diagnostics, not summer_get_console alone. " +
-    "An all-black screenshot means the viewport had not redrawn: recapture. " +
+    "After play, read summer_get_diagnostics, not summer_get_console alone. " +
+    "An all-black screenshot means no redraw yet: recapture. " +
     "Report verified entries via summer_library_feedback. " +
-    "Publishing: summer_export_game, summer_publish_build, summer_store_*; an agent never publishes alone: summer_store_submit returns the owner's approval link.";
+    "Publishing: summer_export_game, summer_publish_build, summer_store_*; agents never publish alone: summer_store_submit returns the owner's approval link; summer_store_review, feedback to fix.";
 /**
  * Fire-and-forget probe of the npm registry on MCP boot. Caches the result for
  * the session. We never await this in startup so a slow / offline registry
@@ -327,6 +329,7 @@ export function createMcpServer() {
     registerFabricateTools(server);
     registerUiTools(server);
     registerRuntimeTools(server);
+    registerAppTools(server);
     // The playbook is also an MCP prompt so prompt-surfacing hosts get it
     // natively (same content as the summer_get_agent_playbook tool).
     registerPlaybookPrompt(server);

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

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerAppTools(server: McpServer): void;

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

@@ -0,0 +1,64 @@
+import { MAX_APP_EVENTS_WAIT_SECONDS, APP_DOCK_FALLBACK, appCall, appCallArgsSchema, appCreate, appCreateArgsSchema, appData, appDataArgsSchema, appDockArgsSchema, appDockOp, appEvents, appEventsArgsSchema, appGet, appGetArgsSchema, appGuide, appGuideArgsSchema, appList, appListArgsSchema, appPage, appPageArgsSchema, appPublish, appPublishArgsSchema, appReportGap, appReportGapArgsSchema, appScreenshot, appScreenshotArgsSchema, appUpdate, appUpdateArgsSchema, appsGateway, appTools, appToolsArgsSchema, } from "../../core/capabilities/apps.js";
+import { enablePluginArgsSchema, enablePluginOp, interpretEnablePluginResult } from "../../core/capabilities/enable-plugin.js";
+import { missingEngineOpResult, withEngine } from "./with-engine.js";
+/**
+ * Summer Apps over MCP: tools a game team uses inside Summer Studio, built by
+ * the agent. Shared implementation: core/capabilities/apps.ts.
+ */
+const CLOUD = "Cloud tool: runs on Summer's servers and works without the Summer Engine app open. Requires sign-in: npx -y summer-engine@latest login.";
+function result(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], ...(value.ok === false ? { isError: true } : {}) };
+}
+/** The MCP handler of one cloud tool: validate with the shared schema, call the web API. */
+function cloud(name, schema, run) {
+    return async (args) => {
+        const parsed = schema.safeParse(args ?? {});
+        if (!parsed.success)
+            return result({ ok: false, code: "invalid", error: parsed.error.issues[0]?.message ?? "Invalid arguments" });
+        return result(await run(parsed.data, { request: appsGateway("mcp", name) }));
+    };
+}
+export function registerAppTools(server) {
+    server.tool("summer_app_guide", `Read this before building or changing a Summer App (a tool for the person's team inside Summer Studio, live on their assets, game data and engine): when to build one, Layout vs code, the build loop, manifest schema, SDK reference, UI kit, layout format, design rules and four worked examples. section returns one part.\n\n${CLOUD}`, appGuideArgsSchema.shape, cloud("summer_app_guide", appGuideArgsSchema, appGuide));
+    server.tool("summer_app_list", `The Summer Apps in the person's workspaces: id, name, purpose, folder, status (scratch, kept, archived), version, format.\n\n${CLOUD}`, appListArgsSchema.shape, cloud("summer_app_list", appListArgsSchema, appList));
+    server.tool("summer_app_create", `Create a new scratch Summer App; their open Summer Studio tab opens it. Without workspaceId it goes to the person's team (the one their Studio tab is on, else their latest team, else personal); the result's workspace says which: tell the person. Read summer_app_guide first. format code (index.html + JS/CSS) or layout (a JSON layout of kit nodes for a quick decision UI). Then summer_app_publish.\n\n${CLOUD}`, appCreateArgsSchema.shape, cloud("summer_app_create", appCreateArgsSchema, appCreate));
+    server.tool("summer_app_publish", `Publish a new immutable version of a Summer App: dir (a local folder with index.html at its root) or files [{path, content, encoding}] for code apps, layout for layout apps, plus the manifest. Limits: 10 MB, 300 files, 5 MB per file. The person's Studio tab boots it. An error names the file or rule to fix: fix it and publish again.\n\n${CLOUD}`, appPublishArgsSchema.shape, cloud("summer_app_publish", appPublishArgsSchema, appPublish));
+    server.tool("summer_app_get", `A Summer App's manifest, its current version's files (or layout) and a summary of its shared data. Use it before changing an app.\n\n${CLOUD}`, appGetArgsSchema.shape, cloud("summer_app_get", appGetArgsSchema, appGet));
+    server.tool("summer_app_update", `Rename a Summer App, change its purpose or folder, or set its status: kept (the team keeps it), archived (hidden from the app list; restore with scratch or kept), scratch. Archive the scratch apps you made that the person did not keep.\n\n${CLOUD}`, appUpdateArgsSchema.shape, cloud("summer_app_update", appUpdateArgsSchema, appUpdate));
+    server.tool("summer_app_events", `Wait for what a Summer App sends you: summer.agent.send events (kind agent), errors in the app (kind error), feedback (kind feedback), agent tool calls (kind tool). Waits up to timeoutSeconds (max ${MAX_APP_EVENTS_WAIT_SECONDS}) for the first event after the cursor; pass the returned cursor as after next time.\n\n${CLOUD}`, appEventsArgsSchema.shape, cloud("summer_app_events", appEventsArgsSchema, appEvents));
+    server.tool("summer_app_page", `Read or use the fields and buttons a Summer App declared while it is open in the person's Studio tab or editor dock: no fill and no press reads the page; fill [{field, value}] and press an action id use it. Critical actions (delete, publish, pay, send) are pressed only by the person. app_not_open when the app is not open.\n\n${CLOUD}`, appPageArgsSchema.shape, cloud("summer_app_page", appPageArgsSchema, appPage));
+    server.tool("summer_app_screenshot", `See a Summer App without the person: Summer renders its current version (or version) headless with the person's data and returns the picture plus what to fix: console lines, uncaught errors, refused calls, whether the SDK connected and rendered, and the fields, buttons and agent tools it declared. Read-only: writes, sends and paid calls are refused, nothing changes. width 390 for a phone, theme dark, fullPage for the whole scroll; out also saves the PNG. Use it after every publish.\n\n${CLOUD}`, appScreenshotArgsSchema.shape, async (args) => {
+        const parsed = appScreenshotArgsSchema.safeParse(args ?? {});
+        if (!parsed.success)
+            return result({ ok: false, code: "invalid", error: parsed.error.issues[0]?.message ?? "Invalid arguments" });
+        const shot = await appScreenshot(parsed.data, { request: appsGateway("mcp", "summer_app_screenshot") });
+        if (shot.ok !== true || !("image" in shot))
+            return result(shot);
+        const { image, ...report } = shot;
+        return { content: [{ type: "image", data: image.base64, mimeType: image.mimeType }, { type: "text", text: JSON.stringify(report, null, 2) }] };
+    });
+    server.tool("summer_app_data", `Read or write a Summer App's shared data, its API: works with no app open, and everyone in the app sees writes live. Without ops it reads records (paged with after) plus declaredCollections, the record shape the app declares; with ops it writes them in one revision: {op: put|patch|remove, collection, recordId, data|patch, ifRevision?}. Writes show as yours (actor kind agent); as: seed writes starter data for the team (kind seed, no author).\n\n${CLOUD}`, appDataArgsSchema.shape, cloud("summer_app_data", appDataArgsSchema, appData));
+    server.tool("summer_app_tools", `The agent tools (name, description, input JSON Schema) and the data collections (record fields and types) a Summer App declares. Run a tool with summer_app_call; read or write the collections with summer_app_data.\n\n${CLOUD}`, appToolsArgsSchema.shape, cloud("summer_app_tools", appToolsArgsSchema, appTools));
+    server.tool("summer_app_call", `Run one of a Summer App's agent tools inside the person's open app (Studio tab or editor dock) with their rights; waits up to 60 s. app_not_open when the app is not open: use summer_app_data or ask the person to open it. May spend the person's credits when the tool generates.\n\n${CLOUD}`, appCallArgsSchema.shape, cloud("summer_app_call", appCallArgsSchema, appCall));
+    server.tool("summer_app_report_gap", `Tell Summer about an SDK capability a Summer App needed and did not have, so it can be built for everyone.\n\n${CLOUD}`, appReportGapArgsSchema.shape, cloud("summer_app_report_gap", appReportGapArgsSchema, appReportGap));
+    server.tool("summer_app_dock", `Dock a Summer App as a panel in the running Summer Engine editor (left, right or bottom), close its dock, or list docked apps. Docks persist per project. Engine builds without app docks return engine_lacks_op: open the app in the Summer Studio tab instead.`, appDockArgsSchema.shape, async (args) => {
+        const parsed = appDockArgsSchema.safeParse(args ?? {});
+        if (!parsed.success)
+            return result({ ok: false, code: "invalid", error: parsed.error.issues[0]?.message ?? "Invalid arguments" });
+        if (parsed.data.action !== "list" && !parsed.data.appId)
+            return result({ ok: false, code: "invalid", error: `${parsed.data.action} needs appId` });
+        const op = appDockOp(parsed.data);
+        return withEngine(async (client) => {
+            const missing = missingEngineOpResult(client, op.op, APP_DOCK_FALLBACK);
+            if (missing)
+                return missing;
+            return client.executeOps([op]);
+        });
+    });
+    server.tool("summer_enable_plugin", `Enable an editor plugin in the open project (res://addons/<name>/, for example one paired with a Summer App) and report the real result: enabled with the autoloads it registered, or why it failed (code SCRIPT_ERROR, NOT_TOOL, NOT_EDITOR_PLUGIN, CFG_MISSING, TIMEOUT, ...). Older Summer Engine builds only queue the enable; then the result says queued: true and enabled: null, and you check summer_get_debugger_errors before relying on the plugin.`, enablePluginArgsSchema.shape, async (args) => {
+        const parsed = enablePluginArgsSchema.safeParse(args ?? {});
+        if (!parsed.success)
+            return result({ ok: false, code: "invalid", error: parsed.error.issues[0]?.message ?? "Invalid arguments" });
+        return withEngine(async (client) => interpretEnablePluginResult(await client.executeOps([enablePluginOp(parsed.data)])));
+    });
+}

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

@@ -1,27 +1,16 @@
 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";
 import { publishBuild } from "../../core/capabilities/publish-build.js";
 import { BuildToolError } from "../../core/capabilities/summer-bundle.js";
-import { CONFIG_KEYS, getConfigValue, isConfigKey, readSummerConfig, setConfigValue, unsetConfigValue, } from "../../core/config.js";
 import { textJson } from "./text-json.js";
 async function creatorResult(operation) {
     try {
         return textJson(await operation());
     }
     catch (error) {
-        if (error instanceof CreatorOperationError) {
-            return textJson({
-                ok: false,
-                code: error.code,
-                operation: error.operation,
-                message: error.message,
-                recovery: error.recovery,
-            }, true);
-        }
         if (error instanceof BuildToolError) {
             return textJson({
                 ok: false,
@@ -116,64 +105,4 @@ export function registerCreatorTools(server) {
         confirm: z.boolean().default(false).describe("Set true only after the user approves the exact upload."),
         waitSeconds: z.number().int().min(0).max(1800).optional().describe("How long to wait for Summer to make the Build (default 600). On timeout, call again to keep waiting."),
     }, async (args) => creatorResult(() => publishBuild({ ...args, face: "mcp" })));
-    server.tool("summer_creator_publish", "Deprecated: use summer_export_game, then summer_publish_build, which upload the summer.games .zip to the game's store listing. This old path publishes a .pck to the legacy Summercraft creator API with a separate sc_ token and will be removed. First call with confirm=false and present the returned project, version, digest, size, artifact path, channel, and notes; set confirm only after the user approves that exact target. The server independently verifies token scope, ownership, bytes, and review state.", {
-        project: z.string().optional().describe("Project root. Defaults to the current working directory."),
-        artifact: z.string().describe("Exact path to the exported Summer .pck artifact."),
-        version: z.string().describe("Immutable release version."),
-        manifest: z.string().optional().describe("Optional path to a JSON release manifest."),
-        projectId: z.string().optional().describe("Creator project ID. Defaults to ~/.summer/config.json."),
-        channel: z.string().optional().describe("Release channel. Defaults to the configured channel or production."),
-        notes: z.string().optional().describe("Release notes shown during confirmation and recorded in the local audit."),
-        confirm: z.boolean().default(false).describe("Set true only after the user approves the exact release target."),
-    }, async (args) => creatorResult(() => publishCreator({
-        ...args,
-        face: "mcp",
-    })));
-    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."),
-    }, async (args) => creatorResult(() => listCreatorReleases({
-        ...args,
-        face: "mcp",
-    })));
-    server.tool("summer_creator_config", "Read or update the shared non-secret ~/.summer configuration used by the CLI and this MCP. Mutations require confirm=true. Tokens are never returned or accepted by this tool.", {
-        action: z.enum(["list", "get", "set", "unset"]),
-        key: z.enum(CONFIG_KEYS).optional(),
-        value: z.string().optional(),
-        confirm: z.boolean().default(false),
-    }, async ({ action, key, value, confirm }) => creatorResult(async () => {
-        if (action === "list") {
-            const config = await readSummerConfig();
-            return {
-                ok: true,
-                values: Object.fromEntries(CONFIG_KEYS.map((name) => [
-                    name,
-                    getConfigValue(config, name) ?? null,
-                ])),
-            };
-        }
-        if (!key || !isConfigKey(key)) {
-            throw new Error(`A valid key is required. Recovery: use one of ${CONFIG_KEYS.join(", ")}.`);
-        }
-        if (action === "get") {
-            return {
-                ok: true,
-                key,
-                value: getConfigValue(await readSummerConfig(), key) ?? null,
-            };
-        }
-        if (!confirm) {
-            throw new Error(`Changing ${key} requires confirmation. Recovery: show the exact change to the user, then retry with confirm=true.`);
-        }
-        if (action === "set") {
-            if (value === undefined) {
-                throw new Error(`A value is required for ${key}. Recovery: provide value and retry with confirm=true.`);
-            }
-            const config = await setConfigValue(key, value);
-            return { ok: true, key, value: getConfigValue(config, key) };
-        }
-        const config = await unsetConfigValue(key);
-        return { ok: true, key, value: getConfigValue(config, key) ?? null };
-    }));
 }

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

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { BOARD_ENDPOINT, boardArgsSchema, boardContent, boardQuery } from "../../core/capabilities/board.js";
 import { IMAGE_GENERATION_TIMEOUT_MS, imageGenerationArgsSchema, saveGeneratedImage } from "../../core/capabilities/image-generation.js";
 import { buildMotionRequestBody, motionErrorHint, motionGenerationArgsSchema, motionJobFailureHint, } from "../../core/capabilities/motion-generation.js";
-import { MAX_CHOICES_WAIT_SECONDS, defaultCanOpenBrowser, generateSfxChoices, getChoices, getChoicesArgsSchema, openInStudioTab, sfxChoicesArgsSchema, SFX_CHOICES_ENDPOINT, } from "../../core/capabilities/sfx-choices.js";
+import { MAX_CHOICES_WAIT_SECONDS, defaultCanOpenBrowser, generateSfxChoices, getChoices, getChoicesArgsSchema, sfxChoicesArgsSchema, SFX_CHOICES_ENDPOINT, } from "../../core/capabilities/sfx-choices.js";
 import open from "open";
 import { getAuthToken } from "../../core/auth.js";
 import { resolveGatewayUrl } from "../../core/config.js";
@@ -106,9 +106,9 @@ async function mcpGenerate(endpoint, body, timeoutMs = 120_000) {
     if (!res.ok) {
         let message = formattedApiErrorMessage(res.status, data);
         if (res.status === 402) {
-            message =
-                (data.message || "Insufficient credits.") +
-                    "\nTop up at: https://www.summerengine.com/dashboard\nOr upgrade your plan at: https://www.summerengine.com/pricing";
+            // One link: the Add credits step in Studio (no plan needed). Newer servers already put it in the message.
+            const base = String(data.message || "Not enough credits.");
+            message = base.includes("/studio/credits") ? base : `${base}\nAdd credits: https://summerengine.com/studio/credits`;
         }
         if (res.status === 401) {
             message =
@@ -453,7 +453,6 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
     const sfxChoicesDeps = {
         post: (endpoint, body, timeoutMs) => mcpGenerate(endpoint, body, timeoutMs),
         get: (endpoint, params, timeoutMs) => mcpGet(endpoint, params, timeoutMs),
-        studioOpen: (path, reviewUrl) => openInStudioTab(path, reviewUrl),
         openUrl: (url) => open(url),
         canOpenBrowser: () => defaultCanOpenBrowser(),
     };
@@ -463,8 +462,8 @@ one or more. The approved model becomes their default for sound effects.
 
 Use it for the first sound effect in a chat after the person said yes to
 "three versions to pick from", or whenever they want to compare. The page
-opens in their open Summer Studio tab when there is one (needs the store
-sign-in), else in the browser; open:false only returns reviewUrl.
+opens in their open Summer Studio tab when there is one, else in the browser
+(open:false skips the browser and only returns reviewUrl).
 
 Then tell the person the returned "say" text and call summer_get_choices
 with the choiceSetId. Do not pick for them.

package/gemini-extension.json

@@ -1,7 +1,7 @@
 {
   "_generated": "GENERATED from integrations/gemini — do not edit; npm run generate:registry",
   "name": "summer",
-  "version": "3.6.0",
+  "version": "3.8.0",
   "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": {
@@ -113,6 +113,8 @@
     "./library/skills/store-art/",
     "./library/skills/store-listing/",
     "./library/skills/summer-analytics/",
+    "./library/skills/summer-apps/",
+    "./library/skills/summer-apps-design/",
     "./library/skills/summer-friends/",
     "./library/skills/summer-leaderboards/",
     "./library/skills/summer-match-results/",

package/library/references/mcp-tools-reference/mcp-tools-reference.md

@@ -17,7 +17,7 @@
 
 **Rule of thumb:** project reads/writes go through Summer; live hierarchy/inspector changes use scene tools; process-level work remains with the host.
 
-## Tool surface (107 tools)
+## Tool surface (119 tools)
 
 ### Project files (4)
 
@@ -240,16 +240,13 @@ Preview. One fast, read-only call that walks every node of a 3D scene and lists
 | `summer_get_agent_playbook` | Daily operating contract (observe-first loop, content routing, invariants, verification ritual) — call at start of session. Also served natively as the `summer_agent_playbook` MCP prompt. |
 | `summer_get_board` | Read the person's approved planning board (look, characters, place, storyboard, picks), with the look and picked cards as images to compare screenshots against. Needs the project id from the build brief; works without the engine. |
 
-### Creator platform (7)
+### Creator platform (4)
 
 | Tool | Use |
 |---|---|
 | `summer_export_game` | Export the game in the file the Summer Games store takes, headless (no window), no running editor needed. `format:"bundle"` (default): the `summer.games` `.zip` the Summer apps run; `targets` picks `ios`, `android`, `macos`, `windows` (a game without a server: phones only) through a named `summer.games <targets>` preset in `export_presets.cfg`. `format:"download"` with one target: `web` (HTML5 `.zip` on Summer's WebGPU Forward+ template; refuses Compatibility projects), `macos` (ad hoc signed `.app` zip, `macos-universal`) or `windows` (`.exe` with embedded pack, zipped, `windows-x64`). Returns path, sha256, size, bundle manifest or store platform, warnings. |
 | `summer_export_templates` | `list` or `install` export templates from Summer's CDN (`downloads.summer.games/engine-templates/<summerVersion>/manifest.json`) into the engine's user template folder (`<data>/Godot/export_templates/<FULL_CONFIG>/`), sha256-checked. Only download exports need them; store bundles need none. `summerVersion` is read on macOS, passed elsewhere. |
 | `summer_publish_build` | Upload that `.zip` to the creator's game through Studio's store upload: confirm-gated preview first, then declare, part upload from disk, seal, wait for the Build, name its client pack; `publish:true` also approves it. Needs `summer login --store`; a retry with the same file and version continues the same upload. |
-| `summer_creator_publish` | **Deprecated** (use the two tools above). Compute the exact `.pck` digest and size, require user confirmation, then run versioned prepare → write-once upload → finalize. The server independently verifies `publish` scope, ownership, bytes, and review state. |
-| `summer_creator_releases` | **Deprecated.** Lists releases on the legacy creator API. For summer.games use `summer_store_releases` (hosted, mounted after `summer login --store`). |
-| `summer_creator_config` | Read or confirm updates to the shared non-secret `~/.summer/config.json`. It never accepts or returns tokens. |
 | `summer_capture_gameplay` | Real gameplay frames without a running editor: starts the game (main scene or `scene`) in the engine's offscreen verify instance (`--summer-verify`, real renderer, window parked offscreen, no focus) (`--summer-offscreen`) at `resolution` (default `1920x1080`), waits `waitSeconds`, runs `steps` (`press` a button by text, `key`, `action`, `click`, `drag`, `wait`, `shot`), saves `frames` PNGs (HUD included; with a `shot` step, one per shot) to `<project>/.summer/captures/<time>/`. `args` are the game's own flags, passed after `--` (e.g. `["--autostart"]` to skip the title screen). Imports the project first when `.godot/` is missing. Returns each path with its real width and height; warns when the stretch settings render another size. For store screenshots. |
 
 ### Library search (2)
@@ -265,6 +262,28 @@ Preview. One fast, read-only call that walks every node of a 3D scene and lists
 |---|---|
 | `summer_library_feedback` | Report library-entry outcomes (worked/wrong/outdated/...) so entries get fixed and re-ranked. Fire-and-forget with a 1s cap; enum-first schema with no field for project files, chat content, or code; honors `SUMMER_NO_TELEMETRY=1` and `DO_NOT_TRACK=1`. |
 
+### Summer Apps (13)
+
+Team tools inside Summer Studio that agents build: shared, live on the team's data and engine. Load the `summer-apps` and `summer-apps-design` skills first.
+
+| Tool | Use |
+|---|---|
+| `summer_app_guide` | The build guide: when to build, Layout vs code, build loop, manifest, SDK, UI kit, layout format, design rules, worked examples. |
+| `summer_app_list` | The apps in the person's workspaces. |
+| `summer_app_create` | New scratch app; the person's Studio tab opens it. |
+| `summer_app_publish` | New immutable version from a local `dir`, `files` or a `layout`, plus the manifest. |
+| `summer_app_get` | Manifest, current files and a data summary. |
+| `summer_app_update` | Rename, move to a folder, keep, archive or restore an app. |
+| `summer_app_events` | Long-poll (up to 50 s) what the app sends agents, errors, feedback and tool calls. |
+| `summer_app_page` | Read, fill and press the open app's declared fields and buttons. |
+| `summer_app_screenshot` | See the app without the person: a headless, read-only render (PNG) with console, errors, refused calls and the declared page; `width` 390 for a phone, `theme` dark, `out` saves the PNG. |
+| `summer_app_data` | Read or write the app's shared collections; no app needs to be open, the team sees writes live. |
+| `summer_app_tools` | The app's declared agent tools. |
+| `summer_app_call` | Run an agent tool inside the person's open app; `app_not_open` otherwise. |
+| `summer_app_report_gap` | Report an SDK capability an app needed and did not have. |
+| `summer_app_dock` | Dock an app in the editor (left, right, bottom), close it, list docks; `engine_lacks_op` on engines without app docks. |
+| `summer_enable_plugin` | Enable an editor plugin (`res://addons/<name>/`) and get the real load result (`enabled`, autoloads, or a failure `code`); older engines answer `queued: true, enabled: null` instead of claiming success. |
+
 ## Common pattern
 
 Every scene-touching skill should follow this loop:

package/library/skills/README.md

@@ -1,6 +1,6 @@
 # Summer skills
 
-> 123 skills, grouped by their primary domain. **Generated** by `npm run generate:registry` from each skill's `resource.yaml`; `--check` fails when this file and the library disagree. Do not edit by hand.
+> 125 skills, grouped by their primary domain. **Generated** by `npm run generate:registry` from each skill's `resource.yaml`; `--check` fails when this file and the library disagree. Do not edit by hand.
 
 The folder is flat on purpose (`docs/design/DECISIONS.md`, D3): a skill usually belongs to several domains, so categories live in each skill's `facets.domains` and this index is rendered from them. The first domain listed is the primary one. `summer skills list --by-domain` prints the same grouping; `summer skills info <slug>` shows one skill.
 
@@ -29,7 +29,8 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 - [runtime](#runtime) (1)
 - [scenes](#scenes) (12)
 - [scripting](#scripting) (2)
-- [ui](#ui) (1)
+- [tools](#tools) (1)
+- [ui](#ui) (2)
 - [vfx](#vfx) (9)
 - [video](#video) (3)
 
@@ -248,10 +249,17 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 | [gdscript-patterns](./gdscript-patterns/SKILL.md) ★ | GDScript conventions — type hints, signals, exports, onready, lifecycle methods, get_node vs $NodePath, naming. | conventions |
 | [*save-load*](./save-load/SKILL.md) (preview) | Persist game state in Summer Engine: user:// paths, JSON progress vs ConfigFile settings, a versioned save schema with migration, autosave hooks. | gameplay |
 
+## tools
+
+| skill | when to use | also |
+|---|---|---|
+| [*summer-apps*](./summer-apps/SKILL.md) ★ (preview) | Build a Summer App, a team tool inside Summer Studio (balance table, quest editor, tracker, pick grid): build loop, Layout vs code, data as API, agent tools. | ui, agent-workflow |
+
 ## ui
 
 | skill | when to use | also |
 |---|---|---|
+| [*summer-apps-design*](./summer-apps-design/SKILL.md) ★ (preview) | How a Summer App should look - page layout, Summer UI kit components, tables, charts, media, boards, states and a pre-ship checklist. | tools |
 | [ui-basics](./ui-basics/SKILL.md) ★ | Build Summer Engine UI — HUDs, menus, health bars, dialogue boxes, Control trees — anchors, containers, responsive layout, theme vs inline styling. | ux |
 
 ## vfx

package/library/skills/publish-your-game/SKILL.md

@@ -21,3 +21,5 @@ Its current text lives on the hosted Summer Engine MCP, the same text the Studio
 Before the build upload, run `release-readiness` on the exact `.zip` you upload, and report each check to the owner; a hosted game's upload checks can pass while every online join fails.
 
 The one rule to keep even before you load it: Submitting does not publish. `summer_store_submit` returns an approval link; only the owner's click sends the game to review, and review comes before live.
+
+After the review: `summer_store_review` (hosted) returns Summer's decision, the reviewer's feedback and the next step. When Summer asks for changes or does not approve the game, fix every point in the feedback, then call `summer_store_submit` again; the owner approves the resubmission. If there is no written feedback, say so and ask the owner instead of guessing. The game is not live until Summer approves it.

package/library/skills/sound-effect/SKILL.md

@@ -106,6 +106,8 @@ summer_generate_audio(capability: "sound_effects", text: "<prompt>", durationSec
 
 Leave out `modelId` so their approved default runs. The description goes in `text`, not `prompt` (`prompt` gives a 400 `text_required` here).
 
+No Summer project (an asset-only request, or the engine is not installed or not running): stop here. The clips are in the person's Summer library; give them the `audioUrl` of each approved version and skip steps 7 and 8.
+
 ### 7. Import
 
 ```

package/library/skills/summer-apps/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: summer-apps
+description: "Build a Summer App, a team tool inside Summer Studio (balance table, quest editor, tracker, pick grid): build loop, Layout vs code, data as API, agent tools."
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: tools
+user-invocable: true
+allowed-tools: Read Write Edit Glob summer_app_guide summer_app_list summer_app_create summer_app_publish summer_app_get summer_app_update summer_app_events summer_app_page summer_app_screenshot summer_app_data summer_app_tools summer_app_call summer_app_dock summer_app_report_gap
+---
+
+# Summer Apps
+
+A Summer App is a tool the person's team uses inside Summer Studio: shared with
+the workspace, live on its assets, game data and engine, dockable in the editor.
+You build it in minutes; the team keeps it.
+
+## First: does Summer already do it?
+
+A custom app is something the team has to maintain. Before you build one, check whether
+Summer already does the job: Studio features (the asset library with its collections and
+groups, Pick one and sound choices, Grow dashboards, Team) and the existing `summer_*` MCP
+tools. If it does, use that and tell the person where it lives.
+
+Build an app only when the need is real and Summer lacks it, or as a Scratch throwaway (a
+quick asset review, a UI prototype) that you call throwaway when you make it, and archive
+when it is done (`summer_app_update {appId, status: "archived"}`). When
+something is missing natively, report it with `summer_app_report_gap` (and
+`summer_library_feedback` when a library entry fell short), so Summer can build it for
+everyone.
+
+| Ask | Do |
+| --- | --- |
+| "Let me pick from these 12 sword sounds" | Pick one: `summer_generate_sfx_choices`, or put the sounds in a library collection. No app. |
+| "Group our Studio assets into a moodboard for the forest level" | Organize them with the asset library's collections and groups. No app. |
+| "A weapon balance table that writes res://data/weapons.json" | Build an app: nothing in Summer edits game data with the team's balance rules. |
+
+## When to build one
+
+- The person asks for a tool ("build us a loot balance tool", "track every creature
+  from concept to in-engine", "a board to review playtest clips").
+- They need a UI to decide or edit something they will come back to.
+- Not for a one-off answer: reply in chat instead.
+- Not when Summer already does it (above).
+
+## Layout or code
+
+- **Layout** (`format: "layout"`): a JSON layout of kit nodes. Quick, throwaway,
+  always on brand. Use it to ask the person to pick, rate or fill something now.
+- **Code** (default): `index.html` + JS/CSS with the Summer SDK and UI kit. Use it
+  for state, editing, shared data, generation or engine access.
+
+## Start from the working app
+
+Read these before writing code; they are exact:
+
+- [minimal-app.md](minimal-app.md): a complete working app (manifest, `index.html`,
+  `app.js`) built from kit components, using shared data, live changes, the viewer, `page.declare`, an
+  agent event, an agent tool and frame-move state. Copy it and change it.
+- [sdk-reference.md](sdk-reference.md): every SDK call with its exact arguments and
+  return shape.
+- [manifest.md](manifest.md): every manifest field.
+- The kit's component catalog (every `<summer-*>` element with attributes, events and a
+  copyable example) is `summer_app_guide` section `kit`, also at `/summer-ui/v1/catalog.json`
+  on the app host. Copy its examples instead of inventing markup.
+
+To see an app, publish it and call `summer_app_screenshot {appId}`: Summer renders it headless
+with the person's data and returns the picture plus the console, uncaught errors, refused calls
+and the fields and buttons it declared. No Studio tab needed; the person sees it at
+`/studio/apps/<appId>` (`summer_app_create` opens it for them). Opening `index.html` on its own
+never connects. There is no offline host: do not build one or mock the SDK.
+
+The app is served from its own host, apps.summerengine.app. Load the SDK and the kit as
+ES modules with root paths: `<script type="module" src="/summer-sdk/v1.js">` and
+`<script type="module" src="/summer-ui/v1/ui.js">`. Then `await summer.ready` before
+the first call, and reach data only through `summer.data.collection(name)`.
+
+## The loop
+
+1. `summer_app_guide` (whole once per session; later one `section`). Load the
+   `summer-apps-design` skill for how it must look.
+2. `summer_app_create {name, purpose, format}`. The person's Studio tab opens it.
+3. Write the files in a local folder, then `summer_app_publish {appId, dir, manifest, note}`
+   (or `layout`). Each publish is an immutable version the tab boots. A publish
+   error names the file or rule: fix it and publish again.
+4. Seed starter data with `summer_app_data` (`ops` plus `"as": "seed"`) when the app should
+   start full. Seed rows belong to the team and show no author.
+5. Look at it: `summer_app_screenshot {appId}`, then `width: 390` (phone) and `theme: "dark"`.
+   Fix every error and console line it reports, publish again, look again. It is read-only:
+   writes, sends and paid calls are refused there and work in Studio.
+6. `summer_app_events {appId, after}` waits for what the app sends you
+   (`summer.agent.send`), errors (uncaught and `console.error`) and feedback. Act on them;
+   pass the cursor on.
+7. Change the app by publishing again; `summer_app_get` returns the current files.
+
+## Data is the API
+
+Read and write an app's shared collections with `summer_app_data`. It works with
+no app open, and everyone in the app sees your edits live. "Nerf the bow in our
+balance sheet" is a data write, not a click.
+
+Declare each collection's record shape in the manifest `collections`; `summer_app_tools`
+and `summer_app_data` reads return it, so any agent knows what a record looks like.
+
+```json
+{ "appId": "<id>", "ops": [
+  { "op": "patch", "collection": "items", "recordId": "bow", "patch": { "damage": 36 }, "ifRevision": 4 },
+  { "op": "put", "collection": "notes", "recordId": "n-17", "data": { "text": "Boss too long", "status": "open" } },
+  { "op": "remove", "collection": "notes", "recordId": "n-3" }
+] }
+```
+
+Up to 100 ops per call. Without `ops`, `summer_app_data` reads (`collection`, `after`, `limit`);
+removed records are not returned. Your writes are recorded as `actor { kind: "agent" }` (and
+as `createdBy` on records you create), so the app can show which rows an agent made. Add
+`"as": "seed"` for starter data that belongs to the team (`kind: "seed"`, no author). `patch` merges keys
+(`null` removes one); `ifRevision` guards against overwriting a newer change.
+
+## Agent tools
+
+Logic that lives in the app (a balance formula, an export) can be exposed in the
+manifest `agentTools` and implemented with `summer.agent.tool(name, handler)`.
+`summer_app_tools` lists them; `summer_app_call` runs one inside the person's open
+app and answers `app_not_open` otherwise. Prefer data for plain reads and edits.
+
+## Rules
+
+- Declare only the permissions the app uses; declare every `engineFiles` path and
+  every `agentEvents` name. A missing one fails at runtime with `permission_missing`.
+- The app runs sandboxed (`allow-scripts allow-forms allow-popups allow-modals
+  allow-downloads`, never `allow-same-origin`): no cookies, no `localStorage`, no network
+  unless the workspace allows a domain. Keep state in `summer.data`.
+- Paid SDK calls spend the credits of the person using the app. Say so before
+  building an app that generates.
+- Use real data (`summer.data`, `summer.assets`, `summer.engine.readFile`), never
+  placeholder numbers.
+- Studio moves an idle app to a fresh frame every few minutes. Keep UI state you care
+  about in shared data, or return it from `summer.app.onSnapshot(() => state)` (up to
+  256 KB) and read it back from `(await summer.ready).restored`. Wrap Web Audio playback
+  in `summer.app.busy(true)` / `summer.app.busy(false)` so a long sound is not cut;
+  `<audio>` and `<video>` count on their own.
+- Call `summer.page.declare` so agents can read and use the UI; mark delete,
+  publish, pay and send actions `critical`.
+- When the SDK cannot do what the app needs, say so and call
+  `summer_app_report_gap`.
+- `summer_app_dock` docks an app in the editor; on engines without app docks it
+  returns `engine_lacks_op`: open the app in the Studio tab instead.
+
+## Done means
+
+The app is published; `summer_app_screenshot` shows it with real data in light, dark and at
+390 px with no errors; its states (loading, empty, error) work; and the person knows what it
+does and where its data goes.

package/library/skills/summer-apps/manifest.md

@@ -0,0 +1,57 @@
+# The Summer App manifest
+
+Sent as `manifest` on every `summer_app_publish` and written into the app as
+`summer.app.json`. Unknown keys and unknown permissions are refused with a message that
+names them. Every field:
+
+```json
+{
+  "name": "Loot table",
+  "purpose": "Balance item stats and write them to res://data/items.json",
+  "permissions": ["data", "assets:read", "generate", "ai", "team:read", "engine:read", "engine:write"],
+  "engineFiles": ["res://data/items.json"],
+  "collections": {
+    "items": {
+      "description": "One weapon or armour piece",
+      "fields": {
+        "name": { "type": "string", "required": true },
+        "damage": { "type": "number", "description": "Damage per hit" },
+        "speed": { "type": "number", "description": "Attacks per second" },
+        "tags": { "type": "array" }
+      }
+    }
+  },
+  "agentEvents": ["items.written"],
+  "agentTools": [
+    {
+      "name": "nerf_item",
+      "description": "Lower one item's damage by a percent",
+      "input": {
+        "type": "object",
+        "properties": { "id": { "type": "string" }, "percent": { "type": "number" } },
+        "required": ["id", "percent"]
+      }
+    }
+  ],
+  "surface": "both",
+  "dock": { "preferred": "bottom" },
+  "plugin": { "name": "loot_tools" }
+}
+```
+
+| Key | Rules |
+|---|---|
+| `name` | Required, 1-80 characters. |
+| `purpose` | Up to 280 characters: what the tool does and where its data goes. |
+| `permissions` | Only these: `data`, `assets:read`, `assets:write`, `generate`, `ai`, `projects:read`, `team:read`, `grow:read`, `engine:read`, `engine:write`, `choices`. `engine:write` includes `engine:read`; `assets:write` includes `assets:read`. No permission is needed for `app.*`, `agent.*`, `page.*` and `team.presence`. |
+| `engineFiles` | Up to 50 `res://` paths `engine.readFile` / `writeFile` may touch. |
+| `collections` | Up to 50, keyed by collection name (lowercase `a-z 0-9 _ . -`). Each: `description`, `fields` (up to 50, name `[A-Za-z_][A-Za-z0-9_]*`) with `type` (`string`, `number`, `integer`, `boolean`, `object`, `array`, `any`), `description`, `required`. Descriptive: agents and people read it; writes are not rejected for it. |
+| `agentEvents` | Up to 50 names (`a-z 0-9 _ . -`) the app sends with `summer.agent.send`. |
+| `agentTools` | Up to 20: `name` (`a-z 0-9 _`, max 64), `description` (max 1,000), `input` (JSON Schema, up to 8 KB). |
+| `surface` | `page` (the Studio app page, default), `dock` (an editor dock) or `both`. A dock layout must work from 320 px wide; docked apps get selection and scene events (`summer.engine.onEvent`). |
+| `dock` | `{ "preferred": "left" \| "right" \| "bottom" }`. |
+| `plugin` | `{ "name": "<folder>" }`: the app may also write `res://addons/<folder>/`. |
+| `entry` | Always `index.html` (you can leave it out). |
+
+The whole manifest is at most 200 KB. A code app's bundle: `index.html` at the root, at most
+300 files, 10 MB, 5 MB per file.