docs: Setup auf jungfräulichem Host + Warum USA+China parallel (#4)

BEDIENUNGSANLEITUNG.md

@@ -5,7 +5,21 @@
 
 ---
 
-## 1. Wozu dieses Repository?
+## 1. Warum Modelle aus USA und China parallel?
+
+Dieses Repo ist bewusst nicht an einen einzigen Anbieter oder ein einziges Land gebunden. Es verbindet Modelle aus **USA (Anthropic/Claude)** und **China (Z.ai GLM, Moonshot Kimi, Alibaba Qwen, DeepSeek)** über denselben Client. Dafür gibt es fünf handfeste Gründe:
+
+1. **Resilienz gegen Störungen.** Wer nur eine Quelle hat, steht bei API-Ausfällen, Rate-Limits, Wartungsfenstern oder geopolitischen Maßnahmen (z. B. US-Exportkontrollen, regionalen Sperren) plötzlich ohne Coding-Tool da. Mit Profilen für mehrere Anbieter wechselst du den Endpunkt in einem Aufruf – `claude-pro` fällt aus? Weiter mit `claude-glm`.
+2. **Preisdruck durch Wahl.** Allein die Existenz der chinesischen Modelle zwingt die Preisliste nach unten. Wer wählen kann, zahlt nicht den vollen Anthropic-Tarif, sondern nutzt für Alltags-Coding DeepSeek/GLM (ein Vielfaches günstiger, siehe Abschnitt 8) und hebt Claude für die kritischen Stellen auf.
+3. **Kein Vendor-Lock-in.** Dein Workflow – Repository, Prompts, Tooling – bleibt anbieterunabhängig. Nur der API-Endpunkt wechselt. Niemand kann dir den Zugriff auf deine eigene Pipeline sperren.
+4. **Modellvielfalt je Aufgabe.** Code-Stärke (GLM-5.2, Kimi-K2.7-code, Qwen3-Coder), maximale Wirtschaftlichkeit (DeepSeek V3.1), Top-Reasoning (Claude Opus/Sonnet), kostenloses Ausprobieren (Qwen3-Coder `:free`). Pro Task das passende Modell, pro Aufruf wechselbar.
+5. **Perspektivenvielfalt.** Modelle aus unterschiedlichen Trainings- und Rechtsräumen liefern unterschiedliche Perspektiven – wertvoll bei Code-Reviews, Risk-Assessment oder kreativen Problemen, weil ein zweites, unabhängig trainiertes Modell denselben Code anders bewerten kann.
+
+> **Hinweis zu Datenschutz & Datenabfluss:** Sowohl US- als auch CN-Endpunkte übertragen deine Prompts und Codes in fremde Rechtsräume (USA bzw. VR China). Konfiguriere OpenRouter-Datenverarbeitung bewusst (https://openrouter.ai/settings), setze für sensible Projekte `ANTHROPIC_AUTH_TOKEN` nur in vertrauenswürdigen Sessions und vermeide das Einreichen von Secrets über das CLI. Siehe auch Abschnitt 9.
+
+---
+
+## 2. Wozu dieses Repository?
 
 Claude Code ist der CLI-Client von Anthropic. Er spricht standardmäßig die Anthropic-API an – und die ist teuer:
 
@@ -40,43 +54,139 @@ claude-profile <name>   # generischer Aufruf
 
 ---
 
-## 2. Voraussetzungen
+## 3. Setup auf einem jungfräulichen Linux-Host
 
-- `claude` (Claude Code CLI) installiert
+Dieser Abschnitt führt von einem nackten Debian/Ubuntu-System (vHost im Rechenzentrum oder heimischer Laptop) bis zur lauffähigen `claude-*`-Umgebung. Falls `claude` und `node` bei dir bereits vorhanden sind, überspringe ihn und gehe direkt zu Abschnitt 4.
-- funktionierendes **Claude-Pro-Login** (nur für das `pro`-Profil nötig)
-- `bash`
-- `yq` zum Parsen der YAML-Konfiguration
-- ein **OpenRouter-Account + API-Key** (nur für die OpenRouter-Profile)
-  → Key anlegen unter https://openrouter.ai/keys
 
-`yq` installieren (Debian/Ubuntu):
+> **Zielplattform:** Debian/Ubuntu (apt). Für Fedora/RHEL ersetze `apt-get` durch `dnf`, für Arch durch `pacman`. Ein containerisiertes Setup (reproduzierbar, ohne Host-Veränderung) steht ganz unten in diesem Abschnitt.
+
+### 3.1 Basissystem: git, bash, yq
 
 ```bash
 sudo apt-get update
-sudo apt-get install -y yq
+sudo apt-get install -y git bash yq curl ca-certificates
 ```
 
 > Hinweis: Unter Debian/Ubuntu ist `yq` der *jq-Wrapper* („Command-line YAML processor – jq wrapper"). Das funktioniert. Der *MikeFarah-yq* geht ebenfalls.
 
----
+### 3.2 Node.js 18+ (Voraussetzung für Claude Code)
 
-## 3. Setup – Schritt für Schritt
+Claude Code benötigt **Node.js 18 oder neuer**. Die sauberste, sudo-freie Methode auf einem vHost ist **NodeSource** (systemweit) oder **nvm** (pro User):
 
-### 3.1 Repository klonen
+**Variante A – NodeSource (empfohlen für vHost):**
+
+```bash
+curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
+sudo apt-get install -y nodejs
+node --version    # muss >= 18 sein
+```
+
+**Variante B – nvm (pro User, mehrere Node-Versionen):**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
+source "$HOME/.bashrc"
+nvm install --lts
+nvm use --lts
+node --version
+```
+
+### 3.3 Claude Code CLI installieren
+
+```bash
+npm install -g @anthropic-ai/claude-code
+claude --version
+```
+
+- Paketname: `@anthropic-ai/claude-code` (offiziell, global).
+- ⚠️ **Nicht `sudo npm install -g` verwenden** – das verursacht Berechtigungsprobleme. Nutze NodeSource (systemweit) oder nvm (pro User), damit `npm -g` ohne `sudo` in ein Verzeichnis deines Users installiert.
+- Upgrade später mit `npm install -g @anthropic-ai/claude-code@latest` (nicht `npm update -g`).
+
+### 3.4 Claude-Pro-Login
+
+```bash
+claude
+```
+
+Erstmaliger Start öffnet den Login-Flow. Melde dich mit dem Anthropic-Pro-Account an. Damit ist das `pro`-Profil einsatzbereit (keine API-Kosten, nur das Pro-Abo).
+
+### 3.5 OpenRouter-Account + Key
+
+1. Auf https://openrouter.ai ein Konto anlegen (funktioniert auch ohne Kreditkarte für die `:free`-Modelle).
+2. Unter https://openrouter.ai/keys einen API-Key erzeugen (Format `sk-or-v1-…`).
+3. Key als Umgebungsvariable setzen (siehe Abschnitt 5.4).
+
+### 3.6 Repo klonen + installieren
 
 ```bash
 git clone https://kitux.de/forgejo/dschlueter/claude-launcher-profiles.git
 cd claude-launcher-profiles
+cp config/profiles.example.yml config/profiles.yml
+chmod +x bin/claude-profile bin/install-claude-profiles lib/profiles.sh
+./bin/install-claude-profiles
+source ~/.bashrc
 ```
 
-### 3.2 Konfiguration anlegen
+Ab hier weiter mit **Abschnitt 5 (OpenRouter-Key setzen)** und **Abschnitt 6 (Nutzung)**.
+
+### 3.7 Alternative: containerisiertes Setup
+
+Für reproduzierbare vHost-Umgebungen ohne Veränderung des Host-Systems. Beispiel-`Dockerfile` (Debian-basiert, enthält Node, Claude Code, yq und das Repo):
+
+```dockerfile
+FROM debian:bookworm-slim
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      git bash yq curl ca-certificates gnupg \
+ && curl -fsSL https://deb.nodesource.com/setup_lts.x | bash - \
+ && apt-get install -y nodejs \
+ && rm -rf /var/lib/apt/lists/*
+RUN npm install -g @anthropic-ai/claude-code
+WORKDIR /root/src
+RUN git clone https://kitux.de/forgejo/dschlueter/claude-launcher-profiles.git \
+ && cd claude-launcher-profiles \
+ && cp config/profiles.example.yml config/profiles.yml \
+ && chmod +x bin/claude-profile bin/install-claude-profiles lib/profiles.sh \
+ && ./bin/install-claude-profiles
+WORKDIR /root/src/claude-launcher-profiles
+ENV OPENROUTER_API_KEY=""
+ENTRYPOINT ["/bin/bash"]
+```
+
+Bauen und starten:
+
+```bash
+docker build -t vibe-code .
+# Key zur Laufzeit reinreichen, nie ins Image backen:
+docker run -it -e OPENROUTER_API_KEY="$OPENROUTER_API_KEY" \
+  -v "$HOME/.claude:/root/.claude" \
+  vibe-code
+```
+
+> ⚠️ **OpenRouter-Key nie ins Image backen.** Im `Dockerfile` ist er absichtlich leer (`ENV OPENROUTER_API_KEY=""`); er wird erst beim `docker run` als `-e`-Flag hereingereicht. Das Claude-Pro-Login liegt im Volume `~/.claude` auf dem Host und bleibt so containerübergreifend erhalten. Podman funktioniert analog (ersetze `docker` durch `podman`).
+
+---
+
+## 4. Voraussetzungen (Kurzfassung)
+
+Vollständige Einrichtung ab nacktem System → **Abschnitt 3**. Kurzform, falls du schon `claude`, `node` und `yq` hast:
+
+- `claude` (Claude Code CLI) installiert → Abschnitt 3.3
+- funktionierendes **Claude-Pro-Login** (nur für das `pro`-Profil nötig) → Abschnitt 3.4
+- `bash` + `yq` (YAML-Parser) → Abschnitt 3.1
+- ein **OpenRouter-Account + API-Key** (nur für die OpenRouter-Profile) → Abschnitt 3.5
+
+---
+
+## 5. Konfiguration & Keys
+
+### 5.1 `profiles.yml` anlegen
 
 ```bash
 cp config/profiles.example.yml config/profiles.yml
 $EDITOR config/profiles.yml
 ```
 
-`config/profiles.yml` enthält **keine** API-Keys – nur Modellnamen, Base-URL und den Claude-Startbefehl. Der OpenRouter-Key kommt ausschließlich aus der Umgebung (siehe 3.4). Beispiel:
+`config/profiles.yml` enthält **keine** API-Keys – nur Modellnamen, Base-URL und den Claude-Startbefehl. Der OpenRouter-Key kommt ausschließlich aus der Umgebung (siehe 5.2). Beispiel:
 
 ```yaml
 defaults:
@@ -104,16 +214,7 @@ profiles:
 >
 > ⚠️ **`openrouter/free` ist ein Meta-Slug**, kein festes Modell: OpenRouter routet den Aufruf an ein gerade verfügbares Gratis-Modell weiter. Aktuell landet das z. B. bei `nvidia/nemotron-3.5-content-safety` – einem **Content-Safety-Klassifikator, nicht einem Coding-Modell**. Zum Coden stattdessen `qwen/qwen3-coder:free` eintragen (gültig, aber rate-limitiert – bei 429 kurz warten oder eigenes Guthaben nutzen).
 
-### 3.3 Skripte ausführbar machen und installieren
+### 5.2 OpenRouter-Key setzen
-
-```bash
-chmod +x bin/claude-profile bin/install-claude-profiles lib/profiles.sh
-./bin/install-claude-profiles
-```
-
-Der Installer legt (falls nötig) einen Symlink unter `~/src/claude-launcher-profiles` an und fügt eine `source`-Zeile in deine `~/.bashrc` ein, die die Aliase lädt.
-
-### 3.4 OpenRouter-Key setzen
 
 Der Key wird **nicht** in `profiles.yml` gespeichert, sondern als Umgebungsvariable.
 
@@ -130,18 +231,27 @@ echo 'export OPENROUTER_API_KEY="sk-or-v1-..."' >> ~/.bashrc
 source ~/.bashrc
 ```
 
-### 3.5 Shell neu laden
+### 5.3 Skripte ausführbar machen und installieren
+
+```bash
+chmod +x bin/claude-profile bin/install-claude-profiles lib/profiles.sh
+./bin/install-claude-profiles
+```
+
+Der Installer legt (falls nötig) einen Symlink unter `~/src/claude-launcher-profiles` an und fügt eine `source`-Zeile in deine `~/.bashrc` ein, die die Aliase lädt.
+
+### 5.4 Shell neu laden und prüfen
 
 ```bash
 source ~/.bashrc
 alias | grep claude-
 ```
 
-Du sollte `claude-pro`, `claude-glm`, `claude-kimi`, `claude-free` sehen.
+Du solltest `claude-pro`, `claude-glm`, `claude-kimi`, `claude-free` sehen.
 
 ---
 
-## 4. Nutzung
+## 6. Nutzung
 
 ```bash
 claude-pro      # Claude Pro (Anthropic-Login, keine API-Kosten)
@@ -161,7 +271,7 @@ Jeder Aufruf setzt die nötigen `ANTHROPIC_*`-Variablen für die jeweilige Sitzu
 
 ---
 
-## 5. Eigene Profile anlegen
+## 7. Eigene Profile anlegen
 
 Trage ein neues Profil in `config/profiles.yml` ein:
 
@@ -181,9 +291,9 @@ Danach `source ~/.bashrc` – fertig. Der Key (`OPENROUTER_API_KEY`) gilt für a
 
 ---
 
-## 6. Kosten vs. Qualität – ehrlicher Vergleich
+## 8. Kosten vs. Qualität – ehrlicher Vergleich
 
-### 6.1 Beispielsitzung (500 K Input + 50 K Output, ungespeichert)
+### 8.1 Beispielsitzung (500 K Input + 50 K Output, ungespeichert)
 
 | Modell | Kosten | relativ zu Sonnet 4.5 |
 |---|---|---|
@@ -196,7 +306,7 @@ Danach `source ~/.bashrc` – fertig. Der Key (`OPENROUTER_API_KEY`) gilt für a
 
 > Wer Claude Code intensiv nutzt, gibt an einem Tag schnell mehrere Millionen Token aus. Bei 10 M Output/Tag macht der Unterschied zwischen Sonnet ($150) und GLM-5.2 ($30) schnell **über $120 pro Tag** aus. Prompt-Caching (Cache-Read bei GLM ~$0,18/M) senkt die Kosten für wiederholte System-Prompts zusätzlich.
 
-### 6.2 Qualität – realistische Einordnung
+### 8.2 Qualität – realistische Einordnung
 
 - **GLM-5.2** (`z-ai/glm-5.2`): großes Reasoning-Modell, 1-M-Kontext, stark in langen Coding-/Agenten-Workflows und Werkzeugnutzung. Für die meisten Software-Engineering-Aufgaben ein brauchbarer Sonnet-Ersatz; bei den allerschwersten Schlussfolgerungen liegt Opus weiter vorn.
 - **Kimi K2.7-code** (`moonshotai/kimi-k2.7-code`): fokussiert auf langfristiges Coding und UI-Generierung, Multi-Agenten-Orchestrierung. Gut für komplexere End-to-End-Coding-Tasks; 262K-Kontext (schmaler als GLM). Reasoning-Modell – braucht genug Output-Token, sonst verbraucht das „Denken" das Limit bevor die Antwort kommt.
@@ -208,7 +318,7 @@ Danach `source ~/.bashrc` – fertig. Der Key (`OPENROUTER_API_KEY`) gilt für a
 
 ---
 
-## 7. Sicherheit
+## 9. Sicherheit
 
 - `config/profiles.yml` enthält nur lokale Einstellungen und steht in `.gitignore` – sie wird nicht committet.
 - Der OpenRouter-Key liegt **nur** in der Shell-Umgebung (`~/.bashrc`), nie im Repo.
@@ -221,11 +331,11 @@ Danach `source ~/.bashrc` – fertig. Der Key (`OPENROUTER_API_KEY`) gilt für a
 
 ---
 
-## 8. Troubleshooting
+## 10. Troubleshooting
 
 | Symptom | Ursache / Lösung |
 |---|---|
-| `Error: yq is required` | `yq` fehlt → siehe Abschnitt 2. |
+| `Error: yq is required` | `yq` fehlt → siehe Abschnitt 3.1. |
 | `Error: missing config file` | `config/profiles.yml` fehlt → `cp config/profiles.example.yml config/profiles.yml`. |
 | `Error: OPENROUTER_API_KEY is not set` | Key nicht exportiert → `export OPENROUTER_API_KEY=...` und `source ~/.bashrc`. |
 | `Error: profile 'x' not found` | Tippfehler oder Profil fehlt in `profiles.yml`. |
@@ -239,7 +349,7 @@ Danach `source ~/.bashrc` – fertig. Der Key (`OPENROUTER_API_KEY`) gilt für a
 
 ---
 
-## 9. Wo was liegt
+## 11. Wo was liegt
 
 ```
 bin/claude-profile           # Einstieg: ruft launch_profile <name> auf
@@ -248,6 +358,8 @@ lib/profiles.sh              # Kernlogik: YAML-Parser, Profile, Env-Setup
 shell/aliases.sh             # die claude-* Aliase
 config/profiles.example.yml  # Vorlage (im Repo)
 config/profiles.yml          # deine lokale Konfig (gitignored)
+tests/test_profiles.sh       # Test-Suite (siehe Abschnitt 10)
+Makefile                     # `make test` Runner
 ```
 
 Fragen oder Erweiterungen → Forgejo: https://kitux.de/forgejo/dschlueter/claude-launcher-profiles