summer-engine 3.0.0 → 3.2.0

package/dist/installer/skill-locations.d.ts

@@ -3,9 +3,12 @@
  *
  * Lives in the installer layer (not cli/) so `summer setup` can report the
  * destination and count without importing the CLI (import-direction contract
- * §2: shared layers never import cli or mcp).
+ * §2: shared layers never import cli or mcp). The per-agent paths come from
+ * the one agent table (agent-table.ts); only the `summer` pseudo-client is
+ * resolved here.
  */
 import { type AgentClient } from "../core/skills-registry.js";
+import { type SkillLocationKind } from "./agent-table.js";
 export declare const SKILL_SCOPES: readonly ["user", "project"];
 export type SkillScope = (typeof SKILL_SCOPES)[number];
 /** The agent/scope flags `summer skills install` accepts (legacy aliases included). */
@@ -22,24 +25,12 @@ export declare function parseSkillScope(value: string): SkillScope;
 /** Pick the agent from --agent / legacy --as-claude-skill / --as-cursor-skill
  *  (default "summer"); throws on conflicting flags. */
 export declare function resolveSkillAgent(opts: SkillInstallSelection): AgentClient;
-/** Explicit --scope wins; otherwise project-rooted agents default to "project". */
+/** Explicit --scope wins; otherwise the agent's default (rule-file agents default to "project"). */
 export declare function resolveSkillScope(agent: AgentClient, opts: SkillInstallSelection): SkillScope;
-export type InstallLocation = {
-    kind: "skill-dir";
+export interface InstallLocation {
+    kind: SkillLocationKind;
     path: string;
-} | {
-    kind: "cursor-rule-dir";
-    path: string;
-} | {
-    kind: "windsurf-rule-file";
-    path: string;
-} | {
-    kind: "cline-rule-dir";
-    path: string;
-} | {
-    kind: "opencode-skill-dir";
-    path: string;
-};
+}
 export declare function resolveInstallLocation(agent: AgentClient, scope: SkillScope): InstallLocation;
 /** One-line, human path pattern for where an install location puts skills. */
 export declare function describeInstallLocation(location: InstallLocation): string;

package/dist/installer/skill-locations.js

@@ -3,12 +3,15 @@
  *
  * Lives in the installer layer (not cli/) so `summer setup` can report the
  * destination and count without importing the CLI (import-direction contract
- * §2: shared layers never import cli or mcp).
+ * §2: shared layers never import cli or mcp). The per-agent paths come from
+ * the one agent table (agent-table.ts); only the `summer` pseudo-client is
+ * resolved here.
  */
 import { join } from "path";
-import { homedir, platform } from "os";
+import { homedir } from "os";
 import { AGENT_CLIENTS } from "../core/skills-registry.js";
 import { tildeify } from "../core/format.js";
+import { agentSpec, defaultPathContext, resolveSkillPath, } from "./agent-table.js";
 export const SKILL_SCOPES = ["user", "project"];
 function isAgentClient(value) {
     return AGENT_CLIENTS.includes(value);
@@ -44,114 +47,32 @@ export function resolveSkillAgent(opts) {
     }
     return parseSkillAgent(opts.agent ?? legacyAgent ?? "summer");
 }
-/** Explicit --scope wins; otherwise project-rooted agents default to "project". */
+/** Explicit --scope wins; otherwise the agent's default (rule-file agents default to "project"). */
 export function resolveSkillScope(agent, opts) {
     if (opts.scope)
         return parseSkillScope(opts.scope);
-    if (agent === "cursor" ||
-        agent === "windsurf" ||
-        agent === "cline" ||
-        agent === "roo-code" ||
-        agent === "kilo-code") {
-        return "project";
-    }
-    return "user";
+    if (agent === "summer")
+        return "user";
+    return agentSpec(agent).skills?.defaultScope ?? "user";
 }
 export function resolveInstallLocation(agent, scope) {
     const overrideDir = process.env.SUMMER_SKILLS_DIR;
-    if (overrideDir) {
-        if (agent === "cursor")
-            return { kind: "cursor-rule-dir", path: overrideDir };
-        if (agent === "windsurf") {
-            return { kind: "windsurf-rule-file", path: join(overrideDir, ".windsurfrules") };
-        }
-        if (agent === "cline" || agent === "roo-code" || agent === "kilo-code") {
-            return { kind: "cline-rule-dir", path: overrideDir };
-        }
-        if (agent === "gemini") {
-            return { kind: "skill-dir", path: overrideDir };
-        }
-        if (agent === "opencode") {
-            return { kind: "opencode-skill-dir", path: overrideDir };
-        }
-        return { kind: "skill-dir", path: overrideDir };
+    if (agent === "summer") {
+        const root = scope === "user" ? homedir() : process.cwd();
+        return { kind: "skill-dir", path: overrideDir ?? join(root, ".summer", "skills") };
     }
-    const root = scope === "user" ? homedir() : process.cwd();
-    switch (agent) {
-        case "codex":
-            return { kind: "skill-dir", path: join(root, ".agents", "skills") };
-        case "claude-code":
-            return { kind: "skill-dir", path: join(root, ".claude", "skills") };
-        case "cursor":
-            return { kind: "cursor-rule-dir", path: join(root, ".cursor", "rules") };
-        case "windsurf":
-            return { kind: "windsurf-rule-file", path: join(root, ".windsurfrules") };
-        case "cline":
-            return {
-                kind: "cline-rule-dir",
-                path: scope === "user"
-                    ? clineUserRulesDir()
-                    : join(process.cwd(), ".clinerules"),
-            };
-        case "roo-code":
-            return {
-                kind: "cline-rule-dir",
-                path: scope === "user"
-                    ? rooCodeUserRulesDir()
-                    : join(process.cwd(), ".clinerules"),
-            };
-        case "kilo-code":
-            return {
-                kind: "cline-rule-dir",
-                path: scope === "user"
-                    ? join(homedir(), ".kilocode", "rules")
-                    : join(process.cwd(), ".kilocode", "rules"),
-            };
-        case "gemini":
-            // Gemini discovers extension skills from <extension>/skills/<name>/SKILL.md
-            // (geminicli.com/docs/extensions/reference), so copy the skill directories
-            // as-is. The extension dir itself is written by `summer setup gemini`.
-            return {
-                kind: "skill-dir",
-                path: join(homedir(), ".gemini", "extensions", "summer-engine", "skills"),
-            };
-        case "github-copilot":
-        case "vscode-copilot":
-            return {
-                kind: "skill-dir",
-                path: scope === "user"
-                    ? join(homedir(), ".copilot", "skills")
-                    : join(process.cwd(), ".github", "skills"),
-            };
-        case "opencode":
-            return {
-                kind: "opencode-skill-dir",
-                path: scope === "user"
-                    ? opencodeUserAgentsDir()
-                    : join(process.cwd(), ".opencode", "agents", "summer"),
-            };
-        case "summer":
-            return { kind: "skill-dir", path: join(root, ".summer", "skills") };
+    const spec = agentSpec(agent);
+    const resolved = resolveSkillPath(spec, scope, defaultPathContext());
+    if (!resolved) {
+        throw new Error(`${spec.label} has no skills folder. ${spec.noSkillsNote ?? ""}`.trim());
     }
-}
-function clineUserRulesDir() {
-    // Cline reads global rules from the user's Documents/Cline/Rules folder.
-    return join(homedir(), "Documents", "Cline", "Rules");
-}
-function rooCodeUserRulesDir() {
-    // Roo Code reads global rules from the user's Documents/Roo/Rules folder.
-    return join(homedir(), "Documents", "Roo", "Rules");
-}
-function opencodeUserAgentsDir() {
-    // OpenCode's user-scope agent definition directory varies by OS.
-    // On Windows, OpenCode reads from %APPDATA%/opencode/agents/summer.
-    // On Linux/macOS, it reads from $XDG_CONFIG_HOME or ~/.config/opencode/agents/summer.
-    if (platform() === "win32") {
-        const appData = process.env.APPDATA ?? join(homedir(), "AppData", "Roaming");
-        return join(appData, "opencode", "agents", "summer");
+    if (overrideDir) {
+        return {
+            kind: resolved.kind,
+            path: resolved.kind === "windsurf-rule-file" ? join(overrideDir, ".windsurfrules") : overrideDir,
+        };
     }
-    const xdg = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
-    return join(xdg, "opencode", "agents", "summer");
+    return { kind: resolved.kind, path: resolved.path };
 }
 /** One-line, human path pattern for where an install location puts skills. */
 export function describeInstallLocation(location) {

package/dist/installer/version-check.d.ts

@@ -11,6 +11,7 @@
  * Both are designed to be silent on offline / network errors — we never want
  * to false-alarm a user just because their wifi is flaky.
  */
+import { type McpFormat } from "./agent-table.js";
 import { type StdioMcpServerConfig } from "./agent-config.js";
 export interface SemverParts {
     major: number;
@@ -145,10 +146,13 @@ export declare function isLocalDevServerConfig(server: StdioMcpServerConfig): bo
  *   json-copilot   {"mcpServers": {"summer-engine": {type, command, args}}}
  *   json-vscode    {"servers":    {"summer-engine": {type, command, args}}}
  *   json-opencode  {"mcp":        {"summer-engine": {type, command: [cmd, ...args]}}}
+ *   json-zed       {"context_servers": {"summer-engine": {source, command, args}}}
+ *   yaml-goose     extensions: summer-engine: {cmd, args}
+ *   yaml-hermes    mcp_servers: summer-engine: {command, args}
  *   toml (codex)   [mcp_servers.summer-engine]\ncommand = "…"\nargs = ["…", …]
  * Returns null when the file is missing, unparsable, or has no Summer entry.
  */
-export declare function readRecordedMcpServer(text: string, format: "json" | "toml" | "json-opencode" | "json-copilot" | "json-vscode"): StdioMcpServerConfig | null;
+export declare function readRecordedMcpServer(text: string, format: McpFormat): StdioMcpServerConfig | null;
 /** Is the CLI running this check a source checkout rather than an installed
  *  package? npm/npx/global installs all live under a node_modules directory. */
 export declare function runningCliIsCheckout(packageRoot?: string): boolean;

package/dist/installer/version-check.js

@@ -12,10 +12,11 @@
  * to false-alarm a user just because their wifi is flaky.
  */
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir, platform } from "node:os";
+import { parse as parseYaml } from "yaml";
+import { allAgentSpecs, defaultPathContext, resolveSkillPath } from "./agent-table.js";
 import { join, sep } from "node:path";
 import { PACKAGE_ROOT } from "../core/package-root.js";
-import { configureAgentMcp, parseAgent, SUMMER_MCP_SERVER_NAME, } from "./agent-config.js";
+import { configureAgentMcp, parseAgent, SUMMER_MCP_SERVER_NAME, topLevelKey, } from "./agent-config.js";
 const NPM_REGISTRY_LATEST_URL = "https://registry.npmjs.org/summer-engine/latest";
 const REGISTRY_FETCH_TIMEOUT_MS = 3000;
 export function parseSemver(version) {
@@ -197,32 +198,17 @@ export function writeSkillMarker(dir, version, now = new Date()) {
     return path;
 }
 export function defaultSkillMarkerCandidates() {
-    const home = homedir();
+    const ctx = defaultPathContext();
     const candidates = [
-        { agent: "claude-code", dir: join(home, ".claude", "skills") },
-        { agent: "codex", dir: join(home, ".agents", "skills") },
-        { agent: "summer", dir: join(home, ".summer", "skills") },
-        { agent: "cline", dir: join(home, "Documents", "Cline", "Rules") },
-        { agent: "roo-code", dir: join(home, "Documents", "Roo", "Rules") },
-        {
-            agent: "gemini",
-            dir: join(home, ".gemini", "extensions", "summer-engine", "skills"),
-        },
+        { agent: "summer", dir: join(ctx.home, ".summer", "skills") },
     ];
-    // OpenCode user-scope agent dir is OS-dependent.
-    if (platform() === "win32") {
-        const appData = process.env.APPDATA ?? join(home, "AppData", "Roaming");
-        candidates.push({
-            agent: "opencode",
-            dir: join(appData, "opencode", "agents", "summer"),
-        });
-    }
-    else {
-        const xdg = process.env.XDG_CONFIG_HOME ?? join(home, ".config");
-        candidates.push({
-            agent: "opencode",
-            dir: join(xdg, "opencode", "agents", "summer"),
-        });
+    // Every agent with a user-scope skills home, from the one agent table.
+    // Devin Desktop's single rules file has no dir to mark; skip that kind.
+    for (const spec of allAgentSpecs()) {
+        const home = resolveSkillPath(spec, "user", ctx);
+        if (!home || home.kind === "windsurf-rule-file")
+            continue;
+        candidates.push({ agent: spec.id, dir: home.path });
     }
     return candidates;
 }
@@ -362,12 +348,29 @@ export function isLocalDevServerConfig(server) {
  *   json-copilot   {"mcpServers": {"summer-engine": {type, command, args}}}
  *   json-vscode    {"servers":    {"summer-engine": {type, command, args}}}
  *   json-opencode  {"mcp":        {"summer-engine": {type, command: [cmd, ...args]}}}
+ *   json-zed       {"context_servers": {"summer-engine": {source, command, args}}}
+ *   yaml-goose     extensions: summer-engine: {cmd, args}
+ *   yaml-hermes    mcp_servers: summer-engine: {command, args}
  *   toml (codex)   [mcp_servers.summer-engine]\ncommand = "…"\nargs = ["…", …]
  * Returns null when the file is missing, unparsable, or has no Summer entry.
  */
 export function readRecordedMcpServer(text, format) {
     if (!text.trim())
         return null;
+    if (format === "toml-array") {
+        const block = text.match(new RegExp(`^\\[\\[mcp_servers\\]\\]\\s*$([\\s\\S]*?)(?=^\\[|(?![\\s\\S]))`, "gm"));
+        for (const candidate of block ?? []) {
+            if (!new RegExp(`^name\\s*=\\s*"${SUMMER_MCP_SERVER_NAME}"`, "m").test(candidate))
+                continue;
+            const command = candidate.match(/^command\s*=\s*"((?:[^"\\]|\\.)*)"/m)?.[1];
+            const argsText = candidate.match(/^args\s*=\s*\[([^\]]*)\]/m)?.[1] ?? "";
+            if (!command)
+                return null;
+            const args = [...argsText.matchAll(/"((?:[^"\\]|\\.)*)"/g)].map((m) => m[1].replace(/\\(.)/g, "$1"));
+            return { command: command.replace(/\\(.)/g, "$1"), args };
+        }
+        return null;
+    }
     if (format === "toml") {
         const table = text.match(new RegExp(`^\\[mcp_servers\\.${SUMMER_MCP_SERVER_NAME.replace(/[-.]/g, "\\$&")}\\]\\s*$([\\s\\S]*?)(?=^\\[|(?![\\s\\S]))`, "m"));
         if (!table)
@@ -381,7 +384,7 @@ export function readRecordedMcpServer(text, format) {
     }
     let parsed;
     try {
-        parsed = JSON.parse(text);
+        parsed = format === "yaml-goose" || format === "yaml-hermes" ? parseYaml(text) : JSON.parse(text);
     }
     catch {
         return null;
@@ -389,7 +392,9 @@ export function readRecordedMcpServer(text, format) {
     if (!parsed || typeof parsed !== "object")
         return null;
     const root = parsed;
-    for (const container of ["mcpServers", "servers", "mcp"]) {
+    // The format's own key first, then the other shapes (a user may have moved to a newer file layout).
+    const containers = [topLevelKey(format), "mcpServers", "servers", "mcp", "context_servers", "extensions", "mcp_servers", "amp.mcpServers"];
+    for (const container of [...new Set(containers)]) {
         const servers = root[container];
         if (!servers || typeof servers !== "object")
             continue;
@@ -397,6 +402,11 @@ export function readRecordedMcpServer(text, format) {
         if (!entry || typeof entry !== "object")
             continue;
         const record = entry;
+        if (typeof record.cmd === "string") {
+            // Goose: { cmd, args }
+            const args = Array.isArray(record.args) ? record.args.filter((part) => typeof part === "string") : [];
+            return { command: record.cmd, args };
+        }
         if (Array.isArray(record.command)) {
             const [command, ...args] = record.command.filter((part) => typeof part === "string");
             return command ? { command, args } : null;

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.`, {