From e615d09b68f009a977735fa26e2fa1f0ae057aa8 Mon Sep 17 00:00:00 2001
From: jester <admin@zerolaghub.com>
Date: Sun, 1 Mar 2026 23:18:15 +0000
Subject: [PATCH] docs: replace with current upstream dependencies (portal,
 API, agent, Modrinth, artifact store)

---
 UPSTREAMS.md | 103 +++++++++++++++++++++++----------------------------
 1 file changed, 46 insertions(+), 57 deletions(-)

diff --git a/UPSTREAMS.md b/UPSTREAMS.md
index 64ded8c..dd9594f 100644
--- a/UPSTREAMS.md
+++ b/UPSTREAMS.md
@@ -1,39 +1,29 @@
-# Upstreams — zlh-grind
+# Upstream Dependencies
 
-This repository tracks GPT execution work across upstream projects.
+## Portal
+- Next.js 15 (App Router)
+- TypeScript
+- Axios (API calls)
+- WebSocket console (`TerminalView` / `ServerConsole`)
+- Multipart `FormData` upload
 
-## Rules
-- This file is a registry of upstream repos used during execution.
-- Do not duplicate canonical documentation here; link to it.
+## API
+- Node.js (ESM)
+- Express
+- Raw `http.request` for upload proxy (not `fetch`)
+- Prisma (DB ORM)
+- JWT token auth
+- Redis (agent telemetry cache)
 
----
-
-## ZeroLagHub Knowledge Base (Canonical)
-- Repo: `https://git.zerolaghub.com/jester/knowledge-base`
-- Role: Canonical architecture, decisions, procedures, handovers
-
-## zlh-grind (Execution Ledger)
-- Repo: `https://git.zerolaghub.com/jester/zlh-grind`
-- Role: GPT execution notes, session logs, drift prevention
-
-## zlh-api / zpack-api (API / Control Plane)
-- Repo: `https://git.zerolaghub.com/jester/zlh-api`
-- Role: Control-plane orchestration (instance lifecycle, DB writes, agent coordination)
-- Notes: Game telemetry routes live under `/api/game/*`. Full mod lifecycle routes added Feb 2026.
-
-## Portal / Frontend (Next.js)
-- Repo: `https://git.zerolaghub.com/jester/zlh-portal`
-- Role: Customer portal (dashboard, console UX, mod management UI)
-
-## zlh-agent (Go Agent)
-- Repo: `https://git.zerolaghub.com/jester/zlh-agent`
-- Role: Agent runtime for provisioning/install/verify/start workflows + console PTY
-- Notes: Periodic update checks + Phase 1 mod management + process metrics added Feb 2026. Host allowlist includes `cdn.modrinth.com` and `artifacts.zerolaghub.com`.
-
-## Artifacts (Minecraft zpack tree)
-- Location (VM filesystem): `/opt/zlh/zpacks/minecraft/`
-- Role: Local-first artifacts for vanilla/paper/purpur/fabric/forge/**neoforge** installs.
-- Notes: Phase 1 contract normalizes certain installer filenames for predictable installs.
+## Agent
+- Go
+- Runtime root sandboxing (`internal/files`)
+- Atomic file writes (`os.Rename`)
+- `.zlh_metadata.json` provenance tracking
+- Shadow backup system (`.zlh-shadow`)
+- PTY-backed console over WebSocket
+- Mod management endpoints
+- Agent update system (versioned, SHA-verified)
 
 ---
 
@@ -41,36 +31,35 @@ This repository tracks GPT execution work across upstream projects.
 
 Used for mod resolution and search.
 
-**Endpoints used:**
-- `GET /v2/project/{id}/version` — fetch compatible versions for a mod
-- `GET /v2/search?facets=` — search mods by loader + game version
-
-**Host allowlist:**
-- `cdn.modrinth.com` — artifact downloads (agent-level)
-- `api.modrinth.com` — API calls (API-level resolver)
-
-**Constraints:**
+- Base: `api.modrinth.com/v2`
 - Rate limit: 300 req/min
 - Requires `User-Agent` header
-- Search is loader + game version filtered
-- SHA512 provided on all artifacts (SHA1 fallback)
 - No API key required for public endpoints
+- SHA512 provided on all artifacts (SHA1 fallback)
+
+Agent host allowlist:
+- `cdn.modrinth.com` — artifact downloads
+- `api.modrinth.com` — search/resolve (API-level)
 
 ---
 
-## Authentication Ownership
+## Artifact Store
 
-### Portal
-- Owns identity UX (login, logout, session handling)
-- Stores JWT token
-- Attaches Authorization header to API calls
+Location (VM filesystem): `/opt/zlh/zpacks/minecraft/`
 
-### APIv2
-- Validates credentials
-- Issues JWT tokens
-- Verifies tokens for protected routes
-- Persists user records
+Loader coverage:
+- Vanilla, Paper, Purpur, Forge, Quilt, NeoForge
 
-### Explicit Non-Responsibilities
-- API does not manage frontend sessions
-- Portal does not validate credentials directly
+No external reverse proxy required for internal upload path.
+
+---
+
+## Repo Registry
+
+| Repo | Role |
+|------|------|
+| `zlh-grind` | Architecture alignment, session logs, constraints, open threads |
+| `zlh-api` | Control plane (Node + Express) |
+| `zlh-portal` | Frontend (Next.js) |
+| `zlh-agent` | Go runtime inside containers |
+| `knowledge-base` | Canonical architecture docs |