summer-engine 2.6.6 → 2.8.0

package/assets/autopilot/autopilot.gd

@@ -0,0 +1,222 @@
+# Autopilot — drives the player through a list of waypoints, saves a frame at each,
+# asserts what it saw, and exits.
+#
+# This is a starting point, not a finished test. Edit CONFIG below to match your game,
+# then add your own assertions in _check_at_waypoint(). Everything here is ordinary
+# GDScript against your real running game — there is no test framework to learn.
+#
+# Run it:
+#   bash tests/autopilot/run.sh
+# or from an agent, as a RunVerification probe (see tests/autopilot/README.md).
+
+extends "res://tests/autopilot/probe_base.gd"
+
+# ── CONFIG — edit this ────────────────────────────────────────────────────────────
+
+# Node path to the player, from the current scene root.
+const PLAYER_PATH := "Player"
+
+# Input action names from your project's Input Map. Leave an entry empty to skip it.
+const ACT_LEFT  := "move_left"
+const ACT_RIGHT := "move_right"
+const ACT_UP    := ""              # "move_forward" in 3D, "move_up" in top-down 2D
+const ACT_DOWN  := ""
+const ACT_JUMP  := "jump"
+
+# Where to walk. 2D games use x/y in pixels; 3D games use x/z in metres (y ignored).
+# Positions are WORLD positions, not offsets.
+const WAYPOINTS := [
+    Vector3(300, 0, 0),
+    Vector3(600, 0, 0),
+]
+
+# How close counts as arrived, and how long to allow per leg before giving up.
+const ARRIVE_EPSILON := 40.0
+const LEG_TIMEOUT_FRAMES := 240
+
+# ── END CONFIG ────────────────────────────────────────────────────────────────────
+
+var _player: Node = null
+var _is_3d := false
+
+
+func _ready() -> void:
+    await super._ready()
+
+    # Let the scene settle. Physics frames, not timers — timers are wall-clock and
+    # make results differ between runs and between machines.
+    for _i in 30:
+        await get_tree().physics_frame
+
+    if not _bind_player():
+        finish()
+        return
+
+    report("player_path", PLAYER_PATH)
+    report("player_class", _player.get_class())
+    report("mode", "3D" if _is_3d else "2D")
+    report("start_pos", str(_pos()))
+    dump_tree()
+    save_frame("00_start")
+
+    for i in WAYPOINTS.size():
+        var target: Vector3 = WAYPOINTS[i]
+        var arrived := await _walk_to(target)
+        report("waypoint_%d_reached" % i, arrived)
+        report("waypoint_%d_pos" % i, str(_pos()))
+        save_frame("%02d_waypoint_%d" % [i + 1, i])
+        _check_at_waypoint(i)
+        if not arrived:
+            report("failed_at_waypoint", i)
+            break
+
+    _check_at_end()
+    finish()
+
+
+# ── Your assertions go here ───────────────────────────────────────────────────────
+
+# Called after arriving at (or failing to reach) each waypoint.
+func _check_at_waypoint(index: int) -> void:
+    # Assert things that are TRUE OR FALSE, not things that are approximately a number.
+    # Hold durations are wall-clock, so exact distances drift between runs.
+    #
+    #   var hud := get_tree().current_scene.get_node_or_null("UI/HUD")
+    #   report("hud_visible_at_%d" % index, hud != null and hud.visible)
+    #   report("enemies_alive_at_%d" % index, get_tree().get_nodes_in_group("enemy").size())
+    pass
+
+
+# Called once after the last waypoint.
+func _check_at_end() -> void:
+    #   report("player_alive", _player.has_method("is_alive") and _player.is_alive())
+    pass
+
+
+# ── Machinery — you should not need to edit below this line ───────────────────────
+
+func _bind_player() -> bool:
+    var scene := get_tree().current_scene
+    if scene == null:
+        report("error", "no current scene — is run/main_scene set in project.godot?")
+        return false
+    _player = scene.get_node_or_null(PLAYER_PATH)
+    if _player == null:
+        report("error", "player not found at '%s'" % PLAYER_PATH)
+        report("scene_children", _child_names(scene))
+        dump_tree()
+        return false
+    _is_3d = _player is Node3D
+    if not (_is_3d or _player is Node2D):
+        report("error", "player at '%s' is neither Node2D nor Node3D" % PLAYER_PATH)
+        return false
+    return true
+
+
+func _child_names(n: Node) -> Array:
+    var names := []
+    for c in n.get_children():
+        names.append(c.name)
+    return names
+
+
+# Player position normalised to a Vector3 so one code path handles 2D and 3D.
+# In 2D, x/y are screen pixels and z is unused.
+func _pos() -> Vector3:
+    if _is_3d:
+        var p: Vector3 = _player.global_position
+        return p
+    var p2: Vector2 = _player.global_position
+    return Vector3(p2.x, p2.y, 0.0)
+
+
+# Distance that matters for "did we arrive", measured ONLY on axes the game can
+# actually steer. A side-on platformer has no up/down actions, so its Y is gravity,
+# not a destination — including it would mean the player never "arrives" while
+# standing on the ground 368 pixels below Y=0. That is a real failure this scaffold
+# hit on its first run.
+func _planar_distance(a: Vector3, b: Vector3) -> float:
+    var d := 0.0
+    if _has_horizontal_actions():
+        d += pow(b.x - a.x, 2.0)
+    if _has_secondary_actions():
+        var d2 := (b.z - a.z) if _is_3d else (b.y - a.y)
+        d += pow(d2, 2.0)
+    return sqrt(d)
+
+
+func _has_horizontal_actions() -> bool:
+    return _action_live(ACT_LEFT) or _action_live(ACT_RIGHT)
+
+
+func _has_secondary_actions() -> bool:
+    return _action_live(ACT_UP) or _action_live(ACT_DOWN)
+
+
+func _action_live(action: String) -> bool:
+    return action != "" and InputMap.has_action(action)
+
+
+func _walk_to(target: Vector3) -> bool:
+    var frames := 0
+    var held: Array[String] = []
+
+    while frames < LEG_TIMEOUT_FRAMES:
+        var here := _pos()
+        if _planar_distance(here, target) <= ARRIVE_EPSILON:
+            _release(held)
+            return true
+
+        var want := _actions_toward(here, target)
+        # Only touch actions that changed, so a held key stays held across frames
+        # instead of being released and re-pressed every frame.
+        for a in held:
+            if not want.has(a):
+                _set_action(a, false)
+        for a in want:
+            if not held.has(a):
+                _set_action(a, true)
+        held = want
+
+        await get_tree().physics_frame
+        frames += 1
+
+    _release(held)
+    return false
+
+
+func _actions_toward(here: Vector3, target: Vector3) -> Array[String]:
+    var out: Array[String] = []
+    var dx := target.x - here.x
+    if absf(dx) > ARRIVE_EPSILON * 0.5:
+        var a := ACT_RIGHT if dx > 0.0 else ACT_LEFT
+        if _action_live(a):
+            out.append(a)
+
+    # Second axis: z in 3D, y in 2D. Skipped when the game has no such actions
+    # (a side-on platformer, for example).
+    if _has_secondary_actions():
+        var d2 := (target.z - here.z) if _is_3d else (target.y - here.y)
+        if absf(d2) > ARRIVE_EPSILON * 0.5:
+            var b := ACT_DOWN if d2 > 0.0 else ACT_UP
+            if _action_live(b):
+                out.append(b)
+
+    return out
+
+
+# Press and release directly rather than via press(), which awaits its own hold
+# duration on the wall clock. Holding across physics frames is what makes an
+# autopilot run reproducible.
+func _set_action(action: String, pressed: bool) -> void:
+    if action == "" or not InputMap.has_action(action):
+        return
+    var ev := InputEventAction.new()
+    ev.action = action
+    ev.pressed = pressed
+    Input.parse_input_event(ev)
+
+
+func _release(held: Array) -> void:
+    for a in held:
+        _set_action(a, false)

package/assets/autopilot/probe_base.gd

@@ -0,0 +1,262 @@
+# SUMMER - Verification Runner v1: probe base class.
+#
+# An AI-authored probe extends this base. The engine injects the probe as a singleton
+# named "SummerProbe" into a disposable, invisible --summer-verify game instance. The
+# base provides the runtime API (report / save_frame / dump_tree / press / key / finish)
+# and guarantees a results.json is written even if the probe hangs (at-exit backstop +
+# the frames-based quit-after ceiling in main.cpp).
+#
+# The engine sets two members on the instance before _ready() via `set()`:
+#   summer_out_dir     : String  - absolute temp dir to write results/frames into
+#   summer_max_seconds : int     - soft budget; base auto-finishes at this ceiling
+#
+# Contract of <out_dir>/results.json:
+#   { "reports": {..}, "frames": [names], "errors_seen": [strings],
+#     "frame_warnings": [strings], "duration_ms": int, "finished": bool }
+#
+# PERCEPTION NOTES (measured against the shipped 0.5.55 binary, reproducible 3/3):
+#   * This instance is NOT --headless. Headless has no renderer, so
+#     viewport.get_texture().get_image() returns null and NO frame can ever be
+#     captured. The verify child is a real windowed instance parked offscreen at
+#     (-32000,-32000) precisely so capture works. Never add --headless here.
+#   * The viewport does not hold your scene yet during _ready(). Measured, with a
+#     red box on screen, sampling distinct colours in the captured image:
+#         in _ready()              frames_drawn=0  ->  1 colour  (clear colour only)
+#         after 1 process_frame    frames_drawn=0  ->  1 colour  (still empty)
+#         after 2 process_frames   frames_drawn=1  ->  2 colours (the box is there)
+#     So `await settle()` before your FIRST save_frame(). save_frame() records a
+#     frame_warnings entry rather than lying if you skip it.
+#   * RenderingServer.force_draw() is NOT a shortcut. Measured: it fills the image
+#     with the clear colour (1 colour, all non-black) but the scene geometry is
+#     still missing. A plausible-but-wrong frame is worse than a blank one.
+#   * Audio IS assertable even though this instance forces the Dummy driver
+#     (main.cpp, summer_verify block). AudioServer still mixes, so measured:
+#         silent scene  -> AudioServer.get_bus_peak_volume_left_db(0,0) == -200.0
+#         playing sound -> ... == -1.938
+#   * Performance monitors work here and only here. Measured in this instance:
+#     draw_calls=1, fps=46, objects=1, primitives=12. The same probe under
+#     --headless reports draw_calls=0, fps=1, objects=0 -- all meaningless.
+extends Node
+
+var summer_out_dir: String = ""
+var summer_max_seconds: int = 20
+
+var _reports: Dictionary = {}
+var _frames: Array = []
+var _frame_warnings: Array = []
+var _start_ms: int = 0
+var _finished: bool = false
+
+func _enter_tree() -> void:
+	_start_ms = Time.get_ticks_msec()
+
+func _ready() -> void:
+	# Hard soft-ceiling: if the probe body never calls finish(), auto-finish just before
+	# the main.cpp frames ceiling would kill us, so we still flush a partial results.json.
+	var t := Timer.new()
+	t.one_shot = true
+	t.wait_time = float(summer_max_seconds)
+	t.timeout.connect(_on_deadline)
+	add_child(t)
+	t.start()
+
+func _on_deadline() -> void:
+	if not _finished:
+		report("_timeout", true)
+		finish()
+
+# --- Runtime API for the AI-authored probe --------------------------------------------
+
+func report(key: String, value) -> void:
+	_reports[key] = value
+
+func settle(frames: int = 1) -> void:
+	# Await until the renderer has actually PRESENTED `frames` more frames. Call this
+	# before your first save_frame(), and after any change you want to see on screen.
+	#
+	#     await settle()          # first capture is now trustworthy
+	#     save_frame("start")
+	#
+	# Counting presented frames (Engine.get_frames_drawn()) rather than awaiting
+	# process_frame is deliberate: a process frame can complete without the renderer
+	# having presented anything, which is exactly the blank-capture bug. See the
+	# PERCEPTION NOTES at the top for the measurements behind this.
+	#
+	# But that counter only advances when there IS a renderer. Under --headless it is
+	# 0 forever -- measured: 438 process frames awaited over 3005ms, frames_drawn
+	# still 0 -- so waiting on it there would spin until the probe budget killed the
+	# run. This base is normally injected into the windowed verify child, but the
+	# headless-scripting path runs it under `--headless -s`, where that would hang.
+	# So: fall back to process frames when there is no renderer, and bound the wait
+	# either way so settle() can never be the reason a probe fails to finish.
+	if not has_renderer():
+		# +1 because content lands a frame later than the naive count suggests.
+		for _i in range(maxi(1, frames) + 1):
+			await get_tree().process_frame
+		return
+	var target := Engine.get_frames_drawn() + maxi(1, frames)
+	var guard := 0
+	while Engine.get_frames_drawn() < target and guard < 600:
+		guard += 1
+		await get_tree().process_frame
+	if guard >= 600:
+		report("_settle_timeout", true)
+
+func has_renderer() -> bool:
+	# True when this instance can actually draw. Use this, NOT OS.has_feature("headless"),
+	# which is measurably FALSE under --headless and will mislead you. The rendering
+	# method setting lies too -- it still reads "forward_plus" with no renderer behind it.
+	# DisplayServer's own name is the honest signal.
+	return DisplayServer.get_name() != "headless"
+
+func settle_physics(frames: int = 1) -> void:
+	# Await N physics frames. Call this after building a scene and BEFORE asserting
+	# anything physical. A body added this frame has no space yet, so the natural
+	# "build the scene, immediately assert physics" probe throws on frame 0:
+	#   Parameter "body->get_space()" is null
+	#   at: godot_physics_server_2d.cpp:997
+	# One physics frame after add_child() is the minimum; raycasts and contacts
+	# generally want two.
+	for _i in range(maxi(1, frames)):
+		await get_tree().physics_frame
+
+func settle_navigation(max_frames: int = 60) -> bool:
+	# Await until the navigation map is actually queryable, and report whether it got
+	# there. Returns true on success, false if it timed out.
+	#
+	# This exists because the failure is SILENT. NavigationServer3D.map_get_path()
+	# returns an EMPTY array with no error until the map has synchronized TWICE --
+	# iteration_id == 1 is not enough. Measured here, awaiting physics_frame:
+	#     frame 0-1  iter=0  path_pts=0
+	#     frame 2-3  iter=1  path_pts=0     <- still empty, still no error
+	#     frame 4+   iter=2  path_pts=2     <- queryable
+	# So the obvious probe returns [] and reads as "navigation is broken" when
+	# nothing is wrong. (map_get_closest_point() does error; map_get_path() does not.)
+	# process_frame does NOT advance the iteration id as quickly -- await physics.
+	var map := get_viewport().world_3d.navigation_map
+	for _i in range(maxi(1, max_frames)):
+		if NavigationServer3D.map_get_iteration_id(map) >= 2:
+			return true
+		await get_tree().physics_frame
+	report("_navigation_settle_timeout", true)
+	return false
+
+func save_frame(name: String) -> String:
+	# Capture the current viewport framebuffer to <out_dir>/<name> (jpg). Returns the
+	# absolute path written, or "" on failure.
+	#
+	# If no frame has been presented yet, the file still lands (so the web side can look
+	# at it) but a frame_warnings entry is recorded, because the image will be the flat
+	# clear colour rather than your scene. Fix that by `await settle()` first -- do not
+	# ignore the warning, the capture is not evidence of anything.
+	if not has_renderer():
+		var hw := "save_frame(\"%s\") called under --headless: there is NO renderer, get_image() returns null and no frame can ever be captured. Use the windowed verify path (--summer-verify), not --headless." % name
+		if not _frame_warnings.has(hw):
+			_frame_warnings.append(hw)
+	elif Engine.get_frames_drawn() < 1:
+		var w := "save_frame(\"%s\") ran before any frame was presented - the image is the clear colour, not the scene. `await settle()` first." % name
+		if not _frame_warnings.has(w):
+			_frame_warnings.append(w)
+	var vp := get_viewport()
+	if vp == null:
+		return ""
+	var tex := vp.get_texture()
+	if tex == null:
+		return ""
+	var img := tex.get_image()
+	if img == null:
+		return ""
+	var fname := name if name.ends_with(".jpg") else name + ".jpg"
+	var path := summer_out_dir.path_join(fname)
+	var err := img.save_jpg(path, 0.75)
+	if err == OK:
+		if not _frames.has(fname):
+			_frames.append(fname)
+		return path
+	return ""
+
+func dump_tree(max_depth: int = 6) -> void:
+	# Summarize the live scene tree (names + classes) into the report under "tree".
+	var root := get_tree().root
+	var lines: Array = []
+	_dump_node(root, 0, max_depth, lines)
+	report("tree", lines)
+
+func _dump_node(n: Node, depth: int, max_depth: int, lines: Array) -> void:
+	if depth > max_depth:
+		return
+	var indent := "  ".repeat(depth)
+	lines.append("%s%s (%s)" % [indent, n.name, n.get_class()])
+	for c in n.get_children():
+		_dump_node(c, depth + 1, max_depth, lines)
+
+func press(action: String, hold_ms: int = 100) -> void:
+	# Inject an input action press+release from INSIDE the process (no debugger).
+	var ev := InputEventAction.new()
+	ev.action = action
+	ev.pressed = true
+	Input.parse_input_event(ev)
+	await get_tree().create_timer(hold_ms / 1000.0).timeout
+	var up := InputEventAction.new()
+	up.action = action
+	up.pressed = false
+	Input.parse_input_event(up)
+
+func key(keycode: int, hold_ms: int = 100) -> void:
+	# Inject a physical key press+release by keycode (e.g. KEY_SPACE).
+	var ev := InputEventKey.new()
+	ev.keycode = keycode
+	ev.physical_keycode = keycode
+	ev.pressed = true
+	Input.parse_input_event(ev)
+	await get_tree().create_timer(hold_ms / 1000.0).timeout
+	var up := InputEventKey.new()
+	up.keycode = keycode
+	up.physical_keycode = keycode
+	up.pressed = false
+	Input.parse_input_event(up)
+
+func finish() -> void:
+	# Flush results.json and terminate the disposable instance.
+	if _finished:
+		return
+	_finished = true
+	_write_results(true)
+	get_tree().quit()
+
+# --- Results writing ------------------------------------------------------------------
+
+func _collect_errors() -> Array:
+	# The C++ SummerVerifyLogger appends error-level engine/script errors to errors.log.
+	var errors: Array = []
+	var p := summer_out_dir.path_join("errors.log")
+	if FileAccess.file_exists(p):
+		var f := FileAccess.open(p, FileAccess.READ)
+		if f != null:
+			while not f.eof_reached():
+				var line := f.get_line()
+				if line.strip_edges() != "":
+					errors.append(line)
+	return errors
+
+func _write_results(finished: bool) -> void:
+	var out := {
+		"reports": _reports,
+		"frames": _frames,
+		"frame_warnings": _frame_warnings,
+		"errors_seen": _collect_errors(),
+		"duration_ms": Time.get_ticks_msec() - _start_ms,
+		"finished": finished,
+	}
+	var path := summer_out_dir.path_join("results.json")
+	var f := FileAccess.open(path, FileAccess.WRITE)
+	if f != null:
+		f.store_string(JSON.stringify(out, "  "))
+		f.flush()
+		f.close()
+
+func _exit_tree() -> void:
+	# At-exit backstop: if finish() was never called (quit-after ceiling in main.cpp
+	# killed us, or the probe crashed), still leave a partial results.json behind.
+	if not _finished:
+		_write_results(false)

package/assets/autopilot/run.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# Run the autopilot against this project and print the results.
+#
+#   bash tests/autopilot/run.sh                    # runs autopilot.gd
+#   bash tests/autopilot/run.sh my_probe.gd        # runs a different probe
+#
+# No editor required. This spawns the engine's offscreen verify instance, which
+# has a REAL renderer — unlike --headless, which produces no pixels at all.
+set -euo pipefail
+
+PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+PROBE="${1:-$PROJECT_DIR/tests/autopilot/autopilot.gd}"
+OUT="$PROJECT_DIR/tests/autopilot/out"
+MAX_SECONDS="${MAX_SECONDS:-40}"
+
+# Find the engine. Override with SUMMER_BIN=/path/to/engine if it lives elsewhere.
+# There is no `godot` binary on a Summer install — do not substitute one.
+if [[ -n "${SUMMER_BIN:-}" ]]; then
+  ENGINE="$SUMMER_BIN"
+elif [[ -x "/Applications/Summer.app/Contents/MacOS/Summer" ]]; then
+  ENGINE="/Applications/Summer.app/Contents/MacOS/Summer"
+elif [[ -x "${LOCALAPPDATA:-}/Summer/current/Summer.exe" ]]; then
+  ENGINE="${LOCALAPPDATA}/Summer/current/Summer.exe"
+else
+  echo "Could not find the Summer engine binary." >&2
+  echo "Set SUMMER_BIN, or read engineBinaryPath from summer_get_project_context." >&2
+  exit 1
+fi
+
+rm -rf "$OUT"
+mkdir -p "$OUT"
+
+# --disable-crash-handler: Summer's handler popen()s atos from inside a signal
+# handler, which turns a clean failure into a hang. Never arm it on an
+# agent-driven run. Note there is deliberately no --headless here: headless has
+# no renderer, so save_frame() would produce nothing.
+"$ENGINE" \
+  --disable-crash-handler \
+  --path "$PROJECT_DIR" \
+  --summer-verify "$PROBE" \
+  --summer-verify-out "$OUT" \
+  --summer-verify-max "$MAX_SECONDS" \
+  >"$OUT/engine.log" 2>&1 || true
+
+if [[ ! -f "$OUT/results.json" ]]; then
+  echo "No results.json — the probe never started. Engine output:" >&2
+  tail -30 "$OUT/engine.log" >&2
+  exit 1
+fi
+
+cat "$OUT/results.json"
+echo
+echo "Frames and full log: $OUT"
+
+# finished:false means the probe hit its time ceiling before calling finish().
+# That is a failure, not a pass — exit non-zero so CI notices.
+if command -v python3 >/dev/null 2>&1; then
+  python3 - "$OUT/results.json" <<'PY'
+import json, sys
+d = json.load(open(sys.argv[1]))
+reports = d.get("reports", {})
+if not d.get("finished", False):
+    print("FAILED: probe did not finish (hit --summer-verify-max)", file=sys.stderr)
+    sys.exit(1)
+if d.get("errors_seen"):
+    print(f"FAILED: {len(d['errors_seen'])} engine error(s) during the run", file=sys.stderr)
+    sys.exit(1)
+if reports.get("error"):
+    print(f"FAILED: {reports['error']}", file=sys.stderr)
+    print("Edit the CONFIG block at the top of tests/autopilot/autopilot.gd.", file=sys.stderr)
+    sys.exit(1)
+# Any waypoint the autopilot could not reach is a failure, whatever else passed.
+missed = [k for k, v in reports.items() if k.endswith("_reached") and v is False]
+if missed:
+    print(f"FAILED: waypoints not reached: {', '.join(sorted(missed))}", file=sys.stderr)
+    sys.exit(1)
+PY
+fi

package/commands/gameskill.md

@@ -6,9 +6,18 @@ This is the meta-skill: the loop that turns ad-hoc fixes into durable, reusable
 
 Three repos, one ecosystem:
 
-1. **`~/development/SummerEngine`** — the desktop engine (Godot fork in C++) + the canonical CLI. The engine source lives at `editor/`, `core/`, and the Summer-specific module at `modules/1summer_engine/`. The Summer CLI lives at `tools/summer-cli/`. It ships as `npm i -g summer-engine`. It does install/login/create/run for the engine, plus `summer skills install --as-claude-skill` which writes a curated subset of skills into `~/.claude/skills/` for any agent to auto-discover.
+1. **`~/development/SummerEngine`** — the Summer Engine desktop source and the
+   canonical CLI. The C++ engine is maintained against the upstream Godot
+   Engine codebase; the Summer-owned module lives at `modules/1summer_engine/`.
+   The Summer CLI lives at `tools/summer-cli/` and is normally invoked with
+   `npx -y summer-engine@latest`. It installs, signs in, creates, and runs Summer
+   projects and can install the current Summer skill bundle for supported
+   agents.
 2. **`~/development/PublicSummerEngine`** — the web app at summerengine.com. Has its own AI skill stores at `src/lib/ai/skills/bundled/` and `public/knowledge/summer/skills/` for the in-browser chat agent. ALSO has its own MCP-style consumers of the engine API (`src/lib/bridge/direct-executor.ts`, `src/lib/ai/tools/run-and-verify.ts`) which call the same engine endpoints the CLI does.
-3. **The active game project** — usually `~/development/<game-name>` (Godot 4.6) or whatever game we were just working on. Real working code in this repo is the gold standard for examples.
+3. **The active Summer game project** — usually
+   `~/development/<game-name>` or whatever game we were just working on. The
+   live compatibility line comes from Summer Engine, not this prompt. Real
+   working code in this repo is the gold standard for examples.
 
 The skill system is the value flywheel: every game we ship teaches lessons → the lessons become skills → the next user (or AI) starts smarter. Your job here is to close that loop for what we just did.
 

package/commands/summer.md

@@ -0,0 +1,13 @@
+You are the Summer Engine command router. The user invoked `/summer` because they want game-development help inside Summer Engine, not generic software advice.
+
+Arguments:
+
+```
+$ARGUMENTS
+```
+
+First, route the request to the closest Summer skill. Use `summer:using-summer` if you need base context before choosing.
+
+If the arguments start with `debug`, or the user is reporting a crash, error, broken behavior, cloud/Codex failure, or anything they want to send to Summer support, use `summer:debugging/debug`. In that support-report mode, call `summer_create_debug_report` when available and tell the user where the Markdown report was written. Continue fixing the issue only if the user also asked for a fix.
+
+For all other requests, follow the `/summer` persona routing table from the Summer skill family and start the appropriate game-dev workflow.

package/dist/bin/summer.js

@@ -17,6 +17,11 @@ import { setupCommand } from "../commands/setup.js";
 import { doctorCommand } from "../commands/doctor.js";
 import { planCommand } from "../commands/plan.js";
 import { cloudCommand } from "../commands/cloud.js";
+import { debugCommand } from "../commands/debug.js";
+import { configCommand } from "../commands/config.js";
+import { publishCommand } from "../commands/publish.js";
+import { releasesCommand } from "../commands/releases.js";
+import { logsCommand } from "../commands/logs.js";
 import { getBanner } from "../lib/banner.js";
 import { c, sym } from "../lib/format.js";
 const require = createRequire(import.meta.url);
@@ -42,9 +47,14 @@ program.addCommand(skillsCommand);
 program.addCommand(mcpCommand);
 program.addCommand(setupCommand);
 program.addCommand(doctorCommand);
+program.addCommand(debugCommand);
 program.addCommand(planCommand);
 program.addCommand(orchestratorCommand);
 program.addCommand(cloudCommand);
+program.addCommand(configCommand);
+program.addCommand(publishCommand);
+program.addCommand(releasesCommand);
+program.addCommand(logsCommand);
 program.parseAsync().catch((err) => {
     console.error(err instanceof Error ? err.message : String(err));
     process.exit(1);
@@ -63,10 +73,12 @@ function printIntro(version) {
     console.log(`     ${c.dim("$")} npx -y summer-engine@latest setup claude-code --yes`);
     console.log(`     ${c.dim("$")} npx -y summer-engine@latest create 3d-basic my-game`);
     console.log(`     ${c.dim("$")} npx -y summer-engine@latest plan make a small arena shooter`);
+    console.log(`     ${c.dim("$")} npx -y summer-engine@latest debug "player crashes on pickup"`);
     console.log(`     ${c.dim("$")} npx -y summer-engine@latest memory`);
     console.log(`     ${c.dim("$")} npx -y summer-engine@latest doctor`);
     console.log("");
     console.log(`     ${c.bold("Slash commands")} ${c.dim("(in your AI agent)")}`);
+    console.log(`     ${c.brand("/summer debug")}   ${c.dim("Create a support-ready debug report")}`);
     console.log(`     ${c.brand("/debug")}   ${c.dim("Triage and fix a bug end-to-end")}`);
     console.log(`     ${c.brand("/play")}    ${c.dim("Run the game and report state")}`);
     console.log("");

package/dist/commands/config.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const configCommand: Command;