summer-engine 3.0.0 → 3.2.0

package/integrations/vscode-copilot/README.md

@@ -1,12 +1,12 @@
-# VS Code Copilot integration
+# GitHub Copilot in VS Code integration
 
-No manifest file is generated in this repo for VS Code Copilot —
-`manifest-target.json` is intentionally empty. Support is delivered at install
-time by `summer setup vscode-copilot`, which writes:
+No manifest file is generated in this repo for GitHub Copilot in VS Code — `manifest-target.json`
+is intentionally empty. Support is delivered at install time by
+`summer setup vscode-copilot` (aliases: `vscode`, `vs-code`, `vs-code-copilot`, `github-copilot-vscode`), which writes:
 
-- MCP config: VS Code's user-profile `mcp.json` (user scope) or
-  `./.vscode/mcp.json` (project scope), in VS Code's MCP config format.
-- Skills: `summer skills install --agent vscode-copilot` writes skill files to
-  `~/.copilot/skills/` (user scope) or `./.github/skills/` (project scope).
+- MCP config: `~/Library/Application Support/Code/User/mcp.json`; Linux `~/.config/Code/User/mcp.json`; Windows `%APPDATA%/Code/User/mcp.json` (user); `.vscode/mcp.json` (project).
+  Shape: `servers.summer-engine = { type: "stdio", command, args }`.
+- Skills: `~/.agents/skills` (user) or `.agents/skills` (project) as `<skill>/SKILL.md`.
+- After: Restart VS Code or run MCP: List Servers, then start summer-engine in Copilot Agent mode.
 
-Source of truth: `src/installer/agent-config.ts`, `src/cli/commands/skills.ts`.
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/warp/README.md

@@ -0,0 +1,12 @@
+# Warp integration
+
+No manifest file is generated in this repo for Warp — `manifest-target.json`
+is intentionally empty. Support is delivered at install time by
+`summer setup warp` (aliases: `warp-terminal`), which writes:
+
+- MCP config: `~/.warp/.mcp.json`; Windows `%USERPROFILE%/.warp/.mcp.json` (user); `.warp/.mcp.json` (project).
+  Shape: `mcpServers.summer-engine = { command, args }`.
+- Skills: `~/.agents/skills` (user) or `.agents/skills` (project) as `<skill>/SKILL.md`.
+- After: Warp detects the file and spawns the server; check Settings > AI > MCP servers.
+
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/warp/manifest-target.json

@@ -0,0 +1,3 @@
+{
+  "targets": []
+}

package/integrations/windsurf/README.md

@@ -1,13 +1,12 @@
-# Windsurf (Devin Desktop) integration
+# Devin Desktop (formerly Windsurf) integration
 
-No manifest file is generated in this repo for Windsurf — `manifest-target.json`
+No manifest file is generated in this repo for Devin Desktop (formerly Windsurf) — `manifest-target.json`
 is intentionally empty. Support is delivered at install time by
-`summer setup windsurf`, which writes:
+`summer setup windsurf` (aliases: `devin`, `devin-desktop`, `devindesktop`), which writes:
 
-- MCP config: `~/.codeium/windsurf/mcp_config.json` (user scope; project scope
-  writes `.windsurf/mcp_config.json` for teams that load workspace config —
-  Windsurf documents MCP configuration as user-scoped).
-- Skills: `summer skills install --agent windsurf` writes the `.windsurfrules`
-  rule file (`~/.windsurfrules` user scope, `./.windsurfrules` project scope).
+- MCP config: `~/.codeium/windsurf/mcp_config.json`; Windows `%USERPROFILE%/.codeium/windsurf/mcp_config.json` (user); user scope only (project requests fall back with a warning).
+  Shape: `mcpServers.summer-engine = { command, args }`.
+- Skills: `~/.agents/skills` (user) or `.agents/skills` (project) as `<skill>/SKILL.md`.
+- After: Restart Devin Desktop (formerly Windsurf) and refresh MCP servers from the agent settings. Devin's docs say mcp_config.json configures the Cascade agent; for the Devin agent add the server in the app's MCP settings with the same command.
 
-Source of truth: `src/installer/agent-config.ts`, `src/cli/commands/skills.ts`.
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/zed/README.md

@@ -0,0 +1,12 @@
+# Zed integration
+
+No manifest file is generated in this repo for Zed — `manifest-target.json`
+is intentionally empty. Support is delivered at install time by
+`summer setup zed` (aliases: `zed-editor`), which writes:
+
+- MCP config: `~/.config/zed/settings.json`; Windows `%APPDATA%/zed/settings.json` (user); user scope only (project requests fall back with a warning).
+  Shape: `context_servers.summer-engine = { source: "custom", command, args, env }`.
+- Skills: `~/.agents/skills` (user) or `.agents/skills` (project) as `<skill>/SKILL.md`.
+- After: Zed reloads settings.json live; open the Agent panel and check summer-engine under MCP servers.
+
+Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/zed/manifest-target.json

@@ -0,0 +1,3 @@
+{
+  "targets": []
+}

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

@@ -13,17 +13,18 @@
 - 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.
+**Use host tools for** git, shell, searching outside the project, 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)
+## Tool surface (101 tools)
 
-### Project files (3)
+### Project files (4)
 
 | Tool | Use |
 |---|---|
-| `summer_read_file` | Read project text plus a full-file sha256 receipt. |
+| `summer_read_file` | Read project text plus a full-file sha256 receipt. Big files in parts: `offset`/`limit` page by lines (or `unit:'bytes'`), `data.window` gives `next_offset`/`eof`; for JSON, `json_path` picks one value (`pieces.wall_a`), `keys` keeps matching object keys (`['wall_*']`), `keys_only` lists key names. The sha256 always covers the whole file. |
+| `summer_grep` | Regex search over project files (ripgrep through the engine): file, line and text per match, `context_lines` before/after (0-10), `path` (res:// dir or file), `glob`, `max_results` (default 50) with `truncated`. Find the part of a big file you need, then read just that part with `summer_read_file`. |
 | `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. |
 
@@ -36,11 +37,11 @@
 | `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_instantiate_scene` | Add an existing scene or 3D model as a child node; `position` / `rotation_degrees` / `scale` (or `transform`) place it in the same call. |
+| `summer_inspect_node` | Read a single node's properties (about 5 KB). `fields` keeps only named properties/globs plus derived `transform`, `global_transform`, `scene_file_path`, `aabb`, `warnings` — e.g. `fields:['transform','global_transform','scene_file_path']`. |
 | `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_replace_node` | Swap a node for another scene/model or type in the explicit `scenePath` (a `.tscn`), keeping parent, index, name, transform, property overrides and added children. Verified: it saves, reads the saved file back and returns `persisted:true` only when the file holds the new scene; otherwise an error with `failure_reason: not_persisted`. `not_carried_over` lists what could not travel (groups, signal connections, sub_resource values). |
 | `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. |
 
@@ -50,8 +51,8 @@
 |---|---|
 | `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. |
+| `summer_inspect_resource` | Read a resource FILE (`path`): a Mesh `.res` gives AABB, surfaces (primitive, vertex/index counts, attributes, triangles, material) and materials; a `.tscn`/`.glb` gives its nodes and meshes; anything else its non-default editor properties. Or a resource a node of the active scene holds (`nodePath` + `property`). |
+| `summer_connect_signal` | Wire a signal between nodes in the explicit `scenePath` (a `.tscn`). Connects with `CONNECT_PERSIST` through a RunSceneScript probe (the engine's ConnectSignal op never saves the connection), saves, and returns `persisted:true` / `verified:true` only when the saved file holds the `[connection]` line; otherwise `failure_reason: not_persisted`. |
 
 ### Project & input (2)
 
@@ -96,7 +97,7 @@ Preview — the `Ui*` engine ops ship with a follow-up engine build; until then
 
 | 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_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`. Lists at most 200 nodes by default; `path_prefix` (one subtree), `classes`, `fields` (e.g. `['pos','aabb']`) and `offset` keep it small, `matched_counts` counts a subtree's classes. `counts` and the `snapshot_id` baseline always cover the whole scene. |
 | `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`. |
@@ -108,11 +109,25 @@ Bounded spatial evidence for deliberate 3D arrangement. All five take exact `sce
 | 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_snap_to_surface` | Seat one subject on the first surface along a world ray (default downward); mutation + save. `evidence: physics` = collider sweep; `visual_aabb` = the engine's mesh-only broad-phase fallback; `visual_mesh` = the tool re-measured a `visual_aabb` answer (failure or seat) on visible triangles, placed the subject with one SetProp, verified the gap and saved (`engine`, `verify` in the receipt; `mesh_fallback` says why when it could not). A prop sunk into its support is lifted by the overlap depth plus 2 cm (at most its own extent, 0.5 m) and settled from there (`recovery` in the receipt). `gap_exceeds_hit_travel` / `overlap_recovery_exceeded` failures add `start_overlap`, `blocking` (the nodes it touches or sits in), `below` and a `next_step`. |
 | `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. |
 
+### Kit placement (7)
+
+Placement of modular kit pieces from measured geometry, built on the existing ops (a read-only `RunSceneScript` probe, then `SetProp` / `SnapToSurface` / `InstantiateScene` with the usual scene target, undo and final save). Each takes exact paths, needs the scene open in the editor (any tab; physics rays need the active tab) and returns a receipt under 5 KB that names its evidence. Arguments, result shapes, limits and the ops each one uses: `skill/spatial-placement` (`references/kit-placement-tools.md`).
+
+| Tool | Use |
+|---|---|
+| `summer_inspect_asset` | Measure a `.tscn`/`.glb`/`.gltf` (or Mesh) WITHOUT adding it to a scene. A `summary` block first (AABB, origin label, the two largest opposite plane pairs with a `one_sided` flag per plane, port-like loop ids such as `+Y`), then per-mesh AABBs and triangle counts, the 6 largest planar faces, open boundary loops with stable ids by facing and position (`detail: "summary"` lists only port-like ones), Marker3D anchors, collision shapes. Read-only. |
+| `summer_place_adjacent` | Put one node's bounds face against another's along an axis (gap, side), lining up the other axes (min/center/max, per axis); facade modules edge to edge, storeys stacked. One SetProp + save, verified. |
+| `summer_attach_to_surface` | Turn a piece so its measured local back axis faces into a surface hit by a ray (up kept), then seat its back face (not its origin) with `SnapToSurface` at a standoff, keeping its height. Refuses and puts the piece back when the seat lands on another node or the move exceeds `maxMove`. Pipes, lamps, AC units, signs. |
+| `summer_repeat_along` | Instance copies of a scene along a line (spacing or count, leftover aligned start/center/end), each placed in the same call; compact receipt with created paths. At most 64. |
+| `summer_connect_ports` | Move and turn a piece so its port (open-loop id such as `+Y`, Marker3D name, or open-loop index) meets another piece's port, facing it; refuses a join that would tilt the piece more than `maxTiltDegrees` (default 5) unless `allowTilt`; verified distance, angle and tilt, and where the piece's other ports now point. |
+| `summer_raycast` | One ray from any point, before anything is placed: hit path, point, normal. Physics first; visual-AABB fallback declared as such. Read-only. |
+| `summer_measure` | Gap/overlap per axis between two nodes, or face coplanarity across 2-32 nodes (proud/recessed). Read-only. |
+
 ### Play / runtime (3)
 
 | Tool | Use |
@@ -149,6 +164,28 @@ Drive and observe the RUNNING game (engine runtime-control ops, preview — `eng
 | `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. |
 
+`summer_screenshot framing:"bookmark"` keeps a clean render (no marks, at most 1024 px) as the bookmark's one previous image in `res://.summer/shots/<bookmark>.jpg` when it has none; an existing one is the compare baseline and is replaced only by `compare_previous:true` (which returns previous | now | difference map in one image) or `update_previous:true`. With `marks:true` each labelled node gets an occlusion test (centre + 4 bounds points) and hidden ones are noted `(hidden behind <path>)`.
+
+### Seeing (5)
+
+Preview. Judge a 3D environment the way a player and an artist would. Every image comes back inline (one grid image per call, never N images) with a compact caption; renders are offscreen copies of the SAVED scene with its REAL WorldEnvironment and lights; nothing in the scene, the open tab or the undo history changes. Disk is bounded: only one previous-image slot per rendered bookmark plus explicit `save_to` copies, JPEG at most 1024 px, at most 20 MB under `res://.summer/shots/` (oldest evicted first). The `verifying-scenes` skill carries the environment review loop.
+
+| Tool | Use |
+|---|---|
+| `summer_frame_nodes` | Fit a camera to the world bounds of 1-16 nodes (`direction` preset or `from` vector, `fill`) and render it with the real environment; `bookmark_name` saves the pose, `marks:true` maps labels to node paths (hidden nodes are noted). An explicit `from` is checked in-engine: walls in the way, or a camera behind or inside a one-sided surface (its back is not drawn, so the image looks through it), open the caption with a WARNING and the nearest valid `from` (+ `fov`). |
+| `summer_shot_sheet` | 1-12 bookmarks/poses in one labelled grid, same tile size, one `view`; `compare_previous:true` gives previous / now / difference map per bookmark with the changed-pixel share and makes this render the next baseline. Without it the baseline is kept (a missing one is created); `update_previous:true` replaces it on purpose. |
+| `summer_debug_views` | One pose as beauty, lighting, unshaded (albedo), world normals, overdraw and wireframe in one grid; the caption names the method per view. |
+| `summer_zoom` | An exact sub-frustum of a `region` (honoured exactly: no pad by default, never widened to an aspect ratio; the image takes the region's aspect) or of `mark` N (pad 0.15; warns when the node is hidden) rendered at full resolution: seams, gaps, floating pieces, texture quality. The caption reports the real zoom and `widened_because`. |
+| `summer_frame_shot` | Smart framing for `establishing`, `eye_level`, `low_angle`, `detail` or `corridor`: candidates measured in-engine (thick sweep visibility, near-lens check, low-angle rule, frame ray grid, a small beauty render per pose for featureless areas and near/far value contrast; walls reject, and so does a camera behind or inside a one-sided surface; props frame; transparent foliage and glass are see-through cover), scored (including the key light's direction and the world edge below the horizon; an establishing pose over 15% empty ground or world edge ranks below every cleaner one), top 3 returned with breakdowns as three different views and each camera's height above the surface below it, best saved as a bookmark, top 3 rendered as one sheet. Eye-level and corridor cameras stand 1.5-1.8 m (or `eye_height`) above the walkable surface and are never raised. |
+
+### Scene audit (1)
+
+Preview. One fast, read-only call that walks every node of a 3D scene and lists likely visual and placement problems, so you know exactly where to look; every issue is a flag to look at, never an auto-fix. Like the seeing tools it works on an offscreen private copy of the SAVED scene (ScenePreview): the open tab never becomes unsaved, undo is untouched, nothing is saved. Save first. The `verifying-scenes` skill carries the loop: audit after each build stage, then frame every error and look item up close before calling the scene done.
+
+| Tool | Use |
+|---|---|
+| `summer_scene_audit` | Checks `through_hole` (ray grids through each facade line: rays that pass the wall and reach the far side of the building), `exposed_edge` (open outline edges of walls, bands, piers and corner blocks nothing covers within 4-7 mm, seen from walkable eye points, with a 2-60 cm reveal, a seam within 4 cm or a gap to the next sheet within 35 cm; warn on bands, look on walls unless `depth_step` agrees), `open_fixture_end` (open ends of run pieces, two or more open rims of one size, nothing joins within 2.5 cm; a cap, funnel or outlet is open by design; warn), `depth_step` (look: ray rows at each facade's band levels and every 1.25 m; band recesses, seams, proud modules, holes; a hole confirms a `through_hole`), `floor_gap` (down rays over the tiles, their seams and the strip from each tile edge to a wall within 1 m, classified by the first surface hit: the void, an underlay through a hole, or an underlay covering the floor's own drain or dip; areas from the missed rays' own footprints with the strip's size), `floating` / `sunken` (2 cm / 3 cm; the embed is against the first surface from above, named), `interpenetration` (3 cm, then every partner it cuts, up to 3), `orientation` (look: long props more than 15 deg off a wall within 1.2 m; never which way to face), `uv_stretch` (over 8:1 or collapsed UVs that an instance shows), `duplicate`, `z_fight` (coplanar overlaps from each mesh's planar face groups, between any two pieces and between two surfaces of one mesh, plus the ray samples; the tolerance is twice the 24-bit depth step at the view distance from the nearest walkable eye point, camera or bookmark, for the main camera's near/far; warn over 0.05 m2 seen from a viewpoint, `render_priority`, depth or normal offsets, see-through (alpha) materials and no depth test demoted to look with the reason), `lights` (per-object light limit, spot rims, shadowed count), `transform` (pieces left at the origin: an identity local transform under an identity parent, touching nothing, not one of a row of siblings; several sharing it warn), `resource`. `z_fight` evidence names the plane's normal and the axis to nudge (world and the piece's local). Returns at most 5 KB: counts and time per check, and one page of issues sorted by severity (`error` / `warn` / `look`) with node path, world position, reason, evidence numbers, the next tool and a `key`. `offset`/`limit` page, `checks`, `root` (subtree) and `min_severity` filter; `accept:[{key, reason}]` writes judged-fine look / warn items to `res://.summer/audit-accept.json` (later audits count them as `accepted` and hide them until their evidence changes; `show_accepted` lists them); `budget_ms` (default 3000) bounds the editor time, and a check past its weighted share stops and shows `partial` (the share it covered) in its counts; the gap detectors run last on the time the others leave; `render:"sheet"` adds one inline image of the page's first 6 issues framed from their open side, tiles labelled `#n`. Every check works from geometry, engine data and materials alone, never names or kit metadata; piece roles (dressing, wall, floor, roof, underlay, insert, facade structure, prop) come from shape. |
+
 ### Diagnostics (7)
 
 | Tool | Use |
@@ -165,7 +202,7 @@ Drive and observe the RUNNING game (engine runtime-control ops, preview — `eng
 
 | Tool | Use |
 |---|---|
-| `summer_search_assets` | Free public asset search (community library + user's own). Sources: `library`, `community`, `my_assets`, `all`. |
+| `summer_search_assets` | Free public asset search (community library + user's own). Sources: `library`, `community`, `my_assets`, `all`. `style` keeps one art direction (realistic, stylized-lowpoly, toon, pixel, hand-painted, voxel); `preview` returns a numbered picture of the first 9 results; curated packs first unless `includeCommunity`. |
 | `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. |
@@ -189,7 +226,7 @@ Drive and observe the RUNNING game (engine runtime-control ops, preview — `eng
 | Tool | Use |
 |---|---|
 | `summer_check_job` | Poll a generation job. |
-| `summer_batch` | Run multiple ops as a transaction. |
+| `summer_batch` | Run multiple ops as a transaction. `InstantiateScene` ops may carry `position` / `rotation_degrees` / `scale` / `transform`; `receipt: "summary"` returns counts, failures with op index and created paths under 5 KB. A `ReparentNode` keeps the moved node's scene-owned children and grandchildren (the engine op drops them from the saved file) and is verified from the saved `.tscn` (`persisted:true` / `verified:true`, else `failure_reason: not_persisted`); a raw `ConnectSignal` is refused — use `summer_connect_signal`. `scenePersistence.saved` only means the SaveScene ran. |
 
 ### Meta (4)
 
@@ -197,7 +234,7 @@ Drive and observe the RUNNING game (engine runtime-control ops, preview — `eng
 |---|---|
 | `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_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. Compact by default (a few KB: `sceneSummary`, scalar `health` with capability counts); `include:['scene_tree','capabilities','settings']` adds the heavy blocks, `omitted` says how. |
 | `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)
@@ -213,7 +250,7 @@ Drive and observe the RUNNING game (engine runtime-control ops, preview — `eng
 | 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`. |
+| `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. A body ends with its relative links and the id that loads each; a linked file loads by `<entry id>/<link as written>` (e.g. `skill/spatial-placement/references/kit-placement-tools.md`). The last line is the `entry_id` footer to report through `summer_library_feedback`. |
 
 ### Library feedback (1)
 
@@ -234,6 +271,13 @@ Every scene-touching skill should follow this loop:
 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.
 
+Read big things in parts, never whole:
+
+- `summer_get_project_context` is compact by default; add `include:['scene_tree']` (or `'capabilities'`, `'settings'`) only when you need that block.
+- `summer_world_snapshot path_prefix:'House3' fields:['pos','aabb']` reads one subtree; `classes` and `offset` narrow and page it.
+- `summer_inspect_node fields:['transform','global_transform','scene_file_path']` reads a transform in a few hundred bytes.
+- `summer_grep` finds the lines (with `context_lines`), then `summer_read_file` reads just that part: `offset`/`limit` for text, `json_path` / `keys` / `keys_only` for JSON such as a kit manifest.
+
 Every asset-generation skill should follow this loop:
 
 1. `summer_search_assets` or `summer_list_my_assets` — reuse before generating when reasonable.

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

@@ -1,6 +1,6 @@
 id: reference/mcp-tools-reference
 kind: reference
-version: 1.0.3
+version: 1.4.0
 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

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

@@ -1,6 +1,6 @@
 id: reference/summer-folder
 kind: reference
-version: 1.0.1
+version: 1.0.2
 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

package/library/references/summer-folder/summer-folder.md

@@ -83,7 +83,7 @@ Then write the fact in normal Markdown so users can inspect and edit it:
 | `/play` | does NOT write here |
 | `/game-feel`, `/vfx-<effect>` | does NOT write here (VFX edits scenes/scripts) |
 | `/tune-performance` | optionally writes `.summer/perf-notes.md` if user requests |
-| `/setup-multiplayer` | optionally writes `.summer/multiplayer-architecture.md` |
+| `/multiplayer-*`, `/summer-*` | does NOT write here (writes `summer.build.json`, `world.json`, `network/`, `client/`, `authority/`) |
 | `/export-and-ship` | does NOT write here (writes export configs in `project.godot`) |
 
 ## Linter check (future)

package/library/skills/3d-lighting/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: 3d-lighting
-description: Use when setting up lighting in a Summer Engine 3D scene — adding lights, configuring WorldEnvironment, sky, or shadows. Covers DirectionalLight3D versus Omni versus Spot, shadow tuning, ambient and sky-driven lighting, and the current Summer rendering conventions. Trigger on "lighting", "shadows", "WorldEnvironment", "sun", "ambient", "sky", "light".
+description: "Set up 3D scene lighting — DirectionalLight3D vs Omni vs Spot, WorldEnvironment, sky, shadow tuning, ambient — per current Summer conventions."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: rendering-and-lighting

package/library/skills/README.md

@@ -0,0 +1,264 @@
+# Summer skills
+
+> 116 skills, grouped by their primary domain. **Generated** by `npm run generate:registry` from each skill's `resource.yaml`; `--check` fails when this file and the library disagree. Do not edit by hand.
+
+The folder is flat on purpose (`docs/design/DECISIONS.md`, D3): a skill usually belongs to several domains, so categories live in each skill's `facets.domains` and this index is rendered from them. The first domain listed is the primary one. `summer skills list --by-domain` prints the same grouping; `summer skills info <slug>` shows one skill.
+
+Status: **stable** unless marked; *preview* = not yet exercised in-engine by the Summer team; ~~deprecated~~ installs only by name. ★ = installed by `--recommended`.
+
+## Domains
+
+- [2d](#2d) (10)
+- [3d](#3d) (6)
+- [agent-workflow](#agent-workflow) (17)
+- [ai](#ai) (2)
+- [animation](#animation) (7)
+- [assets](#assets) (3)
+- [audio](#audio) (6)
+- [character-controller](#character-controller) (2)
+- [debug](#debug) (1)
+- [deployment](#deployment) (2)
+- [editor](#editor) (1)
+- [gameplay](#gameplay) (6)
+- [level-design](#level-design) (2)
+- [multiplayer](#multiplayer) (16)
+- [navigation](#navigation) (1)
+- [performance](#performance) (1)
+- [rendering](#rendering) (5)
+- [runtime](#runtime) (1)
+- [scenes](#scenes) (12)
+- [scripting](#scripting) (2)
+- [ui](#ui) (1)
+- [vfx](#vfx) (9)
+- [video](#video) (3)
+
+## 2d
+
+| skill | when to use | also |
+|---|---|---|
+| [character-portrait](./character-portrait/SKILL.md) ★ | Generate a single polished character bust for dialogue UI, character select, lore cards, or codex entries. One character, locked composition, VN-style. | assets |
+| [concept-art](./concept-art/SKILL.md) ★ | Explore art direction with 3-4 rough concept variants of a character, environment, or prop to pick a vibe before committing to a final asset. | assets |
+| [create-asset-sheet](./create-asset-sheet/SKILL.md) | Generate a pack of 2D game assets from one prompt — tile sheet, UI kit, character pack, or biome set — sliced, classified, and saved as one pack ArtAsset. | assets |
+| [instantiate-asset-pack](./instantiate-asset-pack/SKILL.md) | Import a whole create-asset-sheet pack into the scene: groups composites, sorts paint order, emits Sprite2D/Node2D/NinePatchRect ops to lay it out. | assets |
+| [pixel-art](./pixel-art/SKILL.md) ★ | Generate pixel-art assets — sprites, items, tiles, portraits — at a specific resolution with pixel-perfect grid, limited palette, retro feel. | assets |
+| [skybox-panorama](./skybox-panorama/SKILL.md) | Generate a 360-degree equirectangular sky panorama and wire it as a PanoramaSkyMaterial Sky resource on WorldEnvironment in a 3D scene. | assets |
+| [sprite-sheet](./sprite-sheet/SKILL.md) | Generate animated 2D character sprites laid out as a sprite sheet — walk cycle, attack, idle, death — wired into AnimatedSprite2D / SpriteFrames. | assets |
+| [tileable-texture](./tileable-texture/SKILL.md) | Generate a seamless tileable texture for walls, floors, or terrain — repeats cleanly on all four edges, wired as a StandardMaterial3D albedo. | assets |
+| [ui-graphics](./ui-graphics/SKILL.md) | Generate game-UI elements — icons, buttons, panels, frames, HUD widgets, badges — flat design, transparent background, wired via TextureRect/NinePatchRect. | assets |
+| [use-widget-asset](./use-widget-asset/SKILL.md) | Wire a widget slice from a create-asset-sheet pack (panel, button, slider, bar, toggle) into NinePatchRect, TextureProgressBar, or TextureRect via sliceMeta. | assets |
+
+## 3d
+
+| skill | when to use | also |
+|---|---|---|
+| [character-model](./character-model/SKILL.md) ★ | Generate a rigged humanoid — player, NPC, enemy, boss — via T-pose reference, user-gated preview, and Meshy auto-rig, wired as CharacterBody3D or Node3D. | assets |
+| [environment-kit](./environment-kit/SKILL.md) | Generate a modular environment kit — wall pieces, floor tiles, pillars, doors, arches, corners — snap-together meshes sharing one visual style. | assets |
+| [*fabricating-assets*](./fabricating-assets/SKILL.md) (preview) | Fabricate meshes with a bpy script in the user's own Blender (summer_fabricate_3d) — kits with exact dimensions, VFX meshes, post-processing generated models. | assets, scripting, agent-workflow |
+| [organic-model](./organic-model/SKILL.md) | Generate organic 3D shapes — trees, rocks, mushrooms, coral, plants, vines, crystals — where AI artifacts read as natural irregularity. | assets |
+| [prop-model](./prop-model/SKILL.md) ★ | Generate a single static 3D prop — sword, barrel, chest, lantern, throne, statue — one isolated object, no rigging, wired as a MeshInstance3D. | assets |
+| [vehicle-model](./vehicle-model/SKILL.md) | Generate a hard-surface vehicle — car, spaceship, mech, boat, tank — static mesh with optional detail-texture pass, wired as Vehicle3D or MeshInstance3D. | assets |
+
+## agent-workflow
+
+| skill | when to use | also |
+|---|---|---|
+| [brainstorming](./brainstorming/SKILL.md) ★ | Explore user intent, requirements, and design before implementation — must run before any creative work: features, components, mechanics, behavior. | game-design |
+| [debugging-game-feel](./debugging-game-feel/SKILL.md) | Debug features that work but feel wrong — floaty jumps, mushy combat, sluggish camera — subjective bugs living in tuning, timing, and feedback layers. | gameplay |
+| [diagnosing-perf-regressions](./diagnosing-perf-regressions/SKILL.md) | Find why frame rate, frame time, or load time got worse since a known-good state — regression hunting, not general performance tuning. | performance |
+| [dispatching-parallel-agents](./dispatching-parallel-agents/SKILL.md) | Work 2+ independent tasks in parallel when they share no state and have no sequential dependencies. | meta |
+| [gameskill](./gameskill/SKILL.md) | Capture what a game-dev session just learned as a reusable skill (project, user or Summer library) so the next session starts smarter. | meta |
+| [*godogen-visual-proof-game-generation*](./godogen-visual-proof-game-generation/SKILL.md) (preview) | Godogen-style game generation with a visual QC loop — capture frames from the running game, self-verify against the brief, bounded fix rounds, proof clip. | verification |
+| [headless-scripting](./headless-scripting/SKILL.md) ★ | Run a GDScript file against Summer Engine from the shell for operations no MCP tool exposes — navmesh baking, collision shapes, TileSets, re-imports. | headless |
+| [investigating-bugs](./investigating-bugs/SKILL.md) ★ | Systematic investigation of any bug, test failure, or unexpected behavior before proposing fixes. | debug |
+| [playtesting-a-feature](./playtesting-a-feature/SKILL.md) ★ | Before claiming a gameplay feature done: actually run the game and walk through the feature. Static diagnostics and type checks do not count. | verification |
+| [running-in-the-cloud](./running-in-the-cloud/SKILL.md) | Run Summer Engine on a Linux box with no display — install it, launch headless, know when xvfb + software GL are needed, authenticate without a browser. | project |
+| [skill-create](./skill-create/SKILL.md) | Bootstrap a new Summer library skill (library/skills/<slug>/ with resource.yaml and SKILL.md), frontmatter, and stub sections. | meta |
+| [skill-improve](./skill-improve/SKILL.md) | Upgrade an underperforming Summer skill — run it against a behavioral spec with and without changes via a parallel-eval harness; ship the winner. | meta |
+| [skill-test](./skill-test/SKILL.md) | Lint a Summer skill before commit, audit the whole library, or check a behavioral spec assertion — static structural rules plus behavioral specs. | meta |
+| [using-summer](./using-summer/SKILL.md) | Session bootstrap for Summer projects — establishes how to find and use Summer skills and the summer-engine MCP before any response. | meta |
+| [verification-before-completion](./verification-before-completion/SKILL.md) ★ | Run verification commands and confirm output before claiming work complete, fixed, or passing — evidence before assertions, always. | verification |
+| [writing-plans](./writing-plans/SKILL.md) | Turn a spec or requirements for a multi-step task into a written implementation plan before touching code. | meta |
+| [writing-skills](./writing-skills/SKILL.md) | Create, edit, and verify agent skills — format, structure, testing with subagents, and best practices. | meta |
+
+## ai
+
+| skill | when to use | also |
+|---|---|---|
+| [*ai-characters-in-games*](./ai-characters-in-games/SKILL.md) (preview) | Safe AI characters in published games: no keys in the build, replies via Summer's player AI gateway, moderation, spend caps, offline brain and a report button. | npc |
+| [design-npc](./design-npc/SKILL.md) ★ | Design enemy/NPC/boss/companion behavior — perception, personality, intent, action state machine, telegraphs — outputs a GDScript stub plus node tree. | npc |
+
+## animation
+
+| skill | when to use | also |
+|---|---|---|
+| [animation-tree](./animation-tree/SKILL.md) | Design and wire AnimationTree state machines and blend trees so clips respond to gameplay — locomotion blends, attack interrupts, hit reactions. | 3d |
+| [character-animation-wiring](./character-animation-wiring/SKILL.md) | Wire a rigged, animated character end to end — inspect real clips and bones, locomotion state machine, method-track events, poses, blend shapes, root motion. | 3d |
+| [facial-and-lipsync](./facial-and-lipsync/SKILL.md) | Make a character's mouth move with a voice-over — phoneme extraction from audio, viseme blendshape mapping, and emotional facial expressions. | 3d |
+| [generate-motion](./generate-motion/SKILL.md) ★ | Attach an animation clip to a rigged character from the curated Meshy motion library — idle, walk, run, attack — wired via AnimationPlayer. | 3d |
+| [procedural-animation](./procedural-animation/SKILL.md) | Runtime bone modification on top of clips — head look-at, foot IK, hand-grabs-prop, additive lean, recoil. Code-and-modifier patterns, not generation. | 3d |
+| [retarget](./retarget/SKILL.md) | Apply existing animation clips from one rigged character to a different rigged character — same library, multiple models, no regeneration. | 3d |
+| [*text-to-motion*](./text-to-motion/SKILL.md) (preview) | Custom 2-second animation clips from text prompts on any of the user's own rigged models — humanoids, animals, creatures, cartoon plants, props. | generate, 3d |
+
+## assets
+
+| skill | when to use | also |
+|---|---|---|
+| [asset-strategy](./asset-strategy/SKILL.md) ★ | Route any 'I need a [thing]' asset request to the right specialist skill — disambiguates 2D / 3D / audio / video / VFX / animation pipelines. | pipeline |
+| [*lumera-single-image-scene-reconstruction*](./lumera-single-image-scene-reconstruction/SKILL.md) (preview) | Lumera-style single image to editable 3D scene — VLM-parsed object boxes and parametric lights, per-object meshes, HDR probe, .tscn assembly, refinement loop. | pipeline, 3d, scenes |
+| [*skintokens-auto-rigging*](./skintokens-auto-rigging/SKILL.md) (preview) | Offline auto-rigging with skin-tokens.cpp (GGML SkinTokens/TokenRig port) — skeleton and skin weights from a static GLB mesh on CPU/Vulkan, into Godot 4. | pipeline, 3d, animation |
+
+## audio
+
+| skill | when to use | also |
+|---|---|---|
+| [adaptive-music](./adaptive-music/SKILL.md) | Wire music stems to game state — combat/explore/boss/tension crossfades on a shared bus, paired with a state machine and AudioBus structure. | gameplay |
+| [ambient-bed](./ambient-bed/SKILL.md) | Generate a long looping location ambience — forest, dungeon, city, spaceship, cave — a looping AudioStreamPlayer on the Ambient bus with a seamless loop. | assets |
+| [audio-direction](./audio-direction/SKILL.md) ★ | Define the game's sonic identity — music style, instruments, SFX vocabulary, dynamic music plan — output as an audio bible at .summer/audio-bible.md. | game-design |
+| [music-track](./music-track/SKILL.md) ★ | Generate a looped or cinematic music track — loops authored at >=30s with a marked loop point, cinematic tracks at >=60s linear. | assets |
+| [sound-effect](./sound-effect/SKILL.md) ★ | Generate short SFX one-shots — footsteps, weapon swings, UI clicks, hit impacts — wired as AudioStreamPlayer/2D/3D that auto-frees on finished. | assets |
+| [voice-line](./voice-line/SKILL.md) ★ | Generate TTS voice lines — NPC barks, narrator, dialogue — with voice-id sourcing, a character-to-voice decision tree, and multi-line dialogue support. | assets |
+
+## character-controller
+
+| skill | when to use | also |
+|---|---|---|
+| [*character-movement*](./character-movement/SKILL.md) (preview) | Player controllers for 2D and 3D, plus the canonical third-person controller for Summer humanoid packages: movement owns translation, clips follow state. | gameplay, 2d, 3d |
+| [fps-controller](./fps-controller/SKILL.md) ★ | Production-quality first-person controller — WASD, mouse look, jump, coyote time, jump buffering, air control, and external-velocity handling. | gameplay |
+
+## debug
+
+| skill | when to use | also |
+|---|---|---|
+| [debug](./debug/SKILL.md) ★ | Disciplined bug/crash/error loop for Summer projects — script errors, console, debugger, hypothesis, fix, verify — before making code or scene changes. | verification |
+
+## deployment
+
+| skill | when to use | also |
+|---|---|---|
+| [export-and-ship](./export-and-ship/SKILL.md) ★ | Assess and prepare a game export: inventory installed templates and targets, validate release assets and config, produce supported builds after approval. | project |
+| [remote-deploy](./remote-deploy/SKILL.md) ★ | Run or test the game on a real device — phone, tablet, another computer — via the Remote Deploy button, runnable export presets, and on-device debugging. | project |
+
+## editor
+
+| skill | when to use | also |
+|---|---|---|
+| [*driving-the-editor-ui*](./driving-the-editor-ui/SKILL.md) (preview) | Drive the editor UI by name: invoke actions, clear blocking dialogs, switch the main screen, read a dock — and route scene work to the scene tools instead. | agent-workflow, verification |
+
+## gameplay
+
+| skill | when to use | also |
+|---|---|---|
+| [auto-fire-targeting](./auto-fire-targeting/SKILL.md) | Design or fix auto-fire weapon targeting (survivors, top-down ARPG, tower defense) — the pending-damage pattern that prevents over-commit and overkill. | game-design |
+| [*celeste-momentum-platforming*](./celeste-momentum-platforming/SKILL.md) (preview) | Celeste-style 2D precision platformer movement — momentum running, coyote time, variable jumps, dash, wall jump/slide, climb stamina, pixel corner correction. | character-controller, game-design |
+| [*combat-basics*](./combat-basics/SKILL.md) (preview) | Damage in Summer Engine: hitbox and hurtbox Areas on opposing layers, a reusable Health component, damage signals, knockback, hit feedback, projectiles. | scripting, game-design |
+| [design-mechanic](./design-mechanic/SKILL.md) ★ | Design one game mechanic in detail — input, response, feedback, failure modes, depth, tunables — outputs a design doc, node-graph sketch, GDScript stub. | game-design |
+| [*in-game-purchases*](./in-game-purchases/SKILL.md) (preview) | Sell items for Sparks and let short players buy Sparks in game via the Summer purchase sheet: checkout, Sparks purchase, results, testing, store policy. | scripting, game-design |
+| [*web-and-touch-input*](./web-and-touch-input/SKILL.md) ★ (preview) | Input for the browser and phones: the first-click rule for sound and mouse capture, focus, and touch buttons or a virtual stick on the same actions. | ui |
+
+## level-design
+
+| skill | when to use | also |
+|---|---|---|
+| [design-level](./design-level/SKILL.md) ★ | Design a single level — layout, pacing, encounters, secrets, reward gating — outputs a level design doc and a node-tree skeleton for summer_create_scene. | game-design |
+| [scene-to-level](./scene-to-level/SKILL.md) | Go from a scene reference image or concept art to a playable scene — orchestrates concept, asset pack, terrain, composition, and scene assembly. | game-design |
+
+## multiplayer
+
+| skill | when to use | also |
+|---|---|---|
+| [multiplayer](./multiplayer/SKILL.md) ★ | Start here for Summer multiplayer: how the authority, clients, Worlds and Sessions fit, and which skill comes next. | project |
+| [multiplayer-movement](./multiplayer-movement/SKILL.md) | Client-side movement in Summer multiplayer: owners move instantly, others glide, the authority checks each pose. | character-controller, scripting |
+| [multiplayer-project](./multiplayer-project/SKILL.md) | Set up a Summer multiplayer project: both entry scenes, World and queue files, joining, and a first Local Play run. | project, scripting |
+| [*multiplayer-publish*](./multiplayer-publish/SKILL.md) (preview) | Ship a hosted Summer multiplayer game: the summer.games bundle, server preset, pre-upload checks, and a new Build. | deployment |
+| [multiplayer-state](./multiplayer-state/SKILL.md) | Authority-owned game state in Summer multiplayer: shared and private State groups, validated Commands, and Events. | game-design, scripting |
+| [multiplayer-testing](./multiplayer-testing/SKILL.md) | Test a Summer multiplayer game with Local Play: several players, a bad network, bots, and what a passing run shows. | playtest, verification |
+| [*summer-analytics*](./summer-analytics/SKILL.md) (preview) | Send game events to Summer analytics from the authority or client: fire-and-forget, never blocking gameplay. | scripting |
+| [*summer-friends*](./summer-friends/SKILL.md) (preview) | Summer friends in a game: a consented friends list, profile and chat screens, direct messages. Hosted only. | ui |
+| [*summer-leaderboards*](./summer-leaderboards/SKILL.md) (preview) | Leaderboards in a Summer game: queue ratings from matches, and Game rankings your authority scores. | ui |
+| [summer-match-results](./summer-match-results/SKILL.md) | End a Summer match: report each player's win, loss or draw, show results on clients, then close the World. | gameplay |
+| [*summer-matchmaking*](./summer-matchmaking/SKILL.md) (preview) | Get players into matches with Summer matchmaking: queues, teams, accept prompts, join progress and failures. | ux |
+| [*summer-parties*](./summer-parties/SKILL.md) (preview) | Let a Summer party play together: the leader presses Play, members follow into the same match. Hosted only. | ui |
+| [summer-player-data](./summer-player-data/SKILL.md) | Save a player's progress so it follows them to every match: authority load and commit, autosave, safe retries. | scripting |
+| [*summer-store*](./summer-store/SKILL.md) (preview) | Sell Summer items for Sparks in a multiplayer game: shop, checkout, owned items, authority entitlement checks. | gameplay |
+| [*summer-world-chat*](./summer-world-chat/SKILL.md) (preview) | Add match chat to a Summer game: one World channel shared by everyone in the match. Hosted only. | ui |
+| [*summer-world-saves*](./summer-world-saves/SKILL.md) (preview) | Keep a persistent Summer World between restarts: checkpoint saves, restore before join, the final save. | scripting |
+
+## navigation
+
+| skill | when to use | also |
+|---|---|---|
+| [navigate-summer](./navigate-summer/SKILL.md) ★ | When to open a Summer web page or editor surface FOR the user (billing, their games, the scene just built) versus acting through the API, using summer_open. | agent-workflow, meta |
+
+## performance
+
+| skill | when to use | also |
+|---|---|---|
+| [tune-performance](./tune-performance/SKILL.md) ★ | Profile a slow game via summer_get_diagnostics, identify rendering/physics/scripting hotspots, propose fixes with before/after metric expectations. | debug |
+
+## rendering
+
+| skill | when to use | also |
+|---|---|---|
+| [3d-lighting](./3d-lighting/SKILL.md) ★ | Set up 3D scene lighting — DirectionalLight3D vs Omni vs Spot, WorldEnvironment, sky, shadow tuning, ambient — per current Summer conventions. | lighting |
+| [art-direction](./art-direction/SKILL.md) ★ | Define the game's visual style — references, palette, mood, lighting plan, post-processing, do/don't list — output as an art bible at .summer/art-bible.md. | lighting |
+| [*psx-retro-rendering*](./psx-retro-rendering/SKILL.md) (preview) | Hardware-informed PlayStation 1 rendering in Godot 4 — low-res output, RGB5 and exact dither, affine textures, vertex snapping, blend modes, fog; limits named. | 3d |
+| [*realtime-wet-surfaces*](./realtime-wet-surfaces/SKILL.md) (preview) | Real-time wetness on existing Godot 4 materials without losing their values — value-copying wet shader, geometry-driven wet mask, instance-uniform wet amount. | vfx |
+| [*web-compatibility-look*](./web-compatibility-look/SKILL.md) ★ (preview) | Make a web or browser game look high-end in the Compatibility renderer (WebGL 2): what works, what to avoid, 2D and 3D recipes, web performance. | 2d, 3d |
+
+## runtime
+
+| skill | when to use | also |
+|---|---|---|
+| [*agent-playtesting*](./agent-playtesting/SKILL.md) ★ (preview) | Playtest by driving the LIVE game — deterministic launch, frame-stamped probes before/after each action, exact frame steps, scripted or recorded input. | playtest, verification, agent-workflow |
+
+## scenes
+
+| skill | when to use | also |
+|---|---|---|
+| [brainstorm-game](./brainstorm-game/SKILL.md) ★ | Turn a vague idea into a buildable plan — genre, scope, core loop, mechanics, art direction — written as a 1-page brief to .summer/GameSoul.md. | project |
+| [browse-templates](./browse-templates/SKILL.md) ★ | List available Summer Engine project templates, present the choices, and create a project from the chosen one via summer create. | project |
+| [*camera-rigs*](./camera-rigs/SKILL.md) (preview) | Camera rigs for 2D and 3D: Camera2D follow with limits, first-person head camera, SpringArm3D third-person, orthographic top-down, FOV guidance. | 3d, 2d |
+| [make-game](./make-game/SKILL.md) ★ | Orchestration spine for 'make me a game': brainstorm, plan, scaffold, mechanics, art, audio, polish, verify, ship — delegates to specialist skills. | project |
+| [new-project](./new-project/SKILL.md) ★ | Create a fresh blank Summer Engine project — asks one question (project name) and runs summer create empty. | project |
+| [play](./play/SKILL.md) ★ | Run the project in Summer Engine, wait briefly, then report what's happening — clean run, errors, or warnings. | project |
+| [scene-composition](./scene-composition/SKILL.md) ★ | Scene structure conventions — node hierarchy, when to extract sub-scenes, reusable prefab patterns, and instance-versus-add-node decisions. | project |
+| [*scene-hierarchy-design*](./scene-hierarchy-design/SKILL.md) (preview) | Structure Summer Engine scenes by access pattern — asset vs live hierarchies, wrapper nodes per operation, sub-scenes for reuse, path-agnostic logic. | project, agent-workflow |
+| [*scene-scripting*](./scene-scripting/SKILL.md) ★ (preview) | One GDScript in the live editor (summer_run_script) builds scenes, 2D levels, HUDs and gameplay wiring instead of CRUD chains; verify with diff + screenshot. | scripting, 2d, ui, agent-workflow |
+| [*spatial-placement*](./spatial-placement/SKILL.md) ★ (preview) | Place 3D objects and modular kit pieces from measured geometry — inspect, place, starcast, measure, correct; floor, wall, facade, pipe and alcove recipes. | 3d, world-building, level-design, verification |
+| [*verifying-scenes*](./verifying-scenes/SKILL.md) ★ (preview) | Prove scene work landed (snapshot, diff, screenshots, runtime reads), audit 3D scenes for holes and misplacement, review them with shot sheets and zooms. | verification, agent-workflow |
+| [*world-building-3d*](./world-building-3d/SKILL.md) ★ (preview) | Compose, ground, space, and validate 3D scenes with Summer's four bounded spatial tools — exact paths, one geometric decision at a time, verified. | 3d, world-building, level-design, verification |
+
+## scripting
+
+| skill | when to use | also |
+|---|---|---|
+| [gdscript-patterns](./gdscript-patterns/SKILL.md) ★ | GDScript conventions — type hints, signals, exports, onready, lifecycle methods, get_node vs $NodePath, naming. | conventions |
+| [*save-load*](./save-load/SKILL.md) (preview) | Persist game state in Summer Engine: user:// paths, JSON progress vs ConfigFile settings, a versioned save schema with migration, autosave hooks. | gameplay |
+
+## ui
+
+| skill | when to use | also |
+|---|---|---|
+| [ui-basics](./ui-basics/SKILL.md) ★ | Build Summer Engine UI — HUDs, menus, health bars, dialogue boxes, Control trees — anchors, containers, responsive layout, theme vs inline styling. | ux |
+
+## vfx
+
+| skill | when to use | also |
+|---|---|---|
+| [game-feel](./game-feel/SKILL.md) ★ | Add juice: hit-flash, trauma-based camera shake, and audio ducking wired so one hit fires all three — for games that feel flat or lack impact. | gameplay |
+| [vfx-dissolve](./vfx-dissolve/SKILL.md) | Dissolve effect — a mesh disintegrating with a glowing burning edge, driven by a noise-threshold ShaderMaterial overriding the target's material. | rendering |
+| [vfx-fire](./vfx-fire/SKILL.md) ★ | Fire effect — animated flames built with a particle shader, GPUParticles3D, and a noise-based color ramp — torches, campfires, candles. | rendering |
+| [vfx-hit-spark](./vfx-hit-spark/SKILL.md) | Hit-spark effect — a one-shot burst of additive billboard particles oriented to a surface normal, fired on impact. | rendering |
+| [vfx-lightning](./vfx-lightning/SKILL.md) | Lightning bolt effect — procedural jagged path drawn via ImmediateMesh, glow shader, sparks at endpoints, screen shake. | rendering |
+| [vfx-magic-glow](./vfx-magic-glow/SKILL.md) | Magic-glow effect — a pulsing OmniLight3D plus drifting additive motes plus optional emission shader on the source mesh. | rendering |
+| [vfx-muzzle-flash](./vfx-muzzle-flash/SKILL.md) ★ | Muzzle-flash effect — a one-shot ~80 ms burst at a gun barrel built with a particle one-shot or a flashing quad with a star-burst shader. | rendering |
+| [vfx-smoke](./vfx-smoke/SKILL.md) | Smoke effect — a slow-rising column or puff of soft particles built with a noise + density falloff shader on a quad mesh, GPUParticles3D. | rendering |
+| [vfx-water-ripple](./vfx-water-ripple/SKILL.md) | Water-ripple effect — animated normal-distortion ripples on a water plane (or as a Decal) triggered by impacts. | rendering |
+
+## video
+
+| skill | when to use | also |
+|---|---|---|
+| [animated-loop](./animated-loop/SKILL.md) | Generate a short seamlessly-looping video clip — splash background, animated logo backdrop, idle title-screen footage — wired as a looping VideoStreamPlayer. | assets |
+| [cinematic-cutscene](./cinematic-cutscene/SKILL.md) ★ | Generate a non-interactive cutscene — reference-locked look, a 5-10s image-to-video shot, optional TTS dialogue — wired as a fading VideoStreamPlayer. | assets |
+| [trailer-shot](./trailer-shot/SKILL.md) | Generate marketing or trailer footage — slow-mo combat, establishing shots, hero beats, splash screens, pitch-deck B-roll — max punch in 5-10 seconds. | assets |

package/library/skills/adaptive-music/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: adaptive-music
-description: Use when wiring music stems to game state — combat / explore / boss / tension crossfades on a shared bus. Pairs generated stems with a state machine and AudioBus structure. Trigger on "adaptive music", "dynamic music", "music changes when combat starts", "layered music", "vertical music", "wire stems".
+description: "Wire music stems to game state — combat/explore/boss/tension crossfades on a shared bus, paired with a state machine and AudioBus structure."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: audio

package/library/skills/agent-playtesting/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-playtesting
-description: Use when proving a gameplay feature, reproducing a bug, or comparing two variants by driving the LIVE running game yourself — deterministic launch (seed, fixed_fps, offscreen instances), frame-stamped probes before and after every action, exact frame stepping, scripted or recorded input. The doctrine behind summer_game_probe, summer_game_input, summer_game_control and the summer_runtime_* tools.
+description: "Playtest by driving the LIVE game — deterministic launch, frame-stamped probes before/after each action, exact frame steps, scripted or recorded input."
 ---
 
 # Agent Playtesting