From 95a6a853dd88140e4f2e2466504b866ed42ec0d9 Mon Sep 17 00:00:00 2001
From: jester <admin@zerolaghub.com>
Date: Sun, 22 Feb 2026 18:18:33 +0000
Subject: [PATCH] docs: update README with Feb 22 handover state

---
 README.md | 76 ++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 56 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 3ba4cdc..b09cab4 100644
--- a/README.md
+++ b/README.md
@@ -10,29 +10,65 @@ This repository is intentionally lightweight and is used for:
 
 ---
 
-## Latest handover (2026-02-08)
+## Latest handover (2026-02-22)
 
-**System state**
-- API, frontend, and agent are now aligned and operational.
-- Interactive PTY-backed consoles are stable for both dev and game servers.
-- Customer isolation is enforced end-to-end (API → frontend).
-- Agent update system is live, versioned, and hash-verified.
+### System state (high confidence)
+- **PTY-backed consoles are stable** (dev + game) and no longer depend on log tailing.
+- **Customer isolation is enforced** end-to-end (API auth → ownership checks → per-customer data).
+- **Agent update system is operational** (versioned, SHA-verified) with periodic checks.
+- **Game telemetry is now separated** behind a dedicated API router (`/api/game/*`).
 
-**Key areas completed**
-- Metrics API (server-side Prometheus summaries)
-- Game console UI (metrics, notes, player presence)
-- Agent auto-update pipeline (manifest + SHA validation)
-- Minecraft player presence via agent `/game/players`
-- Forge startup race condition resolved
-- Prometheus SD schema + auth fixes
+### What shipped since the prior handover
 
-**Primary focus moving forward**
-- Final UI polish & stabilization
-- Concurrent provisioning validation
-- Hardening agent update + rollback paths
-- Defining GA readiness criteria
+#### API (control plane)
+- Added `src/routes/game.js` and mounted at `/api/game`.
+- Added `GET /api/game/servers/:id/players` (reads Redis `agent:<vmid>`; returns normalized `{ vmid, playerCount, players, max, timestamp }`).
+- Extended `src/utils/agentPoller.js`:
+  - polls agent `GET /game/players` for **game** containers and caches in Redis.
+  - polls agent `GET /version` and `GET /agent/update/status`; derives `updateAvailable`.
+- Added `GET /api/game/servers/:id/update-status` (returns agent version + update state).
+- Provisioning persists engine metadata:
+  - `engineType = "minecraft"` for game containers
+  - `engineVersion` from payload
+  - dev containers set both to `null`
+- Rolled back API-triggered update during provisioning (back to direct `/config` provisioning flow).
+
+#### Frontend (portal)
+- Game console now polls:
+  - `GET /api/game/servers/:id/players`
+  - `GET /api/game/servers/:id/update-status`
+- Player presence shows count + optional name list.
+- Version context displayed as `Version: X` or `Version: X -> Y`.
+- Auth behavior unchanged (all calls through `apiClient` with JWT Bearer).
+
+#### Agent (runtime)
+- `GET /game/players` hardened for reliability (port/protocol fallbacks).
+- Added periodic update checks:
+  - `ZLH_AGENT_UPDATE_MODE=notify|auto|off`
+  - `ZLH_AGENT_UPDATE_INTERVAL` (default `30m`; first check ~10s after boot)
+- Added Phase 1 mod management endpoints:
+  - `GET /game/mods`
+  - `POST /game/mods/install`
+  - `PATCH /game/mods/:mod_id`
+  - `DELETE /game/mods/:mod_id`
+- Added `GET /metrics/process` (PID + memory via `/proc/<pid>/status`, restart_count mapped to crash count).
+- Added Minecraft readiness probe after start/restart + stop-wait-before-restart sync to reduce restart races.
+- Logging improved with `lifecycle.log` alongside `agent.log`.
+
+#### Artifacts
+- Artifact tree expanded to include **NeoForge** under `.../minecraft/neoforge/<mc_version>/`.
+- Phase 1 contract: NeoForge installer filename is normalized to `neoforge-installer.jar` within the version directory.
+
+---
+
+## Primary focus moving forward
+
+1. **API proxy endpoints for mods + process metrics** (to mirror agent capabilities behind auth/ownership).
+2. **Artifact catalog + ingestion workflow** (Modrinth/NeoForge local-first, approval-gated).
+3. **Frontend Mods UI** (installed mods list + enable/disable/remove + curated install; upload likely Phase 2).
+4. **Concurrent provisioning validation** (multi-user parallel create + port allocation + isolation).
 
 See:
-- `SESSION_LOG.md` for chronological execution details
 - `OPEN_THREADS.md` for remaining work
-- `ANTI_DRIFT*.md` for guardrails and constraints
+- `CONSTRAINTS.md` + `ANTI_DRIFT*.md` for guardrails
+- `SESSION_LOG.md` for a chronological ledger