summer-engine 2.8.2 → 3.0.0

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

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

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

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

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

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

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

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

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

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

package/{references → library/references/summer-folder}/summer-folder.md

@@ -4,16 +4,17 @@
 
 ## Files at the root of `.summer/`
 
-- `GameSoul.md` — the project brief. Created by `/summer:brainstorm-game`. Contains: name, one-sentence pitch, core loop, 3 mechanics max, art direction summary, scope. Updated whenever the game's high-level direction changes.
-- `art-bible.md` — visual style reference. Created by `/summer:art-direction`. Contains: palette (6–15 hex codes), mood adjectives, lighting plan, post-processing notes, do/don't list, references.
-- `audio-bible.md` — sonic identity. Created by `/summer:audio-direction`. Contains: music style + tempo range, SFX vocabulary (8 classes), dynamic music FSM, bus layout reference.
-- `build-plan.md` — implementation plan derived from `GameSoul.md`. Created by `/summer:make-game` before scaffold/build work.
+- `GameSoul.md` — the project brief. Created by `/brainstorm-game`. Contains: name, one-sentence pitch, core loop, 3 mechanics max, art direction summary, scope. Updated whenever the game's high-level direction changes.
+- `art-bible.md` — visual style reference. Created by `/art-direction`. Contains: palette (6–15 hex codes), mood adjectives, lighting plan, post-processing notes, do/don't list, references.
+- `audio-bible.md` — sonic identity. Created by `/audio-direction`. Contains: music style + tempo range, SFX vocabulary (8 classes), dynamic music FSM, bus layout reference.
+- `build-plan.md` — implementation plan derived from `GameSoul.md`. Created by `/make-game` before scaffold/build work.
+- `project.json` — written by `summer create`, not by skills: the template pin (`id`, `version`, and `repo` + `commit` + `tree_digest` or `builtin: true`), `toolkit_version`, `created_at`. Read it to learn which template started the project; never edit it by hand.
 
 ## Subdirectories
 
-- `mechanics/<mechanic-name>.md` — one file per designed mechanic (e.g., `double-jump.md`, `parry.md`). Created by `/summer:design-mechanic`. Contains: input → response → feedback → failure modes → tunable parameters.
-- `levels/<level-name>.md` — one file per designed level. Created by `/summer:design-level`. Contains: teaching goal, pacing curve (5 beats), encounters, secrets, reward gating.
-- `npcs/<npc-name>.md` — one file per designed NPC. Created by `/summer:design-npc`. Contains: archetype, perception model, decision tree, escalation, defeat sequence.
+- `mechanics/<mechanic-name>.md` — one file per designed mechanic (e.g., `double-jump.md`, `parry.md`). Created by `/design-mechanic`. Contains: input → response → feedback → failure modes → tunable parameters.
+- `levels/<level-name>.md` — one file per designed level. Created by `/design-level`. Contains: teaching goal, pacing curve (5 beats), encounters, secrets, reward gating.
+- `npcs/<npc-name>.md` — one file per designed NPC. Created by `/design-npc`. Contains: archetype, perception model, decision tree, escalation, defeat sequence.
 - `memory/` — structured project memory for durable facts that must survive future sessions. Use this for locked cast decisions, character facts, provider IDs, world canon, and conflict notes.
 - `skills/` — installed project-scoped Summer skills. Do not put game design memory here.
 
@@ -71,20 +72,20 @@ Then write the fact in normal Markdown so users can inspect and edit it:
 
 | Skill | Writes |
 |---|---|
-| `/summer:brainstorm-game` | `.summer/GameSoul.md` |
-| `/summer:art-direction` | `.summer/art-bible.md` |
-| `/summer:audio-direction` | `.summer/audio-bible.md` |
-| `/summer:design-mechanic` | `.summer/mechanics/<name>.md` |
-| `/summer:design-level` | `.summer/levels/<name>.md` |
-| `/summer:design-npc` | `.summer/npcs/<name>.md` |
-| `/summer:voice-line` | `.summer/memory/casting/voices.md` |
-| `/summer:debug` | does NOT write here |
-| `/summer:play` | does NOT write here |
-| `/summer:vfx` | does NOT write here (VFX edits scenes/scripts) |
-| `/summer:tune-performance` | optionally writes `.summer/perf-notes.md` if user requests |
-| `/summer:setup-multiplayer` | optionally writes `.summer/multiplayer-architecture.md` |
-| `/summer:export-and-ship` | does NOT write here (writes export configs in `project.godot`) |
+| `/brainstorm-game` | `.summer/GameSoul.md` |
+| `/art-direction` | `.summer/art-bible.md` |
+| `/audio-direction` | `.summer/audio-bible.md` |
+| `/design-mechanic` | `.summer/mechanics/<name>.md` |
+| `/design-level` | `.summer/levels/<name>.md` |
+| `/design-npc` | `.summer/npcs/<name>.md` |
+| `/voice-line` | `.summer/memory/casting/voices.md` |
+| `/debug` | does NOT write here |
+| `/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` |
+| `/export-and-ship` | does NOT write here (writes export configs in `project.godot`) |
 
 ## Linter check (future)
 
-Once `workflow/skill-test` gains an executable mode, it should validate that any skill writing to `.summer/` is documented in the table above.
+Once the `skill-test` skill gains an executable mode, it should validate that any skill writing to `.summer/` is documented in the table above.

package/{skills/rendering-and-lighting → library/skills}/3d-lighting/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: rendering-and-lighting
 user-invocable: false
-allowed-tools: Read Grep summer_add_node summer_set_prop summer_set_resource_property summer_save_scene
+allowed-tools: Read Grep summer_add_node summer_set_prop summer_set_resource_property summer_save_scene summer_run_script summer_screenshot
 paths: ["**/*.tscn", "**/*.tres"]
 ---
 
@@ -109,8 +109,9 @@ Always use `Color(r, g, b, a)` with values 0.0–1.0:
 
 ## Baked lighting — what you can and cannot do from here
 
-Real-time lighting (everything above) is fully scriptable. Baking is not, and the
-split is worth stating before you promise a user a bake.
+Real-time lighting (everything above) is fully scriptable. Baking mostly is too on
+this build — the split that matters is *which process* runs the bake, not whether a
+script can trigger it.
 
 | Approach | Callable from MCP / a script? |
 |---|---|
@@ -118,14 +119,17 @@ split is worth stating before you promise a user a bake.
 | `WorldEnvironment` + `Environment` (sky, ambient, tonemap, glow, SSAO, SSR) | Yes |
 | `SDFGI` real-time GI | Yes — `Environment.sdfgi_enabled = true`, no bake step at all |
 | `VoxelGI` | Yes — `VoxelGI.bake()` **is** bound to script (`ClassDB.class_has_method("VoxelGI", "bake")` is true) |
-| **`LightmapGI` bake** | **No.** `LightmapGI` exposes only its `set_*` / `get_*` configuration methods — there is no `bake` in its method list on this build. It runs from the editor's Bake Lightmaps button only. |
-| **`OccluderInstance3D` occlusion bake** | **No.** `bake_single_node` is not script-callable either. Editor-only. |
-
-So when the user asks for baked lighting: add and configure the `LightmapGI`
-node and set the meshes' `gi_mode`, then tell them plainly that the bake itself
-is a button they press in the editor and that you cannot trigger it. Do not claim
-a bake happened. If they want GI without a manual step, steer to `SDFGI`
-(`Environment.sdfgi_enabled`, no bake) or `VoxelGI` (whose `bake()` you can call).
+| **`LightmapGI` bake** | **Yes, from the live editor.** Summer binds `LightmapGI.bake(from_node, image_data_path)` to script (upstream leaves it button-only). Call it from `summer_run_script`. The GPU lightmapper needs a real renderer (a RenderingDevice): a normal desktop editor has one; a cloud container needs xvfb + GL (`running-in-the-cloud`); a **pure-headless** process has none and the call returns `BAKE_ERROR_NO_LIGHTMAPPER`. |
+| **`OccluderInstance3D` occlusion bake** | **No.** `bake_single_node` is not script-callable. Editor-button only. |
+
+So when the user asks for baked lighting: add and configure the `LightmapGI` node,
+set the meshes' `gi_mode`, then run the bake yourself from `summer_run_script` —
+`lgi.bake(lgi, "res://lightmaps/scene_lm.exr")` — and check the returned bake-error
+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,
+steer to `SDFGI` (`Environment.sdfgi_enabled`) or `VoxelGI`.
 
 Note the related trap: `Engine.has_singleton("EditorInterface")` returns **true**
 even in a headless non-editor process, so it is not a valid capability probe.

package/library/skills/3d-lighting/resource.yaml

@@ -0,0 +1,27 @@
+id: skill/3d-lighting
+kind: skill
+version: 1.0.3
+summary: Set up 3D scene lighting — DirectionalLight3D vs Omni vs Spot, WorldEnvironment, sky, shadow tuning, ambient — per current Summer conventions.
+use_when:
+  - setting up lighting in a Summer Engine 3D scene — adding lights, configuring WorldEnvironment, sky, or shadows
+  - a 3D scene looks flat, too dark, or washed out, or has harsh or missing shadows
+facets:
+  lifecycle:
+    - build
+  domains:
+    - rendering
+    - lighting
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/running-in-the-cloud
+    - skill/scene-scripting
+source: official
+license: MIT
+status: stable
+recommended: true
+aliases:
+  - skills/rendering-and-lighting/3d-lighting

package/{skills/audio → library/skills}/adaptive-music/SKILL.md

@@ -326,5 +326,5 @@ in Summer Engine.
 - `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
-- `../../../references/godot-version.md` — Summer compatibility for AudioServer
+- `../../references/godot-version/godot-version.md` — Summer compatibility for AudioServer
   and Tween APIs

package/library/skills/adaptive-music/resource.yaml

@@ -0,0 +1,28 @@
+id: skill/adaptive-music
+kind: skill
+version: 1.0.2
+summary: Wire music stems to game state — combat/explore/boss/tension crossfades on a shared bus, paired with a state machine and AudioBus structure.
+use_when:
+  - wiring music stems to game state — combat / explore / boss / tension crossfades on a shared bus
+  - layered or vertical music that changes when combat starts
+facets:
+  lifecycle:
+    - build
+  domains:
+    - audio
+    - gameplay
+  modalities:
+    - audio
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/audio-direction
+    - skill/music-track
+source: official
+license: MIT
+status: stable
+recommended: false
+aliases:
+  - skills/audio/adaptive-music

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

@@ -0,0 +1,148 @@
+---
+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.
+---
+
+# Agent Playtesting
+
+## Overview
+
+`playtesting-a-feature` says a feature is not done until someone has played it. This skill is how *you* play it — not a hidden probe that dies when it finishes, but the live game, driven one action at a time, with a frame-stamped record of what each action did.
+
+The engine's runtime-control ops make the running game a thing you can see and touch:
+
+| Tool | Does |
+|---|---|
+| `summer_play` | Start the game. With `instance` + `mode:"offscreen"` a disposable parallel instance; with `seed` / `fixed_fps` (and `deterministic:true` offscreen) a reproducible one. |
+| `summer_game_probe` | State AND pixels of ONE frame, atomically: live tree, property reads, screenshot, all stamped with the same frame counters. The evidence tool. |
+| `summer_game_control` | `pause`, `resume`, `step` exactly N physics/process frames, `speed`, `instances`. |
+| `summer_game_input` | `script` timed synthetic input; `record_start` / `record_stop` real input into `res://.summer/replays/`; `replay` a recording (with `seed` on a deterministic instance). |
+| `summer_runtime_set` / `summer_runtime_call` | Set a property / call a method on a live node. Actions, not evidence. |
+| `summer_runtime_spawn` | Spawn a PackedScene into, or free a node from, the live game. |
+| `summer_runtime_animate` | Read/drive an AnimationPlayer, an AnimationTree state machine, or read Skeleton3D bone poses. |
+| `summer_stop` | Stop the main game, or `instance` to stop one offscreen instance. |
+
+Every one of these needs a RUNNING game and answers `game_not_running` otherwise. On an engine build that predates them the result is `engine_lacks_op` naming the fallback — usually the `RunVerification` probe from `playtesting-a-feature`. Record that as the expected outcome, not a failure.
+
+<EXTREMELY-IMPORTANT>
+An action is not evidence. `summer_runtime_set` returning `applied: true`, `summer_game_input` returning `completed: true`, `summer_runtime_call` returning a value — each proves the request was honoured, not that the game did what the feature promises. Only a probe of the frame AFTER, compared with a probe of the frame BEFORE, proves motion, spawning, damage, or a state change. Never claim any of those without the two frame numbers.
+</EXTREMELY-IMPORTANT>
+
+## The Loop
+
+```
+  Launch deterministically → Wait for boot → Probe BEFORE → Act → Step (or run) → Probe AFTER → Assert → Stop
+```
+
+### 1. Launch deterministically
+
+Decide before pressing play what the run must pin.
+
+- **Embedded main game** (`summer_play` with no instance): the game the user sees. Add `seed` and `fixed_fps` to pin the RNG and the frame clock — `seed` only applies to a game that is not already running (`determinism.applied: false` with `reason: already_running` means `summer_stop` first).
+- **Offscreen instance** (`summer_play {instance:"a", mode:"offscreen"}`): a hidden child process the user never sees, addressed by name on every runtime tool. Up to three at once. `deterministic: true` launches it with `--fixed-fps 60 --summer-seed <seed> --audio-driver Dummy`; this is the only kind of instance on which `summer_game_input action:"replay"` accepts a `seed`.
+- **Two variants side by side**: `instance:"before"` and `instance:"after"` (different scenes or different `summer_runtime_set` setups), the same recorded input replayed into each, probes compared frame for frame.
+
+The result's `determinism.seed_scope` tells you what the seed does NOT pin: `RandomNumberGenerator` instances (self-randomized on construction), scripts that call `randomize()`, wall-clock reads, thread timing. A feature that uses any of those is not deterministic under a seed; assert ranges there, or fix the script to use the global RNG.
+
+### 2. Wait for boot — never sleep a guessed delay
+
+Boot time varies. Confirm, do not assume:
+
+- Main game: `summer_is_running` until it reports running.
+- Offscreen instance: `summer_game_control action:"instances"` until the instance shows `attached: true`. Before that, every runtime op answers `request_failed` ("session has not attached yet"). `session_timeout` means the child never attached and was killed — read `summer_get_console` for its stderr.
+
+### 3. Probe BEFORE
+
+```
+summer_game_probe
+  tree: {path: "/root/Main", depth: 2}
+  props: ["/root/Main/Player:position", "/root/Main/Player:velocity", "/root/Main/HUD/Health:value"]
+```
+
+Write down `frame.process_frames` and `frame.physics_frames`. Every path you will act on comes from this tree — runtime paths are absolute (`/root/Main/Player`) and differ from the edited scene when nodes spawn, rename, or reparent at runtime. Look at the screenshot and say what is in it.
+
+### 4. Act
+
+One action per step, so the AFTER probe attributes cleanly:
+
+- `summer_runtime_set path:"/root/Main/Player" property:"position" value:"Vector3(0, 2, 0)"` — read `applied`. `applied: false` (`not_applied`) means a script rewrote the value the same frame, or the literal type was wrong; do not proceed as if it landed.
+- `summer_runtime_call path:"/root/Main/Boss" method:"take_damage" args:[25]` — `return` is what the method answered; the effect still needs the probe.
+- `summer_game_input action:"script" events:[{at_frame:0, type:"action", action:"move_right", hold_ms:500}, {at_frame:30, type:"action", action:"jump", hold_ms:50}]` — `rejected[]` names events the game refused (`unknown_action` = not in the InputMap; bind it with `summer_input_map_bind` and restart, or drive `type:"key"`). One script in flight per instance: `busy` means wait for the first.
+- `summer_runtime_spawn action:"spawn" parent:"/root/Main/Enemies" scene:"res://enemies/goblin.tscn" props:{position:"Vector3(4, 0, -2)"}` — use the returned `node.path` from here on.
+
+### 5. Step — for exact assertions
+
+When "after 3 physics frames the velocity is zero" is the claim, do not let wall-clock time decide how many frames ran:
+
+```
+summer_game_control action:"pause"
+summer_game_probe props:[...]                 # frame N
+summer_runtime_set ... / summer_game_input ... wait:false
+summer_game_control action:"step" frames:3   # kind "physics" (default)
+summer_game_probe props:[...]                 # frame N+3 — the step draws its last frame before replying
+```
+
+The step result carries `before`, `after`, `exact`, and `overshoot`; cite them. The game stays suspended after a step — `summer_game_control action:"resume"` when you want it to run again. Time-based behaviour (a 500 ms hold, a 2 s cooldown) runs on the game's clock: with `fixed_fps` a step of N frames IS N/fps seconds; without it, use `at_ms` and read `clock_mapping` ("approximate" means the mapping went through the physics tick rate).
+
+A minimized game window draws no frames and cannot step (`timeout`). `game_breaked` means the game sits at a script breakpoint; continue it in the debugger first.
+
+### 6. Probe AFTER, then assert
+
+Same probe as step 3. Compare the two:
+
+- positions, velocities, HUD values — as inequalities (`x > before.x + 50`), never exact equality unless the run is deterministic AND frame-stepped;
+- `tree` — the spawned node exists under its parent; the freed one is gone (a `queue_free` takes effect at the end of the frame, so step once before asserting absence);
+- the screenshots — look at both and describe the difference in words. A tree that says "goblin spawned" and a frame that shows no goblin is a bug, not a pass.
+
+Then `summer_get_debugger_errors` — a feature that "worked" while logging null-reference errors did not work.
+
+### 7. Stop
+
+`summer_stop` (main) or `summer_stop instance:"a"` for each offscreen instance you started. Offscreen children also die when the editor exits, but do not leave them for the user to discover.
+
+## Input scripts vs. recordings
+
+| | `action:"script"` | `record_start` / `record_stop` / `replay` |
+|---|---|---|
+| Source | You write it from the spec | Whatever actually happened — a human's hands or a script's output |
+| Readable | Yes; edit a frame number and re-run | A JSON file of events; treat it as an artifact |
+| Timing | `at_frame` exact; `at_ms` exact only with `fixed_fps` | Recorded frames re-based on the first event |
+| Best for | Golden paths, edge probes, regression checks | "Do exactly what the user did", A/B of two builds under identical input |
+| Reproducible | With `seed` + `fixed_fps` on the instance | With `seed` on a `deterministic:true` offscreen instance (`replay` refuses `seed` elsewhere: `nondeterministic_instance`) |
+
+Recording caps at 20,000 events / about 1 MiB (`truncated: true` when hit). Files land in `res://.summer/replays/<id>.json`; pass that exact path to `replay`. A waited script or replay is capped at 20 s by the engine — for longer sequences pass `wait:false` and follow along with probes.
+
+## What seed does not pin
+
+Read `determinism.seed_scope` on the play result and believe it. Pinned: the global RNG (`randi`, `randf`, `randi_range`, `randf_range`, `randfn`, `Array.shuffle`, `Array.pick_random`), re-seeded after `SceneTree` init and before autoloads and the main scene. Not pinned: `RandomNumberGenerator` instances, scripts calling `randomize()`, wall-clock reads (`Time.get_ticks_msec` used as a source of variation), thread timing, and anything read from the network or the file system. When a replay diverges on a deterministic instance, one of these is the reason — find it in the script before doubting the tooling.
+
+## Honesty rules
+
+- **Cite frames.** "At frame 1834 the player was at x=12.0; after `move_right` for 30 frames, at frame 1864 x=57.3" is a verification. "The player moved" is not.
+- **`applied: false` is a no.** Do not narrate a value change the read-back denied.
+- **`completed: false` is a no.** The script did not finish inside the wait; probe to see how far it got, do not call it done.
+- **`rejected[]` is part of the result.** Report the rejected events and why, even when the rest applied.
+- **`engine_lacks_op` is the expected outcome on an engine without these ops.** Say so, fall back to the `playtesting-a-feature` probe loop, and do not describe a runtime playtest you could not run.
+- **A screenshot you did not look at is not a screenshot.** Describe what is in it.
+- **Parallel instances are not the user's game.** Findings from `instance:"a"` describe that instance's launch (scene, seed, fixed_fps); say which instance a claim came from.
+- **Do not hand the walkthrough to the user** while any of these tools works. Ask a human only for what a probe cannot judge — feel, beauty, fun (`debugging-game-feel`).
+
+## Red flags — STOP
+
+| Red flag | Reality |
+|---|---|
+| Asserting motion from a `summer_runtime_set` result | applied means the write landed; probe to see the motion |
+| One probe, then "it works" | One frame proves a state, not a change; two frames prove a change |
+| Sleeping a fixed delay after `summer_play` | Boot varies; `summer_is_running` / `instances` `attached:true` |
+| `position.x == 250.0` on a non-deterministic run | Assert inequality, or pin the run with `fixed_fps` + steps |
+| Ignoring `rejected[]` because `applied > 0` | The rejected event may be the one the feature needed |
+| `seed` on the embedded game called "deterministic" | It pins the global RNG only; `deterministic:true` needs an offscreen instance |
+| Leaving offscreen instances running | Stop each one you started |
+
+## Related skills
+
+- `playtesting-a-feature` — the iron law (no shipped claim without a played walkthrough) and the `RunVerification` probe loop this skill replaces when the runtime tools exist.
+- `verifying-scenes` — evidence discipline for the EDITED scene (snapshot, diff, screenshot).
+- `verification-before-completion` — the code layer that must be green before any of this.
+- `debugging-game-feel` — when the feature works but feels wrong.
+- `investigating-bugs` — root-causing a reproducible bug once a recording reproduces it.

package/library/skills/agent-playtesting/resource.yaml

@@ -0,0 +1,52 @@
+id: skill/agent-playtesting
+kind: skill
+version: 1.0.0
+summary: Playtest by driving the LIVE game — deterministic launch, frame-stamped probes before/after each action, exact frame steps, scripted or recorded input.
+use_when:
+  - proving a gameplay feature works by driving the running game frame by frame with the runtime tools (summer_game_probe, summer_game_input, summer_game_control, summer_runtime_set/call/spawn/animate)
+  - a bug repro or an A/B needs a deterministic launch (seed, fixed frame rate, offscreen instance), a recorded input replay, or two instances side by side
+  - deciding what counts as evidence for "it moved / it fired / the node appeared" — the probe-before, probe-after, frame-stamped discipline
+  - asserting exact positions or timings by advancing the live game a physics frame at a time
+do_not_use_when:
+  - static or code-layer checks — verification-before-completion (compile, diagnostics) comes first
+  - a hidden disposable probe run is enough or the engine build lacks the runtime-control ops (Summer Engine 0.5.66 or newer) — playtesting-a-feature's RunVerification loop still applies there
+  - the feature works but feels wrong — debugging-game-feel
+facets:
+  lifecycle:
+    - build
+  domains:
+    - runtime
+    - playtest
+    - verification
+    - agent-workflow
+  modalities:
+    - project
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/play
+    - tool/stop
+    - tool/is-running
+    - tool/game-probe
+    - tool/game-control
+    - tool/game-input
+    - tool/runtime-set
+    - tool/runtime-call
+    - tool/runtime-spawn
+    - tool/runtime-animate
+    - tool/get-runtime-tree
+    - tool/inspect-runtime-node
+    - tool/get-debugger-errors
+    - tool/screenshot
+  skills:
+    - skill/playtesting-a-feature
+    - skill/verifying-scenes
+    - skill/verification-before-completion
+    - skill/debugging-game-feel
+    - skill/investigating-bugs
+source: official
+license: MIT
+status: preview
+recommended: true

package/library/skills/ambient-bed/resource.yaml

@@ -0,0 +1,24 @@
+id: skill/ambient-bed
+kind: skill
+version: 1.0.2
+summary: Generate a long looping location ambience — forest, dungeon, city, spaceship, cave — a looping AudioStreamPlayer on the Ambient bus with a seamless loop.
+use_when:
+  - generating a long looping location ambience — forest at dawn, dungeon air, city street, spaceship hum, cave drip — non-melodic and low-energy
+  - a location feels silent and needs a continuous soundscape beneath the score and effects
+facets:
+  lifecycle:
+    - build
+  domains:
+    - audio
+    - assets
+  modalities:
+    - audio
+    - scenes
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+recommended: false
+aliases:
+  - skills/audio/ambient-bed