summer-engine 3.3.0 → 3.4.1

package/integrations/factory/README.md

@@ -1,25 +1,29 @@
-# Factory (Droid) integration
+# Factory Droid integration
+
+`summer setup factory` (aliases: `droid`, `factory-droid`) writes:
+
+- MCP config: `~/.factory/mcp.json`; Windows `%USERPROFILE%/.factory/mcp.json` (user); `.factory/mcp.json` (project).
+  Shape: `mcpServers.summer-engine = { type: "stdio", command, args }`.
+- Skills: `~/.agents/skills` (user) or `.agents/skills` (project) as `<skill>/SKILL.md`.
+- After: Restart droid or run /mcp in the active session.
 
 Generated by `scripts/generate-registry` from `library/**/resource.yaml`:
 
 - `registry/generated/plugin.factory.json` -> `.factory-plugin/plugin.json`
-  (metadata manifest, now including the full skill list at
-  `./library/skills/<slug>/` — the pre-v3 manifest listed zero skills, which
-  was a bug fixed by generation; version stamped from `package.json`).
+  (metadata manifest with the full skill list at
+  `./library/skills/<slug>/`; version stamped from `package.json`).
 
-There is no `summer setup factory` target (`summer setup` rejects `factory`).
-Install through the plugin marketplace instead:
+The plugin marketplace is an alternative install:
 
 ```
 droid plugin marketplace add https://github.com/summerengine/summer
 droid plugin install summer@summer-engine --scope user
 ```
 
-Factory reads MCP servers from the plugin's root `.mcp.json` (generated) and
-skills ONLY from a root `skills/<name>/SKILL.md` directory; it has no `skills`
-manifest field, so the array in `plugin.factory.json` is inert and this package
-(skills under `library/skills/`) currently exposes no skills to Factory. Open
-gap; fix is a root `skills/` layout, not a setup target.
+A plugin install reads MCP servers from the root `.mcp.json` (generated) and
+skills only from a root `skills/<name>/SKILL.md` directory. Factory has no
+`skills` manifest field, so the array in `plugin.factory.json` is inert and the
+plugin install exposes no skills. Use `summer setup factory` to get the skills.
 
 Never edit the destination file by hand — edit `library/` resources or
 `scripts/generate-registry/manifests.ts`, then run

package/integrations/mistral-vibe/README.md

@@ -5,7 +5,7 @@ is intentionally empty. Support is delivered at install time by
 `summer setup mistral-vibe` (aliases: `vibe`, `mistral`), which writes:
 
 - MCP config: `~/.vibe/config.toml`; Windows `%USERPROFILE%/.vibe/config.toml` (user); `.vibe/config.toml` (project).
-  Shape: undefined.
+  Shape: a `[[mcp_servers]]` entry with `name`, `transport`, `command`, `args` (TOML).
 - Skills: `~/.vibe/skills` (user) or `.agents/skills` (project) as `<skill>/SKILL.md`.
 - After: Restart Vibe so it reloads config.toml.
 

package/integrations/opencode/README.md

@@ -6,7 +6,7 @@ is intentionally empty. Support is delivered at install time by
 
 - MCP config: `~/.config/opencode/opencode.json`; Windows `%APPDATA%/opencode/opencode.json` (user); `opencode.json` (project).
   Shape: `mcp.summer-engine = { type: "local", command: [npx, ...], enabled: true }`.
-- Skills: `~/.agents/skills` (user) or `.agents/skills` (project) as `<skill>/SKILL.md`. OpenCode loads skills from this folder on the next session. Summer 3.0 wrote markdown under agents/summer and 3.1.0 wrote opencode/skills; `--force` removes both.
+- Skills: `~/.agents/skills` (user) or `.agents/skills` (project) as `<skill>/SKILL.md`. OpenCode loads skills from this folder on the next session. `--force` also removes skill copies that older Summer versions wrote under `opencode/agents/summer` and `opencode/skills`.
 - After: Restart OpenCode so it reloads opencode.json.
 
 Source of truth: `src/installer/agent-table.ts` (one row per agent).

package/integrations/roo-code/README.md

@@ -1,6 +1,6 @@
 # Roo Code integration
 
-> **Legacy.** Roo Code shut down on 2026-05-15. The extension may still run, but it is no longer maintained; consider Cline or Kilo Code.
+> **Legacy.** Roo Code is no longer maintained. The target still works; consider Cline or Kilo Code.
 
 No manifest file is generated in this repo for Roo Code — `manifest-target.json`
 is intentionally empty. Support is delivered at install time by

package/integrations/rovo-dev/README.md

@@ -5,7 +5,7 @@ is intentionally empty. Support is delivered at install time by
 `summer setup rovo-dev` (aliases: `rovodev`, `rovo`, `atlassian-rovo-dev`), which writes:
 
 - MCP config: `~/.rovodev/mcp.json`; Windows `%USERPROFILE%/.rovodev/mcp.json` (user); user scope only (project requests fall back with a warning).
-  Shape: undefined.
+  Shape: `mcpServers.summer-engine = { command, args, transport: "stdio" }`.
 - Skills: `~/.agents/skills` (user) or `.agents/skills` (project) as `<skill>/SKILL.md`.
 - After: Restart Rovo Dev CLI so it reconnects its MCP servers.
 

package/integrations/trae/README.md

@@ -4,7 +4,7 @@ No manifest file is generated in this repo for Trae — `manifest-target.json`
 is intentionally empty. Support is delivered at install time by
 `summer setup trae` (aliases: `trae-ide`, `bytedance-trae`), which writes:
 
-- MCP config: `.trae/mcp.json` (user); `.trae/mcp.json` (project).
+- MCP config: `.trae/mcp.json` (project only; Trae manages user-level servers in its UI, so a user-scope request writes the project file with a warning).
   Shape: `mcpServers.summer-engine = { command, args }`.
 - Skills: none. Trae documents no skills folder; the MCP server ships summer_get_agent_playbook for in-chat guidance.
 - After: Restart Trae and open the MCP settings; summer-engine should show as connected.

package/integrations/windsurf/README.md

@@ -1,12 +1,12 @@
-# Devin Desktop (formerly Windsurf) integration
+# Devin Desktop integration
 
-No manifest file is generated in this repo for Devin Desktop (formerly Windsurf) — `manifest-target.json`
+No manifest file is generated in this repo for Devin Desktop — `manifest-target.json`
 is intentionally empty. Support is delivered at install time by
 `summer setup windsurf` (aliases: `devin`, `devin-desktop`, `devindesktop`), which writes:
 
 - 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.
+- After: Restart Devin Desktop 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-table.ts` (one row per agent).

package/library/references/collaborative-protocol/collaborative-protocol.md

@@ -1,6 +1,6 @@
 # Collaborative Protocol — "May I write?"
 
-> Every Summer skill must follow this. The agent works *with* the user, not around them.
+> Every Summer skill follows this rule.
 
 ## The rule
 
@@ -13,7 +13,7 @@ This applies to:
 - Setting up project-wide settings (`project.godot`)
 - Installing tools, libraries, or templates
 
-Reading is unconditional. Inspection, scene-tree walks, diagnostics — never need permission.
+Reading needs no permission: inspection, scene-tree walks and diagnostics run without asking.
 
 ## Phrasing
 
@@ -42,9 +42,9 @@ Plain, short, action-first. Examples:
 
 ## Linter check
 
-The `workflow/skill-test/SKILL.md` static linter looks for the phrases:
-- "May I" / "May I write" / "May I create" / "May I attach"
+The `skill-test` skill's static check looks for one of these phrases:
+- "May I"
 - "I'm about to"
 - "Continue?" / "OK?" / "Proceed?"
 
-A skill that mutates files but never says any of these fails the linter.
+A skill that triggers user-visible writes but never says any of these fails the check. Read-only skills are exempt.

package/library/references/gd-style/gd-style.md

@@ -1,6 +1,6 @@
 # GDScript Style — Summer Conventions
 
-> The bar for GDScript in Summer. Skills should produce code that matches this. Where Godot's official style guide is silent, this is the tiebreaker.
+> Skills produce GDScript that matches this. Where the upstream GDScript style guide is silent, this file decides.
 
 ## File structure
 
@@ -43,7 +43,7 @@ func _physics_process(delta: float) -> void:
 func _input(event: InputEvent) -> void:
     pass
 
-# 7. Public API (PascalCase or snake_case methods, snake_case for funcs)
+# 7. Public API (snake_case)
 func take_damage(amount: int) -> void:
     pass
 
@@ -115,7 +115,5 @@ tween.tween_property(self, "modulate", Color.WHITE, 0.3)
 
 ## See also
 
-- [Official Godot GDScript style guide](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_styleguide.html)
-- `scripting-patterns/gdscript-patterns/SKILL.md` — patterns and idioms
-- `scripting-patterns/signal-patterns/SKILL.md` — signal usage
-- `scripting-patterns/state-machine-patterns/SKILL.md` — state machine patterns
+- [Upstream GDScript style guide](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_styleguide.html)
+- The `gdscript-patterns` skill: patterns and idioms, including signals

package/library/references/godot-version/godot-version.md

@@ -18,8 +18,8 @@ running engine also reports its measured technical version:
 <engineBinaryPath> --version      # e.g. 4.6.1.stable.mono.custom_build.<hash>
 ```
 
-Get `engineBinaryPath` from `summer_get_project_context`. Prefer live
-inspection to a copied version string. Creator onboarding and headlines should
+Get `engineBinaryPath` from `summer_get_project_context`. Prefer the live
+version to a copied version string. Creator onboarding and headlines should
 say Summer Engine, Summer game, Summer SDK, and GDScript. Use the upstream name
 only where technical compatibility, migration, extension APIs, contribution
 routing, attribution, or licensing requires it.
@@ -40,7 +40,7 @@ routing, attribution, or licensing requires it.
 ## Summer-specific deltas from the upstream engine
 
 - Local API server runs on `localhost:6550` by default (the port increments when several editors are open; each live editor publishes its port in `~/.summer/instances/<id>.json`, and the shared token lives in `~/.summer/api-token`).
-- Engine ships a webview module in `modules/1summer_engine/`. Do not assume the
+- The editor carries Summer's own modules (including a webview). Do not assume the
   unmodified upstream editor for UI patches.
 - Project root contains `.summer/` for project memory; do not delete it.
 

package/library/references/headless-routing/headless-routing.md

@@ -15,12 +15,12 @@ Only file, import, scene-read, and game run/stop/logs/screenshot operations work
 ## Ships dark
 
 - Enabled by `SUMMER_HEADLESS_ROUTING=1`. Unset, the module is not loaded at all and nothing changes.
-- Requires an engine build that ships the worker mode and process registry (Summer 4.7.x line). On older builds, leave the flag off.
+- Requires an engine build that ships the worker mode and process registry. On builds without it, leave the flag off.
 - With the flag on and an editor open, the editor path is used unchanged — caching, credential-drift reconnects, and identity binding all behave as before.
 
 ## What an agent should expect
 
-- Errors from this layer are prefixed `[headless:<stage>]` where stage is one of `connect`, `auth`, `op`, `spawn`, so you can tell "could not reach the worker" from "the worker went quiet mid-import".
+- Errors from this layer are prefixed `[headless:<stage>]` where stage is one of `connect`, `auth`, `op`, `spawn`, so "could not reach the worker" and "the worker went quiet mid-import" read differently.
 - A first call with no editor and no worker can take up to two minutes while the worker starts and imports the project. Later calls are fast.
 - **No blind retries.** If a mutating operation (write, import, run, stop) times out or the worker connection drops, the outcome is reported as UNKNOWN and the connection is quarantined. Inspect the target (read the file, check the scene) before retrying. There is deliberately no automatic reconnect or replay.
 - Worker error strings start with a snake_case classifier (`sha256_mismatch`, `already_exists`, `needs_display`). `needs_display` on a screenshot means the machine has no display; open the project in the editor for screenshots.

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

@@ -4,10 +4,10 @@ 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.
+1. **Understand** the request and outline a short plan.
 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.
+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. Do not wait for the user to find the first error.
 
 ## When to use Summer MCP (the live engine)
 

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

@@ -1,14 +1,14 @@
 # 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.
+> Which Summer MCP tool to call. Skills 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:
+**Use Summer MCP for** anything that needs the live editor or the engine'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)
+- Asset import (the 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)
@@ -17,7 +17,7 @@
 
 **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 (104 tools)
+## Tool surface (105 tools)
 
 ### Project files (4)
 
@@ -28,7 +28,7 @@
 | `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)
+### Scene graph (12)
 
 | Tool | Use |
 |---|---|
@@ -49,7 +49,7 @@
 
 | Tool | Use |
 |---|---|
-| `summer_set_prop` | Set a typed property in an explicit `scenePath` using Godot's `str_to_var()`. |
+| `summer_set_prop` | Set a typed property in an explicit `scenePath` using `str_to_var()`. |
 | `summer_set_resource_property` | Set a nested resource property in an explicit `scenePath`. |
 | `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`. |
@@ -65,7 +65,7 @@
 
 | Tool | Use |
 |---|---|
-| `summer_import_from_url` | Download a `.glb`/`.png`/etc and run Godot's full import pipeline. |
+| `summer_import_from_url` | Download a `.glb`/`.png`/etc and run the engine's full import pipeline. |
 | `summer_import_from_url_batch` | Same, batched (single filesystem scan). |
 
 ### Scene scripting (3)
@@ -84,7 +84,7 @@
 
 ### 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.
+Preview: needs Summer Engine 0.5.66 or newer; older engines return `engine_lacks_op`. 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 |
 |---|---|
@@ -190,7 +190,7 @@ Preview. One fast, read-only call that walks every node of a 3D scene and lists
 
 | Tool | Use |
 |---|---|
-| `summer_create_debug_report` | Create a support-ready Markdown report for `/summer debug`. |
+| `summer_create_debug_report` | Create a support-ready Markdown report (same as `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. |
@@ -206,9 +206,9 @@ Preview. One fast, read-only call that walks every node of a 3D scene and lists
 | `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` | Search, choose the top match, download, run the engine 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_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. |
 | `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)
@@ -228,7 +228,7 @@ Preview. One fast, read-only call that walks every node of a 3D scene and lists
 | `summer_check_job` | Poll a generation job. |
 | `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)
+### Meta (5)
 
 | Tool | Use |
 |---|---|
@@ -236,8 +236,9 @@ Preview. One fast, read-only call that walks every node of a 3D scene and lists
 | `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. 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. |
+| `summer_get_board` | Read the person's approved planning board (look, characters, place, storyboard, picks), with the look and picked cards as images to compare screenshots against. Needs the project id from the build brief; works without the engine. |
 
-### Creator platform (5)
+### Creator platform (7)
 
 | Tool | Use |
 |---|---|
@@ -245,8 +246,9 @@ Preview. One fast, read-only call that walks every node of a 3D scene and lists
 | `summer_export_templates` | `list` or `install` export templates from Summer's CDN (`downloads.summer.games/engine-templates/<summerVersion>/manifest.json`) into the engine's user template folder (`<data>/Godot/export_templates/<FULL_CONFIG>/`), sha256-checked. Only download exports need them; store bundles need none. `summerVersion` is read on macOS, passed elsewhere. |
 | `summer_publish_build` | Upload that `.zip` to the creator's game through Studio's store upload: confirm-gated preview first, then declare, part upload from disk, seal, wait for the Build, name its client pack; `publish:true` also approves it. Needs `summer login --store`; a retry with the same file and version continues the same upload. |
 | `summer_creator_publish` | **Deprecated** (use the two tools above). 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_releases` | **Deprecated.** Lists releases on the legacy creator API. For summer.games use `summer_store_releases` (hosted, mounted after `summer login --store`). |
 | `summer_creator_config` | Read or confirm updates to the shared non-secret `~/.summer/config.json`. It never accepts or returns tokens. |
+| `summer_capture_gameplay` | Real gameplay frames without a running editor: starts the game (main scene or `scene`) in the engine's offscreen verify instance (`--summer-verify`, real renderer, window parked offscreen, no focus) at `resolution` (default `1920x1080`), waits `waitSeconds`, saves `frames` PNGs (HUD included) to `<project>/.summer/captures/<time>/`. Imports the project first when `.godot/` is missing. Returns each path with its real width and height; warns when the stretch settings render another size. For store screenshots. |
 
 ### Library search (2)
 
@@ -287,7 +289,7 @@ Every asset-generation skill should follow this loop:
 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.
+5. `summer_import_asset_by_id` — import the exact result through the engine's import pipeline.
 6. `summer_get_asset_download_url` — only when the user explicitly wants a downloadable file/link.
 
 ## summer_set_resource_property — nested properties
@@ -304,7 +306,7 @@ summer_set_resource_property(
 
 `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.
+**Inline `sub_resource` targets work.** You do not need to save the resource as a standalone `.tres` first: the op reads the node's property and sets the sub-property on whatever resource it holds. The canonical example in the shipped `summer_batch` description does exactly this against an inline mesh.
 
 Structural failures are explicit:
 

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

@@ -7,7 +7,7 @@
 ## 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.
+- **Editor rows** are ids of Summer Engine's one navigation table (the `Navigate` op). 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
 

package/library/references/public-surface-language/public-surface-language.md

@@ -13,7 +13,7 @@ Godot Engine remains relevant in narrow technical and legal contexts:
 - upstream contributions, attribution, copyright, and licenses.
 
 The current technical base is 4.6.1 and the approved next target is 4.7.1. The
-source of truth is the repository compatibility contract. Neither number is a
+source of truth is `src/core/summer-compatibility.ts`. Neither number is a
 permanent Summer identity, so creator prompts and skills should not pin
 themselves to one upstream release.
 

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

@@ -1,6 +1,6 @@
 # `.summer/` Folder Convention
 
-> The canonical layout for project-scoped Summer state. Read this if you're authoring a skill that writes durable design output, locked project memory, or agent-readable design notes.
+> The layout of project-scoped Summer state. Read this before writing a skill that writes design output, locked project memory, or agent-readable notes.
 
 ## Files at the root of `.summer/`
 

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

@@ -11,7 +11,7 @@ paths: ["**/*.tscn", "**/*.tres"]
 
 # 3D Lighting for Summer Engine
 
-Set up lighting and environment for 3D scenes. Follow these patterns for outdoor and indoor setups.
+Outdoor and indoor lighting setups for 3D scenes.
 
 ## Light Types
 
@@ -59,9 +59,9 @@ For a simple procedural sky:
 summer_set_resource_property(nodePath="./World/WorldEnvironment", resourceProperty="environment", subProperty="background_mode", value="2")
 ```
 
-You may need to create a Sky resource and assign it. In the editor this is done via the inspector; via MCP, SetResourceProperty on nested resources may require the resource to exist first. If `environment` is "Environment", the engine creates a default. For `sky`, you might set `sky` to "ProceduralSkyMaterial" or similar—check Godot docs for the exact property chain.
+A sky is a `Sky` resource in `environment.sky`, with a `ProceduralSkyMaterial` (or `PhysicalSkyMaterial`) in its `sky_material`. `summer_set_resource_property` only sets properties on a resource that already exists, so create the `Sky` and its material in one `summer_run_script` call.
 
-**Simpler path:** Use the 3d-basic template which already has a sky. Copy that structure.
+**Simpler path:** start from the `3d-basic` template, which already has a sky, and copy its structure.
 
 ### 3. Fill Light (Optional)
 
@@ -128,7 +128,7 @@ set the meshes' `gi_mode`, then run the bake yourself from `summer_run_script`
 enum (0 is OK; `BAKE_ERROR_NO_LIGHTMAPPER` means no renderer in this process, not a
 missing binding). Verify with a `framing:"camera"` screenshot, which renders the
 real environment. Only fall back to "press Bake Lightmaps in the editor" when
-there is genuinely no renderer available. If they want GI with zero bake step,
+no renderer is available. If they want GI with zero bake step,
 steer to `SDFGI` (`Environment.sdfgi_enabled`) or `VoxelGI`.
 
 Note the related trap: `Engine.has_singleton("EditorInterface")` returns **true**

package/library/skills/README.md

@@ -1,6 +1,6 @@
 # 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.
+> 118 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.
 
@@ -10,7 +10,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 
 - [2d](#2d) (10)
 - [3d](#3d) (6)
-- [agent-workflow](#agent-workflow) (17)
+- [agent-workflow](#agent-workflow) (18)
 - [ai](#ai) (2)
 - [animation](#animation) (7)
 - [assets](#assets) (3)
@@ -24,7 +24,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 - [multiplayer](#multiplayer) (16)
 - [navigation](#navigation) (1)
 - [performance](#performance) (1)
-- [rendering](#rendering) (5)
+- [rendering](#rendering) (6)
 - [runtime](#runtime) (1)
 - [scenes](#scenes) (12)
 - [scripting](#scripting) (2)
@@ -56,12 +56,13 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 | [*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 |
+| [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 VehicleBody3D or MeshInstance3D. | assets |
 
 ## agent-workflow
 
 | skill | when to use | also |
 |---|---|---|
+| [*bounded-engine-runs*](./bounded-engine-runs/SKILL.md) ★ (preview) | Run Summer headless or offscreen safely from an agent: time limits, one engine per project, muted runs, import passes, tests that fail on crashes. | headless, verification |
 | [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 |
@@ -105,7 +106,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 |---|---|---|
 | [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 |
+| [*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 Summer Engine. | pipeline, 3d, animation |
 
 ## audio
 
@@ -152,7 +153,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 | [*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 |
+| [*in-game-purchases*](./in-game-purchases/SKILL.md) (preview) | Sell items for Sparks in a game shop via the Summer purchase sheet: checkout, results, not enough Sparks, inventory unlocks, authority grants, 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
@@ -193,7 +194,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 
 | 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 |
+| [tune-performance](./tune-performance/SKILL.md) ★ | Profile a slow game with a measurement probe, identify rendering/physics/scripting hotspots, propose fixes with before/after metric expectations. | debug |
 
 ## rendering
 
@@ -201,8 +202,9 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 |---|---|---|
 | [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 |
+| [*compatibility-renderer-traps*](./compatibility-renderer-traps/SKILL.md) ★ (preview) | Make a Forward+ Summer game also look right on the Compatibility renderer: instance-uniform budget, black MultiMesh colors, sRGB vertex colors. | performance |
+| [*psx-retro-rendering*](./psx-retro-rendering/SKILL.md) (preview) | PlayStation 1 rendering in Summer Engine — 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 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

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

@@ -13,7 +13,7 @@ paths: ["audio/music/**", "scripts/audio/**", "**/*.tscn", "default_bus_layout.t
 
 ## Overview
 
-This is the **wiring** skill, not the generation skill. The job is to take 3–5 music stems (or full tracks) and connect them to a game state machine so the music shifts as the player's situation changes — exploration → tension → combat → victory → exploration — with crossfades, ducking, and bus routing the player never consciously notices but always feels.
+This skill wires music; it does not generate it. It connects 3–5 music stems (or full tracks) to a game state machine so the music follows the player's situation — exploration → tension → combat → victory → exploration — with crossfades, ducking, and bus routing.
 
 This skill assumes the stems already exist. If they don't, run `/music-track` first for each state, or generate matching stems (same tempo, same key, same bar count) so they layer/crossfade cleanly.
 
@@ -51,7 +51,7 @@ If the plan is absent, run `/audio-direction` step 6 first.
 | **Vertical re-orchestration** | Same melody, different orchestration per state, snap on bar | All variants play simultaneously muted; swap on next bar boundary |
 | **Procedural / generative** | Rules generate music in real-time | Beyond this skill; needs a custom system |
 
-For 90% of indie games, **horizontal sequencing** is correct. It's cheaper to author, easier to swap, and players don't notice the difference.
+For most games, **horizontal sequencing** is right. It is cheaper to author and easier to swap.
 
 ### 3. Confirm stems exist (or generate them)
 
@@ -67,7 +67,7 @@ You need (typical case):
 - (optional) `audio/music/boss.mp3` — distinct from combat
 - (optional) `audio/music/victory.mp3` — short linear sting (4–8s)
 
-If any are missing, run `/music-track` for each. Critically: **same BPM, same key, same time signature, same bar length** so they overlap cleanly.
+If any are missing, run `/music-track` for each. Use **the same BPM, key, time signature, and bar length** for all of them so they overlap cleanly.
 
 ### 4. Verify / extend the bus layout
 
@@ -294,7 +294,7 @@ Master
 ## Anti-patterns
 
 - **Stems generated at different BPM/key.** They will not crossfade cleanly. Same BPM, same key, same bar count.
-- **Restarting tracks on state change.** Players hear the restart and the magic dies. Always crossfade volumes; never `play()` mid-state.
+- **Restarting tracks on state change.** Players hear the restart. Always crossfade volumes; never `play()` mid-state.
 - **No autoplay on the silent stems.** They can't fade in to phase if they never started.
 - **Polling state in `_process`.** Use signals. Music director listens to `EventBus`, not to game state every frame.
 - **Hardcoding volumes in `set_state`.** Use the table-driven `_apply_state` so adding a new state doesn't fork the function.
@@ -323,8 +323,8 @@ in Summer Engine.
 
 ## See also
 
-- `audio/audio-direction` — defines the dynamic music plan and bus layout
-- `audio/music-track` — generates the stems
-- `audio/voice-line` — the voice bus that triggers ducking
+- `audio-direction` — defines the dynamic music plan and bus layout
+- `music-track` — generates the stems
+- `voice-line` — the voice bus that triggers ducking
 - `../../references/godot-version/godot-version.md` — Summer compatibility for AudioServer
   and Tween APIs

package/library/skills/ai-characters-in-games/SKILL.md

@@ -48,7 +48,7 @@ Not for scripted dialogue trees (design-npc) or for enemy behaviour.
 
 ## Top up and set limits
 
-AI characters are paid from the Summer credits of the developer who turned them on: usage is billed from your Summer credits. Cost depends on the models and voices you choose. Your dashboard shows spend as it happens, and your limits cap it. Players never pay. There is nothing to configure in the game project.
+AI characters are paid from the Summer credits of the developer who turned them on. Cost depends on the models and voices you choose. Your dashboard shows spend as it happens, and your limits cap it. Players never pay. There is nothing to configure in the game project.
 
 1. In Summer Studio, open the game and its **AI characters** section.
 2. Add a persona per character: name, a plain-words description, an optional voice, reply length, a safe line in character, and the model (from the models the game allows, each marked fast or smart).