diff --git a/HOWTO.md b/HOWTO.md
new file mode 100644
index 0000000..9e929f2
--- /dev/null
+++ b/HOWTO.md
@@ -0,0 +1,236 @@
+# AUR-Shield HOWTO
+
+## Server einrichten (10.90.9.102)
+
+```bash
+# Klonen
+git clone https://gitea.die-heimatlosen.eu/arch_agent/aur-shield.git
+cd aur-shield
+
+# Installieren (Python venv, systemd service, cache dirs)
+./install.sh
+
+# Config anpassen falls nötig
+cp config.example.yaml config.yaml
+nano config.yaml
+
+# Service starten
+sudo systemctl enable --now aur-shield
+
+# Verifikation
+curl http://localhost:8443/api/status
+```
+
+Erwartete Ausgabe:
+```json
+{
+  "status": "running",
+  "model": "qwen2.5:latest",
+  "ollama_url": "http://localhost:11434",
+  "repo_dir": "/var/cache/aur-shield/repo",
+  "cached_scans": 0
+}
+```
+
+## Client einrichten (Desktop/Laptop)
+
+### Standard-Installation
+
+```bash
+# Einzeiler — installiert safe-yay + pacman repo + config
+curl -sL https://gitea.die-heimatlosen.eu/arch_agent/aur-shield/raw/branch/main/install-client.sh | sudo bash
+```
+
+Das macht:
+1. `/etc/safe-yay.conf` — Server-Adresse (`SHIELD_HOST="10.90.9.102"`)
+2. `[aur-shield]` repo in `/etc/pacman.conf` — zeigt auf `http://10.90.9.102:8443/repo`
+3. `/usr/local/bin/safe-yay` — Wrapper-Skript
+
+### Manuelle Installation (anderer Server)
+
+Falls der AUR-Shield Server woanders läuft:
+
+```bash
+curl -sL https://gitea.die-heimatlosen.eu/arch_agent/aur-shield/raw/branch/main/install-client.sh \
+  | AUR_SHIELD_HOST=192.168.1.50 AUR_SHIELD_PORT=8443 sudo bash
+```
+
+Oder nachträglich ändern:
+```bash
+sudo nano /etc/safe-yay.conf
+# SHIELD_HOST="192.168.1.50" eintragen
+# Dann pacman.conf aktualisieren:
+sudo sed -i 's|Server = .*|Server = http://192.168.1.50:8443/repo|' /etc/pacman.conf
+```
+
+### Config-Datei
+
+`/etc/safe-yay.conf`:
+```bash
+# AUR-Shield client configuration
+SHIELD_HOST="10.90.9.102"
+SHIELD_PORT="8443"
+```
+
+Env-Variablen überschreiben die Config-Datei:
+```bash
+AUR_SHIELD_HOST=192.168.1.50 safe-yay firefox-nightly
+```
+
+## Verwendung
+
+### Neue Pakete installieren
+
+```bash
+# Scan + Build + Install
+safe-yay firefox-nightly
+
+# Mehrere Pakete
+safe-yay google-chrome discord spotify
+```
+
+Ablauf:
+1. AUR-Shield holt PKGBUILD vom AUR
+2. IOC Pre-Check (HedgeDoc, Gist, Arch Security, aur-audit, etc.)
+3. Regex Pre-Scan (`curl|bash`, `eval|base64`, etc.)
+4. LLM Scan (Ollama analysiert den PKGBUILD)
+5. Clean → `makepkg` baut das Paket → `repo-add` fügt es zum Repo hinzu
+6. `pacman -S aur-shield/<paket>` installiert es
+
+### System-Update
+
+```bash
+safe-yay -Syu
+```
+
+Ablauf:
+1. `pacman -Sy` (Repo-Listen aktualisieren)
+2. `yay -Qua` (AUR-Updates finden)
+3. Jedes AUR-Update → AUR-Shield Scan
+4. Clean → installieren | Suspicious → fragen | Malicious → blockieren
+5. `pacman -Su` (Repo-Updates installieren)
+
+### Installierte Pakete prüfen
+
+```bash
+safe-yay --check-installed
+```
+
+Prüft alle installierten AUR-Pakete (`pacman -Qmq`) gegen die IOC-Listen.
+Ähnlich wie `archcanary` — findet Pakete die nach der Installation als malicious markiert wurden.
+
+### Nur scannen (ohne Installation)
+
+```bash
+safe-yay --scan-only firefox-nightly
+```
+
+Nützlich um zu prüfen ob ein Paket safe ist bevor man es installiert.
+
+### Health Check
+
+```bash
+safe-yay --doctor
+```
+
+Zeigt:
+- Server erreichbar?
+- Welches Modell?
+- Wie viele cached scans?
+- Ollama läuft?
+- pacman repo konfiguriert?
+
+## Exit Codes
+
+| Code | Bedeutung | Verwendung in Scripts |
+|------|-----------|----------------------|
+| 0 | Clean | `if safe-yay $pkg; then echo "safe"; fi` |
+| 1 | Warning (suspicious) | Review empfohlen |
+| 2 | Malicious (blocked) | Nicht installieren |
+
+Beispiel:
+```bash
+#!/bin/bash
+for pkg in firefox-nightly google-chrome discord; do
+    safe-yay --scan-only $pkg
+    case $? in
+        0) echo "$pkg: safe to install" ;;
+        1) echo "$pkg: suspicious — review needed" ;;
+        2) echo "$pkg: MALICIOUS — do not install!" ;;
+    esac
+done
+```
+
+## API direkt verwenden
+
+```bash
+# Paket scannen
+curl http://10.90.9.102:8443/api/scan/yay | python3 -m json.tool
+
+# Paket scannen + bauen
+curl http://10.90.9.102:8443/api/build/yay | python3 -m json.tool
+
+# Server-Status
+curl http://10.90.9.102:8443/api/status
+
+# Scan-Report abrufen
+curl http://10.90.9.102:8443/api/report/yay
+
+# Cache leeren für ein Paket
+curl -X DELETE http://10.90.9.102:8443/api/cache/yay
+
+# Alle cached scans anzeigen
+curl http://10.90.9.102:8443/api/cache
+```
+
+## Modell wechseln
+
+In `config.yaml` auf dem Server:
+```yaml
+ollama:
+  model: qwen2.5:latest  # 4.7GB, 6GB VRAM (default)
+  # model: qwen2.5-coder:3b  # 1.9GB, 3GB VRAM (kleinstes)
+  # model: qwen3.5:9b  # 6.6GB, 8GB VRAM (besser)
+  # model: hf.co/AtomicChat/Laguna-XS-2.1-GGUF:Q3_K_M  # 16GB, 16GB VRAM (beste)
+```
+
+Dann: `sudo systemctl restart aur-shield`
+
+## Troubleshooting
+
+### Server nicht erreichbar
+```bash
+# Auf dem Server prüfen:
+sudo systemctl status aur-shield
+journalctl -u aur-shield -f
+```
+
+### Ollama nicht erreichbar
+```bash
+# Auf dem Server prüfen:
+sudo systemctl status ollama
+ollama list  # Modell da?
+```
+
+### pacman sync Fehler (404)
+Die Repo-DB ist leer wenn noch kein Paket gebaut wurde. Leere DB erstellen:
+```bash
+ssh hbock@10.90.9.102 'cd /var/cache/aur-shield/repo && repo-add aur-shield.db.tar.gz'
+```
+
+### Build schlägt fehl
+```bash
+# Build-Log ansehen:
+journalctl -u aur-shield --since "5 min ago" | grep -i error
+
+# Manuelles Build-Test auf dem Server:
+cd /var/cache/aur-shield/build/<package>
+makepkg -sf --noconfirm
+```
+
+### AUR RPC 404
+AUR API URL hat sich geändert. Prüfen:
+```bash
+curl -sf "https://aur.archlinux.org/rpc?type=info&v=5&arg[]=yay" | python3 -m json.tool
+```
+Wenn 404: URL in `aur_shield/aur_client.py` anpassen.
\ No newline at end of file