summer-engine 3.7.0 → 4.0.0

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

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

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

@@ -192,17 +192,17 @@ Use this when summer_get_diagnostics shows a non-zero \`debugger.warnings\` coun
         const { result } = shapeEngineLogResponse(engineResult, { maxEntries: max_warnings });
         return result;
     }));
-    server.tool("summer_play", `Start running the game in the engine. With no extra parameters the game runs inside Summer Engine's viewport (the 'main' instance) QUIETLY — see below.
+    server.tool("summer_play", `Start the game. With no parameters it runs QUIETLY inside Summer Engine's viewport (the 'main' instance); scene runs one level or UI screen instead of the main scene.
 
-QUIET BY DEFAULT (focus:false, PlayGame agent:true): the user is usually working on the same machine while you build, so a play must not take over their screen. Quiet play makes the EDITOR stay put: it does not switch the main screen to the Game tab, does not grab keyboard focus for the embedded game, ignores the game's later focus report, and skips the render-health self-check that would otherwise misread the untouched Game view as a GPU failure and flip the user's embed setting. Quiet play does NOT hide the game: it still runs embedded in the Game view (visible if the user already has that tab open), it is the running game for summer_is_running / summer_screenshot target:'game' / summer_get_diagnostics, and on engines without the background launch posture it does not change a user who has "Embed Game on Play" turned off — their game opens in its own OS window as always. Engines with the background posture (--summer-background, 0.5.66+) also launch the play child with that flag, so a separate-window game appears without activating or taking focus either. The result echoes agent_quiet:true when honoured; a launch result WITHOUT agent_quiet means the engine predates quiet play and most likely took focus — the tool adds posture_note saying so. focus:true launches like the toolbar Play button (Game tab + focus): use it ONLY when the user is watching and asked to see the game come up.
+QUIET BY DEFAULT (focus:false, PlayGame agent:true): the user usually works on the same machine, so the EDITOR stays put. It does not switch to the Game tab or take keyboard focus (nor follow the game's later focus report), and skips the render-health self-check that would misread the untouched Game view as a GPU failure and flip the user's embed setting. Quiet play does NOT hide the game: it runs embedded in the Game view (visible if that tab is open) and is the running game for summer_is_running / summer_screenshot target:'game' / summer_get_diagnostics. With "Embed Game on Play" off the game gets its own OS window; engines with --summer-background (0.5.66+) open it without taking focus. The result echoes agent_quiet:true when honoured; without agent_quiet the engine predates quiet play and most likely took focus (posture_note says so). focus:true launches like the toolbar Play button (Game tab + focus): ONLY when the user is watching and asked to see the game come up.
 
-After starting, confirm boot with summer_is_running (boot time varies — never sleep a guessed delay), then summer_get_diagnostics for runtime errors. You can run a specific scene instead of the main scene — useful for testing individual levels or UI screens.
+After starting, confirm boot with summer_is_running (boot time varies; never sleep a guessed delay), then summer_get_diagnostics for runtime errors.
 
-DETERMINISTIC RUNS (newer engines): seed / fixed_fps / time_scale pin THIS launch only (nothing is persisted). seed pins the game's GLOBAL RNG (randi/randf/randi_range/randf_range/randfn, Array.shuffle/pick_random) — it does NOT pin RandomNumberGenerator instances, scripts that call randomize(), rand_from_seed, wall-clock reads, or thread/IO/audio timing. fixed_fps decouples scene time from the wall clock so frame-count-derived state lands on the same frame run to run. The result's \`determinism\` block says whether the pins were applied (applied:false carries a reason: already_running, editor_run_args_override, launch_not_started) and restates seed_scope. If the result has NO determinism block although you sent a pin, the engine predates the params and the run is NOT reproducible — the tool says so; do not claim otherwise. Omitting every pin and instance parameter is exactly the v1 launch.
+DETERMINISTIC RUNS (newer engines): seed / fixed_fps / time_scale pin THIS launch only, nothing persisted. seed pins the GLOBAL RNG only (not RandomNumberGenerator instances, randomize(), rand_from_seed, wall-clock, thread/IO/audio timing). The result's \`determinism\` block says whether the pins applied (applied:false carries a reason: already_running, editor_run_args_override, launch_not_started) and restates seed_scope. NO determinism block although you sent a pin = the engine predates the params and the run is NOT reproducible (the tool says so); never claim otherwise.
 
-PLAYTEST LAUNCH (engine runtime-control build): instance + mode:'offscreen' spawn a disposable hidden instance (at most 3) that summer_game_probe / summer_game_input / summer_game_control / summer_runtime_* address by name — run two variants side by side for an A/B. deterministic:true (offscreen only) launches with --fixed-fps 60 --summer-seed --audio-driver Dummy and is what lets summer_game_input action:'replay' accept a seed; speed sets the user time scale on session start. The instance result reports session_attached; poll summer_game_control action:'instances' until attached:true before addressing it. Then: probe -> act -> step/probe -> assert (the agent-playtesting skill). Failure reasons: too_many_instances, instance_exists, session_timeout (child never attached — check summer_get_console), unsupported_mode, main_scene_not_configured. A game already running answers playing:true with determinism.applied:false — summer_stop first to apply seed/fixed_fps.
+PLAYTEST LAUNCH (engine runtime-control build): instance + mode:'offscreen' spawn a disposable hidden instance (at most 3) that summer_game_probe / summer_game_input / summer_game_control / summer_runtime_* address by name; two side by side make an A/B. deterministic:true (offscreen only) is what lets summer_game_input action:'replay' accept a seed. Poll summer_game_control action:'instances' until attached:true (the result reports session_attached) before addressing it. Then probe -> act -> step/probe -> assert (the agent-playtesting skill). Failure reasons: too_many_instances, instance_exists, session_timeout (child never attached; check summer_get_console), unsupported_mode, main_scene_not_configured. A game already running answers playing:true with determinism.applied:false: summer_stop first to apply seed/fixed_fps.
 
-MULTIPLAYER — LOCAL PLAY (Summer multiplayer games; engine with Local Play): players:N starts the game's authority headless plus N clients on this machine, each joining through the game's OWN Summer.client.join(SummerJoinTarget.queue(...)) — no account, login, Docker, CLI or local-only game code. The scenes and queue come from the project's summer.build.json and its WorldDefinition (client_entry_point + the headless_engine component entry_point); queue picks another declared queue — pass queue WITHOUT players to start that queue's minPlayers (a 4-player queue starts 4), or players to choose; spectators adds spectator clients. local_play.warnings flags a roster outside the queue's minPlayers..maxPlayers. The result's local_play block lists every process (label, role, persona) and the port; failure_reason local_play_unavailable says exactly what to declare. Every process attaches to the editor debugger: screenshots, input and summer_game_* go to the FIRST client, the authority's output is in summer_get_console, and summer_stop stops them all. A join for a different queue fails with a message naming both queues. It is not a proof of sign-in, matchmaking or hosted admission (staging). No local_play block although you sent players means the engine predates Local Play and ran ONE client — the tool says so.`, {
+MULTIPLAYER — LOCAL PLAY (engine with Local Play; the multiplayer-testing skill): players:N starts the game's authority headless plus N clients on this machine, each joining through the game's OWN Summer.client.join(SummerJoinTarget.queue(...)): no account, login, Docker, CLI or local-only game code. Scenes and queue come from summer.build.json's WorldDefinition (client_entry_point, the headless_engine component entry_point). queue picks another declared queue; queue WITHOUT players starts its minPlayers; spectators adds spectator clients. local_play.warnings flags a roster outside minPlayers..maxPlayers. The local_play block lists every process (label, role, persona) and the port; failure_reason local_play_unavailable says what to declare. Every process attaches to the editor debugger: screenshots, input and summer_game_* go to the FIRST client, the authority's output is in summer_get_console, summer_stop stops them all. A join for a different queue fails naming both queues. Not a proof of sign-in, matchmaking or hosted admission (staging). No local_play block although you sent players = the engine predates Local Play and ran ONE client; the tool says so.`, {
         scene: z.string().optional().describe("Scene to run instead of main scene, e.g. 'res://levels/test_level.tscn'"),
         ...playGameExtensionSchema,
     }, async (args) => {

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

@@ -7,17 +7,17 @@ WHEN — the three asset classes neither generation nor the free library serve w
 - modular kits with exact dimensions and snapping (walls, pipes, fences, rails: array + boolean + bevel, one shared material) — generation cannot hold size and style across 30 pieces;
 - VFX meshes (shatter pieces, curve sweeps, trails, LOD chains) — one-liners in bpy, absent in the engine;
 - post-processing a generated model (decimate -> UV unwrap -> bake) before it goes into the scene.
-WHEN NOT: a generic prop (barrel, crate, chair) -> summer_search_assets / summer_import_asset first, then summer_generate_3d; a character or any organic shape -> summer_generate_3d (scripted organic modelling is the documented failure mode); a blockout or placeholder -> summer_run_script primitives/CSG, instant and in-scene. Route with the asset-strategy skill; the fabricating-assets skill carries the bpy rules and recipes.
+WHEN NOT: a generic prop (barrel, crate, chair) -> summer_search_assets / summer_import_asset first, then summer_generate_3d; a character or any organic shape -> summer_generate_3d (scripted organic modelling is the documented failure mode); a blockout or placeholder -> summer_run_script primitives/CSG, instant and in-scene. Route with the asset-strategy skill; the fabricating-assets skill carries the bpy rules, recipes and the fix for each failure_reason.
 
-SCRIPT CONTRACT: 'source' is plain bpy code. Pre-bound names: bpy, bmesh, mathutils, math, Vector, Matrix, Euler. The script must CREATE mesh objects and leave them linked in the scene — do NOT export and do NOT quit (the engine's bootstrap exports for you: modifiers applied at export, Geometry Nodes realized, +Y-up conversion, materials carried as Principled BSDF only, a procedural Base Color baked to a 2K texture; procedural Metallic/Roughness/Normal/Emission are NOT baked and come back in 'warnings'). Objects hidden or render-disabled are treated as helpers (boolean cutters, guides) and are not exported — they are listed in 'skipped'. Model in metres. MESH/CURVE/SURFACE/META/FONT export as meshes, EMPTY/ARMATURE keep hierarchy, cameras and lights are dropped. Name your objects — they become node names.
+SCRIPT CONTRACT: 'source' is plain bpy that must CREATE mesh objects and leave them linked in the scene — do NOT export and do NOT quit. The engine's bootstrap exports for you: modifiers applied, Geometry Nodes realized, +Y-up conversion, materials as Principled BSDF only, a procedural Base Color baked to a 2K texture; procedural Metallic/Roughness/Normal/Emission are NOT baked (see 'warnings'). Hidden or render-disabled objects are helpers (boolean cutters, guides), not exported, listed in 'skipped'. Model in metres. MESH/CURVE/SURFACE/META/FONT export as meshes, EMPTY/ARMATURE keep hierarchy, cameras and lights are dropped. Name your objects — they become node names.
 
-REQUIRES BLENDER on the user's machine (4.2 LTS or newer). Resolution order: 'blender_path' -> SUMMER_BLENDER_BIN in the editor's environment -> Editor Settings filesystem/import/blender/blender_path (shared with .blend import) -> PATH, well-known install dirs, ~/.summer/tools/blender-*. Not found -> failure_reason blender_not_found with the exact fix and every path that was checked; relay it to the user as a one-line decision, never guess a path and never install anything on their behalf.
+REQUIRES BLENDER 4.2 LTS or newer. Resolution: 'blender_path' -> SUMMER_BLENDER_BIN in the editor's environment -> Editor Settings filesystem/import/blender/blender_path -> PATH, well-known install dirs, ~/.summer/tools/blender-*. Not found -> failure_reason blender_not_found with the exact fix and every path checked; relay it to the user as a one-line decision; never guess a path or install anything for them.
 
-ONE fabrication runs at a time per editor (failure_reason busy — wait for the result, never fire two in parallel). Budget max_seconds 15-600 (default 120) covers Blender boot + script + bakes + export; the client waits max_seconds + 60 s. Blind until import: there is no viewport feedback while the script runs, so keep scripts deterministic (fixed seeds) and verify afterwards.
+ONE fabrication runs at a time per editor (failure_reason busy: wait for the result, never fire two in parallel). There is no viewport feedback while the script runs, so keep scripts deterministic (fixed seeds) and verify afterwards.
 
-Returns {ok, ran, blender_version, blender_path, out_path, objects[{name,type,vertices,faces,triangles,materials,modifiers}], object_count, dimensions{x,y,z} (+Y up, source scale), warnings[], baked[], skipped[], output[], errors[], exit_code, duration_ms, checkpoint} plus imported_node_path / scale_applied / instance_dimensions with import_to_scene, and no_rewind_point:true when no checkpoint exists. Failures carry failure_reason: blender_not_found | blender_launch_failed | script_error (traceback_tail + script_line — fix the bpy against the reported blender_version and re-run; bpy APIs change across majors) | timeout (raise max_seconds or split the job) | export_empty (no exportable object — check hide/render flags and collection links) | export_failed | export_missing | import_failed / instantiate_failed (the .glb IS at out_path — summer_instantiate_scene it yourself; the importer's message is in summer_get_console) | busy | cancelled.
+Returns blender_version, blender_path, out_path, objects[{name, type, vertices, faces, triangles, materials, modifiers}], object_count, dimensions{x,y,z} (+Y up, source scale), warnings, baked, skipped, output, errors, exit_code, duration_ms, checkpoint; with import_to_scene also imported_node_path / scale_applied / instance_dimensions; no_rewind_point:true when no checkpoint exists. failure_reason: blender_not_found | blender_launch_failed | script_error (traceback_tail + script_line; fix the bpy for the reported blender_version) | timeout (raise max_seconds or split the job) | export_empty (check hide/render flags and collection links) | export_failed | export_missing | import_failed / instantiate_failed (the .glb IS at out_path: summer_instantiate_scene it yourself; importer message in summer_get_console) | busy | cancelled.
 
-THE LOOP: summer_world_snapshot BEFORE (keep snapshot_id) -> summer_fabricate_3d with import_to_scene (+ target_size for real-world scale) -> read dimensions/warnings/skipped -> summer_snapshot_diff + summer_screenshot -> iterate. Never claim a visual result without the screenshot. If this engine build predates FabricateMesh, the result is a structured engine_lacks_op failure (nothing is sent): use summer_generate_3d / summer_search_assets, or update Summer Engine.`, fabricateArgsSchema.shape, async (args) => withEngine(async (client) => {
+THE LOOP: summer_world_snapshot BEFORE (keep snapshot_id) -> summer_fabricate_3d with import_to_scene (+ target_size for real-world scale) -> read dimensions/warnings/skipped -> summer_snapshot_diff + summer_screenshot -> iterate. Never claim a visual result without the screenshot. An engine build without FabricateMesh returns a structured engine_lacks_op failure (nothing is sent): use summer_generate_3d / summer_search_assets, or update Summer Engine.`, fabricateArgsSchema.shape, async (args) => withEngine(async (client) => {
         const missing = missingEngineOpResult(client, "FabricateMesh", FABRICATE_FALLBACK);
         if (missing)
             return missing;

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

@@ -8,7 +8,8 @@ import { getAuthToken } from "../../core/auth.js";
 import { resolveGatewayUrl } from "../../core/config.js";
 import { readJsonResponse } from "../../core/util/http.js";
 import { asRecord, stringFrom } from "../../core/util/json.js";
-import { TOOLKIT_VERSION as CLI_VERSION } from "../../core/version.js";
+import { summerRequestHeaders } from "../../core/agent-host.js";
+import { codedFailure, codeForStatus, describeNetworkError, networkDetails, NOT_SIGNED_IN, SIGN_IN_AGAIN_RECOVERY, } from "../../core/error-codes.js";
 const TOOL_BY_ENDPOINT = {
     "/api/mcp/generate/image": "summer_generate_image",
     "/api/mcp/generate/audio": "summer_generate_audio",
@@ -72,13 +73,18 @@ async function readLenientJson(res) {
         return json;
     return text ? { message: text.slice(0, 1000) } : {};
 }
+/** The coded failure for a non-OK reply: 401 (token expired) and 402 (no
+ *  credits) carry the shared codes. */
+function statusFailure(status) {
+    const code = codeForStatus(status);
+    if (!code)
+        return {};
+    return code === "not_signed_in" ? { code, recovery: SIGN_IN_AGAIN_RECOVERY } : { code };
+}
 async function mcpGenerate(endpoint, body, timeoutMs = 120_000) {
     const token = await getAuthToken();
     if (!token) {
-        return {
-            error: "Not signed in. Run in your terminal:\n  npx -y summer-engine@latest login\nOr open: https://www.summerengine.com/login",
-            status: 401,
-        };
+        return { error: NOT_SIGNED_IN, status: 401, code: "not_signed_in" };
     }
     const gatewayUrl = await resolveGatewayUrl();
     let res;
@@ -86,36 +92,27 @@ async function mcpGenerate(endpoint, body, timeoutMs = 120_000) {
         res = await fetch(`${gatewayUrl}${endpoint}`, {
             method: "POST",
             headers: {
+                ...summerRequestHeaders({ tool: TOOL_BY_ENDPOINT[endpoint], surface: "mcp" }),
                 Authorization: `Bearer ${token}`,
                 "Content-Type": "application/json",
-                "X-Summer-Client": "summer-cli",
-                "X-Summer-Client-Version": CLI_VERSION,
-                "X-Summer-Client-Surface": "mcp",
                 "X-Summer-MCP-Endpoint": endpoint,
-                "X-Summer-MCP-Tool": TOOL_BY_ENDPOINT[endpoint] ?? "unknown",
             },
             body: JSON.stringify(body),
             signal: AbortSignal.timeout(timeoutMs),
         });
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return { error: `Generation request failed: ${msg}`, status: 0 };
+        return { error: `Generation request failed: ${describeNetworkError(err)}`, status: 0, code: "unavailable", data: networkDetails(err) };
     }
     const data = await readLenientJson(res);
     if (!res.ok) {
         let message = formattedApiErrorMessage(res.status, data);
-        if (res.status === 402) {
-            message =
-                (data.message || "Insufficient credits.") +
-                    "\nTop up at: https://www.summerengine.com/dashboard\nOr upgrade your plan at: https://www.summerengine.com/pricing";
-        }
-        if (res.status === 401) {
-            message =
-                (data.message || "Auth token expired.") +
-                    "\nRe-authenticate:\n  npx -y summer-engine@latest login";
-        }
-        return { error: message, data: { ...data, status: res.status }, status: res.status };
+        // The next step (Add credits, sign in again) rides in `recovery`.
+        if (res.status === 402)
+            message = String(data.message || "Not enough credits.");
+        if (res.status === 401)
+            message = String(data.message || "Auth token expired.");
+        return { error: message, data: { ...data, status: res.status }, status: res.status, ...statusFailure(res.status) };
     }
     return { data, status: res.status };
 }
@@ -127,19 +124,15 @@ async function mcpGet(endpoint, searchParams, timeoutMs = 30_000) {
     try {
         res = await fetch(`${gatewayUrl}${endpoint}${suffix}`, {
             headers: {
+                ...summerRequestHeaders({ tool: TOOL_BY_ENDPOINT[endpoint], surface: "mcp" }),
                 ...(token ? { Authorization: `Bearer ${token}` } : {}),
-                "X-Summer-Client": "summer-cli",
-                "X-Summer-Client-Version": CLI_VERSION,
-                "X-Summer-Client-Surface": "mcp",
                 "X-Summer-MCP-Endpoint": endpoint,
-                "X-Summer-MCP-Tool": TOOL_BY_ENDPOINT[endpoint] ?? "unknown",
             },
             signal: AbortSignal.timeout(timeoutMs),
         });
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return { error: `Request failed: ${msg}`, status: 0 };
+        return { error: `Request failed: ${describeNetworkError(err)}`, status: 0, code: "unavailable", data: networkDetails(err) };
     }
     const data = await readLenientJson(res);
     if (!res.ok) {
@@ -147,6 +140,8 @@ async function mcpGet(endpoint, searchParams, timeoutMs = 30_000) {
             error: formattedApiErrorMessage(res.status, data),
             data: { ...data, status: res.status },
             status: res.status,
+            // Without a token a 401 means "sign in", not "sign in again".
+            ...(!token && res.status === 401 ? { code: "not_signed_in" } : statusFailure(res.status)),
         };
     }
     return { data, status: res.status };
@@ -158,18 +153,18 @@ async function mcpGet(endpoint, searchParams, timeoutMs = 30_000) {
 async function pollJob(jobId, maxWaitMs = 600_000, intervalMs = 5_000) {
     const token = await getAuthToken();
     if (!token)
-        return { error: "Not signed in" };
+        return { error: NOT_SIGNED_IN, code: "not_signed_in" };
     const gatewayUrl = await resolveGatewayUrl();
     const deadline = Date.now() + maxWaitMs;
     while (Date.now() < deadline) {
         try {
             const res = await fetch(`${gatewayUrl}/api/mcp/jobs/${encodeURIComponent(jobId)}`, {
-                headers: { Authorization: `Bearer ${token}` },
+                headers: { ...summerRequestHeaders({ surface: "mcp" }), Authorization: `Bearer ${token}` },
                 signal: AbortSignal.timeout(15_000),
             });
-            const data = await res.json();
+            const data = await readLenientJson(res);
             if (!res.ok)
-                return { error: data.message || "Poll failed", data };
+                return { error: data.message || "Poll failed", data, ...statusFailure(res.status) };
             if (data.status === "completed")
                 return { data };
             if (data.status === "failed")
@@ -182,23 +177,32 @@ async function pollJob(jobId, maxWaitMs = 600_000, intervalMs = 5_000) {
             }
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            return { error: `Poll error: ${msg}` };
+            return { error: `Poll error: ${describeNetworkError(err)}`, code: "unavailable", data: networkDetails(err) };
         }
     }
     return { error: `Timed out after ${maxWaitMs / 1000}s. Use summer_check_job({ jobId: "${jobId}" }) to check later.` };
 }
-function errorResult(message, extra) {
+/** A failed tool call. With a shared code (core/error-codes.ts) the body is
+ *  `{ok:false, code, error, recovery, …, message}`; otherwise the older
+ *  `{error:true, …, message}`. */
+function errorResult(message, extra, coded) {
+    const body = coded?.code
+        ? codedFailure(coded.code, message, { ...extra, message }, coded.recovery)
+        : { error: true, ...extra, message };
     return {
         content: [
             {
                 type: "text",
-                text: JSON.stringify({ error: true, ...extra, message }, null, 2),
+                text: JSON.stringify(body, null, 2),
             },
         ],
         isError: true,
     };
 }
+/** The step after a generation job starts (the hosted tools answer the same way). */
+function checkJobNext(jobId) {
+    return `The job runs on Summer's servers. Poll summer_check_job({ jobId: "${jobId}" }) every 15-30 seconds until status is "completed".`;
+}
 function successResult(data) {
     return {
         content: [
@@ -232,7 +236,7 @@ handoff that MCP cannot perform automatically; do not pretend that stage ran.`,
             params.set("id", workflowId);
         const result = await mcpGet("/api/mcp/workflows", params);
         if (result.error)
-            return errorResult(result.error, result.data);
+            return errorResult(result.error, result.data, result);
         return successResult(result.data);
     });
     // ========================================================================
@@ -252,7 +256,7 @@ Cloud tool — runs on Summer's servers and works WITHOUT the Summer Engine app
 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 errorResult(result.error, result.data, result);
         return { content: boardContent(result.data ?? {}) };
     });
     // ========================================================================
@@ -307,7 +311,7 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, imageG
             options,
         }, IMAGE_GENERATION_TIMEOUT_MS);
         if (result.error) {
-            return errorResult(result.error, result.data);
+            return errorResult(result.error, result.data, result);
         }
         // Download to temp so the AI can Read and show the image
         const imageUrl = result.data?.asset?.fileUrl || result.data?.asset?.thumbnailUrl;
@@ -343,7 +347,7 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
     }, async ({ assetId }) => {
         const result = await mcpGenerate("/api/mcp/generate/slice-asset-sheet", { assetId }, 300_000);
         if (result.error) {
-            return errorResult(result.error, result.data);
+            return errorResult(result.error, result.data, result);
         }
         return successResult({
             ...result.data,
@@ -442,7 +446,7 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
             body.options = options;
         const result = await mcpGenerate("/api/mcp/generate/audio", body);
         if (result.error) {
-            return errorResult(result.error, result.data);
+            return errorResult(result.error, result.data, result);
         }
         return successResult(result.data);
     });
@@ -533,8 +537,9 @@ For a complete animated humanoid package, pass rig=true plus animationNames or
 actionIds. This routes through the shared character pipeline instead of a
 one-off mesh job.
 
-By default, waits for completion (up to 10 min) and returns the result directly.
-Set wait=false to get the jobId immediately and poll manually with summer_check_job.
+Returns a jobId within seconds. Poll summer_check_job with it until status is
+"completed" (most models take 1-5 minutes; tell the user it is running and keep
+working meanwhile). wait=true blocks up to 10 minutes instead.
 
 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.`, {
@@ -589,8 +594,8 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
             .describe("Character height used by auto-rigging"),
         wait: z
             .boolean()
-            .default(true)
-            .describe("Wait for completion (default true, up to 10 min). Set false to get jobId immediately."),
+            .default(false)
+            .describe("Block until the job finishes (up to 10 min) and return the result. Default false returns the jobId at once; poll summer_check_job."),
         options: z
             .record(z.any())
             .optional()
@@ -616,17 +621,17 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
             options: mergedOptions,
         });
         if (result.error) {
-            return errorResult(result.error, result.data);
+            return errorResult(result.error, result.data, result);
         }
         const jobId = result.data?.jobId;
-        // If not waiting or no jobId, return immediately
+        // The job runs on Summer's servers; the agent polls summer_check_job.
         if (!wait || !jobId) {
-            return successResult(result.data);
+            return successResult(jobId ? { ...result.data, next: checkJobNext(jobId) } : result.data);
         }
-        // Auto-poll until done
+        // wait=true: block until done
         const pollResult = await pollJob(jobId);
         if (pollResult.error) {
-            return errorResult(pollResult.error, { ...pollResult.data, jobId });
+            return errorResult(pollResult.error, { ...pollResult.data, jobId }, pollResult);
         }
         return successResult({
             ...pollResult.data,
@@ -688,7 +693,7 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
             options,
         });
         if (result.error) {
-            return errorResult(result.error, result.data);
+            return errorResult(result.error, result.data, result);
         }
         return successResult(result.data);
     });
@@ -697,9 +702,10 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
     // ========================================================================
     server.tool("summer_check_job", `Check the status of an async generation job.
 
-Use this when you called summer_generate_3d with wait=false, or need to re-check
-a job that timed out. Most of the time you won't need this — summer_generate_3d
-waits automatically.
+summer_generate_3d and summer_generate_motion return a jobId; call this with it
+every 15-30 seconds until status is "completed" or "failed". A completed job
+carries the result: assetId (3D), rigAssetId (rig=true), animationAssetId or
+result.assets (motion), with file URLs. Import with summer_import_asset_by_id.
 
 Status values: waiting, active, completed, failed, delayed, unknown.
 
@@ -709,24 +715,24 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
     }, async ({ jobId }) => {
         const token = await getAuthToken();
         if (!token) {
-            return errorResult("Not signed in. Run: npx -y summer-engine@latest login");
+            return errorResult(NOT_SIGNED_IN, undefined, { code: "not_signed_in" });
         }
+        let res;
         try {
             const gatewayUrl = await resolveGatewayUrl();
-            const res = await fetch(`${gatewayUrl}/api/mcp/jobs/${encodeURIComponent(jobId)}`, {
-                headers: { Authorization: `Bearer ${token}` },
+            res = await fetch(`${gatewayUrl}/api/mcp/jobs/${encodeURIComponent(jobId)}`, {
+                headers: { ...summerRequestHeaders({ surface: "mcp" }), Authorization: `Bearer ${token}` },
                 signal: AbortSignal.timeout(15_000),
             });
-            const data = await res.json();
-            if (!res.ok) {
-                return errorResult(data.message || data.error || "Failed to check job status", data);
-            }
-            return successResult(data);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            return errorResult(`Job status check failed: ${msg}`);
+            return errorResult(`Job status check failed: ${describeNetworkError(err)}`, networkDetails(err), { code: "unavailable" });
+        }
+        const data = await readLenientJson(res);
+        if (!res.ok) {
+            return errorResult(data.message || data.error || "Failed to check job status", data, statusFailure(res.status));
         }
+        return successResult(data);
     });
     // ========================================================================
     // summer_generate_motion
@@ -763,9 +769,9 @@ 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.
 
-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.
+Returns a jobId within seconds. Poll summer_check_job with it until status is
+"completed" (wait=true blocks up to 10 minutes instead). Import finished clips
+with summer_import_asset_by_id.
 
 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
@@ -782,16 +788,16 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, motion
         const result = await mcpGenerate("/api/mcp/generate/motion", built.body);
         if (result.error) {
             const hint = motionErrorHint(result.data?.error);
-            return errorResult(result.error, hint ? { ...result.data, hint } : result.data);
+            return errorResult(result.error, hint ? { ...result.data, hint } : result.data, result);
         }
         const jobId = result.data?.jobId;
         if (!args.wait || !jobId) {
-            return successResult(result.data);
+            return successResult(jobId ? { ...result.data, next: checkJobNext(jobId) } : result.data);
         }
         const pollResult = await pollJob(jobId);
         if (pollResult.error) {
             const hint = motionJobFailureHint(pollResult.error);
-            return errorResult(pollResult.error, { ...pollResult.data, jobId, ...(hint ? { hint } : {}) });
+            return errorResult(pollResult.error, { ...pollResult.data, jobId, ...(hint ? { hint } : {}) }, pollResult);
         }
         return successResult({
             ...pollResult.data,

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

@@ -5,12 +5,17 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
  * share ONE implementation. The MCP surface contributes the boot drift notice
  * it owns. Exported for tests.
  */
-export declare function buildAgentPlaybook(): Record<string, unknown>;
-export declare function renderAgentPlaybook(): string;
+export declare function buildAgentPlaybook(options?: ProjectToolsOptions): Record<string, unknown>;
+export declare function renderAgentPlaybook(options?: ProjectToolsOptions): string;
+/** What the session's profile serves. `engine: false` (the assets profile)
+ *  turns the playbook and the task plan into their no-engine versions. */
+export interface ProjectToolsOptions {
+    engine?: boolean;
+}
 /**
  * Register the playbook as an MCP PROMPT as well, so hosts that surface
  * prompts (prompt pickers, slash commands) get the operating guide natively
  * without knowing to call the tool. Same content, second doorway.
  */
-export declare function registerPlaybookPrompt(server: McpServer): void;
-export declare function registerProjectTools(server: McpServer): void;
+export declare function registerPlaybookPrompt(server: McpServer, options?: ProjectToolsOptions): void;
+export declare function registerProjectTools(server: McpServer, options?: ProjectToolsOptions): void;

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

@@ -38,37 +38,42 @@ function getScenePathFromSceneState(sceneState) {
  * share ONE implementation. The MCP surface contributes the boot drift notice
  * it owns. Exported for tests.
  */
-export function buildAgentPlaybook() {
+export function buildAgentPlaybook(options = {}) {
     return buildCoreAgentPlaybook({
         summerUpdateNotice: getCachedBootDriftNotice()?.text ?? null,
+        engine: options.engine,
     });
 }
-export function renderAgentPlaybook() {
-    return JSON.stringify(buildAgentPlaybook(), null, 2);
+export function renderAgentPlaybook(options = {}) {
+    return JSON.stringify(buildAgentPlaybook(options), null, 2);
 }
 /**
  * Register the playbook as an MCP PROMPT as well, so hosts that surface
  * prompts (prompt pickers, slash commands) get the operating guide natively
  * without knowing to call the tool. Same content, second doorway.
  */
-export function registerPlaybookPrompt(server) {
+export function registerPlaybookPrompt(server, options = {}) {
     server.registerPrompt("summer_agent_playbook", {
-        title: "Summer Engine agent playbook",
-        description: "AI-first operating guide for the Summer Engine MCP tools: observe-first loop, screenshot before/after every mutation, content routing (reuse -> import -> generate -> script last), physical invariants, cost rules, verification ritual, honesty rules, and recovery steps.",
+        title: options.engine === false ? "Summer assets playbook" : "Summer Engine agent playbook",
+        description: options.engine === false
+            ? "Operating guide for the Summer assets tools without Summer Engine: ask what the asset is for, reuse before generating, confirm spend, check the preview, hand over the file."
+            : "AI-first operating guide for the Summer Engine MCP tools: observe-first loop, screenshot before/after every mutation, content routing (reuse -> import -> generate -> script last), physical invariants, cost rules, verification ritual, honesty rules, and recovery steps.",
     }, async () => ({
         messages: [
             {
                 role: "user",
                 content: {
                     type: "text",
-                    text: "Operate Summer Engine by this playbook for the rest of the session:\n\n" +
-                        renderAgentPlaybook(),
+                    text: (options.engine === false
+                        ? "Work with the Summer assets tools by this playbook for the rest of the session:\n\n"
+                        : "Operate Summer Engine by this playbook for the rest of the session:\n\n") +
+                        renderAgentPlaybook(options),
                 },
             },
         ],
     }));
 }
-export function registerProjectTools(server) {
+export function registerProjectTools(server, options = {}) {
     server.tool("summer_start_game_task", `Start here for any substantial AI game-building task.
 
 Takes the user's goal and returns the recommended Summer workflow: skill routes,
@@ -102,6 +107,7 @@ mutating the project.`, {
                     target,
                     assetPolicy,
                     verification,
+                    engine: options.engine,
                 }), null, 2),
             },
         ],
@@ -115,7 +121,7 @@ ladder, honesty rules, anti-patterns, and recovery steps.`, {}, async () => ({
         content: [
             {
                 type: "text",
-                text: renderAgentPlaybook(),
+                text: renderAgentPlaybook(options),
             },
         ],
     }));