summer-engine 3.1.0 → 3.2.0

package/dist/installer/agent-table.js

@@ -76,6 +76,25 @@ function vsCodeGlobalStorage(ctx, extensionId, fileName) {
 }
 const home = (...parts) => (ctx) => join(ctx.home, ...parts);
 const project = (...parts) => (ctx) => join(ctx.cwd, ...parts);
+/**
+ * The agentskills.io shared folder: `~/.agents/skills` and `<project>/.agents/skills`.
+ * Every agent whose docs say it reads this folder installs here, so one
+ * install serves them all and "where are the skills" has one answer.
+ */
+const SHARED_SKILLS_USER = home(".agents", "skills");
+const SHARED_SKILLS_PROJECT = project(".agents", "skills");
+function sharedSkills(extra = {}) {
+    return { kind: "skill-dir", user: SHARED_SKILLS_USER, project: SHARED_SKILLS_PROJECT, ...extra };
+}
+/** True when this location is the shared agentskills.io folder. */
+export function isSharedSkillsPath(path) {
+    return /[\\/]\.agents[\\/]skills$/.test(path);
+}
+/** Agents that read the shared folder at the given scope (for the install summary). */
+export function agentsSharingSkills(scope, ctx) {
+    const shared = (scope === "user" ? SHARED_SKILLS_USER : SHARED_SKILLS_PROJECT)(ctx);
+    return SPECS.filter((spec) => resolveSkillPath(spec, scope, ctx)?.path === shared);
+}
 /** agentskills.io layout (`<dir>/<skill>/SKILL.md`) under a user dir and a project dir. */
 function skillDirs(user, proj, extra = {}) {
     return { kind: "skill-dir", user, project: proj, ...extra };
@@ -121,7 +140,7 @@ const SPECS = [
             projectNote: "Codex only loads project .codex/config.toml from trusted projects.",
         },
         restart: "Restart Codex or run /mcp in a new session.",
-        skills: skillDirs(home(".agents", "skills"), project(".agents", "skills")),
+        skills: sharedSkills(),
     },
     {
         id: "cursor",
@@ -132,9 +151,10 @@ const SPECS = [
         format: "json-stdio",
         mcp: { user: home(".cursor", "mcp.json"), project: project(".cursor", "mcp.json") },
         restart: "Restart Cursor and enable the summer-engine MCP server if prompted.",
-        skills: skillDirs(home(".cursor", "skills"), project(".cursor", "skills"), {
-            reloadHint: "Cursor loads skills in the next chat. Summer 3.0 and earlier wrote rule files to .cursor/rules; `--force` removes those.",
+        skills: sharedSkills({
+            reloadHint: "Cursor loads skills in the next chat. Summer 3.0 wrote rule files to .cursor/rules and 3.1.0 wrote .cursor/skills; `--force` removes both.",
             legacyRules: { user: home(".cursor", "rules"), project: project(".cursor", "rules"), suffix: ".mdc" },
+            legacyDirs: { user: home(".cursor", "skills"), project: project(".cursor", "skills") },
         }),
     },
     {
@@ -149,7 +169,7 @@ const SPECS = [
             project: null,
         },
         restart: "Restart Devin Desktop (formerly Windsurf) and refresh MCP servers from the agent settings. Devin's docs say mcp_config.json configures the Cascade agent; for the Devin agent add the server in the app's MCP settings with the same command.",
-        skills: skillDirs(home(".codeium", "windsurf", "skills"), project(".windsurf", "skills")),
+        skills: sharedSkills({ legacyDirs: { user: home(".codeium", "windsurf", "skills"), project: project(".windsurf", "skills") } }),
     },
     {
         id: "antigravity",
@@ -259,7 +279,7 @@ const SPECS = [
         format: "json-vscode",
         mcp: { user: (ctx) => join(vsCodeUserDir(ctx), "mcp.json"), project: project(".vscode", "mcp.json") },
         restart: "Restart VS Code or run MCP: List Servers, then start summer-engine in Copilot Agent mode.",
-        skills: skillDirs(home(".copilot", "skills"), project(".github", "skills")),
+        skills: sharedSkills({ legacyDirs: { user: home(".copilot", "skills"), project: project(".github", "skills") } }),
     },
     {
         id: "visual-studio",
@@ -300,9 +320,10 @@ const SPECS = [
             project: project("opencode.json"),
         },
         restart: "Restart OpenCode so it reloads opencode.json.",
-        skills: skillDirs((ctx) => join(xdgOrAppData(ctx), "opencode", "skills"), project(".opencode", "skills"), {
-            reloadHint: "OpenCode loads skills from this folder on the next session. Summer 3.0 and earlier wrote markdown under agents/summer; `--force` removes those.",
+        skills: sharedSkills({
+            reloadHint: "OpenCode loads skills from this folder on the next session. Summer 3.0 wrote markdown under agents/summer and 3.1.0 wrote opencode/skills; `--force` removes both.",
             legacyRules: { user: (ctx) => join(xdgOrAppData(ctx), "opencode", "agents", "summer"), project: project(".opencode", "agents", "summer"), suffix: ".md" },
+            legacyDirs: { user: (ctx) => join(xdgOrAppData(ctx), "opencode", "skills"), project: project(".opencode", "skills") },
         }),
     },
     {
@@ -317,7 +338,7 @@ const SPECS = [
             project: null,
         },
         restart: "Zed reloads settings.json live; open the Agent panel and check summer-engine under MCP servers.",
-        skills: skillDirs(home(".agents", "skills"), project(".agents", "skills")),
+        skills: sharedSkills(),
     },
     {
         id: "kiro",
@@ -355,8 +376,9 @@ const SPECS = [
         format: "yaml-hermes",
         mcp: { user: home(".hermes", "config.yaml"), project: null },
         restart: "Run /reload-mcp in Hermes Agent (or restart it).",
-        skills: skillDirs(home(".hermes", "skills"), project(".hermes", "skills"), {
+        skills: skillDirs(home(".hermes", "skills"), SHARED_SKILLS_PROJECT, {
             reloadHint: "Project skills need `hermes skills trust` before Hermes loads them.",
+            legacyDirs: { user: home(".hermes", "skills"), project: project(".hermes", "skills") },
         }),
     },
     {
@@ -395,7 +417,7 @@ const SPECS = [
         format: "json",
         mcp: { user: home(".kimi-code", "mcp.json"), project: project(".kimi-code", "mcp.json") },
         restart: "Restart Kimi Code CLI so it reconnects its MCP servers.",
-        skills: skillDirs(home(".kimi-code", "skills"), project(".kimi-code", "skills")),
+        skills: sharedSkills({ legacyDirs: { user: home(".kimi-code", "skills"), project: project(".kimi-code", "skills") } }),
     },
     {
         id: "crush",
@@ -409,7 +431,7 @@ const SPECS = [
             project: project(".crushrc"),
         },
         restart: "Restart Crush so it reloads crushrc.",
-        skills: skillDirs(home(".config", "crush", "skills"), project(".crush", "skills")),
+        skills: sharedSkills({ legacyDirs: { user: home(".config", "crush", "skills"), project: project(".crush", "skills") } }),
     },
     {
         id: "amp",
@@ -420,7 +442,7 @@ const SPECS = [
         format: "json-amp",
         mcp: { user: (ctx) => join(xdgOrAppData(ctx), "amp", "settings.json"), project: null },
         restart: "Restart Amp so it reloads settings.json.",
-        skills: skillDirs((ctx) => join(xdgOrAppData(ctx), "amp", "skills"), project(".agents", "skills")),
+        skills: sharedSkills({ legacyDirs: { user: (ctx) => join(xdgOrAppData(ctx), "amp", "skills"), project: null } }),
     },
     {
         id: "factory",
@@ -431,7 +453,7 @@ const SPECS = [
         format: "json-stdio",
         mcp: { user: home(".factory", "mcp.json"), project: project(".factory", "mcp.json") },
         restart: "Restart droid or run /mcp in the active session.",
-        skills: skillDirs(home(".factory", "skills"), project(".factory", "skills")),
+        skills: sharedSkills({ legacyDirs: { user: home(".factory", "skills"), project: project(".factory", "skills") } }),
     },
     {
         id: "junie",
@@ -454,7 +476,7 @@ const SPECS = [
         format: "json",
         mcp: { user: home(".warp", ".mcp.json"), project: project(".warp", ".mcp.json") },
         restart: "Warp detects the file and spawns the server; check Settings > AI > MCP servers.",
-        skills: skillDirs(home(".warp", "skills"), project(".warp", "skills")),
+        skills: sharedSkills({ legacyDirs: { user: home(".warp", "skills"), project: project(".warp", "skills") } }),
     },
     {
         id: "rovo-dev",
@@ -465,7 +487,7 @@ const SPECS = [
         format: "json-transport",
         mcp: { user: home(".rovodev", "mcp.json"), project: null },
         restart: "Restart Rovo Dev CLI so it reconnects its MCP servers.",
-        skills: skillDirs(home(".rovodev", "skills"), project(".rovodev", "skills")),
+        skills: sharedSkills({ legacyDirs: { user: home(".rovodev", "skills"), project: project(".rovodev", "skills") } }),
     },
     {
         id: "qoder",
@@ -487,7 +509,7 @@ const SPECS = [
         format: "toml",
         mcp: { user: home(".grok", "config.toml"), project: project(".grok", "config.toml") },
         restart: "Restart Grok Build so it reloads config.toml (it also reads ~/.claude.json and .cursor/mcp.json).",
-        skills: skillDirs(home(".grok", "skills"), project(".grok", "skills")),
+        skills: sharedSkills({ legacyDirs: { user: home(".grok", "skills"), project: project(".grok", "skills") } }),
     },
     {
         id: "mistral-vibe",
@@ -498,7 +520,7 @@ const SPECS = [
         format: "toml-array",
         mcp: { user: home(".vibe", "config.toml"), project: project(".vibe", "config.toml") },
         restart: "Restart Vibe so it reloads config.toml.",
-        skills: skillDirs(home(".vibe", "skills"), project(".vibe", "skills")),
+        skills: skillDirs(home(".vibe", "skills"), SHARED_SKILLS_PROJECT, { legacyDirs: { user: home(".vibe", "skills"), project: project(".vibe", "skills") } }),
     },
     {
         id: "lm-studio",
@@ -573,6 +595,19 @@ export function legacyRuleFiles(spec, scope, ctx, skillNames) {
     const prefix = spec.id === "opencode" ? "" : "summer-";
     return [...skillNames].map((name) => join(dir, `${prefix}${name}${legacy.suffix}`));
 }
+/** Skill dirs a Summer 3.1.0 install may have written at this agent's old native location; `null` when it never moved. */
+export function legacySkillDirs(spec, scope, ctx, skillNames) {
+    const legacy = spec.skills?.legacyDirs;
+    if (!legacy)
+        return null;
+    const dir = scope === "project" ? (legacy.project ? legacy.project(ctx) : null) : legacy.user(ctx);
+    if (!dir)
+        return [];
+    const current = resolveSkillPath(spec, scope, ctx)?.path;
+    if (current === dir)
+        return [];
+    return [...skillNames].map((name) => join(dir, name));
+}
 /** Where skills go for an agent with a skills home. */
 export function resolveSkillPath(spec, scope, ctx) {
     if (!spec.skills)

package/dist/mcp/server.js

@@ -4,10 +4,13 @@ import { EngineApiClient } from "../core/api-client.js";
 import { registerSceneTools } from "./tools/scene-tools.js";
 import { registerDebugTools } from "./tools/debug-tools.js";
 import { registerVisualTools } from "./tools/visual-tools.js";
+import { registerSeeingTools } from "./tools/seeing-tools.js";
+import { registerAuditTools } from "./tools/audit-tools.js";
 import { WITH_ENGINE_META } from "./tools/with-engine.js";
 import { registerPlaybookPrompt, registerProjectTools, } from "./tools/project-tools.js";
 import { registerPerceptionTools } from "./tools/perception-tools.js";
 import { registerSpatialTools } from "./tools/spatial-tools.js";
+import { registerPlacementTools } from "./tools/placement-tools.js";
 import { registerScriptTools } from "./tools/script-tools.js";
 import { registerEventTools } from "./tools/event-tools.js";
 import { registerFabricateTools } from "./tools/fabricate-tools.js";
@@ -36,10 +39,10 @@ export const getCachedBootDriftNotice = getCachedNotice;
  * it costs a few hundred tokens once; the full operating guide stays in the
  * summer_agent_playbook prompt / summer_get_agent_playbook tool.
  */
-export const SUMMER_MCP_INSTRUCTIONS = "Summer Engine MCP. Call summer_get_project_context first: it binds this session to the open project and returns mainScene, projectMemory (GameSoul, template pin) and any capabilitySkewWarning. " +
-    "Before building or fixing, summer_search_library then summer_read_library the hit — skills, examples and templates live there. " +
+export const SUMMER_MCP_INSTRUCTIONS = "Summer Engine MCP. Call summer_get_project_context first: it binds this session to the open project and returns mainScene, projectMemory (GameSoul, template pin) and any capabilitySkewWarning, compactly. " +
+    "Before building or fixing, summer_search_library then summer_read_library the hit: skills, examples, templates live there. " +
     "After a playthrough read summer_get_diagnostics, not summer_get_console alone (runtime errors live in the debugger). " +
-    "A uniformly black screenshot means the viewport had not redrawn — recapture before concluding. " +
+    "An all-black screenshot means the viewport had not redrawn — recapture before concluding. " +
     "Report entries you verified in-engine via summer_library_feedback.";
 /**
  * Fire-and-forget probe of the npm registry on MCP boot. Caches the result for
@@ -302,6 +305,8 @@ export function createMcpServer() {
     registerSceneTools(server);
     registerDebugTools(server);
     registerVisualTools(server);
+    registerSeeingTools(server);
+    registerAuditTools(server);
     registerProjectTools(server);
     registerFileTools(server);
     registerAssetTools(server);
@@ -311,6 +316,7 @@ export function createMcpServer() {
     registerScriptTools(server);
     registerPerceptionTools(server);
     registerSpatialTools(server);
+    registerPlacementTools(server);
     registerNavigationTools(server);
     registerLibraryTools(server);
     registerEventTools(server);

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

@@ -23,6 +23,12 @@ async function searchAssetsApi(params) {
     if (params.source) {
         searchParams.set("source", params.source);
     }
+    if (params.style)
+        searchParams.set("style", params.style);
+    if (params.includeCommunity)
+        searchParams.set("includeCommunity", "true");
+    if (params.preview)
+        searchParams.set("contactSheet", "true");
     const gatewayUrl = await resolveGatewayUrl();
     const res = await fetch(`${gatewayUrl}/api/mcp/assets?${searchParams}`, {
         headers: { Authorization: `Bearer ${token}` },
@@ -120,7 +126,10 @@ Sources:
   - "all" — Search both library and your assets.
 
 Uses hybrid search: keywords + semantic similarity. Finds assets by name AND by meaning.
-Returns asset names, types, preview URLs, and import-ready file URLs.
+Returns asset names, types, each asset's art style, preview URLs, and import-ready file URLs.
+Keep a game in ONE art direction: pass style (the game's chosen family) so clashing styles are
+left out, and set preview to see the first results as one numbered picture before importing.
+Curated, open-source and Summer packs come first; people's own public generations only with includeCommunity.
 
 Cloud tool — works WITHOUT the Summer Engine app open.
 Requires authentication (so we can attribute usage and apply per-user rate limits): run 'npx -y summer-engine@latest login' first.`, {
@@ -128,8 +137,14 @@ Requires authentication (so we can attribute usage and apply per-user rate limit
         assetType: z.enum(["2d_image", "animation", "3d_model", "audio", "music", "all"]).default("all").describe("Filter by asset type"),
         limit: z.number().default(10).describe("Max results (1-20)"),
         source: z.enum(["library", "my_assets", "all"]).default("library").describe("Where to search: library (public 25k+), my_assets (your generated assets), all"),
-    }, async ({ query, assetType, limit, source }) => {
-        const result = await searchAssetsApi({ query, assetType, limit: Math.min(limit, 20), source });
+        style: z
+            .enum(["realistic", "stylized-lowpoly", "toon", "pixel", "hand-painted", "voxel"])
+            .optional()
+            .describe("The game's one art direction: clashing styles are left out, matches come first"),
+        preview: z.boolean().default(false).describe("Also return one picture of the first 9 results, numbered in order, to see them before importing"),
+        includeCommunity: z.boolean().default(false).describe("Also include people's own public AI generations"),
+    }, async ({ query, assetType, limit, source, style, preview, includeCommunity }) => {
+        const result = await searchAssetsApi({ query, assetType, limit: Math.min(limit, 20), source, style, preview, includeCommunity });
         if (result.error) {
             return {
                 content: [
@@ -141,6 +156,7 @@ Requires authentication (so we can attribute usage and apply per-user rate limit
                 isError: true,
             };
         }
+        const sheet = result.contactSheet?.match(/^data:(image\/[a-z]+);base64,(.+)$/);
         return {
             content: [
                 {
@@ -150,8 +166,10 @@ Requires authentication (so we can attribute usage and apply per-user rate limit
                         count: result.count,
                         summary: result.summary,
                         message: result.message,
+                        ...(sheet ? { preview: "attached: the first results, numbered in this order" } : {}),
                     }, null, 2),
                 },
+                ...(sheet ? [{ type: "image", data: sheet[2], mimeType: sheet[1] }] : []),
             ],
         };
     });

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

@@ -0,0 +1,23 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type AuditResult } from "../../core/capabilities/audit/audit.js";
+/**
+ * summer_scene_audit: one read-only call that walks every node of a 3D scene
+ * and lists likely visual and placement problems, so a build agent knows
+ * exactly where to look. Implementation and the in-engine kernel:
+ * src/core/capabilities/audit/ and assets/audit/scene_audit.gd.
+ */
+type ToolResultContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+type ToolResult = {
+    content: ToolResultContent[];
+    isError?: boolean;
+};
+export declare function auditContent(result: AuditResult): ToolResult;
+export declare function registerAuditTools(server: McpServer): void;
+export {};

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

@@ -0,0 +1,60 @@
+import { withEngine } from "./with-engine.js";
+import { sceneAudit } from "../../core/capabilities/audit/audit.js";
+import { sceneAuditShape } from "../../core/capabilities/audit/args.js";
+export function auditContent(result) {
+    if (!result.ok) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        ok: false,
+                        tool: "summer_scene_audit",
+                        failure_reason: result.failure_reason,
+                        error: result.error,
+                        ...(result.hint ? { hint: result.hint } : {}),
+                        ...(result.detail ? { detail: result.detail } : {}),
+                    }),
+                },
+            ],
+        };
+    }
+    const content = [];
+    if (result.image)
+        content.push({ type: "image", data: result.image.base64, mimeType: result.image.mime || "image/jpeg" });
+    content.push({ type: "text", text: JSON.stringify(result.summary) });
+    return { content };
+}
+export function registerAuditTools(server) {
+    server.tool("summer_scene_audit", `Audit a 3D scene in one fast, read-only call: every node and subnode is walked and likely visual and placement problems come back as a short list, sorted by severity, so you know exactly where to look. Each issue is a flag to LOOK at, never an auto-fix.
+
+Checks (each can be picked with checks):
+- through_hole: capped ray grids through every facade line (coplanar wall fronts); clusters of rays that pass the wall AND reach the far side of the building (a door insert narrower than its frame, a missing module, a seam). Walls, structure and inserts close an opening; props do not.
+- exposed_edge: open outline edges of walls and facade members (bands, piers, corner blocks; cached per mesh) that nothing covers within 4-7 mm, seen from walkable space (eye points over open-sky floor cells, flood-filled from the scene's cameras and characters, sight lines not through a building), with a 2-60 cm reveal behind them, or a coplanar sheet continuing within 4 cm (seam) or 35 cm (gap). Warn on band pieces and when depth_step agrees, look otherwise; repeats group per piece type.
+- open_fixture_end: open ends of run pieces (a mesh with two or more open rims of one size: pipe, duct or gutter sections, elbows, tees) that nothing joins within 2.5 cm (sleeve tolerance), seen from walkable space: a missing elbow, coupler, section or end piece (warn). A piece with one rim or rims of different sizes (a cap, a funnel, an outlet) is open by design.
+- depth_step (look): ray rows across each visible facade side at its band levels and every 1.25 m: band recesses and missing runs, seams, modules standing proud, holes with something behind them; a hole next to a through_hole confirms it (warn -> error); runs a door-like opening covers are skipped.
+- floor_gap: down rays over the floor tiles, along their seams, and from each tile edge to a wall within 1 m (bare strips at wall bases), classified by the FIRST surface hit: the void (error); an underlay over the floor's own lower surface such as a drain channel ("covers the floor", warn, not a hole); an underlay through a hole or strip. Areas are the missed rays' own footprints with the strip's size; a tile whose own mesh has holes is one issue for the piece.
+- floating / sunken: support under each prop's footprint; gap over 2 cm, embed over 3 cm, measured against the first surface from above (the tile it is buried in, not the underlay under it); structure and pieces touching a wall well off the ground excluded.
+- interpenetration: each prop's convex hulls against props, walls, structure and inserts; a deepest overlap over 3 cm, then every partner it cuts (up to 3).
+- orientation (look): long props within 1.2 m of a wall more than 15 deg off parallel. It never says which way a piece should face.
+- uv_stretch: per mesh resource, large triangles whose UV-to-world mapping is stretched over 8:1 or collapsed to a line, where an instance shows them (a reveal that inserts normally cover = warn).
+- duplicate: the same scene at the same transform.
+- z_fight: coplanar overlapping faces anywhere, from each mesh's planar face groups: between any two pieces (props, roofs, ledges, side walls, inserts against hosts, decals; opposite-facing only when both are double-sided) and between two surfaces of one mesh (once per mesh), plus the ray samples. Coplanar = a gap under twice the 24-bit depth step at the view distance (the nearest walkable eye point, camera or bookmark; 30 m without one) for the main camera's near/far; ev carries the overlap, gap, tolerance, surfaces, the plane's normal and the axis to nudge (nudge.world, nudge.local: a window can share its head or a jamb with its host, not its front). Warn over 0.05 m2 seen from a viewpoint; the material decides what is demoted to look, with the reason: render_priority, depth or normal offsets, a see-through (alpha) material, no depth test or depth writes.
+- lights: meshes paired with more than the per-object limit of omni or spot lights (Compatibility: 8 each; light cuts off at seams), spot lights with spot_angle_attenuation under 3; shadowed light counts.
+- transform: NaN, negative or non-uniform scale, a piece far out of bounds, and pieces left at the origin: an identity LOCAL transform under an identity parent, touching nothing and not one of a row of siblings (several sharing it warn, one alone is look; a module whose corner is the world origin is placed).
+- resource: missing dependency files, MeshInstance3D without a mesh, surfaces without a material.
+
+budget_ms (default 3000) bounds the editor time: each check gets a weighted share of it, and a check past its share stops and is marked counts.<check>.partial (the share it covered), never clean. The three gap detectors (exposed_edge, open_fixture_end, depth_step) run last on the time the other checks leave (band pieces and band rows first); rerun them alone when partial.
+
+accept:[{key, reason}] (keys from issues[].key) records look and warn items you judged fine in res://.summer/audit-accept.json (the only file the audit writes); later audits count them (counts.<check>.accepted) but hide them until their evidence changes materially (severity rises, or the measured size moves by over 25%: shown again with accept_stale). Errors cannot be accepted; show_accepted lists them.
+
+Returns at most 5 KB of JSON: counts per check, time per check (editor ms), the scene size, and ONE page of issues {n, check, sev (error|warn|look), path, pos (world), why, ev (evidence numbers: sizes, distances, angles, the ray to reproduce), next (the tool to use next), key (for accept)}. Page with offset/limit (next_offset names the next page); filter with checks, root (a subtree) and min_severity. render:"sheet" adds ONE inline image of the page's first 6 issues framed up close from their open side (a camera never behind a wall), each tile labelled #n.
+
+Every check works on any scene from geometry, the engine's node and resource data and materials alone: never node or file names, never kit metadata. Each piece's role comes from its shape: see-through cards (every material alpha) are dressing; thin upright sheets are walls (facing their side with more face area); flat slabs whose tops cover their footprint are floors (raised ones with walls under them are roofs, a large one below the rest is the underlay); a piece inside a wall's rectangle that reaches through the wall where it is open is an insert; bands, piers and corner blocks touching a facade wall are structure; the rest are props up to 3.5 m.
+
+Read-only: it audits the SAVED file in a private offscreen copy (ScenePreview), so the open tab never becomes unsaved, undo is untouched and nothing is saved (accept writes only its own file). Save the scene first. Failures are structured (failure_reason), never a silent fallback.`, sceneAuditShape, async (args) => withEngine(async (client) => {
+        const audit = await sceneAudit(client, args);
+        return audit.ok ? { audit } : { audit, failure_reason: audit.failure_reason };
+    }, { onResult: (wrapped) => auditContent(wrapped.audit) }));
+}

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

@@ -200,7 +200,9 @@ After starting, confirm boot with summer_is_running (boot time varies — never
 
 DETERMINISTIC RUNS (newer engines): seed / fixed_fps / time_scale pin THIS launch only (nothing is persisted). seed pins the game's GLOBAL RNG (randi/randf/randi_range/randf_range/randfn, Array.shuffle/pick_random) — it does NOT pin RandomNumberGenerator instances, scripts that call randomize(), rand_from_seed, wall-clock reads, or thread/IO/audio timing. fixed_fps decouples scene time from the wall clock so frame-count-derived state lands on the same frame run to run. The result's \`determinism\` block says whether the pins were applied (applied:false carries a reason: already_running, editor_run_args_override, launch_not_started) and restates seed_scope. If the result has NO determinism block although you sent a pin, the engine predates the params and the run is NOT reproducible — the tool says so; do not claim otherwise. Omitting every pin and instance parameter is exactly the v1 launch.
 
-PLAYTEST LAUNCH (engine runtime-control build): instance + mode:'offscreen' spawn a disposable hidden instance (at most 3) that summer_game_probe / summer_game_input / summer_game_control / summer_runtime_* address by name — run two variants side by side for an A/B. deterministic:true (offscreen only) launches with --fixed-fps 60 --summer-seed --audio-driver Dummy and is what lets summer_game_input action:'replay' accept a seed; speed sets the user time scale on session start. The instance result reports session_attached; poll summer_game_control action:'instances' until attached:true before addressing it. Then: probe -> act -> step/probe -> assert (the agent-playtesting skill). Failure reasons: too_many_instances, instance_exists, session_timeout (child never attached — check summer_get_console), unsupported_mode, main_scene_not_configured. A game already running answers playing:true with determinism.applied:false — summer_stop first to apply seed/fixed_fps.`, {
+PLAYTEST LAUNCH (engine runtime-control build): instance + mode:'offscreen' spawn a disposable hidden instance (at most 3) that summer_game_probe / summer_game_input / summer_game_control / summer_runtime_* address by name — run two variants side by side for an A/B. deterministic:true (offscreen only) launches with --fixed-fps 60 --summer-seed --audio-driver Dummy and is what lets summer_game_input action:'replay' accept a seed; speed sets the user time scale on session start. The instance result reports session_attached; poll summer_game_control action:'instances' until attached:true before addressing it. Then: probe -> act -> step/probe -> assert (the agent-playtesting skill). Failure reasons: too_many_instances, instance_exists, session_timeout (child never attached — check summer_get_console), unsupported_mode, main_scene_not_configured. A game already running answers playing:true with determinism.applied:false — summer_stop first to apply seed/fixed_fps.
+
+MULTIPLAYER — LOCAL PLAY (Summer multiplayer games; engine with Local Play): players:N starts the game's authority headless plus N clients on this machine, each joining through the game's OWN Summer.client.join(SummerJoinTarget.queue(...)) — no account, login, Docker, CLI or local-only game code. The scenes and queue come from the project's summer.build.json and its WorldDefinition (client_entry_point + the headless_engine component entry_point); queue picks another declared queue — pass queue WITHOUT players to start that queue's minPlayers (a 4-player queue starts 4), or players to choose; spectators adds spectator clients. local_play.warnings flags a roster outside the queue's minPlayers..maxPlayers. The result's local_play block lists every process (label, role, persona) and the port; failure_reason local_play_unavailable says exactly what to declare. Every process attaches to the editor debugger: screenshots, input and summer_game_* go to the FIRST client, the authority's output is in summer_get_console, and summer_stop stops them all. A join for a different queue fails with a message naming both queues. It is not a proof of sign-in, matchmaking or hosted admission (staging). No local_play block although you sent players means the engine predates Local Play and ran ONE client — the tool says so.`, {
         scene: z.string().optional().describe("Scene to run instead of main scene, e.g. 'res://levels/test_level.tscn'"),
         ...playGameExtensionSchema,
     }, async (args) => {

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

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { withEngine, ToolInputError } from "./with-engine.js";
 import { occurrenceCount, readTextPayload, safeProjectPath, validSha256, } from "../../core/capabilities/engine-ops.js";
+import { readFileInputShape, readProjectFileWindow } from "../../core/capabilities/file-read.js";
+import { GREP_DEFAULT_MAX_RESULTS, GREP_MAX_RESULTS, grepInputShape, grepProject, } from "../../core/capabilities/grep.js";
 // MCP clients may issue tool calls concurrently. Keep the complete read->write
 // transaction ordered for one project file while allowing unrelated files to
 // proceed in parallel. The tail is always released in `finally`, so a rejected
@@ -32,10 +34,21 @@ async function withFileMutationTurn(projectIdHash, path, fn) {
 export function registerFileTools(server) {
     server.tool("summer_read_file", `Read a text file from the engine-bound project and return its full-file sha256 receipt.
 
-Use the returned sha256 as expected_sha256 when overwriting an existing file. Paths must begin with res://.`, {
-        path: z.string().describe("Project path, e.g. res://scripts/player.gd"),
-        max_bytes: z.number().int().positive().max(1_000_000).default(200_000),
-    }, async ({ path, max_bytes }) => withEngine(async (client) => client.readProjectFile(safeProjectPath(path), max_bytes)));
+Use the returned sha256 as expected_sha256 when overwriting an existing file. Paths must begin with res://.
+
+READ BIG FILES IN PARTS instead of all at once:
+- offset + limit page the file: lines by default (unit:'bytes' for a byte range on UTF-8 boundaries). The result's data.window gives start_line/end_line, total_lines, next_offset (null at the end) and eof.
+- For JSON: json_path picks one value ('pieces.wall_a', 'items[3]'); keys keeps matching object keys (['wall_*']); keys_only lists key names only. data.json says what matched. offset/limit then page the selection.
+The sha256 always covers the WHOLE file, so a windowed read still guards a later overwrite. Files over 1 MB can be paged only within their first 1 MB.`, readFileInputShape, async (args) => withEngine(async (client) => readProjectFileWindow(client, args)));
+    server.tool("summer_grep", `Search project files with a regular expression (ripgrep, through the engine) and get file + line + text per match, optionally with context lines around each.
+
+Use it to find things in big files without reading them whole: every '"fits_into"' in a kit manifest, the scenes of a kit (glob '*.tscn'), where a signal handler is defined. Then read exactly the part you need with summer_read_file (offset/limit, or json_path for JSON).
+
+- path: a res:// directory or file (default: the whole project; .godot/ and .import/ are never searched).
+- glob: ripgrep --glob filter ('*.gd', '**/*.json', '!addons/**'). Ripgrep skips files ignored by .gitignore unless a glob names them.
+- context_lines (0-10): lines before/after each match, as before[] / after[].
+- max_results (default ${GREP_DEFAULT_MAX_RESULTS}, max ${GREP_MAX_RESULTS}) caps the matches; truncated:true says there were more. Lines are clipped to max_line_chars.
+Case-insensitive unless case_sensitive:true. Read-only.`, grepInputShape, async (args) => withEngine(async (client) => grepProject(client, args)));
     server.tool("summer_write_file", `Create or safely overwrite a complete text file through the identity-bound engine.
 
 For a new file, set create_only:true. For an existing file, first call summer_read_file and pass its sha256 as expected_sha256. Exactly one guard is required; unguarded writes fail closed. Supports scripts, .tscn scenes, .tres resources, JSON, docs, and project config.`, {

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

@@ -1,5 +1,7 @@
 import { z } from "zod";
+import { BOARD_ENDPOINT, boardArgsSchema, boardContent, boardQuery } from "../../core/capabilities/board.js";
 import { imageGenerationArgsSchema } from "../../core/capabilities/image-generation.js";
+import { buildMotionRequestBody, motionErrorHint, motionGenerationArgsSchema, motionJobFailureHint, } from "../../core/capabilities/motion-generation.js";
 import { writeFile, mkdir } from "fs/promises";
 import { tmpdir } from "os";
 import { join } from "path";
@@ -16,6 +18,7 @@ const TOOL_BY_ENDPOINT = {
     "/api/mcp/generate/motion": "summer_generate_motion",
     "/api/mcp/generate/slice-asset-sheet": "summer_slice_asset_sheet",
     "/api/mcp/workflows": "summer_get_studio_workflow",
+    [BOARD_ENDPOINT]: "summer_get_board",
 };
 // ---------------------------------------------------------------------------
 // Shared helpers
@@ -253,6 +256,26 @@ handoff that MCP cannot perform automatically; do not pretend that stage ran.`,
         return successResult(result.data);
     });
     // ========================================================================
+    // summer_get_board
+    // ========================================================================
+    server.tool("summer_get_board", `Read the person's approved planning board for this game: the look (palette,
+description, picture), the characters, the place, the first-minute storyboard
+and the cards they picked, with a version that changes when the board does.
+
+The look and the picked cards come back as images you can see. Read the board at
+the start of each build step and compare your screenshot against its images
+(palette, shapes and proportions, camera angle, composition); fix the biggest
+difference. Use the picked card pictures as referenceImageUrl for
+summer_generate_image to make sprites and backgrounds in the same look.
+
+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.`, boardArgsSchema.shape, async (args) => {
+        const result = await mcpGet(BOARD_ENDPOINT, boardQuery(args), 45_000);
+        if (result.error)
+            return errorResult(result.error, result.data);
+        return { content: boardContent(result.data ?? {}) };
+    });
+    // ========================================================================
     // summer_generate_image
     // ========================================================================
     server.tool("summer_generate_image", `Generate an image using AI models via Summer Engine Studio.
@@ -651,89 +674,74 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
     // ========================================================================
     // summer_generate_motion
     //
-    // NOTE (2026-05-10): only the "meshy-library" backend is exposed today.
-    // The "hunyuan-custom" path exists in the Studio route but has not been
-    // tested end-to-end on a user's rig (Hunyuan returns a generic skeleton
-    // FBX that isn't retargeted onto the caller's character). The schema and
-    // call are kept commented-out below — re-enable by restoring the wider
-    // zod enum, the prompt/durationSeconds params, the validation branch, and
-    // the relevant description lines once the path is verified.
+    // Backends exposed: "meshy-library" (curated humanoid mocap by name) and
+    // "text-to-motion" (Summer-hosted model, any of the caller's own rigs, from
+    // text prompts; default-off on the server until enabled, which answers 400
+    // backend_unavailable). The Studio route's "hunyuan-custom" stays hidden: it
+    // returns a generic skeleton FBX that is not retargeted onto the caller's
+    // rig. The shared zod shape + body builder live in
+    // core/capabilities/motion-generation.ts so `summer tool generate-motion`
+    // validates identically.
     // ========================================================================
-    server.tool("summer_generate_motion", `Generate an animation clip for a Meshy-rigged humanoid character via Summer Engine Studio.
-
-Backend:
-  - "meshy-library" — picks a clip from a curated mocap set by name (idle, walk,
-    run, attack_sword, jump, ~70 standard names). Fast (~30s), cheap (~$0.10),
-    real mocap quality.
+    server.tool("summer_generate_motion", `Generate animation clips for a rigged 3D model via Summer Engine Studio.
+
+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.
+    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
+    ANY of your own rigged models: humanoid, animal, creature, cartoon plant,
+    prop (GLB/FBX 3d_model, one skinned armature, 5-70 bones). Use it for
+    actions the library lacks (nod, bow, shrug, wave with the right arm) and
+    for non-humanoid rigs. Pass prompt or prompts (1-8), optional takes (1-4),
+    cfgScale (1.5-8, default 3; 5 for clearer gestures), and lockJoints for
+    rooted characters (e.g. ["Hips","Spine"] on a plant; never on characters
+    that walk). Human-style bone names (Hips, Spine, LeftArm...) animate far
+    better, even on non-humans. Jobs take ~1-2 min; result.assets lists one
+    animation asset per prompt x take.
+
+Each clip (meshy: each motion; text-to-motion: each prompt x take) is billed.
+State the clip list and estimated cost and confirm with the user before
+spending.
 
-Requires a Meshy-rigged humanoid as the target. The 'rigAssetId' must come from
-a prior summer_generate_3d call with options.rig=true.
-
-By default, waits for completion (up to 5 min) and returns the result directly.
-Set wait=false to get the jobId immediately and poll manually with summer_check_job.
-
-Common motion names:
-  Locomotion: idle, idle_alert, idle_combat, walk, walk_back, run, sprint,
-              crouch_idle, crouch_walk, jump, jump_loop, jump_land
-  Combat: attack_sword, attack_punch, attack_kick, attack_bow, attack_cast,
-          block, dodge_left, dodge_right, hit_react, death
-  Social: wave, dance, sit_idle
-
-Cost: ~$0.10 per clip. Confirm with user before spending.
+By default, waits for completion (up to 10 min) and returns the result directly.
+Set wait=false to get the jobId immediately and poll with summer_check_job.
+Import finished clips with summer_import_asset_by_id.
 
-Custom prompt-driven motion is on the roadmap; not yet shipped. For one-off
-signature moves not on the curated list, fall back to hand-authoring in the
-Summer Engine or importing from Mixamo.
+Errors: backend_unavailable means text-to-motion is not enabled on this server
+yet — use meshy-library for humanoids and do not retry. Job failures starting
+"text_motion:" (no skinned armature, too many/few joints, unknown joint) are
+input problems and are refunded; fix the rig or request instead of retrying.
 
 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.`, {
-        rigAssetId: z
-            .string()
-            .describe("Asset ID of a rigged character (from summer_generate_3d with options.rig=true)"),
-        backend: z
-            .enum(["meshy-library"])
-            .default("meshy-library")
-            .describe("Backend: meshy-library (only option today)"),
-        motionName: z
-            .string()
-            .describe("Curated motion name: walk, run, attack_sword, idle, jump, etc."),
-        // prompt + durationSeconds reserved for the hunyuan-custom backend (not
-        // shipped yet — see header comment).
-        wait: z
-            .boolean()
-            .default(true)
-            .describe("Wait for completion (default true, up to 5 min). Set false to get jobId immediately."),
-        options: z
-            .record(z.any())
-            .optional()
-            .describe("Backend-specific passthrough"),
-    }, async ({ rigAssetId, backend, motionName, wait, options }) => {
-        // Client-side validation
-        if (!motionName) {
-            return errorResult("motionName is required (e.g. 'walk', 'run', 'attack_sword'). See the tool description for the curated list.");
+Requires authentication: run 'npx -y summer-engine@latest login' first.`, motionGenerationArgsSchema.shape, async (args) => {
+        // Client-side validation of the backend-specific rules.
+        const built = buildMotionRequestBody(args);
+        if ("error" in built) {
+            return errorResult(built.error);
         }
-        const body = {
-            rigAssetId,
-            backend,
-            motionName,
-            options,
-        };
-        const result = await mcpGenerate("/api/mcp/generate/motion", body);
+        const result = await mcpGenerate("/api/mcp/generate/motion", built.body);
         if (result.error) {
-            return errorResult(result.error, result.data);
+            const hint = motionErrorHint(result.data?.error);
+            return errorResult(result.error, hint ? { ...result.data, hint } : result.data);
         }
         const jobId = result.data?.jobId;
-        if (!wait || !jobId) {
+        if (!args.wait || !jobId) {
             return successResult(result.data);
         }
         const pollResult = await pollJob(jobId);
         if (pollResult.error) {
-            return errorResult(pollResult.error, { ...pollResult.data, jobId });
+            const hint = motionJobFailureHint(pollResult.error);
+            return errorResult(pollResult.error, { ...pollResult.data, jobId, ...(hint ? { hint } : {}) });
         }
         return successResult({
             ...pollResult.data,
             jobId,
-            message: "Motion generation complete. animationAssetId is in result.",
+            message: args.backend === "text-to-motion"
+                ? "Motion generation complete. result.assets lists one animation asset per prompt x take; import with summer_import_asset_by_id."
+                : "Motion generation complete. animationAssetId is in result.",
         });
     });
 }