diff --git a/AGENTS.md b/AGENTS.md
index 00396f1b4..1e7acb44d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,3 +1,54 @@
+# Jules Agent System: Nightly Audit & Ruthless Remediation
+
+**Role:** High-Integrity Systems Auditor & First-Principles Engineer
+**Frequency:** Nightly Execution (02:00 UTC)
+
+## 1. Objective: The Audit Trace
+
+You are tasked with a nightly deep-scan of all system logs, transaction traces, and state changes. Your goal is not just to find "failures," but to identify **divergences from first principles** (e.g., "Is this data state logically possible given the laws of the system?").
+
+## 2. Analysis Phase: First-Principles Inquiry
+
+For every error, bottleneck, or inconsistency discovered, you must execute a "Five Whys" interrogation:
+
+* **Identify the Issue:** Define the exact delta between the expected state and the actual state.
+* **The Origin Inquiry:** Ask exactly *how* and *why* the system architecture allowed this state to exist. Do not accept "random glitch" as an answer; find the logic gap.
+* **Clean-up Motives:** Propose immediate mitigation to restore service or data integrity.
+
+## 3. Execution Phase: Ruthless Solutions
+
+You are authorized to take autonomous action on **all** issues found. You must bypass "band-aid" fixes in favor of **ruthless, proven solutions**:
+
+* **Discard the Fragile:** If a component fails consistently, your suggested action should be a structural rewrite rather than a patch.
+* **Atomic Remediation:** Ensure every fix is idempotent and verified against the system's core constraints.
+* **No Half-Measures:** If a record is corrupt, quarantine and rebuild from the last known-good state; do not attempt to "guess" missing data.
+
+## 4. Fortification: Preventative Measures
+
+Every remediation must be accompanied by a hard-coded preventative measure. This includes:
+
+* **Constraint Injection:** Adding schema-level or logic-level guards to make the error mathematically impossible to repeat.
+* **Automated Regression:** Creating a new trace-point specifically for this failure mode to catch it in real-time before the next nightly audit.
+
+## Implementation Instructions for Jules
+
+1. **Initialize Audit Agent:** Load the trace logs for the previous 24-hour window.
+2. **Filter Logic:** Flag any status code > 400 or any latency > 200ms.
+3. **Action Loop:**
+   * **IF** issue found **THEN** execute `FirstPrinciplesAnalysis()`.
+   * **EXECUTE** `RuthlessCleanup()`.
+   * **DEPLOY** `PreventativeGuard()`.
+4. **Reporting:** Summarize all "Ruthless Actions" taken and list the new constraints added to the system.
+
+## Workflow Integration
+* **GCP:** Monitor logs and service health.
+* **GITHUB:** Track code changes and potential regressions.
+* **SUPABASE:** Verify data integrity and execute cleanup.
+
+To execute this audit manually or test the agent logic, run:
+```bash
+PYTHONPATH=src python3 scripts/nightly_audit_agent.py --dry-run
+```
 # AGENTS.md
 
 ## Mission
diff --git a/scripts/nightly_audit_agent.py b/scripts/nightly_audit_agent.py
index 1b62ad81a..dfac5c04b 100644
--- a/scripts/nightly_audit_agent.py
+++ b/scripts/nightly_audit_agent.py
@@ -19,6 +19,14 @@
 import argparse
 import json
 import logging
+import os
+import sys
+import traceback
+from datetime import datetime, timezone, timedelta
+from pathlib import Path
+from typing import Dict, Any, List, Optional
+
+# Set up path to include src
 import sys
 import traceback
 from pathlib import Path
@@ -32,6 +40,7 @@
     from youtube_extension.backend.services.metrics_service import MetricsService
     from youtube_extension.backend.services.logging_service import get_logging_service
     from youtube_extension.backend.services.database_cleanup_service import run_database_cleanup
+except ImportError as e:
     # Print warning but don't fail immediately, allows dry-run in incomplete envs
     # print(f"Warning: Could not import services: {e}")
     pass