Move non-core root reference docs under docs/reference

docs/reference/ANTI_DRIFT_GUARDRAIL.md

@@ -0,0 +1,102 @@
+# Anti-Drift Guardrails
+
+This document exists to prevent architectural regression
+caused by convenience changes, AI tooling, or incomplete context.
+
+---
+
+## Primary Drift Risk: Frontend Shortcuts
+
+The most common drift vector is:
+
+**Frontend → Agent**
+
+This is **always wrong**, regardless of environment.
+
+---
+
+## Guardrail Rules (Hard)
+
+- Browsers never call agents
+- Browsers never see container IPs
+- Agents never expose CORS headers
+- API is the only control plane
+
+---
+
+## Codex / AI-Specific Guardrails
+
+When using AI tools:
+
+- Explicitly forbid frontend → agent calls
+- Require API-only control paths
+- Reject changes that "just work" via shortcuts
+- Prefer deletion over convenience
+
+If AI introduces direct agent calls:
+- The change is invalid
+- The prompt must be corrected
+
+---
+
+## Status & State Drift
+
+- UI state is observational
+- Pollers are authoritative
+- Buttons express intent only
+- No optimistic state transitions
+
+---
+
+## Restart Semantics
+
+- Restart is agent-defined
+- Restart is not "stop + start" in UI
+- Restart must preserve PTY continuity where possible
+
+---
+
+## Terminal & Realtime UI Rules
+- Terminal components must be isolated and client-only
+- No terminal logic in shared utilities
+- No implicit socket initialization at import time
+
+---
+
+## UI Philosophy
+- Prefer boring, predictable UI over clever abstractions
+- Do not introduce new visual metaphors without removing an old one
+- No "sci-fi" effects unless strictly informational
+- Avoid abstractions that hide client/server boundaries
+
+---
+
+## When Unsure
+Default to:
+- Removing code
+- Leaving a comment
+- Asking for review
+
+Silence is better than instability.
+
+---
+
+## Enforcement Rule
+
+If behavior and documentation disagree:
+
+> **Documentation wins.**
+
+This file exists to stop slow erosion of system integrity.
+
+---
+
+### Enforcement Note (Dec 28)
+
+If portal code references:
+- CSRF
+- Cookies for auth
+- Pterodactyl
+- APIv1 routes
+
+That code must be removed or refactored before merge.