From e61ecaf674d49f019803d4e50dbc2b48c5e4b5e0 Mon Sep 17 00:00:00 2001
From: jester <admin@zerolaghub.com>
Date: Mon, 13 Apr 2026 21:48:55 +0000
Subject: [PATCH] Move non-core root reference docs under docs/reference

---
 docs/reference/ANTI_DRIFT_GUARDRAIL.md | 102 +++++++++++++++++++++++++
 1 file changed, 102 insertions(+)
 create mode 100644 docs/reference/ANTI_DRIFT_GUARDRAIL.md

diff --git a/docs/reference/ANTI_DRIFT_GUARDRAIL.md b/docs/reference/ANTI_DRIFT_GUARDRAIL.md
new file mode 100644
index 0000000..1c1da58
--- /dev/null
+++ b/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.