summer-engine 3.1.0 → 3.2.0

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

@@ -15,6 +15,8 @@ export const READ_LIBRARY_DESCRIPTION = "Load one library entry by id (<kind>/<s
     "Skills: the SKILL.md body plus metadata (status, use_when, related) and how to invoke the skill in your host (bare slug). " +
     "Tools: how to call it (MCP name, `summer tool <slug> --args`, engine requirement, authority) plus the descriptor. " +
     "Templates: the pinned repo @ commit and tree digest (or built-in) and the `summer create <slug>` command. References: the markdown body. " +
+    "Linked files: a body ends with its relative links and the id that loads each; a file an entry links loads by <entry id>/<link as written> " +
+    "(e.g. skill/spatial-placement/references/kit-placement-tools.md), by the relative path alone when one entry ships it, inside library/ only. " +
     "part: 'skill' = body only, 'resource' = the resource.yaml descriptor only, 'all' (default) = both. " +
     "The LAST line of every load is the feedback footer `— entry_id: <id>@<content-hash>. If this entry is wrong, stale, or you deviate from it, report via summer_library_feedback.` " +
     "— copy that entry_id verbatim into summer_library_feedback once you have verified the outcome in-engine. " +

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

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { withEngine, missingEngineOpResult, withOldEngineHint } from "./with-engine.js";
 // engine_lacks_op fallbacks: ONE copy for every face (E2E 2026-09-03 F-16).
 import { RUNTIME_NODE_FALLBACK, RUNTIME_TREE_FALLBACK, SNAPSHOT_DIFF_FALLBACK, WORLD_SNAPSHOT_FALLBACK, } from "../../core/capabilities/engine-fallbacks.js";
+import { WORLD_SNAPSHOT_DEFAULT_MAX_NODES, buildWorldSnapshotOp, shapeWorldSnapshot, worldSnapshotInputShape, } from "../../core/capabilities/world-snapshot.js";
 /**
  * Perception tools. Two signals, two jobs: these ops return STRUCTURED state —
  * exact node paths, transforms, world AABBs, counts — while summer_screenshot
@@ -40,28 +41,14 @@ export function registerPerceptionTools(server) {
 
 THE LOOP: summer_world_snapshot (note snapshot_id) -> mutate (summer_run_script / scene tools / imports) -> summer_snapshot_diff from_id:<that id> -> summer_screenshot. The diff proves exactly what changed structurally; the screenshot proves it looks right. This is how you catch a node that silently vanished on save, a transform that landed at the origin, or an AABB clipping through the floor.
 
-Node lists are path-sorted and truncated DETERMINISTICALLY (result carries total_nodes + truncated) so two snapshots stay diffable without phantom adds/removes. The engine retains the last 8 snapshots per session, keyed by snapshot_id. Use this instead of summer_get_scene_tree when you need transforms/AABBs/fingerprints or a diffable baseline; the tree read remains the hierarchy-shaped view. On an engine build that predates GetWorldSnapshot the result is a structured engine_lacks_op failure naming the fallback.`, {
-        scene_path: z
-            .string()
-            .optional()
-            .describe("Scene to snapshot, e.g. 'res://main.tscn'. Omit for the currently edited scene."),
-        max_nodes: z
-            .number()
-            .int()
-            .positive()
-            .optional()
-            .describe("Node cap (engine default 4000). The result declares truncation — never assume a capped list is complete."),
-    }, async ({ scene_path, max_nodes }) => withEngine(async (client) => {
+Node lists are path-sorted and truncated DETERMINISTICALLY (result carries total_nodes + truncated) so two snapshots stay diffable without phantom adds/removes. The engine retains the last 8 snapshots per session, keyed by snapshot_id. Use this instead of summer_get_scene_tree when you need transforms/AABBs/fingerprints or a diffable baseline; the tree read remains the hierarchy-shaped view. On an engine build that predates GetWorldSnapshot the result is a structured engine_lacks_op failure naming the fallback.
+
+KEEP IT SMALL (about 250 bytes per node): at most ${WORLD_SNAPSHOT_DEFAULT_MAX_NODES} nodes are listed by default. path_prefix reads one subtree ('House3', 'Lane2/Props'), classes keeps some node classes, fields keeps some per-node fields (e.g. ['pos','aabb']), offset/next_offset page the list. A filtered read adds matched_nodes and matched_counts (class counts of the subtree). counts and total_nodes always describe the whole scene, and snapshot_id always covers the whole scene, so summer_snapshot_diff still sees every change.`, worldSnapshotInputShape, async (args) => withEngine(async (client) => {
         const missing = missingEngineOpResult(client, "GetWorldSnapshot", WORLD_SNAPSHOT_FALLBACK);
         if (missing)
             return missing;
-        const op = { op: "GetWorldSnapshot" };
-        if (scene_path)
-            op.scene_path = scene_path;
-        if (max_nodes !== undefined)
-            op.max_nodes = max_nodes;
-        const result = await client.executeOps([op]);
-        return withFailureReasonHint(withOldEngineHint(result, "GetWorldSnapshot", WORLD_SNAPSHOT_FALLBACK), {
+        const result = await client.executeOps([buildWorldSnapshotOp(args)]);
+        return withFailureReasonHint(withOldEngineHint(shapeWorldSnapshot(result, args), "GetWorldSnapshot", WORLD_SNAPSHOT_FALLBACK), {
             no_scene: "No scene is open to snapshot. Call summer_get_project_context, then summer_open_main_scene (or summer_open_scene with a known .tscn path), then retry.",
             scene_not_loaded: "scene_path resolves only a LIVE editor tab or an already-cached scene — never a disk load. Open that scene first (summer_open_scene), or omit scene_path to snapshot the currently edited scene.",
         });

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

@@ -0,0 +1,24 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type PlacementClient, type PlacementResult } from "../../core/capabilities/placement.js";
+type Content = {
+    type: "text";
+    text: string;
+};
+export declare function renderPlacementResult(body: PlacementResult | Record<string, unknown>): {
+    content: Content[];
+    isError?: true;
+};
+/** withEngine wrapper that renders the placement result verbatim. */
+export declare function runPlacement<T>(run: (client: PlacementClient, args: T) => Promise<PlacementResult>): (args: T) => Promise<{
+    content: ({
+        type: "text";
+        text: string;
+    } | {
+        type: "image";
+        data: string;
+        mimeType: string;
+    })[];
+    isError?: boolean;
+}>;
+export declare function registerPlacementTools(server: McpServer): void;
+export {};

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

@@ -0,0 +1,91 @@
+import { withEngine } from "./with-engine.js";
+import { attachToSurface, attachToSurfaceArgsSchema, connectPorts, connectPortsArgsSchema, inspectAsset, inspectAssetArgsSchema, measure, measureArgsSchema, placeAdjacent, placeAdjacentArgsSchema, raycast, raycastArgsSchema, repeatAlong, repeatAlongArgsSchema, } from "../../core/capabilities/placement.js";
+/**
+ * Kit-placement tools: measure an asset before instancing it, place pieces
+ * relative to each other, mount them on surfaces, repeat them along a line,
+ * join ports, and query the scene with arbitrary rays and per-axis measures.
+ *
+ * The implementations live in core/capabilities/placement.ts (shared with
+ * `summer tool <slug>`). They use only existing engine ops: the placement
+ * probe runs through RunSceneScript (read-only, undo "none", no checkpoint)
+ * and mutations are SetProp / SnapToSurface / InstantiateScene with the usual
+ * scene target, undo step and final SaveScene.
+ *
+ * Results are rendered here, not by withEngine's failure renderer: a placement
+ * failure carries structured fields (failure_reason, what already applied,
+ * the measured hit) that a plain error string would drop.
+ */
+const RESULT_LIMIT_BYTES = 5 * 1024;
+export function renderPlacementResult(body) {
+    let text = JSON.stringify(body);
+    if (Buffer.byteLength(text, "utf8") > RESULT_LIMIT_BYTES) {
+        text = JSON.stringify({
+            ok: false,
+            tool: body.tool,
+            failure_reason: "result_exceeded_byte_limit",
+            error: "The placement result was larger than 5 KB and was not forwarded. Narrow the request (fewer nodes or copies).",
+            ...(body.ok === true ? { mutationApplied: body.saved === true, retrySafe: false } : {}),
+        });
+        return { content: [{ type: "text", text }], isError: true };
+    }
+    return body.ok === true ? { content: [{ type: "text", text }] } : { content: [{ type: "text", text }], isError: true };
+}
+/** withEngine wrapper that renders the placement result verbatim. */
+export function runPlacement(run) {
+    return async (args) => withEngine(async (client) => ({ placementResult: await run(client, args) }), {
+        onResult: (wrapped) => renderPlacementResult(wrapped.placementResult),
+    });
+}
+export function registerPlacementTools(server) {
+    server.tool("summer_inspect_asset", `Measure a 3D asset file (.tscn/.scn/.glb/.gltf, or a Mesh resource) WITHOUT adding it to any scene: it is loaded and instanced off-scene in the editor, measured, and freed. Call it once per kit piece before placing it, instead of guessing size, origin or facing.
+
+Returns (all in the asset root's own frame, the frame position/rotation apply in), the facing evidence first:
+- summary {aabb, origin {fraction, label e.g. "x:center y:min z:min"}, plane_pairs, port_like_loops [loop ids], triangles, mesh_count, anchor_count, collision_count, warnings?}. plane_pairs: the 2 largest pairs of opposite planes (a pair under 1% of the largest one's area is left out), each {larger, opposite (null for a single sheet), separation}; every plane {axis (e.g. "+z", only when the normal is within about 1 degree of it), normal, offset, area, one_sided}. one_sided true = its material culls back faces, so the plane is invisible from behind its normal: a single sheet that is one_sided faces along its normal and its back is the opposite axis. An oblique normal (no axis) means a baked yaw or a 45-degree corner face. warnings says when the triangle budget cut the analysis and which maxTriangles covers the whole mesh
+- aabb, origin, meshes [{path, tris, min, max}], triangles total
+- planes: the 6 largest planar face groups {normal, offset, area, tris, cull_back, one_sided}; normals follow the triangle winding (outward faces). You decide the front; the tool does not label facing
+- open_loops: open boundary loops {id, index, mesh, center, direction (outward), radius, vertices, max_dev} in a stable order: grouped by the piece axis the direction is nearest (+X, -X, +Y, -Y, +Z, -Z; ~X/~Y/~Z when undecided), the outermost along that axis first, then by centre; never by radius. id names the loop by that order: "+Y" is the outermost loop facing +Y, "+Y#2" the next. summer_connect_ports accepts the id (or the index); the same id names the same loop on the placed node in any pose. detail "summary" (default) lists only port-like loops (radius over 2 cm with a partner loop facing more than 60 degrees away: the ends of a pipe, duct or bend; or the one opening of an end piece, such as an outlet's socket, on its bounding-box face) and says how many it omitted; detail "full" lists every loop, including the outline of flat sheets
+- anchors: Marker3D nodes {name, path, position, forward (-Z), up}
+- collision: CollisionShape3D nodes {path, shape, size/radius/height/faces, center, min, max}
+- analysis {triangles_analyzed, triangle_budget, truncated}; a "truncated" object when a list was cut to fit 5 KB
+
+maxTriangles 100-300000 (default 60000). Evidence is mesh_triangles. Uses the existing RunSceneScript op (in the live editor, read-only); an engine without it answers engine_lacks_op.`, inspectAssetArgsSchema.shape, runPlacement(inspectAsset));
+    server.tool("summer_place_adjacent", `Move one node so its bounds face sits against another node's bounds face along one axis: facade modules edge to edge, a storey stacked on the one below, a cornice on a wall. Optionally line up the other two axes (min, center or max), per axis.
+
+Example: next module to the right, same base height, same front plane: {axis:"x", side:"max", gap:0, alignOtherAxes:{y:"min", z:"max"}}.
+
+Bounds are the visible GeometryInstance3D AABBs (the definition summer_align_distribute_3d uses; evidence visual_aabb). space "local" uses the reference's own axes for rotated facades. When the subject is inside the reference, its geometry is left out of the reference's bounds. One SetProp on position, one undo step, then the scene is saved; a fresh read verifies the achieved gap and residuals (verify). Returns {moved_by, position, verify:{gap, residuals}}. The scene must be open in the editor (any tab).`, placeAdjacentArgsSchema.shape, runPlacement(placeAdjacent));
+    server.tool("summer_attach_to_surface", `Mount a piece on a surface: turn it so its given LOCAL backAxis faces into the surface (opposite the hit normal) with its upAxis kept toward worldUp, then seat its measured back face (the extreme of its visible bounds along backAxis, not its origin) at standoff from the surface. Pipes, gutters, lamps, AC units, signs, fire escapes. Place the piece near its mount first (summer_instantiate_scene with position); this tool turns it and pushes it onto the surface.
+
+Find the surface with surface (a node: the ray runs from the subject's origin to the nearest point of that node's bounds) or ray {origin, direction} (both: the ray, and hits on other nodes are skipped). The ray is physics first; if physics finds nothing it falls back to visual AABBs and says so (the normal is then an AABB face normal). Get backAxis from summer_inspect_asset (the piece's back plane normal), not from a guess.
+
+placeAt "current" (default): the piece keeps its height and its place along the surface and only moves along the surface normal. placeAt "hit": it also slides so the centre of its back face lands on the ray hit point.
+
+Steps (existing ops): a read-only probe (RunSceneScript) reads the piece's bounds in its own axes and casts the ray; one SetProp turns the piece and puts its back face 5 cm in front of the planned seat; SnapToSurface sweeps it along -normal (at most standoff + 0.3) and seats it at standoff (its own physics/visual_aabb evidence). Before saving, the seat is checked:
+- with surface: the seat must be on that node (or inside it), else it is refused;
+- with a ray only: a seat on another node is refused unless it lies on the hit plane (a coplanar neighbour module, warned);
+- the piece must end within maxMove (default 2) of where it started; a longer planned move is refused before anything changes, and so is (with placeAt "current") a ray hit farther than maxMove along the surface from the piece (hit_far_from_piece: aim at the piece, or pass placeAt "hit").
+A refused or failed seat puts the piece back where it started (restored: true), saves nothing, and names the cause: seated_on, the seat's failure_reason, blockers {overlapping, overlaps, first_contact} and a next_step.
+
+Returns {seated_on, final_gap (collider gap from SnapToSurface), back_face_gap (visible back face to the hit plane), moved_by, surface_hit, orientation, back_face_offset, seat {evidence, supportPath, finalGap, gapErrorBound, initiallyOverlapping, ...}, saved, warnings}. A warning visible_back_X_into_surface means the piece's collider sits behind its visible back: add X to standoff.`, attachToSurfaceArgsSchema.shape, runPlacement(attachToSurface));
+    server.tool("summer_repeat_along", `Instance copies of one scene along a straight line in one call: wall clamps every 0.45 m, braces every 0.8 m, fence posts, a row of window modules. Give start plus end (with spacing or count) or start plus direction (with count and spacing); positions are in the parent's local space. align (start|center|end) places the leftover length when spacing does not divide the line. Each copy is an InstantiateScene (the engine runs each alone), named <namePrefix>_<n>; the copies' transforms (position, rotationDegrees, scale) are then set in one request and the scene is saved once: N copies cost N + 2 engine requests. At most 64 copies per call.
+
+Returns a compact receipt: {count, spacing, first, last, created [node paths], renamed, failures [{index, error}], saved}. Lists are cut to stay under 5 KB and the cut is declared.`, repeatAlongArgsSchema.shape, runPlacement(repeatAlong));
+    server.tool("summer_connect_ports", `Move and turn one piece so its port meets another piece's port, facing it: pipe to pipe, duct to duct, gutter section to funnel or outlet. A port is an open-loop id from summer_inspect_asset on that node's scene ("+Y" = the outermost open loop facing +Y in the piece's own axes, "+Y#2" the next one facing +Y; resolved on the live node's meshes in its own frame, so the id is the same in every pose), a Marker3D (or any Node3D) name under the node whose -Z axis points out of the port, or an open-loop index in the same stable order.
+
+The subject turns by the shortest rotation that makes its port direction opposite the target's, then by rollDegrees about the joined axis, then moves so the ports coincide (gap along the target port's direction). rollDegrees: axis = roll_axis in the receipt (the target port direction reversed, pointing into the target); right-hand rule, positive = counter-clockwise seen from inside the target looking back at the subject; zero = the shortest turn from the subject's CURRENT orientation, so the same value differs between start poses. Once the ports are joined, a second call turns by exactly rollDegrees (180 flips a bend's free end to the other side).
+
+Tilt guard: a join that would tilt the subject's up axis (its local +Y) more than maxTiltDegrees (default 5) is refused before anything changes (failure_reason tilt_exceeds_limit, with tilt_degrees and ports_within_limit: the subject ports that would join within the limit, least tilt first). Turning about the up axis is never tilt. Pass allowTilt true for an intended tilt (a bend laid on its side).
+
+One SetProp on transform, saved; a fresh read verifies {distance, angle_degrees, tilt_degrees}. Returns {subject_port {kind, id|name, index, position, direction, radius}, target_port, roll_axis, roll_degrees, rotated_degrees, tilt_degrees, max_tilt_degrees, moved_by, other_ports, verify, warnings}. other_ports: every other port of the subject (its other Marker3D anchors, or its other open loops for an open-loop port) with world position and outward direction AFTER the move, measured by the verify read: read where a bend's free end now points instead of measuring it. Open-loop ports are only as exact as the mesh: check direction_ambiguous warnings and a screenshot.`, connectPortsArgsSchema.shape, runPlacement(connectPorts));
+    server.tool("summer_raycast", `Cast one ray from any point in an open scene, before anything is placed there: find the wall, floor or ceiling in front of a point and its normal. (summer_starcast casts from an existing node's bounds; this casts from an arbitrary origin.)
+
+evidence auto (default): physics first (collider hit: exact point and normal); if physics hits nothing, the nearest visible-mesh AABB hit, declared with fallback:true and fallback_reason. Physics needs the scene to be the active editor tab (only that scene's bodies are in the editor's physics space); otherwise auto falls back to visual AABBs. When physics hits but a mesh-only object is nearer, nearer_visual_only names it.
+
+Returns {hit, evidence, path, point, normal, distance, origin, direction, physics_available, warnings}. Read-only (RunSceneScript probe, undo "none"); never saves.`, raycastArgsSchema.shape, runPlacement(raycast));
+    server.tool("summer_measure", `Measure placement between specific nodes from their visible-mesh bounds (evidence visual_aabb). Read-only, never saves. Complements summer_starcast (which reports clearance around ONE node in 26 directions).
+
+mode pair (a, b): per axis {gap (> 0 clearance, < 0 overlap depth), relation gap|touching|overlap, a/b intervals, delta_min/max/center (b minus a)} and boxes_overlap. Catches facade gaps and modules that overlap.
+mode plane (nodes, face): whether that face of every node lies on one plane: {coplanar, plane (median), spread, nodes [{path, face, deviation, off_plane: proud|recessed}]}. Catches modules standing proud of a facade line. face '+z' = the face pointing along +z.
+
+space "local" measures along the axes of a (pair) or nodes[0] (plane), for rotated facades. tolerance (default 5 mm) decides touching / coplanar.`, measureArgsSchema.shape, runPlacement(measure));
+}

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

@@ -119,26 +119,29 @@ ladder, honesty rules, anti-patterns, and recovery steps.`, {}, async () => ({
             },
         ],
     }));
-    server.tool("summer_get_project_context", `Get essential project context before editing. Returns:
-- engine health/status
-- project name and project path when exposed by project state
-- current scene path (if available)
-- main scene path from project settings
+    server.tool("summer_get_project_context", `Get essential project context before editing. The default payload is COMPACT (a few KB):
+- project name and project path, current scene path, main scene path
+- sceneSummary: the open scene's root node and node count (not its tree)
+- health: the engine's scalar status fields plus capability COUNTS
 - projectMemory: the .summer summary — GameSoul/build-plan/memory files and
   \`pin\` (.summer/project.json: which template at which commit started this
   project, toolkit version, created_at)
-- capabilitySkewWarning (only when the engine build and this CLI have drifted
-  apart — non-fatal; explains upcoming 'unknown op' failures)
+- warnings: capabilitySkewWarning (only when the engine build and this CLI
+  have drifted apart — non-fatal; explains upcoming 'unknown op' failures),
+  rebindError, summerUpdateNotice
+- omitted: how to ask for each heavy block that was left out
 
-Use this first in every fresh chat to avoid guessing scene filenames or editing the wrong scene.
+Use this first in every fresh chat to avoid guessing scene filenames or editing the wrong scene. It also binds the session to the open project.
 
-Project settings in project.data.entries are trimmed to the curated default
-groups (application/, display/window/, the project's input/ actions, default
-gravity, rendering/renderer/, the 2D default texture filter) to bound payload
-size — the untrimmed dump is ~1000 entries. The payload declares the trim
-(settingsTruncated, totalSettings, settingsPrefixesIncluded,
-settingsPrefixesExcluded). Pass settingsPrefixes (e.g. ["audio/",
-"layer_names/"]) or settingsPrefix to read other groups instead.`, projectContextInputShape, async (args) => withEngine(async (client) => 
+Heavy blocks are opt-in with include: 'scene_tree' (the open scene's tree, up
+to 200 nodes; for one subtree prefer summer_world_snapshot path_prefix),
+'capabilities' (the engine's full op lists), 'settings' (project settings in
+project.data.entries, trimmed to the curated default groups: application/,
+display/window/, the project's input/ actions, default gravity,
+rendering/renderer/, the 2D default texture filter; the trim is declared in
+settingsTruncated / totalSettings / settingsPrefixesIncluded /
+settingsPrefixesExcluded). settingsPrefixes (e.g. ["audio/", "layer_names/"])
+or settingsPrefix read other settings groups and imply 'settings'.`, projectContextInputShape, async (args) => withEngine(async (client) => 
     // ONE builder for both faces (core/capabilities/project-context.ts);
     // the MCP surface contributes the boot drift notice it owns and logs
     // a capability skew once per process.

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

@@ -1,7 +1,12 @@
 import { z } from "zod";
 import { withEngine, ToolInputError } from "./with-engine.js";
-import { executeOpsChunked, executeSceneMutation } from "../../core/capabilities/engine-ops.js";
-import { annotateVariantTypes } from "../../core/capabilities/variant-types.js";
+import { executeSceneMutation } from "../../core/capabilities/engine-ops.js";
+import { instantiateScene, runBatch } from "../../core/capabilities/placement-batch.js";
+import { renderPlacementResult } from "./placement-tools.js";
+import { inspectNodeFields, inspectNodeInputShape } from "../../core/capabilities/inspect-node.js";
+import { inspectResource, inspectResourceInputShape } from "../../core/capabilities/inspect-resource.js";
+import { rawSceneReplaceRefusal, replaceNodeInputShape, replaceNodePersisted, } from "../../core/capabilities/replace-node.js";
+import { connectSignalInputShape, connectSignalPersisted } from "../../core/capabilities/connect-signal.js";
 import { FALLBACK_SINGLE_ONLY_OPS, resolveSingleOnlyOps, } from "../../core/capability-skew.js";
 // Re-exported for tests and for callers that reason about dispatch classes.
 // executeSceneMutation is the ONE copy in core/capabilities/engine-ops.ts,
@@ -28,6 +33,8 @@ function requireSuccessfulOps(result, context) {
 function minimalSceneText(rootName, rootType) {
     return `[gd_scene format=3]\n\n[node name="${rootName}" type="${rootType}"]\n`;
 }
+const finiteNumber = z.number().finite();
+const finiteVector3 = z.tuple([finiteNumber, finiteNumber, finiteNumber]);
 // Node names reject . : @ / " %; the type must be a plain class name.
 // Both are interpolated into quoted .tscn fields, so validate before composing.
 const VALID_ROOT_NAME = /^[A-Za-z_][A-Za-z0-9_\- ]*$/;
@@ -194,7 +201,9 @@ Do not guess paths. Prefer:
 
 The scene must already exist in the project. Use summer_import_from_url first if importing from external sources.
 
-PASS target_size FOR IMPORTED MODELS. Downloaded/generated .glb assets arrive at arbitrary scale (a "chair" can be 40 units tall). target_size uniformly scales the instanced subtree so its largest world-AABB dimension equals that many units — commit to real-world size: chair 1.0, door 2.0, car 4.5, person 1.7, tree 6-10. The result then reports dimensions + scale_applied; verify placement afterwards (summer_world_snapshot AABBs, summer_screenshot). Older engine builds ignore target_size — when the result lacks scale_applied, this tool appends a note and you must scale the node yourself (summer_set_prop scale) and re-check.`, {
+PASS target_size FOR IMPORTED MODELS. Downloaded/generated .glb assets arrive at arbitrary scale (a "chair" can be 40 units tall). target_size uniformly scales the instanced subtree so its largest world-AABB dimension equals that many units — commit to real-world size: chair 1.0, door 2.0, car 4.5, person 1.7, tree 6-10. The result then reports dimensions + scale_applied; verify placement afterwards (summer_world_snapshot AABBs, summer_screenshot). Older engine builds ignore target_size — when the result lacks scale_applied, this tool appends a note and you must scale the node yourself (summer_set_prop scale) and re-check.
+
+PLACE IT IN THE SAME CALL: position, rotation_degrees and scale ([x, y, z], parent-local, like summer_set_prop), or transform (a "Transform3D(...)" string). The instance is created, then those properties are set on the exact node path the receipt reports (a name collision rename is followed), then the scene is saved: one call per piece, no window at the origin. The result adds placement {nodePath, applied, fields}. Do not combine transform with the others, or scale/transform with target_size. Measure a kit piece first with summer_inspect_asset.`, {
         scenePath: z.string().describe("Target scene to receive the instance, e.g. 'res://main.tscn'"),
         parent: z.string().describe("Parent node path, e.g. './World'"),
         scene: z.string().describe("Scene/model path, e.g. 'res://player.tscn' or 'res://models/tree.glb'"),
@@ -204,30 +213,18 @@ PASS target_size FOR IMPORTED MODELS. Downloaded/generated .glb assets arrive at
             .positive()
             .optional()
             .describe("Normalize the instance's physical size: uniformly scale it so its largest world-AABB dimension equals this many units (chair 1.0, car 4.5, person 1.7). Strongly recommended for imported .glb/.gltf models."),
-    }, async ({ scenePath, parent, scene, name, target_size }) => withEngine(async (client) => {
-        const op = { op: "InstantiateScene", parent, scene };
-        if (name)
-            op.name = name;
-        if (target_size !== undefined)
-            op.target_size = target_size;
-        const result = await executeSceneMutation(client, scenePath, [op]);
-        // An older engine applies the op but silently drops target_size — its
-        // receipt then lacks scale_applied. Confess that instead of letting a
-        // 40-unit "chair" pass as normalized.
-        if (target_size !== undefined && result && typeof result === "object") {
-            const envelope = result;
-            const instanced = envelope.results?.find((entry) => entry.op === "InstantiateScene" && entry.ok === true);
-            if (instanced && !("scale_applied" in instanced)) {
-                return {
-                    ...envelope,
-                    target_size_note: `This Summer Engine build IGNORED target_size (no scale_applied in the receipt) — the instance is at the asset's raw scale, NOT normalized to ${target_size}. ` +
-                        "Scale it yourself (summer_set_prop scale, or ctx code in summer_run_script), verify with summer_world_snapshot/summer_screenshot, or update Summer Engine.",
-                };
-            }
-        }
-        return result;
-    }));
-    server.tool("summer_connect_signal", `Connect a signal between two nodes. Signals are Godot's event system — they notify when something happens.
+        position: finiteVector3.optional().describe("Parent-local position [x, y, z] set right after the instance is created."),
+        rotation_degrees: finiteVector3.optional().describe("Parent-local rotation in degrees [x, y, z] (Godot rotation_degrees)."),
+        scale: finiteVector3.optional().describe("Local scale [x, y, z]. Not with target_size."),
+        transform: z
+            .string()
+            .optional()
+            .describe('Full local transform as "Transform3D(xx, xy, xz, yx, yy, yz, zx, zy, zz, ox, oy, oz)" (Godot row-major basis, then origin). Not with position/rotation_degrees/scale/target_size.'),
+    }, async (args) => 
+    // E2E: an older engine applies the op but silently drops target_size —
+    // instantiateScene appends target_size_note when scale_applied is absent.
+    withEngine(async (client) => instantiateScene(client, args)));
+    server.tool("summer_connect_signal", `Connect a signal between two nodes so the connection is SAVED in the scene. Signals are Godot's event system — they notify when something happens.
 
 Common signals:
 - "body_entered" / "body_exited" — Area3D/Area2D detects physics bodies
@@ -236,15 +233,9 @@ Common signals:
 - "area_entered" — Area detects another area
 - "input_event" — CollisionObject received input
 
-The receiver node must have a script with the specified method.`, {
-        scenePath: z.string().describe("Target scene path, e.g. 'res://main.tscn'"),
-        emitter: z.string().describe("Node that fires the signal, e.g. './Player/HitArea'"),
-        signal: z.string().describe("Signal name, e.g. 'body_entered'"),
-        receiver: z.string().describe("Node with the handler script, e.g. './Player'"),
-        method: z.string().describe("Method name in the receiver's script, e.g. '_on_hit_area_body_entered'"),
-    }, async ({ scenePath, emitter, signal, receiver, method }) => withEngine(async (client) => executeSceneMutation(client, scenePath, [
-        { op: "ConnectSignal", emitter, signal, receiver, method },
-    ])));
+The receiver should have the method (a script method, or a built-in such as queue_free); a missing one is saved anyway and reported in warnings. scenePath must be a .tscn.
+
+PERSISTENCE IS VERIFIED: the engine's ConnectSignal op connects without CONNECT_PERSIST, so its connection never reached the file. This tool connects through a RunSceneScript probe with CONNECT_PERSIST (replacing a non-persistent connection of the same pair), saves, reads the saved .tscn back and returns persisted:true / verified:true only when the [connection] line is there; otherwise an error with failure_reason not_persisted. The probe runs in the active tab: a scene in a background tab is brought forward and the user's tab restored (tab_switched). One Ctrl+Z reverts it.`, connectSignalInputShape, async (args) => withEngine(async (client) => connectSignalPersisted(client, args)));
     server.tool("summer_select_node", "Select a node in the editor's scene tree and show it in the inspector panel. Useful for focusing the editor on a specific node.", {
         nodePath: z.string().describe("Node path to select"),
         scenePath: z.string().optional().describe("Open this scene first, then select the node"),
@@ -254,35 +245,29 @@ The receiver node must have a script with the specified method.`, {
             op.scenePath = scenePath;
         return client.executeOps([op]);
     }));
-    server.tool("summer_replace_node", "Replace a node with a different type or scene, preserving its position in the tree and its children. Useful for changing a StaticBody3D to a RigidBody3D, or swapping a placeholder with a proper prefab.", {
-        scenePath: z.string().describe("Target scene path, e.g. 'res://main.tscn'"),
-        path: z.string().describe("Node path to replace"),
-        type: z.string().optional().describe("New node type, e.g. 'RigidBody3D'"),
-        scene: z.string().optional().describe("Scene to replace with, e.g. 'res://enemies/boss.tscn'"),
-    }, async ({ scenePath, path, type, scene }) => withEngine(async (client) => {
-        const op = { op: "ReplaceNode", path };
-        if (type)
-            op.type = type;
-        if (scene)
-            op.scene = scene;
-        return executeSceneMutation(client, scenePath, [op]);
-    }));
+    server.tool("summer_replace_node", `Replace a node with a different scene/model or node type, keeping its parent, sibling index, name, transform and property overrides, and the children the scene added under it. Use it to swap a kit piece for another (a wall host for a door host), a placeholder for a prefab, or a StaticBody3D for a RigidBody3D.
+
+Give exactly one of scene or type. The scenePath must be a .tscn.
+
+PERSISTENCE IS VERIFIED: the tool saves, reads the saved .tscn back and checks that the node at path now instances the new scene (or has the new type), under the same parent, with every child present. persisted:true is proven from the file; a mismatch is an error with failure_reason not_persisted — never report that as done.
+
+How: a scene swap runs as InstantiateScene (temporary name) -> SetProp each property override -> ReparentNode the children -> MoveNode to the old index -> RemoveNode the old node -> rename -> SaveScene, because the engine's own ReplaceNode keeps the OLD scene reference in the saved file. A type change of a plain node uses the engine's ReplaceNode. State that cannot travel (groups, signal connections, scene-local sub_resource values, overrides of nodes inside the old scene) is listed in not_carried_over. Undo takes one Ctrl+Z per step.`, replaceNodeInputShape, async (args) => withEngine(async (client) => replaceNodePersisted(client, args)));
     server.tool("summer_inspect_node", `Get all editable properties of a node with their current values, types, and resource info.
 
 Call this before modifying a node to understand its current state. Returns every property the Godot inspector would show. Each prop carries the engine's raw Variant.Type integer as "type" plus its name as "type_name" (e.g. type 5 = TYPE_VECTOR2, 20 = TYPE_COLOR, 24 = TYPE_OBJECT); resource-valued props also carry resource_type / resource_path.
 
 Reads the currently OPEN scene — "path" is relative to its root (there is no scenePath argument; open the scene first if needed).
 
-Example: inspect a light to see its energy, color, shadow settings before changing them.`, {
-        path: z.string().describe("Node path from scene tree, e.g. 'Player', 'World/Enemies/Boss', 'DirectionalLight3D'"),
-    }, async ({ path }) => 
+Example: inspect a light to see its energy, color, shadow settings before changing them.
+
+The full read is about 5 KB. To read only what you need, pass fields: property names or globs ('position', 'surface_material_override/*'), plus derived fields: transform (local position / rotation_degrees / scale, and a Transform3D literal for 3D nodes), global_transform (world origin + Transform3D, composed from the world snapshot), scene_file_path (the scene this node instances), aabb (world bounds), warnings. Example: fields:['transform','global_transform','scene_file_path'] is a few hundred bytes. missing_fields and unavailable say what could not be read.`, inspectNodeInputShape, async (args) => 
     // E2E 2026-09-03 F-14: the engine returns Variant.Type as a bare int.
-    withEngine(async (client) => annotateVariantTypes(await client.inspectNode(path))));
-    server.tool("summer_inspect_resource", `Get all properties of a resource (material, mesh, shape, environment, etc).
+    withEngine(async (client) => inspectNodeFields(client, args)));
+    server.tool("summer_inspect_resource", `Read a resource: a material, mesh, shape, texture, environment, or a scene/model file.
 
-Use when you need the sub-properties of a resource attached to a node. For example, summer_inspect_node tells you a MeshInstance3D has a "StandardMaterial3D" material — this tool tells you that material's albedo_color, metallic, roughness, etc.`, {
-        path: z.string().describe("Resource path, e.g. 'res://materials/ground.tres' or 'res://models/player.glb'"),
-    }, async ({ path }) => withEngine(async (client) => client.inspectResource(path)));
+Two forms, pass exactly one:
+- path: a resource FILE ('res://materials/ground.tres', a mesh 'res://kit/meshes/wall_01.res', 'res://models/player.glb'), loaded read-only in the editor. A Mesh returns its AABB, surface_count and per surface the primitive, vertex and index counts, attributes, triangles and material (class, path or embedded, albedo for standard materials), plus the unique materials and blend shapes. A scene or model (.tscn/.glb/.gltf) returns its node count, the first 40 nodes with type, instanced scene and mesh, and its meshes; summer_inspect_asset measures it (AABB, planes, ports). Every other resource (and a mesh) returns its editor properties that differ from the class default (props), with props_at_default counting the rest.
+- nodePath + property: a resource a node of the ACTIVE scene tab holds, e.g. nodePath 'Floor', property 'mesh'. For example, summer_inspect_node tells you a MeshInstance3D has a "StandardMaterial3D" material_override — this form returns its albedo_color, metallic, roughness, etc.`, inspectResourceInputShape, async (args) => withEngine(async (client) => inspectResource(client, args)));
     server.tool("summer_batch", `Execute multiple operations in a single call. Each op is forwarded to the engine VERBATIM, so this is also how you reach engine ops that have no dedicated tool.
 
 UNDO: when nothing in the list forces a split (see the single-op contract below), the whole batch is ONE undo step — the user undoes everything with a single Ctrl+Z. When single-only ops are present the list is split into sequential requests and EACH chunk is its own undo step (one Ctrl+Z per chunk; the receipt shows the chunks). Use this when building something that involves multiple nodes and properties — e.g., creating a player character with collision, camera, and properties.
@@ -297,6 +282,11 @@ RAW RUNTIME OPS (interactive verification — structured failure_reason passes t
 - RunVerification — spawn a hidden, disposable game instance that runs a GDScript probe and dies (never touches the editor): {"op": "RunVerification", "probe_source": "...", "max_seconds": 20}. Returns {ok, results, frames, out_dir}. Probe API: report(name, value) / save_frame(name) / press(action) / key(keycode) / finish(). save_frame REQUIRES a name argument — save_frame() with no args is a script error. Mount scenes deferred: get_tree().root.add_child.call_deferred(instance); await get_tree().process_frame; await settle() — a direct add_child in _ready can hit the parent-busy guard and capture a black frame.
 - SimulateInput — inject an action/key/mouse/axis into the RUNNING game (summer_play first): {"op": "SimulateInput", "type": "action", "action": "jump", "pressed": true}. It MUST be sent alone (single-op batch). failure_reason "not_running" = start the game first; "unsupported" = the running game build predates the handler — fall back to RunVerification or ask the user.
 
+A raw ReplaceNode with scene is refused (it saves the old scene reference); use summer_replace_node.
+A raw ConnectSignal is refused (the engine connects without CONNECT_PERSIST, so the file never holds it); use summer_connect_signal.
+
+REPARENTNODE KEEPS ITS SUBTREE AND IS VERIFIED: the engine's ReparentNode re-owns only the moved node, so its children and grandchildren were dropped from the saved file. A batch with ReparentNode saves first, reads the saved .tscn, sends each ReparentNode in its own request with an in-place ReparentNode (same parent, same index) per scene-owned descendant to give it back to the scene, then reads the saved file again: persisted:true / verified:true only when every moved node and descendant is at its new path; otherwise an error with failure_reason not_persisted. A move onto a parent that already has a child of that name is refused (failure_reason name_collision). The scenePath must be a .tscn, and Undo cannot share the batch.
+
 Do not mix OpenScene with scene mutations in one batch. OpenScene is a UI action;
 send it separately. scenePath selects every mutation target. The tool appends one
 final SaveScene when the batch mutates a scene; if supplied explicitly, SaveScene
@@ -306,10 +296,21 @@ SaveScene, InstantiateScene, ReplaceNode, SimulateInput, the runtime reads
 ops to travel as their own request, so this tool automatically splits your op
 list into sequential requests around them — each split chunk is its own undo
 step (NOT one step for the whole batch), and if a later chunk fails the receipt
-reports exactly which earlier ops already applied.`, {
+reports exactly which earlier ops already applied.
+
+PLACED INSTANCES: an InstantiateScene op may also carry position, rotation_degrees, scale ([x, y, z] or "Vector3(...)") or transform ("Transform3D(...)"); the tool sets them on the created node. One op per piece. Other ops are forwarded verbatim. Cost: each InstantiateScene is its own engine request (the engine requires it); the transforms of a run of InstantiateScene ops are then sent together (up to 200 per request) before the next other op, so N placed pieces plus the save cost about N + 2 requests and N + 2 undo steps. Every later op (a SetProp, SnapToSurface, the save) sees the pieces already placed; if an InstantiateScene fails, the pieces created before it still get their transforms.
+
+RECEIPTS: receipt "summary" returns only counts, failures [{index, op, error}] (index = position in your ops list), created node paths and renames, under 5 KB with any cut declared. Use it for any batch over a few ops; the full receipt of a large batch overflows the tool-output limit.
+
+scenePersistence.saved means the SaveScene ran; it does not prove what the file
+holds. verified:true is set only where the tool read the saved file back.`, {
         scenePath: z.string().optional().describe("Required when ops contains scene mutations; exact res:// target scene path"),
         ops: z.array(z.record(z.unknown())).describe("Array of operation objects, each with 'op' plus its parameters"),
-    }, async ({ scenePath, ops }) => withEngine(async (client) => {
+        receipt: z
+            .enum(["full", "summary"])
+            .optional()
+            .describe("full (default): every engine receipt. summary: counts, failures with op index, created node paths only (under 5 KB)."),
+    }, async ({ scenePath, ops, receipt }) => withEngine(async (client) => {
         const rawFileMutation = ops.find((op) => {
             const kind = String(op.op ?? "");
             return kind === "WriteFile" || kind === "ReplaceText";
@@ -318,28 +319,15 @@ reports exactly which earlier ops already applied.`, {
             throw new ToolInputError(`summer_batch does not accept raw ${String(rawFileMutation.op)} operations. ` +
                 "Use summer_write_file or summer_replace_text so project identity, content guards, and same-file ordering are enforced.");
         }
-        const sceneMutations = new Set([
-            "AddNode", "RemoveNode", "MoveNode", "ReparentNode", "ReplaceNode",
-            "SetProp", "SetResourceProperty", "ConnectSignal", "DisconnectSignal",
-            "InstantiateScene", "SaveScene", "SnapToSurface", "AlignDistribute3D", "Undo",
-        ]);
-        // Read-only spatial queries target an exact scene (identity-bound) but
-        // never save — no SaveScene is appended for them.
-        const sceneQueries = new Set([
-            "TestPlacement3D", "NavigationProbe3D", "Starcast3D",
-        ]);
-        const containsMutation = ops.some((op) => sceneMutations.has(String(op.op ?? "")));
-        const needsScenePath = containsMutation ||
-            ops.some((op) => sceneQueries.has(String(op.op ?? "")));
-        if (needsScenePath && !scenePath) {
-            throw new ToolInputError("summer_batch requires scenePath when ops targets a scene");
-        }
-        const options = { groupUndo: true, ...(scenePath ? { scenePath } : {}) };
-        if (containsMutation) {
-            return executeSceneMutation(client, scenePath, ops, options);
-        }
-        return executeOpsChunked((chunk) => needsScenePath
-            ? client.executeIdentityBoundOps(chunk, options)
-            : client.executeOps(chunk, options), ops, resolveSingleOnlyOps(client));
-    }));
+        const replaceRefusal = rawSceneReplaceRefusal(ops);
+        if (replaceRefusal)
+            throw new ToolInputError(replaceRefusal);
+        // Scene mutations get one final SaveScene; read-only spatial queries
+        // (TestPlacement3D, NavigationProbe3D, Starcast3D) are identity-bound
+        // to the scene but never saved (core/capabilities/placement-batch.ts).
+        const result = await runBatch(client, { scenePath, ops: ops, receipt });
+        return receipt === "summary" ? { summaryReceipt: result } : result;
+    }, receipt === "summary"
+        ? { onResult: (wrapped) => renderPlacementResult(wrapped.summaryReceipt) }
+        : undefined));
 }

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

@@ -0,0 +1,24 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type SeeingResult } from "../../core/capabilities/seeing/seeing.js";
+/**
+ * Seeing tools: look at a 3D environment the way a player and an artist do.
+ * Every image comes back INLINE as an MCP image block (one grid image for a
+ * sheet, never N images), with a compact text caption (labels, poses, scores,
+ * mark -> path). Renders use the scene's REAL WorldEnvironment and lights.
+ * Implementation and the in-engine kernel: src/core/capabilities/seeing/.
+ */
+type ToolResultContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+type ToolResult = {
+    content: ToolResultContent[];
+    isError?: boolean;
+};
+export declare function seeingContent(result: SeeingResult): ToolResult;
+export declare function registerSeeingTools(server: McpServer): void;
+export {};

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

@@ -0,0 +1,64 @@
+import { withEngine } from "./with-engine.js";
+import { debugViews, frameNodes, frameShot, shotSheet, zoom, } from "../../core/capabilities/seeing/seeing.js";
+import { debugViewsShape, frameNodesShape, frameShotShape, shotSheetShape, zoomShape, } from "../../core/capabilities/seeing/args.js";
+function wrap(result) {
+    return result.ok ? { seeing: result } : { seeing: result, failure_reason: result.failure_reason };
+}
+export function seeingContent(result) {
+    if (!result.ok) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: result.error,
+                        failure_reason: result.failure_reason,
+                        ...(result.hint ? { hint: result.hint } : {}),
+                        ...(result.detail ? { detail: result.detail } : {}),
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    const content = [];
+    if (result.image)
+        content.push({ type: "image", data: result.image.base64, mimeType: result.image.mime || "image/jpeg" });
+    content.push({ type: "text", text: result.caption });
+    return { content };
+}
+function run(op) {
+    return async (args) => withEngine(async (client) => wrap(await op(client, args)), {
+        onResult: (wrapped) => seeingContent(wrapped.seeing),
+    });
+}
+const COMMON = `Read-only: the scene file, the open tab and the undo history are never touched (the render is an offscreen copy of the SAVED scene). The image arrives inline; the caption carries poses, labels and numbers. Failures are structured (failure_reason), never a silent fallback.`;
+export function registerSeeingTools(server) {
+    server.tool("summer_frame_nodes", `Frame one or more nodes with a camera fitted to their WORLD bounds and render it with the scene's REAL WorldEnvironment, lights, fog and tonemap (unlike summer_screenshot nodePath, which only works with the flat preview environment).
+
+Pick the side with direction (front/back/left/right/top/iso) or an explicit from vector; fill sets how much of the frame they span. bookmark_name also saves the fitted pose so every later render (summer_shot_sheet, summer_debug_views, summer_screenshot framing:"bookmark") lines up with it. marks:true adds numbered labels mapped to node paths.
+
+An explicit from is checked in-engine before you trust the image: if walls block the nodes, or the camera stands behind or inside a one-sided surface (its back is not drawn, so the image would look THROUGH the wall), the caption opens with a WARNING and the nearest valid from (+ fov) to pass back. With marks:true every labelled node gets an occlusion test (centre + 4 bounds points); hidden ones are noted "(hidden behind <path>)".
+
+Returns the image + caption: the pose as Vector3 literals, the bounds, the environment used, the view check, and the mark list. ${COMMON}`, frameNodesShape, run(frameNodes));
+    server.tool("summer_shot_sheet", `Render several bookmarks and/or explicit poses into ONE labelled grid image in a single call: same tile size, same view, real lighting. Use it after every change to see all hero views at once instead of N screenshots.
+
+compare_previous:true turns each bookmark into a row of [previous | now | difference map] and reports the share of pixels that changed and where. Each bookmark keeps exactly one previous render (its compare baseline) at res://.summer/shots/<bookmark>.jpg (JPEG, <= 1024 px; the folder is capped at 20 MB, oldest first). Only compare_previous:true or update_previous:true replaces it; a plain sheet creates a missing baseline and never overwrites one. view renders every tile as lighting/unshaded/normals/overdraw/wireframe instead of beauty.
+
+Returns the grid + caption (tile number -> label and pose, difference stats). ${COMMON}`, shotSheetShape, run(shotSheet));
+    server.tool("summer_debug_views", `One pose rendered as a grid of debug views next to the beauty pass: beauty, lighting (light only: direction, pools, dead-dark areas), unshaded (albedo: texture quality, value grouping), normals (world-space, x red y green z blue: seams, flipped or faceted normals), overdraw (stacked transparent layers), wireframe (triangle density, floating or duplicated pieces).
+
+Use it on the weakest shot of a sheet to see WHY it reads badly. lighting/unshaded/overdraw/wireframe are the engine's Viewport debug draw modes; normals uses an unshaded override material on a private copy (normal maps and alpha cut-outs are not applied) and works on every renderer. The caption names the method per view.
+
+Returns the grid + caption. ${COMMON}`, debugViewsShape, run(debugViews));
+    server.tool("summer_zoom", `High-resolution close look at part of a frame: region [x, y, w, h] (fractions of the frame) or mark N from a marks render of the same pose. The camera renders the EXACT sub-frustum of that region at full output resolution, so you see real texture detail, seams, gaps and floating pieces, not upscaled pixels. A region is honoured exactly (no pad by default, never widened to an aspect ratio: the image takes the region's own aspect, with dark bars only for extreme shapes); a mark gets pad 0.15.
+
+Use after a sheet or debug view shows something suspicious. view picks beauty or a debug view. Returns the zoomed image + caption (the real zoom factor, the rendered region, widened_because when it is larger than asked, mark -> node path and a warning when that node is hidden). ${COMMON}`, zoomShape, run(zoom));
+    server.tool("summer_frame_shot", `Smart framing: find good camera poses for a shot type automatically, measured in-engine against the real geometry.
+
+shot: establishing (wide), eye_level (from a spawn node at player eye height), low_angle (hero, near the ground looking up: the camera moves closer and widens its FOV instead of sinking into the ground), detail (close-up), corridor (down a lane or corridor found inside the subject by a free-space scan, preferring the view in from its open end, walls on both sides).
+
+How: candidate poses on a ring/hemisphere (or along the corridor line) at the distance where the subject fills the shot's target share of the frame; each is checked with a THICK sphere sweep to points on the subject (thin rays miss corners), a near-lens sphere (camera inside or touching geometry is nudged forward or rejected), a ray grid through the frame, and a small beauty render per pose. Walls/terrain blocking the subject reject a pose, and so does a camera behind or inside a one-sided surface (a sight line or a quarter of the frame meeting a wall from behind: its back is not drawn, so the image would look through it). Foliage, fences, props and pipes in front are allowed (wanted, up to a limit) as framing; transparent materials (alpha, scissor, glass, foliage cards) are see-through cover at partial weight. Scored on rule-of-thirds placement, frame fill, level horizon, sky share, depth behind the subject (no flat wall right behind it), empty or featureless areas, near-wall clearance, near/far value contrast, foreground framing, surfaces seen from behind, the key light's direction (side or front-side beats a flat front-lit face) and the world edge (sky or void below the horizon).
+
+Returns the top 3 with score breakdowns and poses — three different views (one per side of the subject while the score allows, at least 25 degrees apart) — saves the best as a bookmark (default <shot>_<subject>), and renders the 3 as one sheet with real lighting (render:"best" or "none" to save context). ${COMMON} Saving the bookmark writes res://.summer/camera_bookmarks.json.`, frameShotShape, run(frameShot));
+}