Pin bcrypt<4.1 to fix passlib 1.7.4 compatibility

passlib 1.7.4 (last release, unmaintained since ~2020) detects its bcrypt
backend via bcrypt.__about__.__version__, which bcrypt>=4.1 removed. Every
hash_password/verify_password call was raising 'password cannot be longer
than 72 bytes' -- a misleading downstream symptom of the real
AttributeError: module 'bcrypt' has no attribute '__about__'.

Without this pin, pip install -r requirements.txt silently grabs whatever
the latest bcrypt is and breaks register/login outright -- confirmed this
broke 3 separate pieces of work this session (manual register curl tests,
and now a real Godot smoke test) purely from environment drift, not from
any actual code bug. Verified the fix works from a genuinely clean venv +
pip install, not just patching the already-installed shared venv.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

.gitignore

@@ -8,3 +8,6 @@ export/
 # OS
 .DS_Store
 Thumbs.db
+
+# Godot UID files (regenerated from path)
+*.uid

backend/app/models/script.py

@@ -1,39 +0,0 @@
-"""Script model — game logic scripts owned by users and associated with worlds."""
-
-from typing import Optional
-
-from sqlalchemy import Column, Integer, String, Text, DateTime, ForeignKey, func
-from sqlalchemy.dialects.postgresql import ENUM, JSONB
-from sqlalchemy.orm import relationship
-import enum
-
-from app.database import Base
-
-
-class ScriptType(str, enum.Enum):
-    """Type of script storage."""
-    GDSCRIPT = "gdscript"
-    DSL = "dsl"
-
-
-class Script(Base):
-    """A game script — either raw GDScript source or a DSL payload."""
-    __tablename__ = "scripts"
-
-    id = Column(Integer, primary_key=True, index=True)
-    name = Column(String(255), nullable=False)
-    world_id = Column(Integer, ForeignKey("worlds.id", ondelete="CASCADE"), nullable=True)
-    owner_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
-    source_code = Column(Text, nullable=True)
-    version = Column(Integer, nullable=False, server_default="1")
-    script_type = Column(
-        ENUM(ScriptType, name="script_type", create_type=False),
-        nullable=False,
-        default=ScriptType.GDSCRIPT,
-    )
-    dsl_payload = Column(JSONB, nullable=True)
-    created_at = Column(DateTime(timezone=True), server_default=func.now())
-    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())
-
-    owner = relationship("User", back_populates="scripts")
-    world = relationship("World", back_populates="scripts")

backend/requirements.txt

@@ -9,6 +9,14 @@ pydantic==2.10.3
 pydantic-settings==2.7.0
 python-jose[cryptography]==3.3.0
 passlib[bcrypt]==1.7.4
+# passlib 1.7.4 (last release, unmaintained since ~2020) detects its bcrypt
+# backend via bcrypt.__about__.__version__, which bcrypt>=4.1 removed --
+# hashing/verifying a password then raises "password cannot be longer than
+# 72 bytes" (a misleading downstream symptom of the real AttributeError:
+# module 'bcrypt' has no attribute '__about__') on every call. Without this
+# pin, `pip install -r requirements.txt` silently grabs whatever the latest
+# bcrypt is and breaks register/login outright. Pin below 4.1 explicitly.
+bcrypt==4.0.1
 python-multipart==0.0.20
 email-validator==2.2.0
 httpx==0.28.1

docs/planning/client-server-wiring.md

@@ -23,10 +23,9 @@ explicitly out of scope.
 | # | Type | Task | Depends on |
 |---|------|------|-----------|
 | 1 | architecture | `ApiClient` autoload: HTTP + JWT storage + error contract | — |
-| 2 | implementation | Main-menu **login** wiring (form-encoded) | 1 |
-| 3 | implementation | Main-menu **register** wiring (JSON + age gate) | 2 |
-| 4 | implementation | **World list** screen consuming `GET /api/worlds` | 2 |
-| 5 | testing | End-to-end headless smoke test + manual verify | 1,3,4 |
+| 2 | implementation | Main-menu **login + register** UI built & wired (form-encoded + JSON/age gate) | 1 |
+| 3 | implementation | **World list** screen consuming `GET /api/worlds` | 1 |
+| 4 | testing | End-to-end headless smoke test + manual verify | 1,2,3 |
 
 ## Design decisions captured (resolved in task 1)
 - Token storage: in-memory singleton property for the MVP; a `save_to_disk` seam is left
@@ -35,3 +34,8 @@ explicitly out of scope.
   never crash on network failure; non-2xx surfaces `{status, detail}` from the backend.
 - Base URL: read from a ProjectSetting, defaulting to `http://127.0.0.1:8000`.
 - Login is form-encoded; register is JSON — the client helper must support both content types.
+
+## Notes
+- The main-menu auth UI does **not** exist yet (main_menu.gd currently has only Play/Quit
+  stubs). Task 2 must **build** the login/register UI, not merely wire an existing one.
+- The world-list screen also needs to be **built** (a new scene), not just wired.

docs/testing/README.md

@@ -0,0 +1,50 @@
+# Testing at Package Checkpoints
+
+A Package Checkpoint (PC1, PC2, ...) is a periodic review point — every few
+real milestones, the client and server builds get packaged together and
+independently reviewed before anyone calls anything actually done. See
+`project_agp` in Claude's memory, or ask, for the full definition; this
+doc is just the mechanical "how do I run the tests" part of that review.
+
+## Running the suite
+
+```
+python scripts/run_checkpoint_tests.py
+```
+
+Brings up a throwaway Postgres, runs Alembic migrations against it, runs the
+backend pytest suite, starts the backend server, and runs every Godot
+headless smoke test (`scripts/smoke_test_*.gd`) against it. Tears the
+Postgres container down afterward (`--keep-postgres` to skip that if you
+want to poke at the DB after a failure).
+
+If port 5432 is already taken on the machine, pass `--postgres-port` with
+something else.
+
+Exit code is 0 only if everything that actually ran passed — suites with
+nothing to run yet (no Godot binary found, no smoke test scripts yet) are
+reported SKIPPED, not treated as a failure.
+
+## What this does and doesn't prove
+
+Passing this script means: migrations apply cleanly to a genuinely empty
+database, the backend's unit-level logic is correct, and whatever Godot
+smoke tests exist actually round-trip against a live backend. It does
+**not** mean full endpoint/integration coverage exists — see
+`test_inventory.md` for the current, honest list of what's tested and what
+isn't. A checkpoint review should still involve reading the actual diffs
+for anything this script's current coverage doesn't reach, not just running
+green and calling it done.
+
+## Growing this over time
+
+As real integration tests get added (endpoint tests hitting the FastAPI app,
+more Godot smoke coverage beyond `health_check`), they should land under
+`backend/tests/` / `scripts/smoke_test_*.gd` respectively — this script
+picks up new files automatically, nothing to register by hand. Update
+`test_inventory.md`'s tables when you do, so the inventory stays a source
+of truth instead of quietly going stale.
+
+Eventual goal (not implemented yet): gate merges to `main` on this script
+passing, the same way a real CI pipeline would. For now it's a manual step
+run at checkpoint review time.

docs/testing/test_inventory.md

@@ -0,0 +1,78 @@
+# Test Inventory
+
+What automated coverage actually exists, what it actually verifies, and what
+doesn't have coverage yet. Keep this current as tests are added — it's the
+thing a Package Checkpoint review (see `docs/testing/README.md`) reads first
+to know what "run the tests" actually checked.
+
+Run everything below in one shot with `scripts/run_checkpoint_tests.py`.
+
+Last verified against `main`: 2026-08-19 (commit `1c75367`).
+
+## Backend — `backend/tests/` (pytest)
+
+Run: `cd backend && python -m pytest -v` (needs `DATABASE_URL` pointed at a
+reachable Postgres — see the runner script; most of these tests don't
+actually touch the DB, but the app's import chain requires a valid URL to
+construct).
+
+**Current total: 38 tests, all passing on a clean `main` checkout.**
+
+| File | Tests | What it covers |
+|---|---|---|
+| `test_auth_age_gate.py` | 10 | `calculate_age()` date-math correctness (exact boundary, leap years, birthday-not-yet-this-year) + `RegisterRequest` date-of-birth validation (parametrized valid/invalid date rejection). Backs the 18+ registration gate (PR #23). |
+| `test_gltf_metadata.py` | 21 | glTF/GLB binary + JSON parsing: magic-byte detection, chunk-padding handling, mesh/animation/texture-reference metadata extraction, malformed-input rejection. Backs the asset-import pipeline (PR #27). |
+
+**What these are, honestly:** pure unit tests of standalone functions
+(`calculate_age`, the glTF parser, Pydantic validators). None of them spin
+up the FastAPI app or hit a real endpoint — they run in ~1s and don't
+actually need Postgres reachable at all (the import chain just needs a
+syntactically valid `DATABASE_URL`, nothing connects during collection).
+
+**Known coverage gaps** (real gaps, not placeholders — nothing enforces filling
+these yet):
+- No integration/endpoint tests at all — `/register`, `/login`, `/refresh`,
+  `/worlds`, `/assets/*` have zero tests that actually call them through
+  the FastAPI app (e.g. via `httpx.AsyncClient` + `ASGITransport`) against a
+  real (or test) database. Everything currently shipped works because it
+  was manually verified at merge time (checkpoint review), not because a
+  test asserts it.
+- No tests for the RS256 auth upgrade (key generation, refresh-token
+  issuance/persistence) — PR #30, pending review as of this writing,
+  manually verified (correct key usage, all 38 existing tests still pass)
+  but not covered by an automated test of its own yet.
+- No tests for the moderation schema/migration (in progress as of this
+  writing) beyond "the migration runs."
+
+## Godot client — `scripts/smoke_test_*.gd`
+
+**Nothing merged into `main` yet as of this writing** — `sandbox_probe/test_script.gd`
+is the only Godot script on `main` right now, and it's **not a real
+test** (a leftover manual probe, returns a hardcoded string, asserts
+nothing). Don't count it toward coverage; delete or repurpose it if anyone
+actually needs a sandbox probe again.
+
+`scripts/smoke_test_api.gd` (PC1, PR #29, pending review as of this writing)
+will be the first real one once merged — `ApiClient` autoload's
+`health_check()` against a **live backend** (set `AGP_API_BASE_URL` to point
+at one), verified by hand end-to-end before opening the PR: exercises the
+real HTTP request path (`HTTPRequest` node lifecycle, JSON parse, the
+result-dictionary contract), not just that the script compiles. Exits 1 on
+failure, so it's CI/script-friendly.
+
+Run (once merged): `godot --headless --path . --import` once (builds the
+class cache — skip this and every `class_name`-declared class falsely
+errors as undeclared), then for each `scripts/smoke_test_*.gd`:
+`godot --headless --path . --script res://scripts/<name>.gd`
+
+**Known gap once it lands:** only `health_check()` is exercised end-to-end.
+`login`, `register`, `get_worlds`, `get_me` are implemented (see
+`scripts/api_client.gd`) but have no smoke coverage yet — each would need a
+real user/world fixture in the target backend to test against meaningfully.
+
+## What "full coverage" should eventually mean here
+
+Not defined precisely yet — the honest target as of 2026-08-19 is just
+"more than pure-function unit tests." As real integration/endpoint tests get
+added, update the tables above rather than letting this doc drift stale;
+a wrong inventory is worse than no inventory.

export_presets.cfg

@@ -0,0 +1,74 @@
+[preset.0]
+
+name="Linux"
+platform="Linux/X11"
+runnable=true
+advanced_options=false
+dedicated_server=false
+custom_features=""
+export_filter="all_resources"
+include_filter=""
+exclude_filter=""
+export_path="export/linux/agp-game.x86_64"
+encryption_include_filters=""
+encryption_exclude_filters=""
+encrypt_pck=false
+encrypt_directory=false
+script_export_mode=2
+
+[preset.0.options]
+
+custom_template/debug=""
+custom_template/release=""
+debug/export_console_wrapper=1
+binary_format/embed_pck=false
+texture_format/bptc=true
+texture_format/s3tc=true
+texture_format/etc=false
+texture_format/etc2=false
+binary_format/architecture="x86_64"
+ssh_remote_deploy/enabled=false
+
+[preset.1]
+
+name="Windows Desktop"
+platform="Windows Desktop"
+runnable=true
+advanced_options=false
+dedicated_server=false
+custom_features=""
+export_filter="all_resources"
+include_filter=""
+exclude_filter=""
+export_path="export/windows/agp-game.exe"
+encryption_include_filters=""
+encryption_exclude_filters=""
+encrypt_pck=false
+encrypt_directory=false
+script_export_mode=2
+
+[preset.1.options]
+
+custom_template/debug=""
+custom_template/release=""
+debug/export_console_wrapper=1
+binary_format/embed_pck=false
+texture_format/bptc=true
+texture_format/s3tc=true
+texture_format/etc=false
+texture_format/etc2=false
+binary_format/architecture="x86_64"
+codesign/enable=false
+application/icon=""
+application/console_wrapper_icon=""
+application/icon_interpolation=4
+application/file_version=""
+application/product_version=""
+application/company_name=""
+application/product_name=""
+application/file_description=""
+application/copyright=""
+application/trademarks=""
+application/export_angle=0
+application/export_d3d12=0
+d3d12/agility_sdk_multizip=0

project.godot

@@ -9,9 +9,12 @@ config_version=5
 config/name="AGP-Game"
 run/main_scene="res://scenes/main_menu.tscn"
 config/features=PackedStringArray("4.6.2")
+agp/api_base_url="http://127.0.0.1:8000"
 
 [autoload]
 
+ApiClient="*res://scripts/api_client.gd"
+
 [display]
 
 window/size/viewport_width=1920

scripts/api_client.gd

@@ -0,0 +1,292 @@
+extends Node
+## Central HTTP client singleton (autoload name: "ApiClient").
+##
+## Every network call in the game flows through this class. Callers use the
+## high-level helpers ([method login], [method register], [method get_worlds],
+## [method health_check], [method get_me]) or the generic [method request]
+## primitive. All results conform to the result-dictionary contract below.
+##
+## [b]Result Dictionary Contract[/b]
+## Every public method returns (after `await`) a Dictionary with this shape:
+##
+##     {
+##         "ok":     bool,     # true for HTTP 2xx, false otherwise
+##         "status": int,      # HTTP status code (0 on network failure)
+##         "data":   Variant,  # parsed JSON body on success (null otherwise)
+##         "detail": String,   # human-readable message
+##     }
+##
+## Network failures (timeout / DNS / refused connection) return `status == 0`
+## with a `detail` describing the transport failure. Non-2xx responses return
+## the real HTTP status and the backend's `detail` field from the JSON error
+## body when present. No caller can crash on a failed request.
+##
+## [b]Token storage[/b]
+## JWTs are kept in memory. [method set_token] is the single seam for future
+## disk persistence (override it to save to `user://`).
+##
+## [b]Usage[/b]
+##     var result: Dictionary = await ApiClient.login("alice", "secret")
+##     if result.ok:
+##         print("Logged in!")
+##     else:
+##         print("Error: ", result.detail)
+
+# ---------------------------------------------------------------------------
+# Token storage
+# ---------------------------------------------------------------------------
+
+var _access_token: String = ""
+var _token_type: String = "Bearer"
+
+## Full Authorization header value, e.g. "Bearer eyJ...". Empty if no token.
+var bearer_token: String:
+	get:
+		return _token_type + " " + _access_token if _access_token != "" else ""
+
+
+## Whether an access token is currently stored.
+func has_token() -> bool:
+	return _access_token != ""
+
+
+## Set the access token (called after login / register / token refresh).
+## This is the persistence seam: override to also write to disk.
+func set_token(access_token: String, token_type: String = "Bearer") -> void:
+	_access_token = access_token
+	_token_type = token_type
+
+
+## Clear stored tokens.
+func clear_token() -> void:
+	_access_token = ""
+	_token_type = "Bearer"
+
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+var _base_url: String = "http://127.0.0.1:8000"
+
+## Request timeout in seconds. 0 disables the timeout.
+var timeout_seconds: float = 10.0
+
+
+func _ready() -> void:
+	# Environment variable override (e.g. for headless smoke tests against a
+	# backend on a non-default port). Falls back to the ProjectSetting, then
+	# to the documented default.
+	var env_url := OS.get_environment("AGP_API_BASE_URL")
+	if env_url != "":
+		_base_url = env_url.rstrip("/")
+	else:
+		_base_url = str(ProjectSettings.get_setting(
+			"application/agp/api_base_url",
+			"http://127.0.0.1:8000"
+		)).rstrip("/")
+
+
+# ---------------------------------------------------------------------------
+# Core request primitive
+# ---------------------------------------------------------------------------
+
+## Generic request primitive. Awaitable via `await`.
+##
+## Uses a dedicated HTTPRequest node per call so concurrent requests can never
+## cross-talk, and so the result maps 1:1 to the awaiting caller.
+##
+## @param method       HTTPClient.Method enum value (GET/POST/PUT/PATCH/DELETE).
+## @param path         URL path, e.g. "/api/health".
+## @param body         Request body string (JSON or form-encoded).
+## @param content_type "application/json" or "application/x-www-form-urlencoded".
+## @param require_auth If true, attach the stored bearer token when present.
+## @return Result dictionary conforming to the contract.
+func request(
+	method: HTTPClient.Method,
+	path: String,
+	body: String = "",
+	content_type: String = "application/json",
+	require_auth: bool = false
+) -> Dictionary:
+	var http := HTTPRequest.new()
+	http.timeout = timeout_seconds
+	http.max_redirects = 8
+	http.accept_gzip = true
+	add_child(http)
+
+	var headers := PackedStringArray()
+	headers.append("Accept: application/json")
+	if content_type != "":
+		headers.append("Content-Type: " + content_type)
+	if require_auth and has_token():
+		headers.append("Authorization: " + bearer_token)
+
+	var url := _base_url + path
+	var err := http.request(url, headers, method, body)
+	if err != OK:
+		http.queue_free()
+		return _make_result(false, 0, null, "Failed to start request: " + _error_string(err))
+
+	# request_completed emits (result, response_code, headers, body).
+	var args: Array = await http.request_completed
+	var result_code: int = args[0]
+	var response_code: int = args[1]
+	var response_body: PackedByteArray = args[3]
+	http.queue_free()
+
+	# Transport-level failure (timeout / DNS / refused / TLS, etc.).
+	if result_code != HTTPRequest.RESULT_SUCCESS:
+		return _make_result(false, 0, null, _transport_error_detail(result_code))
+
+	# Server accepted the connection but returned no HTTP status line.
+	if response_code == 0:
+		return _make_result(false, 0, null, "No response received from server.")
+
+	var json_string := response_body.get_string_from_utf8()
+	var ok := response_code >= 200 and response_code < 300
+
+	if ok:
+		var data: Variant = _parse_json(json_string)
+		return _make_result(true, response_code, data, "OK")
+
+	# Non-2xx: surface the backend's "detail" message when available.
+	var detail := "HTTP error %d" % response_code
+	var parsed: Variant = _parse_json(json_string)
+	if parsed is Dictionary and (parsed as Dictionary).has("detail"):
+		detail = str((parsed as Dictionary)["detail"])
+	return _make_result(false, response_code, null, detail)
+
+
+# ---------------------------------------------------------------------------
+# High-level helpers
+# ---------------------------------------------------------------------------
+
+## Log in with username/password (OAuth2PasswordRequestForm).
+## On success stores the returned access token.
+func login(username: String, password: String) -> Dictionary:
+	var form := "username=" + username.uri_encode() + "&password=" + password.uri_encode()
+	var result := await request(
+		HTTPClient.METHOD_POST,
+		"/api/auth/login",
+		form,
+		"application/x-www-form-urlencoded",
+		false
+	)
+	_store_token_from_result(result)
+	return result
+
+
+## Register a new user. On success stores the returned access token.
+## @param date_of_birth ISO date string "YYYY-MM-DD".
+func register(
+	username: String,
+	email: String,
+	password: String,
+	date_of_birth: String
+) -> Dictionary:
+	var payload := {
+		"username": username,
+		"email": email,
+		"password": password,
+		"date_of_birth": date_of_birth,
+	}
+	var result := await request(
+		HTTPClient.METHOD_POST,
+		"/api/auth/register",
+		JSON.stringify(payload),
+		"application/json",
+		false
+	)
+	_store_token_from_result(result)
+	return result
+
+
+## List worlds visible to the current user (requires auth).
+## @param visibility Optional filter: "public", "private", "friends_only".
+func get_worlds(skip: int = 0, limit: int = 50, visibility: String = "") -> Dictionary:
+	var path := "/api/worlds/?skip=%d&limit=%d" % [skip, limit]
+	if visibility != "":
+		path += "&visibility=" + visibility.uri_encode()
+	return await request(HTTPClient.METHOD_GET, path, "", "application/json", true)
+
+
+## Ping the backend health endpoint (no auth).
+func health_check() -> Dictionary:
+	return await request(HTTPClient.METHOD_GET, "/api/health", "", "application/json", false)
+
+
+## Fetch the current user's profile from the stored JWT (requires auth).
+func get_me() -> Dictionary:
+	return await request(HTTPClient.METHOD_GET, "/api/users/me", "", "application/json", true)
+
+
+# ---------------------------------------------------------------------------
+# Internals
+# ---------------------------------------------------------------------------
+
+func _store_token_from_result(result: Dictionary) -> void:
+	if result.ok and result.data is Dictionary:
+		var token: String = str((result.data as Dictionary).get("access_token", ""))
+		if token != "":
+			set_token(token)
+
+
+func _parse_json(text: String) -> Variant:
+	if text == "":
+		return null
+	var parsed: Variant = JSON.parse_string(text)
+	if parsed == null:
+		# null is ambiguous (valid JSON "null" vs parse failure). Fall back to
+		# the raw string so callers never lose the body entirely.
+		return text if text != "null" else null
+	return parsed
+
+
+func _make_result(ok: bool, status: int, data: Variant, detail: String) -> Dictionary:
+	return {
+		"ok": ok,
+		"status": status,
+		"data": data,
+		"detail": detail,
+	}
+
+
+func _transport_error_detail(result_code: int) -> String:
+	match result_code:
+		HTTPRequest.RESULT_CANT_CONNECT:
+			return "Could not connect to server. Is it running?"
+		HTTPRequest.RESULT_CANT_RESOLVE:
+			return "Could not resolve server hostname."
+		HTTPRequest.RESULT_CONNECTION_ERROR:
+			return "Connection error."
+		HTTPRequest.RESULT_TLS_HANDSHAKE_ERROR:
+			return "TLS handshake failed."
+		HTTPRequest.RESULT_NO_RESPONSE:
+			return "No response from server."
+		HTTPRequest.RESULT_BODY_SIZE_LIMIT_EXCEEDED:
+			return "Response body too large."
+		HTTPRequest.RESULT_BODY_DECOMPRESS_FAILED:
+			return "Failed to decompress response body."
+		HTTPRequest.RESULT_REQUEST_FAILED:
+			return "Request failed."
+		HTTPRequest.RESULT_TIMEOUT:
+			return "Request timed out."
+		_:
+			return "Network error (code %d)." % result_code
+
+
+func _error_string(err_code: int) -> String:
+	match err_code:
+		OK:
+			return "OK"
+		ERR_UNCONFIGURED:
+			return "HTTPRequest not configured (not in tree)."
+		ERR_BUSY:
+			return "HTTPRequest is busy with a previous request."
+		ERR_INVALID_PARAMETER:
+			return "Invalid URL format."
+		ERR_CANT_CONNECT:
+			return "Cannot connect to host."
+		_:
+			return "Unknown error (%d)." % err_code

scripts/build.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Headless CI export for Linux and Windows.
+#
+# Requires:
+#   - Godot 4.6.2 (the exact version this project + export_presets.cfg were
+#     built against; a different Godot minor version's export templates are
+#     not guaranteed compatible)
+#   - The matching export templates installed at
+#     ~/.local/share/godot/export_templates/4.6.2.stable/
+#     (download: https://godotengine.org/download/archive/4.6.2-stable/,
+#     "Export templates" -- NOT the same as the editor download)
+#   - godot on PATH (or set GODOT_BIN below)
+#
+# Usage: scripts/build.sh
+# Output: export/linux/agp-game.x86_64, export/windows/agp-game.exe
+
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+GODOT_BIN="${GODOT_BIN:-godot}"
+if ! command -v "$GODOT_BIN" >/dev/null 2>&1; then
+    if [ -x "$HOME/godot/godot" ]; then
+        GODOT_BIN="$HOME/godot/godot"
+    else
+        echo "godot binary not found (checked PATH and ~/godot/godot)." >&2
+        exit 1
+    fi
+fi
+
+echo "Godot version: $("$GODOT_BIN" --version)"
+
+mkdir -p export/linux export/windows
+
+echo "=== Exporting Linux/X11 ==="
+"$GODOT_BIN" --headless --path . --export-release "Linux" export/linux/agp-game.x86_64
+
+echo "=== Exporting Windows Desktop ==="
+"$GODOT_BIN" --headless --path . --export-release "Windows Desktop" export/windows/agp-game.exe
+
+echo ""
+echo "Build artifacts:"
+ls -la export/linux export/windows

scripts/run_checkpoint_tests.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""Run the full automated test inventory for a Package Checkpoint review.
+
+See docs/testing/test_inventory.md for what each suite actually covers (and
+doesn't) -- keep that doc in sync as tests are added, this script just runs
+whatever's there.
+
+Usage:
+    python scripts/run_checkpoint_tests.py [--keep-postgres] [--postgres-port PORT]
+
+Exits 0 if everything that ran passed, 1 otherwise. Suites with nothing to
+run (e.g. no scripts/smoke_test_*.gd yet, or no Godot binary found) are
+reported as SKIPPED, not counted as a failure.
+"""
+import argparse
+import glob
+import os
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+BACKEND = ROOT / "backend"
+
+
+def run(cmd, cwd=None, env=None, capture=False):
+    print(f"$ {' '.join(cmd)}" + (f"  (cwd={cwd})" if cwd else ""))
+    return subprocess.run(cmd, cwd=cwd, env=env, capture_output=capture, text=True)
+
+
+def find_godot():
+    for candidate in ("godot", str(Path.home() / "godot" / "godot")):
+        if shutil.which(candidate) or Path(candidate).is_file():
+            return candidate
+    return None
+
+
+def wait_for_http(url: str, timeout_s: int = 20) -> bool:
+    import urllib.request
+    import urllib.error
+
+    deadline = time.time() + timeout_s
+    while time.time() < deadline:
+        try:
+            with urllib.request.urlopen(url, timeout=2) as resp:
+                if resp.status == 200:
+                    return True
+        except (urllib.error.URLError, ConnectionError, OSError):
+            pass
+        time.sleep(1)
+    return False
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--keep-postgres", action="store_true",
+                         help="Don't tear down the checkpoint Postgres container afterward")
+    parser.add_argument("--postgres-port", default=os.environ.get("CHECKPOINT_POSTGRES_PORT", "5432"),
+                         help="Host port for the checkpoint's own Postgres container (default 5432 -- "
+                              "override if that's already in use on this machine)")
+    parser.add_argument("--backend-port", default=os.environ.get("CHECKPOINT_BACKEND_PORT", "18080"),
+                         help="Port to run the backend server on for the Godot smoke tests")
+    args = parser.parse_args()
+
+    results = {}
+
+    # --- Backend: bring up Postgres ---
+    compose_env = os.environ.copy()
+    compose_env["COMPOSE_PROJECT_NAME"] = "agp-checkpoint"
+    compose_env["POSTGRES_HOST_PORT"] = args.postgres_port
+    compose_env["POSTGRES_PORT"] = args.postgres_port  # some branches use this name instead, see tools/definitions.py
+    print("=== Backend: bringing up Postgres ===")
+    run(["docker", "compose", "up", "-d", "postgres"], cwd=BACKEND, env=compose_env)
+
+    print("Waiting for Postgres to be ready...")
+    pg_ready = False
+    for _ in range(20):
+        r = run(["docker", "compose", "exec", "-T", "postgres", "pg_isready", "-U", "agp_user", "-d", "agp_db"],
+                cwd=BACKEND, env=compose_env, capture=True)
+        if r.returncode == 0:
+            pg_ready = True
+            break
+        time.sleep(1)
+    if not pg_ready:
+        print("Postgres never became ready -- aborting.")
+        sys.exit(1)
+
+    db_url = f"postgresql+asyncpg://agp_user:agp_password@localhost:{args.postgres_port}/agp_db"
+    backend_env = os.environ.copy()
+    backend_env["DATABASE_URL"] = db_url
+
+    print("\n=== Backend: alembic upgrade head ===")
+    r = run([sys.executable, "-m", "alembic", "upgrade", "head"], cwd=BACKEND, env=backend_env)
+    results["migrations (fresh DB)"] = r.returncode == 0
+
+    print("\n=== Backend: pytest ===")
+    r = run([sys.executable, "-m", "pytest", "-v"], cwd=BACKEND, env=backend_env)
+    results["backend pytest"] = r.returncode == 0
+
+    # --- Godot: headless smoke tests (need a live backend server) ---
+    godot_bin = find_godot()
+    smoke_tests = sorted(glob.glob(str(ROOT / "scripts" / "smoke_test_*.gd")))
+
+    if not godot_bin:
+        print("\n=== Godot: binary not found (checked PATH and ~/godot/godot), skipping smoke tests ===")
+        results["godot smoke tests"] = None
+    elif not smoke_tests:
+        print("\n=== Godot: no scripts/smoke_test_*.gd found yet, nothing to run ===")
+        results["godot smoke tests"] = None
+    else:
+        print(f"\n=== Backend: starting server on :{args.backend_port} for Godot smoke tests ===")
+        server_proc = subprocess.Popen(
+            [sys.executable, "-m", "uvicorn", "app.main:app", "--host", "127.0.0.1", "--port", args.backend_port],
+            cwd=BACKEND, env=backend_env,
+            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+        )
+        try:
+            base_url = f"http://127.0.0.1:{args.backend_port}"
+            if not wait_for_http(f"{base_url}/api/health"):
+                print("Backend server never became healthy -- skipping Godot smoke tests.")
+                results["godot smoke tests"] = False
+            else:
+                godot_env = os.environ.copy()
+                godot_env["AGP_API_BASE_URL"] = base_url
+
+                print("=== Godot: import pass (builds the class cache) ===")
+                run([godot_bin, "--headless", "--path", str(ROOT), "--import"], env=godot_env)
+                run([godot_bin, "--headless", "--path", str(ROOT), "--quit"], env=godot_env)
+
+                godot_ok = True
+                for test in smoke_tests:
+                    rel = os.path.relpath(test, ROOT)
+                    print(f"\n--- {rel} ---")
+                    r = run([godot_bin, "--headless", "--path", str(ROOT), "--script", f"res://{rel}"], env=godot_env)
+                    if r.returncode != 0:
+                        godot_ok = False
+                results["godot smoke tests"] = godot_ok
+        finally:
+            server_proc.terminate()
+            try:
+                server_proc.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                server_proc.kill()
+
+    if not args.keep_postgres:
+        print("\n=== Backend: tearing down checkpoint Postgres ===")
+        run(["docker", "compose", "down", "-v", "postgres"], cwd=BACKEND, env=compose_env)
+
+    # --- Summary ---
+    print("\n" + "=" * 50)
+    print("SUMMARY")
+    print("=" * 50)
+    overall_ok = True
+    for name, ok in results.items():
+        if ok is None:
+            print(f"  {name}: SKIPPED")
+        elif ok:
+            print(f"  {name}: PASS")
+        else:
+            print(f"  {name}: FAIL")
+            overall_ok = False
+
+    print("\nSee docs/testing/test_inventory.md for what each suite actually covers (and doesn't).")
+    sys.exit(0 if overall_ok else 1)
+
+
+if __name__ == "__main__":
+    main()

scripts/smoke_test_api.gd

@@ -0,0 +1,46 @@
+extends SceneTree
+## Headless smoke test for the ApiClient autoload.
+##
+## Run with:
+##     godot --headless --path . --script res://scripts/smoke_test_api.gd
+##
+## Requires the backend to be running (default base URL
+## `application/agp/api_base_url` -> http://127.0.0.1:8000).
+##
+## Calls the real autoload's `health_check()` (which exercises the generic
+## `request()` primitive) and exits 0 on a `status == "ok"` response, 1
+## otherwise. This script is intentionally NOT wired into any game scene.
+
+
+func _initialize() -> void:
+	_run()
+
+
+func _run() -> void:
+	# _initialize() fires before the SceneTree has processed its first frame,
+	# so a freshly add_child()'d HTTPRequest node isn't reliably considered
+	# "inside tree" yet (request_raw fails with !is_inside_tree()). One frame
+	# of delay is enough; this only matters for --script mode, not a real
+	# running game.
+	await process_frame
+
+	# Godot's --script/SceneTree runner doesn't resolve autoload singletons
+	# as bare global identifiers at compile time (the node exists at
+	# runtime -- root.has_node("ApiClient") is true -- but referencing it as
+	# a plain identifier fails with "Identifier not found: ApiClient" during
+	# script compilation). get_node sidesteps compile-time resolution
+	# entirely. This only affects --script mode; a real game scene resolves
+	# the bare autoload name normally.
+	var api_client := root.get_node("ApiClient")
+	print("SMOKE: calling ApiClient.health_check() ...")
+	var result: Dictionary = await api_client.health_check()
+	print("SMOKE: result = ", result)
+
+	if result.ok \
+			and result.data is Dictionary \
+			and str((result.data as Dictionary).get("status", "")) == "ok":
+		print("SMOKE RESULT: PASS (status=ok)")
+		quit(0)
+	else:
+		printerr("SMOKE RESULT: FAIL")
+		quit(1)