summer-engine 3.4.0 → 3.4.1

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

@@ -1,14 +1,14 @@
 # Summer MCP Tools — Canonical Reference
 
-> Use this as the single source of truth for which Summer MCP tool to call. Skills should reference tool names exactly as written here.
+> Which Summer MCP tool to call. Skills reference tool names exactly as written here.
 
 ## When to use Summer MCP vs. host tools
 
-**Use Summer MCP for** anything that needs the live editor or Godot's import pipeline:
+**Use Summer MCP for** anything that needs the live editor or the engine's import pipeline:
 - Scene graph mutation (`.tscn`)
 - Node properties and resources (`.tres`)
 - Project settings (`project.godot`) and InputMap
-- Asset import (Godot's import pipeline must run)
+- Asset import (the import pipeline must run)
 - Play / stop / runtime state
 - Diagnostics, console, debugger output, script errors
 - Project text reads and guarded writes (`.gd`, `.cs`, `.tscn`, `.tres`, JSON, docs, config)
@@ -28,7 +28,7 @@
 | `summer_write_file` | Create-only or sha256-guarded complete file write. |
 | `summer_replace_text` | Unique (or explicit replace-all) text mutation with read/sha guard. |
 
-### Scene graph (11)
+### Scene graph (12)
 
 | Tool | Use |
 |---|---|
@@ -49,7 +49,7 @@
 
 | Tool | Use |
 |---|---|
-| `summer_set_prop` | Set a typed property in an explicit `scenePath` using Godot's `str_to_var()`. |
+| `summer_set_prop` | Set a typed property in an explicit `scenePath` using `str_to_var()`. |
 | `summer_set_resource_property` | Set a nested resource property in an explicit `scenePath`. |
 | `summer_inspect_resource` | Read a resource FILE (`path`): a Mesh `.res` gives AABB, surfaces (primitive, vertex/index counts, attributes, triangles, material) and materials; a `.tscn`/`.glb` gives its nodes and meshes; anything else its non-default editor properties. Or a resource a node of the active scene holds (`nodePath` + `property`). |
 | `summer_connect_signal` | Wire a signal between nodes in the explicit `scenePath` (a `.tscn`). Connects with `CONNECT_PERSIST` through a RunSceneScript probe (the engine's ConnectSignal op never saves the connection), saves, and returns `persisted:true` / `verified:true` only when the saved file holds the `[connection]` line; otherwise `failure_reason: not_persisted`. |
@@ -65,7 +65,7 @@
 
 | Tool | Use |
 |---|---|
-| `summer_import_from_url` | Download a `.glb`/`.png`/etc and run Godot's full import pipeline. |
+| `summer_import_from_url` | Download a `.glb`/`.png`/etc and run the engine's full import pipeline. |
 | `summer_import_from_url_batch` | Same, batched (single filesystem scan). |
 
 ### Scene scripting (3)
@@ -84,7 +84,7 @@
 
 ### Editor UI control (4)
 
-Preview — the `Ui*` engine ops ship with a follow-up engine build; until then these return `engine_lacks_op`. Semantic first: scene work never goes through the editor UI (use the scene, scripting, and perception tools). UI ops are for editor-workflow steps a human does with the mouse — open Project Settings, switch the main screen, clear a blocking dialog, read a dock. Ladder: dedicated tool → named action → tree + activate → screenshot (pixels last, never for coordinates). Quit / project-reload / delete-without-confirm actions are denied by the engine. The `driving-the-editor-ui` skill carries the patterns.
+Preview: needs Summer Engine 0.5.66 or newer; older engines return `engine_lacks_op`. Scene work never goes through the editor UI (use the scene, scripting, and perception tools). UI ops are for editor-workflow steps a human does with the mouse — open Project Settings, switch the main screen, clear a blocking dialog, read a dock. Ladder: dedicated tool → named action → tree + activate → screenshot (pixels last, never for coordinates). Quit / project-reload / delete-without-confirm actions are denied by the engine. The `driving-the-editor-ui` skill carries the patterns.
 
 | Tool | Use |
 |---|---|
@@ -190,7 +190,7 @@ Preview. One fast, read-only call that walks every node of a 3D scene and lists
 
 | Tool | Use |
 |---|---|
-| `summer_create_debug_report` | Create a support-ready Markdown report for `/summer debug`. |
+| `summer_create_debug_report` | Create a support-ready Markdown report (same as `summer debug`). |
 | `summer_get_diagnostics` | Aggregate error/warning summary. Call after every change. |
 | `summer_get_console` | Engine output panel. |
 | `summer_clear_console` | Clear before a fresh play, so post-run output is clean. |
@@ -206,9 +206,9 @@ Preview. One fast, read-only call that walks every node of a 3D scene and lists
 | `summer_list_my_assets` | List/search the signed-in user's generated and uploaded assets. Empty query lists recent assets. |
 | `summer_get_asset` | Fetch one exact asset by ID with file URL, download URL, viewer URL, metadata, license, and visibility. |
 | `summer_get_asset_download_url` | Get the primary or thumbnail download URL for a specific asset. Stable shape for future signed URLs. |
-| `summer_import_asset` | Search, choose the top match, download, run Godot import, and optionally instantiate 3D models. |
+| `summer_import_asset` | Search, choose the top match, download, run the engine import, and optionally instantiate 3D models. |
 | `summer_import_asset_by_id` | Import one exact Summer asset ID. Use after generation jobs or when the user selects a specific asset. |
-| `summer_import_hdri` | Search Poly Haven's CC0 HDRIs (public API, no Summer login), import the `.hdr`/`.exr` into `res://sky/`, and get the exact `summer_run_script` snippet that wires it as the WorldEnvironment sky. The cheapest whole-scene lighting upgrade. |
+| `summer_import_hdri` | Search Poly Haven's CC0 HDRIs (public API, no Summer login), import the `.hdr`/`.exr` into `res://sky/`, and get the exact `summer_run_script` snippet that wires it as the WorldEnvironment sky. |
 | `summer_slice_asset_sheet` | Detect and crop every distinct asset from a generated sheet image into named individual assets (works without the engine; import the results afterwards). |
 
 ### Asset generation (5 — metered)
@@ -228,7 +228,7 @@ Preview. One fast, read-only call that walks every node of a 3D scene and lists
 | `summer_check_job` | Poll a generation job. |
 | `summer_batch` | Run multiple ops as a transaction. `InstantiateScene` ops may carry `position` / `rotation_degrees` / `scale` / `transform`; `receipt: "summary"` returns counts, failures with op index and created paths under 5 KB. A `ReparentNode` keeps the moved node's scene-owned children and grandchildren (the engine op drops them from the saved file) and is verified from the saved `.tscn` (`persisted:true` / `verified:true`, else `failure_reason: not_persisted`); a raw `ConnectSignal` is refused — use `summer_connect_signal`. `scenePersistence.saved` only means the SaveScene ran. |
 
-### Meta (4)
+### Meta (5)
 
 | Tool | Use |
 |---|---|
@@ -236,6 +236,7 @@ Preview. One fast, read-only call that walks every node of a 3D scene and lists
 | `summer_get_studio_workflow` | Discover Summer Studio's guided workflow recipes (starter prompts, ordered steps, required tools) for a goal. |
 | `summer_get_project_context` | Project, scene, and `.summer` memory summary — call at start of session. Binds the session to the open project and surfaces a `capabilitySkewWarning` when the engine build and CLI have drifted; tools whose op the engine provably lacks return a structured `engine_lacks_op` result instead of running. Compact by default (a few KB: `sceneSummary`, scalar `health` with capability counts); `include:['scene_tree','capabilities','settings']` adds the heavy blocks, `omitted` says how. |
 | `summer_get_agent_playbook` | Daily operating contract (observe-first loop, content routing, invariants, verification ritual) — call at start of session. Also served natively as the `summer_agent_playbook` MCP prompt. |
+| `summer_get_board` | Read the person's approved planning board (look, characters, place, storyboard, picks), with the look and picked cards as images to compare screenshots against. Needs the project id from the build brief; works without the engine. |
 
 ### Creator platform (7)
 
@@ -245,7 +246,7 @@ Preview. One fast, read-only call that walks every node of a 3D scene and lists
 | `summer_export_templates` | `list` or `install` export templates from Summer's CDN (`downloads.summer.games/engine-templates/<summerVersion>/manifest.json`) into the engine's user template folder (`<data>/Godot/export_templates/<FULL_CONFIG>/`), sha256-checked. Only download exports need them; store bundles need none. `summerVersion` is read on macOS, passed elsewhere. |
 | `summer_publish_build` | Upload that `.zip` to the creator's game through Studio's store upload: confirm-gated preview first, then declare, part upload from disk, seal, wait for the Build, name its client pack; `publish:true` also approves it. Needs `summer login --store`; a retry with the same file and version continues the same upload. |
 | `summer_creator_publish` | **Deprecated** (use the two tools above). Compute the exact `.pck` digest and size, require user confirmation, then run versioned prepare → write-once upload → finalize. The server independently verifies `publish` scope, ownership, bytes, and review state. |
-| `summer_creator_releases` | List real creator-owned releases from `summer.creator.v1`, with opaque cursor pagination. |
+| `summer_creator_releases` | **Deprecated.** Lists releases on the legacy creator API. For summer.games use `summer_store_releases` (hosted, mounted after `summer login --store`). |
 | `summer_creator_config` | Read or confirm updates to the shared non-secret `~/.summer/config.json`. It never accepts or returns tokens. |
 | `summer_capture_gameplay` | Real gameplay frames without a running editor: starts the game (main scene or `scene`) in the engine's offscreen verify instance (`--summer-verify`, real renderer, window parked offscreen, no focus) at `resolution` (default `1920x1080`), waits `waitSeconds`, saves `frames` PNGs (HUD included) to `<project>/.summer/captures/<time>/`. Imports the project first when `.godot/` is missing. Returns each path with its real width and height; warns when the stretch settings render another size. For store screenshots. |
 
@@ -288,7 +289,7 @@ Every asset-generation skill should follow this loop:
 2. `summer_generate_image` / `summer_generate_3d` / `summer_generate_audio` — metered creation.
 3. `summer_check_job` if the generation was async.
 4. `summer_get_asset` — resolve the returned `assetId`, `rigAssetId`, or `animationAssetId`.
-5. `summer_import_asset_by_id` — import the exact result into Godot's pipeline.
+5. `summer_import_asset_by_id` — import the exact result through the engine's import pipeline.
 6. `summer_get_asset_download_url` — only when the user explicitly wants a downloadable file/link.
 
 ## summer_set_resource_property — nested properties
@@ -305,7 +306,7 @@ summer_set_resource_property(
 
 `nodePath`, `resourceProperty` and `subProperty` are all required and canonical. There is no dotted `"mesh.size"` form.
 
-**Inline `sub_resource` targets work.** An earlier revision of this file claimed the op silently fails on an inline sub-resource and told you to save the resource as a standalone `.tres` first. That was wrong, and it propagated into nine skills. The implementation reads `node->get(resourceProperty)` and sets the sub-property on whatever comes back (`modules/1summer_engine/editor/ops/scene_ops.cpp:1273-1400`) — there is no inline-versus-external branch anywhere in it. The canonical example in the shipped `summer_batch` description does exactly this against an inline mesh.
+**Inline `sub_resource` targets work.** You do not need to save the resource as a standalone `.tres` first: the op reads the node's property and sets the sub-property on whatever resource it holds. The canonical example in the shipped `summer_batch` description does exactly this against an inline mesh.
 
 Structural failures are explicit:
 

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

@@ -7,7 +7,7 @@
 ## Who owns what
 
 - **Web rows** come from summerengine.com's own route catalog (`/agent-routes.json`, published from the web repo's `src/lib/navigation/routes.ts`). The toolkit vendors a snapshot (`assets/navigation/web-routes.json`, refreshed with `npm run sync:web-routes`); it does not invent pages.
-- **Editor rows** are ids of Summer Engine's one navigation table (`navigate_ops.cpp`, op `Navigate`). The running engine advertises which ids it can open in `/api/health` `capabilities.navigation`; `summer open --list` shows availability from the connected engine. Engines that predate the `Navigate` op can still serve the rows with a legacy op (last-but-one column); every other row answers `engine_lacks_op` with an update hint.
+- **Editor rows** are ids of Summer Engine's one navigation table (the `Navigate` op). The running engine advertises which ids it can open in `/api/health` `capabilities.navigation`; `summer open --list` shows availability from the connected engine. Engines that predate the `Navigate` op can still serve the rows with a legacy op (last-but-one column); every other row answers `engine_lacks_op` with an update hint.
 
 ## How to read a row
 

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

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

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

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

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

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

package/library/skills/README.md

@@ -56,7 +56,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 | [*fabricating-assets*](./fabricating-assets/SKILL.md) (preview) | Fabricate meshes with a bpy script in the user's own Blender (summer_fabricate_3d) — kits with exact dimensions, VFX meshes, post-processing generated models. | assets, scripting, agent-workflow |
 | [organic-model](./organic-model/SKILL.md) | Generate organic 3D shapes — trees, rocks, mushrooms, coral, plants, vines, crystals — where AI artifacts read as natural irregularity. | assets |
 | [prop-model](./prop-model/SKILL.md) ★ | Generate a single static 3D prop — sword, barrel, chest, lantern, throne, statue — one isolated object, no rigging, wired as a MeshInstance3D. | assets |
-| [vehicle-model](./vehicle-model/SKILL.md) | Generate a hard-surface vehicle — car, spaceship, mech, boat, tank — static mesh with optional detail-texture pass, wired as Vehicle3D or MeshInstance3D. | assets |
+| [vehicle-model](./vehicle-model/SKILL.md) | Generate a hard-surface vehicle — car, spaceship, mech, boat, tank — static mesh with optional detail-texture pass, wired as VehicleBody3D or MeshInstance3D. | assets |
 
 ## agent-workflow
 
@@ -106,7 +106,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 |---|---|---|
 | [asset-strategy](./asset-strategy/SKILL.md) ★ | Route any 'I need a [thing]' asset request to the right specialist skill — disambiguates 2D / 3D / audio / video / VFX / animation pipelines. | pipeline |
 | [*lumera-single-image-scene-reconstruction*](./lumera-single-image-scene-reconstruction/SKILL.md) (preview) | Lumera-style single image to editable 3D scene — VLM-parsed object boxes and parametric lights, per-object meshes, HDR probe, .tscn assembly, refinement loop. | pipeline, 3d, scenes |
-| [*skintokens-auto-rigging*](./skintokens-auto-rigging/SKILL.md) (preview) | Offline auto-rigging with skin-tokens.cpp (GGML SkinTokens/TokenRig port) — skeleton and skin weights from a static GLB mesh on CPU/Vulkan, into Godot 4. | pipeline, 3d, animation |
+| [*skintokens-auto-rigging*](./skintokens-auto-rigging/SKILL.md) (preview) | Offline auto-rigging with skin-tokens.cpp (GGML SkinTokens/TokenRig port) — skeleton and skin weights from a static GLB mesh on CPU/Vulkan, into Summer Engine. | pipeline, 3d, animation |
 
 ## audio
 
@@ -194,7 +194,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 
 | skill | when to use | also |
 |---|---|---|
-| [tune-performance](./tune-performance/SKILL.md) ★ | Profile a slow game via summer_get_diagnostics, identify rendering/physics/scripting hotspots, propose fixes with before/after metric expectations. | debug |
+| [tune-performance](./tune-performance/SKILL.md) ★ | Profile a slow game with a measurement probe, identify rendering/physics/scripting hotspots, propose fixes with before/after metric expectations. | debug |
 
 ## rendering
 
@@ -203,8 +203,8 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 | [3d-lighting](./3d-lighting/SKILL.md) ★ | Set up 3D scene lighting — DirectionalLight3D vs Omni vs Spot, WorldEnvironment, sky, shadow tuning, ambient — per current Summer conventions. | lighting |
 | [art-direction](./art-direction/SKILL.md) ★ | Define the game's visual style — references, palette, mood, lighting plan, post-processing, do/don't list — output as an art bible at .summer/art-bible.md. | lighting |
 | [*compatibility-renderer-traps*](./compatibility-renderer-traps/SKILL.md) ★ (preview) | Make a Forward+ Summer game also look right on the Compatibility renderer: instance-uniform budget, black MultiMesh colors, sRGB vertex colors. | performance |
-| [*psx-retro-rendering*](./psx-retro-rendering/SKILL.md) (preview) | Hardware-informed PlayStation 1 rendering in Godot 4 — low-res output, RGB5 and exact dither, affine textures, vertex snapping, blend modes, fog; limits named. | 3d |
-| [*realtime-wet-surfaces*](./realtime-wet-surfaces/SKILL.md) (preview) | Real-time wetness on existing Godot 4 materials without losing their values — value-copying wet shader, geometry-driven wet mask, instance-uniform wet amount. | vfx |
+| [*psx-retro-rendering*](./psx-retro-rendering/SKILL.md) (preview) | PlayStation 1 rendering in Summer Engine — low-res output, RGB5 and exact dither, affine textures, vertex snapping, blend modes, fog; limits named. | 3d |
+| [*realtime-wet-surfaces*](./realtime-wet-surfaces/SKILL.md) (preview) | Real-time wetness on existing materials without losing their values — value-copying wet shader, geometry-driven wet mask, instance-uniform wet amount. | vfx |
 | [*web-compatibility-look*](./web-compatibility-look/SKILL.md) ★ (preview) | Make a web or browser game look high-end in the Compatibility renderer (WebGL 2): what works, what to avoid, 2D and 3D recipes, web performance. | 2d, 3d |
 
 ## runtime

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

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

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

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

package/library/skills/ambient-bed/SKILL.md

@@ -13,9 +13,9 @@ paths: ["audio/ambient/**", "**/*.tscn", "**/*.import"]
 
 ## Overview
 
-An ambient bed is the *air* of a place. Forest at dawn, dungeon corridor, spaceship hum, market street, ocean cave. It plays at low energy under everything else — never melodic, never drawing attention, but its absence is immediately felt. Players don't notice an ambient bed; they notice the silence when you forget one.
+An ambient bed is the *air* of a place. Forest at dawn, dungeon corridor, spaceship hum, market street, ocean cave. It plays at low energy under everything else and is never melodic. Players rarely notice a bed, but they notice the silence when a level has none.
 
-This is **not** music. Use `summer_generate_audio({capability: 'sound_effects'})`, not `{capability: 'music'}`. SFX renders textures; Music renders melody. You want texture.
+This is **not** music. Use `summer_generate_audio({capability: 'sound_effects'})`, not `{capability: 'music'}`: the SFX model renders texture, the music model renders melody.
 
 Generated at 15–22 seconds (the SFX duration ceiling) and looped with a Summer
 Engine import loop point and optional crossfade.
@@ -28,9 +28,9 @@ Engine import loop point and optional crossfade.
 
 ## When NOT to use
 
-- Short event SFX (<5s) → `audio/sound-effect`.
-- Music with melody / chord progression → `audio/music-track`.
-- Voice barks → `audio/voice-line`.
+- Short event SFX (<5s) → `sound-effect`.
+- Music with melody / chord progression → `music-track`.
+- Voice barks → `voice-line`.
 
 ## Steps
 
@@ -50,7 +50,7 @@ Ask if it's not pinned by context:
 
 ### 3. Build the prompt — environment + time + weather + 2–3 sources + density + duration
 
-ElevenLabs SFX renders ambient textures well when the prompt names sources, not vibes.
+The SFX model renders ambient texture well when the prompt names sound sources, not moods.
 
 Prompts that work:
 
@@ -117,9 +117,7 @@ If the model returns a clip with a loud event near the start or end (a sudden bi
 
 ### 6. Mark the seamless loop in Summer Engine's Import dock
 
-This step is what makes the bed sound like a place rather than a 22-second sample.
-
-WAV and MP3 use **different importers with different option names** — do not copy the MP3 block from `audio/music-track` here. The WAV importer has no `loop` / `loop_offset`; it has an `edit/loop_mode` enum plus sample-frame bounds.
+WAV and MP3 use **different importers with different option names** — do not copy the MP3 block from `music-track` here. The WAV importer has no `loop` / `loop_offset`; it has an `edit/loop_mode` enum plus sample-frame bounds.
 
 In Summer Engine, select the `.wav` and open the Import dock:
 
@@ -144,7 +142,7 @@ After changing, click `Reimport`.
 
 ### 7. Crossfade-loop pattern for seamlessness
 
-ElevenLabs SFX returns are not gapless. Even with `loop = true`, you'll hear a tiny click on the loop point. Fix it with a two-player crossfade in code:
+Generated SFX clips are not gapless. Even with the loop mode set, you will often hear a small click at the loop point. Fix it with a two-player crossfade in code:
 
 ```gdscript
 # scripts/audio/AmbientBed.gd
@@ -278,7 +276,7 @@ Print the SFX prompt and the import dock settings. User runs via the Summer dash
 
 ## See also
 
-- `audio/audio-direction` — defines the Ambient layer class
-- `audio/sound-effect` — short event SFX layered over the bed
-- `audio/music-track` — melodic music layered over the bed
-- `audio/adaptive-music` — state-driven crossfades use the same pattern
+- `audio-direction` — defines the Ambient layer class
+- `sound-effect` — short event SFX layered over the bed
+- `music-track` — melodic music layered over the bed
+- `adaptive-music` — state-driven crossfades use the same pattern

package/library/skills/animated-loop/SKILL.md

@@ -11,11 +11,11 @@ paths: ["assets/video/**", "menus/**", "ui/**"]
 
 # animated-loop — 5 Second Seamless Background Loop
 
-A loop is the only video format that has to *not have* a beginning or end. The viewer sees it on the title screen for 30 seconds; if the seam between loop iterations is visible, the whole thing reads as broken. This skill exists to force the constraints that make seams invisible: take the shortest duration available, keep the motion ambient (no narrative, no big camera moves), use the cheap fast model (`ltx`), and prompt for a composition where the first and last frames are functionally identical.
+A loop is the only video format that has to *not have* a beginning or end. The viewer sees it on the title screen for 30 seconds; if the seam between loop iterations is visible, the whole thing reads as broken. This skill exists to force the constraints that make seams invisible: take the shortest duration available, keep the motion ambient (no narrative, no big camera moves), use the fast model (`ltx`), and prompt for a composition where the first and last frames are functionally identical.
 
 **Duration is not a dial here.** `summer_generate_video` accepts only `duration=5` or `duration=10`; the server coerces every other value to 5. So "drop to 3s to hide the seam" is not an option — 5s is the floor, and the seam has to be won in the prompt and the reference frame instead.
 
-If the user wants a 5s punchy marketing shot, that's `video/trailer-shot`. If they want a 10s narrative cutscene, that's `video/cinematic-cutscene`. This skill is the one for video that has to *disappear* — atmosphere behind a logo, mood behind a menu, ambience behind a splash card.
+If the user wants a 5s punchy marketing shot, that's `trailer-shot`. If they want a 10s narrative cutscene, that's `cinematic-cutscene`. This skill is the one for video that has to *disappear* — atmosphere behind a logo, mood behind a menu, ambience behind a splash card.
 
 ## When to use
 
@@ -28,9 +28,9 @@ If the user wants a 5s punchy marketing shot, that's `video/trailer-shot`. If th
 
 ## When NOT to use
 
-- Marketing shot for a trailer (5-10s with punch) — `video/trailer-shot`.
-- Narrative cutscene with a beginning and end — `video/cinematic-cutscene`.
-- Static splash image — generate with `2d-assets/concept-art` and use a `TextureRect`. A still is cheaper, lighter, and never seams.
+- Marketing shot for a trailer (5-10s with punch) — `trailer-shot`.
+- Narrative cutscene with a beginning and end — `cinematic-cutscene`.
+- Static splash image — generate with `concept-art` and use a `TextureRect`. A still is cheaper, lighter, and never seams.
 - UI element animation (icons, button states) — those are GDScript `Tween` or sprite sheets, not video.
 - A 10-second shot you want to "loop". That seam will be visible. Either accept a hard cut every 10s (ugly) or generate a 5s clip designed to loop.
 
@@ -40,21 +40,21 @@ If the user wants a 5s punchy marketing shot, that's `video/trailer-shot`. If th
 
 > Quick check — this loop will play on a screen the user might stare at for 30+ seconds. That means the loop point must be invisible. I'll take the 5s minimum and prompt for ambient motion (drift, flicker, shimmer) rather than a narrative beat. OK?
 
-If the user wants narrative motion (a character walking, a door opening), this is the wrong skill — route to `video/cinematic-cutscene`.
+If the user wants narrative motion (a character walking, a door opening), this is the wrong skill — route to `cinematic-cutscene`.
 
 ### 2. Pick the model — `ltx` first, always
 
-For loops, `ltx` is correct ~95% of the time. It's $0.10, ~30s, and the constraints (short duration, ambient motion) are exactly the ones `ltx` handles best. Premium models add cost without adding loop quality.
+For loops, `ltx` is almost always right. It takes ~30s, and short ambient motion is what it handles best. The premium models cost more credits and do not loop better.
 
 This skill always passes `imageUrl` (step 3), which puts every call on the image-to-video route — and that route accepts only `ltx`, `kling`, and `minimax`. `kling-turbo` and `veo3` are text-to-video only; pairing either with an `imageUrl` is a 400 `invalid_model`, not a silent downgrade.
 
-| Model | i2v? | Cost | Speed | When |
-|---|---|---|---|---|
-| `ltx` | yes | $0.10 | ~30s | Default. Use this. |
-| `kling` | yes | $0.50 | 2-4 min | Only if the loop is the centerpiece of a premium splash and quality is visibly lacking on `ltx` |
-| `minimax` | yes | $0.25 | 2-3 min | Stylized / anime aesthetic loops |
-| `kling-turbo` | **no** | $0.30 | 1-2 min | Not reachable from this skill — text-to-video only |
-| `veo3` | **no** | $1.00 | 3-5 min | Not reachable from this skill, and pointless for ambient loops anyway |
+| Model | i2v? | Speed | When |
+|---|---|---|---|
+| `ltx` | yes | ~30s | Default. Use this. |
+| `kling` | yes | 2-4 min | Only if the loop is the centerpiece of a premium splash and quality is visibly lacking on `ltx` |
+| `minimax` | yes | 2-3 min | Stylized / anime aesthetic loops |
+| `kling-turbo` | **no** | 1-2 min | Not reachable from this skill — text-to-video only |
+| `veo3` | **no** | 3-5 min | Not reachable from this skill, and pointless for ambient loops anyway |
 
 ### 3. Lock the look with a reference still
 
@@ -69,7 +69,7 @@ summer_generate_image(
 
 `summer_generate_image` has no size or aspect argument — `options.image_size` is dropped without an error and every MCP image comes back at the server's 1:1 default. Ask for the framing in the prompt, or generate the reference in the Summer dashboard (which exposes aspect ratio) and pass its URL.
 
-This matters more than usual here: on the image-to-video route `aspectRatio` is **not applied at all** — the clip inherits the reference image's framing. So a vertical mobile splash needs a genuinely 9:16 reference image, and setting `aspectRatio="9:16"` on the video call does nothing.
+On the image-to-video route `aspectRatio` is **not applied at all** — the clip inherits the reference image's framing. So a vertical mobile splash needs a 9:16 reference image, and setting `aspectRatio="9:16"` on the video call does nothing.
 
 ### 4. Prompt for loopable motion only
 
@@ -89,7 +89,7 @@ summer_generate_video(
 )
 ```
 
-The phrase **"looping, seamless"** in the prompt biases the model toward stable first/last frames. `options.negative_prompt` is one of the few provider keys that does pass through on the video route (`prompt`, `image_url`, `num_frames`, `duration`, `resolution`, and `model` are stripped; everything else is forwarded), so the negative genuinely rules out narrative drift here — unlike on `summer_generate_image`, where no such argument exists.
+The phrase **"looping, seamless"** in the prompt biases the model toward stable first/last frames. `options.negative_prompt` is one of the few provider keys that does pass through on the video route (`prompt`, `image_url`, `num_frames`, `duration`, `resolution`, and `model` are stripped; everything else is forwarded), so the negative prompt does rule out narrative drift here — unlike on `summer_generate_image`, where no such argument exists.
 
 `aspectRatio` is omitted deliberately: it is applied on the text-to-video path only, and this call passes `imageUrl`.
 
@@ -115,7 +115,7 @@ VideoStream exts: ["ogv", "tres", "res"]
 ERROR: No loader found for resource: res://clip.mp4 (expected type: unknown)
 ```
 
-`summer_import_from_url` downloads the bytes, runs Godot's import pipeline, and *fails the import* if the file never becomes a loadable resource — so importing the `.mp4` does not quietly half-work, it is rejected and rolled back. Convert first:
+`summer_import_from_url` downloads the bytes, runs the engine's import pipeline, and *fails the import* if the file never becomes a loadable resource — so importing the `.mp4` does not quietly half-work, it is rejected and rolled back. Convert first:
 
 ```
 ffmpeg -i title_screen_bg.mp4 -c:v libtheora -q:v 8 -an title_screen_bg.ogv
@@ -137,7 +137,7 @@ summer_set_prop(scenePath="res://ui/title_screen.tscn", path="./BackgroundLoop",
 summer_save_scene(scenePath="res://ui/title_screen.tscn")
 ```
 
-Anchors preset 15 is "full rect" — the loop fills the menu. Place the logo and menu buttons as children *above* the `VideoStreamPlayer` in the tree (Godot draws siblings in tree order; later siblings render on top).
+Anchors preset 15 is "full rect" — the loop fills the menu. Place the logo and menu buttons as children *above* the `VideoStreamPlayer` in the tree (Controls draw in tree order; later siblings render on top).
 
 ### 7. Mute the audio track
 
@@ -147,22 +147,22 @@ Loops should never have a baked audio track that loops with them — the audio s
 summer_set_prop(scenePath="res://ui/title_screen.tscn", path="./BackgroundLoop", key="volume_db", value=-80)
 ```
 
-Score the menu separately with `audio/music-track`.
+Score the menu separately with `music-track`.
 
 ## Reference card — prompts that work
 
 Pattern: `<subject> + <ambient loopable motion> + <constant lighting> + "looping, seamless" + <stylistic anchor>`. Keep under 40 words. Always pair with `imageUrl`.
 
-| Goal | Model | Prompt | Cost | Duration |
-|---|---|---|---|---|
-| Title menu — fog forest | `ltx` | `dense pine forest in low fog, fog drifting slowly between trunks, soft moonlight, ambient particles rising, looping, seamless, cinematic painterly` | $0.10 | 5s |
-| Title menu — dungeon torch | `ltx` | `stone dungeon corridor lit by a single torch, flame flickering steadily, dust motes drifting in the light cone, looping, seamless` | $0.10 | 5s |
-| Splash — embers / sky | `ltx` | `dusk sky with slow drifting embers rising upward across frame, deep blue gradient, looping, seamless, cinematic` | $0.10 | 5s |
-| Logo backdrop — magic runes | `ltx` | `dark surface with glowing blue runes pulsing softly in slow rhythm, faint shimmer, no narrative motion, looping, seamless` | $0.10 | 5s |
-| Menu — underwater | `ltx` | `underwater scene with caustic light dancing on a sandy floor, slow drifting bubbles, gentle current sway on kelp, looping, seamless` | $0.10 | 5s |
-| Pause screen — slow rain | `ltx` | `window pane with continuous gentle rain drops, blurred warm interior glow behind, looping, seamless, ambient` | $0.10 | 5s |
-| Title — anime sky | `minimax` | `anime style cumulus clouds drifting slowly across a pastel sunset sky, soft, painterly, looping, seamless, Ghibli` | $0.25 | 5s |
-| Premium splash centerpiece | `kling` | `dragon silhouette breathing in profile against a vast sunset sky, only the chest rising and falling and clouds drifting, looping, seamless` | $0.50 | 5s |
+| Goal | Model | Prompt | Duration |
+|---|---|---|---|
+| Title menu — fog forest | `ltx` | `dense pine forest in low fog, fog drifting slowly between trunks, soft moonlight, ambient particles rising, looping, seamless, cinematic painterly` | 5s |
+| Title menu — dungeon torch | `ltx` | `stone dungeon corridor lit by a single torch, flame flickering steadily, dust motes drifting in the light cone, looping, seamless` | 5s |
+| Splash — embers / sky | `ltx` | `dusk sky with slow drifting embers rising upward across frame, deep blue gradient, looping, seamless, cinematic` | 5s |
+| Logo backdrop — magic runes | `ltx` | `dark surface with glowing blue runes pulsing softly in slow rhythm, faint shimmer, no narrative motion, looping, seamless` | 5s |
+| Menu — underwater | `ltx` | `underwater scene with caustic light dancing on a sandy floor, slow drifting bubbles, gentle current sway on kelp, looping, seamless` | 5s |
+| Pause screen — slow rain | `ltx` | `window pane with continuous gentle rain drops, blurred warm interior glow behind, looping, seamless, ambient` | 5s |
+| Title — anime sky | `minimax` | `anime style cumulus clouds drifting slowly across a pastel sunset sky, soft, painterly, looping, seamless, Ghibli` | 5s |
+| Premium splash centerpiece | `kling` | `dragon silhouette breathing in profile against a vast sunset sky, only the chest rising and falling and clouds drifting, looping, seamless` | 5s |
 
 ### Bad prompts and why
 
@@ -178,7 +178,7 @@ Pattern: `<subject> + <ambient loopable motion> + <constant lighting> + "looping
 
 - **Asking the model for a 10s loop.** Past ~6s, identity drifts and the seam shows. `duration=5` is both the floor and the right answer; 10 is the only other value the API accepts.
 - **Treating `summer_generate_video` as synchronous.** It returns `{ queued: true, jobId }` and no URL. Poll `summer_check_job` before claiming a clip exists.
-- **Spending `kling` money on a loop.** `ltx` is the right call ~95% of the time. The constraints favor the cheap model.
+- **Using `kling` for a loop.** `ltx` is almost always right; short ambient motion is what it does best.
 - **Prompting narrative motion.** "Hero draws sword" doesn't loop. Use ambient verbs.
 - **Forgetting `loop=true` on the `VideoStreamPlayer`.** The clip will play once and freeze on the last frame.
 - **Forgetting to mute baked audio.** If audio is on, the loop point becomes audible even if it's invisible.
@@ -188,17 +188,17 @@ Pattern: `<subject> + <ambient loopable motion> + <constant lighting> + "looping
 ## Edge cases
 
 - **Splash loop must be tiny in build size.** Loops compress aggressively because of low motion. Target ≤2MB by exporting at 720p, low bitrate, in DaVinci. Studio's import doesn't re-encode by default.
-- **Mobile portrait splash.** The reference image must genuinely be portrait — `aspectRatio` is ignored on the image-to-video path, and MCP image generation is square-only, so make the reference in the Summer dashboard or crop it. Anchors preset 15 still works.
+- **Mobile portrait splash.** The reference image must be portrait — `aspectRatio` is ignored on the image-to-video path, and MCP image generation is square-only, so make the reference in the Summer dashboard or crop it. Anchors preset 15 still works.
 - **Loop must sync to a music beat.** The video model doesn't know your BPM. Generate at the duration matching one bar at the menu music tempo (e.g. 120 BPM × 4 beats = 2s, or 8 beats = 4s) and confirm visually.
 - **Loop is behind translucent UI.** Generate with extra contrast headroom — the model tends toward mid-grey, and translucent UI on mid-grey reads muddy. Push for `high contrast cinematic` in the prompt.
 - **Loop seam still visible after 3 regens.** Set up two `VideoStreamPlayer` siblings and crossfade between them with a `Tween` on a 0.5s overlap. Costs an extra GPU decode but hides the seam.
 
 ## Fallback (no MCP)
 
-If the Studio MCP server isn't running, route the user to the Studio web dashboard:
+If the MCP server isn't running, route the user to the Summer dashboard:
 
 1. Image tab → generate the reference still (the loop's "neutral frame").
-2. Video tab → image-to-video with `ltx`, duration 4s, aspect ratio per target.
+2. Video tab → image-to-video with `ltx`, duration 5s, aspect ratio per target.
 3. Prompt with the loopable-motion vocabulary above and `"looping, seamless"`.
 4. Download the result, transcode to `.ogv` if needed, place under `assets/video/loops/`.
 
@@ -209,16 +209,16 @@ Print the exact prompt + model + duration + aspect ratio so the user can paste i
 Once the loop is wired:
 
 > Loop `title_screen_bg` is wired to `TitleScreen/BackgroundLoop` with autoplay + loop. Next:
-> - Score the menu with `audio/music-track` — a quiet ambient bed scored to the loop's mood.
-> - For the logo and menu UI on top, hand off to `2d-assets/ui-graphics`.
-> - If the user wants a punchy 5s shot for the trailer using the same look, hand off to `video/trailer-shot` (reuse the reference image).
-> - If the user wants a narrative intro that plays *before* the title loops, hand off to `video/cinematic-cutscene`.
+> - Score the menu with `music-track` — a quiet ambient bed scored to the loop's mood.
+> - For the logo and menu UI on top, hand off to `ui-graphics`.
+> - If the user wants a punchy 5s shot for the trailer using the same look, hand off to `trailer-shot` (reuse the reference image).
+> - If the user wants a narrative intro that plays *before* the title loops, hand off to `cinematic-cutscene`.
 
 ## See also
 
-- `video/trailer-shot` — punchy marketing footage.
-- `video/cinematic-cutscene` — narrative cutscenes with dialogue.
-- `audio/music-track` — score the menu.
-- `2d-assets/ui-graphics` — logo, menu buttons, HUD that sits over the loop.
-- `2d-assets/concept-art` — produce the reference still that anchors the loop.
+- `trailer-shot` — punchy marketing footage.
+- `cinematic-cutscene` — narrative cutscenes with dialogue.
+- `music-track` — score the menu.
+- `ui-graphics` — logo, menu buttons, HUD that sits over the loop.
+- `concept-art` — produce the reference still that anchors the loop.
 - `../../references/mcp-tools-reference/mcp-tools-reference.md` — `summer_generate_video` parameter schema and error codes.

package/library/skills/animation-tree/SKILL.md

@@ -11,18 +11,18 @@ paths: ["**/*.gd", "**/*.tscn", "**/*.tres"]
 
 # AnimationTree — Wire Clips Into Behavior
 
-Generation gives you clips. The AnimationTree gives the character life. This skill is **not generative** — no FAL, no MCP AI calls. It composes existing clips on an `AnimationPlayer` into an `AnimationTree` with a `StateMachine` for distinct states (idle / attack / hit / dead) and `BlendSpace` nodes for continuous parameters (walk-run blend by speed). Done right, the character moves like a shipped game; done wrong, you get T-poses, snapping, or animations that "eat" each other.
+This skill generates nothing. It composes existing clips on an `AnimationPlayer` into an `AnimationTree` with a `StateMachine` for distinct states (idle / attack / hit / dead) and `BlendSpace` nodes for continuous parameters (walk-run blend by speed). Wired wrong, you get T-poses, snapping, or clips that cut each other off.
 
 The canonical Summer Engine stack:
 
 ```
 Character (CharacterBody3D)
-├── Skeleton3D (from the Meshy rig)
+├── Skeleton3D (from the rigged GLB)
 ├── AnimationPlayer            # holds the raw clips (idle, walk, run, attack_sword, ...)
 └── AnimationTree              # references AnimationPlayer, drives behavior
 ```
 
-Before adding the tree, prove direct `AnimationPlayer.play()` visibly moves the rig. Godot may import animation GLBs as `AnimationLibrary` resources or as `PackedScene`s with embedded `AnimationPlayer`s. If a copied clip appears in the list but the mesh T-poses, its tracks probably target a different root/skeleton path. Use the embedded player that came with the matching GLB, or remap/copy tracks only after confirming they target the active `Skeleton3D`. An inactive AnimationTree is also a no-op, so always set `AnimationTree.active = true`.
+Before adding the tree, prove direct `AnimationPlayer.play()` visibly moves the rig. The engine may import animation GLBs as `AnimationLibrary` resources or as `PackedScene`s with embedded `AnimationPlayer`s. If a copied clip appears in the list but the mesh T-poses, its tracks probably target a different root/skeleton path. Use the embedded player that came with the matching GLB, or remap/copy tracks only after confirming they target the active `Skeleton3D`. An inactive AnimationTree is also a no-op, so always set `AnimationTree.active = true`.
 
 ## When to use this skill
 
@@ -72,7 +72,7 @@ Before walking the CRUD steps below, check the ctx lane — one `summer_run_scri
 - **Animation-tier engines:** `ctx.anim_state_machine(character, {states: {...}, transitions: [[from, to, {blend_s: 0.2}], ...], start: "idle"})` gets-or-creates the AnimationTree, wires it to the player, builds the state machine, sets `active = true`. Unknown clip names come back as a report entry listing the player's REAL clips — never wire against guessed names. Full recipe (inspect clips/bones first, method-track events, root motion, playtest verification): `character-animation-wiring`.
 - **Any engine (raw fallback):** the same classes are fully script-bound — `AnimationNodeStateMachine.add_node(name, AnimationNodeAnimation)`, `add_transition(from, to, AnimationNodeStateMachineTransition)` (one transition resource each, `xfade_time` on it), then `tree.anim_player = tree.get_path_to(player)`, `tree.tree_root = sm`, `tree.active = true`, and `ctx.set_owner_recursive(tree)`. The raw script is quoted in `character-animation-wiring`.
 
-Note the helper's scope honestly: `anim_state_machine` builds clip states + transitions only. The canonical machine below — BlendSpace1D locomotion, OneShot attack/hit — still needs the `.tres` (or raw-script) lane for those node types. Discrete idle/walk/run backbones don't.
+Scope: `anim_state_machine` builds clip states + transitions only. The canonical machine below — BlendSpace1D locomotion, OneShot attack/hit — still needs the `.tres` (or raw-script) lane for those node types. Discrete idle/walk/run backbones don't.
 
 ## Steps via MCP
 
@@ -259,7 +259,7 @@ Then `summer_play` and watch — the goblin should idle in place, blend up to wa
 
 - **OneShot:** the action is a *temporary override* of an underlying state (attack while running, hit-react while attacking). The base keeps playing.
 - **StateMachine state:** the action is a *replacement* (dead, stunned, ragdoll). Nothing else plays.
-- Combat in 2026-feel games is almost always OneShot for attacks + StateMachine state for "dead". Don't model attacks as StateMachine states unless you need precise transition control between attack-string variants.
+- Action combat is usually OneShot for attacks + a StateMachine state for "dead". Don't model attacks as StateMachine states unless you need precise transition control between attack-string variants.
 
 ### BlendSpace1D vs BlendSpace2D
 
@@ -270,7 +270,7 @@ Then `summer_play` and watch — the goblin should idle in place, blend up to wa
 
 - Skipping AnimationTree and calling `AnimationPlayer.play("walk")` from script. Works for one clip; breaks the moment you need a crossfade.
 - Modeling every attack as a StateMachine state. The transition matrix explodes (N states × N transitions). Use one OneShot per attack and switch its inner clip via `parameters/Attack/animation`.
-- Writing the `.tres` by hand without using sub_resource IDs — Godot loses references and the inspector is unhappy. Always use `[sub_resource id="..."]` blocks.
+- Writing the `.tres` by hand without using sub_resource IDs — the engine loses the references. Always use `[sub_resource id="..."]` blocks.
 - Driving `blend_position` from raw input (`Input.get_axis(...)`). Drive from actual velocity — that way the blend matches the body's real motion, including knockback and slope-slide.
 
 ## Edge cases