summer-engine 3.0.0 → 3.2.0

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

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

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.