zlh-grind/README.md

zlh-grind

Execution Workspace for ZeroLagHub (ZLH)

This repository exists to capture live execution context, architectural decisions, and day-to-day grind notes while building ZeroLagHub.

This is not a source-of-truth code repo. This repo preserves:

• rationale
• decision history
• migration state
• unresolved threads

It exists so long-running work can resume cleanly without re-deriving intent.

---

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.

---

Live Console (Implemented)

ZeroLagHub now provides a true interactive server console:

• Dev servers expose a live shell (PTY-backed)
• Game servers expose live Minecraft console access
• Console sessions survive browser reconnects
• No SSH, no Proxmox console access required
• All execution occurs inside the container via the agent

This replaces all prior log-only or exec-based approaches.

---

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.