summer-engine 3.8.0 → 4.0.0

package/library/tools/fabricate-3d/GUIDE.md

@@ -0,0 +1,19 @@
+# summer_fabricate_3d
+
+Fabricate a 3D mesh asset by running a Blender Python (bpy) script in the USER'S OWN installed Blender — headless, supervised by the engine — then import the exported .glb into the project and optionally instantiate it into the open scene. Blender is a dependency the user installs; Summer never bundles, downloads, or brands it.
+
+WHEN — the three asset classes neither generation nor the free library serve well:
+- 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, recipes and the fix for each failure_reason.
+
+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 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). There is no viewport feedback while the script runs, so keep scripts deterministic (fixed seeds) and verify afterwards.
+
+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. 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.

package/library/tools/frame-nodes/GUIDE.md

@@ -0,0 +1,9 @@
+# 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. 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.

package/library/tools/frame-shot/GUIDE.md

@@ -0,0 +1,9 @@
+# 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). 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. Saving the bookmark writes res://.summer/camera_bookmarks.json.

package/library/tools/game-control/GUIDE.md

@@ -0,0 +1,9 @@
+# summer_game_control
+
+Control the clock of the RUNNING game and list instances. action:'pause' suspends it (GamePause — Engine time frozen, physics inactive; SceneTree.paused untouched), 'resume' lifts the suspension, 'step' advances EXACTLY frames (1..600) of kind 'physics' (default) or 'process' and leaves the game suspended (GameStep), 'speed' sets the user time scale (GameSpeed, 0.25 = quarter speed), 'instances' lists every live game instance (ListGameInstances: name, mode, pid, attached, breaked, scene, seed, fixed_fps, deterministic, summer_capture).
+
+Frame stepping is how you make exact assertions: pause -> summer_game_probe -> act -> step 1 -> probe; the step result reports before/after frame counters, exact, overshoot, and draws the last stepped frame before replying so the following probe shows it. A minimized game window draws no frames and cannot step (timeout). step and pause answer game_breaked while the game sits at a breakpoint. GameSpeed rides a no-reply channel: acknowledged:false means the engine could not read the new time_scale back (older game build) — verify with summer_game_probe time_scale.
+
+'instances' is also the boot check after summer_play {instance, mode:'offscreen'}: address an instance only once attached:true (before that the ops answer request_failed). THE LOOP: summer_play (add instance + mode:'offscreen' for a disposable instance; deterministic:true + seed for a reproducible run; fixed_fps for exact timing) -> wait for boot (summer_is_running, or summer_game_control action:'instances' showing attached:true) -> summer_game_probe BEFORE (frame-stamped state + pixels) -> act (summer_runtime_set / summer_runtime_call / summer_game_input) -> summer_game_control action:'step' for exact frames, or let it run -> summer_game_probe AFTER -> assert on the two probes. Never claim something moved, spawned or fired without a probe that shows it.
+
+Needs a RUNNING game: failure_reason game_not_running (summer_play first), request_failed (debug session still attaching — wait, retry), unknown_instance (summer_game_control action:'instances'), game_breaked (the game sits at a breakpoint — continue it first), timeout (game wedged, minimized or breaked — summer_get_debugger_errors, or summer_stop + summer_play), unsupported (the running game predates the summer capture; restart it after updating). All runtime paths are ABSOLUTE ('/root/Main/Player') and come from summer_game_probe tree / summer_get_runtime_tree. On an engine build that predates these ops the result is a structured engine_lacks_op failure; the fallback for exact frames is a RunVerification probe awaiting physics_frame N times.

package/library/tools/game-input/GUIDE.md

@@ -0,0 +1,9 @@
+# summer_game_input
+
+Drive the RUNNING game's input like a player would. action:'script' schedules up to 1000 timed synthetic events (SimulateInputScript): [{at_frame: 0, type:'action', action:'move_right', hold_ms: 500}, {at_frame: 30, type:'action', action:'jump', hold_ms: 50}]; types action | key (keycode / physical_keycode) | mouse_click (position [x,y], button) | axis (action_negative/action_positive, signed strength) | raw ({class, props} — a recorded InputEvent). clock 'frame' (at_frame, exact) or 'ms' (at_ms — exact only when the instance runs with fixed_fps, else approximate; the result reports clock_mapping). action:'record_start' / 'record_stop' capture the game's REAL input into res://.summer/replays/<id>.json (InputRecordStart/Stop — cap 20,000 events / ~1 MiB, truncated:true when hit); action:'replay' plays a recording (or inline events) back (InputReplay), with seed asserting reproducibility on a deterministic offscreen instance.
+
+script returns {scheduled, applied, rejected[{index, failure_reason, error}], first_frame, last_frame, completed, clock_mapping}; per-event rejections (unknown_action: not in the project InputMap — summer_input_map_bind, or use type:'key') are non-fatal unless all_rejected. ONE script in flight per instance: a second call answers busy — wait for the first. wait:true (default) blocks until the last event fires but the engine caps it at 20 s; a longer script uses wait:false and observes with summer_game_probe. replay returns the same shape plus {recording, deterministic}; seed on an instance not started with summer_play {mode:'offscreen', deterministic:true} answers nondeterministic_instance.
+
+Scripts vs recordings: a script is the readable, editable repro you write from the spec; a recording is the exact repro of what a human (or a script) actually did — replay it on a deterministic instance for an A/B under identical inputs. Input is an ACTION: prove what it caused with summer_game_probe before/after (or summer_game_control action:'step' for the exact frame). THE LOOP: summer_play (add instance + mode:'offscreen' for a disposable instance; deterministic:true + seed for a reproducible run; fixed_fps for exact timing) -> wait for boot (summer_is_running, or summer_game_control action:'instances' showing attached:true) -> summer_game_probe BEFORE (frame-stamped state + pixels) -> act (summer_runtime_set / summer_runtime_call / summer_game_input) -> summer_game_control action:'step' for exact frames, or let it run -> summer_game_probe AFTER -> assert on the two probes. Never claim something moved, spawned or fired without a probe that shows it.
+
+Needs a RUNNING game: failure_reason game_not_running (summer_play first), request_failed (debug session still attaching — wait, retry), unknown_instance (summer_game_control action:'instances'), game_breaked (the game sits at a breakpoint — continue it first), timeout (game wedged, minimized or breaked — summer_get_debugger_errors, or summer_stop + summer_play), unsupported (the running game predates the summer capture; restart it after updating). All runtime paths are ABSOLUTE ('/root/Main/Player') and come from summer_game_probe tree / summer_get_runtime_tree. engine_lacks_op on an older build names the fallback (single SimulateInput ops via summer_batch, or a RunVerification probe's press()/key()).

package/library/tools/game-probe/GUIDE.md

@@ -0,0 +1,9 @@
+# summer_game_probe
+
+State AND pixels of ONE frame of the RUNNING game, atomically (GameProbe): the live scene tree (tree {path, depth, limit}), up to 64 property reads (props ['/root/Main/Player:position', '/root/Main/HUD/Health:value']) and a screenshot of the game viewport, all stamped with the SAME frame counters. This is the evidence tool of the playtest loop — the only read where "what the tree says" and "what the screen shows" cannot come from different moments.
+
+You SEE the screenshot as an image block; the text block carries the frame stamp ({frame: {process_frames, physics_frames, frames_drawn}, image_frame, suspended, paused, time_scale}), values {key: Godot literal string}, missing[] (keys that did not resolve — a typo or a node that is gone), tree/total_nodes/truncated. Two probes around an action are a claim's proof: cite both frame numbers. screenshot:false is the cheap state-only read (works when the window draws nothing). max_dim (default 1280) bounds the image. Unlike summer_screenshot target:'game', the capture happens game-side, so it works for offscreen and floating instances.
+
+THE LOOP: summer_play (add instance + mode:'offscreen' for a disposable instance; deterministic:true + seed for a reproducible run; fixed_fps for exact timing) -> wait for boot (summer_is_running, or summer_game_control action:'instances' showing attached:true) -> summer_game_probe BEFORE (frame-stamped state + pixels) -> act (summer_runtime_set / summer_runtime_call / summer_game_input) -> summer_game_control action:'step' for exact frames, or let it run -> summer_game_probe AFTER -> assert on the two probes. Never claim something moved, spawned or fired without a probe that shows it.
+
+Needs a RUNNING game: failure_reason game_not_running (summer_play first), request_failed (debug session still attaching — wait, retry), unknown_instance (summer_game_control action:'instances'), game_breaked (the game sits at a breakpoint — continue it first), timeout (game wedged, minimized or breaked — summer_get_debugger_errors, or summer_stop + summer_play), unsupported (the running game predates the summer capture; restart it after updating). All runtime paths are ABSOLUTE ('/root/Main/Player') and come from summer_game_probe tree / summer_get_runtime_tree. A probe still answers while the game is breaked. On an engine build that predates GameProbe the result is a structured engine_lacks_op failure; fall back to summer_get_runtime_tree + summer_screenshot target:'game' (two calls, two frames).

package/library/tools/generate-3d/resource.yaml

@@ -1,7 +1,7 @@
 id: tool/generate-3d
 kind: tool
 version: 1.0.2
-summary: Generate a 3D model from text or images via Summer Studio, with optional auto-rig and animation pipeline; waits or returns a job id.
+summary: Generate a 3D model from text or images via Summer Studio, with optional auto-rig and animation pipeline; returns a job id to poll with summer_check_job.
 use_when:
   - creating a 3D asset or character from a prompt or reference image
   - '"make me a low-poly tree / a sci-fi crate / a goblin for my game"'
@@ -95,8 +95,8 @@ input_schema:
       description: Character height used by auto-rigging
     wait:
       type: boolean
-      default: true
-      description: Wait for completion (default true, up to 10 min). Set false to get jobId immediately.
+      default: false
+      description: 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:
       type: object
       additionalProperties: {}

package/library/tools/generate-motion/resource.yaml

@@ -82,8 +82,8 @@ input_schema:
       description: Stable retry key so the same logical request is not billed or queued twice
     wait:
       type: boolean
-      default: true
-      description: Wait for completion (default true, up to 10 min). Set false to get jobId immediately.
+      default: false
+      description: 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:
       type: object
       additionalProperties: {}

package/library/tools/get-console/GUIDE.md

@@ -0,0 +1,9 @@
+# summer_get_console
+
+Read recent messages from the editor's Output panel (print() output, editor-side warnings and errors).
+
+SCOPE: the editor console ONLY. Runtime errors from a played game are collected by the debugger, not the console — right after summer_play this tool can honestly report errors 0 while summer_get_debugger_errors holds several. Never treat this tool alone as the post-play verdict: read summer_get_diagnostics (console + debugger + script errors together) first, then come here for message bodies. Every result carries a "_scope" note restating this.
+
+Output is post-processed for token economy: consecutive identical messages collapse into one entry with a "(×N)" count suffix, and the response carries a "_filter" summary so you can see what was hidden. Message types come straight from the editor log (error / warning / std / editor); errors_only=true (default) drops the std/editor lines — startup banners and print() output — and keeps errors and warnings. Use errors_only=false to read print() output, raw=true to bypass all shaping.
+
+Use after summer_get_diagnostics indicates console issues, or to check what your print() statements said.

package/library/tools/get-console/resource.yaml

@@ -60,6 +60,11 @@ input_schema:
       type: boolean
       default: false
       description: Bypass dedupe and level filtering — return engine output verbatim
+    maxCharacters:
+      type: integer
+      minimum: 500
+      maximum: 1000000
+      description: Most characters of text to return (default 4000). A longer result is cut and says so.
   additionalProperties: false
 authority:
   filesystem: false

package/library/tools/get-debugger-errors/GUIDE.md

@@ -0,0 +1,7 @@
+# summer_get_debugger_errors
+
+Read runtime errors from the debugger. These occur while the game is running (null references, missing nodes, physics errors). Different from console output — these come from the debugger, not print statements.
+
+For warning text, use summer_get_debugger_warnings (separate tool — engine returns warning count here but not the bodies).
+
+Output is deduped: identical errors firing every frame collapse into one entry with a "(×N)" count suffix. A "_filter" summary tells you exactly what was collapsed or truncated. Use raw=true to bypass shaping when you really need every entry.

package/library/tools/get-debugger-errors/resource.yaml

@@ -47,6 +47,11 @@ input_schema:
       type: boolean
       default: false
       description: Bypass dedupe — return engine output verbatim
+    maxCharacters:
+      type: integer
+      minimum: 500
+      maximum: 1000000
+      description: Most characters of text to return (default 4000). A longer result is cut and says so.
   additionalProperties: false
 authority:
   filesystem: false

package/library/tools/get-debugger-warnings/GUIDE.md

@@ -0,0 +1,7 @@
+# summer_get_debugger_warnings
+
+Read runtime warnings from the debugger panel. Warnings are non-fatal issues the game flags during play: missing optional resources, dead signal connections, deprecated API use, large allocations, physics warnings, etc.
+
+Returns structured entries with file/line/function/error_descr/callstack — same shape as summer_get_debugger_errors but filtered to severity = "warning". Engine-internal warnings without a source file are filtered out as noise.
+
+Use this when summer_get_diagnostics shows a non-zero `debugger.warnings` count and you want to see what they actually say.

package/library/tools/get-debugger-warnings/resource.yaml

@@ -43,6 +43,11 @@ input_schema:
       type: boolean
       default: false
       description: Bypass dedupe
+    maxCharacters:
+      type: integer
+      minimum: 500
+      maximum: 1000000
+      description: Most characters of text to return (default 4000). A longer result is cut and says so.
   additionalProperties: false
 authority:
   filesystem: false

package/library/tools/get-diagnostics/GUIDE.md

@@ -0,0 +1,13 @@
+# summer_get_diagnostics
+
+Quick overview of all errors and warnings from the editor console, the runtime debugger, and script errors together. Returns error counts and a guidance message.
+
+ALWAYS call this FIRST before diving into summer_get_console or summer_get_debugger_errors. It tells you where to look. It is also THE post-play read: a played game's runtime errors land in the debugger section here (and in summer_get_debugger_errors), never in the editor console — summer_get_console alone can honestly report errors 0 right after a play session that produced several.
+
+By default the response is a prioritized view: errors first, then warnings, then a small capped tail of recent info/std noise. Counts (console totals, debugger totals) are always complete — only low-severity message bodies are trimmed, and a "_view" block reports exactly what was suppressed. Pass includeAll: true for the full untrimmed engine payload.
+
+Typical workflow after making changes or playing:
+1. summer_get_diagnostics — are there issues? (after a play session: check debugger.errors)
+2. If errors: summer_get_debugger_errors (runtime, with stacks) or summer_get_console (editor output) for details
+3. Fix the issues
+4. summer_get_diagnostics again to verify

package/library/tools/get-project-context/GUIDE.md

@@ -0,0 +1,25 @@
+# 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)
+- 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. It also binds the session to the open project.
+
+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'.

package/library/tools/get-runtime-tree/GUIDE.md

@@ -0,0 +1,7 @@
+# summer_get_runtime_tree
+
+Scene tree of the RUNNING GAME — live runtime state, not the edited scene. Use it during playtests to see what actually spawned: dynamically created enemies/projectiles/UI, autoloads, pooled nodes — everything summer_get_scene_tree (an EDITOR read) can never show. Inspecting live keeps the bug alive; stopping the game to look usually resets it.
+
+Returns {tree: {name, class, path, children}, total_nodes, truncated}. Depth/limit are capped and truncation is declared — never assume a capped tree is complete. Drill into one node's live properties with summer_inspect_runtime_node.
+
+Needs a running game: fails with failure_reason "game_not_running" otherwise — start with summer_play, then re-run.

package/library/tools/get-runtime-tree/resource.yaml

@@ -53,6 +53,11 @@ input_schema:
       type: integer
       exclusiveMinimum: 0
       description: Maximum nodes to return (engine default 500).
+    maxCharacters:
+      type: integer
+      minimum: 500
+      maximum: 1000000
+      description: Most characters of text to return (default 4000). A longer result is cut and says so.
   additionalProperties: false
 authority:
   filesystem: false

package/library/tools/get-scene-tree/GUIDE.md

@@ -0,0 +1,11 @@
+# summer_get_scene_tree
+
+Get a scene tree. Pass scenePath to read that exact in-memory/open scene;
+omit it only when you intentionally want the currently visible editor scene.
+Scene mutations load their explicit target, so a follow-up targeted read does
+not require OpenScene.
+
+The engine defaults to depth 2 and limit 200 nodes and SILENTLY truncates
+deeper hierarchies (the response then carries truncated: true and a visited
+count lower than the real node count). Pass an explicit depth (e.g. 10) to
+read a full tree — a 102-node scene returns only 61 nodes at the defaults.

package/library/tools/get-scene-tree/resource.yaml

@@ -43,6 +43,11 @@ input_schema:
       type: integer
       exclusiveMinimum: 0
       description: Maximum number of nodes to return. Engine default is 200.
+    maxCharacters:
+      type: integer
+      minimum: 500
+      maximum: 1000000
+      description: Most characters of text to return (default 8000). A longer result is cut and says so.
   additionalProperties: false
 authority:
   filesystem: false

package/library/tools/get-script-errors/GUIDE.md

@@ -0,0 +1,5 @@
+# summer_get_script_errors
+
+Check a GDScript file for parse/compile errors without running the game.
+
+Use after writing or editing a .gd file to verify it compiles. Returns line numbers, error messages, and severity. Much faster than running the game to discover script errors.

package/library/tools/grep/GUIDE.md

@@ -0,0 +1,11 @@
+# summer_grep
+
+Search project files with a regular expression (ripgrep, through the engine) and get file + line + text per match, optionally with context lines around each.
+
+Use it to find things in big files without reading them whole: every '"fits_into"' in a kit manifest, the scenes of a kit (glob '*.tscn'), where a signal handler is defined. Then read exactly the part you need with summer_read_file (offset/limit, or json_path for JSON).
+
+- path: a res:// directory or file (default: the whole project; .godot/ and .import/ are never searched).
+- glob: ripgrep --glob filter ('*.gd', '**/*.json', '!addons/**'). Ripgrep skips files ignored by .gitignore unless a glob names them.
+- context_lines (0-10): lines before/after each match, as before[] / after[].
+- max_results (default 50, max 500) caps the matches; truncated:true says there were more. Lines are clipped to max_line_chars.
+Case-insensitive unless case_sensitive:true. Read-only.

package/library/tools/import-asset/GUIDE.md

@@ -0,0 +1,8 @@
+# summer_import_asset
+
+Search the asset library and import the best match into the project in one step.
+
+Use when the user wants a specific type of asset added: "Add a tree to the scene", "Import a wooden barrel".
+Searches, picks the top result, downloads and imports it, then optionally adds it to the scene.
+
+Requires authentication. If the user gets an auth error, they need to run 'npx -y summer-engine@latest login' in their terminal first. Summer Engine must be running.

package/library/tools/import-asset-by-id/GUIDE.md

@@ -0,0 +1,12 @@
+# summer_import_asset_by_id
+
+Import an exact Summer asset ID into the current project.
+
+Use this when the asset was just generated, selected from my assets, or returned
+by search. Unlike summer_import_asset, this does not search or guess: it fetches
+the asset by ID, downloads it through Summer Engine, and runs Godot's import
+pipeline. For 3D models, pass parent and scenePath to instantiate it in that
+exact scene; it does not need to be the active editor tab.
+
+Requires the Summer Engine app to be open with the project loaded (generation
+itself does not — only this import step does).

package/library/tools/import-from-url/GUIDE.md

@@ -0,0 +1,10 @@
+# summer_import_from_url
+
+Download a file from a URL and import it into the project. Triggers Godot's full import pipeline — generates .import files, extracts textures from .glb models, creates materials.
+
+Use this for:
+- 3D models (.glb, .gltf, .obj)
+- Textures (.png, .jpg, .webp)
+- Audio (.ogg, .wav, .mp3)
+
+The path is auto-inferred from the URL filename if not specified. After import, the asset is immediately usable in scenes.

package/library/tools/import-from-url-batch/GUIDE.md

@@ -0,0 +1,3 @@
+# summer_import_from_url_batch
+
+Download multiple files from URLs in one operation. Performs a single filesystem scan after all downloads, which is faster than importing one at a time.

package/library/tools/import-hdri/GUIDE.md

@@ -0,0 +1,16 @@
+# summer_import_hdri
+
+Search Poly Haven's CC0 HDRI library and import one as environment lighting.
+
+The single cheapest visual-quality upgrade for a 3D scene: a real HDRI sky lights
+and reflects the whole world. Searches ~1,000 CC0 HDRIs on Poly Haven's public API
+(no account, no key), downloads the .hdr/.exr through the engine's import pipeline
+into res://sky/, and returns a ready-to-run summer_run_script snippet that wires it
+into the WorldEnvironment (PanoramaSkyMaterial + sky ambient/reflections).
+
+Pass query ("sunset beach", "night city", "studio") to search, or assetId for an
+exact Poly Haven id. resolution 2k is right for most games; 4k for hero skies.
+All results are CC0 — no attribution required.
+
+Requires the Summer Engine app to be open with the project loaded (the download
+runs through the engine). No Summer login needed.

package/library/tools/input-map-bind/GUIDE.md

@@ -0,0 +1,11 @@
+# summer_input_map_bind
+
+Set up input controls. Creates the action if it doesn't exist, then binds events to it.
+
+Event format:
+- Keyboard: { type: "key", key: "W" } or { type: "key", key: "Space" }
+- Mouse button: { type: "mouse_button", button: 1 } (1=left, 2=right, 3=middle)
+- Common keys: "W", "A", "S", "D", "Space", "Shift", "E", "Escape", "Up", "Down", "Left", "Right"
+
+Example: Bind jump to Space and W:
+  name: "jump", events: [{ type: "key", key: "Space" }, { type: "key", key: "W" }]

package/library/tools/inspect-asset/GUIDE.md

@@ -0,0 +1,14 @@
+# 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.

package/library/tools/inspect-asset/resource.yaml

@@ -60,6 +60,11 @@ input_schema:
       enum: [summary, full]
       default: summary
       description: "summary: open_loops lists only port-like loops (radius over 2 cm with a partner loop facing another way, or the one opening of an end piece on its bounding-box face), or none. full: every open loop, including the outline of flat sheets. Every loop has a stable id ('+Y', '+Y#2') that summer_connect_ports accepts. Both start with the summary block (AABB, origin, the two largest opposite plane pairs with one_sided flags, port-like loop ids)."
+    maxCharacters:
+      type: integer
+      minimum: 500
+      maximum: 1000000
+      description: Most characters of text to return (default 4000). A longer result is cut and says so.
   required:
     - path
   additionalProperties: false

package/library/tools/inspect-node/GUIDE.md

@@ -0,0 +1,11 @@
+# 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.
+
+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.

package/library/tools/inspect-node/resource.yaml

@@ -42,6 +42,11 @@ input_schema:
         type: string
       maxItems: 48
       description: "Only these fields: property names or globs (e.g. 'position', 'surface_material_override/*') and the derived fields transform, global_transform, scene_file_path, aabb, warnings. Omit for every property."
+    maxCharacters:
+      type: integer
+      minimum: 500
+      maximum: 1000000
+      description: Most characters of text to return (default 4000). A longer result is cut and says so.
   required:
     - path
   additionalProperties: false

package/library/tools/inspect-resource/GUIDE.md

@@ -0,0 +1,7 @@
+# summer_inspect_resource
+
+Read a resource: a material, mesh, shape, texture, environment, or a scene/model file.
+
+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.

package/library/tools/inspect-resource/resource.yaml

@@ -47,6 +47,11 @@ input_schema:
       minLength: 1
       maxLength: 128
       description: With nodePath, the node property holding the resource, e.g. 'mesh', 'material_override', 'shape', 'environment'.
+    maxCharacters:
+      type: integer
+      minimum: 500
+      maximum: 1000000
+      description: Most characters of text to return (default 4000). A longer result is cut and says so.
   additionalProperties: false
 authority:
   filesystem: false

package/library/tools/inspect-runtime-node/GUIDE.md

@@ -0,0 +1,7 @@
+# summer_inspect_runtime_node
+
+Live properties of ONE node in the RUNNING GAME: {node: {path, class, properties, children_names}} with a curated common-property set (transform, visibility, physics state, ...). The runtime counterpart of summer_inspect_node (which reads the EDITED scene) — use it to answer "what are this enemy's actual stats right now", "where IS the player", "did that flag flip" without stopping the game and losing the state.
+
+Find the path with summer_get_runtime_tree first — runtime paths (e.g. '/root/Main/Enemies/Goblin3') often differ from edited-scene paths because nodes are spawned, renamed, or reparented at runtime.
+
+Needs a running game: fails with failure_reason "game_not_running" otherwise — start with summer_play, then re-run.

package/library/tools/inspect-runtime-node/resource.yaml

@@ -43,6 +43,11 @@ input_schema:
     path:
       type: string
       description: Runtime node path, e.g. '/root/Main/Player'. Get it from summer_get_runtime_tree.
+    maxCharacters:
+      type: integer
+      minimum: 500
+      maximum: 1000000
+      description: Most characters of text to return (default 4000). A longer result is cut and says so.
   required:
     - path
   additionalProperties: false

package/library/tools/instantiate-scene/GUIDE.md

@@ -0,0 +1,12 @@
+# summer_instantiate_scene
+
+Add an existing scene or 3D model as a child node. Use this to:
+- Add a .tscn prefab (reusable scene) as a child
+- Add a .glb/.gltf 3D model into the scene
+- Compose scenes from smaller scenes (e.g., add a "Player" scene into a "Level" scene)
+
+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.
+
+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.

package/library/tools/is-running/GUIDE.md

@@ -0,0 +1,3 @@
+# summer_is_running
+
+Check if the game is currently running. Returns the active scene path if running.

package/library/tools/measure/GUIDE.md

@@ -0,0 +1,8 @@
+# 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.

package/library/tools/navigation-probe/GUIDE.md

@@ -0,0 +1,9 @@
+# summer_navigation_probe
+
+Inspect whether two explicit world-space points are connected by the targeted 3D scene's built-in Godot navigation map without changing or saving the scene.
+
+Returns navigation readiness and its reason, map iteration and region counts, requested and layer-filtered snapped endpoints, snap distances, conservative reachability, full route length, and at most 16 deterministic route points. A path is reachable only when it terminates at both snapped endpoints within the reported tolerance.
+
+ready:false means navigation evidence is unavailable, not that the route is unreachable. In particular, map iteration 0 precedes the first usable synchronization and can return silently empty paths; iteration 1 and later are usable. evidence is always navigation. Normal results are capped below 5 KB.
+
+Always pass an exact scenePath and finite world-space start/end points. This read-only tool never uses editor selection, creates undo history, or calls SaveScene. On an engine build that predates NavigationProbe3D the result is a structured engine_lacks_op failure naming the fallback.

package/library/tools/open/resource.yaml

@@ -9,7 +9,7 @@ use_when:
   - 'handing the user a link instead of opening a browser (open: false), or checking which destination an intent maps to'
   - resolving where a user intent lives ("where do I change my plan?") before acting
 do_not_use_when:
-  - the user wants a result, not a view — add the node, set the property, publish; use the mutation tools (summer_add_node, summer_set_prop, summer_publish_build)
+  - the user wants a result, not a view — add the node, set the property, publish; use the mutation tools (summer_add_node, summer_set_prop, store.publish)
   - opening a project directory in the engine — that is the CLI's `summer open <path>` / `summer run <path>` project launcher, not a navigation target
   - the destination is not on summerengine.com or docs.summerengine.com — the tool refuses other origins
 facets:
@@ -73,7 +73,7 @@ input_schema:
 authority:
   filesystem: false
   editor_mutation: false
-  network: false
+  network: true
   credentials: false
   publish: false
 evidence_checks:

package/library/tools/open-main-scene/GUIDE.md

@@ -0,0 +1,6 @@
+# summer_open_main_scene
+
+Open the project's configured main scene from project settings.
+
+Safer than guessing scene names like main.tscn/Main.tscn.
+Call this when you get "no scene open".

package/library/tools/open-scene/GUIDE.md

@@ -0,0 +1,8 @@
+# summer_open_scene
+
+Open a scene file in the editor. Use this to switch between scenes.
+
+Do not guess paths. Prefer:
+1) summer_get_project_context (read mainScene)
+2) summer_open_main_scene (open known main scene)
+3) summer_open_scene only when user gave an explicit path.

package/library/tools/place-adjacent/GUIDE.md

@@ -0,0 +1,7 @@
+# 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).

package/library/tools/play/GUIDE.md

@@ -0,0 +1,13 @@
+# 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 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.
+
+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; 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 (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.