# Upstreams — zlh-grind

This repository tracks GPT execution work across upstream projects.

## Rules
- This file is a registry of upstream repos used during execution.
- Do not duplicate canonical documentation here; link to it.

---

## 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.

---

## Modrinth API

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:**
- 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

---

## Authentication Ownership

### Portal
- Owns identity UX (login, logout, session handling)
- Stores JWT token
- Attaches Authorization header to API calls

### APIv2
- Validates credentials
- Issues JWT tokens
- Verifies tokens for protected routes
- Persists user records

### Explicit Non-Responsibilities
- API does not manage frontend sessions
- Portal does not validate credentials directly