docs/checkpoints/PC1.md

@@ -0,0 +1,84 @@
+# Package Checkpoint 1 (PC1)
+
+Validated 2026-08-20 against `main` commit `927f9bd`, from a genuinely fresh
+clone (not a reused agent workspace).
+
+## Automated validation
+
+Run with `scripts/run_checkpoint_tests.py` — see
+`docs/testing/test_inventory.md` for exactly what each suite covers.
+
+| Check | Result |
+|---|---|
+| Alembic migrations, fresh DB | PASS |
+| Backend pytest | 68/68 PASS |
+| Godot smoke tests (4 files) | ALL PASS |
+| Linux export (`agp-game.x86_64`) | Builds, verified as a real ELF64 binary |
+| Windows export (`agp-game.exe`) | Builds, verified as a real PE32+ binary |
+
+## Problems found during this checkpoint (fixed, tracked as tasks)
+
+- Roadmap showed the Godot Engine Scaffold feature amber despite 6/6 tasks
+  done — a historical data gap (a review-feedback follow-up task's
+  supersession link was never recorded, predating when that field started
+  being tracked). Backfilled in the PM database; confirmed green.
+- `docs/testing/test_inventory.md` was stale (said 38 backend tests,
+  actually 68; said no integration tests existed, 4 real ones had landed).
+  Fixed via task `398bf1a22a2d` / PR #40.
+
+## What's actually testable right now
+
+Login/register/browse-worlds only — there's no joinable gameplay yet. That's
+the real scope of PC1; don't expect more when playtesting.
+
+- Register a new account (18+ only, rejected otherwise)
+- Log out, log back in with the same credentials
+- Play → Browse Worlds — loads a (currently empty) world list with no errors
+
+## Manual playtest: backend on cloudbison, client on pinkbison
+
+Cloudbison's LAN IP: `192.168.58.138`. Pinkbison's: `192.168.58.124`.
+
+### 1. On cloudbison — start a real (persistent, not throwaway) backend
+
+```bash
+cd ~
+git clone http://localhost:3000/daddy/agp-game.git agp-game-playtest
+cd agp-game-playtest/backend
+docker compose up -d postgres
+docker compose exec -T postgres pg_isready -U agp_user -d agp_db   # wait for this to succeed
+
+export DATABASE_URL="postgresql+asyncpg://agp_user:agp_password@localhost:5432/agp_db"
+export JWT_ALGORITHM="RS256"
+/home/daddy/agp/venv/bin/python3 -m alembic upgrade head
+nohup /home/daddy/agp/venv/bin/python3 -m uvicorn app.main:app --host 0.0.0.0 --port 8000 > /tmp/agp-backend.log 2>&1 &
+disown
+```
+
+`--host 0.0.0.0` matters — the default `127.0.0.1` only listens on loopback
+and pinkbison won't be able to reach it. Verify: `curl
+http://localhost:8000/api/health` should return `{"status":"ok",...}`.
+
+### 2. On pinkbison — get the game and point it at cloudbison
+
+Copy `export/windows/agp-game.exe` (or `export/linux/agp-game.x86_64`,
+whichever matches pinkbison's OS) from cloudbison, or clone the repo there
+and run `scripts/build.sh` locally. Launch with the backend URL as an env
+var so you don't have to rebuild to change it:
+
+- Windows (PowerShell): `$env:AGP_API_BASE_URL="http://192.168.58.138:8000"; .\agp-game.exe`
+- Linux: `AGP_API_BASE_URL=http://192.168.58.138:8000 ./agp-game.x86_64`
+
+### 3. Tear down when done
+
+```bash
+# on cloudbison
+pkill -f "uvicorn app.main:app"
+cd ~/agp-game-playtest/backend && docker compose down -v
+```
+
+## Status
+
+`config/checkpoint_focus_feature_ids` in the AGP framework (`~/agp`) still
+restricts agent claiming to the 5 PC1-scope features. Agents will not move
+on to post-PC1 work until that's widened.