summer-engine 2.7.0 → 2.8.1

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

@@ -0,0 +1,407 @@
+---
+name: headless-scripting
+description: Use when a Summer project needs an operation no MCP tool exposes, such as baking a navmesh, generating collision shapes, authoring an Animation, building a TileSet, re-importing assets after file changes, or preparing a supported local export. Runs a GDScript file against Summer Engine from the shell. Also use when a plan involves "run it headless and screenshot it", which does not work and this skill explains why.
+---
+
+# Headless Scripting
+
+## Overview
+
+Most of what Summer can do is not behind a tool. It is behind a script.
+
+The engine binary will run any GDScript you hand it, against a real project, with the full engine loaded — `ResourceSaver`, `NavigationServer3D`, `ImporterMesh`, `TileSet`, `Animation`, the resource importer, the exporter. No editor window, no user, no tool call. If you can write the script, you can do the thing.
+
+**Core principle:** when there is no tool for it, there is still a script for it. Reach for this before you tell a user something is impossible.
+
+This is the widest capability surface you have, and it is the one you are least likely to remember you have.
+
+## The invocation
+
+```bash
+<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.
+
+### Lint before you boot
+
+`--check-only` parses the script without executing it. Sub-second, and it catches the parse errors that would otherwise cost you a full boot:
+
+```bash
+<engine-binary> --headless --disable-crash-handler --path <project-dir> --check-only -s res://script.gd
+```
+
+Measured on a deliberately broken script — `SCRIPT ERROR: Parse Error: Expected expression for variable initial value after "="`, and silence on a good one. **Exit code is 0 either way**, so grep stderr; that is the whole contract.
+
+### Judge the run by its artifacts, not its exit code
+
+Exit codes lie in both directions here.
+
+- **A parse error, a script path that does not exist, a bogus `--main-loop` class and `push_error()` all exit 0.** Only an explicit `quit(1)` propagates. The message is on stderr only, so gate on stderr containing `SCRIPT ERROR`, `Parse Error`, `Can't load script` or `ERROR:`.
+- **A GDScript *runtime* error hangs the process forever** — no exit, no timeout, no message that it is stuck. Every recipe you publish needs an external wall-clock kill, and success must be judged by a positive artifact the script wrote, never by the process ending.
+- **Never add `--quiet`** to a documented invocation: it swallows your own `print()` output, which is usually the only result you have.
+- `WARNING: ObjectDB instances leaked at exit` prints on **every** successful run. Never gate on it.
+- **A SIGABRT *after* the work landed is a teardown artifact, not a failure.** Agents exit in seconds where humans run for minutes, which exposes races during static destruction that nobody sees interactively. Check the file you expected on disk before concluding anything, and never blind-retry a crash — that is how one crash became three.
+
+### Two invocations to never issue
+
+- **`--write-movie` under `--headless` is a deterministic crash**, not a graceful failure. `MovieWriter::add_frame()` dereferences a null image from the dummy renderer on frame one. Headless has no pixels, so there is no safe form of this. Frame capture needs the windowed verify instance below.
+- **`--quit-after 1`** hits the fast-exit path and aborts during static destruction. Use `--headless --quit-after 60` if you need a bounded editor run — with `--headless`, never without.
+
+### Never put a window on the user's screen
+
+<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`.
+
+If you genuinely believe the user needs to see the editor, ask them first.
+</EXTREMELY-IMPORTANT>
+
+### Finding the binary — do not guess
+
+Call `summer_get_project_context` and read **`engineBinaryPath`**. That is the running engine's own `OS.get_executable_path()`, already resolved through the macOS `.app` bundle to the real inner executable.
+
+If you are inside a script that is already running in the engine, it is just `OS.get_executable_path()`.
+
+If neither is available (an older engine build that predates `engineBinaryPath`, or no editor running), fall back to the install location for the platform:
+
+| Platform | Path |
+|---|---|
+| macOS | `/Applications/Summer.app/Contents/MacOS/Summer` |
+| Windows | `%LOCALAPPDATA%\Summer\current\Summer.exe` |
+| Linux | wherever the AppImage/binary was installed |
+
+<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.
+</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.
+
+```gdscript
+extends SceneTree
+
+func _initialize():
+    # your work here
+    quit()          # or the process runs forever
+```
+
+`_initialize()` runs before the first frame. If you need frames to have elapsed — physics settled, nodes `_ready`-ed — `await process_frame` inside `_initialize()`, or use `_process(delta)` and `quit()` when done.
+
+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.
+
+If a headless run produces zero output and never returns, check the first line of your script before you check anything else.
+
+## What this unlocks
+
+Every one of these was run against the shipped binary. The result column is measured output, not expectation.
+
+| Task | Result |
+|---|---|
+| Collision shape from a mesh | `create_trimesh_shape()` → 12 faces; `create_convex_shape()` → 8 points |
+| Navmesh bake | `NavigationServer3D.bake_from_source_geometry_data()` → 2 polys / 4 verts, saved to `.tres` |
+| LOD generation | `ImporterMesh` instantiable, `generate_lods()` callable |
+| Animation authoring | value + bezier + method tracks saved and reloaded with all 3 intact |
+| TileSet authoring | atlas source + per-tile collision polygon, saved to `.tres` |
+| Asset re-import | `--import` produced the `.import` sidecar and the `.ctex` |
+| Full export | hand-written `export_presets.cfg` + `--export-release` → a 144 MB runnable `.app` |
+
+Themes, shaders, audio bus layouts, input maps and project settings are the same story: plain resources, authored and saved from a script.
+
+### Bake a navmesh
+
+```gdscript
+extends SceneTree
+
+func _initialize():
+    var nav := NavigationMesh.new()
+    nav.cell_size = 0.25
+    nav.agent_radius = 0.5
+
+    var geo := NavigationMeshSourceGeometryData3D.new()
+    var ground := PlaneMesh.new()
+    ground.size = Vector2(10, 10)
+    geo.add_mesh(ground, Transform3D.IDENTITY)
+
+    NavigationServer3D.bake_from_source_geometry_data(nav, geo)
+    print("polys=", nav.get_polygon_count(), " verts=", nav.vertices.size())
+    ResourceSaver.save(nav, "res://levels/level1_nav.tres")
+    quit()
+```
+
+`ResourceSaver.save()` returns `0` (`OK`) on success. Check it — a silent non-zero is how you ship a level with no navmesh.
+
+Prefer parsing collision shapes over visual meshes as source geometry. `add_mesh()` on a visual mesh pulls geometry back off the GPU and warns loudly about it.
+
+### Generate a collision shape
+
+```gdscript
+var mesh: Mesh = load("res://models/rock.glb").instantiate().get_child(0).mesh
+ResourceSaver.save(mesh.create_trimesh_shape(), "res://models/rock_col.tres")   # static
+ResourceSaver.save(mesh.create_convex_shape(),  "res://models/rock_cvx.tres")   # dynamic
+```
+
+Trimesh for static geometry, convex for anything that moves — a `RigidBody3D` with a concave shape is a physics bug, not a modelling choice.
+
+### Author an Animation
+
+```gdscript
+var anim := Animation.new()
+anim.length = 2.0
+
+var t := anim.add_track(Animation.TYPE_VALUE)
+anim.track_set_path(t, "Player:position")
+anim.track_insert_key(t, 0.0, Vector3.ZERO)
+anim.track_insert_key(t, 2.0, Vector3(0, 5, 0))
+
+var b := anim.add_track(Animation.TYPE_BEZIER)
+anim.track_set_path(b, "Player:modulate:a")
+anim.bezier_track_insert_key(b, 0.0, 1.0, Vector2(-0.2, 0), Vector2(0.2, 0))
+
+var m := anim.add_track(Animation.TYPE_METHOD)
+anim.track_set_path(m, "Player")
+anim.track_insert_key(m, 1.0, {"method": "on_landed", "args": []})
+
+ResourceSaver.save(anim, "res://animations/rise.tres")
+```
+
+Track paths are `NodePath:property` relative to the `AnimationPlayer`'s `root_node`. Getting that path wrong is the usual reason an animation loads fine and animates nothing.
+
+### Build a TileSet with collision
+
+```gdscript
+var ts := TileSet.new()
+ts.tile_size = Vector2i(16, 16)
+ts.add_physics_layer()
+
+var atlas := TileSetAtlasSource.new()
+atlas.texture = load("res://art/tiles.png")
+atlas.texture_region_size = Vector2i(16, 16)
+atlas.create_tile(Vector2i(0, 0))
+ts.add_source(atlas)
+
+var tile := atlas.get_tile_data(Vector2i(0, 0), 0)
+tile.add_collision_polygon(0)
+tile.set_collision_polygon_points(0, 0, PackedVector2Array([
+    Vector2(-8, -8), Vector2(8, -8), Vector2(8, 8), Vector2(-8, 8)
+]))
+
+ResourceSaver.save(ts, "res://levels/tiles.tres")
+```
+
+`add_physics_layer()` returns `void`, not the layer index. Layers are indexed in creation order from 0.
+
+### Build a scene from script
+
+`PackedScene.pack()` + `ResourceSaver.save()` is how you write a `.tscn` a script built. It has one trap that costs an entire run:
+
+<EXTREMELY-IMPORTANT>
+**`pack()` silently drops every node whose `owner` is not set**, and both `pack()` and `ResourceSaver.save()` return `0` anyway. You get two success codes and a scene missing most of its contents.
+
+Measured — a root with one owned child, one unowned sibling, and an unowned grandchild under the owned one:
+
+```
+PACK err=0
+SAVE err=0
+RELOADED children=[&"Owned"]        <- both unowned nodes gone, no error anywhere
+```
+
+Note the grandchild vanished too: being a descendant of an owned node is **not** enough. Every node you want persisted needs `.owner` set to the scene root. The root itself does not need one.
+</EXTREMELY-IMPORTANT>
+
+```gdscript
+var root := Node2D.new()
+
+var layer := TileMapLayer.new()
+layer.tile_set = ts
+root.add_child(layer)
+layer.owner = root              # omit this and the layer vanishes, silently
+
+var ps := PackedScene.new()
+ps.pack(root)
+ResourceSaver.save(ps, "res://levels/level1.tscn")
+```
+
+This is also the answer for tilemaps specifically. A `TileMapLayer`'s cells serialise into `tile_map_data`, a `PackedByteArray` — so "just hand-write the `.tscn`" stops being true the moment there are cells in it. Use `set_cell()` and pack the scene; do not try to edit that field as text.
+
+### Re-import assets you wrote to disk
+
+**This is the single most common way an agent breaks a project.** A `.png` written directly to disk is not a resource yet:
+
+```
+ERROR: No loader found for resource: res://raw.png (expected type: unknown)
+   at: _load (core/io/resource_loader.cpp:358)
+```
+
+The file exists. `FileAccess.file_exists()` returns `true`. `load()` fails anyway, because there is no `.import` sidecar and no imported `.ctex` in `.godot/imported/`.
+
+### Prefer the routes that need no import at all
+
+Reach for these before reaching for `--import`:
+
+1. **`ResourceSaver.save()` to `.tres` / `.res`.** No import step, no editor, no `.godot/` race, and it ships correctly in an exported build. Round-trips for `ImageTexture`, `AudioStreamWAV`, `AudioStreamOggVorbis`, `AudioStreamMP3`, `FontFile`, `ArrayMesh`, `Translation`, `AudioBusLayout`. (One trap: `PortableCompressedTexture2D` saves with `err 0` and reloads **empty** — use `ImageTexture`.)
+2. **`.dds` and `.po` load raw.** They are the only formats that need no `.import` and ship as-is. A DDS is a 128-byte header plus raw pixels, which a script can emit directly.
+3. **`summer_import_from_url`** already does its own rescan-and-settle in-process, so assets that arrive that way are registered without any of this.
+
+Only when none of those fit — you genuinely need a `.png` on disk to become a texture — run the import:
+
+```bash
+<engine-binary> --headless --disable-crash-handler --path <project-dir> --import
+```
+
+**Judge it by the `.import` sidecar and the file in `.godot/imported/`, not by the exit status.** If those exist the import succeeded, however the process died. Do not retry blindly. Measured 3/3 clean on 4.6.1; a wider sample put `--import` aborts at 2/12 against `--editor`'s 3/50, statistically the same background boot-abort rate rather than an `--import`-specific crash.
+
+<EXTREMELY-IMPORTANT>
+**On shipped builds up to 0.5.55, `--import` hijacks the user's editor connection.** It starts the local API server, which unconditionally overwrites `~/.summer/api-port` and mints a fresh `~/.summer/api-token` — machine-global, no project identity, last writer wins. When the import process exits, that pointer is left aimed at a **dead port with a dead token**, so the user's editor becomes unreachable and MCP reports "Summer Engine is not running" while their editor is plainly open.
+
+Measured on 0.5.55: `port 6550 -> 6551`, new token, editor still alive on 6550 and now unreachable.
+
+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.
+</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.
+
+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.**
+
+Measured before and after on the same file:
+
+```
+FILE_EXISTS=true   IMPORT_SIDECAR=false  → ERROR: No loader found for resource
+FILE_EXISTS=true   IMPORT_SIDECAR=true   → LOAD_RESULT=<CompressedTexture2D>
+```
+
+Run `--import` after **any** batch of raw asset files you wrote yourself — textures, audio, models. The MCP's `summer_import_from_url` already does its own rescan-and-settle, so assets that arrive that way are fine; assets you wrote with `summer_write_file` or your own shell are not.
+
+### Export a build
+
+`export_presets.cfg` is plain text you can write. Then:
+
+```bash
+<engine-binary> --headless --path <project-dir> --export-release "macOS" <out-dir>/Game.app
+```
+
+Exit code 0 and a real bundle on disk are the success condition — check both. Export templates for the engine's exact version must be installed, or the export fails.
+
+## The trap: `--headless` has no pixels
+
+<EXTREMELY-IMPORTANT>
+`--headless` loads the dummy rendering driver. `viewport.get_texture().get_image()` returns **null**:
+
+```
+ERROR: Parameter "t" is null.
+   at: texture_2d_get (servers/rendering/dummy/storage/texture_storage.h:106)
+GET_IMAGE=<Object#null>
+```
+
+**Any plan of the form "run the game headless and screenshot it" is dead on arrival.** It does not error usefully — it hands you a null and continues.
+
+Performance is equally meaningless there, but **not in the way it first looks.** Sampled every 30 frames across a 401-frame headless run of the same scene:
+
+```
+fps=1.0    draw_calls=0.0  objects=0.0     <- first ~1s
+fps=117.0  draw_calls=0.0  objects=0.0
+fps=145.0  draw_calls=0.0  objects=0.0
+```
+
+Two separate traps in that table:
+
+1. **`draw_calls` and `objects` are `0.0` at every sample, forever.** That is the real headless signature — there is no renderer to count. Those monitors never become meaningful.
+2. **The FPS number is not 1.0, and it is not real either.** It settles high (145 here) precisely *because* nothing is being drawn. Quoting it as the game's frame rate is worse than quoting nothing.
+
+And a third trap that is **not** headless-specific: `TIME_FPS` reads exactly `1.0` until it has about a second of history. A probe that samples too early reports 1 fps in a windowed instance too. A leading `1.0` is warm-up, not a stall — sample for at least a second before believing any frame rate.
+</EXTREMELY-IMPORTANT>
+
+The answer is not headless. The engine ships a second mode: an offscreen **windowed** instance with a real renderer, positioned far off-screen so the user never sees it. That is what `RunVerification` spawns, and you can spawn it directly:
+
+```bash
+<engine-binary> --path <project-dir> \
+  --summer-verify <abs-path-to-probe.gd> \
+  --summer-verify-out <abs-out-dir> \
+  --summer-verify-max 30
+```
+
+Note: **no `--headless`**. That is the entire difference.
+
+Measured in that instance, same project, same machine:
+
+```
+viewport_image_null : false          (1152x648, pixel(4,4) = the real rendered colour)
+display_server      : macOS          (Metal 4.0 — Forward+)
+draw_calls          : 1.0            (vs 0.0 headless, at every sample)
+frames saved        : 00_start.jpg  01_after_walk.jpg  02_after_jump.jpg
+```
+
+So: **scripting and authoring go through `--headless`. Seeing and measuring go through the verify instance.** Choose on that axis and you will not get a null.
+
+For writing probes — the `SummerProbeBase` API, the coroutine rules, what is and is not reproducible — see `summer:playtesting-a-feature`.
+
+## What a script genuinely cannot do
+
+Short list, and it is short on purpose. Everything not on it is worth attempting.
+
+- **Lightmap baking.** `LightmapGI::bake` is not runtime-callable. Editor process only.
+- **Occlusion culling bake.** `OccluderInstance3D.bake_single_node`, same.
+- **Anything needing `EditorInterface`.** Outside the editor, `ClassDB.can_instantiate("EditorScript")` is `false`.
+  **Trap:** `Engine.has_singleton("EditorInterface")` returns **`true`** even in a plain headless script — it lies. Retrieving the singleton then fails with `Can't retrieve singleton 'EditorInterface' outside of editor`. Test with `ClassDB.can_instantiate("EditorScript")`, which tells the truth.
+
+## Never verify a write by reading it back from the thing you wrote
+
+This is the single highest-yield rule in this document, because it is the failure mode with no symptom. In-process read-back returns what you set, from memory, whether or not anything reached disk or took effect. The check passes, the work is gone.
+
+Four measured instances of the same shape:
+
+| What you did | What reading it back says | What is actually true |
+|---|---|---|
+| `PackedScene.pack()` with unset `owner`s | `pack` 0, `save` 0 | Those nodes are not in the file |
+| `ProjectSettings.set_setting()` without `save()` | the new value | Nothing on disk; next boot has the old one |
+| A setting with a feature-tag override | the base value | The engine is using the override |
+| `PathFollow2D.progress = 50.0` | `50.0` | The node never moved |
+
+**Verify from a second process, or by re-reading the file from disk.** Cheapest reliable form: finish the script, then run a second one-liner that `load()`s the artefact fresh and prints what it found — which is exactly what the measurements in this document do. `ResourceSaver.save()` returning `0` means "the write was attempted without error", not "the thing you meant is in there".
+
+## Working pattern
+
+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.
+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.
+
+Keep scripts in the project (`res://` is required for `-s`), but name them so their purpose is obvious and clean up after yourself.
+
+## Red Flags — STOP
+
+| Red flag | Reality |
+|---|---|
+| `godot --headless ...` | That binary does not exist on any user machine. Use `engineBinaryPath`. |
+| A `-s` script that `extends Node` | Silent hang on an invisible modal. Must be `SceneTree` or `MainLoop`. |
+| Headless run returned nothing and never exited | You extended the wrong class. Kill it and fix line 1. |
+| "Run it headless and screenshot" | Headless has no pixels. Use the verify instance, without `--headless`. |
+| Profiling under `--headless` | `draw_calls`/`objects` are 0.0 forever; FPS is inflated by drawing nothing. Use the verify instance. |
+| Quoting a frame rate sampled in the first second | `TIME_FPS` reads 1.0 until it warms up, in every mode. |
+| Wrote a `.png`, then `load()`ed it | No loader found. Save a `.tres` instead, or run `--import`. |
+| `--import` against the user's open project on a shipped build | Hijacks their editor binding. Warn first. |
+| Killing an import at 3s | Measured 0/8 assets registered. The floor is ~5s. |
+| A long-lived `--headless --editor` as a file watcher | It never rescans. Boot, act, exit. |
+| Adding `--quiet` | Swallows your own print() output. |
+| Launching the editor without `--headless` | Pops a window onto the user's screen unasked. |
+| Ignoring `ResourceSaver.save()`'s return value | Non-zero is a silent failure that ships. |
+| `pack()` without setting `.owner` on every node | Two success codes, nodes missing from the file. |
+| Verifying a write by reading the object you just wrote | In-memory read-back passes whether or not it landed. |
+| Script with no `quit()` | Runs forever. |
+| "There's no tool for that, so it can't be done" | There is a script for it. Write the script. |
+
+**Related skills:**
+- `summer:playtesting-a-feature` — the verify instance, probes, and proving gameplay behaviour.
+- `summer:export-and-ship` — the full release pipeline this skill's export example is one step of.
+- `summer:verification-before-completion` — checking the artifact before claiming done.

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

@@ -176,7 +176,8 @@ You MUST complete each phase before proceeding to the next.
    - Automated test if possible
    - One-off test script if no framework
    - MUST have before fixing
-   - Use the `summer:test-driven-development` skill for writing proper failing tests
+   - Verify it red-green: run the test before the fix and confirm it FAILS for the stated reason. A test you never saw fail proves nothing.
+   - For a runtime game bug, the reproduction is a `RunVerification` probe: press the input, assert the state. Re-run the same probe after the fix.
 
 2. **Implement Single Fix**
    - Address the root cause identified
@@ -284,8 +285,9 @@ These techniques are part of systematic debugging and available in this director
 - **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling
 
 **Related skills:**
-- **summer:test-driven-development** - For creating failing test case (Phase 4, Step 1)
 - **summer:verification-before-completion** - Verify fix worked before claiming success
+- **summer:debug** - The Summer-specific triage loop (script errors → console → debugger → probe)
+- **summer:playtesting-a-feature** - When the fix is a gameplay behaviour that has to be walked
 
 ## Real-World Impact
 

package/skills/workflow/mcpupdate/SKILL.md

@@ -16,7 +16,7 @@ This skill lives in the **summer-cli** repo (the CLI + MCP + skills), normally a
 `<SummerEngine checkout>/tools/summer-cli/`. Paths below are relative to that repo root.
 
 - `src/mcp/tools/*.ts`: the `summer_*` MCP tool definitions ("ops": scene/asset/project/etc.)
-- `references/mcp-tools-reference.md`: human-readable tool reference
+- `../../../references/mcp-tools-reference.md`: human-readable tool reference
 - `src/mcp/tools/project-tools.ts` + `docs/MCP_FRESH_CHAT_PLAYBOOK.md`: the **agent playbook** returned by `summer_get_agent_playbook` (startup flow / defaults that steer agents)
 - `src/lib/skills-registry.ts`: how skills are discovered/surfaced to the agent
 - `skills/<category>/<name>/SKILL.md`: the **prompt-engineering skills** (e.g. `character-controllers/fps-controller`, `scene-and-project/make-game`, `level-design/design-level`, `visual-effects/*`)
@@ -53,7 +53,7 @@ node -e "import('./dist/lib/skills-registry.js').then(m=>{const r=m.SKILL_REGIST
    - `.codex-plugin/plugin.json`
    - `AGENTS.md`
    - `GEMINI.md`
-   - `references/mcp-tools-reference.md`
+   - `../../../references/mcp-tools-reference.md`
    - `docs/DEVELOPMENT.md`
    - `docs/SKILLS.md`
 
@@ -75,7 +75,7 @@ node -e "import('./dist/lib/skills-registry.js').then(m=>{const r=m.SKILL_REGIST
 2. **Open the exact file from the map above**. Do not scan the tree.
 3. **Make the change** using the existing maintenance skills:
    - New skill: `skills/workflow/skill-create`. Edit/append: `skills/workflow/skill-improve`. Game-dev win: `skills/workflow/gameskill`.
-   - Tool behavior / playbook: edit `src/mcp/tools/*.ts` and/or `docs/MCP_FRESH_CHAT_PLAYBOOK.md`; keep `references/mcp-tools-reference.md` in sync. Check `src/mcp/tools/project-tools.test.ts` still passes.
+   - Tool behavior / playbook: edit `src/mcp/tools/*.ts` and/or `docs/MCP_FRESH_CHAT_PLAYBOOK.md`; keep `../../../references/mcp-tools-reference.md` in sync. Check `src/mcp/tools/project-tools.test.ts` still passes.
    - Public-facing change: update the matching file in the `docs` repo.
 4. **Keep it concrete**. Every captured pattern gets a real, runnable code block (below), not prose.
 5. **Verify + commit.** If you touched `src/`, run `npm test`. Commit on a branch and summarize.

package/skills/workflow/playtesting-a-feature/SKILL.md

@@ -29,12 +29,9 @@ Static analysis is necessary but never sufficient for gameplay features. A clean
 NO "FEATURE SHIPPED" CLAIM WITHOUT A PLAYED WALKTHROUGH
 ```
 
-If you have not, in this session, called `summer_play` and either:
+If you have not, in this session, driven the feature and read back what happened, you cannot claim it works.
 
-1. Walked the feature yourself via MCP-driven repros where possible, OR
-2. Asked the user to walk it and confirmed the result via `summer_get_console` / `summer_get_debugger_errors`
-
-— then you cannot claim the feature works.
+**You walk the feature. Not the user.** A `RunVerification` probe presses your game's real inputs, reads state back across frames, and saves real rendered frames. Handing the walkthrough to the user is a last resort for things a probe genuinely cannot judge — see [What only a human can answer](#what-only-a-human-can-answer) — not the default.
 
 ## The Loop
 
@@ -51,7 +48,57 @@ Before pressing play, write down — in one or two sentences — what "feature w
 
 If you cannot describe the golden path in one sentence, you do not understand the feature well enough to verify it. Ask the user.
 
-### 2. Press play
+### 2. Walk the golden path with a probe
+
+Write the golden path as a `RunVerification` probe and send it as a raw op through `summer_batch`. The engine spawns a hidden, disposable game instance positioned offscreen, runs your GDScript, writes `results.json` plus any frames you saved, and kills the instance. It never touches the user's open editor, and nothing appears on their screen.
+
+```
+summer_batch ops:[{
+  "op": "RunVerification",
+  "probe_source": "<your GDScript>",
+  "max_seconds": 20
+}]
+```
+
+A probe extends `SummerProbeBase` and has: `report(key, value)`, `save_frame(name)`, `dump_tree()`, `press(action, hold_ms)`, `key(keycode, hold_ms)`, `finish()`.
+
+```gdscript
+extends SummerProbeBase
+
+func _ready() -> void:
+    await super._ready()
+    for i in 20:
+        await get_tree().physics_frame          # let the scene settle
+
+    var player := get_tree().current_scene.get_node("Player")
+    var start: Vector2 = player.position
+    save_frame("00_start")
+
+    await press("move_right", 500)              # await, or the hold never elapses
+    await get_tree().physics_frame
+    report("walked_right", player.position.x > start.x + 50)
+    save_frame("01_after_walk")
+
+    var y_before: float = player.position.y
+    await press("jump", 50)
+    var apex := y_before
+    for i in 25:
+        await get_tree().physics_frame
+        apex = min(apex, player.position.y)
+    report("jumped", apex < y_before - 30)
+    save_frame("02_after_jump")
+
+    finish()
+```
+
+Four rules the probe API will punish you for breaking:
+
+- **`press()` and `key()` are coroutines.** `await press("jump", 50)` — calling them bare starts the press and never releases it. You also cannot store one in a variable and await it later; it returns void.
+- **Assert on physics-frame-derived state.** `await get_tree().physics_frame` N times, then read positions. That is reproducible run to run.
+- **Assert inequalities, never exact values.** `press(hold_ms)` waits on the wall clock, so the number of physics frames a key is held drifts between runs — the same walk lands on x=245 one run and x=250 the next. `position.x > start.x + 50` is a real assertion; `position.x == 250.0` is a flaky test you wrote yourself.
+- **The global RNG is not seeded.** Anything downstream of `randf()` differs every run. Assert ranges, or seed it yourself in the probe.
+
+If the probe cannot express the check — no `SummerProbeBase` in this build, or a genuinely out-of-process feature — fall back to `summer_play` + console reads:
 
 ```
   summer_clear_console
@@ -61,14 +108,9 @@ If you cannot describe the golden path in one sentence, you do not understand th
 
 `summer_clear_console` first so the buffer is not polluted by a previous session's errors. If you skip this, you will chase ghost errors that have nothing to do with the current feature.
 
-### 3. Walk the golden path
-
-The MCP cannot simulate keyboard input, mouse motion, or controller. So either:
-
-- **The user plays.** Ask them to walk the exact golden path you defined. Wait for their confirmation that they did. Then check state.
-- **You drive via scene mutation.** For features that can be triggered through `summer_set_prop` or function calls exposed to the editor (e.g. autoload methods), drive them programmatically. Be honest about which path you took.
+### 3. Read back what actually happened
 
-After the walkthrough:
+The probe's `results.json` is your primary evidence. Then check the editor's own view:
 
 ```
   summer_get_console            (look for unexpected prints, warnings)
@@ -76,8 +118,20 @@ After the walkthrough:
   summer_get_diagnostics        (overall counts)
 ```
 
+A probe also collects engine errors itself — `results.json` carries `errors_seen`. Read it. An empty `reports` block with `finished: false` means the probe hit its `max_seconds` ceiling before calling `finish()`, which is a failure, not a pass.
+
 If anything is non-zero or unexpected, the feature is not done. Go to `summer:debug`.
 
+### What only a human can answer
+
+A probe reports facts. It cannot hold an opinion. Ask the user only when the question is genuinely experiential:
+
+- **Does it feel right?** Floaty jumps, sluggish input, mushy hit feedback — see `summer:debugging-game-feel`.
+- **Does it look good?** Composition, colour, readability. A probe can prove a light exists and prove the frame is not black; it cannot tell you the scene is ugly.
+- **Is this fun?** Not a measurable property.
+
+"I cannot simulate input" is not on that list, and has not been true since `RunVerification` shipped. If you catch yourself asking the user to press a key, write the probe instead.
+
 ### 4. Probe the edges
 
 The golden path proves the happy case. Most gameplay bugs live in the edges. Before claiming done, probe at least these four classes:
@@ -120,13 +174,15 @@ The console catches "looks right but isn't right" cases — silent errors, depre
 
 ## When to record video vs when console+diagnostics is enough
 
-Console + diagnostics + your walkthrough description is usually enough. Ask the user for a video or screenshot when:
+Your probe already produces the visual record: `save_frame()` writes a real rendered JPEG at each step, and a sequence of them across a movement is a flipbook of the feature happening. **You are not the only one who cannot see the game — until you save frames, nobody can.** Save them at the interesting moments and read them back.
+
+Ask the user for a video or a live look only when:
 
-- The feature is **visual** (camera, lighting, particles, animation, UI layout) and the user is the only one who can see the result.
 - The feature **feels wrong** — see `summer:debugging-game-feel`. Frame counts and console output cannot capture "the jump feels floaty."
-- The bug is **non-deterministic** — sometimes-works features need a recording to share with anyone diagnosing later.
+- The bug is **non-deterministic** and your probe cannot reproduce it after several attempts.
+- The judgement is aesthetic — see [What only a human can answer](#what-only-a-human-can-answer).
 
-Don't ask for video reflexively. Most features can be verified through `summer_get_console` + a "did the golden path work?" question. Cost-aware.
+Don't ask reflexively. A saved frame sequence answers most "did it visually work" questions without involving the user at all.
 
 ## Red Flags — STOP
 
@@ -137,10 +193,15 @@ Don't ask for video reflexively. Most features can be verified through `summer_g
 | "User said make this — I'll move on once it builds" | The user wants the feature to work, not to build. |
 | "It would take too long to play" | Playtest takes 60 seconds. Shipping a broken feature costs hours. |
 | "The unit test passes" | Unit tests cover code paths, not gameplay sequences. |
-| "I already played it in a previous session" | State changed. Press play in this session. |
+| "I already played it in a previous session" | State changed. Verify in this session. |
 | "I'll let the user catch any issues" | That is the user's job description for a non-AI engineer. Yours is to ship working features. |
 | Skipping `summer_clear_console` before `summer_play` | You will chase last session's errors. |
 | Skipping `summer_get_console` because diagnostics looked fine | Silent warnings and signal misfires hide there. |
+| "The MCP can't simulate input, so the user has to test it" | False. `RunVerification` presses actions and keys. Write the probe. |
+| "I'll ask the user to press jump and tell me what happened" | You can press jump. They should not have to QA your work. |
+| Probe returned `finished: false`, you called it a pass | It hit `max_seconds` before `finish()`. That is a failure. |
+| Asserting `position.x == 250.0` in a probe | Hold time is wall-clock. Assert `> start.x + 50`. |
+| `press("jump", 50)` without `await` | It is a coroutine. The key is never released. |
 
 ## Rationalization Prevention
 
@@ -154,10 +215,22 @@ Don't ask for video reflexively. Most features can be verified through `summer_g
 
 ## When the engine isn't running
 
-If `summer_play` returns "Summer Engine is not running":
+`RunVerification` is dispatched by the editor, so it needs the editor running. **The verify instance itself does not.** You can spawn exactly the same probe runtime straight from your shell, with no editor at all:
+
+```bash
+/Applications/Summer.app/Contents/MacOS/Summer \
+  --path <project-dir> \
+  --summer-verify <abs-path-to-probe.gd> \
+  --summer-verify-out <abs-out-dir> \
+  --summer-verify-max 30
+```
+
+Then read `<out-dir>/results.json` and the JPEGs beside it. The probe must extend the base class — copy `summer_probe_base.gd` into the project and `extends "res://summer_probe_base.gd"`, or use the project's `tests/autopilot/` scaffold if it has one. See `summer:headless-scripting` for the full pattern and its traps.
+
+So if `summer_play` returns "Summer Engine is not running":
 
-1. Tell the user: `summer run` to start it.
-2. Do not claim the feature is verified from static analysis alone. Say: "Code compiles and looks correct, but I cannot playtest until the engine is running."
+1. Run the probe directly from the shell as above. That is a real playtest.
+2. Only if that is also impossible: tell the user `summer run` to start the editor, and say plainly "code compiles and looks correct, but I have not played it" — do not claim verification from static analysis alone.
 3. When the engine comes back, run the loop.
 
 ## The Bottom Line