docs: Startup-Kommandos vollständig dokumentieren (llama.cpp, Ollama, Gateway)

README: neuer Abschnitt „Starten — alle Szenarien" mit allen Optionen für
cloud/hybrid/local-dev, llama.cpp-ENV-Tabelle, Ollama-Sequenz und make-Targets.
BEDIENUNGSANLEITUNG: § 4.5 (llama.cpp) um direkten Script-Aufruf, docker logs,
vollständige ENV-Tabelle erweitert; neues § 4.6 (Ollama) mit systemctl/serve,
pull/list/ps, .env-Snippet und Reasoning-Hinweis. TOC und Sachregister aktualisiert.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

BEDIENUNGSANLEITUNG.md

@@ -35,7 +35,7 @@ funktioniert trotzdem, die Ausgabe ist dann unformatiert.
 1. [Was ist dieses System?](#1-was-ist-dieses-system)
 2. [Installation und Einrichtung](#2-installation-und-einrichtung)
 3. [Betriebsprofile wählen](#3-betriebsprofile-wählen)
-4. [Starten und Stoppen](#4-starten-und-stoppen)
+4. [Starten und Stoppen](#4-starten-und-stoppen) — [4.5 llama.cpp](#45-llamacpp-server-für-profil-hybridlocal-dev) · [4.6 Ollama](#46-ollama-alternative-zu-llamacpp-kein-docker-nötig)
 
 **Bedienung**
 5. [Das System benutzen](#5-das-system-benutzen)
@@ -416,32 +416,121 @@ Port ändern: `PORT=8005 make run` (einmalig) oder `PORT=8005` in `.env` (dauerh
 
 ### 4.5 llama.cpp-Server (für Profil `hybrid`/`local-dev`)
 
+**Voraussetzungen:** Docker mit NVIDIA-Container-Toolkit, GPU mit ausreichend VRAM
+(Qwen3-35B-Q4: ~22 GB; Qwen3-8B-Q4: ~5 GB).
+
 ```bash
-make llm-up        # startet Docker-Container (Default: GPU 1, Port 8001, Alias va_llm)
+# Starten (Default: GPU 1, Port 8001, Modell qwen3-35B-Uncensored):
-make llm-status    # Container- + HTTP-Status prüfen
+make llm-up
-make llm-down      # stoppen
+
+# Status prüfen (warten bis „Modell bereit" und HTTP 200 erscheinen):
+make llm-status
+
+# Logs live beobachten:
+docker logs -f va_llm
+
+# Stoppen:
+make llm-down
 ```
 
-Parameter überschreibbar per ENV:
+**Mit anderen Parametern** — ENV-Variable vor dem Befehl setzen:
 
-| Variable | Default | Bedeutung |
-|----------|---------|-----------|
-| `HOST_PORT` | `8001` | Host-Port |
-| `GPU_DEVICE` | `1` | GPU-Index |
-| `MODEL_REL_PATH` | `models/qwen3/Qwen3.6-35B-A3B-Uncensored-...Q4_K_M.gguf` | Modellpfad relativ zu `HF_HOME` |
-| `HF_HOME` | `~/nvme2n1p7_home/huggingface` | Modell-Sammlung |
-| `MODEL_ALIAS` | `va_llm` | API-Modellname |
-| `CONTAINER_NAME` | `va_llm` | Docker-Containername |
-
-Beispiel (andere GPU + anderes Modell):
 ```bash
-GPU_DEVICE=2 MODEL_REL_PATH=models/qwen3/anderes-modell.gguf \
+# Andere GPU:
+GPU_DEVICE=0 make llm-up
+
+# Anderen Port:
+HOST_PORT=8101 make llm-up
+
+# Anderes Modell auf anderer GPU:
+GPU_DEVICE=2 HOST_PORT=8102 MODEL_REL_PATH="models/qwen3/anderes-modell.gguf" make llm-up
+
+# Direkt (ohne make — identisch, aber zeigt alle Parameter):
+bash scripts/llm-server/start-llm-server.sh
+GPU_DEVICE=0 bash scripts/llm-server/start-llm-server.sh
+GPU_DEVICE=2 HOST_PORT=8102 MODEL_REL_PATH="models/qwen3/anderes-modell.gguf" \
   bash scripts/llm-server/start-llm-server.sh
 ```
 
+Alle überschreibbaren ENV-Variablen:
+
+| Variable | Default | Bedeutung |
+|----------|---------|-----------|
+| `GPU_DEVICE` | `1` | GPU-Index (0-basiert, `nvidia-smi` zeigt verfügbare GPUs) |
+| `HOST_PORT` | `8001` | Host-Port des LLM-Servers |
+| `MODEL_REL_PATH` | `models/qwen3/Qwen3.6-35B-A3B-Uncensored-...Q4_K_M.gguf` | Modellpfad relativ zu `HF_HOME` |
+| `HF_HOME` | `~/nvme2n1p7_home/huggingface` | Modell-Basisverzeichnis (als Volume eingebunden) |
+| `MODEL_ALIAS` | `va_llm` | Modellname in der OpenAI-API (→ `LOCAL_LLM_MODEL` in `.env`) |
+| `CONTAINER_NAME` | `va_llm` | Docker-Containername |
+| `IMAGE` | `ghcr.io/ggml-org/llama.cpp:server-cuda` | Docker-Image |
+
 > ⚠️ Wird `HOST_PORT` oder `MODEL_ALIAS` geändert, müssen `LOCAL_LLM_BASE_URL`
 > und `LOCAL_LLM_MODEL` in `.env` entsprechend angepasst werden.
 
+Das Skript wartet bis zu 300 Sekunden auf einen HTTP-200-Response und bricht mit
+Fehler ab, wenn das Modell nicht startet — kein stilles Fehlschlagen.
+
+---
+
+### 4.6 Ollama (Alternative zu llama.cpp, kein Docker nötig)
+
+Ollama verwaltet seinen Serverprozess selbst und braucht kein Docker. Es eignet sich
+besonders für schnellen Einstieg, CPU-Betrieb und kleinere Modelle.
+
+**Installation** (falls noch nicht installiert):
+```bash
+curl -fsSL https://ollama.com/install.sh | sh
+```
+
+**Dienst starten:**
+```bash
+# empfohlen — systemd verwaltet den Prozess:
+sudo systemctl start ollama
+sudo systemctl enable ollama    # automatisch bei Boot starten
+sudo systemctl status ollama    # Status prüfen
+
+# alternativ — manuell im Vordergrund (Strg+C stoppt):
+ollama serve
+# mit anderem Port (Default: 11434):
+OLLAMA_HOST=0.0.0.0:11435 ollama serve
+```
+
+**Modell herunterladen** (einmalig):
+```bash
+ollama pull qwen3:30b-a3b       # ~20 GB, Thinking deaktiviert (empfohlen für Voice)
+ollama pull qwen3:8b            # ~5 GB, CPU-tauglich, weniger Qualität
+ollama pull qwen3:14b           # ~9 GB, guter Kompromiss
+```
+
+**Status prüfen:**
+```bash
+ollama list                     # installierte Modelle mit Größe und Änderungsdatum
+ollama ps                       # gerade aktive Modelle mit VRAM-Verbrauch
+```
+
+**Modell entfernen** (Speicher freigeben):
+```bash
+ollama rm qwen3:8b
+```
+
+**Gateway für Ollama konfigurieren** (in `.env`):
+```bash
+LOCAL_LLM_BASE_URL=http://127.0.0.1:11434/v1
+LOCAL_LLM_API_KEY=ollama
+LOCAL_LLM_MODEL=qwen3:30b-a3b   # exakter Name aus 'ollama list'
+```
+
+**Gateway starten:**
+```bash
+VA_PROFILE=hybrid make run      # STT/TTS cloud, LLM via Ollama
+VA_PROFILE=local-dev make run   # alles lokal (STT/TTS in-process, LLM via Ollama)
+```
+
+> **Hinweis Reasoning:** `LOCAL_LLM_DISABLE_REASONING=true` (Gateway-Standard) schickt
+> `enable_thinking: false` an den Server — Ollama ignoriert dieses Feld. Um Reasoning
+> zu deaktivieren, den Modell-Tag ohne Thinking-Suffix wählen (`qwen3:30b-a3b` statt
+> `qwen3:30b-a3b:thinking`).
+
 ---
 
 ## 5. Das System benutzen
@@ -1804,10 +1893,11 @@ in `app/dependencies.py` + Implementierung in `app/providers/`. → [Architektur
 | Kontingent (Kosten-Bremse) | § 9.3 |
 | llama.cpp | § 4.5, § 3.2, § 3.3 |
 | local-dev-Profil | § 3.3 |
+| Ollama starten | § 4.6 |
 | Metriken / Monitoring | § 9.2, Anhang B.1 |
 | Mikrofon → Audio-Geräte | § 6.7 |
 | Notfall-Erkennung | § 10 |
-| Ollama | § 3.3, § 3.2 |
+| Ollama | § 3.2, § 3.3, **§ 4.6** |
 | piper (TTS) | § 6.5.2, Anhang C |
 | Pipeline (Architektur) | § 1.3 |
 | Profile (cloud/hybrid/local-dev) | § 3 |

README.md

@@ -49,6 +49,94 @@ Web-Interface: Browser → `http://localhost:8080/`
 
 ---
 
+## Starten — alle Szenarien
+
+### Profil `cloud` (nur Gateway, alles via OpenRouter)
+
+```bash
+make run                        # Gateway auf PORT aus .env (Standard: 8080)
+VA_PROFILE=cloud make run       # Profil explizit setzen (überschreibt .env)
+PORT=8003 make run              # anderen Port für diesen Start
+LOG_LEVEL=debug make run        # ausführlichere Logs
+```
+
+### Profil `hybrid` / `local-dev` mit llama.cpp (Docker + GPU)
+
+```bash
+# 1) LLM-Server starten
+make llm-up                     # Default: GPU 1, Port 8001, Modell qwen3-35B-Uncensored
+make llm-status                 # warten bis „Modell bereit" + HTTP 200 erscheint
+make llm-down                   # stoppen
+
+# Mit anderen Parametern (via ENV):
+GPU_DEVICE=0 make llm-up
+HOST_PORT=8101 GPU_DEVICE=2 make llm-up
+GPU_DEVICE=0 MODEL_REL_PATH="models/qwen3/anderes-modell.gguf" make llm-up
+
+# Direkt (ohne make):
+bash scripts/llm-server/start-llm-server.sh
+GPU_DEVICE=0 bash scripts/llm-server/start-llm-server.sh
+
+# 2) Gateway starten
+VA_PROFILE=hybrid make run      # STT/TTS cloud, LLM lokal
+VA_PROFILE=local-dev make run   # alles lokal (STT/TTS in-process)
+```
+
+ENV-Optionen für `make llm-up` / `start-llm-server.sh`:
+
+| Variable | Default | Bedeutung |
+|----------|---------|-----------|
+| `GPU_DEVICE` | `1` | GPU-Index (0-basiert) |
+| `HOST_PORT` | `8001` | Host-Port des LLM-Servers |
+| `MODEL_REL_PATH` | `models/qwen3/Qwen3.6-35B-...Q4_K_M.gguf` | Modellpfad relativ zu `HF_HOME` |
+| `HF_HOME` | `~/nvme2n1p7_home/huggingface` | Modell-Basisverzeichnis |
+| `MODEL_ALIAS` | `va_llm` | OpenAI-API-Modellname (→ `LOCAL_LLM_MODEL` in `.env`) |
+| `CONTAINER_NAME` | `va_llm` | Docker-Containername |
+
+> Wird `HOST_PORT` oder `MODEL_ALIAS` geändert, müssen `LOCAL_LLM_BASE_URL` und
+> `LOCAL_LLM_MODEL` in `.env` entsprechend angepasst werden.
+
+### Profil `hybrid` / `local-dev` mit Ollama
+
+```bash
+# 1) Ollama-Dienst starten
+sudo systemctl start ollama     # empfohlen (bei systemd-Installation)
+# oder im Vordergrund:
+ollama serve
+
+# 2) Modell herunterladen (einmalig, ~20 GB):
+ollama pull qwen3:30b-a3b       # Thinking deaktiviert (empfohlen)
+# kleinere Alternative (CPU-tauglich, ~5 GB):
+ollama pull qwen3:8b
+
+# Status prüfen:
+ollama list                     # installierte Modelle
+ollama ps                       # gerade aktive Modelle (mit VRAM-Verbrauch)
+
+# 3) .env anpassen (einmalig):
+# LOCAL_LLM_BASE_URL=http://127.0.0.1:11434/v1
+# LOCAL_LLM_API_KEY=ollama
+# LOCAL_LLM_MODEL=qwen3:30b-a3b   ← exakter Name aus 'ollama list'
+
+# 4) Gateway starten:
+VA_PROFILE=hybrid make run
+VA_PROFILE=local-dev make run
+```
+
+### Alle `make`-Targets im Überblick
+
+```bash
+make install    # venv anlegen + Abhängigkeiten installieren
+make run        # Gateway starten (uvicorn --reload, Port aus .env)
+make test       # Pytest-Suite (offline, kostenlos)
+make smoke      # Live-End-to-End-Test gegen OpenRouter (geringe Kosten)
+make llm-up     # llama.cpp-Docker-Container starten
+make llm-down   # llama.cpp-Container stoppen
+make llm-status # Container- und HTTP-Status prüfen
+```
+
+---
+
 ## Dokumentation
 
 | Dokument | Zielgruppe | Inhalt |