summer-engine 3.8.0 → 4.0.0

package/library/tools/project-setting/GUIDE.md

@@ -0,0 +1,9 @@
+# summer_project_setting
+
+Set a project setting in project.godot. Common settings:
+- "application/config/name" — project name
+- "application/run/main_scene" — main scene path
+- "rendering/renderer/rendering_method" — "forward_plus", "mobile", or "gl_compatibility"
+- "display/window/size/viewport_width" — window width
+- "display/window/size/viewport_height" — window height
+- "physics/3d/default_gravity" — gravity value (float)

package/library/tools/publish-build/resource.yaml

@@ -1,6 +1,6 @@
 id: tool/publish-build
 kind: tool
-version: 1.0.0
+version: 1.0.1
 summary: Upload an export from summer_export_game to the creator's store game, confirm-gated - a store bundle as a Build, or a web or native download as a store version.
 use_when:
   - '"upload my game to summer.games"'
@@ -13,9 +13,9 @@ use_when:
 do_not_use_when:
   - the user has not approved the exact game, file, digest, version and publish choice
   - the game is not exported yet — summer_export_game first
-  - store page text, art or price — summer_store_update_listing, summer_store_set_art (mounted after summer login --store)
-  - making the build live — summer_store_submit (the owner approves publishing), then summer_build_release
-  - what players get now — summer_store_releases
+  - store page text, art or price — store.update_listing, store.set_art (hosted, after summer login --store)
+  - making the build live — store.publish (the owner approves publishing), then store.release
+  - what players get now — store.status
 facets:
   lifecycle:
     - launch
@@ -26,7 +26,7 @@ compatibility:
   engine: ">=4.6"
 source: official
 license: MIT
-status: preview
+status: stable
 aliases:
   - summer_publish_build
 implementation:
@@ -41,7 +41,7 @@ input_schema:
   properties:
     gameId:
       type: string
-      description: The store game id (from summer_store_list_games, or the Studio store page URL). Without it the call fails with game_required and lists your store games, or says why the store did not list them.
+      description: The store game id (from games.list, or the Studio store page URL). Without it the call fails with game_required and lists your store games, or says why the store did not list them.
     file:
       type: string
       description: Exported .zip. Defaults to the last summer_export_game result.

package/library/tools/raycast/GUIDE.md

@@ -0,0 +1,7 @@
+# summer_raycast
+
+Cast one ray from any point in an open scene, before anything is placed there: find the wall, floor or ceiling in front of a point and its normal. (summer_starcast casts from an existing node's bounds; this casts from an arbitrary origin.)
+
+evidence auto (default): physics first (collider hit: exact point and normal); if physics hits nothing, the nearest visible-mesh AABB hit, declared with fallback:true and fallback_reason. Physics needs the scene to be the active editor tab (only that scene's bodies are in the editor's physics space); otherwise auto falls back to visual AABBs. When physics hits but a mesh-only object is nearer, nearer_visual_only names it.
+
+Returns {hit, evidence, path, point, normal, distance, origin, direction, physics_available, warnings}. Read-only (RunSceneScript probe, undo "none"); never saves.

package/library/tools/read-file/GUIDE.md

@@ -0,0 +1,10 @@
+# summer_read_file
+
+Read a text file from the engine-bound project and return its full-file sha256 receipt.
+
+Use the returned sha256 as expected_sha256 when overwriting an existing file. Paths must begin with res://.
+
+READ BIG FILES IN PARTS instead of all at once:
+- offset + limit page the file: lines by default (unit:'bytes' for a byte range on UTF-8 boundaries). The result's data.window gives start_line/end_line, total_lines, next_offset (null at the end) and eof.
+- For JSON: json_path picks one value ('pieces.wall_a', 'items[3]'); keys keeps matching object keys (['wall_*']); keys_only lists key names only. data.json says what matched. offset/limit then page the selection.
+The sha256 always covers the WHOLE file, so a windowed read still guards a later overwrite. Files over 1 MB can be paged only within their first 1 MB.

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

@@ -56,6 +56,11 @@ input_schema:
         - resource
         - all
       description: skill = the body only (SKILL.md for skills, markdown body for references, how-to-call for tools, pin for templates); resource = the resource.yaml descriptor only; all (default) = both.
+    maxCharacters:
+      type: integer
+      minimum: 500
+      maximum: 1000000
+      description: Most characters of text to return (default 24000). A longer result is cut and says so.
   required:
     - id
   additionalProperties: false

package/library/tools/recent-events/GUIDE.md

@@ -0,0 +1,7 @@
+# summer_recent_events
+
+Read the newest engine events in ONE zero-wait poll — what just happened (saves, plays, op receipts, script errors, imports, selection) and, above all, the CURSOR: its next_seq is the `since` to hand summer_wait_for_event BEFORE you trigger the action you will wait on.
+
+since omitted = the newest `limit` sequence numbers (a kinds filter applies inside that window, so fewer may come back). since:0 = the whole retained ring from the oldest, paged — pass next_seq back as since while truncated is true. since:N = everything after N.
+
+Each event is {seq, kind, ts, data}; kinds (v1): op.applied, op.failed, script.error, play.started, play.stopped, scene.saved, scene.opened, import.completed, selection.changed, snapshot.published. The engine retains 512 events / 10 minutes — older history is gone, so an empty result is not proof nothing happened earlier. Payloads over 4 KB arrive clamped with truncated:true inside data. On an engine build without the events channel the result is a structured engine_lacks_events failure (nothing sent).

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

@@ -0,0 +1,3 @@
+# summer_remove_node
+
+Remove a node from the scene tree. All children are removed too. Cannot remove the root node. Supports undo. Destructive operation: do not delete multiple top-level nodes unless the user explicitly requests destructive changes.

package/library/tools/repeat-along/GUIDE.md

@@ -0,0 +1,5 @@
+# summer_repeat_along
+
+Instance copies of one scene along a straight line in one call: wall clamps every 0.45 m, braces every 0.8 m, fence posts, a row of window modules. Give start plus end (with spacing or count) or start plus direction (with count and spacing); positions are in the parent's local space. align (start|center|end) places the leftover length when spacing does not divide the line. Each copy is an InstantiateScene (the engine runs each alone), named <namePrefix>_<n>; the copies' transforms (position, rotationDegrees, scale) are then set in one request and the scene is saved once: N copies cost N + 2 engine requests. At most 64 copies per call.
+
+Returns a compact receipt: {count, spacing, first, last, created [node paths], renamed, failures [{index, error}], saved}. Lists are cut to stay under 5 KB and the cut is declared.

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

@@ -0,0 +1,9 @@
+# summer_replace_node
+
+Replace a node with a different scene/model or node type, keeping its parent, sibling index, name, transform and property overrides, and the children the scene added under it. Use it to swap a kit piece for another (a wall host for a door host), a placeholder for a prefab, or a StaticBody3D for a RigidBody3D.
+
+Give exactly one of scene or type. The scenePath must be a .tscn.
+
+PERSISTENCE IS VERIFIED: the tool saves, reads the saved .tscn back and checks that the node at path now instances the new scene (or has the new type), under the same parent, with every child present. persisted:true is proven from the file; a mismatch is an error with failure_reason not_persisted — never report that as done.
+
+How: a scene swap runs as InstantiateScene (temporary name) -> SetProp each property override -> ReparentNode the children -> MoveNode to the old index -> RemoveNode the old node -> rename -> SaveScene, because the engine's own ReplaceNode keeps the OLD scene reference in the saved file. A type change of a plain node uses the engine's ReplaceNode. State that cannot travel (groups, signal connections, scene-local sub_resource values, overrides of nodes inside the old scene) is listed in not_carried_over. Undo takes one Ctrl+Z per step.

package/library/tools/replace-text/GUIDE.md

@@ -0,0 +1,5 @@
+# summer_replace_text
+
+Safely replace text in an existing project file through the identity-bound engine.
+
+The MCP server reads the complete file, requires a unique match by default, computes the new content, and submits a sha256-guarded WriteFile. Set replace_all:true only when every exact occurrence should change.

package/library/tools/run-editor-script/GUIDE.md

@@ -0,0 +1,16 @@
+# summer_run_editor_script
+
+Run a GDScript EditorScript in a FRESH HEADLESS editor spawned against the ON-DISK project. Cold path: a whole child editor boots, runs your script once, and exits — seconds to tens of seconds depending on the project and the script (about 2 s end to end on a small template project; large projects can spend 30 s+ just booting).
+
+USE FOR batch/project-wide jobs that should not block the live editor: re-saving many scenes, sweeping resources, mass import fixes, generating .tres assets, long bakes. It sees ONLY what is saved on disk — unsaved live edits in the open editor are INVISIBLE to it, and the live editor won't show its output until files reload. For work on the OPEN scene, use summer_run_script instead.
+
+SCRIPT CONTRACT — write a plain EditorScript body:
+
+  func _run():
+      var scene = load("res://main.tscn").instantiate()
+      # ... work ...
+      print("done")  # captured into output[]
+
+You may omit the '@tool' and 'extends EditorScript' lines — the engine prepends any that are missing and reports each fix in 'normalizations' (with 'line_offset' so error line numbers map back to your source). Including 'extends EditorScript' yourself is also fine.
+
+Returns {ok, ran, exit_code, output, errors, boot_errors, result, out_dir, checkpoint, normalizations} plus a failure_reason taxonomy on failure (script_parse_failed, timeout, spawn_failed, ...). A top-level no_rewind_point:true means no pre-run checkpoint exists — the run is NOT rewindable; tell the user before doing more destructive work. This headless child has NO renderer: screenshots/pixels are impossible here (see the headless-scripting skill).

package/library/tools/run-script/GUIDE.md

@@ -0,0 +1,30 @@
+# summer_run_script
+
+Run a GDScript snippet INSIDE the live editor, against the scene named by scenePath (opened first when it is not the edited one; the person's tab comes back after the run). Without scenePath it runs against the currently OPEN scene. This is the scene-scripting workhorse: one script replaces long chains of add-node/set-prop calls, and it can compute (loops, randomness, math, procedural meshes) what individual CRUD ops cannot.
+
+SCRIPT CONTRACT — write ONLY the body below; do not add extends/@tool lines (missing ones are prepended and reported in 'normalizations'):
+
+  func run(ctx):
+      var root = ctx.get_scene_root()    # root node of the open scene
+      for i in range(10):
+          var m := MeshInstance3D.new()
+          m.mesh = BoxMesh.new()
+          m.position = Vector3(i * 2, 0, 0)
+          root.add_child(m)
+          ctx.set_owner_recursive(m)     # REQUIRED or the node is NOT saved
+      ctx.report("count", 10)            # structured value back to you
+
+- ctx.get_scene_root() — the open scene's root node. Full editor API access.
+- ctx.set_owner_recursive(node) — stamps node AND its descendants with the scene-root owner (equivalent to node.owner = root on each). Call it after add_child on every created subtree.
+- ctx.report(key, value) — return structured results (comes back in 'reports').
+- print(...) — captured and returned in 'output'.
+- OWNERSHIP: a created node whose owner is never set silently vanishes when the scene saves — descendants too. ctx.set_owner_recursive covers both.
+- Values here are real GDScript — Vector3(0,10,0), Color(1,0,0,1) — NOT the quoted variant strings used by summer_set_prop.
+
+Newer ctx builds also carry creation helpers that set the owner FOR you and return the node — prefer them: ctx.add_node(type, name, parent, props), ctx.find(name), ctx.get_or_create(type, name, parent), ctx.instance_scene(res_path, parent, name), ctx.add_mesh(shape, name, parent, props) / ctx.add_mesh_with_collision(...), ctx.mesh_from_arrays(...), ctx.make_material(props) / ctx.apply_material(node, material), ctx.grid(count_x, count_z, spacing, maker) / ctx.scatter(area, count, maker, seed), ctx.add_light_rig(target), ctx.ensure_environment(props), ctx.add_camera(position, look_at, make_current), ctx.summary(), ctx.save_scene(path). Unknown props keys are reported in 'prop_warnings', never silently dropped. On an older engine a missing helper is a plain GDScript error — fall back to the manual form above.
+
+WHEN TO USE: 3+ related ops, anything with computed placement (scatter, grids, rings), procedural geometry (SurfaceTool/ArrayMesh), bulk renames/retunes. For a single property tweak, summer_set_prop is cheaper. Use summer_api_docs to verify property/method names instead of guessing.
+
+THE LOOP: summer_world_snapshot (keep snapshot_id) -> summer_run_script -> summer_snapshot_diff + summer_screenshot -> inspect -> iterate. Never claim visual success without the screenshot.
+
+Returns {ok, ran, result, reports, output, errors, duration_ms, checkpoint} — newer engines add rolled_back (a runtime error rolled the whole undo action back; the scene is untouched) and budget_enforced (max_seconds was a HARD deadline; when the budget hits, the script errors with "Summer script budget exceeded" — split the work into smaller scripts, never resubmit the same oversized one). Read 'errors' even when ok — with undo:'none', a partially-failed script may have mutated the scene. If this engine build predates RunSceneScript, the result is a structured engine_lacks_op failure (nothing is sent): use summer_run_editor_script or update Summer Engine.

package/library/tools/run-script/resource.yaml

@@ -1,7 +1,7 @@
 id: tool/run-script
 kind: tool
-version: 1.0.1
-summary: Run a GDScript `func run(ctx):` inside the live editor against the open scene — one script instead of a chain of add-node/set-prop calls.
+version: 1.1.0
+summary: Run a GDScript `func run(ctx):` inside the live editor against scenePath — one script instead of a chain of add-node/set-prop calls.
 use_when:
   - a change needs 3+ related ops or any computed placement (scatter, grids, procedural meshes, bulk edits)
   - the ctx helpers (add_node, add_mesh, grid, scatter, light rig, environment) fit the job
@@ -31,7 +31,7 @@ related:
     - skill/verifying-scenes
 source: official
 license: MIT
-status: preview
+status: stable
 aliases:
   - summer_run_script
 implementation:
@@ -44,6 +44,9 @@ surfaces:
 input_schema:
   type: object
   properties:
+    scenePath:
+      type: string
+      description: The scene to run against, e.g. 'res://main.tscn'. Opened first when it is not the edited scene, then the person's tab is restored. Omit only to run against whatever scene is open.
     source:
       type: string
       description: GDScript source containing `func run(ctx):`. No extends/@tool line — just the function (plus any helpers).

package/library/tools/runtime-animate/GUIDE.md

@@ -0,0 +1,7 @@
+# summer_runtime_animate
+
+Drive and read animation in the RUNNING game. target:'player' = an AnimationPlayer (cmd state|play|pause|stop|seek|speed — RuntimeAnimation); target:'tree' = an AnimationTree state machine (cmd state|travel|start|stop|set_param|get_param — RuntimeAnimationTree); target:'bones' = a Skeleton3D's live bone poses (GetRuntimeBones, read-only). Default cmd is 'state' (read-only), so the same tool answers "which clip is playing", "which state is the machine in" and "where is the hand bone" before and after an action.
+
+player returns state {current_animation, assigned_animation, position, length, speed_scale, playing, animations[]}. tree returns state {active, current_node, travel_path, playing, position, length, fading_from, parameters{}}. bones returns {skeleton: {path, bone_count, motion_scale}, bones[{idx, name, parent, global_pose{origin, rotation, scale} | pose | rest}], truncated} — at most 256 bones per call; filter with bones[] to page larger rigs. unknown_animation / unknown_state / unknown_bone list the valid names in the error.
+
+Animation is motion: one 'state' read proves a clip is assigned, not that it moves. Prove motion with summer_game_control action:'step' between two reads (position advances, bone poses change) or two summer_game_probe frames. 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. target:'bones' and cmd:'state' still answer while the game is breaked; the mutating cmds do not. engine_lacks_op on an older build names the fallback.

package/library/tools/runtime-call/GUIDE.md

@@ -0,0 +1,7 @@
+# summer_runtime_call
+
+Call ONE method on a node in the RUNNING game and get its return value: 'take_damage' [25], 'get_velocity', 'has_method', 'start_wave' [3]. The direct way to trigger gameplay code and read its answer without wiring input or waiting for a timer.
+
+Returns {path, method, return, return_type, return_truncated, frame}; return is a Godot literal string for math values. Arguments are JSON scalars/arrays/objects or Godot literal strings ('Vector3(0, 1, 0)'); Object/RID arguments are refused (bad_args). failure_reason call_error carries call_error_detail (the method raised); method_not_found means check summer_api_docs / the node's script.
+
+Calling a method is an ACTION, not evidence: probe after it (summer_game_probe) to see what it did. 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; a game whose build predates the summer capture answers unsupported (no legacy fallback carries a return value).

package/library/tools/runtime-set/GUIDE.md

@@ -0,0 +1,9 @@
+# summer_runtime_set
+
+Set ONE property on a node in the RUNNING game — the live object, never the scene file (nothing is saved; the change dies with the run). Use it to put the game into the state you want to test without playing there by hand: teleport the player ('/root/Main/Player' position 'Vector3(0, 2, 0)'), set health to 1, flip a flag, toggle visibility.
+
+Returns {path, property, value_before, value_after, applied, transport, frame}. READ applied: false means the read-back did not match (failure_reason not_applied) — a script rewrites the value every frame, or the literal type was wrong. Math values in and out are Godot literal strings ('Vector3(1, 2, 3)'); 'script' and 'owner' are refused. For a persistent change edit the EDITED scene (summer_set_prop) and restart.
+
+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 SetRuntimeProp the result is a structured engine_lacks_op failure naming the fallback.

package/library/tools/runtime-spawn/GUIDE.md

@@ -0,0 +1,9 @@
+# summer_runtime_spawn
+
+Spawn a PackedScene into the RUNNING game (action:'spawn' — SpawnRuntimeScene) or free a live node (action:'free' — FreeRuntimeNode). Stage a test in seconds: drop three goblins under '/root/Main/Enemies' with props {position: 'Vector3(4, 0, -2)', health: 10}, or remove the boss to test the empty-arena path. Nothing touches the scene file.
+
+spawn returns {node: {path, class}, renamed_to?, prop_warnings[], frame} — use node.path (absolute) for follow-up set/call/probe; unknown props land in prop_warnings, they never fail the spawn. free returns {path, queued, freed}: mode 'queue_free' (default) frees at the end of the frame, so a probe on the SAME frame may still list the node — step one frame (summer_game_control action:'step') before asserting it is gone; 'free' is immediate. The scene root cannot be freed (refused_root).
+
+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 (summer_instantiate_scene / summer_remove_node in the EDITED scene, then restart).

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

@@ -0,0 +1,3 @@
+# summer_save_scene
+
+Save an explicit scene to disk. Mutation tools already append one save; use this for a standalone save or save-as.

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

@@ -0,0 +1,29 @@
+# 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 (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 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}] (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 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 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: 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.

package/library/tools/screenshot/GUIDE.md

@@ -0,0 +1,17 @@
+# summer_screenshot
+
+Capture a frame from Summer Engine and return it as an image you can look at directly.
+
+Use this to visually verify your work: scene layout, asset placement, scale, framing, missing/untextured assets, or runtime gameplay state. You see the actual pixels — no description layer in between. Lighting and materials are only truthfully shown by the "viewport" and "game" targets — see the note on "scene" below.
+
+target:
+  "viewport" (default) — the editor's CURRENT view (whatever scene/tab is open). No game boot. Use for edit-time checks of how the scene looks right now.
+  "scene" — an OFFSCREEN render of a scene file (no game boot; scripts do not run, physics/particles/animations are static at t=0, so runtime-hidden UI shows as saved). Optionally pass scenePath/framing/size/nodePath. Use for COMPOSITION, SCALE and FRAMING without touching the editor's open tab.
+    With the preset framings (iso/top/...), it does NOT use the scene's environment/sky, and it injects a synthetic camera and light when the scene has none. The scene's WorldEnvironment — sky, fog, tonemap, glow, SSAO, ambient — is replaced by a flat preview environment. So those framings CANNOT verify lighting, mood, or any material property that depends on the environment: change them and the frame comes back identical.
+    framing:"camera" is the exception and the trustworthy way to check lighting edit-time: it renders through the scene's OWN current/first Camera3D (or the one named by camera_path) with the scene's REAL WorldEnvironment — sky, fog, tonemap, glow, ambient all live. Use it before/after any lighting, environment, or emissive-material change, and to see the scene the way the played game will actually frame it.
+    STABLE VIEWPOINTS (newer engines): framing:"bookmark" + bookmark_name renders from a pose saved with summer_camera_bookmark, and framing:"free" from an explicit camera_position / camera_look_at (+ fov). Both are fixed synthetic poses rendered with the scene's REAL WorldEnvironment, and the same pose every time — the way to take before/after frames that actually line up. marks:true draws a Set-of-Mark overlay (numbered tags + boxes over the largest visible 3D nodes, up to max_marks) and the caption lists label -> node path, so you can say "label 3 (Props/Crate_02) is floating" instead of guessing. The scene file is never touched. 2D scenes render normally with marks_unsupported. Older engines resolve the new framings to a preset and ignore marks — the caption says so; a frame from such a build is NOT pose-stable.
+  "game" — a frame from the RUNNING game (real runtime state). Start the game first (summer_play). Works over the plain local connection on current Summer Engine builds (verified on 0.5.65, about 1.4 s); if a build refuses with bridge_required the result says so and names the alternatives.
+
+BLANK FRAMES ARE A CAPTURE CONDITION, NOT A SCENE FACT. A uniformly black/grey "viewport" frame means the editor had not redrawn its viewport texture when it was read (typically right after a tab switch or a scene mutation) — not that the scene is dark or has no camera. Every frame is content-checked; a flat viewport frame is recaptured once automatically and the caption says what happened. Never conclude anything about lights, cameras, or content from a blank frame: recapture first.
+
+Static frame only — one moment, not motion. For a SEQUENCE of frames over time, or for anything lighting-dependent on an engine build without framing:"camera", use a RunVerification probe's save_frame(name) — its instance has a real renderer.

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

@@ -0,0 +1,3 @@
+# summer_select_node
+
+Select a node in the editor's scene tree and show it in the inspector panel. Useful for focusing the editor on a specific node.

package/library/tools/set-prop/GUIDE.md

@@ -0,0 +1,23 @@
+# summer_set_prop
+
+Set a property on a node. This is the primary way to configure nodes after adding them.
+
+VALUE FORMAT — Godot string syntax for complex types:
+- Vector3: "Vector3(0, 10, 0)" — position, scale, rotation_degrees
+- Vector2: "Vector2(100, 200)" — 2D position, size
+- Color: "Color(1, 0.5, 0, 1)" — RGBA, always 4 components, values 0.0-1.0
+- Transform3D: "Transform3D(1,0,0, 0,1,0, 0,0,1, 0,5,0)" — basis + origin
+- Resource class name: "BoxMesh", "SphereMesh", "StandardMaterial3D" — auto-instantiated
+- Numbers: 1.5, 42 — native JSON
+- Booleans: true, false — native JSON
+- Strings: "hello" — native JSON
+
+COMMON PROPERTIES:
+- position: "Vector3(x, y, z)" — world position
+- rotation_degrees: "Vector3(rx, ry, rz)" — rotation in degrees
+- scale: "Vector3(sx, sy, sz)" — scale factor
+- visible: true/false — visibility
+- mesh: "BoxMesh", "SphereMesh", "CapsuleMesh", "CylinderMesh", "PlaneMesh"
+- shadow_enabled: true — for lights
+- light_energy: 1.5 — light intensity
+- fov: 75.0 — camera field of view

package/library/tools/set-resource-property/GUIDE.md

@@ -0,0 +1,8 @@
+# summer_set_resource_property
+
+Set a nested property on a resource attached to a node.
+
+Use when you need to modify a sub-property of a resource, like:
+- CollisionShape3D shape size: nodePath="./Player/CollisionShape3D", resourceProperty="shape", subProperty="size", value="Vector3(1, 2, 1)"
+- Material albedo color: nodePath="./Floor", resourceProperty="material_override", subProperty="albedo_color", value="Color(0.2, 0.5, 0.2, 1)"
+- Mesh size: nodePath="./Box", resourceProperty="mesh", subProperty="size", value="Vector3(2, 2, 2)"

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

@@ -0,0 +1,7 @@
+# summer_shot_sheet
+
+Render several bookmarks and/or explicit poses into ONE labelled grid image in a single call: same tile size, same view, real lighting. Use it after every change to see all hero views at once instead of N screenshots.
+
+compare_previous:true turns each bookmark into a row of [previous | now | difference map] and reports the share of pixels that changed and where. Each bookmark keeps exactly one previous render (its compare baseline) at res://.summer/shots/<bookmark>.jpg (JPEG, <= 1024 px; the folder is capped at 20 MB, oldest first). Only compare_previous:true or update_previous:true replaces it; a plain sheet creates a missing baseline and never overwrites one. view renders every tile as lighting/unshaded/normals/overdraw/wireframe instead of beauty.
+
+Returns the grid + caption (tile number -> label and pose, difference stats). 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/snap-to-surface/GUIDE.md

@@ -0,0 +1,17 @@
+# summer_snap_to_surface
+
+Move one exact 3D subject along a world-space ray until its support face sits at the requested gap from the first surface. This changes only the subject's global transform, saves the scene, and is one reversible editor undo.
+
+Use the default downward direction to seat props on floors, ramps, tables, or shelves. Set alignUp only when the prop should tilt to match the support normal.
+
+EVIDENCE BOUNDARY:
+- physics means Godot swept the subject's enabled collider shapes against body colliders and refined the first-contact bracket.
+- visual_aabb is the engine's broad-phase fallback for mesh-only geometry (no collider on the subject or the support): AABBs swept against AABBs. It does not prove triangle contact, and alignUp is not applied from that approximate normal.
+- visual_mesh: whenever the engine answers with visual_aabb (overlap_recovery_exceeded, gap_exceeds_hit_travel, surface_not_found, or a seat), a read-only probe measures the move from visible triangles instead: the subject's vertices cast along the direction onto the triangles of the meshes below (a surface cutting through the subject counts as sunk), plus the support's vertices under it cast back. One SetProp places the subject, a second read verifies the gap (the move is undone if it disagrees by more than 5 mm), and the scene is saved. The receipt says evidence visual_mesh, the engine's own answer under engine, verify {final_gap, ok}, and evidenceDetails (samples, triangles, whether the subject and the support have colliders). Meshes whose shader writes POSITION (screen-space quads) are not surfaces. When the triangles find no support either, the engine's failure is returned with mesh_fallback saying why.
+- initiallyOverlapping and backoffDistance expose bounded pre-sweep recovery. The tool fails instead of teleporting when the subject cannot be cleared within maxDistance.
+
+SUNK PROPS: when the subject starts inside its support (gap_exceeds_hit_travel with a start overlap), the tool lifts it against the cast direction by the overlap depth plus 0.02 m (at most 0.5 m and the subject's own extent), snaps again from there, and keeps that only if it settles on a node it was sunk into; the receipt then carries recovery (lifted_by, original_local_position) and 'before' is the lifted pose. Otherwise the original position is restored.
+
+FAILURES EXPLAIN THEMSELVES: after gap_exceeds_hit_travel or overlap_recovery_exceeded a read-only starcast at the current pose adds start_overlap, blocking (the nodes it touches or sits inside), below, and a concrete next_step.
+
+The normal result is bounded below 5 KB and returns before/after transforms, supportPath, finalGap with an error bound, slopeDeg, evidence, and warnings. scenePath and subjectPath are always required; there is no editor-selection fallback. On an engine build that predates SnapToSurface the result is a structured engine_lacks_op failure naming the fallback.

package/library/tools/snapshot-diff/GUIDE.md

@@ -0,0 +1,7 @@
+# summer_snapshot_diff
+
+Diff two world snapshots into exactly what changed: added/removed node paths, changed nodes with the fields that moved (pos, scale, material fingerprint, ...), and per-class count deltas. Reads like a receipt — no wading through two full dumps.
+
+Standard use: take summer_world_snapshot BEFORE a mutation batch, mutate, then call this with from_id (to_id omitted = the engine takes a fresh snapshot now). Verify the diff matches your INTENT: exactly the nodes you meant to add were added, nothing you didn't touch changed, nothing vanished. An empty diff after a "successful" mutation is a red flag — the change did not land (wrong scene? unsaved? unowned nodes dropped on save?).
+
+The engine retains the last 8 snapshot ids per session; an expired/unknown id fails with failure_reason "unknown_snapshot" — take a fresh baseline and re-run the mutation check rather than guessing.

package/library/tools/starcast/GUIDE.md

@@ -0,0 +1,12 @@
+# summer_starcast
+
+Read a 3D spatial rundown for one exact node in an exact scene without moving it or saving the scene: 26 directional clearance casts (6 axes, 12 edges, 8 corners) from the subject's bounds, contact-or-overlap evidence, grounded state, and, in full detail, bounded nearby-object lists. Use it before and after placing an object to learn which side is blocked, by what, and at what distance.
+
+detail 'summary' (default) is a placement report of at most 5 KB: subject position and size, grounded and contactStatus, deduplicated contact paths, one compact record per direction (status open|blocked, nearest distance, object, evidence, relationship), coverage, and warnings. detail 'full' adds per-direction hit geometry, an objects table, nearby lists, and the query echo, at most 12 KB; the engine downgrades to summary rather than exceed that (warning full_result_exceeded_12kb_returned_summary) and always reports requestedDetail vs returnedDetail.
+
+EVIDENCE BOUNDARY:
+- evidence 'physics' uses Godot's PhysicsDirectSpaceState3D against exact collider geometry on collisionMask. Shape intersections say contact_or_overlap because the query does not establish penetration depth; touching and anything within margin are included.
+- evidence 'visual_aabb' uses visible world-axis-aligned bounding boxes: it catches meshes without colliders but is broad-phase only, never triangle-level contact.
+- Lights, cameras, audio, navigation, scripts, and plain Nodes are not obstacles unless they own visual or collision geometry. One representative ray per direction can miss off-center geometry.
+
+scenePath and path are exact; editor selection is never consulted. This tool is read-only: it never moves the node or saves the scene. On an engine build that predates Starcast3D the result is a structured engine_lacks_op failure naming the fallback.

package/library/tools/stop/GUIDE.md

@@ -0,0 +1,3 @@
+# summer_stop
+
+Stop the running game. Use after runtime verification or when you intentionally need to restart the running instance; ordinary editor scene mutations do not require a blanket stop. Pass instance to stop ONE offscreen instance started with summer_play {instance, mode:'offscreen'} (the result reports was_playing and killed); omit it for the editor's main game.

package/library/tools/test-placement/GUIDE.md

@@ -0,0 +1,7 @@
+# summer_test_placement
+
+Ghost-test one 3D node at an explicit candidate global pose without moving it or saving the scene.
+
+Use this before placing a prop in a shelf, cubby, doorway, platform, or dense set. The compact result reports known overlap evidence, grounded state, signed floor gap, and at most eight overlapping object paths. Physics evidence uses enabled collider shapes; because Godot exposes no query-completeness bit, its overlap count is labeled a lower bound and an otherwise-clear physics result reports fits:null rather than claiming proof. visual_aabb evidence is a broad-phase fallback that also catches visible mesh-only obstacles.
+
+The pose is always global/world-space: position and Euler rotation in degrees are both required, while the subject's current global scale is preserved. scenePath and subjectPath are exact; this tool never falls back to editor selection. The normal result is below 5 KB and the scene is never mutated. On an engine build that predates TestPlacement3D the result is a structured engine_lacks_op failure naming the fallback.

package/library/tools/ui-actions/GUIDE.md

@@ -0,0 +1,12 @@
+# summer_ui_actions
+
+List the editor's named actions, or invoke ONE by name exactly as its menu item / shortcut would — the primary way to drive the editor UI. (preview — needs an engine build with UiListActions/UiInvoke)
+
+SCENE WORK IS NOT UI WORK: to add, move, retune, or read nodes use summer_run_script, the scene tools, summer_world_snapshot and summer_screenshot — never by clicking through the editor. UI ops are for editor-workflow steps a human would do with the mouse: open Project Settings or the Import dock, switch the 2D/3D/Script main screen, clear a dialog that is blocking input, read what a dock currently shows.
+
+mode:'list' -> {actions:[{name, label, shortcut_text, category, source:'shortcut'|'command', denied?}], total, truncated, filter}. name is the stable shortcut path ('editor/save_scene', 'editor/project_settings', 'spatial_editor/focus_selection', 'summer/design_mode'); filter is a case-insensitive substring over name and label. denied:true marks names mode:'invoke' will refuse — read it and do not try them.
+mode:'invoke' action_name:'<name>' -> {action, label, invoked:true, handled, via:'shortcut_event'|'command_palette', opened_dialog?, mutates:true}. The event runs through the same MenuBar/PopupMenu/EditorNode handlers the key would. opened_dialog is a window that appeared synchronously; a dialog shown deferred appears on the next summer_ui_tree root:'dialogs'.
+
+Order of preference: a dedicated tool -> summer_ui_actions mode:'invoke' by name -> summer_ui_tree + summer_ui_activate by control path -> summer_ui_screenshot (pixels, last, and only to LOOK — never to pick coordinates). Read back, never assume: after an invoke, confirm the effect with summer_ui_tree root:'dialogs' (a dialog opened), summer_ui_tree root:'dock:<name>' (a dock changed), or the scene/perception tools (the scene changed).
+
+Failures carry failure_reason: unknown_action (+close_matches — pick the exact name) | denied_action (+reason — stop; do not route around it) | modal_open (+blocking_dialog — an exclusive dialog is eating input: summer_ui_tree root:'dialogs', then summer_ui_activate action:'dismiss_dialog', then retry) | not_handled (invoked but no live receiver — switch context first, e.g. summer_ui_activate path:'main_screen' action:'select_tab' value:'3D') | editor_unavailable. Never try to quit the editor, quit to the project list, reload the project, or delete without confirmation (editor/file_quit, editor/quit_to_project_list, editor/reload_current_project, scene_tree/delete_no_confirm, project_manager/*): the engine refuses them with denied_action, and buttons/menu items with those labels are denied the same way. They end the session you are talking over. On an engine build without these ops the result is a structured engine_lacks_op failure (nothing is sent) naming the dedicated tools to use instead.

package/library/tools/ui-activate/GUIDE.md

@@ -0,0 +1,11 @@
+# summer_ui_activate
+
+Activate ONE editor control by its summer_ui_tree path through the control's own input path — a synthetic click for buttons, the public setter + signal for tabs, text fields and ranges — or dismiss a visible dialog (action:'dismiss_dialog'). Mutates editor state; the result's state is READ BACK from the control after the action, not echoed. (preview — needs an engine build with UiActivate/UiDismissDialog)
+
+SCENE WORK IS NOT UI WORK: to add, move, retune, or read nodes use summer_run_script, the scene tools, summer_world_snapshot and summer_screenshot — never by clicking through the editor. UI ops are for editor-workflow steps a human would do with the mouse: open Project Settings or the Import dock, switch the 2D/3D/Script main screen, clear a dialog that is blocking input, read what a dock currently shows. Reach for this only when no named action covers the step (summer_ui_actions mode:'list' first). There is no coordinate click: if a thing is visible it is in the tree and this reaches it by path.
+
+actions: press (BaseButton: hover+press+release at the rect centre — pressed_emitted is observed, not assumed; ItemList/PopupMenu item by index; MenuBar -> unsupported_control, use summer_ui_actions) | toggle (toggle-mode button) | focus (any control/window) | select_tab (TabContainer/TabBar by value title or index; path:'main_screen' switches the 2D/3D/Script/Game/AssetLib editor by value or index and reads back current_tab + text) | set_text (LineEdit/TextEdit; submit:true also presses Enter; value '' clears) | set_value (Range number) | dismiss_dialog (path or title from summer_ui_tree root:'dialogs'; button 'cancel' default = the safe close, 'ok' or a button text to confirm — only when the user asked for that).
+
+Returns {path, class, action, via, state:{...the node's tree fields...}, mutates:true} plus clicked_at/hover_established/pressed_emitted for press, item_text for menus, submitted for set_text; dismiss_dialog returns {title, class, button, via, visible_after} — visible_after:true means the dialog re-validated and stayed up (read it: summer_ui_tree root:'dialog:<title>'). Verify with the read-back (state.checked, state.current_tab, state.text, visible_after), never by assumption.
+
+Failures: not_found | not_visible (hidden — reveal the dock/tab first) | disabled | unsupported_control (+supported_actions) | obscured (+hit_control — something on top, usually a dialog) | modal_open (+blocking_dialog — dismiss it first) | no_activation_path (use the named action instead) | denied_action / denied_path (safety: quit/reload labels, file-dialog paths outside the project) | tab_not_found (+tabs) | index_out_of_range | missing_value | not_selected | button_not_found (+buttons) | ambiguous_dialog (+candidates). Never try to quit the editor, quit to the project list, reload the project, or delete without confirmation (editor/file_quit, editor/quit_to_project_list, editor/reload_current_project, scene_tree/delete_no_confirm, project_manager/*): the engine refuses them with denied_action, and buttons/menu items with those labels are denied the same way. They end the session you are talking over. Engine builds without these ops return a structured engine_lacks_op failure (nothing is sent).

package/library/tools/ui-screenshot/GUIDE.md

@@ -0,0 +1,9 @@
+# summer_ui_screenshot
+
+PNG of the editor window (or one dock / dialog / control's rect) returned as an image you can look at — the PIXELS-LAST fallback of the UI ladder: use it to see layout, an unfamiliar panel, or to sanity-check what the tree described, never to pick click coordinates (there is no coordinate click; summer_ui_activate takes paths). For the 3D/2D viewport, a scene render, or the running game use summer_screenshot instead — that is the visual-verification tool for scene work, and scene work itself goes through summer_run_script and the scene tools, never through the editor UI. (preview — needs an engine build with UiScreenshot)
+
+Order of preference: a dedicated tool -> summer_ui_actions mode:'invoke' by name -> summer_ui_tree + summer_ui_activate by control path -> summer_ui_screenshot (pixels, last, and only to LOOK — never to pick coordinates). Prefer summer_ui_tree for state: a control's checked/current_tab/text is exact there and costs a fraction of an image.
+
+root: 'window' (default; the whole editor window incl. embedded dialogs) | 'main' | 'dock:<title|id>' | 'dialog:<title>' | 'path:<node path>' — a Control or embedded dialog is cropped out of the root viewport texture; a native OS sub-window is not in it (native_subwindow). max_size caps the longest edge (default 1024, 16-4096). Captured from the editor's own root viewport texture, never the OS screen (safety_boundary:'no_os_screen_capture').
+
+Headless is honest: under a headless editor (dummy rendering driver) the result is failure_reason no_renderer — nothing was drawn, so there are no pixels; summer_ui_tree is the structured view of the same UI and a display (Linux: --xvfb) is needed for pixels. Other failures: texture_unavailable | zero_size | native_subwindow | unknown_root | not_found | encode_failed. Engine builds without the op return a structured engine_lacks_op failure (nothing is sent).

package/library/tools/ui-tree/GUIDE.md

@@ -0,0 +1,10 @@
+# summer_ui_tree
+
+Structured tree of the live editor UI — every visible Control with its class, path, rect, text/tooltip and state (checked, enabled, focused, tabs + current_tab, value/min/max, selected item) — or, with root:'dialogs', every visible dialog/popup and whether one is BLOCKING input. The structured alternative to a screenshot: the tree states outright what exists and what is clickable, at a fraction of the tokens, and its paths are what summer_ui_activate takes. (preview — needs an engine build with UiTree/UiDialogs)
+
+SCENE WORK IS NOT UI WORK: to add, move, retune, or read nodes use summer_run_script, the scene tools, summer_world_snapshot and summer_screenshot — never by clicking through the editor. UI ops are for editor-workflow steps a human would do with the mouse: open Project Settings or the Import dock, switch the 2D/3D/Script main screen, clear a dialog that is blocking input, read what a dock currently shows. Use this tree to READ editor state (which main screen is active, what a dock shows, what a dialog says and which buttons it has) and to find a control's path when no named action covers the step; use summer_get_scene_tree / summer_world_snapshot for the SCENE — the editor's Scene dock is a view of that data, not the data.
+
+root: 'main' (default; the editor chrome) | 'window' (incl. every sub-window) | 'dock:<title|id>' (file_system | scene_tree | inspector or any dock title) | 'dialog:<title>' | 'path:<node path>' (zoom into an earlier result) | 'dialogs' -> {count, blocking, blocking_dialog?, dialogs:[{title, path, class, kind, exclusive, popup, embedded, focused, text?, items?, buttons:[{text, path, kind:'ok'|'cancel'|'custom', enabled}]}]}.
+Tree results: {root, root_path, total_emitted, truncated, tree:{name, class, path, visible, rect, text?, tooltip?, enabled?, checked?, focused?, tabs?, current_tab?, value?, child_count, children_truncated?, children}}. Strings clip at 200 chars; icon-only toolbar buttons are named by tooltip; child_count is always the real count, so a children_truncated node can be re-read with root:'path:<its path>' and a larger depth/limit.
+
+Paths (@Panel@123) are stable within a session, not across builds — re-read instead of persisting them. The blocking-dialog pattern: root:'dialogs' -> blocking:true -> summer_ui_activate action:'dismiss_dialog' path:<blocking_dialog.path> -> root:'dialogs' again to confirm blocking:false. Failures: unknown_root (+available_docks, dock_ids) | not_found (+visible_titles) | ambiguous_dialog (+candidates) | editor_unavailable. Engine builds without these ops return a structured engine_lacks_op failure (nothing is sent).

package/library/tools/wait-for-event/GUIDE.md

@@ -0,0 +1,11 @@
+# summer_wait_for_event
+
+Block until the engine emits a matching EVENT, or a bounded timeout elapses — the replacement for sleeping and re-polling. Use it right after summer_play to wait for play.started (the game actually booting), after a long op (import, script, save) to wait for op.applied / op.failed by requestId instead of guessing a delay, and during a playtest to catch script.error the moment it fires.
+
+Event kinds (v1): op.applied, op.failed, script.error, play.started, play.stopped, scene.saved, scene.opened, import.completed, selection.changed, snapshot.published. Each event is {seq, kind, ts, data}; seq is a monotonic cursor.
+
+CURSOR DISCIPLINE: events are delivered live from `since` (omitted = from now). An event that fired BEFORE this call is NOT delivered, so when the moment may come fast, take a cursor first: summer_recent_events returns next_seq — pass it as since BEFORE triggering the action (summer_recent_events -> summer_play -> summer_wait_for_event since:<next_seq> kinds:['play.started']). Every result carries next_seq: pass it as since on the next call to keep waiting with no gap.
+
+match.requestId narrows op.applied / op.failed to one request (other kinds pass through). The call long-polls the engine in slices of at most 25 s until a match or timeout_seconds (default 30, max 120) elapses.
+
+Returns {ok, matched, events, next_seq, since, timed_out, waited_ms, polls}. timed_out:true means NO matching event arrived — it is not evidence the thing did not happen (verify with summer_is_running / summer_get_diagnostics) and you must never claim an event you did not receive. A `gap` field means events between since and the oldest retained were evicted — re-read state instead of trusting the stream. On an engine build without the events channel (no capabilities.events in /api/health) the result is a structured engine_lacks_events failure and nothing is sent: fall back to polling the state.

package/library/tools/world-snapshot/GUIDE.md

@@ -0,0 +1,9 @@
+# summer_world_snapshot
+
+Compact structured snapshot of the whole EDITED scene — the cheap read to run BEFORE and AFTER every mutation batch. Per node: path, class, transform (pos/rot/scale as Godot literal strings, 3-decimal floats), world AABB (3D visuals), visibility, and 8-hex resource fingerprints (script/materials — detect-change markers, never content). Plus a light summary, camera list, environment fingerprint, and per-class counts.
+
+THE LOOP: summer_world_snapshot (note snapshot_id) -> mutate (summer_run_script / scene tools / imports) -> summer_snapshot_diff from_id:<that id> -> summer_screenshot. The diff proves exactly what changed structurally; the screenshot proves it looks right. This is how you catch a node that silently vanished on save, a transform that landed at the origin, or an AABB clipping through the floor.
+
+Node lists are path-sorted and truncated DETERMINISTICALLY (result carries total_nodes + truncated) so two snapshots stay diffable without phantom adds/removes. The engine retains the last 8 snapshots per session, keyed by snapshot_id. Use this instead of summer_get_scene_tree when you need transforms/AABBs/fingerprints or a diffable baseline; the tree read remains the hierarchy-shaped view. On an engine build that predates GetWorldSnapshot the result is a structured engine_lacks_op failure naming the fallback.
+
+KEEP IT SMALL (about 250 bytes per node): at most 200 nodes are listed by default. path_prefix reads one subtree ('House3', 'Lane2/Props'), classes keeps some node classes, fields keeps some per-node fields (e.g. ['pos','aabb']), offset/next_offset page the list. A filtered read adds matched_nodes and matched_counts (class counts of the subtree). counts and total_nodes always describe the whole scene, and snapshot_id always covers the whole scene, so summer_snapshot_diff still sees every change.

package/library/tools/write-file/GUIDE.md

@@ -0,0 +1,5 @@
+# summer_write_file
+
+Create or safely overwrite a complete text file through the identity-bound engine.
+
+For a new file, set create_only:true. For an existing file, first call summer_read_file and pass its sha256 as expected_sha256. Exactly one guard is required; unguarded writes fail closed. Supports scripts, .tscn scenes, .tres resources, JSON, docs, and project config.

package/library/tools/zoom/GUIDE.md

@@ -0,0 +1,5 @@
+# summer_zoom
+
+High-resolution close look at part of a frame: region [x, y, w, h] (fractions of the frame) or mark N from a marks render of the same pose. The camera renders the EXACT sub-frustum of that region at full output resolution, so you see real texture detail, seams, gaps and floating pieces, not upscaled pixels. A region is honoured exactly (no pad by default, never widened to an aspect ratio: the image takes the region's own aspect, with dark bars only for extreme shapes); a mark gets pad 0.15.
+
+Use after a sheet or debug view shows something suspicious. view picks beauty or a debug view. Returns the zoomed image + caption (the real zoom factor, the rendered region, widened_because when it is larger than asked, mark -> node path and a warning when that node is hidden). 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/package.json

@@ -1,7 +1,8 @@
 {
   "name": "summer-engine",
-  "version": "3.8.0",
-  "description": "Local Summer CLI and MCP server for Summer Engine. Install and run the engine, connect Claude Code, Cursor, Codex, Gemini, and other agents, and build real games with bundled skills, hooks, and plugins.",
+  "version": "4.0.0",
+  "description": "MCP server, CLI and skills for Summer Engine, the game engine built for AI. Connect Claude Code, Cursor, Codex and other agents to build, test and publish full games to summer.games.",
+  "mcpName": "io.github.SummerEngine/summer",
   "keywords": [
     "summer-engine",
     "summer-cli",
@@ -43,6 +44,7 @@
     "library/",
     "registry/generated/",
     "registry/schemas/",
+    "registry/operations/",
     "integrations/",
     "commands/",
     "hooks/",
@@ -59,8 +61,7 @@
     "NOTICE",
     "CHANGELOG.md",
     "AGENTS.md",
-    "GEMINI.md",
-    "CLAUDE.md"
+    "GEMINI.md"
   ],
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
@@ -76,6 +77,7 @@
     "test:watch": "vitest",
     "prepublishOnly": "npm run build && npm test",
     "generate:registry": "node scripts/generate-registry/cli.ts",
+    "generate:tool-guides": "UPDATE_TOOL_GUIDES=1 vitest run src/mcp/tool-guides.test.ts",
     "generate:product-map": "npm run build && node scripts/navigation/render-product-map.ts",
     "sync:web-routes": "npm run build && node scripts/navigation/sync-web-routes.ts"
   },

package/registry/generated/counts.json

@@ -4,9 +4,9 @@
     "collection": 0,
     "example": 0,
     "reference": 9,
-    "skill": 125,
+    "skill": 127,
     "template": 19,
     "tool": 119
   },
-  "total": 272
+  "total": 274
 }