summer-engine 3.1.0 → 3.2.0

package/dist/cli/commands/skills.js

@@ -8,7 +8,7 @@ import { writeSkillMarker } from "../../installer/version-check.js";
 import { pruneRetiredSkills } from "../../installer/legacy-skills.js";
 import { resolveInstallLocation, resolveSkillAgent, resolveSkillScope, } from "../../installer/skill-locations.js";
 import { PACKAGE_ROOT } from "../../core/package-root.js";
-import { agentLabel as tableAgentLabel, agentSpec, defaultPathContext, legacyRuleFiles } from "../../installer/agent-table.js";
+import { agentLabel as tableAgentLabel, agentSpec, agentsSharingSkills, defaultPathContext, isSharedSkillsPath, legacyRuleFiles, legacySkillDirs, } from "../../installer/agent-table.js";
 import { TOOLKIT_VERSION as cliVersion } from "../../core/version.js";
 // Skill files live in library/skills/<slug>/ and are resolved through the
 // generated registry (registry/generated/skills-registry.json).
@@ -198,6 +198,14 @@ function printInstallSummary(count, agent, scope, location) {
     const reloadHint = agent === "summer" ? undefined : agentSpec(agent).skills?.reloadHint;
     if (location.kind === "skill-dir") {
         console.log(`${label} can read skills from ${tildeified}/<skill>/SKILL.md`);
+        if (isSharedSkillsPath(location.path)) {
+            const others = agentsSharingSkills(scope, defaultPathContext())
+                .map((spec) => spec.label)
+                .filter((name) => name !== label);
+            if (others.length > 0) {
+                console.log(`This is the shared agentskills.io folder; ${others.join(", ")} read it too, so they are covered by this install.`);
+            }
+        }
         if (reloadHint)
             console.log(reloadHint);
     }
@@ -306,13 +314,23 @@ skillsCommand
         // (Cursor, OpenCode): drop the rule files 3.0 wrote so the agent does not
         // load both for the same slug. Only files with Summer's own naming go.
         if (agent !== "summer" && !process.env.SUMMER_SKILLS_DIR) {
-            const legacy = legacyRuleFiles(agentSpec(agent), scope, defaultPathContext(), skills.map((skill) => skill.name)) ?? [];
+            const names = skills.map((skill) => skill.name);
+            const legacy = legacyRuleFiles(agentSpec(agent), scope, defaultPathContext(), names) ?? [];
             for (const file of legacy) {
                 if (!existsSync(file))
                     continue;
                 rmSync(file, { force: true });
                 console.log(`  Removed ${tildeify(file)} (rule file from Summer 3.0; now a skill)`);
             }
+            // 3.1.0 wrote skills into each agent's own folder; agents that read
+            // the shared ~/.agents/skills now install there. Drop Summer's copies
+            // (dirs with a SKILL.md and a library name) from the old folder.
+            for (const dir of legacySkillDirs(agentSpec(agent), scope, defaultPathContext(), names) ?? []) {
+                if (!existsSync(join(dir, "SKILL.md")))
+                    continue;
+                rmSync(dir, { recursive: true, force: true });
+                console.log(`  Removed ${tildeify(dir)} (moved to the shared skills folder)`);
+            }
         }
     }
     if (name && skills[0]?.status === "preview") {

package/dist/core/api-client.d.ts

@@ -96,6 +96,11 @@ export declare class EngineApiClient {
     getEngineCapabilities(): EngineCapabilities | undefined;
     /** Engine version string from the last health read, for skew messages. */
     getEngineVersion(): string | undefined;
+    /** Absolute project directory: the engine's own report from the last health
+     *  read (newer engines publish project_path), else the explicit --project
+     *  selection. Undefined when neither is known. Used for the bounded
+     *  res://.summer/shots/ folder the seeing tools keep on the local disk. */
+    getProjectRoot(): string | undefined;
     /** The projectIdHash this session is bound to (undefined if none was reported
      *  at connect — e.g. no project open yet). */
     getBoundProjectIdHash(): string | undefined;
@@ -168,11 +173,14 @@ export declare class EngineApiClient {
     getSceneState(scenePath?: string, options?: {
         depth?: number;
         limit?: number;
+        root?: string;
     }): Promise<unknown>;
     getProjectState(prefix?: string): Promise<unknown>;
     getDiagnostics(): Promise<unknown>;
     inspectNode(path: string): Promise<unknown>;
-    inspectResource(path: string): Promise<unknown>;
+    /** A resource a node of the edited scene holds (state:resource takes
+     *  nodePath + property; resource FILES go through the inspect-resource probe). */
+    inspectNodeResource(nodePath: string, property: string): Promise<unknown>;
     getScriptErrors(path: string): Promise<unknown>;
     play(scene?: string, determinism?: PlayDeterminism): Promise<unknown>;
     stop(): Promise<unknown>;

package/dist/core/api-client.js

@@ -6,6 +6,7 @@ import { checkEngineHealth, discoverRegistryConnection, engineNotRunningError, e
 import { asRecord, boolFrom, numberFrom, stringFrom } from "./util/json.js";
 import { classifyOpsResponse, pollOpToTerminal, } from "./async-op-lifecycle.js";
 import { pickPlayDeterminism } from "./capabilities/play-determinism.js";
+import { honestSceneReceipt } from "./capabilities/engine-receipt.js";
 function findSnapshotPayload(value) {
     const record = asRecord(value);
     if (!record)
@@ -180,6 +181,13 @@ export class EngineApiClient {
     getEngineVersion() {
         return this.lastHealth?.version;
     }
+    /** Absolute project directory: the engine's own report from the last health
+     *  read (newer engines publish project_path), else the explicit --project
+     *  selection. Undefined when neither is known. Used for the bounded
+     *  res://.summer/shots/ folder the seeing tools keep on the local disk. */
+    getProjectRoot() {
+        return this.lastHealth?.project_path ?? this.selection?.projectPath;
+    }
     /** The projectIdHash this session is bound to (undefined if none was reported
      *  at connect — e.g. no project open yet). */
     getBoundProjectIdHash() {
@@ -461,7 +469,9 @@ export class EngineApiClient {
         // different project (identity_mismatch, atomic — before any op applies).
         const merged = { ...(options ?? {}), ...this.identityOptions() };
         const body = Object.keys(merged).length ? { ops, options: merged } : { ops };
-        return this._requestQueued("POST", "/api/ops", body, timeoutMs);
+        // scenePersistence.persisted only means SaveScene ran; hand it out as
+        // `saved` (engine-receipt.ts honestSceneReceipt).
+        return honestSceneReceipt(await this._requestQueued("POST", "/api/ops", body, timeoutMs));
     }
     /**
      * Mutation path for MCP file tools. Unlike legacy executeOps callers, this
@@ -480,13 +490,16 @@ export class EngineApiClient {
         return this.request("GET", `/api/state/read-file?${query.toString()}`);
     }
     async getSceneState(scenePath, options) {
-        // depth/limit only take effect on targeted (scene=) reads: the engine
+        // depth/limit/root only take effect on targeted (scene=) reads: the engine
         // routes those through the live command queue and forwards every query
         // param into StateProvider::scene_state (tool_net_thread.cpp
         // _parse_state_args). An UNtargeted read is answered from a pre-published
         // snapshot built with the defaults (depth 2, limit 200) and its query
         // params are ignored — callers who need depth/limit must pass scenePath
         // (summer_get_scene_tree resolves the current scene path for this).
+        // `root` starts the walk at a scene-relative node path; a path the engine
+        // cannot resolve falls back to the scene root, so callers compare the
+        // returned data.path before trusting a rooted read.
         const parts = [];
         if (scenePath)
             parts.push(`scene=${encodeURIComponent(scenePath)}`);
@@ -494,6 +507,8 @@ export class EngineApiClient {
             parts.push(`depth=${options.depth}`);
         if (options?.limit !== undefined)
             parts.push(`limit=${options.limit}`);
+        if (options?.root !== undefined)
+            parts.push(`root=${encodeURIComponent(options.root)}`);
         const query = parts.length ? `?${parts.join("&")}` : "";
         return this.request("GET", `/api/state/scene${query}`);
     }
@@ -513,8 +528,10 @@ export class EngineApiClient {
     async inspectNode(path) {
         return this.request("GET", `/api/state/inspector?path=${encodeURIComponent(path)}`);
     }
-    async inspectResource(path) {
-        return this.request("GET", `/api/state/resource?path=${encodeURIComponent(path)}`);
+    /** A resource a node of the edited scene holds (state:resource takes
+     *  nodePath + property; resource FILES go through the inspect-resource probe). */
+    async inspectNodeResource(nodePath, property) {
+        return this.request("GET", `/api/state/resource?nodePath=${encodeURIComponent(nodePath)}&property=${encodeURIComponent(property)}`);
     }
     async getScriptErrors(path) {
         return this.request("GET", `/api/state/script-errors?path=${encodeURIComponent(path)}`);

package/dist/core/capabilities/agent-playbook.js

@@ -19,6 +19,14 @@ export function buildAgentPlaybook(options = {}) {
             "For lighting, mood, environment, or emissive materials, use summer_screenshot target:'scene' framing:'camera' — it renders through the scene's OWN camera with its REAL WorldEnvironment. The preset framings (iso/top/...) substitute a flat preview environment and CANNOT verify lighting.",
             "When executing multiple batches, screenshot between them — catch the wrong turn at batch 2, not batch 7.",
             "If something looks wrong in the screenshot or the diff, investigate and fix before proceeding. Do not stack more work on a broken base.",
+            "A game made from a planning board (the brief gives its project id): read the board with summer_get_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.",
+        ],
+        // ------------------------------------------------------------------
+        // SEEING — judge a 3D environment the way a player and an artist do.
+        // ------------------------------------------------------------------
+        seeing: [
+            "Environment work ('make it beautiful', level dressing, lighting passes): bookmark hero views with summer_frame_shot (establishing / eye_level / low_angle / detail / corridor; walls, or a camera behind a one-sided wall, reject a pose; props frame it), then after every change one summer_shot_sheet of those bookmarks (compare_previous:true for previous / now / difference; only it or update_previous:true replaces a bookmark's baseline), summer_debug_views on the weakest shot (lighting, unshaded, normals, overdraw, wireframe) and summer_zoom (region or mark N) into each problem. summer_frame_nodes fits nodes with the REAL environment. Images come back inline, one grid per call; the verifying-scenes skill carries the loop and the beauty rubric. Preview tools.",
+            "Before calling a 3D scene done: summer_scene_audit (read-only, one call, at most 5 KB) lists what a camera may miss — see-through gaps, floor holes, floating or clipping props, facing look items, UV stretch, z-fighting, lights — sorted by severity with the node path, world position, evidence and next tool. Look at every error and look item up close (render:'sheet', or summer_frame_nodes / summer_zoom) and decide facings yourself; the audit never auto-fixes. Preview tool.",
         ],
         // ------------------------------------------------------------------
         // LIBRARY FEEDBACK — report how the library entries you used worked out.
@@ -80,6 +88,28 @@ export function buildAgentPlaybook(options = {}) {
             },
         },
         // ------------------------------------------------------------------
+        // 3D PLACEMENT — question -> tool. These bounded spatial tools ship
+        // today; an agent that never hears of them falls back to hand math.
+        // ------------------------------------------------------------------
+        placement3d: {
+            first: "For any 3D placement (props, kit pieces, walls, ledges, alcoves), call summer_search_library and read skill/spatial-placement (and skill/world-building-3d) before placing. Observe first still applies: snapshot, then place, then verify.",
+            questionToTool: [
+                "'How big is this kit piece, where is its origin, which side is its back, where are its pipe ends?' -> summer_inspect_asset (measures the file without adding it to a scene). Measure every piece type before placing it; never guess facing.",
+                "'Place it at this pose' -> summer_instantiate_scene with position / rotation_degrees (one call per piece). Many pieces -> one summer_batch of InstantiateScene ops carrying position / rotation_degrees, with receipt:'summary'.",
+                "'Next module edge to edge, next storey on top' -> summer_place_adjacent. 'Mount it on the wall' -> summer_attach_to_surface (backAxis from summer_inspect_asset). 'Clamps every 0.45 m' -> summer_repeat_along. 'Pipe to pipe' -> summer_connect_ports.",
+                "'What surface is in front of this point?' -> summer_raycast. 'Gap or overlap between these two, is the facade front flush?' -> summer_measure.",
+                "'What is around it, which side is blocked, is it flush against the wall?' -> summer_starcast (read-only, 26 directional casts from one node's bounds: open|blocked per direction with distance and object, contact-or-overlap, grounded). Call it BEFORE and AFTER placing; pass directionSpace:'local' for rotated pieces, wall gaps and alcoves.",
+                "'Will it fit here?' -> summer_test_placement: ghost-test a candidate global pose for overlap and floor gap without moving anything. Use it before committing a pose in a tight or dense spot.",
+                "'Seat it on the floor, table or wall' -> summer_snap_to_surface: move along a ray to the first surface at a requested gap (default straight down).",
+                "'Line these up / space them evenly' -> summer_align_distribute_3d: align (min/center/max) or equal-space 2-16 pieces along one axis from their visible AABBs.",
+                "'Did exactly that change, and does it look right?' -> summer_world_snapshot before + summer_snapshot_diff after, then summer_screenshot.",
+                "'What is wrong with this scene, and where?' -> summer_scene_audit after each build stage (save first; it reads the saved file in a private copy, so the tab stays clean): see-through holes in facades, exposed band ends and seams, open duct or pipe ends, floor gaps, floating/sunken/clipping props, facing look items, UV stretch, z-fighting (with the axis to nudge), lights; every check works from geometry, engine data and materials, never names or kit metadata. At most 5 KB, sorted error/warn/look; page with offset, narrow with checks/root/min_severity, render:'sheet' frames the first 6. Frame every error and look item before calling the scene done; accept:[{key, reason}] the look items you judged fine so later audits hide them.",
+                "'Can the player get from A to B?' -> summer_navigation_probe (reachability on the scene's navigation map).",
+            ],
+            evidence: "physics evidence comes from colliders; visual_aabb is a broad-phase fallback for mesh-only geometry. Read the evidence field before trusting a contact or a gap.",
+            status: "skill/spatial-placement, skill/world-building-3d and summer_starcast / summer_test_placement / summer_snap_to_surface / summer_align_distribute_3d / summer_navigation_probe / summer_world_snapshot / summer_snapshot_diff / summer_inspect_asset / summer_place_adjacent / summer_attach_to_surface / summer_repeat_along / summer_connect_ports / summer_raycast / summer_measure / summer_scene_audit are preview: verify their receipts with a screenshot. An engine build that predates an op answers engine_lacks_op naming the fallback.",
+        },
+        // ------------------------------------------------------------------
         // PHYSICAL INVARIANTS — hold after EVERY placement/import.
         // ------------------------------------------------------------------
         physicalInvariants: [
@@ -96,6 +126,15 @@ export function buildAgentPlaybook(options = {}) {
             "Engine calls are cheap; YOUR context is not: prefer summer_world_snapshot + summer_snapshot_diff (compact, capped, fingerprinted) over repeated full-tree dumps.",
         ],
         // ------------------------------------------------------------------
+        // READ IN PARTS — a result too big for the host is a result you never see.
+        // ------------------------------------------------------------------
+        readingInParts: [
+            "summer_get_project_context is compact by default (project, scene path + sceneSummary, health summary, projectMemory, warnings). Add include:['scene_tree'] / ['capabilities'] / ['settings'] only when you need that block; `omitted` names what was left out.",
+            "summer_world_snapshot lists at most 200 nodes by default. Read one subtree with path_prefix ('House3', 'Lane2/Props'), narrow with classes and fields (['pos','aabb']), page with offset/next_offset; matched_counts counts the subtree's classes. counts and the snapshot_id diff baseline always cover the whole scene.",
+            "summer_inspect_node fields:['transform','global_transform','scene_file_path'] reads where a node is (locally and in the world) and which scene it instances in a few hundred bytes instead of about 5 KB.",
+            "Search, then read the part: summer_grep (regex over project files; context_lines, path, glob, max_results) finds the lines; summer_read_file then reads just that part — offset/limit for text (data.window.next_offset continues), json_path / keys / keys_only for JSON (e.g. json_path:'pieces', keys:['wall_*'] on a kit manifest).",
+        ],
+        // ------------------------------------------------------------------
         // Verification ladder (climb only as high as the change demands).
         // ------------------------------------------------------------------
         verificationLadder: {
@@ -156,6 +195,8 @@ export function buildAgentPlaybook(options = {}) {
             "For live scene hierarchy and inspector changes, prefer scene tools. Guarded text writes support .tscn/.tres, and the engine schedules editor reloads after they land.",
             "Write GDScript by default; use C# only if the project already uses it.",
             "Never remove multiple top-level nodes unless the user explicitly requests destructive edits.",
+            "summer_snap_to_surface lifts a prop that is sunk into its support and settles it (receipt.recovery); when it still fails, read blocking and next_step in the failure instead of guessing a new position.",
+            "To swap one piece for another use summer_replace_node: it keeps parent, index, name, transform and added children, and proves the swap from the saved file. Trust persisted:true only; failure_reason not_persisted means the editor shows a change the file does not hold.",
             "Never change priority: locked .summer memory, voice IDs, canon, or provider bindings without explicit user confirmation.",
         ],
         liveEngineFlow: [
@@ -175,6 +216,11 @@ export function buildAgentPlaybook(options = {}) {
             "SimulateInput (drive the RUNNING game — summer_play first): summer_batch ops:[{op:'SimulateInput', type:'action', action:'jump', pressed:true}], sent ALONE as the only op. failure_reason 'not_running' = start the game first; 'unsupported' = the running game build predates the handler — use RunVerification instead.",
             "SINGLE-OP CONTRACT: the engine rejects any multi-op batch containing SaveScene, InstantiateScene, ReplaceNode, SimulateInput, ViewportSnapshot, GameSnapshot, GetRuntimeSceneTree, GetRuntimeNode, the runtime-control ops (SetRuntimeProp, CallRuntimeMethod, SpawnRuntimeScene, FreeRuntimeNode, RuntimeAnimation, RuntimeAnimationTree, GetRuntimeBones, GamePause, GameStep, GameSpeed, SimulateInputScript, InputRecordStart, InputRecordStop, InputReplay, GameProbe), Run*/Import* or Git* ops (failure_reason 'unsupported_transport', nothing executes). summer_batch splits these into sequential requests for you; when composing raw batches keep them as their own call anyway.",
             "WriteFile and ReplaceText are rejected here by design — use summer_write_file / summer_replace_text so project identity, content guards and same-file ordering are enforced.",
+            "A raw ReplaceNode with scene is rejected here too: the engine op shows the new scene but saves the OLD scene reference. summer_replace_node does the swap with ops that persist and verifies the saved file (persisted:true, or failure_reason not_persisted).",
+            "A raw ConnectSignal is rejected here: the engine connects without CONNECT_PERSIST, so the saved scene never holds it. summer_connect_signal connects with the flag and verifies the [connection] line in the saved file.",
+            "ReparentNode in summer_batch keeps the moved node's subtree: the engine op re-owns only the moved node, so the tool re-owns each scene-owned descendant in place and verifies every moved node in the saved file (persisted:true / verified:true, or failure_reason not_persisted).",
+            "scenePersistence.saved only says the SaveScene ran. Trust verified:true, which a tool sets only after reading the saved file back.",
+            "Searching project files needs no raw op: summer_grep wraps the engine's Grep op and adds context lines and a result cap.",
             "You do not need an engine op to run a shell command: your own host already has a shell. The engine binary that runs project scripts is at OS.get_executable_path() (on macOS, /Applications/Summer.app/Contents/MacOS/Summer); see the summer-cli headless-scripting skill.",
             "These are runtime ops, not scene mutations — the batch undo group is a harmless no-op for them.",
         ],

package/dist/core/capabilities/audit/accept.d.ts

@@ -0,0 +1,55 @@
+import { type Severity } from "./args.js";
+import type { AuditIssue } from "./judge.js";
+export declare const ACCEPT_FILE: string;
+export declare const ACCEPT_MAX_ENTRIES = 500;
+export declare const ACCEPT_SCORE_CHANGE = 0.25;
+export interface AcceptEntry {
+    key: string;
+    scene: string;
+    reason: string;
+    check: string;
+    severity: Severity;
+    score: number;
+    why: string;
+    at: string;
+}
+export declare function issueKey(issue: Pick<AuditIssue, "check" | "path" | "pos">): string;
+export declare function validIssueKey(key: string): boolean;
+/** The file's entries (the kernel echoes the parsed file as result.accept). */
+export declare function parseAcceptFile(raw: unknown): AcceptEntry[];
+/** Why an accepted item shows again, or null while it still holds. */
+export declare function staleReason(entry: AcceptEntry, issue: AuditIssue): string | null;
+export interface AcceptOutcome {
+    /** The new file content (null: nothing to write). */
+    entries: AcceptEntry[] | null;
+    added: string[];
+    refused: Array<{
+        key: string;
+        why: string;
+    }>;
+}
+/** Merge accept requests for THIS run's issues into the file's entries. */
+export declare function mergeAccepts(existing: readonly AcceptEntry[], requests: ReadonlyArray<{
+    key: string;
+    reason: string;
+}>, issues: readonly AuditIssue[], scene: string, now?: Date): AcceptOutcome;
+export interface AcceptFilter {
+    shown: AuditIssue[];
+    accepted: Array<{
+        issue: AuditIssue;
+        entry: AcceptEntry;
+    }>;
+    stale: Array<{
+        issue: AuditIssue;
+        why: string;
+    }>;
+}
+/** Split issues into shown and accepted (stale entries show again). */
+export declare function applyAccepts(issues: readonly AuditIssue[], entries: readonly AcceptEntry[], scene: string): AcceptFilter;
+export declare class AcceptStoreError extends Error {
+    readonly reason: "no_project" | "unsafe_path";
+    constructor(reason: "no_project" | "unsafe_path", message: string);
+}
+/** Write the entries to <project>/.summer/audit-accept.json: refuses symlinks
+ *  at the folder and the file, writes a temp file and renames it. */
+export declare function writeAcceptFile(projectRoot: string | undefined, entries: readonly AcceptEntry[]): Promise<string>;

package/dist/core/capabilities/audit/accept.js

@@ -0,0 +1,147 @@
+/**
+ * Accepted audit items: res://.summer/audit-accept.json.
+ *
+ * Without it an agent re-judges the same look items (hidden contact faces,
+ * overlapping trim at an inside corner) on every audit. An agent that has
+ * looked at an item and judged it fine passes accept: [{key, reason}]; the
+ * MCP side writes the entry here (the kernel only reads it, and the audit
+ * writes nothing else), and later audits count the item but hide it until
+ * its evidence changes materially.
+ *
+ * - Key: check:path@x,y,z, the world position rounded to 0.1 m (node names
+ *   never contain ":" or "@"). A moved piece is a new item.
+ * - Evidence: the severity and the issue's magnitude (score) when accepted.
+ *   A higher severity, or a score that moves by more than 25% (and 0.005),
+ *   makes the entry stale: the item shows again, marked accept_stale.
+ * - Errors cannot be accepted. Entries are per scene; the file keeps the
+ *   newest 500.
+ */
+import { lstat, mkdir, rename, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { randomBytes } from "node:crypto";
+import { ISSUE_KEY_PATTERN } from "./args.js";
+export const ACCEPT_FILE = join(".summer", "audit-accept.json");
+export const ACCEPT_MAX_ENTRIES = 500;
+export const ACCEPT_SCORE_CHANGE = 0.25;
+const SEVERITY_RANK = { error: 0, warn: 1, look: 2 };
+const tenth = (n) => (Math.round(n * 10) / 10 || 0).toFixed(1).replace(/\.0$/, "");
+export function issueKey(issue) {
+    return `${issue.check}:${issue.path}@${issue.pos.map(tenth).join(",")}`;
+}
+export function validIssueKey(key) {
+    return ISSUE_KEY_PATTERN.test(key);
+}
+/** The file's entries (the kernel echoes the parsed file as result.accept). */
+export function parseAcceptFile(raw) {
+    const doc = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+    const list = Array.isArray(doc.entries) ? doc.entries : [];
+    const out = [];
+    for (const e of list.slice(0, ACCEPT_MAX_ENTRIES * 2)) {
+        if (!e || typeof e !== "object")
+            continue;
+        const r = e;
+        const severity = r.severity === "warn" || r.severity === "look" ? r.severity : null;
+        if (typeof r.key !== "string" || !validIssueKey(r.key) || typeof r.scene !== "string" || !severity)
+            continue;
+        out.push({
+            key: r.key,
+            scene: r.scene,
+            reason: String(r.reason ?? "").slice(0, 200),
+            check: String(r.check ?? r.key.split(":")[0]),
+            severity,
+            score: typeof r.score === "number" && Number.isFinite(r.score) ? r.score : 0,
+            why: String(r.why ?? "").slice(0, 160),
+            at: String(r.at ?? ""),
+        });
+    }
+    return out;
+}
+/** Why an accepted item shows again, or null while it still holds. */
+export function staleReason(entry, issue) {
+    if (SEVERITY_RANK[issue.severity] < SEVERITY_RANK[entry.severity])
+        return `severity rose from ${entry.severity} to ${issue.severity}`;
+    const delta = Math.abs(issue.score - entry.score);
+    if (delta > Math.max(ACCEPT_SCORE_CHANGE * Math.abs(entry.score), 0.005)) {
+        return `evidence changed: magnitude ${Math.round(entry.score * 1000) / 1000} -> ${Math.round(issue.score * 1000) / 1000}`;
+    }
+    return null;
+}
+/** Merge accept requests for THIS run's issues into the file's entries. */
+export function mergeAccepts(existing, requests, issues, scene, now = new Date()) {
+    if (!requests.length)
+        return { entries: null, added: [], refused: [] };
+    const byKey = new Map(issues.map((i) => [issueKey(i), i]));
+    const added = [];
+    const refused = [];
+    const fresh = [];
+    for (const req of requests) {
+        const issue = byKey.get(req.key);
+        if (!issue) {
+            refused.push({ key: req.key, why: "no issue with this key in this audit (keys change when a piece moves 5 cm or more)" });
+            continue;
+        }
+        if (issue.severity === "error") {
+            refused.push({ key: req.key, why: "errors cannot be accepted: fix it" });
+            continue;
+        }
+        fresh.push({ key: req.key, scene, reason: req.reason.trim().slice(0, 200), check: issue.check, severity: issue.severity, score: issue.score, why: issue.why.slice(0, 160), at: now.toISOString() });
+        added.push(req.key);
+    }
+    if (!fresh.length)
+        return { entries: null, added, refused };
+    const keep = existing.filter((e) => !(e.scene === scene && fresh.some((f) => f.key === e.key)));
+    const entries = [...keep, ...fresh].slice(-ACCEPT_MAX_ENTRIES);
+    return { entries, added, refused };
+}
+/** Split issues into shown and accepted (stale entries show again). */
+export function applyAccepts(issues, entries, scene) {
+    const mine = new Map(entries.filter((e) => e.scene === scene).map((e) => [e.key, e]));
+    const shown = [];
+    const accepted = [];
+    const stale = [];
+    for (const issue of issues) {
+        const entry = mine.get(issueKey(issue));
+        if (!entry || issue.severity === "error") {
+            shown.push(issue);
+            continue;
+        }
+        const why = staleReason(entry, issue);
+        if (why) {
+            stale.push({ issue, why });
+            shown.push(issue);
+        }
+        else {
+            accepted.push({ issue, entry });
+        }
+    }
+    return { shown, accepted, stale };
+}
+export class AcceptStoreError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "AcceptStoreError";
+    }
+}
+/** Write the entries to <project>/.summer/audit-accept.json: refuses symlinks
+ *  at the folder and the file, writes a temp file and renames it. */
+export async function writeAcceptFile(projectRoot, entries) {
+    if (!projectRoot || !isAbsolute(projectRoot) || !existsSync(join(projectRoot, "project.godot"))) {
+        throw new AcceptStoreError("no_project", "The project folder is not known to this session (no project.godot), so accepted items cannot be saved.");
+    }
+    const root = resolve(projectRoot);
+    const dir = join(root, ".summer");
+    await mkdir(dir, { recursive: true });
+    const dirInfo = await lstat(dir);
+    if (dirInfo.isSymbolicLink() || !dirInfo.isDirectory())
+        throw new AcceptStoreError("unsafe_path", `${dir} is not a real folder.`);
+    const file = join(root, ACCEPT_FILE);
+    if (existsSync(file) && (await lstat(file)).isSymbolicLink())
+        throw new AcceptStoreError("unsafe_path", `${file} is a symlink; refusing to write through it.`);
+    const tmp = `${file}.${randomBytes(6).toString("hex")}.tmp`;
+    await writeFile(tmp, JSON.stringify({ version: 1, note: "summer_scene_audit accepted items (written by accept:[{key, reason}])", entries }, null, 1));
+    await rename(tmp, file);
+    return file;
+}

package/dist/core/capabilities/audit/args.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Argument shape for summer_scene_audit — ONE copy for both faces (the MCP
+ * registration in src/mcp/tools/audit-tools.ts and `summer tool scene-audit`
+ * in tool-dispatch.ts). The descriptions are the docs agents read.
+ *
+ * Strings that name scene content are validated again in audit.ts with the
+ * seeing tools' strict patterns before anything is sent; they reach the
+ * engine only as JSON data in config.json, never as source.
+ */
+import { z } from "zod";
+export declare const AUDIT_CHECKS: readonly ["through_hole", "floor_gap", "floating", "sunken", "interpenetration", "exposed_edge", "open_fixture_end", "orientation", "uv_stretch", "duplicate", "z_fight", "depth_step", "lights", "transform", "resource"];
+export type AuditCheck = (typeof AUDIT_CHECKS)[number];
+export declare const SEVERITIES: readonly ["error", "warn", "look"];
+export type Severity = (typeof SEVERITIES)[number];
+export declare const AUDIT_DEFAULT_LIMIT = 15;
+export declare const AUDIT_MAX_LIMIT = 50;
+/** Editor time the checks may take before the slow ones stop early (partial). */
+export declare const AUDIT_DEFAULT_BUDGET_MS = 3000;
+export declare const AUDIT_MIN_BUDGET_MS = 250;
+export declare const AUDIT_MAX_BUDGET_MS = 60000;
+export declare const AUDIT_MAX_ACCEPT = 50;
+/** An issue key: check:node path@x,y,z (world position rounded to 0.1 m;
+ *  node names never contain ":" or "@"). */
+export declare const ISSUE_KEY_PATTERN: RegExp;
+export declare const sceneAuditShape: {
+    scenePath: z.ZodOptional<z.ZodString>;
+    checks: z.ZodOptional<z.ZodArray<z.ZodEnum<["through_hole", "floor_gap", "floating", "sunken", "interpenetration", "exposed_edge", "open_fixture_end", "orientation", "uv_stretch", "duplicate", "z_fight", "depth_step", "lights", "transform", "resource"]>, "many">>;
+    root: z.ZodOptional<z.ZodString>;
+    min_severity: z.ZodOptional<z.ZodEnum<["error", "warn", "look"]>>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    budget_ms: z.ZodOptional<z.ZodNumber>;
+    accept: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        reason: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        reason: string;
+        key: string;
+    }, {
+        reason: string;
+        key: string;
+    }>, "many">>;
+    show_accepted: z.ZodOptional<z.ZodBoolean>;
+    render: z.ZodOptional<z.ZodEnum<["sheet", "none"]>>;
+};
+export declare const sceneAuditArgsSchema: z.ZodObject<{
+    scenePath: z.ZodOptional<z.ZodString>;
+    checks: z.ZodOptional<z.ZodArray<z.ZodEnum<["through_hole", "floor_gap", "floating", "sunken", "interpenetration", "exposed_edge", "open_fixture_end", "orientation", "uv_stretch", "duplicate", "z_fight", "depth_step", "lights", "transform", "resource"]>, "many">>;
+    root: z.ZodOptional<z.ZodString>;
+    min_severity: z.ZodOptional<z.ZodEnum<["error", "warn", "look"]>>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    budget_ms: z.ZodOptional<z.ZodNumber>;
+    accept: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        reason: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        reason: string;
+        key: string;
+    }, {
+        reason: string;
+        key: string;
+    }>, "many">>;
+    show_accepted: z.ZodOptional<z.ZodBoolean>;
+    render: z.ZodOptional<z.ZodEnum<["sheet", "none"]>>;
+}, "strict", z.ZodTypeAny, {
+    limit?: number | undefined;
+    root?: string | undefined;
+    scenePath?: string | undefined;
+    accept?: {
+        reason: string;
+        key: string;
+    }[] | undefined;
+    render?: "none" | "sheet" | undefined;
+    checks?: ("through_hole" | "floor_gap" | "floating" | "sunken" | "interpenetration" | "exposed_edge" | "open_fixture_end" | "orientation" | "uv_stretch" | "duplicate" | "z_fight" | "depth_step" | "lights" | "transform" | "resource")[] | undefined;
+    min_severity?: "error" | "warn" | "look" | undefined;
+    offset?: number | undefined;
+    budget_ms?: number | undefined;
+    show_accepted?: boolean | undefined;
+}, {
+    limit?: number | undefined;
+    root?: string | undefined;
+    scenePath?: string | undefined;
+    accept?: {
+        reason: string;
+        key: string;
+    }[] | undefined;
+    render?: "none" | "sheet" | undefined;
+    checks?: ("through_hole" | "floor_gap" | "floating" | "sunken" | "interpenetration" | "exposed_edge" | "open_fixture_end" | "orientation" | "uv_stretch" | "duplicate" | "z_fight" | "depth_step" | "lights" | "transform" | "resource")[] | undefined;
+    min_severity?: "error" | "warn" | "look" | undefined;
+    offset?: number | undefined;
+    budget_ms?: number | undefined;
+    show_accepted?: boolean | undefined;
+}>;
+export type SceneAuditArgs = z.output<typeof sceneAuditArgsSchema>;

package/dist/core/capabilities/audit/args.js

@@ -0,0 +1,89 @@
+/**
+ * Argument shape for summer_scene_audit — ONE copy for both faces (the MCP
+ * registration in src/mcp/tools/audit-tools.ts and `summer tool scene-audit`
+ * in tool-dispatch.ts). The descriptions are the docs agents read.
+ *
+ * Strings that name scene content are validated again in audit.ts with the
+ * seeing tools' strict patterns before anything is sent; they reach the
+ * engine only as JSON data in config.json, never as source.
+ */
+import { z } from "zod";
+export const AUDIT_CHECKS = [
+    "through_hole",
+    "floor_gap",
+    "floating",
+    "sunken",
+    "interpenetration",
+    "exposed_edge",
+    "open_fixture_end",
+    "orientation",
+    "uv_stretch",
+    "duplicate",
+    "z_fight",
+    "depth_step",
+    "lights",
+    "transform",
+    "resource",
+];
+export const SEVERITIES = ["error", "warn", "look"];
+export const AUDIT_DEFAULT_LIMIT = 15;
+export const AUDIT_MAX_LIMIT = 50;
+/** Editor time the checks may take before the slow ones stop early (partial). */
+export const AUDIT_DEFAULT_BUDGET_MS = 3000;
+export const AUDIT_MIN_BUDGET_MS = 250;
+export const AUDIT_MAX_BUDGET_MS = 60000;
+export const AUDIT_MAX_ACCEPT = 50;
+/** An issue key: check:node path@x,y,z (world position rounded to 0.1 m;
+ *  node names never contain ":" or "@"). */
+export const ISSUE_KEY_PATTERN = /^[a-z_]{3,24}:[^:@\n\r"\\]{1,300}@-?\d+(?:\.\d)?,-?\d+(?:\.\d)?,-?\d+(?:\.\d)?$/;
+export const sceneAuditShape = {
+    scenePath: z
+        .string()
+        .optional()
+        .describe('Scene to audit, e.g. "res://levels/town.tscn" (the SAVED file). Omit for the scene open in the editor.'),
+    checks: z
+        .array(z.enum(AUDIT_CHECKS))
+        .min(1)
+        .max(AUDIT_CHECKS.length)
+        .optional()
+        .describe("Only these checks (default: all 15). through_hole, floor_gap, floating, sunken, interpenetration, exposed_edge, open_fixture_end, orientation, uv_stretch, duplicate, z_fight, depth_step, lights, transform, resource. Fewer checks run faster (duplicate, lights, transform and resource need no physics); rerun a check budget_ms left partial on its own."),
+    root: z
+        .string()
+        .optional()
+        .describe('Report only issues under this node (subtree), e.g. "Block3". The whole scene is still loaded so walls and floors outside it count as surroundings.'),
+    min_severity: z
+        .enum(SEVERITIES)
+        .optional()
+        .describe('"error" (only errors), "warn" (errors and warnings) or "look" (default: everything, including look items that only ask you to look).'),
+    offset: z.number().int().min(0).max(100000).optional().describe("Skip this many issues of the sorted, filtered list (paging; the result names the next offset)."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(AUDIT_MAX_LIMIT)
+        .optional()
+        .describe(`Issues per page (default ${AUDIT_DEFAULT_LIMIT}, max ${AUDIT_MAX_LIMIT}). The result is capped at 5 KB; a page that does not fit is cut and says so.`),
+    budget_ms: z
+        .number()
+        .int()
+        .min(AUDIT_MIN_BUDGET_MS)
+        .max(AUDIT_MAX_BUDGET_MS)
+        .optional()
+        .describe(`Editor time for the whole audit (default ${AUDIT_DEFAULT_BUDGET_MS} ms, ${AUDIT_MIN_BUDGET_MS}-${AUDIT_MAX_BUDGET_MS}). Each check gets a share weighted by its usual cost (unused time passes on); a check past its share stops and counts.<check>.partial gives the share it covered. Under load, rerun the partial checks with checks:[...] or a larger budget.`),
+    accept: z
+        .array(z
+        .object({
+        key: z.string().min(8).max(360).describe("The issue's key from a previous result (issues[].key)."),
+        reason: z.string().min(3).max(200).describe("Why it is fine, e.g. \"coplanar faces hidden behind a sign\"."),
+    })
+        .strict())
+        .max(AUDIT_MAX_ACCEPT)
+        .optional()
+        .describe(`Accept look or warn items you judged fine (up to ${AUDIT_MAX_ACCEPT} per call): [{key, reason}] with keys from this scene's issues. They are written to res://.summer/audit-accept.json (the only file the audit writes), then counted (counts.<check>.accepted) but hidden on every later audit, until their evidence changes materially (severity rises, or the measured size moves by over 25%): then they show again with accept_stale. Errors cannot be accepted.`),
+    show_accepted: z.boolean().optional().describe("List accepted items too (each with its accepted reason). Default false: hidden, only counted."),
+    render: z
+        .enum(["sheet", "none"])
+        .optional()
+        .describe('"sheet": also return ONE inline image of the first 6 issues of this page framed up close from their open side, each tile labelled with its issue number. Default "none" (no image).'),
+};
+export const sceneAuditArgsSchema = z.object(sceneAuditShape).strict();