summer-engine 3.4.0 → 3.4.1

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

@@ -13,68 +13,61 @@ tags:
 confidence: extracted
 ---
 
-# Godogen-Style Autonomous Game Generation + Visual Proof QC in SummerEngine
 
-## Outcome
+# Godogen-Style Game Generation with Visual Proof QC in Summer Engine
 
-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.
+## Outcome
 
-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.
+Take a **short game description** and produce a **runnable, visually verified game**. The method comes from the open-source Godogen project: *judge the result from the running game, never from a clean compile*. Every iteration ends with a screenshot or short proof clip from the running game, and the host coding agent reviews those frames against the brief itself. There is no separate verifier model.
 
 ## 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."
+- Building a complete small game or prototype from a natural-language brief (mechanics, art style, camera and HUD in one prompt).
+- The agent says the game works but never looked at it running. You need an agent that *sees* the running game and reports concrete visual defects.
+- Unattended generation runs where the deliverable must include proof (a 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."
+- Hand-authored, large-scope production work. This is a generator loop, not a replacement for deliberate design iteration.
+- No GPU capture path. The QC loop is worthless if frames come from a software renderer (see Failure Modes).
+- Quick logic fixes with no visual component. Running and capturing is overhead there.
 
-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.
+## Core Principles (from Godogen)
 
-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."
+1. **Generator repo → game repo → game.** The generator itself is not a game. It publishes 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 minimal: one runtime manifest (`prompts/runtime.md`), a one-page engine guide, and one asset-generation skill (`asset-gen/`). The model plans, scaffolds and decomposes the work itself; there are no planner or architecture skill files.
+3. **Proof over claims.** The agent judges results from the running game (a live build or a recorded clip), not from a clean compile, so visible defects drive the next iteration.
+4. **The host agent verifies from captured frames.** Godogen dropped a separate verification model because it 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.** Defects that survive a compile but fail at runtime are written down where the agent reads them during the run.
 
-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.
+## Mapping to Summer Engine
 
-## SummerEngine Architecture Mapping
-
-| Godogen concept | SummerEngine adaptation |
+| Godogen concept | Summer Engine equivalent |
 |---|---|
-| `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.
+| Publish step that renders the agent files into a game repo | `summer create <template>` plus the installed Summer skills; `.summer/` holds the brief (`GameSoul.md`) and build plan |
+| `prompts/runtime.md` manifest | `.summer/build-plan.md`: delivery contract and involvement mode |
+| One-page engine guide | A project skill with capture recipes, runtime traps and scene conventions (`gameskill` captures new traps) |
+| `asset-gen/` skill | `asset-strategy` and the Summer generation tools |
+| Compile gate (`dotnet build` for C#) | `summer_get_script_errors` per file, then `summer_get_diagnostics` |
+| Proof recording (ffmpeg + xvfb) | `summer_play`, `summer_screenshot target:"game"`, `summer_game_probe`; frame sequences from a `RunVerification` probe's `save_frame`; optional ffmpeg clip |
 
-## Scene / Repo Shape (SummerEngine target)
+**Language note:** Godogen generates C# games because `dotnet build` is a cheap, reliable compile gate. Summer games use GDScript, so the gate is `summer_get_script_errors` on each changed file. The order is the point: compile gate first, *then* visual proof, never one instead of the other.
 
-Published game repo (thin, everything else recreated by the agent):
+## Repo Shape
 
 ```
 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.md                 # host-agent entry
+├── .summer/
+│   ├── GameSoul.md           # the brief
+│   └── build-plan.md         # delivery contract + involvement mode
 └── .agents/skills/
-    └── asset-gen/            # sole published skill (asset generation)
+    └── <project-guide>/      # capture recipes, runtime traps, conventions
 ```
 
-In-engine capture harness (Godot 4 node shape):
+In-game capture harness, for runs outside the editor:
 
 ```
 Main (Node)
@@ -85,9 +78,9 @@ Main (Node)
     # saves PNGs to user://proof/ on trigger
 ```
 
-## Capture Harness (GDScript, adaptation)
+## Capture Harness (GDScript)
 
-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:
+Godogen's own capture code is not public; this is an adaptation. Inside a Summer session, prefer `summer_screenshot target:"game"` and `RunVerification` frames, and use this autoload for unattended runs outside the editor.
 
 ```gdscript
 extends Node
@@ -135,89 +128,78 @@ 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`):
+Encode the PNG sequence (resolve `user://` to its absolute path first):
 
 ```bash
-ffmpeg -framerate 2 -i user://proof/%03d_rec.png -c:v libx264 -pix_fmt yuv420p proof.mp4
+ffmpeg -framerate 2 -i <user_dir>/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)
+Unattended Linux runs need a real display for real rendering: run the engine under `xvfb-run -a`.
 
-This is the piece SummerEngine's validation should adopt:
+## The Visual QC Loop
 
 ```
 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
+2. COMPILE GATE summer_get_script_errors on changed files, then summer_get_diagnostics
+3. RUN + CAPTURE summer_play, then capture frames 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"
+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.
+- **Bounded.** Hard cap on rounds (see Tunables). The run closes with a proof recording; it does not iterate forever.
+- **Same agent verifies.** Do not add a separate verifier model. Godogen tried it and dropped it.
+- **Defects must be visible.** The review asks for concrete visual observations tied to the brief ("character sprite missing; brief asks for chunky iconic sprites"), not "looks wrong".
+- **Engine traps belong in the guide.** Recurring "survives compile, fails at runtime" defects go into the project guide 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 Generation
 
-asset-gen is the **sole published skill** in a godogen game repo — everything else the agent recreates from the engine guide.
+Godogen calls external image, video and image-to-3D providers with their own API keys, then cuts animated sprites from generated video (frame extraction, loop detection, background removal, imagemagick for resize and crop). In Summer, route asset work through `asset-strategy` and the Summer generation tools (`summer_generate_image`, `summer_generate_3d`, `summer_generate_video`) instead of wiring provider keys into the project.
 
 ## 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.
+1. **Write the thin runtime**: the brief in `.summer/GameSoul.md`, the delivery contract and involvement mode in `.summer/build-plan.md`, and a one-page project guide (how to run, how to capture, known runtime traps). Grow the guide every time a defect survives the compile gate.
+2. **Set up capture**: inside a Summer session, `summer_play` plus `summer_screenshot target:"game"`. For unattended Linux runs, add xvfb, ffmpeg and vulkan-tools, and check the GPU path with `vulkaninfo --summary`. A software-renderer fallback on a GPU host is a misconfiguration to fix before trusting any QC frame.
+3. **Add `ProofCapture`** (GDScript above) as an autoload when capturing outside the editor; wire triggers to scene-loaded, state-changed and recording mode.
+4. **Run the compile gate** before every capture round.
+5. **Run the QC loop**: capture → self-review → structured defect list → fix → re-capture, capped at `max_qc_rounds`. The review receives the original brief plus the latest frames and outputs findings in a fixed JSON shape.
+6. **Close with proof**: 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**: for an open-ended task, show the live game early and checkpoint at taste, scope and cost decisions; for a finished brief, run unattended and close with proof.
 
 ## Tunables
 
-| Parameter | Meaning | Godogen reference |
+| Parameter | Meaning | Reference value |
 |---|---|---|
-| `max_qc_rounds` | hard cap on capture→fix iterations | bounded delivery, not infinite |
+| `max_qc_rounds` | hard cap on capture→fix iterations | bounded, never open-ended |
 | 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 |
+| Capture triggers | when screenshots fire (scene load / state change / timer) | defined in the project guide |
+| Record fps | frame rate of the QC strip | 2 fps is enough for review |
+| Verification model | which agent reviews frames | the host agent itself; 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.
+- **Trusting a clean compile.** The compile gate is necessary, never sufficient.
+- **Software-renderer frames.** SwiftShader, llvmpipe and lavapipe output looks wrong and misleads the QC loop. On a GPU host it means the capture path is misconfigured.
+- **Unbounded verification loops.** Without `max_qc_rounds` the agent iterates forever on taste-level nitpicks. Close with proof.
+- **Adding a separate verifier model.** Godogen tried it and found no extra signal.
+- **Capturing before the frame settles.** Grab the viewport after `frame_post_draw` or a short delay, or screenshots show half-rendered scenes and produce false defects.
+- **Headless noise.** Headless runs can print harmless RID warnings on quit. Do not let the QC loop treat engine noise as defects.
+- **An all-black screenshot** usually means the viewport had not redrawn. Recapture before calling it a defect.
 
 ## Verification
 
-Not summerengine-verified. To validate an implementation:
+Not yet verified in Summer Engine. 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.
+1. Scaffold a project and confirm the agent builds a runnable game from the brief and the one-page guide alone.
+2. Run a small brief end to end; confirm the pipeline produces a running build, not just code.
+3. Introduce a visible defect (a broken sprite, a missing material); confirm the self-review finds 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).
+5. Confirm the compile gate runs before every capture round and that frames come from hardware rendering.
 
 ## 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.
+`extracted`. The architecture (thin runtime, manifest, engine guide, asset-gen), proof over claims, self-verification from captured frames, the dropped verifier model, the C# rationale, the capture tooling and the two involvement modes come from Godogen's public README, CHANGELOG and setup notes. The `ProofCapture` script, the QC-loop JSON protocol and the Summer mapping are adaptations; Godogen's internal prompt and guide files are not public.

package/library/skills/godogen-visual-proof-game-generation/resource.yaml

@@ -9,7 +9,6 @@ use_when:
   - "set up headless capture so an unattended generation run ends with a 15-20 second proof clip"
 do_not_use_when:
   - "large hand-authored production work, purely logical code fixes with no visual component, or hosts with no GPU or headless capture path"
-  - "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"
 facets:
   lifecycle:
     - build

package/library/skills/headless-scripting/SKILL.md

@@ -21,7 +21,7 @@ This is the widest capability surface you have, and it is the one you are least
 <engine-binary> --headless --disable-crash-handler --path <project-dir> -s res://<script>.gd
 ```
 
-**Always pass `--disable-crash-handler` on an agent-driven run.** Summer's handler shells out to `atos` from inside a signal handler; when anything does go wrong it turns a clean failure into a hang or a cascade. Three agent-triggered crashes in eight minutes were traced to this on 2026-07-25.
+**Always pass `--disable-crash-handler` on an agent-driven run.** Summer's handler shells out to `atos` from inside a signal handler; when anything does go wrong it turns a clean failure into a hang or a cascade of crashes.
 
 ### Lint before you boot
 
@@ -53,7 +53,7 @@ Exit codes lie in both directions here.
 <EXTREMELY-IMPORTANT>
 **Every engine launch you make is `--headless`.** The user did not ask you to open anything. A window that appears unasked steals focus, interrupts whatever they were doing, and is indistinguishable from a crash or a bug from their side. This is a product rule, not a convenience.
 
-The one exception is the verify instance, and it is safe precisely because it is not visible: `--summer-verify` opens a real rendering window that is **hidden, `NO_FOCUS`, and positioned at `(-32000,-32000)`** (`main/main.cpp:2363` and following). That is why it can produce real pixels without ever appearing. Never reproduce the "I need a renderer" reasoning by launching a plain windowed editor — use `--summer-verify`.
+The one exception is the verify instance, and it is safe precisely because it is not visible: `--summer-verify` opens a real rendering window that is **hidden, `NO_FOCUS`, and positioned at `(-32000,-32000)`**. That is why it can produce real pixels without ever appearing. Never reproduce the "I need a renderer" reasoning by launching a plain windowed editor — use `--summer-verify`.
 
 If you genuinely believe the user needs to see the editor, ask them first.
 </EXTREMELY-IMPORTANT>
@@ -73,12 +73,12 @@ If neither is available (an older engine build that predates `engineBinaryPath`,
 | Linux | `~/.summer/engine/summer-linux-x86_64`, or `$SUMMER_ENGINE_BINARY` (see `running-in-the-cloud`) |
 
 <EXTREMELY-IMPORTANT>
-There is no `godot` binary on a Summer user's machine. `godot --headless`, `godot4`, `/usr/local/bin/godot` — none of these exist. A command built on that name fails with "command not found" on every single user, and no amount of retrying changes it. This skill exists partly because that exact instruction shipped in our own docs for months.
+There is no `godot` binary on a Summer user's machine. `godot --headless`, `godot4`, `/usr/local/bin/godot` — none of these exist. A command built on that name fails with "command not found" for every user, and no amount of retrying changes it.
 </EXTREMELY-IMPORTANT>
 
 ### The script must extend `SceneTree` or `MainLoop`
 
-`-s` does not load an arbitrary script. `main/main.cpp` instantiates it as the process's main loop, and rejects anything that is not one.
+`-s` does not load an arbitrary script. The engine instantiates it as the process's main loop, and rejects anything that is not one.
 
 ```gdscript
 extends SceneTree
@@ -92,7 +92,7 @@ func _initialize():
 
 Always call `quit()`. There is no other exit.
 
-**The trap:** a script extending `Node` (the reflex, since almost all GDScript does) is a wedge, not an error. The engine's rejection path calls `OS.alert()`, and on macOS that is an `NSAlert` `runModal` with **no headless guard** (`platform/macos/os_macos.mm:352-369`). The process blocks forever on a modal dialog that has no window to appear in. You get **no output at all** and a hung process that must be killed. Measured: five orphaned processes accumulated in one session before the cause was found.
+**The trap:** a script extending `Node` (the reflex, since almost all GDScript does) is a wedge, not an error. The engine's rejection path calls `OS.alert()`, and on macOS that is an `NSAlert` `runModal` with **no headless guard**. The process blocks forever on a modal dialog that has no window to appear in. You get **no output at all** and a hung process that must be killed. Measured: five orphaned processes accumulated in one session before the cause was found.
 
 If a headless run produces zero output and never returns, check the first line of your script before you check anything else.
 
@@ -262,13 +262,13 @@ Measured on 0.5.55: `port 6550 -> 6551`, new token, editor still alive on 6550 a
 
 So on a shipped build: run `--import` against a throwaway copy where you can, warn the user before running it against their open project, and tell them to restart the editor afterwards if their agent connection drops.
 
-**Fixed on `main` but not yet in any shipped binary** (`_should_publish_discovery`, commit `420222554e`; tracked as SUM-161): batch-mode invocations — `--import`, `--summer-verify`, `--export-*`, `-s`, `--headless`, `--quit-after` — no longer publish. Once that ships, this warning applies only to older builds. Plain `--headless -s` never started the server on any build, so everything else in this skill is unaffected.
+A later engine fix stops batch-mode invocations (`--import`, `--summer-verify`, `--export-*`, `-s`, `--headless`, `--quit-after`) from publishing. On a build with that fix this warning does not apply; if you cannot tell which build is installed, follow the precautions above. Plain `--headless -s` never started the server on any build, so everything else in this skill is unaffected.
 </EXTREMELY-IMPORTANT>
 
 Two lifecycle facts that decide the shape of every headless run:
 
 - **There is a hard work-completion floor between 3 and 5 seconds.** Fresh project, 8 small PNGs, editor killed at N seconds: at **3s, 0/8 imports landed in 10/10 cycles** — it boots, gets killed mid-scan, and accomplishes nothing. At **5s, 8/8 landed every cycle.** Never give an import a 3-second budget.
-- **`--headless --editor` is not a filesystem watcher.** It never notices files created after boot — 6 assets added 12s in, 45s wait, 0 imported. The rescan is driven by `NOTIFICATION_APPLICATION_FOCUS_IN` (`editor_node.cpp:1096`) and headless never fires a focus event. A long-lived headless editor serves a boot-time snapshot forever.
+- **`--headless --editor` is not a filesystem watcher.** It never notices files created after boot — 6 assets added 12s in, 45s wait, 0 imported. The rescan is driven by `NOTIFICATION_APPLICATION_FOCUS_IN`, and headless never fires a focus event. A long-lived headless editor serves a boot-time snapshot forever.
 
 Both ends of the lifecycle are broken, differently: short runs do no work, long ones go stale. **Boot → act → exit is the only shape that works today.**
 
@@ -379,7 +379,7 @@ Four measured instances of the same shape:
 
 1. Write the script with `summer_write_file` (or your own shell) into the project.
 2. Get the binary from `summer_get_project_context` → `engineBinaryPath`.
-3. Run it. **Read stdout** — GDScript errors go there, and a script that failed to parse still exits cleanly-looking.
+3. Run it. **Read stdout and stderr**: your `print()` output is on stdout, script errors are on stderr, and a script that failed to parse still exits 0.
 4. Verify the artifact exists on disk and check the `ResourceSaver.save()` return value. "The script ran" is not "the resource was written".
 5. If you wrote raw asset files, run `--import`.
 6. Delete throwaway scripts. Do not leave `probe_temp_3.gd` in a user's project.

package/library/skills/instantiate-asset-pack/SKILL.md

@@ -27,7 +27,7 @@ For wiring individual widget slices (9-slice panels, progress bars, toggles), th
 
 - User wants a single slice → import it directly as a `Sprite2D` (or `use-widget-asset` if it's a UI widget).
 - User wants to **generate** a new pack → `create-asset-sheet`.
-- User wants to apply a slice as a material/texture on a 3D mesh → not the pack flow; see `asset_pipeline.json`.
+- User wants to apply a slice as a material/texture on a 3D mesh → not the pack flow; see `asset-strategy`.
 
 ## Pack JSON shape
 
@@ -98,12 +98,15 @@ Delegate the actual wiring (percentage-to-pixel conversion, node-specific props)
 
 ## Examples
 
+Both examples are `summer_batch` arguments; `scenePath` names the scene that receives the nodes.
+
 ### Example 1 — Standalone slice import
 
 Pack has one non-composite slice, `crate_wooden`, no widget metadata. Place it at scene origin:
 
 ```json
 {
+  "scenePath": "res://scenes/level.tscn",
   "ops": [
     {
       "op": "AddNode",
@@ -138,6 +141,7 @@ Pack has a composite parent `settings_panel` (filtered out) plus three children:
 
 ```json
 {
+  "scenePath": "res://ui/settings.tscn",
   "ops": [
     {
       "op": "AddNode",
@@ -224,7 +228,7 @@ Pack has a composite parent `settings_panel` (filtered out) plus three children:
 
 After this, hand `panel_bg` and `apply_button` to `use-widget-asset` to set `patch_margin_*` from their `widget.frameMargins`.
 
-Note the ops format: `position` is the **Godot string** `"Vector2(0, 0)"`, not a JSON object. `z_index` is a bare integer. This is the format Summer Engine expects — see `../../references/mcp-tools-reference/mcp-tools-reference.md`.
+Note the ops format: `position` is the **engine variant string** `"Vector2(0, 0)"`, not a JSON object. `z_index` is a bare integer. This is the format Summer Engine expects — see `../../references/mcp-tools-reference/mcp-tools-reference.md`.
 
 ## Failure modes
 
@@ -240,4 +244,4 @@ Note the ops format: `position` is the **Godot string** `"Vector2(0, 0)"`, not a
 
 - `create-asset-sheet` — production side; how the pack was made.
 - `use-widget-asset` — wiring an individual widget slice (NinePatchRect, TextureProgressBar geometry).
-- `asset_pipeline.json` — broader find-or-generate -> import -> apply flow.
+- `asset-strategy` — broader find-or-generate -> import -> apply flow.

package/library/skills/investigating-bugs/SKILL.md

@@ -230,9 +230,9 @@ If you catch yourself thinking:
 
 **ALL of these mean: STOP. Return to Phase 1.**
 
-**If 3+ fixes failed:** Question the architecture (see Phase 4.5)
+**If 3+ fixes failed:** Question the architecture (Phase 4, step 5)
 
-## the user's Signals You're Doing It Wrong
+## Signals From the User That You're Doing It Wrong
 
 **Watch for these redirections:**
 - "Is that not happening?" - You assumed without verifying
@@ -274,7 +274,7 @@ If systematic investigation reveals issue is truly environmental, timing-depende
 3. Implement appropriate handling (retry, timeout, error message)
 4. Add monitoring/logging for future investigation
 
-**But:** 95% of "no root cause" cases are incomplete investigation.
+**But:** most "no root cause" cases are incomplete investigation.
 
 ## Supporting Techniques
 
@@ -288,11 +288,3 @@ These techniques are part of systematic debugging and available in this director
 - **verification-before-completion** - Verify fix worked before claiming success
 - **debug** - The Summer-specific triage loop (script errors → console → debugger → probe)
 - **playtesting-a-feature** - When the fix is a gameplay behaviour that has to be walked
-
-## Real-World Impact
-
-From debugging sessions:
-- Systematic approach: 15-30 minutes to fix
-- Random fixes approach: 2-3 hours of thrashing
-- First-time fix rate: 95% vs 40%
-- New bugs introduced: Near zero vs common

package/library/skills/investigating-bugs/condition-based-waiting.md

@@ -79,8 +79,6 @@ async function waitFor<T>(
 }
 ```
 
-See `condition-based-waiting-example.ts` in this directory for complete implementation with domain-specific helpers (`waitForEvent`, `waitForEventCount`, `waitForEventMatch`) from actual debugging session.
-
 ## Common Mistakes
 
 **Bad: Polling too fast:** `setTimeout(check, 1)` - wastes CPU
@@ -105,11 +103,3 @@ await new Promise(r => setTimeout(r, 200));   // Then: wait for timed behavior
 1. First wait for triggering condition
 2. Based on known timing (not guessing)
 3. Comment explaining WHY
-
-## Real-World Impact
-
-From debugging session (2025-10-03):
-- Fixed 15 flaky tests across 3 files
-- Pass rate: 60% → 100%
-- Execution time: 40% faster
-- No more race conditions

package/library/skills/investigating-bugs/root-cause-tracing.md

@@ -153,11 +153,3 @@ digraph principle {
 **Before operation:** Log before the dangerous operation, not after it fails
 **Include context:** Directory, cwd, environment variables, timestamps
 **Capture stack:** `new Error().stack` shows complete call chain
-
-## Real-World Impact
-
-From debugging session (2025-10-03):
-- Found root cause through 5-level trace
-- Fixed at source (getter validation)
-- Added 4 layers of defense
-- 1847 tests passed, zero pollution

package/library/skills/lumera-single-image-scene-reconstruction/SKILL.md

@@ -13,13 +13,13 @@ tags:
 confidence: extracted
 ---
 
-# Single-Image → Editable Scene Reconstruction (Lumera-style) in SummerEngine
+# Single-Image → Editable Scene Reconstruction (Lumera-style) in Summer Engine
 
 ## Outcome
 
-Turn one reference image into an **editable, engine-native scene** in SummerEngine: individual `MeshInstance3D` objects with transforms, countable parametric light nodes, and an HDR environment probe — not a fused point cloud, Gaussian splat, or baked texture. This is the adaptation of the Lumera pipeline (arXiv:2607.20889, Tsinghua AIRSUN lab) from UE5 to SummerEngine.
+Turn one reference image into an **editable, engine-native scene** in Summer Engine: individual `MeshInstance3D` objects with transforms, countable parametric light nodes, and an HDR environment probe — not a fused point cloud, Gaussian splat, or baked texture. This adapts the Lumera pipeline (arXiv:2607.20889, Tsinghua AIRSUN lab), which was built on another engine, to Summer Engine.
 
-**Honesty caveat:** Lumera itself is UE5-only with no public code as of retrieval (2026-08-30); the paper explicitly lists Godot/engine-portable extraction as future work. This skill documents the architecture and the parts an agent can build in SummerEngine today (assembly, scene representation, refinement loop, evaluation), and flags the parts that require external model components (VLM box/light parsers, per-object mesh generator, HDR estimator).
+**Caveat:** Lumera has no public code, and the paper lists engine-portable extraction as future work. This skill documents the architecture and the parts an agent can build in Summer Engine today (assembly, scene representation, refinement loop, evaluation), and flags the parts that require external model components (VLM box/light parsers, per-object mesh generator, HDR estimator).
 
 ## When to Use
 
@@ -44,11 +44,11 @@ Lumera's stages (from paper abstract + appendices):
 3. **Per-object mesh reconstruction** — a mesh per parsed box.
 4. **HDR environment estimation** — environment probe (IntrinsicHDR partially compensates for SkyLight/unseen near-camera lights).
 5. **Bounded agentic refinement loop** — dual-agent (geometry stage, then light stage) edits + verifies against the reference image.
-6. **Assembly** — emit engine-native scene (Blender/UE5 in the paper; `.tscn` in SummerEngine).
+6. **Assembly** — emit an engine-native scene (`.tscn` in Summer Engine).
 
-Dataset backing it: Lumera-2K, 2,513 UE5 projects → 3.73M components, 63M object instances, 102.6K parametric lights, 95.1K camera views.
+Dataset backing it: Lumera-2K, 2,513 game-engine projects → 3.73M components, 63M object instances, 102.6K parametric lights, 95.1K camera views.
 
-## Scene / Node Shape (SummerEngine target)
+## Scene / Node Shape (Summer Engine target)
 
 The assembly stage should emit this node tree so output stays inspectable/editable:
 
@@ -65,10 +65,10 @@ ReconstructedScene (Node3D)
     ├── OmniLight3D / SpotLight3D / DirectionalLight3D × M
     │     # position/rotation from (x,y,z); color from (r,g,b);
     │     # light_energy from I (mind log-scale calibration, see Tunables)
-    └── (SkyLight-equivalent is carried by WorldEnvironment in Godot)
+    └── (the sky-light equivalent is carried by WorldEnvironment)
 ```
 
-Keep objects and lights as **separate siblings under named containers** — this mirrors UE5's component structure and is what makes the scene "editable" rather than "looks 3D".
+Keep objects and lights as **separate siblings under named containers**. That separation is what makes the scene editable rather than just looking 3D.
 
 ## Implementation Steps
 
@@ -97,15 +97,15 @@ Add a **repair layer** on ingest: drop/fix invalid labels, non-positive sizes, d
 
 ### 2. Box + light parsing (external VLM components)
 
-Lumera-Box/Lumera-Light are VLMs SFT'd on Lumera-2K; there is no public checkpoint. Options: use a hosted VLM prompted to emit the JSON tuples above, or fine-tune an open VLM on your own engine-exported scenes (Godot scenes are text `.tscn` and trivially exportable — this is the "build Lumera-2K for your engine" step the paper identifies as missing for non-UE5 engines).
+Lumera-Box/Lumera-Light are VLMs SFT'd on Lumera-2K; there is no public checkpoint. Options: use a hosted VLM prompted to emit the JSON tuples above, or fine-tune an open VLM on your own engine-exported scenes (`.tscn` scenes are text and easy to export; this is the "build Lumera-2K for your engine" step the paper identifies as missing for other engines).
 
 ### 3. Per-object mesh generation + HDR environment estimation
 
-Also external model components in Lumera (per-object mesh reconstruction; IntrinsicHDR-style environment estimation). For a SummerEngine blockout you can substitute: box mesh (`BoxMesh` sized to the parsed box) per object and a generated/estimated panorama `Sky`. Swap in real reconstructed meshes later without changing the schema.
+Also external model components in Lumera (per-object mesh reconstruction; IntrinsicHDR-style environment estimation). For a Summer Engine blockout you can substitute: box mesh (`BoxMesh` sized to the parsed box) per object and a generated/estimated panorama `Sky`. Swap in real reconstructed meshes later without changing the schema.
 
 ### 4. Assembly: write a `.tscn`
 
-Deterministic GDScript/tool script: instantiate the node shape above from the repaired records. Godot's `.tscn` is text — generating it directly keeps the output diffable and versionable. Save with `PackedScene.pack()` / `ResourceSaver.save()` from an editor tool.
+Deterministic GDScript/tool script: instantiate the node shape above from the repaired records. A `.tscn` is text, so generating it directly keeps the output diffable and versionable. Save with `PackedScene.pack()` / `ResourceSaver.save()` from an editor tool.
 
 ### 5. Bounded dual-agent refinement loop
 
@@ -148,17 +148,17 @@ Reproduce the paper's metrics on held-out scenes so improvements are measurable:
 - **Per-light localization is weak** (F1 0.209 @ 0.5 m) while scene-level light *count* recall is strong (0.998). Frame the output as "right number of lights, roughly right places."
 - **SkyLight / near-camera lights whose source is off-screen** are not supervised; the environment probe (IntrinsicHDR) only partially compensates.
 - **Large outdoor scenes drift geometrically** (~17 m Chamfer-L2); consider joint camera+geometry calibration if you need metric outdoor consistency.
-- **Engine conventions don't transfer for free** — the dataset and light conventions are UE5's; Godot's light units/probes differ, so recalibrate intensity and validate the representation on Godot-native scenes.
+- **Engine conventions don't transfer for free.** The dataset's light conventions come from another engine; Summer Engine's light units and probes differ, so recalibrate intensity and validate the representation on Summer-native scenes.
 
 ## Verification
 
-Not summerengine-verified. To validate an implementation in SummerEngine:
+Not yet verified in Summer Engine. To validate an implementation:
 
 1. Assemble a scene from a test image; confirm the `.tscn` contains separate, selectable `MeshInstance3D`s and light nodes (editability check).
 2. Move/replace one mesh and re-tune one light in the editor without breaking the scene.
-3. Run the evaluation harness (§6) against a held-out set of known Godot scenes and compare to the reference numbers above.
+3. Run the evaluation harness (§6) against a held-out set of known scenes and compare to the reference numbers above.
 4. Confirm the refinement loop terminates within `T_g`/`T_l` and the history window never exceeds the VLM context budget.
 
 ## Confidence
 
-`extracted` — Architecture, metrics, refinement-loop design, and limitations are drawn directly from the arXiv paper (abstract, intro, appendices H.7–I as retrieved; middle method sections were truncated and are not documented here) and the author's announcement post. The SummerEngine node mapping and GDScript schema are adaptations, not from the sources; no public Lumera code exists to reference.
+`extracted` — Architecture, metrics, refinement-loop design, and limitations are drawn directly from the arXiv paper (abstract, intro, appendices H.7–I as retrieved; middle method sections were truncated and are not documented here) and the author's announcement post. The Summer Engine node mapping and GDScript schema are adaptations, not from the sources; no public Lumera code exists to reference.

package/library/skills/lumera-single-image-scene-reconstruction/resource.yaml

@@ -10,7 +10,6 @@ use_when:
 do_not_use_when:
   - "you only need a visual backdrop (a splat or depth-mesh bake is cheaper), large unbounded outdoor scenes, or exact light positions and intensities"
   - "Lumera itself has no public code; the VLM box/light parsers, per-object mesh generator, and HDR estimator are external components you must supply"
-  - "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"
 facets:
   lifecycle:
     - build

package/library/skills/make-game/SKILL.md

@@ -40,9 +40,9 @@ Distilled blueprints for common genres live in this skill's `references/` folder
 | Third-person action / 3D platformer | `references/3d-third-person.md` | `references/3d-third-person-systems.md` | Node3D / CharacterBody3D / SpringArm3D |
 | First-person horror | `references/3d-horror.md` | `references/3d-horror-systems.md` | Node3D / CharacterBody3D / Camera3D on Head |
 
-No playbook (racing, sandbox, sim): build fresh through the phases below. The playbooks lean on these system skills — load one when its mechanic comes up: `character-movement`, `camera-rigs`, `combat-basics`, `save-load`, `ui-basics`, `setup-multiplayer`.
+No playbook (racing, sandbox, sim): build fresh through the phases below. The playbooks lean on these system skills — load one when its mechanic comes up: `character-movement`, `camera-rigs`, `combat-basics`, `save-load`, `ui-basics`, `multiplayer-project`.
 
-Two rules from the playbooks apply to every genre:
+These rules from the playbooks apply to every genre:
 
 - **2D scales to the viewport.** Set `display/window/stretch/mode = canvas_items` and `stretch/aspect = expand`; UI uses Control anchors; code-positioned nodes compute from `get_viewport_rect().size`. Never hardcode 1920x1080.
 - **Playable slice, not tech demo.** Name the core loop in one sentence; every input gets feedback (tween, sound, particle, flash, shake); progression is visible; a restart exists. The bar is "feels good for 30 seconds".
@@ -198,7 +198,7 @@ Repeat until every mechanic in the plan is implemented OR the user calls cut.
 Skill: art-direction
 ```
 
-That writes `.summer/art-bible.md` if it doesn't exist, then guides the lighting / material / palette pass. Use `3d-lighting` for the actual scene work. If the game plays in the browser or is exported for the web, it runs the Compatibility renderer only: follow `web-compatibility-look` instead of Forward+-only features (SDFGI, SSAO, SSR, volumetric fog), and keep `rendering/renderer/rendering_method` on `gl_compatibility`.
+That writes `.summer/art-bible.md` if it doesn't exist, then guides the lighting / material / palette pass. Use `3d-lighting` for the actual scene work. For the web, check the target first. A summer.games web build (`summer_export_game` with `targets:["web"]`) runs on Summer's WebGPU template, which needs the Forward+ or Mobile renderer. A WebGL 2 target runs the Compatibility renderer only: follow `web-compatibility-look` there, avoid Forward+-only features (SDFGI, SSAO, SSR, volumetric fog), and keep `rendering/renderer/rendering_method` on `gl_compatibility`.
 
 ```
 Skill: audio-direction
@@ -277,8 +277,6 @@ By the end of a successful run, the user has:
 - `summer_get_diagnostics` returns clean
 - `summer_play` runs end-to-end and the win condition is reachable
 
-That's a real game. Not a half-finished prototype.
-
 ## Closing line
 
 When all phases are done:

package/library/skills/make-game/references/2d-platformer.md

@@ -56,7 +56,7 @@ separate Area under the player masking only the Enemies layer.
 
 ## Building the level with a TileMap
 
-Use a `TileMapLayer` (Godot 4.3+) for the solid world. Create a `TileSet`, paint
+Use a `TileMapLayer` for the solid world. Create a `TileSet`, paint
 the collision polygon on the solid tiles, put the layer on the World collision
 layer. The player collides with it for free - no per-tile StaticBody.