docs: explain Directus shim architecture

- Enhanced AI_ONBOARDING.md with detailed shim explanation
- Added shim section to CTO_LOG.md
- Clarifies how God Mode uses Directus SDK syntax without Directus runtime

AI_ONBOARDING.md

@@ -10,9 +10,48 @@
 *   **Queue:** Redis + BullMQ (`BatchProcessor.ts`).
 
 ## ⚡ Critical Systems (The "Shim")
-**File:** `src/lib/directus/client.ts`
-*   **Function:** Intercepts standard SDK calls (`readItems`, `createItem`) and converts them to `pg` pool queries.
-*   **Why:** Allows "Headless" operation. If the API is down, we still run.
+
+**File:** `src/lib/directus/client.ts` - **THIS IS THE KEY TO UNDERSTANDING GOD MODE**
+
+### What It Does:
+Translates Directus SDK syntax → Raw PostgreSQL queries. This allows the entire codebase to use familiar Directus SDK patterns while directly querying PostgreSQL.
+
+### Why It Exists:
+- **No Directus dependency** - God Mode runs standalone
+- **Direct database access** - Faster, no API overhead
+- **Familiar syntax** - Developers can use `readItems('sites')` instead of raw SQL
+- **Hot-swappable** - Can switch to real Directus later if needed
+
+### How It Works:
+
+**Component code looks like this:**
+```typescript
+import { getDirectusClient, readItems } from '@/lib/directus/client';
+
+const client = getDirectusClient();
+const sites = await client.request(readItems('sites', {
+  filter: { status: { _eq: 'active' } },
+  limit: 10
+}));
+```
+
+**Behind the scenes, the shim converts it to:**
+```sql
+SELECT * FROM "sites" 
+WHERE "status" = 'active' 
+LIMIT 10
+```
+
+### Server vs Client:
+- **Server-side:** Direct PostgreSQL via `pg` pool
+- **Client-side:** HTTP proxy to `/api/god/proxy` which then uses `pg`
+
+### Files Involved:
+- `src/lib/directus/client.ts` - Shim implementation (274 lines)
+- `src/pages/api/god/proxy.ts` - Client-side proxy endpoint
+- `src/lib/db.ts` - PostgreSQL connection pool
+
+**IMPORTANT:** All 35+ admin components use this shim. It's not a hack - it's the architecture.
 
 ## ⚠️ "God Tier" Limits (The "Dangerous" Stuff)
 **File:** `docker-compose.yml`