docs: update README with Feb 7 2026 handover summary

This commit is contained in:
jester 2026-02-07 21:46:32 +00:00
parent 452fa59fcb
commit e2d41bedcd

111
README.md
View File

@ -1,101 +1,28 @@
# zlh-grind
**Execution Workspace for ZeroLagHub (ZLH)**
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 repo is intentionally lightweight and is used for:
- handovers / "where we left off" notes
- architecture decisions + rationale
- config snippets worth preserving
- TODO lists that don't belong in a code repo
This is **not** a source-of-truth code repo.
This repo preserves:
- rationale
- decision history
- migration state
- unresolved threads
## Latest handover (2026-02-07)
It exists so long-running work can resume cleanly without re-deriving intent.
- `SCRATCH/2026-02-07_customer-id-schema.md`
- Why a newly registered user looked "hashed" (it's Prisma `cuid()`),
- Why `ContainerInstance.customerId` got polluted with `u-dev-001`,
- The chosen short-term rule: **use `req.user.id` everywhere**.
---
- `SCRATCH/2026-02-07_prometheus-grafana.md`
- Prometheus HTTP service discovery via API `/sd/exporters`,
- Grafana dashboard import gotchas + the "CPU doesn't match top" note,
- Next steps to power portal server cards with metrics.
## What This Repo Is For
- `SCRATCH/2026-02-07_host-controls-and-delete-failsafe.md`
- Decision: keep delete failsafe, add host controls.
- GPT / Claude execution handoffs
- Portal v2 architecture notes
- Dashboard & Servers UX decisions
- Agent vs API responsibility boundaries
- Migration context from Pterodactyl → ZLH-native
## Scratchpad
---
## 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**.
`SCRATCH/` contains one-off notes that may later be promoted into formal docs.