summer-engine 3.3.0 → 3.4.1

package/library/skills/brainstorming/SKILL.md

@@ -22,21 +22,19 @@ Every project goes through this process. A todo list, a single-function utility,
 You MUST create a task for each of these items and complete them in order:
 
 1. **Explore project context** — check files, docs, recent commits
-3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
-4. **Propose 2-3 approaches** — with trade-offs and your recommendation
-5. **Present design** — in sections scaled to their complexity, get user approval after each section
-6. **Write design doc** — save to `.summer/specs/YYYY-MM-DD-<topic>-design.md` in the game project and commit
-7. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below)
-8. **User reviews written spec** — ask user to review the spec file before proceeding
-9. **Transition to implementation** — invoke writing-plans skill to create implementation plan
+2. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
+3. **Propose 2-3 approaches** — with trade-offs and your recommendation
+4. **Present design** — in sections scaled to their complexity, get user approval after each section
+5. **Write design doc** — save to `.summer/specs/YYYY-MM-DD-<topic>-design.md` in the game project and commit
+6. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below)
+7. **User reviews written spec** — ask user to review the spec file before proceeding
+8. **Transition to implementation** — invoke writing-plans skill to create implementation plan
 
 ## Process Flow
 
 ```dot
 digraph brainstorming {
     "Explore project context" [shape=box];
-    "Visual questions ahead?" [shape=diamond];
-    "Offer Visual Companion\n(own message, no other content)" [shape=box];
     "Ask clarifying questions" [shape=box];
     "Propose 2-3 approaches" [shape=box];
     "Present design sections" [shape=box];
@@ -46,10 +44,7 @@ digraph brainstorming {
     "User reviews spec?" [shape=diamond];
     "Invoke writing-plans skill" [shape=doublecircle];
 
-    "Explore project context" -> "Visual questions ahead?";
-    "Visual questions ahead?" -> "Offer Visual Companion\n(own message, no other content)" [label="yes"];
-    "Visual questions ahead?" -> "Ask clarifying questions" [label="no"];
-    "Offer Visual Companion\n(own message, no other content)" -> "Ask clarifying questions";
+    "Explore project context" -> "Ask clarifying questions";
     "Ask clarifying questions" -> "Propose 2-3 approaches";
     "Propose 2-3 approaches" -> "Present design sections";
     "Present design sections" -> "User approves design?";
@@ -62,7 +57,7 @@ digraph brainstorming {
 }
 ```
 
-**The terminal state is invoking writing-plans.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you invoke after brainstorming is writing-plans.
+**The terminal state is invoking writing-plans.** Do NOT invoke any implementation skill. The ONLY skill you invoke after brainstorming is writing-plans.
 
 ## The Process
 
@@ -109,7 +104,6 @@ digraph brainstorming {
 
 - Write the validated design (spec) to `.summer/specs/YYYY-MM-DD-<topic>-design.md` in the game project
   - (User preferences for spec location override this default)
-- Use elements-of-style:writing-clearly-and-concisely skill if available
 - Commit the design document to git
 
 **Spec Self-Review:**

package/library/skills/celeste-momentum-platforming/SKILL.md

@@ -16,11 +16,11 @@ confidence: extracted
 
 ## Outcome
 
-A 2D character controller for SummerEngine that reproduces the tuning architecture and forgiveness mechanics of Celeste's player movement: momentum-based running with distinct ground/air acceleration, variable-height jumping with coyote time, a multi-directional dash with cooldown and residual speed, wall interaction (jump, slide, climb with stamina), and pixel-scale corner corrections that make near-miss inputs succeed instead of fail.
+A 2D character controller for Summer Engine that reproduces the tuning architecture and forgiveness mechanics of Celeste's player movement: momentum-based running with distinct ground/air acceleration, variable-height jumping with coyote time, a multi-directional dash with cooldown and residual speed, wall interaction (jump, slide, climb with stamina), and pixel-scale corner corrections that make near-miss inputs succeed instead of fail.
 
 ## When to Use
 
-- Building a precision 2D platformer in SummerEngine where movement feel is the core gameplay.
+- Building a precision 2D platformer in Summer Engine where movement feel is the core gameplay.
 - Porting or prototyping Celeste-style mechanics (dash, wall jump, climb stamina).
 - Tuning an existing platformer controller that feels "unfair" or unresponsive — the forgiveness systems below are the primary fix.
 
@@ -28,9 +28,9 @@ Do not use for: 3D character controllers, physics-driven (RigidBody) movement, o
 
 ## Core Principle
 
-Celeste's movement is a **single controller class driven by an explicit integer state machine**, with all feel-critical numbers as a **flat compile-time constants table** at the top of the class. The retrieved source (Player.cs, 5,471 lines) defines states `Normal=0, Climb=1, Dash=2, Swim=3, Boost=4, RedDash=5, HitSquash=6, Launch=7, Pickup=8, DreamDash=9` (+ a Summit state), each with Begin/Update/End callbacks. State transitions are direct integer assignments.
+Celeste's movement is a **single controller class driven by an explicit integer state machine**, with all feel-critical numbers as a **flat compile-time constants table** at the top of the class. The released source (`Player.cs`, 5,471 lines) defines states `Normal=0, Climb=1, Dash=2, Swim=3, Boost=4, RedDash=5, HitSquash=6, Launch=7, Pickup=8, DreamDash=9` (+ a Summit state), each with Begin/Update/End callbacks. State transitions are direct integer assignments.
 
-The second principle: **forgiveness at the pixel and millisecond scale**. The code repeatedly nudges the player 2–6 pixels or grants 50–200 ms windows so that inputs which are *almost* correct still succeed. This is the source of the "tightest" feel described in the originating post.
+The second principle: **forgiveness at the pixel and millisecond scale**. The code repeatedly nudges the player 2–6 pixels or grants 50–200 ms windows so that inputs which are *almost* correct still succeed. Most of the "tight" feel comes from these windows.
 
 ## Tuning Constants (verbatim from Player.cs)
 
@@ -133,7 +133,7 @@ Celeste's units are pixels/second for speeds and pixels/second² for acceleratio
 | DuckWindMult | 0 (ducking negates wind) |
 | SpacePhysicsMult | 0.6 (low-gravity zones) |
 
-## Scene / Node Shape (Godot 4)
+## Scene / Node Shape
 
 ```
 Player (CharacterBody2D)
@@ -300,7 +300,7 @@ func _probe_wall() -> int:
     return 0
 ```
 
-The skeleton above is a structural translation for Godot; the exact per-frame update bodies from Player.cs were not fully retrievable (see evidence limitations). The constants, state IDs, and confirmed behaviors (corner correction loops, variable-jump window logic, forced wall-jump timers, stamina costs, squish safety) are extracted directly from the source.
+The skeleton above is a structural translation to GDScript, not a line-by-line port of the per-frame update bodies in `Player.cs`. The constants, state IDs, and confirmed behaviors (corner correction loops, variable-jump window logic, forced wall-jump timers, stamina costs, squish safety) are extracted directly from the source.
 
 ## Confirmed Behavioral Patterns to Replicate
 
@@ -322,7 +322,7 @@ The skeleton above is a structural translation for Godot; the exact per-frame up
 6. Implement dash with 8-way aim, cooldown, residual EndDashSpeed, and corner correction.
 7. Implement climb stamina with the three cost rates and tired threshold.
 8. Add forgiveness pass: upward corner correction on jump, dash nudges, jump-through assist, wall speed retention, squish-safety cascade.
-9. Rescale units if SummerEngine's pixels-per-meter differs from Celeste's native resolution: preserve ratios (e.g., DashSpeed ≈ 2.67× MaxRun; RunAccel ≈ 11× MaxRun).
+9. Rescale units if your game's pixels-per-meter differs from Celeste's native resolution: preserve ratios (e.g., DashSpeed ≈ 2.67× MaxRun; RunAccel ≈ 11× MaxRun).
 
 ## Tunables
 
@@ -358,9 +358,4 @@ After implementing, test each forgiveness system explicitly:
 
 ## Confidence
 
-`extracted` — All tuning values, state IDs, and confirmed behavioral patterns are taken directly from the retrieved Player.cs source. Per-state update-loop bodies from the middle of the 182 KB file were not retrievable (tool truncation); where the skeleton fills standard platformer patterns (e.g., jump-cut-on-release), this is noted as structural translation, not extracted code. Not yet verified inside SummerEngine.
-
-## Evidence
-
-- sources/web/celeste-player-cs/source.md — primary source record: constants tables, state machine, confirmed behavioral snippets, retrieval limitations.
-- sources/x/valigo-celeste-movement/source.md — originating post and primary-source identification.
+`extracted` — All tuning values, state IDs, and confirmed behavioral patterns come from Celeste's publicly released `Player.cs`. Where the skeleton fills in standard platformer patterns (for example jump-cut-on-release), it is a structural translation, not extracted code. Not yet verified inside Summer Engine.

package/library/skills/celeste-momentum-platforming/resource.yaml

@@ -9,7 +9,7 @@ use_when:
   - "my 2D platformer controller feels unfair or unresponsive"
 do_not_use_when:
   - "3D character controllers, physics-driven RigidBody movement, or games that want floaty arcade jump physics over momentum precision"
-  - "intake from the gamedev-knowledge pipeline (source-cited, pipeline-validated, not yet exercised in-engine by the Summer team) — verify results in the engine as you would any technique"
+  - "you need an in-engine verified controller — this one is source-cited but not yet exercised in Summer Engine; verify results in the engine before relying on it"
 facets:
   lifecycle:
     - build

package/library/skills/character-animation-wiring/SKILL.md

@@ -172,7 +172,7 @@ func run(ctx):
 
 That is the mechanism; a full audio-synced viseme timeline is `facial-and-lipsync`. Bone-track keyframes work the same way through `animate()` v2 — `ctx.animate(character, "Skeleton3D:Head/rotation", keys, "nod")` creates a proper bone rotation track (the helper owns the quaternion conversion; never hand-build quaternion tracks).
 
-## Step 6 — Root motion, honestly
+## Step 6 — Root motion
 
 Meshy/mocap locomotion clips translate the root bone forward (Meshy `run` moves ~5m per cycle). Two valid setups — **pick one, never both**:
 
@@ -185,7 +185,7 @@ Root motion CANNOT be judged from the editor state. Playtest it: `summer_play`,
 
 ## Raw lane — the same wiring on older engines
 
-Every class above is script-bound; `ctx.anim_state_machine` is convenience, not capability. The raw locomotion wiring, verbatim the calls that matter:
+Every class above is script-bound; `ctx.anim_state_machine` is convenience, not capability. The raw locomotion wiring:
 
 ```gdscript
 func run(ctx):

package/library/skills/character-model/SKILL.md

@@ -11,31 +11,21 @@ paths: ["assets/characters/**", "assets/models/**", "**/*.tscn", "**/*.gd"]
 
 # Character Model — T-Pose to Rigged Humanoid, Gated
 
-This is the **canonical Meshy auto-rig pipeline**. It produces a humanoid `.glb` with a Meshy-compatible skeleton that `generate-motion` can drive directly. The work is split into two paid passes with a **mandatory user-review gate between them** — the rig pass is more expensive and locks the topology, so the user must see the un-rigged preview and approve before you spend on the rig.
+This is the canonical auto-rig pipeline. It produces a humanoid `.glb` with a skeleton that `generate-motion` can drive directly. The work is two paid passes with a **mandatory user-review gate between them**: the rig pass costs more credits and locks the topology, so the user must see the un-rigged preview and approve it first.
 
 The whole flow:
 
 ```
-1. T-pose reference image    →  summer_generate_image                          (~$0.05, ~10s)
-2. Un-rigged 3D mesh         →  summer_generate_3d(image-to-3d)                (~$0.50, ~60s)
+1. T-pose reference image    →  summer_generate_image                          (~10s)
+2. Un-rigged 3D mesh         →  summer_generate_3d(image-to-3d)                (~60s)
 3. ── USER REVIEW GATE ──
-4. Rigged .glb               →  summer_generate_3d(image-to-3d, rig=true)      (~$1.00, ~90s)
+4. Rigged .glb               →  summer_generate_3d(image-to-3d, rig=true)      (~90s)
 5. Import → editor RESTART → wire as CharacterBody3D / Node3D
 6. Hand off to generate-motion for clips
 ```
 
 The animation skill (`generate-motion`) requires a rigged humanoid; a static `.glb` won't drive motion.
 
-## Web Chat / Public Orchestrator Equivalent
-
-When this skill is running inside the PublicSummerEngine chat orchestrator, use the chat-native tools directly instead of sending the user to Studio:
-
-```
-generateImage -> createCharacter -> checkGenerationStatus/meshyJobStatus -> listUserAssets readiness -> rigModel if needed -> generateAnimation -> meshyJobStatus -> importAssets -> import-character
-```
-
-Use Studio only when the user explicitly asks for visual/manual picking or when chat-side generation fails. The recovered working flow used `createCharacter`, confirmed the rig had `hasMeshyRigTask` or `animationsReady:true`, then generated `idle`, `walk`, `run`, `jump`, and `attack`, imported the rig plus child animation GLBs into `res://characters/<slug>/`, then wired playback from the imported GLB AnimationPlayers/libraries. If `generateAnimation` returns `animations_preparing`, wait, poll/list the rig asset again, and retry instead of routing to Studio. Keep this path repeatable for "animated character", "3D character with animations", "walking enemy", and similar prompts.
-
 ## When to use
 
 - "Make a knight character for the player to control."
@@ -121,11 +111,11 @@ Before paying for the rig pass, surface the un-rigged mesh:
 
 > Un-rigged knight mesh ready: `res://assets/characters/knight_unrigged.glb` (~12k tris, [preview link]).
 >
-> Next step is the **rig pass** (~$1.00, ~90s, Meshy auto-rig). It locks the topology and adds a skeleton compatible with `generate-motion`. Once you approve I'll run it.
+> Next step is the **rig pass** (uses credits, ~90s). It locks the topology and adds a skeleton compatible with `generate-motion`. Once you approve I'll run it.
 >
 > **Approve the mesh and proceed to rig?** Or regenerate the mesh first (different prompt, different polycount, different model)?
 
-If the user wants changes, loop back to step 1 or 2. Do NOT silently run the rig pass — it doubles the cost and locks the design.
+If the user wants changes, loop back to step 1 or 2. Do NOT silently run the rig pass — it spends more credits and locks the design.
 
 ### 4. Run the rig pass
 
@@ -205,17 +195,16 @@ The imported `.glb` includes its own `Skeleton3D` and `AnimationPlayer` (empty l
 
 ### 7. Hand off to animation
 
-> Knight is wired at `./World/Knight` with a Meshy-rigged skeleton. `rigAssetId` saved.
+> Knight is wired at `./World/Knight` with an auto-rigged skeleton. `rigAssetId` saved.
 >
 > Next: `generate-motion` to add idle / walk / run / attack
 > clips. Example call: `summer_generate_motion(rigAssetId: "<saved id>",
-> backend: "meshy-library", motionName: "walk")`. Custom prompt-driven motion
-> is not shipped; hand-author one-off moves in Summer Engine or import a
-> licensed clip.
+> backend: "meshy-library", motionName: "walk")`. For custom actions, use
+> `text-to-motion` (`backend: "text-to-motion"`).
 
 ## Anti-patterns
 
-- **Skipping the user-review gate.** Doubles cost, locks the design, and removes the user's chance to course-correct cheaply.
+- **Skipping the user-review gate.** Spends the rig credits, locks the design, and removes the user's chance to course-correct cheaply.
 - **Generating the mesh from a non-T-pose image.** Locomotion will look broken (inverted knees, snapped elbows). Always re-pose first.
 - **Forgetting the editor restart.** Animations will appear to bind successfully but play to a stale skeleton — the character T-poses motionless. The fix is always restart, never code.
 - **Wrapping a cinematic NPC in CharacterBody3D.** Wastes physics ticks; use Node3D.
@@ -225,7 +214,7 @@ The imported `.glb` includes its own `Skeleton3D` and `AnimationPlayer` (empty l
 
 ## Edge cases
 
-- **Multiple characters share a silhouette.** Generate the rig once, then re-skin via texture swap (cheaper than re-rigging). See `character-model` retexture flow (TBD) — for now, route to `asset-strategy`.
+- **Multiple characters share a silhouette.** Generate the rig once, then re-skin via texture swap (cheaper than re-rigging): generate a new albedo and assign it as a material override.
 - **Character has wings, tail, extra limbs.** Meshy's humanoid rig only weights the standard skeleton — extras sag. Either prompt them as static (e.g. cape held by physics in-engine) or hand-rig in Blender post-export.
 - **Child / dwarf / giant.** Generate at correct proportions in the T-pose; the rig retargets cleanly. Locomotion clips from `generate-motion` will retarget but stride length needs `playback_speed` tuning on the AnimationPlayer.
 - **First-person hands-only character.** Generate just hands + forearms in T-pose; rig pass still works. See `fps-controller` for first-person wiring.
@@ -233,20 +222,20 @@ The imported `.glb` includes its own `Skeleton3D` and `AnimationPlayer` (empty l
 
 ## Fallback (no MCP)
 
-1. Generate the T-pose reference at the Summer dashboard (or any image gen — Midjourney, nano-banana web, DALL-E).
-2. Upload to Meshy at meshy.ai → Image to 3D → enable rigging.
+1. Generate the T-pose reference in the Summer dashboard.
+2. Run image-to-3D with rigging enabled in the Summer dashboard.
 3. Download the `.glb`.
 4. Drop into `res://assets/characters/`; Summer Engine's Import dock picks it up.
 5. Restart the editor.
 6. Wire as CharacterBody3D / Node3D in Summer Engine manually.
 
-The output is identical to the MCP path — same Meshy skeleton, same compatibility with `generate-motion` (which has its own dashboard fallback).
+The output matches the MCP path — same skeleton, same compatibility with `generate-motion` (which has its own dashboard fallback).
 
 ## Handoff
 
 After the rigged character is wired:
 
-> `Knight` is at `./World/Knight` with a Meshy-rigged skeleton. Next:
+> `Knight` is at `./World/Knight` with an auto-rigged skeleton. Next:
 > - **Animations:** `generate-motion` for idle / walk / run / attack. Pass the `rigAssetId` returned in step 4.
 > - **State machine:** after a few clips exist, `animation-tree` for idle → walk → run blends.
 > - **Player input:** if this is the player, wire WASD + mouse via `fps-controller` or a third-person controller skill.

package/library/skills/character-movement/SKILL.md

@@ -207,7 +207,7 @@ integration handed off for a playtest, not an incomplete one.
    Referencing an unbound action is a silent no-op that reads as "controls dead".
 5. Compile-check, then run and watch it move. Feel is a user call, not a still frame.
 
-## 2D side-scroller controller (the 40% every 2D game shares)
+## 2D side-scroller controller
 
 ```gdscript
 extends CharacterBody2D

package/library/skills/character-movement/references/movement-3d.md

@@ -84,7 +84,7 @@ Set its `collision_mask` to your Level layer only (not the player).
 Third-person differences from FPS:
 - Mouse motion rotates the `CameraController` (orbit), not the body.
 - The visual wrapper rotates to face the MOVEMENT direction, decoupled from the camera.
-  Because imported characters face Godot forward `-Z`, lerp
+  Because imported characters face the engine forward `-Z`, lerp
   `CharacterRotationRoot.rotation.y` toward `atan2(-direction.x, -direction.z)`.
 - Rotate only `CharacterRotationRoot.rotation.y`. Do not yaw the CharacterBody3D or add a
   compensating 180-degree model rotation. The package already normalizes forward to `-Z`.

package/library/skills/character-portrait/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 2d-assets
 user-invocable: true
-allowed-tools: Read Grep Glob Write Edit summer_generate_image summer_search_assets summer_import_from_url summer_set_resource_property
+allowed-tools: Read Grep Glob Write Edit summer_generate_image summer_search_assets summer_import_from_url summer_set_prop summer_set_resource_property
 paths: ["assets/**", "art/portraits/**", "ui/portraits/**"]
 ---
 
@@ -62,7 +62,7 @@ background: muted painterly gradient, dark teal to deep brown, no scene detail
 style: semi-realistic painterly, soft edges, oil-painting feel
 ```
 
-Note there is no aspect line. `summer_generate_image` has no size or aspect argument — every MCP image comes back at the server's 1:1 default. Bust framing reads fine square, which is why this skill works over MCP at all; if the cast needs true portrait framing, generate in the Summer dashboard (which exposes aspect ratio) and bring the results back with `summer_import_from_url`, or crop after. Whichever you pick, do it for the *whole* cast — mixed aspect is as visible as mixed lighting.
+Note there is no aspect line. `summer_generate_image` has no size or aspect argument — every MCP image comes back at the server's 1:1 default. Bust framing reads fine square; if the cast needs true portrait framing, generate in the Summer dashboard (which exposes aspect ratio) and bring the results back with `summer_import_from_url`, or crop after. Whichever you pick, do it for the *whole* cast — mixed aspect is as visible as mixed lighting.
 
 Every subsequent portrait in this cast appends the anchor to the prompt verbatim. **Do not edit the anchor mid-cast** unless the user explicitly says "I want the new ones to look different."
 
@@ -86,7 +86,7 @@ The character description should include: identity (age, build, hair, distinctiv
 
 ### 4. Confirm and call
 
-> Generating Aria the witch portrait — 1 image, ~$0.02, model nano-banana-2, anchor locked from `.summer/portrait-anchor.md`. OK?
+> Generating Aria the witch portrait — 1 image (uses credits), model nano-banana-2, anchor locked from `.summer/portrait-anchor.md`. OK?
 
 ```
 summer_generate_image(
@@ -96,7 +96,7 @@ summer_generate_image(
 )
 ```
 
-`style: "none"` because the anchor's "semi-realistic painterly" already specifies style. Be clear about what the preset actually does though: only `cartoon` and `anime` append anything to the prompt, and `realistic` / `none` append nothing — any other value is coerced to `none`. So the preset cannot "fight" a painterly anchor; it just does nothing either way, and every bit of the look has to be in the prompt.
+`style: "none"` because the anchor's "semi-realistic painterly" already specifies style. Only `cartoon` and `anime` append anything to the prompt, and `realistic` / `none` append nothing — any other value is coerced to `none`. So the preset cannot "fight" a painterly anchor; it just does nothing either way, and every bit of the look has to be in the prompt.
 
 `options={ image_size: ... }` is dropped without an error — see the anchor note above.
 

package/library/skills/cinematic-cutscene/SKILL.md

@@ -13,7 +13,7 @@ paths: ["assets/video/**", "cinematics/**", "trailers/**"]
 
 A cutscene is a non-interactive video clip the game plays back at a fixed moment — opening, story beat, character intro, ending. Quality is dominated by **two things**: continuity (the character on screen looks like the character in the game) and shot length (every clip past 10s drifts in identity, hands, and physics). This skill enforces both — generate a reference image first to lock the look, then image-to-video each shot, then chain shots in sequence rather than asking the model for one long take.
 
-If the user wants 5 seconds of marketing footage, that's `video/trailer-shot`. If they want a 3-second seamless background loop, that's `video/animated-loop`. This skill is for narrative beats with a defined start, middle, and end — usually with dialogue or VO.
+If the user wants 5 seconds of marketing footage, that's `trailer-shot`. If they want a seamless background loop, that's `animated-loop`. This skill is for narrative beats with a defined start, middle, and end — usually with dialogue or VO.
 
 ## When to use
 
@@ -26,10 +26,10 @@ If the user wants 5 seconds of marketing footage, that's `video/trailer-shot`. I
 
 ## When NOT to use
 
-- "5-second slow-mo combat shot for the trailer" — `video/trailer-shot`.
-- "Looping splash screen background" — `video/animated-loop`.
-- "Animated logo backdrop on the title screen" — `video/animated-loop`.
-- Real-time in-engine cinematic with the actual gameplay characters and camera — that's a Godot AnimationPlayer / Timeline job, not generated video. Route to `scene-composition`.
+- "5-second slow-mo combat shot for the trailer" — `trailer-shot`.
+- "Looping splash screen background" — `animated-loop`.
+- "Animated logo backdrop on the title screen" — `animated-loop`.
+- Real-time in-engine cinematic with the actual gameplay characters and camera — that's an AnimationPlayer job, not generated video. Route to `scene-composition`.
 - Voice-only narration over a static image — generate the dialogue with `summer_generate_audio` and use a static `TextureRect`, no video needed.
 
 ## Steps
@@ -51,7 +51,7 @@ Cutscenes longer than 10 seconds are **multiple shots**, not one take. Ask the u
 
 > Want this as one 10s shot, or three shots (e.g. wide → close on face → reaction)? Each shot is 5-10s. I'll generate a reference image once, then image-to-video each shot off of it.
 
-Default if the user is vague: **3 shots, 5s each, ~$1.50 total on kling**. Confirm before spending.
+Default if the user is vague: **3 shots, 5s each, on kling**. Confirm before spending credits.
 
 ### 3. Lock the look — generate a reference image first
 
@@ -66,19 +66,19 @@ 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. For image-to-video this matters more than usual: the clip's framing is inherited from the reference, so a square reference gives you a square cutscene.
 
-Show the user the still and confirm it's the right look before video-ing it. Regenerating a $0.05 still beats regenerating a $0.50 video.
+Show the user the still and confirm it's the right look before video-ing it. Regenerating a still costs far less than regenerating a video.
 
 ### 4. Pick the model
 
 **This skill always passes `imageUrl`, which puts every call on the image-to-video route — and that route only accepts three models.** `kling-turbo` and `veo3` are text-to-video only; asking for either with an `imageUrl` set is a 400 `invalid_model`, not a silent downgrade.
 
-| Model | i2v? | Cost | Speed | When |
-|---|---|---|---|---|
-| `ltx` | yes | $0.10 | ~30s | Iteration, blocking shots, B-roll, throwaway tests |
-| `kling` | yes | $0.50 | 2-4 min | Hero shots, character cutscenes, anything the player will sit and watch |
-| `minimax` | yes | $0.25 | 2-3 min | Stylized / anime-leaning content; better at non-photoreal looks than kling |
-| `kling-turbo` | **no** | $0.30 | 1-2 min | Text-to-video only — usable only if you drop the reference image |
-| `veo3` | **no** | $1.00 | 3-5 min | Text-to-video only — usable only if you drop the reference image |
+| Model | i2v? | Speed | When |
+|---|---|---|---|
+| `ltx` | yes | ~30s | Iteration, blocking shots, B-roll, throwaway tests |
+| `kling` | yes | 2-4 min | Hero shots, character cutscenes, anything the player will sit and watch |
+| `minimax` | yes | 2-3 min | Stylized / anime-leaning content; better at non-photoreal looks than kling |
+| `kling-turbo` | **no** | 1-2 min | Text-to-video only — usable only if you drop the reference image |
+| `veo3` | **no** | 3-5 min | Text-to-video only — usable only if you drop the reference image |
 
 Default policy: **`ltx` first** to validate the prompt and shot framing. If it lands the composition but quality is rough, escalate to `kling`. `veo3` is a real tradeoff, not an upgrade: reaching for it means giving up `imageUrl`, which is the one thing that holds character identity across shots. Take that trade only when on-camera lip-sync matters more than continuity, and only with the user's approval on cost.
 
@@ -112,13 +112,13 @@ When the job completes, show the user the URL and ask:
 
 ### 6. Generate dialogue audio (if the scene has dialogue)
 
-Cutscene dialogue is TTS, not in the video model. The video model can render mouth motion that *looks* like talking, but the audio comes from `summer_generate_audio`. Generate it separately and the editor (Godot's AnimationPlayer or your `cinematics/` controller scene) syncs them.
+Cutscene dialogue is TTS, not in the video model. The video model can render mouth motion that *looks* like talking, but the audio comes from `summer_generate_audio`. Generate it separately and an AnimationPlayer or your `cinematics/` controller scene syncs them.
 
 ```
 summer_generate_audio(
   capability="text_to_speech",
   text="They'll come for you at dawn. Run while you can.",
-  voiceId="<from audio bible — see audio/voice-line>"
+  voiceId="<from audio bible — see voice-line>"
 )
 ```
 
@@ -134,7 +134,7 @@ VideoStream exts: ["ogv", "tres", "res"]
 ERROR: No loader found for resource: res://clip.mp4 (expected type: unknown)
 ```
 
-Nothing transcodes for you — `summer_import_from_url` downloads the bytes, runs Godot's import pipeline, and *fails the import* if the file never becomes a loadable resource. Convert with ffmpeg or DaVinci before importing:
+Nothing transcodes for you — `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. Convert with ffmpeg or DaVinci before importing:
 
 ```
 ffmpeg -i intro_shot_01.mp4 -c:v libtheora -q:v 8 -an intro_shot_01.ogv
@@ -167,16 +167,16 @@ For dialogue, add an `AudioStreamPlayer` sibling with the TTS clip and call `pla
 
 Pattern: `<subject> + <action> + <camera move> + <lighting> + <stylistic anchor>`. Keep prompts under 50 words; over-prompting confuses the model. Always pair with `imageUrl` to lock the character.
 
-| Goal | Model | Prompt | Cost | Duration |
-|---|---|---|---|---|
-| Opening establishing shot | `kling` | `wide shot of a fog-shrouded medieval village at dawn, slow dolly-in toward the church spire, warm low sun, cinematic, anamorphic lens flare` | $0.50 | 5s |
-| Character intro (hero turns to camera) | `kling` | `young witch with raven on shoulder turns slowly toward camera, candlelit interior, shallow depth of field, cinematic film still` | $0.50 | 5s |
-| Dialogue close-up (no synced lips) | `kling` | `close-up of a grizzled knight, eyes downcast then looking up, firelight on his face, dust motes, 16mm film grain` | $0.50 | 5s |
-| Dialogue close-up (synced lips) | `veo3` — text-to-video only, drop `imageUrl` | `close-up of the witch saying "they will come for you at dawn", candlelight, cinematic, shallow DOF` | $1.00 | 5s |
-| Action beat (village burns) | `kling` | `medium wide of a thatched village engulfed in flames at night, embers rising, silhouettes running through smoke, hand-held camera, cinematic` | $0.50 | 5s |
-| Ending shot (hero walks away) | `kling` | `low wide shot of a cloaked figure walking away across a blasted plain at sunset, slow truck-back, golden hour, dust on the wind` | $0.50 | 5s |
-| Throwaway iteration / blocking | `ltx` | same prompt as above | $0.10 | 5s |
-| Anime / stylized cutscene | `minimax` | `anime-style young swordsman draws blade and steps forward, sakura petals, dramatic wind, Studio Ghibli soft painterly` | $0.25 | 5s |
+| Goal | Model | Prompt | Duration |
+|---|---|---|---|
+| Opening establishing shot | `kling` | `wide shot of a fog-shrouded medieval village at dawn, slow dolly-in toward the church spire, warm low sun, cinematic, anamorphic lens flare` | 5s |
+| Character intro (hero turns to camera) | `kling` | `young witch with raven on shoulder turns slowly toward camera, candlelit interior, shallow depth of field, cinematic film still` | 5s |
+| Dialogue close-up (no synced lips) | `kling` | `close-up of a grizzled knight, eyes downcast then looking up, firelight on his face, dust motes, 16mm film grain` | 5s |
+| Dialogue close-up (synced lips) | `veo3` — text-to-video only, drop `imageUrl` | `close-up of the witch saying "they will come for you at dawn", candlelight, cinematic, shallow DOF` | 5s |
+| Action beat (village burns) | `kling` | `medium wide of a thatched village engulfed in flames at night, embers rising, silhouettes running through smoke, hand-held camera, cinematic` | 5s |
+| Ending shot (hero walks away) | `kling` | `low wide shot of a cloaked figure walking away across a blasted plain at sunset, slow truck-back, golden hour, dust on the wind` | 5s |
+| Throwaway iteration / blocking | `ltx` | same prompt as above | 5s |
+| Anime / stylized cutscene | `minimax` | `anime-style young swordsman draws blade and steps forward, sakura petals, dramatic wind, Studio Ghibli soft painterly` | 5s |
 
 ### Bad prompts and why
 
@@ -193,7 +193,7 @@ Pattern: `<subject> + <action> + <camera move> + <lighting> + <stylistic anchor>
 - **Generating a 10s shot when you should chain two 5s shots.** Identity, hand consistency, and physics drift every additional second past ~6s. Two 5s shots cut together look better and cost the same.
 - **Skipping the reference image.** Generating four character cutscenes from text prompts alone produces four different-looking people. Always lock the look with `summer_generate_image` first, then `imageUrl` every subsequent video call.
 - **Asking the video model to render dialogue without `veo3`.** `kling` and `ltx` will animate mouths but the motion does not match any audio. Use `veo3` if dialogue is on-camera, or keep the camera off the speaker.
-- **Using `kling` for blocking iterations.** Burn $0.10 on `ltx` to validate framing and prompt; only spend $0.50 once the composition lands.
+- **Using `kling` for blocking iterations.** Validate framing and prompt on the cheaper `ltx` first; move to `kling` once the composition lands.
 - **Putting the cutscene on a `VideoStreamPlayer` without a fade.** Cuts straight from gameplay to video are jarring. Always wrap in a `ColorRect` fade in/out.
 - **Treating `summer_generate_video` as synchronous.** It returns `{ queued: true, jobId }` and no URL. You must poll `summer_check_job` before there is anything to show or import.
 - **Importing the `.mp4` as-is.** The engine has no MP4 or WebM loader — only Ogg Theora (`.ogv`). Transcode first; an un-transcoded import fails and is rolled back.
@@ -210,7 +210,7 @@ Pattern: `<subject> + <action> + <camera move> + <lighting> + <stylistic anchor>
 
 ## Fallback (no MCP)
 
-If the Studio MCP server isn't running, the user can do all of this through the Studio web dashboard at the Summer Engine cloud console:
+If the MCP server isn't running, the user can do all of this in the Summer dashboard:
 
 1. Generate a reference image in the Image tab.
 2. Open the Video tab, paste the reference URL into the image-to-video field.
@@ -224,17 +224,17 @@ Print the exact prompt + model + duration + aspect ratio so the user can paste i
 Once the cutscene is generated and wired:
 
 > Cutscene `intro` wired at `cinematics/Intro.tscn` with fade in/out and `Video.finished` chained to scene change. Next:
-> - Add the dialogue track with `audio/voice-line` if you haven't yet.
-> - Score the moment with `audio/music-track` — a cutscene without music feels like a placeholder.
+> - Add the dialogue track with `voice-line` if you haven't yet.
+> - Score the moment with `music-track` — a cutscene without music feels like a placeholder.
 > - For the boss reveal cutscene, run this skill again with the same reference image to keep the witch identity stable.
-> - If you want a 5s "money shot" version for marketing, run `video/trailer-shot` against the same reference.
+> - If you want a 5s "money shot" version for marketing, run `trailer-shot` against the same reference.
 
 ## See also
 
-- `video/trailer-shot` — marketing footage, 5-10s, maximum visual punch.
-- `video/animated-loop` — seamless looping background clips.
-- `audio/voice-line` — TTS dialogue used inside cutscenes.
-- `audio/music-track` — score the cutscene.
-- `2d-assets/concept-art` — generate the reference image axis if no character reference exists yet.
-- `2d-assets/character-portrait` — produce a high-fidelity locked character portrait for use as `imageUrl`.
+- `trailer-shot` — marketing footage, 5-10s, maximum visual punch.
+- `animated-loop` — seamless looping background clips.
+- `voice-line` — TTS dialogue used inside cutscenes.
+- `music-track` — score the cutscene.
+- `concept-art` — generate the reference image axis if no character reference exists yet.
+- `character-portrait` — produce a high-fidelity locked character portrait for use as `imageUrl`.
 - `../../references/mcp-tools-reference/mcp-tools-reference.md` — `summer_generate_video` parameter schema and error codes.

package/library/skills/combat-basics/SKILL.md

@@ -11,7 +11,7 @@ paths: ["**/*.gd", "**/*.tscn"]
 
 # Combat Basics
 
-The Godot combat pattern is hitbox + hurtbox + health, wired by signals. Build it
+The standard combat pattern is hitbox + hurtbox + health, wired by signals. Build it
 component-first: the same three pieces work for player, enemies, and destructibles.
 
 ## The layer model (set this up first)

package/library/skills/compatibility-renderer-traps/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: compatibility-renderer-traps
+description: "Make a Forward+ Summer game also look right on the Compatibility renderer: instance-uniform budget, black MultiMesh colors, sRGB vertex colors."
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: rendering-and-lighting
+user-invocable: true
+allowed-tools: Read Grep Glob Edit Write summer_project_setting summer_get_script_errors
+paths: ["**/*.gdshader", "**/*.gdshaderinc", "**/*.gd", "project.godot"]
+---
+
+# Forward+ and Compatibility without surprises
+
+Games built on Forward+ can end up on the Compatibility renderer (OpenGL): phones where Metal/Vulkan is
+unavailable, weak GPUs, or a project that picks it for battery. The failures are silent: no error, just
+black fruit, pale colors, or objects that stop animating after the first few hundred. Each trap below
+comes with its fix and the reason.
+
+## 1. Know which renderer you actually got
+
+- Phones use `rendering/renderer/rendering_method.mobile`, which defaults to `mobile`, not Forward+.
+  Set it explicitly.
+- A device can fall back to another renderer when it lacks a capability. Trust the renderer name printed
+  at startup (or `RenderingServer.get_current_rendering_method()`), not the project setting.
+- Preview Compatibility on your computer:
+  `<summer> --path . --rendering-method gl_compatibility`.
+
+## 2. The traps
+
+| Symptom on Compatibility | Cause | Fix |
+|---|---|---|
+| Objects past roughly the 250th stop growing, lose color or read as default | GLES3 reserves 16 `instance uniform` slots per instance out of 4096, so only about 256 instances in the whole scene can use them. Beyond that, values silently read 0. | Don't use `instance uniform` for anything numerous. Put per-instance state in a one-instance MultiMesh's `INSTANCE_CUSTOM` (a vec4), or bake it into mesh vertex colors. |
+| Fruit/flowers render solid black | GLES3 multiplies `COLOR` by the MultiMesh instance color, which is 0 when `use_colors` is off. | Enable `use_colors` and set every instance color to white, or don't read `COLOR` in that path. |
+| Everything looks pastel on Forward+ (saturated on Compatibility) | Forward+ shades in linear space, Compatibility in sRGB. Colors you bake into vertex `COLOR` or hard-code into `ALBEDO` are usually sRGB. | Convert once, only where needed: `if (!OUTPUT_IS_SRGB) col = to_linear(col);` with the helper below (the shading language has no built-in `srgb_to_linear`). Or pass colors as `uniform vec3 c : source_color`, which converts for you. |
+| Whole scene pale/lime on Compatibility while Forward+ looks right | Tonemap, glow and ambient respond differently. | Keep a Compatibility branch of your lighting profile (lower ambient and exposure) and check both. |
+| Foliage glows white | Glow threshold too low for bright leaves. | Raise the glow HDR threshold (~1.5) and keep bloom near 0. |
+
+Everything the player must see (ripe crop, enemy, pickup) must stay readable without glow, SSR,
+volumetric fog or other Forward+-only effects: use shape, color and icons too.
+
+The helper (standard sRGB curve):
+
+```glsl
+vec3 to_linear(vec3 c) {
+	return mix(pow((c + vec3(0.055)) * (1.0 / 1.055), vec3(2.4)), c * (1.0 / 12.92), lessThan(c, vec3(0.04045)));
+}
+```
+
+## 3. Keep one shader path
+
+Write shaders in plain spatial math: vertex-color ramps, simple rim terms, no custom `light()` unless
+you test it on both renderers. One path for both renderers means one set of bugs and no drift.
+
+## 4. Verify, don't assume
+
+1. Render the same scene on Forward+ and `gl_compatibility` offscreen:
+   `<summer> --audio-driver Dummy --summer-offscreen --path . --resolution 1600x900 -s res://tools/capture.gd -- --out=<dir>`
+   (add `--rendering-method gl_compatibility` for the second run).
+2. Read both images side by side, and include a stress shot with many instances (the 256 limit only shows
+   at scale).
+3. Grep the log for `SCRIPT ERROR`, `SHADER ERROR` and `ERROR:`. A shader that fails to compile still lets
+   the capture exit 0 and draws the object untextured, so a missing grep hides the failure.
+4. If later captures repeat the same frame, the offscreen run froze (it happens when another engine
+   renders at the same time). Check with `md5 -r *.png` and rerun alone.
+
+## Common mistakes
+
+- Checking only the project setting and calling it "Forward+ on phones".
+- Using `instance uniform` for per-plant or per-tile state.
+- Reading `COLOR` from a MultiMesh without instance colors.
+- Testing Compatibility with ten objects when the game shows five hundred.
+- Budgeting one run per fix: every look change needs two captures (one per renderer). Plan runs in pairs.
+
+## See also
+
+- `web-compatibility-look` (a finished look when the game only runs on Compatibility, as on the web)
+- `3d-lighting` (lighting profiles)
+- `bounded-engine-runs` (safe offscreen capture runs)

package/library/skills/compatibility-renderer-traps/resource.yaml

@@ -0,0 +1,28 @@
+id: skill/compatibility-renderer-traps
+kind: skill
+version: 1.0.0
+summary: "Make a Forward+ Summer game also look right on the Compatibility renderer: instance-uniform budget, black MultiMesh colors, sRGB vertex colors."
+use_when:
+  - a game must run on phones or weak GPUs that may use the Compatibility or Mobile renderer
+  - objects render black, pale or stop animating on one renderer but not another
+  - writing shaders for many instances (crops, foliage, tiles) that must work everywhere
+facets:
+  lifecycle:
+    - build
+  domains:
+    - rendering
+    - performance
+  modalities:
+    - shaders
+    - scripts
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/web-compatibility-look
+    - skill/3d-lighting
+    - skill/bounded-engine-runs
+source: official
+license: MIT
+status: preview
+recommended: true