summer-engine 4.6.0 → 4.8.0

package/dist/mcp/tool-results.js

@@ -1,4 +1,5 @@
 import { BATCH_EDIT_TOOLS, SINGLE_EDIT_TOOLS } from "./tool-surface.js";
+import { signInKindForCode, signInLinkText } from "../core/sign-in-link.js";
 /** Pretty-printed JSON text as compact JSON; anything else unchanged. */
 export function compactJsonText(text) {
     const first = text[0];
@@ -79,3 +80,66 @@ export function singleEditCounter() {
         return `Tip: ${run} single scene edits in a row. More than 3 edits: write one summer_run_script instead (snapshot, script, diff, screenshot).`;
     };
 }
+/** The store sign-ins a v4 answer names in error.details.was (core/ops/cloud.ts hostedCallFailure). */
+const STORE_SIGN_IN_WAS = new Set(["store_login_required", "store_login_expired"]);
+/**
+ * A v4 cloud answer `not_signed_in` whose cause is the store sign-in (the
+ * hosted server's OAuth grant), not the Summer account: the Summer app, for
+ * one, is signed in to the account, so only the store approval link helps.
+ */
+function storeSignInAnswer(result) {
+    const first = result.content[0];
+    if (!first || first.type !== "text" || typeof first.text !== "string")
+        return false;
+    try {
+        const parsed = JSON.parse(first.text);
+        const error = parsed?.error;
+        return error?.code === "not_signed_in" && typeof error.details?.was === "string" && STORE_SIGN_IN_WAS.has(error.details.was);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A `not_signed_in` / `store_login_required` answer gets one more text block:
+ * the sign-in link for the person (core/sign-in-link.ts). Anything else, or
+ * no link, leaves the result as it is. Never throws.
+ */
+export async function withSignInLink(result, code, links) {
+    if (!result || typeof result !== "object" || !Array.isArray(result.content))
+        return result;
+    const kind = storeSignInAnswer(result) ? "store" : signInKindForCode(code);
+    if (!kind)
+        return result;
+    try {
+        const url = await links.link(kind);
+        if (!url)
+            return result;
+        const original = result;
+        const text = signInLinkText(kind, url);
+        // A JSON answer gets the link inside it (signInUrl, and recovery says what
+        // to do), so a caller that parses it (the v4 operation layer runs 3.x
+        // tools and reads their JSON) keeps the code and passes the link on.
+        const first = original.content[0];
+        if (first && first.type === "text" && typeof first.text === "string") {
+            try {
+                const parsed = JSON.parse(first.text);
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                    const answer = parsed;
+                    const nested = answer.error && typeof answer.error === "object" ? answer.error : null;
+                    const target = nested && typeof nested.code === "string" ? nested : answer;
+                    target.signInUrl = url;
+                    target.recovery = text;
+                    return { ...original, content: [{ ...first, text: JSON.stringify(answer) }, ...original.content.slice(1)] };
+                }
+            }
+            catch {
+                // plain text: the link goes in its own block below
+            }
+        }
+        return { ...original, content: [...original.content, { type: "text", text }] };
+    }
+    catch {
+        return result;
+    }
+}

package/dist/mcp/tool-surface.js

@@ -37,10 +37,14 @@ const LOCAL_TOOLSETS = {
         "summer_get_asset_download_url",
     ],
     ship: ["summer_export_game", "summer_export_templates", "summer_publish_build", "summer_go_live", "summer_store_set_details", "summer_capture_gameplay"],
-    ui: ["summer_ui_actions", "summer_ui_activate", "summer_ui_screenshot", "summer_ui_tree"],
+    // summer_view_set is in the catalog (engine.view_set, summer_call) for every profile.
+    ui: ["summer_ui_actions", "summer_ui_activate", "summer_ui_screenshot", "summer_ui_tree", "summer_view_set"],
     // Create and open a project on this computer with no shell (the full profile;
     // the engine profile's clients have a shell, `summer dev`, and a tool cap).
     projects: ["summer_projects_create_local", "summer_projects_open_local"],
+    // The Summer API (the assets and full profiles; the engine profile's clients
+    // have a shell, `summer login` and `summer api`, and a tool cap).
+    tools: ["summer_api_models", "summer_api_estimate", "summer_api_run", "summer_api_batch", "summer_api_job"],
 };
 const localToolset = new Map(Object.entries(LOCAL_TOOLSETS).flatMap(([set, names]) => names.map((name) => [name, set])));
 /** Hosted tool names by pattern, first match wins. Unknown names land in `other` (full only). */
@@ -185,6 +189,7 @@ const ADDITIVE_OR_TRANSIENT = new Set([
     "summer_open_scene",
     "summer_open_main_scene",
     "summer_select_node",
+    "summer_view_set",
     "summer_clear_console",
     "summer_play",
     "summer_stop",
@@ -208,6 +213,7 @@ const IDEMPOTENT_WRITES = new Set([
     "summer_open_scene",
     "summer_open_main_scene",
     "summer_select_node",
+    "summer_view_set",
     "summer_clear_console",
     "summer_stop",
     "summer_enable_plugin",

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

@@ -0,0 +1,50 @@
+/**
+ * summer_api_models, summer_api_estimate, summer_api_run, summer_api_batch,
+ * summer_api_job — the Summer API (core/summer-api.ts), the same calls as
+ * `summer api models|estimate|run|run --batch|jobs`. MCP adapter only: schemas and descriptions here.
+ * Runs and jobs use the Summer sign-in on this computer (summer login: Supabase OAuth, refreshed by itself).
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+export declare const apiModelsInputShape: {
+    model: z.ZodOptional<z.ZodString>;
+    capability: z.ZodOptional<z.ZodEnum<["image", "3d", "video", "voice", "dialogue", "sound", "music"]>>;
+};
+export declare const apiEstimateInputShape: {
+    model: z.ZodString;
+    input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+};
+export declare const apiRunInputShape: {
+    model: z.ZodString;
+    input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    quoteId: z.ZodOptional<z.ZodString>;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    wait: z.ZodOptional<z.ZodBoolean>;
+    out: z.ZodOptional<z.ZodString>;
+};
+export declare const apiBatchInputShape: {
+    jobs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        model: z.ZodString;
+        input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        idempotencyKey: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        model: string;
+        input?: Record<string, unknown> | undefined;
+        idempotencyKey?: string | undefined;
+    }, {
+        model: string;
+        input?: Record<string, unknown> | undefined;
+        idempotencyKey?: string | undefined;
+    }>, "many">>;
+    batchId: z.ZodOptional<z.ZodString>;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    wait: z.ZodOptional<z.ZodBoolean>;
+    out: z.ZodOptional<z.ZodString>;
+};
+export declare const apiJobInputShape: {
+    jobId: z.ZodString;
+    wait: z.ZodOptional<z.ZodBoolean>;
+    out: z.ZodOptional<z.ZodString>;
+    cancel: z.ZodOptional<z.ZodBoolean>;
+};
+export declare function registerApiTools(server: McpServer): void;

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

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { batchToolResult, cancelJob, checkBatch, createBatch, estimateJob, getBatch, getJob, jobToolResult, listModels, runJob, summerApiToolAnswer, } from "../../core/summer-api.js";
+import { textJson } from "./text-json.js";
+const modelId = z.string().min(1).max(120).describe("A Summer API model id or alias from summer_api_models, e.g. 3d/default.");
+const modelInput = z.record(z.string(), z.unknown()).optional().describe("The model's input, matching its inputSchema from summer_api_models.");
+const out = z.string().min(1).optional().describe("A folder on this computer: save the finished job's files there (implies wait).");
+export const apiModelsInputShape = {
+    model: modelId.optional().describe("One model id or alias; without it, every model."),
+    capability: z.enum(["image", "3d", "video", "voice", "dialogue", "sound", "music"]).optional().describe("Only this kind."),
+};
+export const apiEstimateInputShape = { model: modelId, input: modelInput };
+export const apiRunInputShape = {
+    model: modelId,
+    input: modelInput,
+    quoteId: z.string().min(1).max(600).optional().describe("From summer_api_estimate: refuse to charge more than it quoted."),
+    idempotencyKey: z.string().min(1).max(200).optional().describe("Reuse to retry the same run without running it twice."),
+    wait: z.boolean().optional().describe("Follow the job until it finishes (up to about a minute in this call)."),
+    out,
+};
+export const apiBatchInputShape = {
+    jobs: z
+        .array(z.object({
+        model: modelId,
+        input: modelInput,
+        idempotencyKey: z.string().min(1).max(200).optional().describe("This job's own key; by default the batch key and the job's position."),
+    }))
+        .min(1)
+        .max(500)
+        .optional()
+        .describe("Up to 500 jobs, all or none. Leave out with batchId."),
+    batchId: z.string().min(1).max(200).optional().describe("Read a batch summer_api_batch answered, instead of starting one."),
+    idempotencyKey: z.string().min(1).max(200).optional().describe("Reuse to retry the same batch without queuing it twice."),
+    wait: z.boolean().optional().describe("Follow every job until it finishes (up to about a minute in this call)."),
+    out,
+};
+export const apiJobInputShape = {
+    jobId: z.string().min(1).max(200).describe("The job id summer_api_run answered."),
+    wait: z.boolean().optional().describe("Follow the job until it finishes (up to about a minute in this call)."),
+    out,
+    cancel: z.boolean().optional().describe("Ask to stop the job instead. Summer API jobs, queued or running, run to the end: the answer is unsupported."),
+};
+const answer = async (work) => {
+    const result = await summerApiToolAnswer(work);
+    return textJson(result, result.ok === false);
+};
+export function registerApiTools(server) {
+    server.tool("summer_api_models", "The Summer API's curated game-dev models: id, capability, input schema, output formats, typical time and price in USD. No sign-in needed. Next: summer_api_estimate for one exact request.", apiModelsInputShape, async (args) => answer(() => listModels(args)));
+    server.tool("summer_api_estimate", "The exact USD price of one Summer API job before it runs, what makes it up, and a quoteId that holds the price for 15 minutes. Charges nothing; no sign-in needed. Next: summer_api_run with the quoteId.", apiEstimateInputShape, async (args) => answer(() => estimateJob(args.model, args.input ?? {})));
+    server.tool("summer_api_run", "Run one Summer API job into the person's Summer assets with the Summer sign-in on this computer (the person runs summer login first). Spends their paid credits within this app's limit (Connected apps): say what you will make and estimate it first. Short jobs come back done; past the account's running slots a job answers queued at a held price and starts in order. wait follows it, out saves its files on this computer. no_credits (the paid balance) or over_limit (this app's limit): show the person the message and its link.", apiRunInputShape, async (args) => answer(async () => {
+        const follow = args.wait === true || typeof args.out === "string";
+        const job = await runJob(args.model, args.input ?? {}, {
+            ...(args.quoteId ? { quoteId: args.quoteId } : {}),
+            ...(args.idempotencyKey ? { idempotencyKey: args.idempotencyKey } : {}),
+            ...(follow ? { waitSeconds: 30 } : {}),
+        });
+        return jobToolResult(job, args);
+    }));
+    server.tool("summer_api_batch", "Run up to 500 Summer API jobs at once with the Summer sign-in on this computer, all or none: when the person's paid credits and this app's limit (Connected apps) cover every job, all are queued at their held prices and run in order; if not, nothing runs and the error (no_credits or over_limit) says how many fit and how much more is needed (show the person its link). Say what you will make and what it costs first. batchId reads a batch; wait follows it, out saves the finished files on this computer.", apiBatchInputShape, async (args) => answer(async () => {
+        if (args.batchId)
+            return batchToolResult(await getBatch(args.batchId), args);
+        const batch = await createBatch(checkBatch(args.jobs ?? []), args.idempotencyKey ? { idempotencyKey: args.idempotencyKey } : {});
+        return batchToolResult(batch, args);
+    }));
+    server.tool("summer_api_job", "Read a Summer API job: its state (queued, running, done, failed, ...), price and, when done, its assets and Summer file URLs. wait follows it, out saves its files on this computer.", apiJobInputShape, async (args) => answer(async () => (args.cancel ? { job: await cancelJob(args.jobId) } : jobToolResult(await getJob(args.jobId), args))));
+}

package/dist/mcp/tools/local-project-tools.d.ts

@@ -1,4 +1,18 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/** The tool call's progress line (notifications/progress), when the client asked for progress. */
+export declare function progressReporter(extra: {
+    _meta?: {
+        progressToken?: string | number;
+    };
+    sendNotification?: (notification: {
+        method: "notifications/progress";
+        params: {
+            progressToken: string | number;
+            progress: number;
+            message?: string;
+        };
+    }) => Promise<void>;
+} | undefined): ((message: string) => void) | undefined;
 /**
  * projects.create_local and projects.open_local: what `summer dev` does, for
  * agents with no shell (core/capabilities/projects-local.ts).

package/dist/mcp/tools/local-project-tools.js

@@ -16,6 +16,17 @@ async function localProjectResult(operation) {
         throw error;
     }
 }
+/** The tool call's progress line (notifications/progress), when the client asked for progress. */
+export function progressReporter(extra) {
+    const token = extra?._meta?.progressToken;
+    const send = extra?.sendNotification;
+    if (token === undefined || !send)
+        return undefined;
+    let step = 0;
+    return (message) => {
+        void send({ method: "notifications/progress", params: { progressToken: token, progress: ++step, message } }).catch(() => undefined);
+    };
+}
 /**
  * projects.create_local and projects.open_local: what `summer dev` does, for
  * agents with no shell (core/capabilities/projects-local.ts).
@@ -26,8 +37,8 @@ export function registerLocalProjectTools(server) {
         name: z.string().max(80).optional().describe("The project's name and folder name. Default my-game (or the template's name)."),
         dir: z.string().max(1000).optional().describe("The project folder: a new or empty folder, not inside another project; ~ is home. Default <name> next to the session's project, in the session's folder, or in ~/Documents/Summer."),
     }, async (args) => localProjectResult(() => createLocalProject(args, currentMcpEngineSelection()?.cwd)));
-    server.tool("summer_projects_open_local", "Open a project on this computer in Summer Engine, in the background, and wait until it connects (an editor that has it open is used as it is); this session's engine tools then work on it. When Summer Engine is not installed it answers engine_not_running: ask the person, and only with their yes call again with install: true (about 660 MB, free). A first open can take a few minutes: the answer says to call again. It adds summer-preview to the session folder's .claude/launch.json (Claude Code Desktop's Browser pane), and preview.url is where the game shows. Next: summer_get_project_context.", {
+    server.tool("summer_projects_open_local", "Open a project on this computer in Summer Engine, in the background, and wait until it connects (an editor that has it open is used as it is; an editor with another project open switches to it in the same window); this session's engine tools then work on it. When Summer Engine is not installed it answers engine_not_running: ask the person, and only with their yes call again with install: true (about 660 MB, free). A first open can take a few minutes: the answer says to call again. It adds summer-preview to the session folder's .claude/launch.json (Claude Code Desktop's Browser pane), and preview.url is where the game shows. Next: summer_get_project_context.", {
         path: z.string().max(1000).optional().describe("The project folder (holds project.godot), e.g. projectPath from summer_projects_create_local. Default this session's project."),
         install: z.boolean().default(false).describe("Install Summer Engine first when it is missing. Set true only after the person said yes."),
-    }, async (args) => localProjectResult(() => openLocalProject(args, currentMcpEngineSelection(), { log: logEngineSelfStart }, (root, client) => bindMcpProject(root, client))));
+    }, async (args, extra) => localProjectResult(() => openLocalProject(args, currentMcpEngineSelection(), { log: logEngineSelfStart, progress: progressReporter(extra) }, (root, client) => bindMcpProject(root, client))));
 }

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

@@ -18,6 +18,7 @@ params: slot values — gameId + section (builds, releases, store-page, analytic
 open: false resolves only and returns url (+ login_url when the page needs login) or op; nothing opens, no engine needed.
 
 Result: { ok, action: opened | printed | listed | ambiguous | unsupported | engine_not_running | engine_error | not_found | invalid_params | open_failed | blocked_origin, target (with availability for editor ids), url, login_url, logged_in, opened_url, op, engine, failure_reason, matches, hint }.
+- Studio pages (/studio...) open in the Summer app's own Studio tab when the running engine advertises the studio destination (op Navigate target studio; result hint says so); otherwise in the browser.
 - Web targets that require login open through /login?returnUrl=<path> when this machine holds no Summer login token (logged_in:false) — the destination loads after sign-in.
 - Editor targets need Summer Engine running with the project open; otherwise action engine_not_running with the op that would have been sent and a 'summer run' hint. Nothing was opened.
 - Editor destinations are forwarded to the engine's own navigation table (op Navigate; ids advertised in /api/health capabilities.navigation). On an engine that predates it, scene/node/script/file and the three docks still work through their original ops; anything else answers action unsupported with failure_reason engine_lacks_op and an update hint. Never claim those opened. Listing (no target) shows each editor id's availability from the connected engine.

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

@@ -1,3 +1,4 @@
+import { viewSetOp } from "../../core/capabilities/view-set.js";
 import { z } from "zod";
 import { withEngine, ToolInputError } from "./with-engine.js";
 import { executeSceneMutation } from "../../core/capabilities/engine-ops.js";
@@ -245,6 +246,12 @@ PERSISTENCE IS VERIFIED: the engine's ConnectSignal op connects without CONNECT_
             op.scenePath = scenePath;
         return client.executeOps([op]);
     }));
+    server.tool("summer_view_set", "Show the person what you are working on: the editor's view (home, chat, 3d, 2d, script, game, studio), its right rail (files, scene, inspector, output, none), what to focus (a res:// script or scene, or a node path) and the nodes to frame the camera on. Changes only what is on screen. The navigate-summer skill says which view fits which moment.", {
+        view: z.enum(["home", "chat", "3d", "2d", "script", "game", "studio"]).describe("The view to show"),
+        rail: z.enum(["files", "scene", "inspector", "output", "none"]).optional().describe("The right rail; none hides it"),
+        focus: z.string().optional().describe("A res:// script or scene, or a node path"),
+        frame: z.array(z.string()).optional().describe("Node paths to frame the camera on"),
+    }, async ({ view, rail, focus, frame }) => withEngine(async (client) => client.executeOps([viewSetOp({ view, rail, focus, frame })])));
     server.tool("summer_replace_node", `Replace a node with a different scene/model or node type, keeping its parent, sibling index, name, transform and property overrides, and the children the scene added under it. Use it to swap a kit piece for another (a wall host for a door host), a placeholder for a prefab, or a StaticBody3D for a RigidBody3D.
 
 Give exactly one of scene or type. The scenePath must be a .tscn.

package/gemini-extension.json

@@ -1,7 +1,7 @@
 {
   "_generated": "GENERATED from integrations/gemini — do not edit; npm run generate:registry",
   "name": "summer",
-  "version": "4.6.0",
+  "version": "4.8.0",
   "description": "The game engine built for AI. Any agent makes a multiplayer game and publishes it. The Summer Engine MCP server, context primer and game-dev skills.",
   "contextFileName": "GEMINI.md",
   "mcpServers": {
@@ -27,7 +27,6 @@
     "./library/skills/3d-lighting/",
     "./library/skills/adaptive-music/",
     "./library/skills/agent-playtesting/",
-    "./library/skills/ai-characters-in-games/",
     "./library/skills/ambient-bed/",
     "./library/skills/animated-loop/",
     "./library/skills/animation-tree/",
@@ -107,6 +106,7 @@
     "./library/skills/store-art/",
     "./library/skills/store-listing/",
     "./library/skills/summer-analytics/",
+    "./library/skills/summer-api/",
     "./library/skills/summer-apps/",
     "./library/skills/summer-apps-design/",
     "./library/skills/summer-assets/",
@@ -117,6 +117,7 @@
     "./library/skills/summer-matchmaking/",
     "./library/skills/summer-parties/",
     "./library/skills/summer-player-data/",
+    "./library/skills/summer-router/",
     "./library/skills/summer-store/",
     "./library/skills/summer-world-chat/",
     "./library/skills/summer-world-saves/",

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

@@ -19,7 +19,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 (125 tools)
+## Tool surface (131 tools)
 
 ### Local projects (2)
 
@@ -93,7 +93,7 @@ No shell needed (Claude Desktop, chat apps); the `summer dev` command does both
 |---|---|
 | `summer_fabricate_3d` | Run a Blender Python (bpy) script in the user's OWN installed Blender — headless, engine-supervised — then import the exported `.glb` into `res://` and optionally instantiate it with `target_size`. For modular kits with exact dimensions, VFX meshes (shatter, sweeps, LOD chains), and post-processing generated models (decimate/UV/bake); generic props go to the library and characters to generation. Requires Blender on the machine (never bundled); `blender_not_found` carries the fix. The `fabricating-assets` skill has the bpy rules that survive glTF export. |
 
-### Editor UI control (4)
+### Editor UI control (5)
 
 Preview: needs Summer Engine 0.5.66 or newer; older engines return `engine_lacks_op`. Scene work never goes through the editor UI (use the scene, scripting, and perception tools). UI ops are for editor-workflow steps a human does with the mouse — open Project Settings, switch the main screen, clear a blocking dialog, read a dock. Ladder: dedicated tool → named action → tree + activate → screenshot (pixels last, never for coordinates). Quit / project-reload / delete-without-confirm actions are denied by the engine. The `driving-the-editor-ui` skill carries the patterns.
 
@@ -103,6 +103,7 @@ Preview: needs Summer Engine 0.5.66 or newer; older engines return `engine_lacks
 | `summer_ui_tree` | Structured Control tree of the live editor UI (class, path, rect, text/tooltip, `checked`/`enabled`/`tabs`/`current_tab`/`value`) from `root:"main" \| "window" \| "dock:<title\|id>" \| "dialog:<title>" \| "path:<node path>"`; `root:"dialogs"` lists every visible dialog/popup with `blocking`, `blocking_dialog`, and its `buttons`. The token-cheap alternative to a screenshot; its paths are what `summer_ui_activate` takes. |
 | `summer_ui_activate` | Activate one control by tree path through its own input path — `press`, `toggle`, `focus`, `select_tab` (incl. `path:"main_screen" value:"3D"`), `set_text` (+`submit`), `set_value` — and `action:"dismiss_dialog"` (by `path` or `title`, `button` cancel/ok/text) to clear a blocking dialog. `state` / `visible_after` are read back after the action, never echoed. |
 | `summer_ui_screenshot` | PNG of the editor window or one dock/dialog/control (`root`, `max_size`) returned as an image — the pixels-last fallback for LOOKING at the editor UI. Not for scene verification (`summer_screenshot`) and never for picking click coordinates. Honest `no_renderer` under a headless editor. |
+| `summer_view_set` (`engine.view_set`) | Show the person what you work on: the frame's view (home, chat, 3D, 2D, script, game, Studio), the right rail, the focus and the nodes to frame. Use it when you start editing a scene or script, play the game, or finish on the best view of the result; not for reading a node (`summer_inspect_node`) or opening a web page (`studio.open`). Needs Summer Engine 4.6 or newer. |
 
 ### Perception (4)
 
@@ -291,6 +292,18 @@ These come from the hosted Summer server (the one ChatGPT and Claude connect to)
 | `summer_docs_search` | Search the library (skills, tools, templates, references, examples, collections) by describing the task in plain words; ranked ids with `matched_by` (lexical / semantic). The first move for any task; works without the engine. |
 | `summer_docs_read` | Load one entry by id: a skill's SKILL.md plus metadata, a tool's call recipe, a template's pin, a reference's body. A body ends with its relative links and the id that loads each; a linked file loads by `<entry id>/<link as written>` (e.g. `skill/spatial-placement/references/kit-placement-tools.md`). The last line is the `entry_id` footer to report through `docs.feedback`. |
 
+### Summer API (5)
+
+Signed in with `summer login` (one browser sign-in on this computer, renewed by itself; `summer token` prints a one-hour token for the person's own HTTP code). Each app spends the person's paid credits up to the limit they set in Connected apps. No rate limits on paid usage: jobs past the account's running slots (10 at once, up to 40 as it buys credits) answer `queued` and start in order. Money is the only refusal: `no_credits` (the paid balance) or `over_limit` (the app's own limit). The `summer-api` skill has the workflow.
+
+| Tool | Use |
+|---|---|
+| `summer_api_models` (`models.list`) | The Summer API's curated game-dev models: id, capability, input schema, output formats, typical time and USD price; `model` for one, `capability` to filter. No sign-in. Shell: `summer api models`. |
+| `summer_api_estimate` (`models.estimate`) | The exact USD price of one job, its breakdown and a `quoteId` that holds it 15 minutes. Charges nothing. Shell: `summer api estimate`. |
+| `summer_api_run` (`models.run`) | Run one job into the person's Summer assets with the Summer sign-in on this computer; spends paid credits within the app's limit. `wait` follows it, `out` saves its files, `quoteId` caps the charge. Shell: `summer api run --wait --download`. |
+| `summer_api_batch` (`POST /v1/batches`) | Run up to 500 jobs at once, all or none: queued at held prices when paid credits and the app's limit cover them all; otherwise nothing runs and the error says how many fit. `batchId` reads a batch; `wait` and `out` as for one job. Shell: `summer api run --batch jobs.jsonl --wait --download`. |
+| `summer_api_job` (`jobs.get`, `jobs.cancel`) | Read a job (state, price, assets and file URLs); `wait`, `out` or `cancel`. Shell: `summer api jobs`. |
+
 ### Library feedback (1)
 
 | Tool | Use |

package/library/references/mcp-tools-reference/resource.yaml

@@ -1,6 +1,6 @@
 id: reference/mcp-tools-reference
 kind: reference
-version: 1.4.2
+version: 1.4.3
 summary: Canonical reference for which Summer MCP tool to call — skills should reference tool names exactly as written here.
 use_when:
   - choosing between Summer MCP tools and host tools for an operation

package/library/skills/README.md

@@ -1,6 +1,6 @@
 # Summer skills
 
-> 132 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.
+> 133 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.
 
@@ -13,7 +13,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 - [agent-workflow](#agent-workflow) (19)
 - [ai](#ai) (2)
 - [animation](#animation) (7)
-- [assets](#assets) (4)
+- [assets](#assets) (5)
 - [audio](#audio) (6)
 - [character-controller](#character-controller) (2)
 - [creator](#creator) (7)
@@ -89,8 +89,8 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 
 | skill | when to use | also |
 |---|---|---|
-| [*ai-characters-in-games*](./ai-characters-in-games/SKILL.md) (preview) | Safe AI characters in published games: no keys in the build, Summer's player AI gateway, moderation, caps. | npc |
 | [design-npc](./design-npc/SKILL.md) ★ | Design enemy, NPC, boss or companion behavior: perception, state machine, telegraphs, script stub. | npc |
+| [*summer-router*](./summer-router/SKILL.md) (preview) | AI characters for games on Summer Games: Summer Router replies, tools, speech, images. | npc, multiplayer |
 
 ## animation
 
@@ -111,7 +111,8 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 | [asset-strategy](./asset-strategy/SKILL.md) ★ | Route any 'I need a [thing]' asset request to the right skill: 2D, 3D, audio, video, VFX or animation. | pipeline |
 | [*lumera-single-image-scene-reconstruction*](./lumera-single-image-scene-reconstruction/SKILL.md) (preview) (library only) | Lumera-style single image to editable 3D scene — VLM-parsed object boxes and parametric lights, per-object meshes, HDR probe, .tscn assembly, refinement loop. | pipeline, 3d, scenes |
 | [*skintokens-auto-rigging*](./skintokens-auto-rigging/SKILL.md) (preview) (library only) | Offline auto-rigging with skin-tokens.cpp (GGML SkinTokens/TokenRig port) — skeleton and skin weights from a static GLB mesh on CPU/Vulkan, into Summer Engine. | pipeline, 3d, animation |
-| [summer-assets](./summer-assets/SKILL.md) | Make game assets with Summer, no Summer Engine: find, generate and download 3D models, images, audio and video for any engine or app. | agent-workflow |
+| [*summer-api*](./summer-api/SKILL.md) (preview) | Summer API game assets: models, estimate, one job or a batch, download the files. | agent-workflow |
+| [summer-assets](./summer-assets/SKILL.md) | Game assets for any engine, no Summer Engine: find, generate and download them. | agent-workflow |
 
 ## audio
 
@@ -207,7 +208,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 
 | skill | when to use | also |
 |---|---|---|
-| [navigate-summer](./navigate-summer/SKILL.md) ★ | Open a Summer web page or editor surface for the user (billing, their games, a scene) with studio.open. | agent-workflow, meta |
+| [navigate-summer](./navigate-summer/SKILL.md) ★ | Open a Summer page or editor view for the person: studio.open, and engine.view_set while you work. | agent-workflow, meta |
 
 ## performance
 

package/library/skills/design-npc/SKILL.md

@@ -493,7 +493,7 @@ For an animated NPC in a runnable project: `summer create 3d-fps-simple-animated
 ## See also
 
 - `animation-tree` — wire the action states to animation clips
-- `ai-characters-in-games` — NPCs that answer free-form player text
+- `summer-router` — NPCs that answer free-form player text in a game on Summer Games
 - `vfx-hit-spark` — hit flash recipe
 - `vfx-dissolve` — death dissolve recipe
 - `game-feel` — screen-feel discipline (camera shake, hit-stop)

package/library/skills/design-npc/resource.yaml

@@ -1,6 +1,6 @@
 id: skill/design-npc
 kind: skill
-version: 1.0.2
+version: 1.0.3
 summary: "Design enemy, NPC, boss or companion behavior: perception, state machine, telegraphs, script stub."
 use_when:
   - designing an enemy, NPC, boss, companion, civilian, or wave-spawned mob's behavior — perception, intent, state machine, telegraphs, defeat handling
@@ -21,6 +21,7 @@ related:
     - skill/game-feel
     - skill/vfx-dissolve
     - skill/vfx-hit-spark
+    - skill/summer-router
 source: official
 license: MIT
 status: stable

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

@@ -1,11 +1,11 @@
 ---
 name: navigate-summer
-description: "Open a Summer web page or editor surface for the user (billing, their games, a scene) with studio.open."
+description: "Open a Summer page or editor view for the person: studio.open, and engine.view_set while you work."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode, Factory, Copilot]
 category: _meta
 user-invocable: true
-allowed-tools: summer_call summer_get_project_context summer_is_running
+allowed-tools: summer_call summer_get_project_context summer_is_running summer_view_set summer_frame_shot
 paths: ["**/project.godot", "**/*.tscn", "**/.summer/**"]
 ---
 
@@ -55,6 +55,26 @@ Use `open: false` (CLI: `--print`) and paste the `url` (or `login_url`) when the
 
 The editor owns its own table of destinations (the `Navigate` op) and tells the tool which ids it can open. `studio.open({})` lists every editor id with `availability`: `available` (Navigate op), `legacy` (an older engine serving it through its original op), `unavailable` (update Summer Engine), `unknown` (engine not running). Ids: `scene` (default = the project's main scene), `main-scene`, `node`, `script` (with `line`), `file`, `files`, `scene-tree`, `inspector`, `import-dock`, `signals-dock`, `changes-dock`, `screen-2d/3d/script/game/assetlib`, `viewport-show/hide`, `assistant`, `project-settings`, `editor-settings`, `output`, `debugger`, `editor-window`. On a legacy engine, `script` opens without taking focus — mention it if the user does not see it.
 
+## While you work: what to open when
+
+When you drive Summer Engine from outside (Claude Code, Codex, Cursor, the `summer` CLI), the person is not using the in-app chat. The editor is their window onto your work. A line at the bottom of it names your app and says what you are doing ("Claude Code · Placing 12 trees"). You choose what they see with `engine.view_set` (3.x `summer_view_set`): `view` (`3d`, `2d`, `script`, `game`, `chat`, `home`, `studio`), optional `rail` (`scene`, `inspector`, `files`, `output`, `none`), optional `focus` and optional `frame`. A node path in `focus` selects that node; a `res://` script or scene opens. `frame` lists the nodes to frame the camera on. Switching is instant and changes nothing in the game.
+
+| You are about to… | Show |
+|---|---|
+| Edit a scene (place, move, remove nodes) | `{"view": "3d", "rail": "scene", "focus": "<the node or group you edit>", "frame": ["<it>"]}`; a 2D game uses `"2d"` |
+| Write or fix a script | `{"view": "script", "focus": "res://<the script>.gd"}` |
+| Tune one node's properties | `{"view": "3d", "rail": "inspector", "focus": "<that node>"}` |
+| Playtest | `{"view": "game"}`, then play the game |
+| Review how it looks | a `summer_frame_shot` of the result |
+| Read errors or logs with the person | `{"view": "3d", "rail": "output"}` |
+| Finish | the best view of the result: the game in `game` for gameplay work, the framed scene in `3d` or `2d` for level and art work, the script for code-only changes |
+
+- Open the view before the first edit of a step, so the person watches the change happen.
+- Focus what you change, not the scene root; for a group, focus its parent.
+- Make one call when the kind of work changes, not one per edit.
+- End on the result, never on an empty or unrelated view.
+- When the person is using the in-app chat, let them choose the view.
+
 ## Anti-patterns
 
 - Opening `billing` or `pricing` when the user asked about a **feature**, not money.
@@ -75,6 +95,7 @@ No Summer MCP tools in this session? Run each one as a command; when `summer --v
 | `summer_is_running` | `summer engine is-running` |
 | `summer_play` | `summer engine play` |
 | `summer_screenshot` | `summer engine screenshot` |
+| `engine.view_set`, `summer_view_set` | `summer engine view-set` |
 | `store.publish` | `summer store publish` |
 | `studio.open`, `summer_open` | `summer studio open` |
 <!-- /shell-commands -->

package/library/skills/navigate-summer/resource.yaml

@@ -1,11 +1,12 @@
 id: skill/navigate-summer
 kind: skill
-version: 1.0.0
-summary: "Open a Summer web page or editor surface for the user (billing, their games, a scene) with studio.open."
+version: 1.0.1
+summary: "Open a Summer page or editor view for the person: studio.open, and engine.view_set while you work."
 use_when:
   - the user asks to see, check, or decide something — "show me my billing", "where do I change my plan", "open my games", "let me look at the scene", "take me to the MCP guide for Cursor"
-  - deciding whether to open a surface for the user or to do the work through Summer tools
+  - deciding whether to open a surface (a page of the website) for the user or to do the work through Summer tools or an API
   - handing the user a link (headless, remote, or the user prefers a link) instead of launching a browser
+  - "you drive Summer Engine from outside (Claude Code, Codex, Cursor, the summer CLI) and the editor should show what you work on: the view, rail and focus for editing, scripting, playtesting, review and the end result"
 do_not_use_when:
   - the user wants a change made — add/set/remove nodes, publish, generate; use the build skills and mutation tools
   - opening a project directory in the engine — `summer run <path>`
@@ -25,6 +26,7 @@ compatibility:
 related:
   tools:
     - tool/open
+    - tool/view-set
   references:
     - reference/product-map
   skills: