summer-engine 2.8.1 → 3.0.0

package/library/skills/facial-and-lipsync/resource.yaml

@@ -0,0 +1,36 @@
+id: skill/facial-and-lipsync
+kind: skill
+version: 1.0.2
+summary: Make a character's mouth move with a voice-over — phoneme extraction from audio, viseme blendshape mapping, and emotional facial expressions.
+use_when:
+  - the user has (or wants) a voice-over and needs the character's mouth to move with the words
+  - adding emotional facial expressions (smile, frown, surprise)
+facets:
+  lifecycle:
+    - build
+  domains:
+    - animation
+    - 3d
+  modalities:
+    - animation
+    - audio
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/character-animation-wiring
+    - skill/design-npc
+    - skill/animation-tree
+    - skill/generate-motion
+    - skill/procedural-animation
+    - skill/retarget
+source: official
+license: MIT
+status: stable
+recommended: false
+aliases:
+  - skills/animation/facial-and-lipsync
+lint_exceptions:
+  - url-allowlist
+  - install-command
+lint_exception_reason: Official skill with a documented dependency on the specific pinned OSS tool rhubarb-lip-sync (its GitHub repo URLs and `brew install rhubarb-lip-sync`) plus the ElevenLabs voice library it pairs with; the install is a user-consented step spelled out in the body, not an agent-autonomous action.

package/{skills/character-controllers → library/skills}/fps-controller/SKILL.md

@@ -58,10 +58,14 @@ Two things the older version of this skill got wrong:
   `summer_set_prop` with a class-name string instantiates a scene-embedded
   (`[sub_resource]`) resource, and `summer_set_resource_property` then reads that
   property off the node and writes the sub-property straight onto it. Embedded
-  and external `.tres` resources take the same path. The op has no silent-drop
-  branch: the only failures are explicit — `node not found`, `property is not a
-  resource`, or `resource is null` when the property was never assigned. Assign
-  the resource first, then set its sub-properties.
+  and external `.tres` resources take the same path. Structural failures are
+  explicit — `node not found`, `property is not a resource`, or `resource is
+  null` when the property was never assigned — but a bad value shape is silent
+  on current engines: a JSON object instead of a Godot literal string, a
+  misspelled `key`/`subProperty`, or a wrong-typed value returns `ok:true` yet
+  no-ops or coerces destructively. Assign the resource first, pass class names
+  and `Vector3(...)`/`Color(...)` strings, and confirm in the saved `.tscn`,
+  never from `ok` alone.
 
 ### 4. Add the Head pivot + Camera
 

package/library/skills/fps-controller/resource.yaml

@@ -0,0 +1,29 @@
+id: skill/fps-controller
+kind: skill
+version: 1.0.3
+summary: Production-quality first-person controller — WASD, mouse look, jump, coyote time, jump buffering, air control, and external-velocity handling.
+use_when:
+  - building an FPS, first-person movement, or a 3D character that walks, jumps, and reacts to external forces
+  - a first-person prototype needs solid movement feel — coyote time, jump buffering, air control
+facets:
+  lifecycle:
+    - build
+  domains:
+    - character-controller
+    - gameplay
+  modalities:
+    - scripts
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  # Legacy frontmatter declared template-id: template-3d-fps (no such repo exists);
+  # mapped to the real repo template-3d-fps-old-school.
+  templates:
+    - template/3d-fps-old-school
+source: official
+license: MIT
+status: stable
+recommended: true
+aliases:
+  - skills/character-controllers/fps-controller

package/{skills/visual-effects → library/skills}/game-feel/SKILL.md

@@ -117,7 +117,7 @@ func flash() -> void:
 
 **Tunable knobs:** `duration` 0.06–0.12s — under 0.06 reads as a flicker, over 0.12 looks slow. `emission_energy_multiplier` 1.5–3.0.
 
-> CRITICAL: do NOT inline a `StandardMaterial3D` as a `sub_resource` via `summer_set_prop`. Build it in script (as above) or save it to `materials/flash.tres`. Inline sub_resources break `summer_set_resource_property` silently — see `../../../references/mcp-tools-reference.md` § "Trap".
+> Note: `summer_set_prop(key="material_override", value="StandardMaterial3D")` creates an inline `StandardMaterial3D` sub_resource that `summer_set_resource_property(resourceProperty="material_override", subProperty="albedo_color", value="Color(r, g, b, a)")` then edits and `summer_save_scene` persists — so the inline route, the script above, and a saved `materials/flash.tres` are all valid. What breaks is the value *shape*: a JSON object instead of a Godot literal string, a misspelled `key`/`subProperty`, or a wrong-typed value returns `ok:true` yet silently no-ops or destructively coerces on current engines (dict → material cleared; dict → `Color(0,0,0,1)`; newer engines reject these with `unknown_property` / `bad_value_shape` / `type_mismatch`). Always pass class names and `Color(...)`/`Vector3(...)` strings, and confirm the result in the saved `.tscn` or a snapshot diff — never from `ok` alone. See `../../references/mcp-tools-reference/mcp-tools-reference.md`.
 
 ## Step 5 — Install Section 2 (Trauma Camera Shake)
 
@@ -369,13 +369,13 @@ Tune one knob at a time:
 | Duck for 1.5+ seconds | 0.4–0.6 second total duck-and-restore | Long ducks make the music feel broken, not punchy |
 | Equal pitch/yaw shake | `yaw_factor ≤ 0.5` | Eyes are sensitive to vertical motion; equal axes feel mechanical |
 | `Engine.time_scale` for every hit | Reserve hit-stop for big events only (boss hits, deaths) | Time-scale dips on every hit feel laggy, not impactful |
-| Inline `StandardMaterial3D` sub_resource via `summer_set_prop` | Build in script or save standalone `.tres` | Inline sub_resources silently break `summer_set_resource_property` |
+| A JSON object (or a misspelled key) as the `summer_set_prop` / `summer_set_resource_property` value — e.g. `value={"type": "StandardMaterial3D", ...}` through `summer_batch`, which forwards ops verbatim | `value="StandardMaterial3D"` to create the inline material, then `summer_set_resource_property(... value="Color(r, g, b, a)")` per field; confirm in the saved `.tscn` | Current engines return `ok:true` and silently no-op or coerce destructively — dict → material cleared, dict → `Color(0,0,0,1)`. The inline sub_resource itself is fine |
 | `summer_set_prop(key="groups", value='["player_camera"]')` | `add_to_group(&"player_camera")` in `_ready()`, or a `groups = [...]` line in the `.tscn` | `Node` has no `groups` property, and `summer_set_prop` takes only string/number/boolean — never an array |
 | `BaseMaterial3D.new()` | `StandardMaterial3D.new()` | `BaseMaterial3D` is abstract; constructing it is a parse error that kills the whole script |
 
 ## Collaborative protocol
 
-This skill writes 3 GDScript files and adds 1 node + 1 autoload entry. Always ask before each section is applied. Group related writes into one ask: "I'm about to add HitFlash + CameraShake + AudioDucker autoload, wire one signal. OK?" See `../../../references/collaborative-protocol.md`.
+This skill writes 3 GDScript files and adds 1 node + 1 autoload entry. Always ask before each section is applied. Group related writes into one ask: "I'm about to add HitFlash + CameraShake + AudioDucker autoload, wire one signal. OK?" See `../../references/collaborative-protocol/collaborative-protocol.md`.
 
 ## When NOT to use this skill
 
@@ -386,11 +386,11 @@ This skill writes 3 GDScript files and adds 1 node + 1 autoload entry. Always as
 
 ## See also
 
-- `../../../references/mcp-tools-reference.md` — full MCP tool list, especially the inline-sub_resource trap
-- `../../../references/godot-version.md` — Summer compatibility and
+- `../../references/mcp-tools-reference/mcp-tools-reference.md` — full MCP tool list, especially `summer_set_resource_property` on inline sub_resources and which failures are loud vs. silent
+- `../../references/godot-version/godot-version.md` — Summer compatibility and
   version-sensitive API notes
-- `../../../references/collaborative-protocol.md` — "May I write" pattern
-- `../../../references/gd-style.md` — typed GDScript conventions
+- `../../references/collaborative-protocol/collaborative-protocol.md` — "May I write" pattern
+- `../../references/gd-style/gd-style.md` — typed GDScript conventions
 - `audio/audio-direction/SKILL.md` — bus layout setup (prerequisite for ducking)
 - `post-processing/screen-shake/SKILL.md` — deeper trauma variants (Perlin noise, stacked sources)
 - `visual-effects/gpuparticles-3d-basics/SKILL.md` — particles to layer on top of the trio

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

@@ -0,0 +1,27 @@
+id: skill/game-feel
+kind: skill
+version: 1.0.2
+summary: "Add juice: hit-flash, trauma-based camera shake, and audio ducking wired so one hit fires all three — for games that feel flat or lack impact."
+use_when:
+  - a Summer game feels flat, lacks impact, needs juice or punch
+  - the user asks for hit feedback, screen shake, camera shake, or audio ducking
+facets:
+  lifecycle:
+    - build
+  domains:
+    - vfx
+    - gameplay
+  modalities:
+    - scenes
+    - scripts
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/audio-direction
+source: official
+license: MIT
+status: stable
+recommended: true
+aliases:
+  - skills/visual-effects/game-feel

package/library/skills/gameskill/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: gameskill
+description: Use when finishing a game-development session and you want to capture what you just learned as a reusable skill so the next session starts smarter. Trigger on "gameskill", "/gameskill", "capture learnings", "save to skills".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: workflow
+allowed-tools: Read Write Edit Glob Grep Bash
+---
+
+# /gameskill: capture session learnings as a skill
+
+You are being invoked at the end (or middle) of a game-development session. Turn what you just figured out into a durable skill so future agents start where you ended. This is the meta-skill: the loop that turns ad-hoc fixes into reusable expertise.
+
+## Where a captured skill goes
+
+Summer resolves skills in this order: the game project, then the user's agent skills directory, then the skills bundled with the Summer package. Pick the narrowest home that fits:
+
+1. **The game project** (default). Write `SKILL.md` into the project-scoped skills directory of the agent you are running in: `.claude/skills/<slug>/` for Claude Code, `.agents/skills/<slug>/` for Codex, `.cursor/rules/` for Cursor, `.windsurfrules` for Windsurf. `summer skills install --scope project` shows the exact path for the current agent. Commit it with the game.
+2. **The user's agent skills directory** when the lesson applies to every project on this machine (`~/.claude/skills/<slug>/`, `~/.agents/skills/<slug>/`). Do not edit skills that Summer installed there; they are overwritten on the next `summer setup`.
+3. **The Summer library** when the lesson is general enough for every Summer user. Only possible inside a checkout of the summer-engine agent repository: add `library/skills/<slug>/resource.yaml` and `library/skills/<slug>/SKILL.md` (flat slugs, no category folders), then run `npm run generate:registry` and `npm run validate:library`. Everything under `registry/generated/` and every plugin manifest is generated from `library/`; never hand-edit them. Outside that checkout, send the lesson through `summer_library_feedback` (or `summer tool library-feedback`) with the id of the closest existing skill so the maintainers can fold it in.
+
+Read the current project as ground truth. Working code from the real project beats invented examples.
+
+## What to do, in order
+
+1. One short sentence to the user: "Capturing learnings from this session into a skill." No plan dump.
+
+2. Probe. Check which skills directories exist for this agent and project, and search the bundled library first (`summer_search_library "<topic>"`, or `summer skills list`) so you extend an existing skill instead of duplicating it.
+
+3. Recap the session. Pull out learnings that are non-obvious AND general, things a future agent could not derive from reading the codebase. Examples that count:
+   - A working shader (the actual code)
+   - A GDScript idiom that beat the obvious approach
+   - A UI layout that survived the design pass
+   - A bug, its root cause and the fix that was not in any docs
+   - A Godot 4.x quirk (type inference, signal gotchas, plugin configuration)
+   - A spawning, AI or enemy pattern that worked
+   - A performance fix with measured before and after
+   - An asset workflow that beat the alternatives
+   - A Summer tool that steered you wrong: report that with `summer_library_feedback` on the tool's id, in addition to any skill
+
+   Examples that do NOT count: one-off code with no general lesson, things already documented in an existing skill or the project's agent instructions, personal preferences without reasoning, anything manufactured to fill space.
+
+4. Decide placement for each learning: extend an existing skill (name the file, quote the section, draft the addition) or create a new one (pick the home from the list above, name the slug, draft the full skill). Match the format of the bundled skills: YAML frontmatter with `name` and a "Use when ..." `description`, then the body.
+
+5. One tight pause for the user. Five to ten lines: what files you will touch, what each captures, what gets left out. Wait for OK or a redirect. Do not ask multiple questions.
+
+6. Apply. Write the files, run `git status` so the diff is visible, and if you touched the Summer library run the generator and validator.
+
+7. Report. One short message: files changed, the future-agent payoff in one sentence per skill, and what (if anything) is still uncaptured.
+
+## Style rules
+
+- Tight. No filler.
+- Capture the why, not just the what. "Use X" rots. "Use X because Y breaks under Z" survives. Lead with the reason.
+- Real working code from the active project beats invented examples.
+- VFX is code: shaders, GDScript and node setup. Never an image-generation pipeline.
+- No em dashes in skill text. Use periods or restructure.
+- No dates inside skill bodies. Skills are timeless guidance; dates belong in commit messages.
+- No specific game or project names inside skill bodies. The same skill may be installed by someone who never heard of your project.
+- Verify before claiming. If a skill says "Summer Engine does X", check it against the tool result or the running engine first.
+
+## When there is nothing worth capturing
+
+Say so: "session was tactical, no durable learnings worth a skill." Better to ship nothing than to ship noise.

package/library/skills/gameskill/resource.yaml

@@ -0,0 +1,22 @@
+id: skill/gameskill
+kind: skill
+version: 1.0.2
+summary: Capture what a game-dev session just learned as a reusable skill (project, user or Summer library) so the next session starts smarter.
+use_when:
+  - finishing a game-development session with learnings worth capturing as a reusable skill
+  - a session found a technique, workaround, or convention worth reusing across Summer sessions
+facets:
+  lifecycle:
+    - build
+  domains:
+    - agent-workflow
+    - meta
+  modalities:
+    - docs
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+aliases:
+  - skills/workflow/gameskill

package/library/skills/gdscript-patterns/resource.yaml

@@ -0,0 +1,23 @@
+id: skill/gdscript-patterns
+kind: skill
+version: 1.0.3
+summary: GDScript conventions — type hints, signals, exports, onready, lifecycle methods, get_node vs $NodePath, naming.
+use_when:
+  - writing or refactoring GDScript — type hints, signals, exports, onready, lifecycle methods, naming conventions
+  - reviewing GDScript for idiomatic signals, exports, @onready usage, node references, and naming
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scripting
+    - conventions
+  modalities:
+    - scripts
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+recommended: true
+aliases:
+  - skills/scripting-patterns/gdscript-patterns

package/{skills/animation → library/skills}/generate-motion/SKILL.md

@@ -13,7 +13,7 @@ paths: ["**/*.tscn", "**/*.tres", "**/*.gd"]
 
 Picks a clip from a **curated mocap library** by name and wires it onto a Meshy-rigged humanoid. Fast (~30s) and cheap (~$0.10) and looks great because it's real mocap. The five short aliases that always work are `idle`, `walk`, `run`, `jump`, `attack`; anything else must be an exact library name — see the Reference card before you invent one.
 
-The target must be a **Meshy-rigged humanoid** — a `rigAssetId` from a prior `summer_generate_3d({ kind: "image-to-3d", imageUrl: "...", options: { rig: true } })` call. The result job includes `rigAssetId`. If the user points at a non-rigged mesh, stop and route to `summer:asset-pipeline/asset-strategy` (or directly call `summer_generate_3d` with `options.rig: true`) before generating motion.
+The target must be a **Meshy-rigged humanoid** — a `rigAssetId` from a prior `summer_generate_3d({ kind: "image-to-3d", imageUrl: "...", options: { rig: true } })` call. The result job includes `rigAssetId`. If the user points at a non-rigged mesh, stop and route to `asset-strategy` (or directly call `summer_generate_3d` with `options.rig: true`) before generating motion.
 
 > **Custom prompt-driven motion** (e.g. "drops to one knee, draws bow") is on
 > the roadmap but not shipped yet. For one-off signature moves not on the
@@ -45,11 +45,11 @@ After animation jobs complete, import the rig plus child animation assets togeth
 
 ## When NOT to use this skill
 
-- The user wants to apply an *existing* animation to a *new* model — use `summer:animation/retarget` instead. Don't regenerate.
-- The user wants state-machine wiring (idle → walk → run blend) — generate the clips here, then hand off to `summer:animation/animation-tree`.
-- The user wants facial / lipsync animation — that's `summer:animation/facial-and-lipsync`.
+- The user wants to apply an *existing* animation to a *new* model — use `retarget` instead. Don't regenerate.
+- The user wants state-machine wiring (idle → walk → run blend) — generate the clips here, then hand off to `animation-tree`.
+- The user wants facial / lipsync animation — that's `facial-and-lipsync`.
 - The mesh isn't rigged. Rig first; never call `summer_generate_motion` on a static `.glb`.
-- The user wants procedural look-at, IK, foot placement — that's `summer:animation/procedural-animation`.
+- The user wants procedural look-at, IK, foot placement — that's `procedural-animation`.
 - The user described a **custom signature move** that isn't on the curated list. Today, route to the manual-authoring fallback below.
 
 ## Steps
@@ -60,7 +60,7 @@ After animation jobs complete, import the rig plus child animation assets togeth
 summer_search_assets(query="<character name>", assetType="3d_model", source="my_assets")
 ```
 
-The result must include `rigAssetId: <id>` on a Meshy rig. If it shows `rigAssetId: null`, the model isn't rigged — stop, propose `summer_generate_3d({ kind: "image-to-3d", imageUrl: "...", options: { rig: true } })` first (the result includes `rigAssetId`), or route to `summer:asset-pipeline/asset-strategy`.
+The result must include `rigAssetId: <id>` on a Meshy rig. If it shows `rigAssetId: null`, the model isn't rigged — stop, propose `summer_generate_3d({ kind: "image-to-3d", imageUrl: "...", options: { rig: true } })` first (the result includes `rigAssetId`), or route to `asset-strategy`.
 
 ### 2. Confirm with the user before spending
 
@@ -103,7 +103,7 @@ summer_save_scene(scenePath="res://main.tscn")
 `summer_save_scene`. `summer_inspect_node` takes only `path` — it has no
 `scenePath` and reads the currently-edited scene.
 
-If the character will use multiple clips, leave the AnimationPlayer in place — every subsequent generation appends to the same library. State-machine wiring belongs to `summer:animation/animation-tree`, not here.
+If the character will use multiple clips, leave the AnimationPlayer in place — every subsequent generation appends to the same library. State-machine wiring belongs to `animation-tree`, not here.
 
 ## Confirmation gates
 
@@ -140,8 +140,8 @@ have actually seen, or route to the manual-authoring fallback.
 ### Pitfalls
 
 - **Invented `motionName` strings fail.** `"run_fast"`, `"attack_sword"`, `"death"` all resolve to nothing and the call errors. Name resolution is exact — five aliases, or a real library name / display name / numeric id. Do not extrapolate a naming scheme.
-- **Locomotion clips have a forward bias.** Meshy's `run` translates the root forward by ~5m. If you're driving root motion in code, set `root_motion_track` correctly or strip the translation in an AnimationPlayer Edit. Check the upstream root-motion API reference matching the current Summer technical base.
-- **Rig pose mismatch.** If your rig was rigged with a non-T-pose reference image, the limbs may bend wrong. Re-rig from a T-pose mannequin (see `summer:asset-pipeline/asset-strategy`) before re-generating.
+- **Locomotion clips have a forward bias.** Meshy's `run` translates the root forward by ~5m. Either the code drives movement (then the baked root translation causes a lunge-and-snap every loop — strip it) or the clip does via `root_motion_track` + `get_root_motion_position()` — never both. The full root-motion setup and its playtest verification live in `character-animation-wiring`.
+- **Rig pose mismatch.** If your rig was rigged with a non-T-pose reference image, the limbs may bend wrong. Re-rig from a T-pose mannequin (see `asset-strategy`) before re-generating.
 - **Rig still preparing.** New rigs need ~3 minutes after the rig job completes before the animation library is ready. The MCP route returns 425 "animations_preparing" if you call too early. Wait and retry.
 
 ## Anti-patterns
@@ -170,13 +170,13 @@ Engine.
 
 ## Handoff
 
-- After generating locomotion clips, suggest `summer:animation/animation-tree` to wire idle → walk → run.
-- After generating a one-shot (death, hit-react), suggest `summer:ai-and-npcs/design-npc` to fire it from the behavior state machine.
-- For first-person hand animations on a player, use this skill on a *hands-only rig* and then `summer:character-controllers/fps-controller` for the wiring.
-- If the user wants to apply these clips to a second character, hand off to `summer:animation/retarget`.
+- After generating locomotion clips, suggest `character-animation-wiring` — the end-to-end wiring path (inspect what landed, idle/walk/run state machine with blend times, footstep method tracks, root motion, playtest proof). For blend spaces and attack/hit overlays on top, `animation-tree`.
+- After generating a one-shot (death, hit-react), suggest `design-npc` to fire it from the behavior state machine.
+- For first-person hand animations on a player, use this skill on a *hands-only rig* and then `fps-controller` for the wiring.
+- If the user wants to apply these clips to a second character, hand off to `retarget`.
 
 ## See also
 
-- `summer:asset-pipeline/asset-strategy` — how to get a Meshy-rigged character in the first place.
-- `summer:animation/animation-tree` — wire the generated clips into a state machine.
-- `summer:animation/retarget` — re-use one library across many characters without regenerating.
+- `asset-strategy` — how to get a Meshy-rigged character in the first place.
+- `animation-tree` — wire the generated clips into a state machine.
+- `retarget` — re-use one library across many characters without regenerating.

package/library/skills/generate-motion/resource.yaml

@@ -0,0 +1,34 @@
+id: skill/generate-motion
+kind: skill
+version: 1.0.3
+summary: Attach an animation clip to a rigged character from the curated Meshy motion library — idle, walk, run, attack — wired via AnimationPlayer.
+use_when:
+  - the user needs an animation clip on a rigged character — idle/walk/run/attack from the curated Meshy library
+  - a rigged character has no idle, walk, run, or attack animation yet
+facets:
+  lifecycle:
+    - build
+  domains:
+    - animation
+    - 3d
+  modalities:
+    - animation
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/character-animation-wiring
+    - skill/design-npc
+    - skill/animation-tree
+    - skill/facial-and-lipsync
+    - skill/procedural-animation
+    - skill/retarget
+    - skill/asset-strategy
+    - skill/fps-controller
+source: official
+license: MIT
+status: stable
+recommended: true
+aliases:
+  - skills/animation/generate-motion

package/library/skills/godogen-visual-proof-game-generation/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: godogen-visual-proof-game-generation
+description: "Use when adopting Godogen's thin-runtime autonomous game generation and its 'proof over claims' visual QC loop for SummerEngine: capture frames from the running engine, let the host agent self-verify against the brief, and drive bounded fix iterations until a proof recording closes the run."
+license: MIT
+category: workflow
+tags:
+  - agentic
+  - validation
+  - visual-qc
+  - asset-generation
+  - godot4
+  - automation
+confidence: extracted
+---
+
+# Godogen-Style Autonomous Game Generation + Visual Proof QC in SummerEngine
+
+## Outcome
+
+Give SummerEngine an agent workflow that takes a **short game description** and produces a **runnable, visually verified game**, using Godogen's core insight: *judge the result from the running game, never from a clean compile*. The visible output of every iteration is a screenshot or short proof clip from the actual engine, and the host coding agent itself reviews those frames against the brief — no separate verifier model.
+
+This directly targets a known studio pain point: Summer Engine already has a "validation of the game" step, but it does not yet verify the running game. Godogen's visual QC loop is the reference design to rebuild it.
+
+## When to Use
+
+- Building complete small games or prototypes from a natural-language brief (mechanics + art style + camera + HUD in one prompt, like Godogen's demo prompts).
+- Fixing SummerEngine's broken game-validation step: you need an agent that can *see* the running game and report concrete visual defects.
+- Unattended generation runs where the deliverable must include proof (15–20s recording) instead of "it compiled, trust me."
+- Asset generation for the game (references, textures, 3D models, animated sprites) as part of the same pipeline.
+
+## When NOT to Use
+
+- Hand-authored, large-scope production work — this is a generator loop, not a replacement for deliberate design iteration.
+- When no headless/GPU capture environment exists — the QC loop is worthless if frames come from a software renderer (see Failure Modes).
+- Quick code fixes with no visual component — running the engine and capturing is overhead if the change is purely logic.
+
+## Core Principles (extracted)
+
+1. **godogen → game repo → game.** The generator itself is not a game. You publish a thin scaffold into a fresh game repo; the agent then builds the actual game *inside* that repo from a short engine guide.
+
+2. **Thin runtime, smart agent.** The published repo is intentionally minimal: one engine-agnostic runtime manifest (`prompts/runtime.md`), a one-page per-engine guide (`engines/godot.md`), and a single cross-engine asset-generation skill (`asset-gen/`). The model plans, scaffolds, and decomposes the work itself — there are no planner/decomposer/architecture skill files anymore (dropped 2026-07-02).
+
+3. **Proof over claims.** "The agent judges results from the running game (a live URL or a recorded clip), not from a clean compile, so visible defects drive the next iteration."
+
+4. **Host agent self-verifies from captured frames.** Godogen dropped a separate Gemini verification pass on 2026-04-26: "Opus 4.7 / GPT 5.5 self-verify from captured frames; external pass added no signal." One strong coding agent looking at real screenshots is enough.
+
+5. **Two involvement modes, chosen by how the task is framed.** Watch the live game and steer at decision points, or run unattended and receive a 15–20s proof recording at the end, "watched back before done."
+
+6. **Engine-specific runtime traps live in the engine guide** — the defects that "survive a compile but fail at runtime" are documented where the agent will read them during the run.
+
+## SummerEngine Architecture Mapping
+
+| Godogen concept | SummerEngine adaptation |
+|---|---|
+| `publish.sh --engine godot --agent codex` | A SummerEngine publish step that renders `AGENTS.md` + skills into the target game repo |
+| `prompts/runtime.md` manifest | One SummerEngine runtime manifest describing delivery contract + involvement modes |
+| `engines/godot.md` one-page guide | SummerEngine engine guide: capture recipes, runtime traps, scene conventions |
+| `asset-gen/` skill | SummerEngine asset-generation skill (Gemini/Grok/Tripo3D stack below) |
+| Proof recording (ffmpeg + xvfb) | Godot viewport screenshot capture + optional ffmpeg clip |
+| C#/.NET + `dotnet build` as compile gate | See note below — Godogen migrated to C# specifically so `dotnet build` replaces per-file validation loops |
+
+**Language note:** Godogen generates Godot games in **C#/.NET** (migrated from GDScript on 2026-04-06) because `dotnet build` gives a cheap, reliable compile gate. If SummerEngine stays GDScript, you need an equivalent cheap gate — e.g. `godot --headless --check-only` script parsing — before the visual stage, since the whole point is: compile gate first, *then* visual proof, never one instead of the other.
+
+## Scene / Repo Shape (SummerEngine target)
+
+Published game repo (thin, everything else recreated by the agent):
+
+```
+my-summer-game/
+├── AGENTS.md                 # host-agent entry (Codex flavor)
+├── prompts/runtime.md        # delivery manifest + involvement modes
+├── engines/summerengine.md   # one-page guide: capture, traps, conventions
+└── .agents/skills/
+    └── asset-gen/            # sole published skill (asset generation)
+```
+
+In-engine capture harness (Godot 4 node shape):
+
+```
+Main (Node)
+├── Game ...                  # whatever the agent built
+├── Camera3D / Camera2D
+└── ProofCapture (Node, autoload or scene node)
+    # listens to RenderingServer.frame_post_draw
+    # saves PNGs to user://proof/ on trigger
+```
+
+## Capture Harness (GDScript, adaptation)
+
+The source says *that* Godogen captures (xvfb + engine screenshots + ffmpeg proof video) but the repo internals were not retrievable. Below is a SummerEngine-facing adaptation, not extracted code:
+
+```gdscript
+extends Node
+## ProofCapture — saves viewport screenshots for the visual QC loop.
+## Trigger via capture(tag) at meaningful moments: scene loaded,
+## state changed, or on a timer during a proof recording.
+
+const OUTPUT_DIR := "user://proof/"
+
+var _shot_index: int = 0
+var _recording := false
+var _record_timer: float = 0.0
+var _record_interval: float = 0.5   # 2 fps is plenty for a QC strip
+var _record_remaining: float = 0.0
+
+func _ready() -> void:
+    DirAccess.make_dir_recursive_absolute(OUTPUT_DIR)
+    RenderingServer.frame_post_draw.connect(_on_frame_post_draw)
+
+func capture(tag: String) -> String:
+    var img: Image = get_viewport().get_texture().get_image()
+    var path := "%s%03d_%s.png" % [OUTPUT_DIR, _shot_index, tag.simplify_path()]
+    img.save_png(path)
+    _shot_index += 1
+    return path
+
+func start_recording(seconds: float = 18.0) -> void:
+    _recording = true
+    _record_remaining = seconds
+    _record_timer = 0.0
+
+func _process(delta: float) -> void:
+    if not _recording:
+        return
+    _record_remaining -= delta
+    _record_timer += delta
+    if _record_timer >= _record_interval:
+        _record_timer = 0.0
+        capture("rec")
+    if _record_remaining <= 0.0:
+        _recording = false
+        # hand the PNG sequence to ffmpeg for the 15–20s proof clip
+
+func _on_frame_post_draw() -> void:
+    pass  # hook if you need exact-frame capture timing
+```
+
+The ffmpeg step (from setup.md, `ffmpeg — MP4 encoding of proof videos`):
+
+```bash
+ffmpeg -framerate 2 -i user://proof/%03d_rec.png -c:v libx264 -pix_fmt yuv420p proof.mp4
+```
+
+Headless run on Linux uses xvfb so rendering is real: `xvfb-run -a godot --headless ...` (setup.md: xvfb is explicitly for "headless Godot/Bevy runs and capture").
+
+## The Visual QC Loop (the core deliverable)
+
+This is the piece SummerEngine's validation should adopt:
+
+```
+1. BUILD/EDIT   agent applies a change to the game
+2. COMPILE GATE cheap syntax/build check (dotnet build OR godot script check)
+3. RUN + CAPTURE launch game under xvfb, capture screenshots at defined triggers
+4. SELF-REVIEW  host agent inspects captured frames against the brief
+5. DEFECT LIST  structured findings: {location, expected, observed, severity}
+6. DECIDE       no blocking defects → go to 7; else → back to 1 with the list
+7. PROOF        15–20s recording, "watched back before done"
+```
+
+Rules that make it work:
+
+- **Bounded.** Hard cap on rounds (see Tunables). Godogen's delivery manifest frames this as closing with a proof recording, not iterating forever.
+- **Same agent verifies.** Do not add a separate verifier model — Godogen tested that (Gemini verification) and dropped it: no extra signal.
+- **Defects must be visible.** The review prompt asks for concrete visual observations tied to the brief ("character sprite missing against brief's 'chunky iconic sprites'", not "looks wrong").
+- **Engine traps belong in the guide.** Recurring "survives compile, fails at runtime" defects get written into `engines/summerengine.md` so the agent reads them before they happen again.
+
+## Asset Generation Pipeline (extracted)
+
+| Need | Tool | Notes |
+|---|---|---|
+| Precise references & characters | Gemini (`GOOGLE_API_KEY`, google-genai) | high-fidelity image generation |
+| Textures & simple objects | xAI Grok (`XAI_API_KEY`) | image/video generation |
+| Image-to-3D, rigged biped animation | Tripo3D (`TRIPO3D_API_KEY`) | 3D conversion |
+| Animated sprites | Grok video → frame extraction (ffmpeg) → loop detection → background removal | BiRefNet multi-signal matting (since 2026-03-25); imagemagick for resize/flip/crop |
+
+asset-gen is the **sole published skill** in a godogen game repo — everything else the agent recreates from the engine guide.
+
+## Implementation Steps
+
+1. **Write the thin runtime for SummerEngine**: `prompts/runtime.md` (delivery manifest + the two involvement modes), `engines/summerengine.md` (one page: how to run, how to capture, known runtime traps), and the asset-gen skill. Engine guide content comes from actual SummerEngine run failures — start it now, grow it every time a defect "survives compile."
+2. **Set up headless capture**: Godot 4 (.NET build if following Godogen's C# choice) on PATH, xvfb, ffmpeg, imagemagick, vulkan-tools. Verify GPU path with `vulkaninfo --summary`; a software-renderer fallback on a GPU host is a misconfiguration to fix before trusting any QC frame.
+3. **Implement `ProofCapture`** (GDScript above) as an autoload; wire capture triggers to scene-loaded, state-changed, and recording mode.
+4. **Define the compile gate**: `dotnet build` (C#) or `godot --headless --check-only` (GDScript). Gate must run before every capture round.
+5. **Implement the QC loop protocol**: capture → self-review → structured defect list → fix → re-capture, capped at `max_qc_rounds`. The reviewing prompt receives the original brief + latest frames and must output findings in a fixed JSON shape.
+6. **Add the proof-recording close**: after the loop passes, record 15–20s, encode with ffmpeg, and have the agent watch the clip back before declaring done.
+7. **Support both involvement modes**: if the task is framed open-ended, surface the live game early and checkpoint at taste/scope/cost decisions; if it's a finished brief, run unattended and close with proof.
+8. **Optionally move runs to a server**: tmux/screen for long sessions, GPU instance for faster render+capture, remote-control interface to steer mid-run.
+
+## Tunables
+
+| Parameter | Meaning | Godogen reference |
+|---|---|---|
+| `max_qc_rounds` | hard cap on capture→fix iterations | bounded delivery, not infinite |
+| Proof clip length | recording at the end of a run | 15–20 s |
+| Capture triggers | when screenshots fire (scene load / state change / timer) | engine-guide defined |
+| Record fps | frame rate of the QC strip | 2 fps is enough for review; ffmpeg re-encodes |
+| Verification model | which agent reviews frames | host agent itself (Claude Code / Codex); no separate verifier |
+| Involvement mode | live-steered vs unattended | chosen by task framing |
+
+## Failure Modes & Gotchas
+
+- **Trusting a clean compile.** The whole anti-pattern Godogen exists to kill. Compile gate is necessary, never sufficient.
+- **Software-renderer frames.** SwiftShader/llvmpipe/lavapipe output looks wrong and misleads the QC loop; on a GPU host it means the capture path is misconfigured (setup.md warns explicitly).
+- **Unbounded verification loops.** Without `max_qc_rounds` the agent iterates forever on taste-level nitpicks. Close with proof, don't chase perfection.
+- **Adding a separate verifier model.** Godogen tried Gemini verification and dropped it — "external pass added no signal." Don't repeat the experiment.
+- **Capturing before the frame settles.** Grab the viewport after `frame_post_draw`/a short delay, or screenshots show half-rendered scenes and generate false defects.
+- **Harmless headless noise.** `godot --headless --quit` may show RID warnings (setup.md calls them harmless) — don't let the QC loop treat engine noise as defects.
+- **GDScript vs C# trade-off.** Godogen's C# migration was driven by `dotnet build` replacing per-file validation loops. Staying GDScript is fine, but you must provide an equally cheap compile gate or the loop loses its fast first stage.
+- **Stale claims.** The X post mentions "850+ GDScript classes" language reference, but the project migrated to C# in April 2026 — verify current repo state before copying specifics.
+
+## Verification
+
+Not summerengine-verified. To validate an implementation:
+
+1. Publish a thin SummerEngine game repo from the runtime manifest; confirm the agent scaffolds a runnable project from the one-page guide alone.
+2. Run a small game brief end-to-end; confirm the pipeline produces a running build, not just code.
+3. Intentionally introduce a visible defect (e.g., broken sprite, missing material); confirm the QC loop's self-review detects it from captured frames and fixes it within the round cap.
+4. Confirm the run closes with a 15–20s proof clip that the agent reviews before marking done.
+5. Confirm the compile gate runs before every capture round and that frames come from hardware rendering (check with vulkaninfo).
+
+## Confidence
+
+`extracted` — Architecture (thin runtime, manifest + engine guide + asset-gen), the proof-over-claims principle, self-verification from captured frames, the dropped Gemini verification, C# migration rationale, capture tooling (xvfb/ffmpeg/imagemagick/vulkan-tools), asset-generation stack, and the two involvement modes are drawn directly from the GitHub README, CHANGELOG.md, and setup.md. The `ProofCapture` GDScript, the QC-loop JSON protocol, and the SummerEngine repo mapping are librarian adaptations — the repository's internal files (`prompts/runtime.md`, `engines/godot.md`, `asset-gen/` contents) could not be retrieved and are referenced only by their README-described roles.