diff --git a/README.md b/README.md index ca8739a..a1efe2c 100644 --- a/README.md +++ b/README.md @@ -1,198 +1,171 @@ -# ZeroLagHub – Grind State Repository +# zlh-grind -This repository documents the current architecture, decisions, constraints, and open threads for ZeroLagHub (ZLH). +GPT Execution Workspace for ZeroLagHub -It is not a code repository. -It is the authoritative design + operational alignment layer between: +This repository exists to preserve execution continuity for long-running implementation work performed with GPT. -- Portal (Next.js frontend) -- API (Node + Express) -- Agent (Go runtime inside containers) +It is not a source-of-truth architecture repository. +Canonical documentation lives in: + +jester/knowledge-base --- -# Current System Overview +## Assistant Prompt -## Runtime Model +You are údar. -Each game container has a single runtime root: +In this repository you act as the execution assistant. -/opt/zlh/minecraft/// +Your role is to: -All file operations are resolved relative to this root. +- implement changes +- verify behavior +- document work +- maintain session continuity -The agent is the only authority allowed to mutate the filesystem. +Before doing work you must read: + +SESSION_LOG.md +OPEN_THREADS.md +UPSTREAMS.md + +Architecture decisions must not be made here. + +If architectural interpretation is required: + +Stop and defer to Claude or the canonical docs. --- -# Current Platform Capabilities (March 2026) +## What This Repo Is For -## Game Server Control +This repository tracks: -- Start / Stop / Restart -- Crash detection via process exit -- Intentional stop detection (no false crash increments) -- Readiness probing (Minecraft ping) -- Console streaming via WebSocket + PTY -- Crash metadata recorded by the agent +- GPT implementation work +- session handovers +- debugging notes +- execution reasoning +- cross-repo coordination -## File System Operations - -- File browser -- Safe editing of server files -- Shadow backups (.zlh-shadow) -- Upload support: - - mods/*.jar - - world/datapacks/*.zip -- Upload provenance tracking via `.zlh_metadata.json` - -## Observability - -Agent `/status` endpoint exposes: - -- `state` -- `crashCount` -- `lastCrashTime` -- `lastCrashExitCode` -- `lastCrashSignal` -- `lastCrashUptimeSeconds` -- `lastCrashLogTail` - -## Notes System - -Server instances support persistent notes stored in the platform database and editable from the portal UI. - -## Console System - -- xterm.js frontend -- WebSocket transport -- PTY session managed by the agent -- Reconnect handled client-side — no page refresh required +It serves as the execution ledger for the ZeroLagHub platform. --- -# File System Capabilities (Current State) +## What This Repo Is NOT -## Read +This repo must never become an architecture source. -- List -- Stat -- Read text files -- Download -- Hidden internal paths blocked +Do not add: -## Write +- system diagrams +- architecture decisions +- platform policy +- runtime design -- Full overwrite for: - - `server.properties` - - `config/*.toml` - - `config/*.json` - - `config/*.properties` -- Shadow backup created on first modification -- Manual revert supported -- No automated rollback +Those belong in: -## Delete (Constrained) - -Allowed only for: - -- `mods-removed/` -- `mods-uploaded/` -- `logs/.log` -- `logs/.log.gz` - -No directory deletes. -No recursive deletes. - -## Upload - -Allowed only for: - -- `mods/.jar` -- `world/datapacks/.zip` - -Uploads: -- Are streamed -- Written atomically -- Enforced by strict allowlist -- Do not create directories -- Do not use staging -- Do not use symlinks +jester/knowledge-base --- -# Provenance Model +## Platform Context (Current State) -User uploads write to: +ZeroLagHub consists of several core components. -.zlh_metadata.json +### Control Plane -Example: +zlh-api -```json -{ - "mods/sodium.jar": { - "source": "user", - "uploaded_at": "2026-03-01T22:37:01Z" - } -} -``` +Responsibilities: -stat returns: - -`"source": "user" | null` - -No curated inference currently implemented. +- container lifecycle orchestration +- database state +- agent provisioning payloads +- DNS / proxy coordination --- -# Upload Transport +### Execution Plane -Browser → API → Agent +zlh-agent -API uses raw Node http.request piping: +Responsibilities: + +- container runtime provisioning +- game server install + management +- dev container provisioning +- runtime installs +- addon installs +- status reporting + +--- + +### Artifact Distribution + +zlh-artifacts + +Artifact server hosts: ``` -req.pipe(proxyReq) -proxyRes.pipe(res) +devcontainer/ + _catalog.json + go/ + node/ + python/ + java/ + dotnet/ + +addons/ + code-server/ ``` -No fetch() streaming for uploads. +Artifacts are fetched by the agent at provisioning time. -Upload timeout must be significantly larger than normal file operations. +Nothing provisioning-related is assumed to exist locally inside containers. --- -# Console Model +### Developer Containers -TerminalView owns websocket lifecycle. ServerConsole owns policy + session gating. +Dev containers support runtimes: -Console reconnect is automatic. File panel does not interrupt console lifecycle. +- node +- python +- go +- java +- dotnet + +Runtime installs are: + +- catalog driven +- artifact backed +- idempotent + +Install root: + +``` +/opt/zlh/runtimes// +``` + +Dev environment: + +``` +user: dev +home: /home/dev +workspace: /home/dev/workspace +``` --- -# Repo Usage +## Repo Role in the Platform -This repo is used to: +This repository tracks execution work across all components: -- Prevent architecture drift -- Track decisions -- Record sessions -- Track open threads -- Keep frontend/API/agent alignment clean +- zlh-api +- zlh-agent +- zlh-portal +- zlh-artifacts +- infrastructure ---- - -# Update Instructions - -When updating this repo: - -1. Update SESSION_LOG with date-stamped entry. -2. Update OPEN_THREADS if decisions were resolved. -3. Update CONSTRAINTS if guardrails changed. -4. Keep architecture docs consistent with real code behavior. -5. Do not speculate future features as implemented. - ---- - -System posture: Stable, controlled expansion phase. +It ensures GPT sessions remain consistent across days and chats.