docs: replace with consolidated system constraints (filesystem, upload, auth, console)

CONSTRAINTS.md

@@ -1,100 +1,137 @@
-# ZeroLagHub — Frontend Constraints (ZLH Grind)
+# System Constraints
 
-These constraints are **non-negotiable**.  
-They exist to prevent architectural drift, instability, and "demo-ware" UI patterns.
-
-## Runtime & Framework
-- Node.js **22 LTS**
-- Next.js **App Router**
-- React 18
-- TypeScript
-- Build once → run many
-- No runtime builds
-- No PM2 during active development
-
-## SSR & Client Boundaries
-- Any file that touches:
-  - `window`
-  - `document`
-  - `location`
-  - WebSockets
-  - xterm / DOM refs  
-  **MUST** be a client component with `"use client"` as the first line.
-- No browser globals at module scope in server components.
-- Prefer `useEffect` for browser-only logic.
-
-## UI Philosophy
-- Control-plane first, not marketing gimmicks.
-- Flat UI by default.
-- Subtlety beats spectacle.
-- Readability > novelty.
-
-## Explicitly Forbidden
-- Neon / RGB accent colors outside error states
-- Scanline / CRT / HUD overlays
-- Persistent 3D transforms or perspective UI
-- Excessive glow stacking
-- Clip-path bevel frames
-- Continuous decorative animations
-
-## Branding
-- Brand: **ZeroLagHub**
-- Shorthand: **ZLH**
-- Gaming heritage is acceptable, esports aesthetic is not.
-
-## Authentication Constraints (APIv2)
-
-- APIv2 authentication is stateless
-- JWT tokens are issued by APIv2 only
-- No CSRF protection is allowed
-- No cookies are allowed for auth
-- Portal stores tokens client-side (sessionStorage)
-- APIv1 and Pterodactyl auth patterns are forbidden
+These are non-negotiable guardrails.
 
 ---
 
-## Network & Agent Architecture (CRITICAL)
+## 1. Agent Is Authority
 
-### Frontend Cannot Reach Agents
+The agent:
+- Owns filesystem enforcement
+- Owns path normalization
+- Owns write restrictions
+- Owns upload allowlist
+- Owns metadata
 
-**The Rule**
-- Frontend must never call agents directly
-- All agent access flows through API
-- Container IPs are internal-only (10.x network)
-- No CORS headers exist on agents
+The API must NOT duplicate filesystem logic.
 
-**Why This Is Enforced**
-- Agents are not web services
-- They have no public network path
-- Direct calls would fail (no route)
-- API enforces auth, logging, rate limits
+---
+
+## 2. Runtime Root Sandbox
+
+No operation may escape runtime root.
+
+All paths:
+- Cleaned
+- Symlink-resolved
+- Verified inside root
+
+---
+
+## 3. No Symlink Deployment Model
+
+Uploads write directly to runtime.
+
+No:
+- Staging folders
+- Symlink injection
+- Delayed deployment
+
+---
+
+## 4. Metadata Is Hidden
+
+`.zlh_metadata.json` and `.zlh-shadow` must never be exposed via file APIs.
+
+Filtered centrally inside the agent `internal/files` package, not in route handlers.
+
+---
+
+## 5. Upload Allowlist Only
+
+Only:
+- `mods/*.jar`
+- `world/datapacks/*.zip`
+
+Anything else → `403`.
+
+---
+
+## 6. Delete Is Strictly Constrained
+
+No recursive delete. No directory delete. One-level file only.
+
+Allowed paths:
+- `mods-removed/<file>`
+- `mods-uploaded/<file>`
+- `logs/<file>.log`
+- `logs/<file>.log.gz`
+
+---
+
+## 7. No Curated Inference
+
+If metadata does not exist → `source: null`
+
+Do not assume curated status from filename or path.
+
+---
+
+## 8. Upload Transport
+
+API upload must:
+- Stream via raw `http.request` piping
+- Not buffer entire file in memory
+- Not use `fetch()` streaming
+- Not re-implement upload policy (agent enforces)
+
+---
+
+## 9. Timeouts
+
+Upload route must use extended timeout. Other file routes remain short.
+
+---
+
+## 10. Portal Does Not Enforce Security
+
+Portal may validate for UX (extension pre-check, size warning). Agent enforces real policy.
+
+---
+
+## 11. Frontend Cannot Reach Agents Directly
+
+All agent access flows through API. Container IPs are internal-only (`10.x` network). No CORS headers on agents.
 
-**Correct Pattern**
 ```
-Frontend → API → Agent
+Frontend → API → Agent     ✅
+Frontend → Agent            ❌
 ```
 
-**Forbidden Pattern**
-```
-Frontend → Agent (FAILS)
-```
+---
 
-### Common Violations
+## 12. Authentication
 
-**Adding CORS to Agents**
-- Never add CORS headers to agents
-- Agents are not HTTP APIs
-- This breaks security model
+- JWT tokens issued by API only
+- No cookies for auth
+- No CSRF tokens
+- No APIv1 or Pterodactyl auth patterns
+- Portal stores tokens client-side (`sessionStorage`)
 
-**Exposing Agent Ports**
-- Do not proxy agent ports through Caddy
-- Do not expose container IPs
-- API is the only gateway
+---
 
-**Frontend Shortcuts**
-- No direct WebSocket to agent
-- No fetch() to container IPs
-- No "quick fixes" that bypass API
+## 13. Console Must Remain PTY-Backed
+
+- PTY-backed
+- Agent-owned
+- WebSocket-based
+- Full duplex (input + output)
+
+Disallowed:
+- Log tailing as "console"
+- Exec-per-command models
+- Frontend-owned processes
+- Proxmox console passthrough
 
 ---