diff --git a/UPSTREAMS.md b/UPSTREAMS.md
index 442a21d..5818042 100644
--- a/UPSTREAMS.md
+++ b/UPSTREAMS.md
@@ -1,37 +1,68 @@
-# Upstream Dependencies
+# Upstreams / Dependency Notes
 
-## Portal
-- Next.js
-- Axios
-- Websocket console
-- Multipart FormData upload
+This file is a concise reference for important repo/runtime dependencies that affect current implementation work.
 
-## API
-- Node.js (ESM)
-- Express
-- Raw http.request for upload proxy
-- Prisma
-- Token auth
+Use it for:
+- major framework/runtime dependencies
+- important transport or proxy assumptions
+- shared infrastructure dependencies such as the artifact server
 
-## Agent
-- Go
-- Runtime root sandboxing
-- Atomic file writes
-- Metadata tracking
-- Shadow backup system
-
-No external reverse proxy required for internal upload.
+Do not use this file as a backlog.
 
 ---
 
-## zlh-artifacts (Artifact Server)
+## Portal (`zpack-portal`)
+
+Core dependencies / assumptions:
+- Next.js
+- Axios for API interaction
+- WebSocket-backed console UI through the API bridge
+- multipart/FormData upload flows through API/agent paths
+
+Portal boundary:
+- Portal talks to API, not directly to agents, for normal state/actions
+
+---
+
+## API (`zpack-api`)
+
+Core dependencies / assumptions:
+- Node.js (ESM)
+- Express
+- Prisma
+- token/cookie-based auth flows
+- WebSocket proxying for console / IDE flows
+- raw `http.request` piping for upload proxy paths
+
+API boundary:
+- API is the polling/heartbeat authority for agent state
+- API normalizes state for Portal consumption
+
+---
+
+## Agent (`zlh-agent`)
+
+Core dependencies / assumptions:
+- Go
+- filesystem enforcement / sandboxing
+- PTY and WebSocket console transport
+- local metadata tracking for managed files/workloads
+- local Minecraft backup / restore support
+
+Agent boundary:
+- agent owns local workload-aware behavior
+- agent does not own offsite/PBS durability strategy
+
+---
+
+## `zlh-artifacts` (Artifact Server)
 
 Role:
-Central artifact distribution for runtime and addon installs.
+- central artifact distribution for runtime and addon installs
 
 Artifacts currently hosted:
 
-```
+```text
 devcontainer/
   _catalog.json
   go/
@@ -44,12 +75,17 @@ addons/
   code-server/
 ```
 
-Used by: zlh-agent
+Used by:
+- `zlh-agent`
 
-Artifacts are downloaded during provisioning using:
-
-```
-provcommon.BuildArtifactURL(...)
-```
+Artifacts are downloaded during provisioning via artifact URL helpers (for example, `provcommon.BuildArtifactURL(...)`).
 
 Containers do not rely on prepositioned artifacts.
+
+---
+
+## Operational reminders
+
+- upload transport uses raw piping, not `fetch()`, on proxy/upload paths
+- hosted browser IDE flow is edge → API → container, not direct edge → container
+- game publish flow and dev IDE flow should not be conflated