summer-engine 3.3.0 → 3.4.1

package/library/skills/concept-art/SKILL.md

@@ -75,9 +75,9 @@ summer_generate_image(
 )
 ```
 
-`style: "none"` is intentional, but be precise about why: only `cartoon` and `anime` append anything to the prompt, `realistic` and `none` append nothing, and any other value is coerced to `none`. So the preset cannot override the prompt's stylistic direction — it just contributes nothing, which is what concept art wants. All four variants' divergence has to come from the prompt.
+`style: "none"` is intentional: only `cartoon` and `anime` append anything to the prompt, `realistic` and `none` append nothing, and any other value is coerced to `none`. So the preset cannot override the prompt's stylistic direction — it just contributes nothing, which is what concept art wants. All four variants' divergence has to come from the prompt.
 
-There is no `image_size` argument, and `options` only recognizes Nano Banana provider keys plus `removeBackground` — an unrecognized key is dropped without an error. Every MCP image comes back at the server's 1:1 default. For wide key art, ask for "wide cinematic framing" in the prompt and accept the square canvas, or generate in the Summer dashboard where aspect ratio is exposed. Since these are exploration images the user reacts to and throws away, square is usually fine.
+For a shape other than square, pass `aspectRatio` (`"16:9"`, `"9:16"`, ...) or `width` + `height`; the result reports the real width and height and the model that ran. Exploration images are thrown away, so square is usually fine. Background removal is the top-level `removeBackground` argument, not an `options` key.
 
 ### 5. Present the batch
 
@@ -114,14 +114,14 @@ The structure: **subject + axis variant + "concept art" + lighting/atmosphere**.
 - **Generating 4 near-identical variants** because you didn't pick a real axis. The user can't choose between four images that all look like the same painting.
 - **Importing concept art as final assets.** These are exploration. The polished version comes from `character-portrait` after a direction is picked.
 - **Treating `style` as the variant axis.** The presets are `realistic | cartoon | anime | none`, and only two of them append anything. Four "stylization" variants have to differ in their prompt text, not in the `style` argument.
-- **Skipping the disambiguation question.** If you don't ask, you'll get yelled at when you generate 4 portraits and the user wanted one polished bust.
+- **Skipping the disambiguation question.** If you don't ask, you may generate four rough variants when the user wanted one polished bust.
 - **Generating before the GameSoul.md is written.** If `.summer/GameSoul.md` exists, read it first — its visual-style section narrows the axis.
 
 ## Edge cases
 
 - **User says "just one" after you propose 4.** That's a `character-portrait` job. Hand off.
 - **User wants 8+ variants.** Generate 4 first; if the user wants more on the same axis, generate 4 more. Don't dump 8 at once — overload paralyzes choice.
-- **Subject is a fully described scene, not an asset.** You're producing key art, not asset reference. Ask for wide cinematic framing in the prompt and bias toward atmospheric — you cannot set an aspect ratio over MCP.
+- **Subject is a fully described scene, not an asset.** You're producing key art, not asset reference. Pass `aspectRatio: "16:9"` (or `width: 1920, height: 1080` for store key art) and bias toward atmospheric.
 - **User wants the final to be 3D.** After they pick a direction, route to `asset-strategy` — concept-art images are not 3D-ready references (they have backgrounds, scene context, dramatic lighting baked in). The 3D pipeline needs its own clean white-background reference.
 
 ## Fallback (no MCP)

package/library/skills/create-asset-sheet/SKILL.md

@@ -11,15 +11,15 @@ paths: ["assets/**", "art/**", "sprites/**"]
 
 # create-asset-sheet — Generate a coherent pack of 2D assets
 
-This skill turns a single prompt into a categorized pack of isolated, named 2D assets ready to drop into a game. It exists because the alternative — generating each asset one-by-one, then losing visual coherence between them, then manually matting backgrounds in Photoshop — is the most-cited pain point from indie devs working with image models in 2026.
+This skill turns a single prompt into a categorized pack of isolated, named 2D assets ready to drop into a game. Generating assets one by one loses visual coherence between them and leaves you matting backgrounds by hand; one sheet keeps the pack consistent.
 
 **Pipeline:**
 
 1. **Generate a sheet** of N isolated assets in one image-gen call.
-2. **Remove background** (fal/bria) so each asset can stand on its own.
-3. **Detect + name + classify** each asset in one vision call (Gemini 3 Pro outputs bbox + snake_case name + category per region).
-4. **Crop** each region with sharp.
-5. **Optionally upscale** any small slice via fal flux-2/edit i2i, preserving aspect.
+2. **Remove the background** so each asset can stand on its own.
+3. **Detect, name and classify** each asset in one vision pass (bounding box + snake_case name + category per region).
+4. **Crop** each region.
+5. **Optionally upscale** any small slice, preserving aspect.
 6. **Save** as a single pack ArtAsset with `packFiles: [{url, name, type}]` and `metadata.sliceBboxes`.
 
 Categories the classifier outputs (used to route into downstream pipelines):
@@ -42,13 +42,7 @@ Categories the classifier outputs (used to route into downstream pipelines):
 
 ## The cleanest path: the studio wizard
 
-The fastest, most reliable way to invoke this flow today is the **Create Asset Sheet** wizard in the Summer studio:
-
-```
-https://summerengine.com/studio/create-tileset
-```
-
-Direct the user there if they're working in the browser. The wizard:
+The most reliable way to run this flow is the **Create Asset Sheet** wizard in Summer Studio's guided workflows. Open it for the user with `summer open workflows` (or `summer_open`) if they're working in the browser. The wizard:
 
 - Offers a 2D / 3D mode toggle (2D is the slice flow described here; 3D is a soft pointer to `concept-art` + per-asset image-to-3D for now)
 - Surfaces six prompt templates (tile sheet, UI kit, menu, character pack, biome, freeform)
@@ -59,7 +53,7 @@ Direct the user there if they're working in the browser. The wizard:
 - Saves as a pack ArtAsset visible in the user's library
 
 If the user is in a chat / agent context, use the programmatic path below. It
-now calls the same server-side slicer as the Studio wizard.
+calls the same server-side slicer as the Studio wizard.
 
 ## Programmatic path (chat / agent driving the engine)
 
@@ -88,14 +82,13 @@ now calls the same server-side slicer as the Studio wizard.
    returned slice ids/names/categories; do not reimplement the vision boxes
    locally.
 
-4. **Optional upscale.** For any crop where longest side < 256px, send through fal flux-2/edit i2i with prompt:
+4. **Optional upscale.** The Studio wizard has per-slice HD upscale. Over MCP, for any crop where the longest side is under 256px, call `summer_generate_image` with the slice as `referenceImageUrl` and this prompt:
 
    ```
    Recreate this exact <name> at high resolution. Preserve every detail, the exact pose, the exact style. Sharper edges, more detail. Transparent background. Single isolated asset, no scene.
    ```
 
-   - Scale longest side to 1024, preserve aspect ratio (FLUX requires multiples of 32).
-   - Don't blindly upscale everything — high-res slices get diminishing returns and you spend $0.04/slice.
+   - Don't upscale everything: each upscale is a paid generation, and large slices gain little.
 
 5. **Import what the game needs.** Use the returned asset ids with
    `summer_import_asset_by_id`. Keep the source pack in My Assets so the agent
@@ -140,26 +133,14 @@ now calls the same server-side slicer as the Studio wizard.
 | Slicer returns 1 giant bbox covering the whole sheet | Items overlap / no gaps in the source | Re-prompt with "each item fully isolated, empty space around each item". Re-generate. |
 | Slicer misses items | Items too small in the source, classifier dropped them as noise | Generate at higher resolution (2048) or with fewer items per sheet |
 | Two items merge into one slice | Items touching in the source | Re-prompt with more isolation. Or accept and let the user split manually in step 2's review. |
-| Slice has a sliver of neighbor in it | Vision bbox is off by 5–15px | Expected. The slicer pads but doesn't snap-to-content yet. Live with it or upscale the slice (FLUX often cleans the edge) |
+| Slice has a sliver of neighbor in it | Vision bbox is off by 5–15px | Expected. The slicer pads but doesn't snap-to-content yet. Live with it or upscale the slice (upscaling often cleans the edge) |
 | Upscaled slice looks invented | Source was too small / too ambiguous | Don't upscale slices below ~32×32. Or accept the hallucination and edit |
 | Detection returns wrong category | Model misjudged context | User can override in the review step; not a blocker |
 
 ## What this skill does NOT do (yet)
 
-- Per-asset planning + individual generation (the Codex-style flow where each asset is generated separately at full resolution). The planner endpoint exists (`POST /api/art/plan-asset-pack`) but the per-asset gen loop is not wired into the wizard yet.
+- Per-asset planning and individual generation, where each asset is generated separately at full resolution.
 - 3D pack assembly. The 3D mode in the wizard is a placeholder pointer to `concept-art` + image-to-3D for now.
-- Character animation routing. Once a slice is classified as `character`, the next step (sprite-sheet generation) is a separate skill that the user has to invoke manually. Auto-routing is on the roadmap.
+- Character animation routing. Once a slice is classified as `character`, the next step (sprite-sheet generation) is a separate skill that the user has to invoke manually.
 - Terrain auto-tiling / Wang-tile generation. Use `tileable-texture` for that.
 - Level composition / scene assembly. Use `design-level`.
-
-## Honest cost estimate
-
-Per 12-asset sheet, end to end through the wizard:
-
-- Generate sheet: $0.04–0.10 (varies by model)
-- Background removal: $0.05
-- Vision detect + classify: $0.02–0.03
-- Save pack: free
-- Optional bulk upscale: ~$0.04 per slice ($0.48 for 12)
-
-**Without upscale:** ~$0.12. **With full upscale:** ~$0.60. About a third of what a Photoshop hour would cost.

package/library/skills/debug/SKILL.md

@@ -28,7 +28,7 @@ victory. Never grep the codebase before reading the actual error.
 
 - The user is asking how to *prevent* a class of bug — that's a design question. Use the relevant discipline skill (`gdscript-patterns`, `scene-composition`).
 - The user is asking for a feature with a known unfinished spec — that's `make-game` territory.
-- The bug is in a non-Godot file the host agent can debug natively (CI config, npm scripts) — use the host's debugger.
+- The bug is in a file outside the game project that the host agent can debug natively (CI config, npm scripts) — use the host's debugger.
 
 ## The Loop
 
@@ -143,7 +143,7 @@ Surface the proposed fix in plain language and ask permission. Two patterns:
 
 - For GDScript edits: `Read` the 20–40 lines around the error, `Edit` the exact change. Don't read the whole file. Don't reformat. Don't rename other things.
 - For scene edits: use the appropriate `summer_*` tool (`summer_add_node`, `summer_set_prop`, `summer_replace_node`). Group multi-step changes in `summer_batch` for one undo step.
-- **Nested resource properties:** `summer_set_resource_property` works against inline `sub_resource` targets too — pass `nodePath`, `resourceProperty`, and `subProperty` (there is no dotted `"mesh.size"` form). Structural failures (`node not found`, `property is not a resource`, `resource is null`) are explicit errors; a bad value shape is not — a JSON object instead of a Godot literal string, a misspelled `key`/`subProperty`, or a wrong-typed value returns `ok:true` yet silently no-ops or coerces destructively on current engines (dict → material cleared; dict → `Color(0,0,0,1)`; newer engines reject these with `unknown_property` / `bad_value_shape` / `type_mismatch`). Pass class names and `Color(...)`/`Vector3(...)` strings, and confirm the fix in the saved `.tscn` or a snapshot diff, never from `ok` alone. See `../../references/mcp-tools-reference/mcp-tools-reference.md`.
+- **Nested resource properties:** `summer_set_resource_property` works against inline `sub_resource` targets too — pass `nodePath`, `resourceProperty`, and `subProperty` (there is no dotted `"mesh.size"` form). Structural failures (`node not found`, `property is not a resource`, `resource is null`) are explicit errors; a bad value shape is not — a JSON object instead of an engine literal string, a misspelled `key`/`subProperty`, or a wrong-typed value returns `ok:true` yet silently no-ops or coerces destructively on current engines (dict → material cleared; dict → `Color(0,0,0,1)`; newer engines reject these with `unknown_property` / `bad_value_shape` / `type_mismatch`). Pass class names and `Color(...)`/`Vector3(...)` strings, and confirm the fix in the saved `.tscn` or a snapshot diff, never from `ok` alone. See `../../references/mcp-tools-reference/mcp-tools-reference.md`.
 
 ### 6. Verify — re-run the diagnostic that found it
 
@@ -160,7 +160,7 @@ If the diagnostic is still red after the fix, you formed the wrong hypothesis. G
 | Don't | Why |
 |---|---|
 | Grep the whole project before reading the error | The error already names the file and line. Save the user's tokens. |
-| Read whole files | 20–40 lines around the error is enough 90% of the time. |
+| Read whole files | 20–40 lines around the error is usually enough. |
 | Run multiple diagnostics in parallel | They mask each other's signal. Cheapest first, escalate. |
 | Edit before asking | The user owns the fix decision, you own the diagnosis. |
 | "Try this, see if it works" | That's not a hypothesis, that's gambling. State the theory or ask another question. |
@@ -177,7 +177,7 @@ If the diagnostic is still red after the fix, you formed the wrong hypothesis. G
 | "Cannot find type 'X'" | `summer_get_script_errors` | Class name mismatch, missing autoload, missing `class_name` |
 | Game runs but visuals wrong | `summer_get_console` + `summer_inspect_node` | Material/light/camera misconfigured |
 | Game freezes (no crash) | `summer_get_console` after `summer_play` for ~3s | Infinite loop in `_process` or `_ready` |
-| `summer_set_resource_property` "succeeded" but nothing changed | n/a | Inline sub-resource silent-fail. Use `summer_set_prop` with class name first. |
+| `summer_set_resource_property` "succeeded" but nothing changed | n/a | Bad value shape (JSON object, misspelled `subProperty`, wrong type). Pass engine literal strings and confirm in the saved `.tscn`. |
 
 ## Closing
 
@@ -200,6 +200,7 @@ The static and boot-time tools (`summer_get_script_errors`, `summer_get_console`
 - **Runtime debugger warning text** (`summer_get_debugger_warnings`) — same structured shape as the errors tool, filtered to severity `warning`. Use it whenever `summer_get_diagnostics` shows a non-zero `debugger.warnings`; do not report a warning count you never read.
 - **Diagnostics summary** (`summer_get_diagnostics`) — counts of console errors, debugger errors, debugger warnings, script errors. Tells you where to drill. **Counts only** — it carries no FPS, frame time, draw calls, or physics-body numbers.
 - **Scene tree + node properties** (`summer_get_scene_tree`, `summer_inspect_node`) — only the **edited** scene, not the running game's live tree.
+- **Live runtime state** (`summer_get_runtime_tree`, `summer_inspect_runtime_node`, `summer_game_probe`) — the running game's tree, properties and frames, on engine builds with the runtime-control ops. See `agent-playtesting`.
 - **Rendered pixels** (`summer_screenshot`) — `target:"viewport"` for the editor's current view, `target:"scene"` for an offscreen render of a scene file, `target:"game"` for a frame of the running game (that one needs the Summer desktop app bridge and fails cleanly over a plain local connection). You look at the actual image, not a description of it.
 - **Gameplay behaviour, driven by you** (`RunVerification` via `summer_batch`) — see the next section. Input, live tree, and frames from a real running instance.
 - **Whether the game is running** (`summer_is_running`) — and on which scene.

package/library/skills/debugging-game-feel/SKILL.md

@@ -184,11 +184,8 @@ After diagnosis pins down which variable(s) are wrong, the tuning is done — bu
 - `game-feel` — for the screen-shake, hit-stop, particle, sound layer once tuning is locked.
 - `debug` — if mid-debug you discover an actual error (signal not firing, node freed) hiding under the feel issue.
 
-## The Bottom Line
+## Related skills
 
-Feel bugs are tuning bugs. Tuning is a one-variable-at-a-time discipline. Anchor to a reference. Tweak one number. Play it. Decide. Repeat.
-
-**Related skills:**
 - `investigating-bugs` — for logical bugs with concrete repros, not feel.
 - `playtesting-a-feature` — the playtest discipline this skill plugs into.
 - `debug` — when the feel investigation surfaces an actual error.

package/library/skills/debugging-game-feel/resource.yaml

@@ -6,7 +6,7 @@ use_when:
   - a gameplay feature works correctly but feels wrong — floaty jumps, mushy combat, sluggish camera, weightless impacts
   - tuning jump height, gravity, camera lag, hit-stop, or impact feedback until controls feel right
 do_not_use_when:
-  - the bug is a logic error rather than subjective feel — use logical bug debugging
+  - the bug is a logic error rather than subjective feel — use investigating-bugs
 facets:
   lifecycle:
     - build

package/library/skills/design-level/SKILL.md

@@ -273,8 +273,8 @@ The skeleton this skill produces is meant to be filled in via `/design-mechanic`
 
 ## See also
 
-- `scene-and-project/brainstorm-game/SKILL.md` — produces `.summer/GameSoul.md`
-- `gameplay-mechanics/design-mechanic/SKILL.md` — designs the verbs the level exercises
-- `ai-and-npcs/design-npc/SKILL.md` — designs the enemies the encounters reference
-- `rendering-and-lighting/3d-lighting/SKILL.md` — sets the lighting in `WorldEnvironment` + lights
-- `rendering-and-lighting/art-direction/SKILL.md` — defines the visual style the level expresses
+- `brainstorm-game` — produces `.summer/GameSoul.md`
+- `design-mechanic` — designs the verbs the level exercises
+- `design-npc` — designs the enemies the encounters reference
+- `3d-lighting` — sets the lighting in `WorldEnvironment` + lights
+- `art-direction` — defines the visual style the level expresses

package/library/skills/design-mechanic/SKILL.md

@@ -142,7 +142,7 @@ Argument notes, all of which the tool schema enforces:
   "current scene" default.
 - `summer_set_prop` takes named `path` / `key` / `value` — not positional.
 - `summer_input_map_bind` events are dicts. `{"type": "key", "key": "Space"}`
-  works; key names go through Godot's keycode table, so `W`, `Space`, `Shift`,
+  works; key names go through the engine's keycode table, so `W`, `Space`, `Shift`,
   `Escape` resolve and typos silently produce no event.
 - `summer_get_script_errors` checks one file and requires `path`. Use
   `summer_get_diagnostics()` (no args) for a project-wide check.
@@ -266,8 +266,8 @@ This skill is a workflow that designs and scaffolds — the templates are runnab
 
 ## See also
 
-- `scene-and-project/brainstorm-game/SKILL.md` — produces `.summer/GameSoul.md` this skill reads
-- `level-design/design-level/SKILL.md` — design the levels that exercise the mechanic
-- `character-controllers/fps-controller/SKILL.md` — FPS movement scaffolding
-- `scripting-patterns/state-machine-patterns/SKILL.md` — state machines for complex mechanics
-- `audio/audio-direction/SKILL.md` — defines the SFX vocabulary the mechanic draws from
+- `brainstorm-game` — produces `.summer/GameSoul.md` this skill reads
+- `design-level` — design the levels that exercise the mechanic
+- `fps-controller` — FPS movement scaffolding
+- `gdscript-patterns` — state machines and other script patterns for complex mechanics
+- `audio-direction` — defines the SFX vocabulary the mechanic draws from

package/library/skills/design-npc/SKILL.md

@@ -211,7 +211,7 @@ resources exactly as it does against external `.tres` files — it reads the
 property off the node and writes the sub-property onto whatever Resource is
 there. Structural failures are explicit errors (`node not found`, `property is
 not a resource`, `resource is null`); a bad value shape is not — a JSON object
-instead of a Godot literal string, a misspelled `subProperty`, or a wrong-typed
+instead of an engine literal string, a misspelled `subProperty`, or a wrong-typed
 value returns `ok:true` yet silently no-ops or coerces destructively on current
 engines. Pass class names and literal strings (`"12.0"`, `"Color(r, g, b, a)"`)
 and confirm the result in the saved `.tscn`, never from `ok` alone. The order
@@ -490,20 +490,13 @@ This skill writes scenes and scripts. Always ask before each step. Group related
 
 ## Want a working starter?
 
-For a fully-rigged enemy with anim controller + loot drop:
-
-→ **template-id**: `template-3d-fps` — ships with a sample patrol enemy
-→ For higher-complexity AI (boss with phases, behavior trees), defer to `ai-and-npcs/behavior-trees/SKILL.md`.
+For an animated NPC in a runnable project: `summer create 3d-fps-simple-animated-npc`. Run `summer list templates` for the current list.
 
 ## See also
 
-- `ai-and-npcs/state-machine-npc/SKILL.md` — FSM pattern deep dive
-- `ai-and-npcs/behavior-trees/SKILL.md` — when complexity demands a BT
-- `ai-and-npcs/perception-sight-and-hearing/SKILL.md` — sensor patterns
-- `ai-and-npcs/navmesh-pathfinding/SKILL.md` — NavigationAgent3D for movement
-- `ai-and-npcs/llm-driven-dialogue/SKILL.md` — Summer's wedge for talking NPCs
-- `ai-and-npcs/boss-patterns/SKILL.md` — phase transitions, mechanics
-- `visual-effects/recipes/hit-spark/SKILL.md` — hit flash recipe
-- `visual-effects/recipes/dissolve/SKILL.md` — death dissolve recipe
-- `visual-effects/game-feel/SKILL.md` — screen-feel discipline (camera shake, hit-stop)
-- `scripting-patterns/state-machine-patterns/SKILL.md` — generic FSM patterns
+- `animation-tree` — wire the action states to animation clips
+- `ai-characters-in-games` — NPCs that answer free-form player text
+- `vfx-hit-spark` — hit flash recipe
+- `vfx-dissolve` — death dissolve recipe
+- `game-feel` — screen-feel discipline (camera shake, hit-stop)
+- `gdscript-patterns` — generic state machine and script patterns

package/library/skills/diagnosing-perf-regressions/SKILL.md

@@ -117,7 +117,7 @@ If a single commit is the obvious suspect (e.g. "Added 200 enemies to spawner"),
 
 ### 4. Match to one of the four Summer Engine performance cliffs
 
-Godot 4.x regressions cluster heavily into four categories. Knowing them shortens diagnosis to minutes.
+Regressions cluster into four categories. Matching the symptom to one shortens diagnosis.
 
 | Cliff | Symptom | How to verify | Common cause |
 |---|---|---|---|
@@ -156,7 +156,7 @@ State the result with the number: "Reverted the per-frame `get_tree().get_nodes_
 |---|---|
 | Regression confirmed and root cause known, but the fix is "make the feature cheaper" rather than "undo the change" | `tune-performance` for the optimization pass |
 | The regression turns out to be a crash or error in disguise (the slow path is throwing exceptions in a tight loop) | `debug` |
-| The cause is a Godot version change or engine-side regression | Surface to the user; this is not a project-side fix |
+| The cause is an engine version change or engine-side regression | Surface to the user; this is not a project-side fix |
 | Bisect lands on a commit that touches 40 files | Subdivide the commit: check out the commit, revert subsets, re-measure |
 
 ## Red Flags — STOP
@@ -179,9 +179,9 @@ State the result with the number: "Reverted the per-frame `get_tree().get_nodes_
 | Excuse | Reality |
 |---|---|
 | "User wants it fixed now, no time to bisect" | Bisect is 5-15 minutes. Blind optimization can burn a day. |
-| "The slow commit is obvious, no need to A/B" | The "obvious" cause is wrong ~30% of the time. Verify before fixing. |
+| "The slow commit is obvious, no need to A/B" | The "obvious" cause is often wrong. Verify before fixing. |
 | "I'll measure after I fix it" | If you don't have the bad number, you can't prove the fix worked. |
-| "It's probably just Godot" | Engine-side regressions exist but are rare. Suspect your project first. |
+| "It's probably the engine" | Engine-side regressions exist but are rare. Suspect your project first. |
 | "Adding a pool / LOD / cache will help anyway" | Premature optimization on the wrong system is wasted work. |
 
 ## When The Engine Isn't Running
@@ -202,13 +202,8 @@ If the MCP tools report the engine isn't running:
 3. Only if neither is possible: ask the user for an in-game perf overlay reading (FPS, frame time, draw call count) and walk the bisect with them — "run on commit X, tell me the FPS; run on commit Y, tell me the FPS."
 4. Do not claim a fix is verified from code reading alone.
 
-## The Bottom Line
+## Related skills
 
-A regression is a delta. Diagnose the delta, not the codebase.
-
-Measure now. Measure last-good. Bisect what changed. Match to a Godot perf cliff. A/B one variable. Re-measure. Done.
-
-**Related skills:**
 - `tune-performance` — for general optimization once the regression is fixed or when no regression exists.
 - `investigating-bugs` — when the slow path turns out to be a logic bug (errors in a tight loop).
 - `debug` — when the perf issue is actually a crash or freeze.

package/library/skills/dispatching-parallel-agents/SKILL.md

@@ -130,7 +130,7 @@ Return: Summary of what you found and what you fixed.
 **Exploratory debugging:** You don't know what's broken yet
 **Shared state:** Agents would interfere (editing same files, using same resources)
 
-## Real Example from Session
+## Example
 
 **Scenario:** 6 test failures across 3 files after major refactoring
 
@@ -155,15 +155,6 @@ Agent 3 → Fix tool-approval-race-conditions.test.ts
 
 **Integration:** All fixes independent, no conflicts, full suite green
 
-**Time saved:** 3 problems solved in parallel vs sequentially
-
-## Key Benefits
-
-1. **Parallelization** - Multiple investigations happen simultaneously
-2. **Focus** - Each agent has narrow scope, less context to track
-3. **Independence** - Agents don't interfere with each other
-4. **Speed** - 3 problems solved in time of 1
-
 ## Verification
 
 After agents return:
@@ -171,12 +162,3 @@ After agents return:
 2. **Check for conflicts** - Did agents edit same code?
 3. **Run full suite** - Verify all fixes work together
 4. **Spot check** - Agents can make systematic errors
-
-## Real-World Impact
-
-From debugging session (2025-10-03):
-- 6 failures across 3 files
-- 3 agents dispatched in parallel
-- All investigations completed concurrently
-- All fixes integrated successfully
-- Zero conflicts between agent changes

package/library/skills/environment-kit/SKILL.md

@@ -13,7 +13,7 @@ paths: ["assets/kits/**", "assets/models/**", "**/*.tscn", "**/*.gd"]
 
 A kit is a *family* of meshes — wall, floor, door, pillar, corner, arch — that the level designer snaps together to build interiors and exteriors. The skill exists to solve **one specific failure mode**: generating each piece with a fresh prompt produces six pieces that look like they came from six different games. The fix is the **style anchor pattern** — generate one piece first, lock its prompt suffix, and reuse that exact suffix for every subsequent piece.
 
-The backing tool is `summer_generate_3d`, called multiple times. Each call costs ~$0.50, so a 6-piece kit is ~$3 and ~5 minutes. Confirm scope before starting.
+The backing tool is `summer_generate_3d`, called once per piece. A 6-piece kit is six generations and about 5 minutes. Generation uses credits, so confirm scope before starting.
 
 ## When to use
 
@@ -32,7 +32,7 @@ The backing tool is `summer_generate_3d`, called multiple times. Each call costs
 
 ## The style anchor pattern
 
-This is the whole skill. Get this right and the kit looks unified. Get this wrong and you waste $3.
+This is the whole skill. Get it right and the kit looks unified. Get it wrong and every piece is wasted.
 
 1. **Generate the anchor piece first.** Pick the most visually defining piece — usually the wall or the door. Iterate the prompt until the user approves it visually.
 2. **Extract the style suffix.** Everything after the object description. Example anchor prompt:
@@ -69,7 +69,7 @@ Kit pieces only feel modular if they snap to a fixed grid. Pick the grid before
 
 ### 1. Confirm scope and pick the grid
 
-> About to build a dungeon kit. Suggested pieces: wall, floor, pillar, door, corner, arch (6 pieces, ~$3, ~5 min). Snap grid: 2m (standard interior). OK?
+> About to build a dungeon kit. Suggested pieces: wall, floor, pillar, door, corner, arch (6 generations, ~5 min). Snap grid: 2m (standard interior). OK?
 
 ### 2. Generate the anchor (wall)
 
@@ -131,13 +131,13 @@ Three things the shape of those calls encodes:
 summer_inspect_resource(path="res://assets/kits/dungeon/wall.glb")
 ```
 
-Check the AABB. If the wall is 1.85m tall when you asked for 3m, scale it in the editor (or re-import with `Scale` in the import dock). Pivots should sit at the *bottom-back* corner for walls and *bottom-center* for floors — that makes snapping to a 2m grid trivial. If pivots are wrong, use Godot's "Center to Origin" import option.
+Check the AABB. If the wall is 1.85m tall when you asked for 3m, scale it in the editor (or re-import with `Scale` in the import dock). Pivots should sit at the *bottom-back* corner for walls and *bottom-center* for floors — that makes snapping to a 2m grid trivial. If pivots are wrong, use the "Center to Origin" import option.
 
 ## Anti-patterns
 
 - **Drifting style suffix.** Each piece gets a slightly different suffix → the kit looks mismatched. Copy-paste the exact string.
 - **Different polycount per piece.** A 5k-tri pillar next to a 500-tri wall reads as "the pillar is a hero piece" — wrong; they should feel like equal kit citizens. Match polycount within ~2× across the kit.
-- **Skipping the anchor approval.** If you generate all six pieces in a batch, you bake in whatever the first call's interpretation of the style was — and the user may hate it after $3 of generation.
+- **Skipping the anchor approval.** If you generate all six pieces in a batch, you bake in whatever the first call's interpretation of the style was — and the user may hate it after six generations.
 - **Generating walls / floors as individual meshes when you only need a tileable texture.** A flat wall section is cheaper as a textured `CSGBox3D`. Reserve the kit for pieces that need actual geometric detail (sconces, mouldings, doorways, arches).
 - **No scale cue in the prompt.** Wall comes back 0.4m tall. Always include `2 meter wide by 3 meter tall` (or your chosen grid).
 - **Forgetting the snap grid.** A 1.87m-tall wall with no scale fix → level looks crooked when tiled.

package/library/skills/export-and-ship/SKILL.md

@@ -33,15 +33,17 @@ export command.
 1. Read `engineBinaryPath` from `summer_get_project_context`.
 2. Resolve the matching export-template directory for that exact Summer
    technical base.
-3. Inventory the installed templates and any `custom_template/release` paths
-   already configured in `export_presets.cfg`.
+3. Inventory the installed templates (`summer_export_templates` lists them and
+   installs Summer's macOS, Windows and web templates) and any
+   `custom_template/release` paths already configured in `export_presets.cfg`.
 4. Build a capability table with `available`, `missing prerequisite`, or
    `impossible on this build` for every requested target.
 
-A stock Summer 4.6.1 Mono install has only the macOS template. Web export is
-incompatible with that Mono build. Windows, Linux, Android, and iOS require a
-matching custom template or an external CI/build environment, plus their
-platform toolchains where applicable.
+A stock Summer Mono install ships only the macOS template. Web export is
+incompatible with that Mono build. Run `summer_export_templates` before marking
+another target missing: it installs Summer's macOS and Windows templates. Linux,
+Android, and iOS require a matching custom template or an external CI/build
+environment, plus their platform toolchains where applicable.
 
 **Hard gate:** an absent template or toolchain means the target is unavailable.
 Do not create its preset, recommend it as a local option, or invoke an export
@@ -55,7 +57,8 @@ Offer only targets marked `available` by step 1. Record other requested
 destinations as blocked follow-ups with their exact prerequisite.
 
 > Locally proven targets: **macOS**. Requested but blocked: **Windows**
-> (matching template or external CI), **Web** (non-Mono build), **Android**
+> (install the template with `summer_export_templates`), **Web** (non-Mono
+> build), **Android**
 > (template + Android toolchain). Which proven target should I prepare?
 
 Each destination has a different list. Multiple destinations = multiple lists. Don't shortcut — the iOS list does not satisfy the Steam list.
@@ -145,7 +148,7 @@ Build config:
 
 #### c) Web (HTML5) — unavailable on the stock Mono build
 
-Do not recommend or attempt this target from the stock Summer installation.
+Do not recommend or attempt this target from the stock Mono installation.
 Route it to a verified non-Mono Summer-compatible build environment first.
 Once that prerequisite is proven, these browser constraints apply:
 
@@ -157,7 +160,7 @@ Once that prerequisite is proven, these browser constraints apply:
 Build config:
 - Export preset: **Web**.
 - Output `.html` + `.wasm` + `.pck` + `.js`.
-- Disable: "Variant: Editor support", "Encryption". Keep: "GLES3 Fallback to GLES2" if targeting old browsers.
+- Disable: "Variant: Editor support", "Encryption".
 
 Known traps:
 - Audio: Chrome blocks autoplay. First user click must trigger audio context resume.
@@ -168,7 +171,7 @@ Known traps:
 | Asset | Resolution / Format |
 |---|---|
 | App icon | 1024×1024 PNG (Apple generates the rest) |
-| Launch screen | Storyboard (Godot generates) |
+| Launch screen | Storyboard (the engine generates it) |
 | Screenshots | 6.5" iPhone: 1242×2688 / 2688×1242 (≥ 3); 12.9" iPad if iPad-eligible |
 | App Store description | text per locale, ≤ 4000 chars |
 | Keywords | ≤ 100 chars, comma-separated |
@@ -230,13 +233,14 @@ For each preset:
 | `texture_format/etc2_astc` | `true` for mobile | Smaller texture compression |
 | `application/short_version` | matches `application/config/version` | Steam reads it |
 | `script_encryption_key` in `export_credentials.cfg` | set only when the user explicitly chooses script encryption | The similarly named preset field does not exist |
-| `application/icon` | path to your `.ico` / `.icns` / `.png` | Otherwise generic Godot icon ships |
+| `application/icon` | path to your `.ico` / `.icns` / `.png` | Otherwise the default engine icon ships |
 
 ### 6. Propose the build sequence
 
-> Capability proof: macOS available locally; Windows and Linux require external
-> CI; Web is unavailable on this Mono build. Pre-flight is clean for the macOS
-> preset. May I produce that one proven build now?
+> Capability proof: macOS available locally; Windows needs its template
+> (`summer_export_templates`); Linux requires external CI; Web is unavailable
+> on this Mono build. Pre-flight is clean
+> for the macOS preset. May I produce that one proven build now?
 
 ### 7. Produce a proven build
 
@@ -270,14 +274,14 @@ To enable another target, prove one of these before returning to step 2:
 
 ### Export-option cautions
 
-- **`script/encryption_key` does not exist.** The real key is `script_encryption_key`, and it lives in a separate `export_credentials.cfg`, not `export_presets.cfg` (`editor/export/editor_export.cpp:101,372-373`). Writing the wrong name produces an **unencrypted build with no error at all**.
+- **`script/encryption_key` does not exist.** The real key is `script_encryption_key`, and it lives in a separate `export_credentials.cfg`, not `export_presets.cfg`. Writing the wrong name produces an **unencrypted build with no error at all**.
 - **There is no `debug` field in a preset.** Debug versus release is chosen by `--export-debug` versus `--export-release`, nothing else.
 
 On Apple Silicon, `binary_format/architecture="arm64"` is the natural guess, and it fails leaving a **0-byte `.app` that looks like success**. Only `"universal"` ships.
 
 See `headless-scripting` for the wider pattern this is one instance of.
 
-If the user is on a CI system (GitHub Actions etc), this is the right place to point them at a cross-compile workflow — Godot can export Windows + Linux from a Linux runner.
+If the user is on a CI system (GitHub Actions etc), point them at a cross-compile workflow: the engine can export Windows and Linux from a Linux runner.
 
 ### 8. Verify each build
 
@@ -293,6 +297,8 @@ Per platform, point the user at the correct upload path:
 
 - **summer.games:** `summer_export_game` writes the summer.games `.zip`; `summer_publish_build` uploads it to the game's store listing after the user confirms the exact game, file and version (needs `summer login --store`). If it answers `store_auth_refused`, the user uploads the `.zip` in Studio instead.
   - Per platform, the store takes: iPhone, Android, macOS and Windows in the Summer apps = one summer.games bundle (`summer_export_game` `targets`, format `bundle`; no template, no signing; a game without a server targets `ios`/`android` only). Web = an HTML5 `.zip` on Summer's WebGPU Forward+ template (`targets:["web"]`; the project must render with Forward+ or Mobile). A macOS or Windows download for the store page = `targets:["macos"]` or `["windows"]` with format `download`. Download exports need the template: `summer_export_templates` `install` fetches it from Summer's CDN.
+  - Hosted games: if `summer_export_game` fails with "… is in the source graph's authority_engine domain, which the client pack leaves out", an authority root in `source-domains.json` holds a file the client loads (often the composition `.tres`). Narrow that root to the server-only files, or move the shared file under a `shared` path, then export again. Every exporter message is in the `multiplayer-publish` skill's export-errors.md; the folder rules are in `multiplayer-project`.
+  - Store page art: key art, covers and icons carry no text, logos or UI (the store page shows the title). Screenshots are real gameplay and may show the game's own HUD; add no captions, logos or overlays. Capture them with `summer_capture_gameplay` (offscreen, no editor needed; `resolution` `1920x1080`, or `1080x1920` for portrait; pass the gameplay `scene` when the main scene is a title menu), or `summer_screenshot` target `game` while the editor runs the game.
 - **Steam:** `steamcmd` + Steam Pipe (`builder_app_xxx.vdf`). Set up depots first in Steamworks.
 - **itch.io:** `butler push <path> <user>/<game>:<channel>` (e.g. `butler push build/win <user>/mygame:windows`).
 - **Web (itch hosted):** zip + drop into itch upload UI as "playable in browser".
@@ -352,7 +358,7 @@ This skill produces release artifacts. Always ask before each build is invoked.
 
 ## Want a working starter?
 
-No template — this is a workflow. Each project's export config and store assets are project-specific. For the Steam-specific GodotSteam GDExtension setup, see `deployment/steam-uploader/SKILL.md` (when shipped).
+No template — this is a workflow. Each project's export config and store assets are project-specific.
 
 ## See also
 
@@ -360,10 +366,5 @@ No template — this is a workflow. Each project's export config and store asset
 - `../../references/godot-version/godot-version.md` — Summer compatibility and
   export-template versioning
 - `../../references/collaborative-protocol/collaborative-protocol.md` — "May I write" pattern
-- `deployment/export-presets/SKILL.md` — preset config deep dive
-- `deployment/web-html5-export/SKILL.md` — HTML5-specific traps
-- `deployment/steam-uploader/SKILL.md` — `steamcmd` + GodotSteam (when shipped)
-- `deployment/itch-uploader/SKILL.md` — `butler` workflow (when shipped)
-- `deployment/mobile-export/SKILL.md` — iOS / Android specifics (when shipped)
-- `asset-pipeline/attribution-and-licensing/SKILL.md` — community asset attribution
-- `performance/tune-performance/SKILL.md` — pre-ship performance pass
+- `headless-scripting` — the headless CLI pattern the export command follows
+- `tune-performance` — pre-ship performance pass

package/library/skills/fabricating-assets/SKILL.md

@@ -24,7 +24,7 @@ Three facts shape every use:
 | Blockout / placeholder | `scene-scripting` primitives or CSG | fabricate | Must be instant and in-scene; no process spawn is justified |
 | Generic hard-surface prop ("a barrel") | `summer_search_assets` → `summer_import_asset` (`prop-model`) | `summer_generate_3d` | The free library plus `target_size` beats paid generation and a 2-minute wait, in a consistent style |
 | Bespoke prop ("the artifact from our GDD") | `summer_generate_3d` | fabricate | Image-to-3D is exactly what generation is for; fabricate when exact dimensions or parametric variants matter |
-| **Modular kit** (walls, pipes, fences, rails that snap) | **fabricate** | library kit (`environment-kit`) | Generation cannot hold dimensions and style across 30 pieces; array + boolean + bevel + one material is the classic kit workflow |
+| **Modular kit** (walls, pipes, fences, rails that snap) | **fabricate** | generated kit (`environment-kit`) | Generation cannot hold dimensions and style across 30 pieces; array + boolean + bevel + one material is the classic kit workflow |
 | Characters (rigged, animated) | `summer_generate_3d` (`character-model`) | library | Scripted organic modelling is the documented failure mode; fabrication has no path to competitive organics blind |
 | Environments / terrain | in-engine terrain + library set dressing | generation for landmarks | Terrain wants interactive tools; dressing wants scatter |
 | Materials / textures / skies | library (`summer_import_hdri`, texture packs) | generation | Fabricate only to bake a procedural material to images |

package/library/skills/facial-and-lipsync/SKILL.md

@@ -13,10 +13,10 @@ paths: ["**/*.gd", "**/*.tscn", "**/*.tres"]
 
 Half generative, half authored. The *generative* half: an audio file (TTS via `summer_generate_audio` with `capability: "text_to_speech"`) goes through a phoneme-extraction tool (Summer does NOT wrap one — you run it externally), out comes a viseme timeline — a list of `{ phoneme, start_time, duration }` triples. The *authored* half: the character's face mesh must have BlendShapes named for the standard viseme set, or the timeline has nothing to drive. Without both halves, you get a talking robot.
 
-The 2026 production stack:
+The pipeline:
 
 1. **Audio in** — `.wav`/`.mp3` from `summer_generate_audio({capability: "text_to_speech", ...})` or imported VO.
-2. **Phoneme extraction** — done OUTSIDE Summer. Recommended: **Rhubarb Lip Sync** (open source, the industry standard for game-dev lipsync; outputs JSON with mouth-shape cues over time). Alternatives: gentle, allosaurus, or a Whisper-phoneme model on Replicate / Hugging Face. There is no `summer_*` MCP for this in the current engine.
+2. **Phoneme extraction** — done OUTSIDE Summer. Recommended: **Rhubarb Lip Sync** (open source, widely used for game lipsync; outputs JSON with mouth-shape cues over time). Alternatives: gentle, allosaurus, or a Whisper-phoneme model on Replicate / Hugging Face. There is no `summer_*` MCP for this in the current engine.
 3. **Viseme mapping** — phonemes / Rhubarb cues → Oculus / Apple ARKit viseme set (15 standard shapes covers English).
 4. **BlendShape driver** — at runtime, lerp the mesh's BlendShape weights along the timeline, synced to audio playback.
 5. **Optional emotional layer** — separate BlendShape track for `smile`, `brow_raise`, `eye_squint` etc., authored in code or at clip-edit time.
@@ -122,7 +122,7 @@ Rhubarb mouth-shape → ARKit viseme cheat sheet (apply during the bake step):
 
 **Cloud fallback:** a Whisper-phoneme model on Replicate or a Hugging Face inference endpoint will emit ARPAbet phonemes with timestamps. Then map ARPAbet → ARKit visemes via the table in the Reference card section. More accurate than Rhubarb on noisy audio; slower and costs cents per minute.
 
-Cost: Rhubarb is free + ~5s CPU per 30s clip locally. Cloud fallback ~$0.02 / minute, ~5s wall-clock for a 30s clip.
+Rhubarb is free and takes ~5s of local CPU per 30s clip. The cloud fallback is billed per minute by its provider and takes ~5s for a 30s clip.
 
 ### 4. Persist the viseme track as an AnimationLibrary entry
 
@@ -254,7 +254,7 @@ Driven from gameplay events; orthogonal to the lipsync layer.
 
 ### Phoneme → viseme mapping (for hand-rolled extraction)
 
-If the user has a CMUDict-style phoneme list and wants to map manually, this is the table to apply.
+If the user has a CMUDict-style phoneme list, map it with the ARPAbet column of the table above.
 
 ### Pitfalls
 
@@ -300,7 +300,7 @@ production speech recognition or photoreal lip sync.
 - For dialogue scripts and conversation flow, `design-npc`.
 - For the AnimationTree this layer composes into, `animation-tree`.
 - For idle blinks, saccades, and head-tracking that complement lipsync, `procedural-animation`.
-- For full performance capture (face + body together), out of scope — see Meshy's mocap docs or external pipelines.
+- Full performance capture (face and body together) is out of scope; use an external capture pipeline.
 
 ## See also