diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md
new file mode 100644
index 0000000..dca17e1
--- /dev/null
+++ b/PROJECT_CONTEXT.md
@@ -0,0 +1,141 @@
+# ZeroLagHub – Project Context
+
+## What It Is
+Game server hosting platform targeting modded, indie, and emerging games.
+Competitive advantages: LXC containers (20-30% perf over Docker), custom
+agent architecture, open-source stack, developer-to-player pipeline that
+turns mod developers into a distribution channel.
+
+System posture: stable, controlled expansion phase.
+
+---
+
+## Infrastructure (Proxmox)
+
+### Active VMs
+
+| VM | Name | Role |
+|----|------|------|
+| 104 | zlh-monitor | Prometheus/Grafana monitoring |
+| 105 | zlh-router | Core services router (node 1) |
+| 300 | zlh-velocity | Minecraft Velocity proxy |
+| 1000 | zlh-router | Game + dev server router (node 2) |
+| 1001 | zlh-dns | Technitium DNS |
+| 1002 | zlh-proxy | Traefik (dev + other games) |
+| 1003 | zlh-artifacts | Runtime binaries + Minecraft server jars (agent install source) |
+| 1004 | zlh-zpack-proxy | Traefik (zpack stack) |
+| 1005 | zpack-api | Node.js API |
+| 1006 | zlh-zpack-router | zpack stack router |
+| 1100 | zpack-portal | Next.js frontend |
+| 2001 | zlh-back | PBS backup + Backblaze B2 |
+
+### Legacy / Reference Only (not active production)
+
+| VM | Name | Notes |
+|----|------|-------|
+| 100 | zlh-panel | Old Pterodactyl panel — kept for reference |
+| 101 | zlh-wings | Old Wings — kept for reference |
+| 103 | zlh-api | Old API VM — kept for reference |
+
+---
+
+## Stack
+
+**API (zpack-api, VM 1005):** Node.js ESM, Express 5, Prisma 6, MariaDB,
+Redis, BullMQ, JWT, Stripe, argon2, ssh2, WebSocket
+
+**Portal (zpack-portal, VM 1100):** Next.js 15, TypeScript, TailwindCSS,
+Axios, WebSocket console. Sci-fi HUD aesthetic (steel textures, neon
+accents, beveled panels).
+
+**Agent (zlh-agent):** Go 1.21, stdlib HTTP, creack/pty, gorilla/websocket.
+Runs inside every game/dev container. Only process with direct filesystem
+access. Pulls runtimes + server jars from zlh-artifacts (VM 1003).
+
+---
+
+## Agent (Operational)
+
+- HTTP server on :18888, internal only — API is the only caller
+- Container types: `game` (Minecraft, Rust, Valheim, etc.) and `dev`
+  (node/python/go/java runtimes)
+- Runtime root: `/opt/zlh/minecraft/<runtime>/<world>/`
+- Lifecycle: POST /config triggers async provision + start pipeline
+- Filesystem: strict path allowlist, atomic writes, shadow backups
+  (7-day retention, 6h cleanup cycle)
+- Upload paths: `mods/*.jar` (250MB), `world/datapacks/*.zip` (100MB)
+- Upload transport: raw `http.request` piping (`req.pipe(proxyReq)`),
+  never fetch()
+- Console: PTY-backed WebSocket, one read loop per container
+- Self-update: periodic check + apply
+- Forge/Neoforge: automated 5-step post-install patch sequence
+- Modrinth mod lifecycle: install/enable/disable/delete — fully operational
+- Provenance: `.zlh_metadata.json` — source is `null` if not set,
+  no curated inference currently implemented
+
+---
+
+## Game Support
+
+**Production:** Minecraft (vanilla/Fabric/Paper/Forge/Neoforge), Rust,
+Terraria, Project Zomboid
+
+**In Pipeline:** Valheim, Palworld, Vintage Story, Core Keeper
+
+---
+
+## Developer-to-Player Pipeline (Revenue Model)
+
+```
+LXC Dev Environment ($15-40/mo)
+  → Game/mod creation + testing
+  → Testing servers (50% dev discount)
+  → Player community referrals (25% player discount)
+  → Developer revenue share (5-10% commission)
+  → Viral growth
+```
+
+Revenue multiplier: 1 developer → ~10 players → $147.50/mo total.
+
+---
+
+## Open Threads
+
+1. **Upload timeout tuning** — need clear separation of client abort /
+   upstream timeout / socket reset in upload route logging
+2. **Dev server filesystem model** — game servers complete; dev container
+   file layout, artifact promotion strategy, and edit scope not yet designed
+3. **Curated provenance** — tracking install origin (Modrinth, manual, etc.)
+   not yet implemented
+4. **Optional future:** config diff viewer, upload progress UI, upload
+   cancellation, log search
+
+---
+
+## Repo Registry
+
+| Repo | Purpose |
+|------|---------|
+| zlh-grind | Architecture decisions, constraints, session logs — source of truth |
+| zlh-docs | API/agent/portal reference docs (read from source) |
+| zpack-api | API source (mirror) |
+| zpack-portal | Portal source (mirror) |
+| zlh-agent | Agent source |
+
+All at `git.zerolaghub.com/jester/<repo>`
+
+---
+
+## Session Guidance
+
+- zlh-grind is the authoritative constraint layer — check before making
+  architecture decisions
+- zlh-docs has full agent documentation (routes, filesystem rules,
+  provisioning pipeline)
+- Agent is the authority on filesystem enforcement — API must NOT
+  duplicate filesystem logic
+- Portal does not enforce real policy — agent enforces
+- Portal never calls agents directly — all traffic through API
+- Upload transport uses raw http.request piping, never fetch()
+- VMs 100, 101, 103 are legacy reference only — not active production
+- Do not speculate future features as implemented