consolidation pass: replace README with current architecture state

README.md

@@ -2,7 +2,7 @@
 
 This repository documents the current architecture, decisions, constraints, and open threads for ZeroLagHub (ZLH).
 
-It is not a code repository.
+It is not a code repository.  
 It is the authoritative design + operational alignment layer between:
 
 - Portal (Next.js frontend)
@@ -11,15 +11,13 @@ It is the authoritative design + operational alignment layer between:
 
 ---
 
-## Current System Overview
+# Current System Overview
 
-### Runtime Model
+## Runtime Model
 
 Each game container has a single runtime root:
 
-```
 /opt/zlh/minecraft/<runtime>/<world>/
-```
 
 All file operations are resolved relative to this root.
 
@@ -27,16 +25,18 @@ The agent is the only authority allowed to mutate the filesystem.
 
 ---
 
-## File System Capabilities (Current State)
+# File System Capabilities (Current State)
+
+## Read
 
-### Read
 - List
 - Stat
 - Read text files
 - Download
-- Hidden internal paths blocked (`.zlh_metadata.json`, `.zlh-shadow`)
+- Hidden internal paths blocked
+
+## Write
 
-### Write
 - Full overwrite for:
   - `server.properties`
   - `config/*.toml`
@@ -44,25 +44,30 @@ The agent is the only authority allowed to mutate the filesystem.
   - `config/*.properties`
 - Shadow backup created on first modification
 - Manual revert supported
-- No automated rollback for user writes
+- No automated rollback
+
+## Delete (Constrained)
 
-### Delete (Constrained)
 Allowed only for:
+
 - `mods-removed/<file>`
 - `mods-uploaded/<file>`
 - `logs/<file>.log`
 - `logs/<file>.log.gz`
 
-No directory deletes. No recursive deletes.
+No directory deletes.
+No recursive deletes.
+
+## Upload
 
-### Upload
 Allowed only for:
+
 - `mods/<file>.jar`
 - `world/datapacks/<file>.zip`
 
 Uploads:
-- Are streamed (raw `http.request` piping in API)
+- Are streamed
-- Written atomically via `os.Rename()`
+- Written atomically
 - Enforced by strict allowlist
 - Do not create directories
 - Do not use staging
@@ -70,9 +75,13 @@ Uploads:
 
 ---
 
-## Provenance Model
+# Provenance Model
 
-User uploads write to `.zlh_metadata.json` at runtime root.
+User uploads write to:
+
+.zlh_metadata.json
+
+Example:
 
 ```json
 {
@@ -83,58 +92,61 @@ User uploads write to `.zlh_metadata.json` at runtime root.
 }
 ```
 
-`stat` returns `"source": "user" | null`
+stat returns:
+
+`"source": "user" | null`
 
 No curated inference currently implemented.
 
 ---
 
-## Upload Transport
+# Upload Transport
 
-```
 Browser → API → Agent
+
+API uses raw Node http.request piping:
+
 ```
-
-API uses raw Node `http.request` piping:
-
-```js
 req.pipe(proxyReq)
 proxyRes.pipe(res)
 ```
 
-No `fetch()` streaming for uploads. Upload timeout must be significantly larger than normal file operations.
+No fetch() streaming for uploads.
+
+Upload timeout must be significantly larger than normal file operations.
 
 ---
 
-## Console Model
+# Console Model
 
-`TerminalView` owns WebSocket lifecycle. `ServerConsole` owns policy + session gating.
+TerminalView owns websocket lifecycle. ServerConsole owns policy + session gating.
 
 Console reconnect is automatic. File panel does not interrupt console lifecycle.
 
 ---
 
-## Repo Usage
+# Repo Usage
 
 This repo is used to:
+
 - Prevent architecture drift
 - Track decisions
 - Record sessions
 - Track open threads
-- Keep portal/API/agent alignment clean
+- Keep frontend/API/agent alignment clean
 
 ---
 
-## Update Instructions
+# Update Instructions
 
 When updating this repo:
 
-1. Update `SESSION_LOG.md` with date-stamped entry
+1. Update SESSION_LOG with date-stamped entry.
-2. Update `OPEN_THREADS.md` if decisions were resolved
+2. Update OPEN_THREADS if decisions were resolved.
-3. Update `CONSTRAINTS.md` if guardrails changed
+3. Update CONSTRAINTS if guardrails changed.
-4. Keep architecture docs consistent with real code behavior
+4. Keep architecture docs consistent with real code behavior.
-5. Do not document future features as implemented
+5. Do not speculate future features as implemented.
 
 ---
 
-**System posture: Stable, controlled expansion phase.**
+System posture: Stable, controlled expansion phase.