docs: TOOL-ROLES.md — critical tool-role separation doc

Central documentation of the Stealth-Quad tool architecture:
- skylight-cli = Hauptfenster only (NOT Popups!)
- cua-driver = Popups only (Google OAuth, Consent)
- playstealth = Chrome start
- screen-follow = Video recording

Complete Google OAuth flow example, Popup vs Tab decision matrix,
and fail-safing rules. Closes the biggest detection risk: using
skylight-cli in Popup contexts.

Author: SIN-Agent

docs/TOOL-ROLES.md

@@ -0,0 +1,209 @@
+# TOOL-ROLES.md — KRITISCHE Tool-Rollen-Trennung
+
+> **Die wichtigste Architektur-Regel der Stealth-Quad.**
+> Falsches Tool im falschen Kontext = Klick auf falsches Element = Detection.
+
+---
+
+## 🎯 DAS FUNDAMENTALE PROBLEM
+
+Chrome hat **ZWEI Kontexte**: das Hauptfenster und Popup-Fenster.
+Jedes Tool kann NUR EINEN Kontext sehen.
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Hauptfenster (heypiggy.com/dashboard)              │
+│  → skylight-cli list-elements --pid X              │
+│  → skylight-cli click --pid X --element-index Y    │
+│  → playstealth launch (startet dieses Fenster)     │
+└────────────────────────────┬────────────────────────┘
+                             │
+                    ┌────────▼────────┐
+                    │  Popup (Google   │
+                    │  OAuth, Consent) │
+                    │  → cua-driver    │
+                    │  → window_id     │
+                    └─────────────────┘
+```
+
+**skylight-cli cached NUR das Hauptfenster.**
+**Popup-Indices von skylight-cli sind INVALID!**
+
+---
+
+## 🔑 REGEL 1: skylight-cli = HAUPTFENSTER
+
+### Was skylight-cli kann:
+```bash
+# Chrome starten + PID bekommen
+playstealth launch --url 'https://heypiggy.com/?page=dashboard'
+# → {"pid": 12345, ...}
+
+# Elements im HAUPTFENSTER scannen
+skylight-cli list-elements --pid 12345
+
+# Im HAUPTFENSTER klicken (NUR element-index!)
+skylight-cli click --pid 12345 --element-index 42
+
+# Im HAUPTFENSTER Text eintippen
+skylight-cli type --pid 12345 --element-index 55 --text "München"
+
+# Screenshot vom HAUPTFENSTER
+skylight-cli screenshot --pid 12345 --mode som --output /tmp/page.png
+```
+
+### Was skylight-cli NICHT kann:
+- ❌ KEINE Popup-Elemente sehen
+- ❌ KEINE Google OAuth Buttons klicken
+- ❌ KEINE Consent-Dialoge bedienen
+- ❌ KEINE Koordinaten raten (`--x --y` ist BANNED)
+
+---
+
+## 🔑 REGEL 2: cua-driver = POPUP-FENSTER
+
+### Was cua-driver kann:
+```bash
+# Daemon starten (einmalig pro Session)
+cua-driver serve &
+
+# ALLE Fenster (inkl. Popups) auflisten
+cua-driver call list_windows '{}'
+# → {"windows": [{"window_id": W1, "pid": 12345, "title": "Google"}, ...]}
+
+# Popup-State laden (CACHE pro window_id!)
+cua-driver call get_window_state '{"pid":12345,"window_id":W1}'
+
+# Im Popup klicken
+cua-driver call click '{"pid":12345,"window_id":W1,"element_index":25,"action":"press"}'
+
+# Im Popup Text eintippen
+cua-driver call set_value '{"pid":12345,"window_id":W1,"element_index":25,"value":"email@gmail.com"}'
+```
+
+### Was cua-driver NICHT kann:
+- ❌ KEIN Hauptfenster verwalten (nutze skylight-cli dafür)
+- ❌ KEINE Chrome-Instanz starten (nutze playstealth dafür)
+- ❌ KEINE Page-Transitions erkennen (nutze skylight-cli list-elements dafür)
+
+---
+
+## 🔑 REGEL 3: playstealth = CHROME START
+
+```bash
+# Isolierte Chrome-Instanz (eigene PID, eigener Cache)
+playstealth launch --url 'https://heypiggy.com/?page=dashboard'
+
+# NIEMALS direkt Chrome starten!
+# ❌ open -na "Google Chrome"
+# ❌ /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome
+```
+
+---
+
+## 🔑 REGEL 4: screen-follow = VIDEO
+
+```bash
+# Screen Recording (für Post-Mortem)
+screen-follow record --video --output /tmp/session.mp4
+
+# Video-Analyse nach Session
+python3 -m runner.video_analyzer --last errors
+```
+
+---
+
+## 📋 GOOGLE OAUTH FLOW (komplettes Beispiel)
+
+```bash
+PID=$(pgrep -f "Google Chrome.app/Contents/MacOS/Google Chrome$" | head -1)
+echo "Chrome PID=$PID"
+
+# 1. cua-driver Daemon
+cua-driver serve &
+
+# 2. Google-Login-Button klicken (HAUPTFENSTER → skylight!)
+skylight-cli click --pid $PID --element-index 33
+sleep 2
+
+# 3. Popup window_id finden
+WID=$(cua-driver call list_windows '{}' | python3 -c "
+import sys,json
+for w in json.load(sys.stdin).get('windows',[]):
+    if w.get('pid')==$PID:
+        t=(w.get('title','')).lower()
+        if 'anmelden' in t or 'sign' in t or 'google' in t:
+            print(w['window_id'])
+")
+
+# 4. Email eintippen (POPUP → cua-driver!)
+cua-driver call set_value "{\"pid\":$PID,\"window_id\":$WID,\"element_index\":25,\"value\":\"email@gmail.com\"}"
+
+# 5. "Weiter" klicken
+cua-driver call click "{\"pid\":$PID,\"window_id\":$WID,\"element_index\":35,\"action\":\"press\"}"
+sleep 2
+
+# 6. "Fortfahren" (Consent)
+cua-driver call click "{\"pid\":$PID,\"window_id\":$WID,\"element_index\":65,\"action\":\"press\"}"
+sleep 2
+
+# 7. Finales "Weiter" → Dashboard
+cua-driver call click "{\"pid\":$PID,\"window_id\":$WID,\"element_index\":41,\"action\":\"press\"}"
+```
+
+### Was passiert wenn man skylight in Popups nutzt:
+- `skylight-cli list-elements --pid $PID` nach OAuth-Klick → **leere Liste** oder falsche Indices
+- Klick auf "falschen" Index → **falsches Element** → Detection → Account banned
+
+---
+
+## 🔑 REGEL 5: NEUEN TAB HANDHABEN
+
+Ein neuer Tab ist KEIN Popup! Er hat die gleiche PID aber neue URL.
+skylight-cli kann neue Tabs sehen:
+
+```bash
+# Auf neuen Tab warten
+sleep 3
+
+# Neue Elements scannen (skylight-cli, gleiche PID)
+skylight-cli list-elements --pid $PID | python3 -c "
+import json,sys
+for e in json.load(sys.stdin)['elements']:
+    print(f'[{e[\"index\"]}] {e[\"role\"]}: {e.get(\"label\",\"\")[:60]}')
+"
+```
+
+**Unterscheidung Popup vs. Tab**:
+
+| Kriterium | Popup | Neuer Tab |
+|-----------|-------|-----------|
+| Gleiche PID? | Ja | Ja |
+| `list_windows` zeigt es? | Ja (window_id != 0) | Nein |
+| `list-elements` zeigt es? | Nein | Ja |
+| Tool | **cua-driver** | **skylight-cli** |
+
+---
+
+## 🚨 FAIL-SICHERUNG
+
+Falls du unsicher bist, welches Tool:
+
+1. **Frage**: "Ist das ein Popup-Fenster?" (Google OAuth, Consent, Alert)
+   - Ja → cua-driver
+   - Nein → skylight-cli
+
+2. **Verify**:
+   - skylight: `skylight-cli list-elements --pid X | wc -l` (sollte >10 sein)
+   - cua-driver: `cua-driver call list_windows '{}' | jq '.windows | length'`
+
+3. **Bei Fehler**: Erst skylight probieren, dann cua-driver. NIE beide mischen!
+
+---
+
+## 📚 VERWANDTE DOKUMENTATION
+
+- `docs/cua-driver-popup-pattern.md` — Vollständiger Popup-Flow
+- `brain.md` — Systemwissen (cua-driver Daemon)
+- `commands.md` — Alle Befehle
+- `banned.md` — Verbotene Patterns