docs(checkpoints): PC4 scope, test plan, and capabilities documentation

docs/checkpoints/PC4.md

@@ -0,0 +1,64 @@
+# Package Checkpoint 4 (PC4) — "A world you can build and be social in"
+
+> **Status: Complete & Verified.** PC4 delivers the integrated multi-user social world platform: in-game building and persistence (M2, M7), comprehensive social graph, chat, and presence (M8), virtual economy, marketplace, and creator payouts (M9), and home discovery with search, category filtering, and trending heuristics (M10).
+
+Built and verified by the Antigravity fleet, branch `agent/2b4212c24690-pc4-checkpoint` → `main`.
+
+---
+
+## 1. What's Real and Verified (`scripts/run_checkpoint_tests.py`)
+
+| Check / Subsystem | Status | Verification Detail |
+|---|---|---|
+| Alembic Migrations (0001 → 0015) | PASS | Hermetic clean run, head revision `0015_add_discovery_metadata` |
+| Backend API Test Suite | PASS | 100+ tests across auth, worlds, social, chat, wallet, marketplace, discovery |
+| Godot Headless Smoke Tests | PASS | 20+ headless smoke suites covering all UIs, network, avatars, economy, discovery |
+| 2-Player Multiplayer (`run_multiplayer_2p_test.sh`) | PASS | Real dedicated server + 2 simultaneous Godot client processes |
+| Fresh-Clone Boot (`verify_fresh_clone.sh`) | PASS | Clean clone imports, compiles, and boots without script errors |
+| Windows Desktop .exe Export | PASS | Packaged release binary with baked-in backend endpoint via `checkpoint_ops.py` |
+
+---
+
+## 2. Milestone Capabilities Included
+
+### M2 & M7 — World Persistence & In-Game Editor
+- **Server Persistence**: World rooms, chunk coordinates (cx, cy, cz), binary chunk payload codec, chunk revision audit trail.
+- **In-Game Editor**: Tools (Brush, Erase, Object Placement, Select, Transform), chunk edit model, undo/redo stack, non-blocking HTTP chunk saving.
+
+### M8 — Social: Friends, Presence, Chat, Groups & Profiles
+- **Social Graph**: Friend requests (pending, accepted, declined), follow/unfollow, bidirectional block enforcement.
+- **Presence & Status**: Real-time Redis-backed heartbeats with custom status messages, friends presence queries.
+- **Chat System**: 1-on-1 direct messaging, in-world spatial chat, chat moderation report queue with profanity filtering.
+- **Groups**: Group creation, membership roles (owner, admin, member), member management, group transfer.
+- **Public Profiles**: Bio, custom avatar rendering, favorite worlds listing, privacy controls.
+- **WebSocket Gateway**: Dual endpoint (`/api/ws`, `/v1/ws`) broadcasting presence and real-time chat messages.
+- **Godot Client & UIs**: `FriendsPresenceUI`, `ChatUI`, `ProfileUI`, `GroupsUI`.
+
+### M9 — Economy: Wallets, Marketplace & Creator Payouts
+- **Wallets & Ledger**: Double-entry accounting for balance credits, debits, transfers, and escrow.
+- **Purchases**: `PaymentProvider` abstraction with simulated and external payment confirmations.
+- **Marketplace**: Catalog item models, active listings, 30/70 platform/creator fee splits with atomic escrow settlement.
+- **Creator Payouts**: Payout request lifecycle (`pending` → `approved` / `rejected` → `paid`), admin audit review.
+- **Godot Client & UIs**: `WalletUI` (balance & transaction history), `MarketplaceUI` (browse & buy), `SellingPayoutUI` (create listings & request payouts).
+
+### M10 — Discovery: Browse, Search & Home Feed
+- **World Discovery Metadata**: Categories, tags (ARRAY with GIN indexing), play count, and last played timestamp.
+- **Visit Tracking**: Atomic increment of `play_count` and `world_visits` log with request deduplication.
+- **Browse & Search API**: Full-text name ILIKE query, category exact match, tag overlap (`&&`), sorting (`newest`, `most_played`, `trending`).
+- **Trending Heuristic**: Time-decay weighted scoring over recent visits (last 24h: 3x, 3d: 2x, 7d: 1x) via single aggregate outer-join query.
+- **Godot Client & UI**: `DiscoveryApiClient` and `DiscoveryUI` (`scenes/discovery_ui.tscn`) with live search, dropdown filters, pagination, and one-click world entry.
+
+---
+
+## 3. Playtest Guide
+
+1. **Dashboard Start**:
+   - Open http://localhost:7070/checkpoints
+   - Locate **PC4: A world you can build and be social in**
+   - Click **Start Backend** (launches backend on `:28004`, Postgres on `:25544`, ENet game servers on `27100–27149`)
+   - The backend automatically seeds the `playtester` account and 5 sample worlds across categories.
+2. **Download & Play**:
+   - Click **Download Windows .exe**
+   - Launch `agp-game.exe` (automatically targets the PC4 backend instance)
+   - Browse the **Discover** tab to see curated, trending, and categorized worlds
+   - Enter worlds, socialize, chat, trade in the marketplace, and build.