summer-engine 2.8.2 → 3.1.0

package/library/references/mcp-fresh-chat-playbook/mcp-fresh-chat-playbook.md

@@ -0,0 +1,49 @@
+# Summer MCP Fresh-Chat Playbook
+
+The minimum safe workflow for AI agents building in a Summer Engine project.
+
+## Build flow (default)
+
+1. **Understand** the request, then outline a brief plan. Proceed once it's clearly right.
+2. **Call `summer_get_project_context` first** so you don't guess scene paths or the project language and so the MCP session binds to the open project. Use `projectMemory` to decide which `.summer` files to read.
+3. **Edit through identity-bound Summer tools.** Use `summer_read_file`, `summer_replace_text`, and guarded `summer_write_file` for `.gd`, `.tscn`, `.tres`, `.cs`, `.json`, docs, and config. Write GDScript by default; use C# only if the project already uses it.
+4. **Play and iterate.** After writing code, **play the scene you just made** and read `summer_get_diagnostics`; fix and repeat until it launches clean — don't wait for the user to navigate to the feature before the first error shows.
+
+## When to use Summer MCP (the live engine)
+
+Use MCP for both guarded project file mutations and live-engine work:
+
+- `summer_play` / `summer_stop` + `summer_get_diagnostics` — run and read errors
+- `summer_screenshot` — see the editor viewport or running game (visual verification)
+- navmesh or light baking
+- runtime inspection of a live scene
+- asset import
+- structural edits into an **already-open** scene where you want the editor to manage node ids / instancing
+- `summer_read_file` / `summer_replace_text` / `summer_write_file` — identity-bound text reads and guarded writes
+
+Git, shell, and grep remain host-native. Project file mutations should stay on the Summer path when MCP is available.
+
+## Safe editing rules
+
+- Never guess scene paths like `res://main.tscn` — get them from `summer_get_project_context`.
+- New files use `summer_write_file` with `create_only:true`; existing files use `summer_replace_text` or `summer_write_file` with the sha256 from `summer_read_file`.
+- Guarded `.tscn`/`.tres` writes are supported. Prefer scene tools for live hierarchy and inspector edits; the engine schedules editor reload handling after file writes.
+- Never perform destructive bulk removals unless the user explicitly asks.
+- Never change `priority: locked` `.summer` memory, voice IDs, canon, or provider bindings without explicit user confirmation.
+- Save live-engine scene edits with `summer_save_scene`; run `summer_get_diagnostics` after changes.
+
+## Live-engine scene-edit flow (only when you need it)
+
+1. `summer_get_project_context`
+2. `summer_open_main_scene` (if needed)
+3. `summer_get_scene_tree`
+4. `summer_add_node` / `summer_set_prop` / `summer_set_resource_property`
+5. `summer_save_scene`
+6. `summer_get_diagnostics`
+
+## Error recovery
+
+- `"no scene open"` / `"no edited scene"` → call `summer_open_main_scene`.
+- `"failed to open scene"` → re-check `mainScene` from `summer_get_project_context`; use the exact path only.
+- A content/sha mismatch → re-read with `summer_read_file`, review the new bytes, and retry only if the intended edit still applies.
+- An identity mismatch → call `summer_get_project_context` to rebind only if the newly open project is intentional.

package/library/references/mcp-fresh-chat-playbook/resource.yaml

@@ -0,0 +1,23 @@
+id: reference/mcp-fresh-chat-playbook
+kind: reference
+version: 1.0.1
+summary: The minimum safe workflow for an AI agent building in a Summer Engine project — get context first, edit through Summer tools, play and iterate.
+use_when:
+  - starting work in a Summer Engine project from a fresh conversation
+  - deciding the safe default order of MCP calls for a build task
+facets:
+  lifecycle: [ build ]
+  domains:
+    - mcp
+    - agent-workflow
+compatibility:
+  engine: ">=4.6"
+related:
+  references:
+    - reference/mcp-tools-reference
+    - reference/summer-folder
+source: official
+license: MIT
+status: stable
+aliases:
+  - docs/MCP_FRESH_CHAT_PLAYBOOK.md

package/library/references/mcp-tools-reference/mcp-tools-reference.md

@@ -0,0 +1,271 @@
+# Summer MCP Tools — Canonical Reference
+
+> Use this as the single source of truth for which Summer MCP tool to call. Skills should reference tool names exactly as written here.
+
+## When to use Summer MCP vs. host tools
+
+**Use Summer MCP for** anything that needs the live editor or Godot's import pipeline:
+- Scene graph mutation (`.tscn`)
+- Node properties and resources (`.tres`)
+- Project settings (`project.godot`) and InputMap
+- Asset import (Godot's import pipeline must run)
+- Play / stop / runtime state
+- Diagnostics, console, debugger output, script errors
+- Project text reads and guarded writes (`.gd`, `.cs`, `.tscn`, `.tres`, JSON, docs, config)
+
+**Use host tools for** git, shell, grep, and non-project work. External host file writes bypass Summer's project-identity, sha256, and editor-reload safeguards and should not be used for project mutations while MCP is available.
+
+**Rule of thumb:** project reads/writes go through Summer; live hierarchy/inspector changes use scene tools; process-level work remains with the host.
+
+## Tool surface (86 tools)
+
+### Project files (3)
+
+| Tool | Use |
+|---|---|
+| `summer_read_file` | Read project text plus a full-file sha256 receipt. |
+| `summer_write_file` | Create-only or sha256-guarded complete file write. |
+| `summer_replace_text` | Unique (or explicit replace-all) text mutation with read/sha guard. |
+
+### Scene graph (11)
+
+| Tool | Use |
+|---|---|
+| `summer_get_scene_tree` | Read current scene graph. Always do this before mutating. |
+| `summer_open_main_scene` | Open the project's main scene. |
+| `summer_open_scene` | Open a specific `.tscn`. |
+| `summer_open` | Navigate for the user: open a summerengine.com page (billing, my games, pricing, an MCP guide) or an editor surface (scene, node, script, file, a dock) by intent name, or `print` the URL / op. Destinations: the `product-map` reference; when to use it: the `navigate-summer` skill. |
+| `summer_create_scene` | Create a new scene. |
+| `summer_instantiate_scene` | Add an existing scene or 3D model as a child node. |
+| `summer_inspect_node` | Read a single node's properties. |
+| `summer_add_node` | Add a node to the explicit `scenePath`; the tab need not be open. |
+| `summer_remove_node` | Remove a node from the explicit `scenePath`. |
+| `summer_replace_node` | Swap a node's type in the explicit `scenePath`, preserving children. |
+| `summer_select_node` | Set editor selection (visual feedback for the user). |
+| `summer_save_scene` | Explicitly save/save-as a `scenePath`; mutation tools already append one final save. |
+
+### Properties / resources (4)
+
+| Tool | Use |
+|---|---|
+| `summer_set_prop` | Set a typed property in an explicit `scenePath` using Godot's `str_to_var()`. |
+| `summer_set_resource_property` | Set a nested resource property in an explicit `scenePath`. |
+| `summer_inspect_resource` | Read a resource's properties. |
+| `summer_connect_signal` | Wire a signal between nodes. |
+
+### Project & input (2)
+
+| Tool | Use |
+|---|---|
+| `summer_project_setting` | Modify `project.godot` settings (rendering, physics). |
+| `summer_input_map_bind` | Bind input actions in InputMap. Folds in the legacy `add_action` step. |
+
+### Import pipeline (2)
+
+| Tool | Use |
+|---|---|
+| `summer_import_from_url` | Download a `.glb`/`.png`/etc and run Godot's full import pipeline. |
+| `summer_import_from_url_batch` | Same, batched (single filesystem scan). |
+
+### Scene scripting (3)
+
+| Tool | Use |
+|---|---|
+| `summer_run_script` | Run a GDScript (`func run(ctx):`) inside the live editor against the OPEN scene. Prefer it over 3+ CRUD ops or any computed placement (scatter, procedural meshes, bulk edits). Created nodes need `ctx.set_owner_recursive(node)` after `add_child`. |
+| `summer_run_editor_script` | Run an EditorScript (`func _run():`) in a fresh headless child editor against the ON-DISK project. Cold path for batch/project-wide jobs; unsaved live edits are invisible to it. |
+| `summer_api_docs` | Offline class-reference lookup (properties, methods, signals, constants). Verify names before scripting instead of guessing; works without the engine. |
+
+### Mesh fabrication (1)
+
+| Tool | Use |
+|---|---|
+| `summer_fabricate_3d` | Run a Blender Python (bpy) script in the user's OWN installed Blender — headless, engine-supervised — then import the exported `.glb` into `res://` and optionally instantiate it with `target_size`. For modular kits with exact dimensions, VFX meshes (shatter, sweeps, LOD chains), and post-processing generated models (decimate/UV/bake); generic props go to the library and characters to generation. Requires Blender on the machine (never bundled); `blender_not_found` carries the fix. The `fabricating-assets` skill has the bpy rules that survive glTF export. |
+
+### Editor UI control (4)
+
+Preview — the `Ui*` engine ops ship with a follow-up engine build; until then these return `engine_lacks_op`. Semantic first: scene work never goes through the editor UI (use the scene, scripting, and perception tools). UI ops are for editor-workflow steps a human does with the mouse — open Project Settings, switch the main screen, clear a blocking dialog, read a dock. Ladder: dedicated tool → named action → tree + activate → screenshot (pixels last, never for coordinates). Quit / project-reload / delete-without-confirm actions are denied by the engine. The `driving-the-editor-ui` skill carries the patterns.
+
+| Tool | Use |
+|---|---|
+| `summer_ui_actions` | `mode:"list"` enumerates the editor's named actions (`name`, `label`, `shortcut_text`, `category`, `denied?`); `mode:"invoke" action_name:"editor/project_settings"` runs one exactly as its menu item / shortcut would and reports `handled`, `via`, `opened_dialog`. Failures: `unknown_action` (+`close_matches`), `denied_action`, `modal_open` (+`blocking_dialog`), `not_handled`. |
+| `summer_ui_tree` | Structured Control tree of the live editor UI (class, path, rect, text/tooltip, `checked`/`enabled`/`tabs`/`current_tab`/`value`) from `root:"main" \| "window" \| "dock:<title\|id>" \| "dialog:<title>" \| "path:<node path>"`; `root:"dialogs"` lists every visible dialog/popup with `blocking`, `blocking_dialog`, and its `buttons`. The token-cheap alternative to a screenshot; its paths are what `summer_ui_activate` takes. |
+| `summer_ui_activate` | Activate one control by tree path through its own input path — `press`, `toggle`, `focus`, `select_tab` (incl. `path:"main_screen" value:"3D"`), `set_text` (+`submit`), `set_value` — and `action:"dismiss_dialog"` (by `path` or `title`, `button` cancel/ok/text) to clear a blocking dialog. `state` / `visible_after` are read back after the action, never echoed. |
+| `summer_ui_screenshot` | PNG of the editor window or one dock/dialog/control (`root`, `max_size`) returned as an image — the pixels-last fallback for LOOKING at the editor UI. Not for scene verification (`summer_screenshot`) and never for picking click coordinates. Honest `no_renderer` under a headless editor. |
+
+### Perception (4)
+
+| Tool | Use |
+|---|---|
+| `summer_world_snapshot` | Compact structured snapshot of the edited scene (paths, classes, transforms, world AABBs, visibility, resource fingerprints, light/camera/counts summary). The cheap read to run BEFORE and AFTER every mutation batch; keep the `snapshot_id`. |
+| `summer_snapshot_diff` | Diff two snapshots into added/removed/changed + count deltas — the structural receipt that a mutation did exactly what was intended. Omit `to_id` to diff against a fresh snapshot taken now. |
+| `summer_get_runtime_tree` | Scene tree of the RUNNING game (spawned enemies, autoloads, pooled nodes) — live state the editor reads can't show. Needs `summer_play` first. |
+| `summer_inspect_runtime_node` | One running-game node's live properties (actual stats/position/flags) without stopping the game. Get paths from `summer_get_runtime_tree`. |
+
+### Spatial / world building (5)
+
+Bounded spatial evidence for deliberate 3D arrangement. All five take exact `scenePath` + scene-root-relative node paths (editor selection is never consulted) and return a compact receipt under 5 KB (`summer_starcast` full detail: at most 12 KB). Read `skill/world-building-3d` for each tool's evidence boundary before the first call, and `skill/spatial-placement` for the inspect -> place -> starcast -> correct -> verify loop.
+
+| Tool | Use |
+|---|---|
+| `summer_test_placement` | Ghost-test one node at a candidate global pose (read-only, never saves): overlap evidence, grounded state, signed floor gap. `fits: null` means physics could not prove clearance — never coerce it to success. |
+| `summer_snap_to_surface` | Seat one subject on the first surface along a world ray (default downward); mutation + save. `evidence: physics` = collider sweep; `visual_aabb` = mesh-only broad-phase fallback. |
+| `summer_align_distribute_3d` | Align (min/center/max) or equal-space (centers/gaps) 2–16 ordered subjects along one world axis from visible AABBs; mutation + save. One-axis evidence only. |
+| `summer_navigation_probe` | Read-only reachability between two world points on the scene's navigation map: readiness, snapped endpoints + snap distances, route length, ≤16 route points. `ready: false` = unknown, not unreachable. |
+| `summer_starcast` | Read-only 26-direction placement rundown around one exact node: per-direction `open`/`blocked` with nearest object, distance and evidence, contact-or-overlap paths, `grounded`, coverage, warnings. `detail: summary` ≤ 5 KB; `full` adds hit geometry, an objects table and nearby lists ≤ 12 KB and downgrades to summary rather than exceed it. `visual_aabb` evidence is broad-phase, never exact contact. |
+
+### Play / runtime (3)
+
+| Tool | Use |
+|---|---|
+| `summer_play` | Run the game. Plain = the editor's embedded main game. Optional `seed` / `fixed_fps` / `time_scale` pin THIS launch (newer engines); the result's `determinism.applied` + `seed_scope` say what was pinned — a missing block means the engine ignored the pins. `instance` + `mode:"offscreen"` (+ `deterministic:true`, `speed`) spawn a hidden parallel instance (at most 3) that the runtime-control tools address by name. |
+| `summer_stop` | Stop the running game, or `instance` to stop one offscreen instance. |
+| `summer_is_running` | Check play state before deciding to call `summer_stop`; the boot check after `summer_play` (never sleep a guessed delay). |
+
+### Runtime control & playtest (7)
+
+Drive and observe the RUNNING game (engine runtime-control ops, preview — `engine_lacks_op` on older builds names the fallback). Every tool needs a running game (`game_not_running` otherwise), takes `instance`, and is sent alone. The `agent-playtesting` skill is the doctrine: launch deterministically → probe → act → step/probe → assert; never claim motion, spawning or a state change without a probe of the frame after.
+
+| Tool | Use |
+|---|---|
+| `summer_game_probe` | State AND pixels of ONE frame, atomically: live tree, up to 64 `path:property` reads, screenshot (returned as an image), all stamped with the same frame counters. The evidence read of the loop. |
+| `summer_game_control` | `pause` / `resume` / `step` exactly N physics or process frames (leaves the game suspended) / `speed` / `instances` (live instances with `attached`). |
+| `summer_game_input` | `script` timed synthetic input (action / key / mouse_click / axis / raw), `record_start` / `record_stop` real input to `res://.summer/replays/`, `replay` a recording (`seed` only on a deterministic offscreen instance). One script in flight per instance (`busy`). |
+| `summer_runtime_set` | Set one property on a live node; `applied:false` means the read-back disagreed. Never touches the scene file. |
+| `summer_runtime_call` | Call one method on a live node and get its return value. |
+| `summer_runtime_spawn` | `spawn` a PackedScene into the live game, or `free` a live node. |
+| `summer_runtime_animate` | AnimationPlayer (`player`), AnimationTree state machine (`tree`), Skeleton3D bone poses (`bones`) — read (`cmd:"state"`, default) or drive. |
+
+### Events (2)
+
+| Tool | Use |
+|---|---|
+| `summer_wait_for_event` | Block until a matching engine event arrives — `play.started` after `summer_play`, `op.applied` / `op.failed` for one `requestId` after a long op, `script.error` during a playtest, `scene.saved`, `import.completed` — or the timeout elapses (default 30 s, max 120). Returns the events, `next_seq`, and an honest `timed_out`; never claim an event you did not receive. Take a cursor with `summer_recent_events` first so a moment that arrives immediately is not missed. Preview: engines without the events channel return `engine_lacks_events`. |
+| `summer_recent_events` | The newest engine events (or everything after `since`) in one zero-wait read; its `next_seq` is the `since` cursor to hand `summer_wait_for_event` before triggering the action you will wait on. Shell twin: `summer events [--follow]`. |
+
+### Visual capture (2)
+
+| Tool | Use |
+|---|---|
+| `summer_screenshot` | Capture a frame and return it as an image the agent sees directly — editor viewport (`target:"viewport"`, default; no play needed), offscreen scene render (`target:"scene"`, presets or `framing:"camera"` which renders through the scene's OWN camera with its REAL WorldEnvironment — the trustworthy edit-time lighting check), or running game (`target:"game"`). Newer engines add fixed poses — `framing:"bookmark"` + `bookmark_name` (saved with `summer_camera_bookmark`) or `framing:"free"` + `camera_position`/`camera_look_at` — for before/after frames that line up, and `marks:true` for numbered labels the caption maps to node paths. Use to visually verify scene layout, asset placement, scale, framing, lighting, or runtime state. On macOS the running game is a floating window that can't be captured; prefer `viewport`. |
+| `summer_camera_bookmark` | Save (`action:"save"`, from the editor viewport camera or an explicit pose), list, or delete named camera viewpoints persisted in the project (`res://.summer/camera_bookmarks.json`). Save once, then screenshot from it with `framing:"bookmark"` every time. Returns `engine_lacks_op` on engines that predate the bookmark ops. |
+
+### Diagnostics (7)
+
+| Tool | Use |
+|---|---|
+| `summer_create_debug_report` | Create a support-ready Markdown report for `/summer debug`. |
+| `summer_get_diagnostics` | Aggregate error/warning summary. Call after every change. |
+| `summer_get_console` | Engine output panel. |
+| `summer_clear_console` | Clear before a fresh play, so post-run output is clean. |
+| `summer_get_debugger_errors` | Runtime errors with stack traces. |
+| `summer_get_debugger_warnings` | Runtime warnings from the debugger panel. |
+| `summer_get_script_errors` | Script compilation errors. |
+
+### Asset library (8)
+
+| Tool | Use |
+|---|---|
+| `summer_search_assets` | Free public asset search (community library + user's own). Sources: `library`, `community`, `my_assets`, `all`. |
+| `summer_list_my_assets` | List/search the signed-in user's generated and uploaded assets. Empty query lists recent assets. |
+| `summer_get_asset` | Fetch one exact asset by ID with file URL, download URL, viewer URL, metadata, license, and visibility. |
+| `summer_get_asset_download_url` | Get the primary or thumbnail download URL for a specific asset. Stable shape for future signed URLs. |
+| `summer_import_asset` | Search, choose the top match, download, run Godot import, and optionally instantiate 3D models. |
+| `summer_import_asset_by_id` | Import one exact Summer asset ID. Use after generation jobs or when the user selects a specific asset. |
+| `summer_import_hdri` | Search Poly Haven's CC0 HDRIs (public API, no Summer login), import the `.hdr`/`.exr` into `res://sky/`, and get the exact `summer_run_script` snippet that wires it as the WorldEnvironment sky. The cheapest whole-scene lighting upgrade. |
+| `summer_slice_asset_sheet` | Detect and crop every distinct asset from a generated sheet image into named individual assets (works without the engine; import the results afterwards). |
+
+### Asset generation (5 — metered)
+
+| Tool | Use |
+|---|---|
+| `summer_generate_image` | AI image gen. |
+| `summer_generate_3d` | Image-to-3D. |
+| `summer_generate_audio` | SFX / music gen. |
+| `summer_generate_video` | Video gen. |
+| `summer_generate_motion` | Generate/apply 3D skeletal motion from a rigged asset. |
+
+### Job tracking (2)
+
+| Tool | Use |
+|---|---|
+| `summer_check_job` | Poll a generation job. |
+| `summer_batch` | Run multiple ops as a transaction. |
+
+### Meta (4)
+
+| Tool | Use |
+|---|---|
+| `summer_start_game_task` | Route a user goal into the right workflow, skills, MCP tool groups, asset policy, gates, and verification path. |
+| `summer_get_studio_workflow` | Discover Summer Studio's guided workflow recipes (starter prompts, ordered steps, required tools) for a goal. |
+| `summer_get_project_context` | Project, scene, and `.summer` memory summary — call at start of session. Binds the session to the open project and surfaces a `capabilitySkewWarning` when the engine build and CLI have drifted; tools whose op the engine provably lacks return a structured `engine_lacks_op` result instead of running. |
+| `summer_get_agent_playbook` | Daily operating contract (observe-first loop, content routing, invariants, verification ritual) — call at start of session. Also served natively as the `summer_agent_playbook` MCP prompt. |
+
+### Creator platform (3)
+
+| Tool | Use |
+|---|---|
+| `summer_creator_publish` | Compute the exact `.pck` digest and size, require user confirmation, then run versioned prepare → write-once upload → finalize. The server independently verifies `publish` scope, ownership, bytes, and review state. |
+| `summer_creator_releases` | List real creator-owned releases from `summer.creator.v1`, with opaque cursor pagination. |
+| `summer_creator_config` | Read or confirm updates to the shared non-secret `~/.summer/config.json`. It never accepts or returns tokens. |
+
+### Library search (2)
+
+| Tool | Use |
+|---|---|
+| `summer_search_library` | Search the library (skills, tools, templates, references, examples, collections) by describing the task in plain words; ranked ids with `matched_by` (lexical / semantic). The first move for any task; works without the engine. |
+| `summer_read_library` | Load one entry by id: a skill's SKILL.md plus metadata, a tool's call recipe, a template's pin, a reference's body. The last line is the `entry_id` footer to report through `summer_library_feedback`. |
+
+### Library feedback (1)
+
+| Tool | Use |
+|---|---|
+| `summer_library_feedback` | Report library-entry outcomes (worked/wrong/outdated/...) so entries get fixed and re-ranked. Fire-and-forget with a 1s cap; enum-first schema with no field for project files, chat content, or code; honors `SUMMER_NO_TELEMETRY=1` and `DO_NOT_TRACK=1`. |
+
+## Common pattern
+
+Every scene-touching skill should follow this loop:
+
+1. `summer_start_game_task` — route the goal into skills/tools/gates.
+2. `summer_get_project_context` — orient.
+3. `summer_get_agent_playbook` — read the rules.
+4. Resolve the exact `res://` scene path; open it only for an intentional current-tab read/UI action.
+5. Pass that `scenePath` to mutations (`summer_add_node`, `summer_set_prop`, `summer_connect_signal`, ...).
+6. Mutation tools append one final `SaveScene`; use `summer_save_scene` directly only for a standalone save/save-as.
+7. `summer_get_script_errors` — catch GDScript breakage.
+8. `summer_play` → `summer_get_debugger_errors` → `summer_screenshot` (see what's on screen) → `summer_stop` if verifying runtime.
+
+Every asset-generation skill should follow this loop:
+
+1. `summer_search_assets` or `summer_list_my_assets` — reuse before generating when reasonable.
+2. `summer_generate_image` / `summer_generate_3d` / `summer_generate_audio` — metered creation.
+3. `summer_check_job` if the generation was async.
+4. `summer_get_asset` — resolve the returned `assetId`, `rigAssetId`, or `animationAssetId`.
+5. `summer_import_asset_by_id` — import the exact result into Godot's pipeline.
+6. `summer_get_asset_download_url` — only when the user explicitly wants a downloadable file/link.
+
+## summer_set_resource_property — nested properties
+
+Use it to reach a property *of a resource attached to a node* — mesh size, shape radius, material colour — the thing `summer_set_prop` cannot reach.
+
+```
+summer_add_node(parent="/", type="MeshInstance3D", name="Box", scenePath="res://main.tscn")
+summer_set_prop(path="Box", key="mesh", value="BoxMesh", scenePath="res://main.tscn")
+summer_set_resource_property(
+    nodePath="Box", resourceProperty="mesh", subProperty="size",
+    value="Vector3(2, 2, 2)", scenePath="res://main.tscn")
+```
+
+`nodePath`, `resourceProperty` and `subProperty` are all required and canonical. There is no dotted `"mesh.size"` form.
+
+**Inline `sub_resource` targets work.** An earlier revision of this file claimed the op silently fails on an inline sub-resource and told you to save the resource as a standalone `.tres` first. That was wrong, and it propagated into nine skills. The implementation reads `node->get(resourceProperty)` and sets the sub-property on whatever comes back (`modules/1summer_engine/editor/ops/scene_ops.cpp:1273-1400`) — there is no inline-versus-external branch anywhere in it. The canonical example in the shipped `summer_batch` description does exactly this against an inline mesh.
+
+Structural failures are explicit:
+
+| Error | Meaning |
+|---|---|
+| `no edited scene` | Nothing open — pass `scenePath`. |
+| `node not found: <path>` | `nodePath` is wrong; it is relative to the scene root. |
+| `property is not a resource` | `resourceProperty` names a plain value, not a resource. |
+| `resource is null` | The node has the property but nothing is assigned yet. Assign it first. |
+
+What is *not* explicit on current engines is a bad value shape. `summer_set_prop` and `summer_set_resource_property` convert only string values (`res://` path → load, Resource class name → instantiate, anything else → `str_to_var`); a JSON object (reachable through `summer_batch`, which forwards ops verbatim, or raw `/api/ops`), a misspelled `key`/`subProperty`, or a wrong-typed value passes straight to `set()` and returns `ok:true` while silently no-op'ing or coercing destructively — a dict assigned to `material_override` clears the material, a dict assigned to a `Color` becomes `Color(0,0,0,1)`. Newer engines reject these with `unknown_property` / `bad_value_shape` / `type_mismatch`. Always pass class names and `Color(...)`/`Vector3(...)` strings, and confirm the result in the saved `.tscn` or a snapshot diff, never from `ok` alone.

package/library/references/mcp-tools-reference/resource.yaml

@@ -0,0 +1,17 @@
+id: reference/mcp-tools-reference
+kind: reference
+version: 1.0.3
+summary: Canonical reference for which Summer MCP tool to call — skills should reference tool names exactly as written here.
+use_when:
+  - choosing between Summer MCP tools and host tools for an operation
+  - authoring a skill that names Summer MCP tools
+facets:
+  lifecycle: [build]
+  domains: [mcp, tools]
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - references/mcp-tools-reference.md

package/library/references/product-map/product-map.md

@@ -0,0 +1,103 @@
+# Summer product map
+
+> Every place an agent can send the user: pages on summerengine.com and docs.summerengine.com, and surfaces inside the Summer Engine editor. One table, two surfaces. Open any row with `summer_open` (MCP) or `summer open <id>` (CLI); the `navigate-summer` skill says when to open a surface for the user and when to act through the API instead.
+
+**Generated file.** Rendered from the tool's own data by `node scripts/navigation/render-product-map.ts`; a test fails when this file and the data disagree. Do not edit by hand.
+
+## Who owns what
+
+- **Web rows** come from summerengine.com's own route catalog (`/agent-routes.json`, published from the web repo's `src/lib/navigation/routes.ts`). The toolkit vendors a snapshot (`assets/navigation/web-routes.json`, refreshed with `npm run sync:web-routes`); it does not invent pages.
+- **Editor rows** are ids of Summer Engine's one navigation table (`navigate_ops.cpp`, op `Navigate`). The running engine advertises which ids it can open in `/api/health` `capabilities.navigation`; `summer open --list` shows availability from the connected engine. Engines that predate the `Navigate` op can still serve the rows with a legacy op (last-but-one column); every other row answers `engine_lacks_op` with an update hint.
+
+## How to read a row
+
+- **id** — what you pass as `target`. Aliases in parentheses also resolve. Intent phrases in the third column resolve too (`summer open "change my plan"`).
+- **where** — the URL (web) or the engine op (editor). `{slot}` is a required param; `[/{slot}]` is optional. Web URLs are shown on the apex host; the tool uses the configured gateway (`gateway.url` / `SUMMER_GATEWAY_URL`), so a staging gateway opens staging.
+- **params** — slot values passed as `params: { … }`. `guide` accepts an agent name (`cursor`, `claude-code`, `codex`, `gemini`, …) or a guide slug; `section` is one of the game's Studio sections; `line`/`col` are for `script`.
+- **login** — the page needs a Summer account; when this machine has no CLI login token the tool opens `/login?returnUrl=<path>` and the destination loads after sign-in. Editor rows need Summer Engine running with the project open; otherwise the tool reports `engine_not_running` and nothing opens.
+
+Things that do not exist and are therefore not in the map (verified against the web app, 2026-09-03): a public play URL for a published game (`/games` is a curated gallery; distribution runs through a game's Builds / Releases / Store page in Studio, so "my published games" is `my-games`), and an API-token or MCP-credential page (CLI login is a device-code flow started by `summer login`).
+
+## Web
+
+| id | surface | intents (excerpt) | where | params | login | what the user sees |
+|---|---|---|---|---|---|---|
+| `home` | web | "summer website", "homepage", "the website", "summerengine.com" | `https://summerengine.com/` | — | — | The Summer homepage. |
+| `pricing` | web | "pricing", "how much does it cost", "plans and prices", "what does summer cost" | `https://summerengine.com/pricing` | — | — | Free tier and paid AI-usage tiers; upgrade buttons start Stripe checkout. |
+| `download` | web | "download the app", "download summer engine", "install summer engine", "get the desktop app" | `https://summerengine.com/download` | — | — | Desktop installers for macOS and Windows. |
+| `cli-guide` | web | "cli page", "how do i install the cli", "cli setup", "command line install" | `https://summerengine.com/cli` | — | — | How to install the summer-engine CLI and the one-paste agent prompt. |
+| `mcp-guide` | web | "mcp setup", "set up the mcp", "connect my agent", "how do i set up cursor" | `https://summerengine.com/mcp[/{guide}]` | `guide` | — | The MCP + CLI hub, or the step-by-step guide for one agent (Claude Code, Cursor, Codex, Gemini CLI, Cline, Kilo Code, OpenCode, Devin, local LLMs, Ollama, LM Studio, Goose). |
+| `templates` | web | "browse templates", "template gallery", "game templates", "starter projects" | `https://summerengine.com/templates` | — | — | Browse every game template by category and use case. |
+| `templates-start` | web | "start a new game on the web", "web onboarding", "plan builder" | `https://summerengine.com/templates/start` | — | — | The web onboarding flow that turns a template pick into a plan. |
+| `asset-store` | web | "asset store", "find assets", "browse assets", "free game assets" | `https://summerengine.com/asset-store` | — | — | Browse 2D art, 3D models, sprites, animations, music and sound effects. |
+| `plugins` | web | "plugins", "plugin catalog", "skills catalog" | `https://summerengine.com/plugins` | — | — | The public plugin and skill catalog. |
+| `changelog` | web | "changelog", "what's new", "release notes", "what changed in the last update" | `https://summerengine.com/changelog[/{version}]` | `version` | — | Release notes: the index, or one engine version. |
+| `blog` | web | "blog", "blog posts", "articles" | `https://summerengine.com/blog` | — | — | The Summer blog. |
+| `roadmap` | web | "roadmap", "what's coming", "planned features" | `https://summerengine.com/roadmap` | — | — | The public product roadmap. |
+| `games` | web | "games gallery", "featured games", "game jams", "jam" | `https://summerengine.com/games` | — | — | The public gallery of featured games, jams and events. |
+| `docs` | web | "documentation", "the docs", "read the docs", "manual" | `https://docs.summerengine.com/` | — | — | docs.summerengine.com, the Summer documentation. |
+| `docs-mcp` | web | "mcp docs", "mcp documentation", "how the mcp works" | `https://docs.summerengine.com/mcp/overview` | — | — | The MCP overview in the documentation. |
+| `docs-install` | web | "installation docs", "install instructions", "how to install" | `https://docs.summerengine.com/essentials/installation` | — | — | Installing Summer Engine, step by step. |
+| `docs-quickstart` | web | "quickstart", "getting started guide", "first project tutorial" | `https://docs.summerengine.com/quickstarts/fresh-project` | — | — | Fresh-project quickstart in the documentation. |
+| `docs-sdk` | web | "sdk reference", "sdk docs", "api reference", "summer sdk" | `https://docs.summerengine.com/api-reference/summer-sdk` | — | — | The Summer SDK API reference. |
+| `login` | web | "sign in", "log in", "login page" | `https://summerengine.com/login` | — | — | The sign-in page (email/password or Google). |
+| `signup` | web | "sign up", "create an account", "register" | `https://summerengine.com/signup` | — | — | The sign-up page. |
+| `studio` | web | "studio", "summer studio", "open studio", "the studio" | `https://summerengine.com/studio` | — | — | The Studio workspace (home tab). |
+| `my-games` (`projects`, `my-projects`, `published-games`) | web | "my games", "my projects", "my published games", "published games" | `https://summerengine.com/studio/games` | — | login | Your games (projects) in Studio: overview, builds, releases, store pages. |
+| `game` | web | "open this game in studio", "builds for my game", "releases of my game", "store page for my game" | `https://summerengine.com/studio/games/{gameId}[/{section}]` | `gameId` (required), `section` | login | One game's Studio pages: overview, builds, releases, store page, passport, players, analytics, economy, settings, danger zone and more. |
+| `billing` (`plan`, `subscription`, `payments`) | web | "billing", "change my plan", "upgrade my plan", "upgrade" | `https://summerengine.com/studio?tab=billing` | — | login | Current plan, upgrade, Stripe billing portal (payment method, invoices), top-ups. |
+| `usage` (`spending`, `credits`) | web | "usage", "how many credits do i have left", "spending", "credit usage" | `https://summerengine.com/studio?tab=billing&section=usage` | — | login | Account usage and spending: how many credits were used and on what. |
+| `settings` | web | "account settings", "settings page", "change my email", "change my password" | `https://summerengine.com/studio?tab=settings` | — | login | Account settings in Studio (email, password, preferences, delete account). |
+| `team` (`members`, `workspace`) | web | "team", "members", "invite a teammate", "workspace members" | `https://summerengine.com/studio?tab=team` | — | login | Workspace members and invites. |
+| `cloud` | web | "project cloud", "cloud storage", "cloud projects", "synced projects" | `https://summerengine.com/studio?tab=cloud` | — | login | Project Cloud storage and synced projects. |
+| `my-assets` (`assets`, `library`) | web | "my assets", "generated assets", "my library", "saved assets" | `https://summerengine.com/studio?tab=assets` | — | — | Assets you generated or saved, ready to import. |
+| `workflows` | web | "guided workflows", "workflows", "studio recipes" | `https://summerengine.com/studio?tab=workflows` | — | — | Guided Studio workflows (recipes). |
+| `story-builder` | web | "story builder", "write my story", "narrative tool" | `https://summerengine.com/studio?tab=storyBuilder` | — | login | The Story Builder tool. |
+| `board` | web | "board", "task board", "kanban" | `https://summerengine.com/studio?tab=board` | — | login | The project board. |
+| `studio-plugins` | web | "plugins in studio", "manage my plugins", "installed plugins" | `https://summerengine.com/studio?tab=plugins` | — | — | Plugins tab inside Studio. |
+| `studio-store` | web | "asset store in studio", "store tab" | `https://summerengine.com/studio?tab=store` | — | — | The Asset Store as a Studio tab. |
+| `generate-image` (`2d`, `image`) | web | "image generator", "generate an image on the web", "2d tab", "make a picture in studio" | `https://summerengine.com/studio?tab=image` | — | — | Generate or edit images (the 2D tab). |
+| `generate-3d` (`3d`) | web | "3d generator", "generate a 3d model on the web", "3d tab" | `https://summerengine.com/studio?tab=3d` | — | — | Generate 3D models (the 3D tab). |
+| `generate-audio` (`audio`) | web | "audio generator", "generate audio on the web", "audio tab", "music generator" | `https://summerengine.com/studio?tab=audio` | — | — | Generate speech, music and sound effects. |
+| `generate-video` (`video`) | web | "video generator", "generate a video on the web", "video tab" | `https://summerengine.com/studio?tab=video` | — | — | Generate video (the Video tab). |
+| `generate-animation` (`animation`) | web | "animation tab", "animation tools", "retarget on the web", "upload a mocap clip" | `https://summerengine.com/studio?tab=animation` | — | — | Animation tools (retargeting, mocap uploads). |
+| `chat` | web | "web chat", "chat on the website", "summer chat" | `https://summerengine.com/chat` | — | login | A new agent chat on the web. |
+| `skills` | web | "my skills page", "edit my skills on the web", "skills editor" | `https://summerengine.com/skills` | — | login | The agent-skills editor on the web. |
+| `profile` | web | "my public profile", "public profile of", "creator page", "see my profile" | `https://summerengine.com/{username}` | `username` (required) | — | A creator's public profile page. |
+| `edit-profile` | web | "edit my profile", "change my avatar", "update my bio", "profile editor" | `https://summerengine.com/profile/edit` | — | login | Edit your public profile. |
+| `submit-game` | web | "submit my game", "add my game to the gallery", "enter the jam", "submit to the jam" | `https://summerengine.com/games/create` | — | login | Submit a game to the public gallery or a jam. |
+
+## Editor
+
+| id | surface | intents (excerpt) | where (Navigate op) | params | legacy op (pre-Navigate engines) | what the user sees |
+|---|---|---|---|---|---|---|
+| `scene` | editor | "open the scene", "open this scene", "show the scene", "switch to the scene" | `Navigate target=scene path=<path> (path defaults to the main scene)` | `path` | `OpenScene` | The scene becomes the current tab in Summer Engine. |
+| `main-scene` | editor | "open the main scene", "main scene", "go to the main scene", "the starting scene" | `Navigate target=scene (path defaults to the main scene)` | — | `OpenScene` | The project's configured main scene becomes the current tab. |
+| `node` | editor | "select the node", "show me the node", "focus the player node", "highlight the node" | `Navigate target=node path=<node> scene=<scene>` | `node` (required), `scene` | `SelectNode` | The node is highlighted in the Scene tree and its properties show in the Inspector. |
+| `script` | editor | "open the script", "show me the script", "open the gdscript file", "go to the script" | `Navigate target=script path=<path> line=<line> col=<col>` | `path` (required), `line`, `col` | `OpenResource` | The script opens in the Script editor and takes focus (at a line, when given). On engines without the Navigate op it opens without taking focus. |
+| `file` | editor | "show the file in the filesystem", "reveal the file", "find the file in the editor", "where is this asset" | `Navigate target=file path=<path>` | `path` (required) | `RevealInFileSystem` | The FileSystem dock comes to the front, scrolled to the file. |
+| `files` (`filesystem`, `file-system`) | editor | "filesystem dock", "file dock", "show the files", "project files panel" | `Navigate target=dock name=file_system` | — | `FocusDock` {"dock":"file_system"} | The FileSystem dock comes to the front. |
+| `scene-tree` | editor | "scene tree", "scene dock", "show the scene tree", "node tree panel" | `Navigate target=dock name=scene_tree` | — | `FocusDock` {"dock":"scene_tree"} | The Scene tree dock comes to the front. |
+| `inspector` | editor | "inspector", "show the inspector", "properties panel", "inspector dock" | `Navigate target=dock name=inspector` | — | `FocusDock` {"dock":"inspector"} | The Inspector dock comes to the front. |
+| `import-dock` | editor | "import dock", "import settings panel", "show import options" | `Navigate target=dock name=import` | — | — (needs an engine with the Navigate op) | The Import dock comes to the front. |
+| `signals-dock` | editor | "signals dock", "node dock", "show the signals", "connect signals panel" | `Navigate target=dock name=node` | — | — (needs an engine with the Navigate op) | The Node dock (signals and groups) comes to the front. |
+| `changes-dock` | editor | "changes dock", "show the changes", "what did the agent change", "diff panel" | `Navigate target=dock name=changes` | — | — (needs an engine with the Navigate op) | The Changes dock comes to the front. |
+| `screen-2d` | editor | "switch to 2d", "2d view", "show the 2d editor" | `Navigate target=screen-2d` | — | — (needs an engine with the Navigate op) | The main editor switches to the 2D view. |
+| `screen-3d` | editor | "switch to 3d", "3d view", "show the 3d editor", "show me the viewport" | `Navigate target=screen-3d` | — | — (needs an engine with the Navigate op) | The main editor switches to the 3D view. |
+| `screen-script` | editor | "switch to the script editor", "script view", "show the code editor" | `Navigate target=screen-script` | — | — (needs an engine with the Navigate op) | The main editor switches to the Script view. |
+| `screen-game` | editor | "switch to the game view", "game tab", "show the running game view" | `Navigate target=screen-game` | — | — (needs an engine with the Navigate op) | The main editor switches to the Game view. |
+| `screen-assetlib` | editor | "asset library tab", "open the asset lib", "godot asset library" | `Navigate target=screen-assetlib` | — | — (needs an engine with the Navigate op) | The main editor switches to the AssetLib view. |
+| `viewport-show` | editor | "show the viewport column", "bring back the viewport", "unhide the editor viewport" | `Navigate target=viewport-show` | — | — (needs an engine with the Navigate op) | The agent layout's viewport column becomes visible. |
+| `viewport-hide` | editor | "hide the viewport column", "hide the editor viewport", "chat only layout" | `Navigate target=viewport-hide` | — | — (needs an engine with the Navigate op) | The agent layout's viewport column is hidden. |
+| `assistant` | editor | "open the assistant", "show the chat dock", "summer assistant", "ai chat in the editor" | `Navigate target=assistant path=<path>` | `path` | — (needs an engine with the Navigate op) | The Summer assistant (chat) dock opens. |
+| `project-settings` | editor | "project settings", "settings", "open project settings", "input map settings" | `Navigate target=project-settings tab=<tab>` | `tab` | — (needs an engine with the Navigate op) | The Project Settings dialog opens. |
+| `editor-settings` | editor | "editor settings", "settings", "open editor settings", "editor preferences" | `Navigate target=editor-settings` | — | — (needs an engine with the Navigate op) | The Editor Settings dialog opens. |
+| `output` | editor | "output panel", "show the output", "editor console", "show the log" | `Navigate target=panel name=output` | — | — (needs an engine with the Navigate op) | The Output panel opens at the bottom of the editor. |
+| `debugger` | editor | "debugger panel", "show the debugger", "open the debugger", "errors panel" | `Navigate target=panel name=debugger` | — | — (needs an engine with the Navigate op) | The Debugger panel opens at the bottom of the editor. |
+| `editor-window` | editor | "bring the editor to the front", "focus summer engine", "show the editor window", "switch to the editor" | `Navigate target=editor-window` | — | — (needs an engine with the Navigate op) | The Summer Engine window comes to the front. |
+
+## Shorthands the tool also accepts
+
+- A `res://` path: `.tscn`/`.scn` → `scene`, `.gd`/`.cs` → `script`, anything else → `file`.
+- A summerengine.com path: `/pricing` resolves to the matching row; an unknown path on the gateway origin opens as given and is reported `unmapped: true`.
+- Anything that is not on summerengine.com or docs.summerengine.com is refused.

package/library/references/product-map/resource.yaml

@@ -0,0 +1,33 @@
+id: reference/product-map
+kind: reference
+version: 1.0.0
+summary: The product map — every summerengine.com page and editor surface an agent can open for the user, with intent phrases, URL or op, required context, and status.
+use_when:
+  - resolving where a user intent lives — "where do I change my plan", "where are my published games", "how do I get to the MCP guide for Codex"
+  - deciding whether a destination needs login, a running engine, or a parameter (gameId, path, node) before calling summer_open
+  - checking whether an editor surface (assistant dock, project settings, 2D/3D switch) can be opened on this engine build or is still planned
+do_not_use_when:
+  - you already know the target id — call summer_open directly (the tool carries the same table)
+  - looking up which Summer MCP tool performs a change — that is the mcp-tools-reference
+facets:
+  lifecycle:
+    - build
+    - launch
+    - support
+  domains:
+    - navigation
+    - agent-workflow
+  modalities:
+    - docs
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/open
+  skills:
+    - skill/navigate-summer
+  references:
+    - reference/mcp-tools-reference
+source: official
+license: MIT
+status: stable

package/{references → library/references/public-surface-language}/public-surface-language.md

@@ -17,14 +17,12 @@ source of truth is the repository compatibility contract. Neither number is a
 permanent Summer identity, so creator prompts and skills should not pin
 themselves to one upstream release.
 
-Run the focused regression guard and inventory with:
+There is no automated guard for this yet. Before a release, list the remaining
+upstream references across the shipped surfaces and review each one:
 
 ```bash
-npm run test:public-language
+grep -rn -i "godot" README.md AGENTS.md CHANGELOG.md library/ | grep -v -i "project.godot\|\.godot/"
 ```
 
-The guard blocks known Godot-led identity phrases and stale fixed-4.5 scaffold
-language across shipped surfaces. It also prints the remaining Godot-reference
-inventory grouped by file. This is intentionally not a semantic linter: a human
-must still review those references and confirm that each is technical,
-migration-related, attribution, or legal context.
+Keep references that are technical, migration-related, attribution, or legal
+context; rewrite identity claims. This is a human review, not a linter.

package/library/references/public-surface-language/resource.yaml

@@ -0,0 +1,17 @@
+id: reference/public-surface-language
+kind: reference
+version: 1.0.0
+summary: The Summer public-surface language boundary — when to say Summer game / Summer SDK and when Godot terminology remains correct.
+use_when:
+  - writing user-facing copy, CLI errors, skill descriptions, or generated prompts
+  - deciding whether a technical or legal context calls for Godot terminology
+facets:
+  lifecycle: [build]
+  domains: [naming, product-language]
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - references/public-surface-language.md

package/library/references/summer-folder/resource.yaml

@@ -0,0 +1,20 @@
+id: reference/summer-folder
+kind: reference
+version: 1.0.1
+summary: The canonical layout of the project-scoped .summer/ folder — GameSoul.md, art/audio bibles, build plan, memory, and locked state.
+use_when:
+  - authoring a skill that writes durable design output or project memory
+  - reading or extending a project's .summer/ state
+facets:
+  lifecycle: [build]
+  domains: [project-memory, conventions]
+compatibility:
+  engine: ">=4.6"
+related:
+  references:
+    - reference/collaborative-protocol
+source: official
+license: MIT
+status: stable
+aliases:
+  - references/summer-folder.md