docs: add architectural boundaries to prevent frontend-agent drift

PORTAL_MIGRATION.md

@@ -113,12 +113,12 @@ It does not directly query agents, Proxmox, or exporters.
 ### UI Mapping
 
 | Container Type | Host Online | Agent State | UI Status |
-|---------------|------------|-------------|-----------|
+|----------------|-------------|-------------|-----------|
-| DEV           | true       | n/a         | running   |
+| DEV            | true        | n/a         | running   |
-| DEV           | false      | n/a         | offline   |
+| DEV            | false       | n/a         | offline   |
-| GAME          | true       | running     | running   |
+| GAME           | true        | running     | running   |
-| GAME          | true       | idle        | stopped   |
+| GAME           | true        | idle        | stopped   |
-| GAME          | false      | n/a         | offline   |
+| GAME           | false       | n/a         | offline   |
 
 ### Notes
 - "Idle" does **not** mean broken
@@ -149,3 +149,52 @@ This model intentionally mirrors Pterodactyl semantics.
 - Must not assume process state
 
 This split is intentional and enforced to prevent drift.
+
+---
+
+## Architectural Boundaries (CRITICAL)
+
+### What Frontend MUST NOT Do
+
+**Never Call Agents Directly**
+- Frontend cannot reach container IPs
+- Frontend has no network path to agents
+- All agent access flows through API
+- This is non-negotiable architecture
+
+**Why This Matters**
+- Container IPs are internal-only (10.x network)
+- No CORS headers on agents (they're not web services)
+- Direct calls would fail and break the security model
+- API enforces auth, rate limits, and access control
+
+**Correct Flow**
+```
+User Action → Frontend → API → Agent → Response
+```
+
+**Incorrect Flow (FORBIDDEN)**
+```
+User Action → Frontend → Agent (FAILS - no network path)
+```
+
+### What Can Break This
+
+**AI Coding Tools**
+- May suggest "quick fixes" that call agents directly
+- May treat agents as HTTP APIs with CORS
+- May generate code that "just works" in wrong way
+
+**Convenience Changes**
+- Adding CORS headers to agents (never do this)
+- Exposing agent ports through proxy (breaks security)
+- Creating frontend → agent shortcuts (breaks architecture)
+
+### Enforcement
+
+If a change violates these boundaries:
+- The change must be reverted
+- The documentation takes precedence
+- AI tools must be corrected
+
+These constraints override convenience.