summer-engine 3.7.0 → 4.0.0

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.7.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/aliases.json

@@ -100,6 +100,20 @@
     "summer_add_node": "tool/add-node",
     "summer_align_distribute_3d": "tool/align-distribute-3d",
     "summer_api_docs": "tool/api-docs",
+    "summer_app_call": "tool/app-call",
+    "summer_app_create": "tool/app-create",
+    "summer_app_data": "tool/app-data",
+    "summer_app_dock": "tool/app-dock",
+    "summer_app_events": "tool/app-events",
+    "summer_app_get": "tool/app-get",
+    "summer_app_guide": "tool/app-guide",
+    "summer_app_list": "tool/app-list",
+    "summer_app_page": "tool/app-page",
+    "summer_app_publish": "tool/app-publish",
+    "summer_app_report_gap": "tool/app-report-gap",
+    "summer_app_screenshot": "tool/app-screenshot",
+    "summer_app_tools": "tool/app-tools",
+    "summer_app_update": "tool/app-update",
     "summer_attach_to_surface": "tool/attach-to-surface",
     "summer_batch": "tool/batch",
     "summer_camera_bookmark": "tool/camera-bookmark",
@@ -111,6 +125,7 @@
     "summer_create_debug_report": "tool/create-debug-report",
     "summer_create_scene": "tool/create-scene",
     "summer_debug_views": "tool/debug-views",
+    "summer_enable_plugin": "tool/enable-plugin",
     "summer_export_game": "tool/export-game",
     "summer_export_templates": "tool/export-templates",
     "summer_fabricate_3d": "tool/fabricate-3d",

package/registry/generated/counts.json

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

package/registry/generated/gemini-extension.json

@@ -1,7 +1,7 @@
 {
   "_generated": "GENERATED from integrations/gemini — do not edit; npm run generate:registry",
   "name": "summer",
-  "version": "3.7.0",
+  "version": "4.0.0",
   "description": "Agent tooling for Summer Engine: MCP bridge, context primer, and game-dev skills. Use with the npm CLI for skill files on disk.",
   "contextFileName": "GEMINI.md",
   "mcpServers": {
@@ -40,7 +40,6 @@
     "./library/skills/brainstorming/",
     "./library/skills/browse-templates/",
     "./library/skills/camera-rigs/",
-    "./library/skills/celeste-momentum-platforming/",
     "./library/skills/character-animation-wiring/",
     "./library/skills/character-model/",
     "./library/skills/character-movement/",
@@ -49,6 +48,7 @@
     "./library/skills/combat-basics/",
     "./library/skills/compatibility-renderer-traps/",
     "./library/skills/concept-art/",
+    "./library/skills/concept-to-level/",
     "./library/skills/create-asset-sheet/",
     "./library/skills/debug/",
     "./library/skills/debugging-game-feel/",
@@ -67,13 +67,11 @@
     "./library/skills/gameskill/",
     "./library/skills/gdscript-patterns/",
     "./library/skills/generate-motion/",
-    "./library/skills/godogen-visual-proof-game-generation/",
     "./library/skills/grow-analytics/",
     "./library/skills/headless-scripting/",
     "./library/skills/in-game-purchases/",
     "./library/skills/instantiate-asset-pack/",
     "./library/skills/investigating-bugs/",
-    "./library/skills/lumera-single-image-scene-reconstruction/",
     "./library/skills/make-game/",
     "./library/skills/multiplayer/",
     "./library/skills/multiplayer-movement/",
@@ -90,9 +88,7 @@
     "./library/skills/playtesting-a-feature/",
     "./library/skills/procedural-animation/",
     "./library/skills/prop-model/",
-    "./library/skills/psx-retro-rendering/",
     "./library/skills/publish-your-game/",
-    "./library/skills/realtime-wet-surfaces/",
     "./library/skills/release-readiness/",
     "./library/skills/remote-deploy/",
     "./library/skills/retarget/",
@@ -102,10 +98,6 @@
     "./library/skills/scene-hierarchy-design/",
     "./library/skills/scene-scripting/",
     "./library/skills/scene-to-level/",
-    "./library/skills/skill-create/",
-    "./library/skills/skill-improve/",
-    "./library/skills/skill-test/",
-    "./library/skills/skintokens-auto-rigging/",
     "./library/skills/skybox-panorama/",
     "./library/skills/sound-effect/",
     "./library/skills/spatial-placement/",
@@ -113,6 +105,9 @@
     "./library/skills/store-art/",
     "./library/skills/store-listing/",
     "./library/skills/summer-analytics/",
+    "./library/skills/summer-apps/",
+    "./library/skills/summer-apps-design/",
+    "./library/skills/summer-assets/",
     "./library/skills/summer-friends/",
     "./library/skills/summer-leaderboards/",
     "./library/skills/summer-match-results/",
@@ -145,7 +140,6 @@
     "./library/skills/web-and-touch-input/",
     "./library/skills/web-compatibility-look/",
     "./library/skills/world-building-3d/",
-    "./library/skills/writing-plans/",
-    "./library/skills/writing-skills/"
+    "./library/skills/writing-plans/"
   ]
 }