From 282ccc6211eac67fd8f7de17c68e7e3ba23832ed Mon Sep 17 00:00:00 2001
From: jester <admin@zerolaghub.com>
Date: Sun, 4 Jan 2026 22:45:09 +0000
Subject: [PATCH] Update README.md - Portal v2 UX alignment, agent-first
 control model, locked dashboard/servers philosophy

---
 README.md | 106 ++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 79 insertions(+), 27 deletions(-)

diff --git a/README.md b/README.md
index ad021a8..66dd7e5 100644
--- a/README.md
+++ b/README.md
@@ -1,35 +1,87 @@
 # zlh-grind
 
-**GPT Execution Workspace for ZeroLagHub**
+**Execution Workspace for ZeroLagHub (ZLH)**
 
-This repository is dedicated exclusively to **GPT-driven implementation work**.
-It exists to capture execution context, day-to-day grind notes, and concrete changes made during development.
+This repository exists to capture **live execution context, architectural decisions, and day-to-day grind notes** while building ZeroLagHub.
 
-This repository exists to preserve execution continuity across long-running development work.
+This is **not** a source-of-truth code repo.
+This repo preserves:
+- rationale
+- decision history
+- migration state
+- unresolved threads
 
-## Assistant Prompt
-
-You are **údar**. In this repo you act as the execution assistant: implement, verify, and log work. Keep continuity by reading `SESSION_LOG.md`, `OPEN_THREADS.md`, and `UPSTREAMS.md`. Do **not** make architecture decisions here; defer to canonical docs in `jester/knowledge-base`.
-
-## What This Repo Is For
-- Daily GPT work logs
-- Session handovers
-- Implementation notes and scratchpads
-- Tracking *what was changed, when, and why*
-
-## What This Repo Is NOT
-- ❌ Architecture decisions
-- ❌ Cross-project source of truth
-- ❌ Product or strategy documentation
-
-All canonical architecture, decisions, and references live in:
-**`jester/knowledge-base`**
-
-## Working Rules
-- This repo may be messy, iterative, and practical
-- Prefer clarity over polish
-- Reference canonical docs instead of duplicating them
+It exists so long-running work can resume cleanly without re-deriving intent.
 
 ---
 
-If it happened during hands-on GPT execution, it belongs here.
+## What This Repo Is For
+
+- GPT / Claude execution handoffs
+- Portal v2 architecture notes
+- Dashboard & Servers UX decisions
+- Agent vs API responsibility boundaries
+- Migration context from Pterodactyl → ZLH-native
+
+---
+
+## Current Platform Model (Jan 2026)
+
+### Control Plane
+
+- **API v2**  
+  Owns:
+  - auth
+  - ownership
+  - permissions
+  - orchestration
+  - routing to agents
+
+- **ZLH Agent (inside every server/LXC)**  
+  Owns:
+  - service lifecycle
+  - runtime state
+  - console / output
+  - in-container truth
+
+The API does **not** infer server state.
+The agent is authoritative for runtime behavior.
+
+---
+
+## Portal UX Philosophy (Locked)
+
+### Dashboard
+- Situational awareness only
+- No operational controls
+- System Health indicator (frontend ↔ backend connectivity)
+- Notices timeline (expandable, scrollable)
+- Resource summaries only
+
+### Servers Page
+- Grouped by server type (GAME / DEV)
+- Expandable server cards
+- Collapsed = status
+- Expanded = context
+- Single escalation action: **System View**
+
+### System View
+- Observation-first detail page
+- Runtime output, metadata, health
+- Future controls may live here
+- No AWS-style console metaphors
+
+---
+
+## What This Repo Is NOT For
+
+- Final schemas
+- Billing logic
+- Infrastructure secrets
+- Canonical documentation
+
+Those live elsewhere.
+
+---
+
+This repo intentionally favors **clarity over completeness**.