diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..fba521f
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,103 @@
+# macbook-setup - Projektkontext fuer Claude Code
+
+## Projekt-Uebersicht
+Setup-Skripte fuer Ubuntu 24.04 auf alten MacBook Pros (Xubuntu-Desktop).
+Repo liegt auf Gitea: git.motocamp.de/rene/macbook-setup
+
+## Hardware
+
+| Bezeichnung | Modell | CPU | GPU | Display | Besonderheiten |
+|---|---|---|---|---|---|
+| m16 | MBP 15" Mid 2014 | i7-4980HQ | Intel HD 5200 + AMD Radeon R9 M370X | Retina (2x) | AMD muss geblockt werden (amdgpu blacklist) |
+| m13 | MBP 13" Late 2013 | - | nur Intel | Retina (2x) | - |
+
+- WLAN: Broadcom BCM4360 (kein Treiber im Ubuntu-Installer!)
+- m16 erreichbar per `ssh rene@m16.local`, sudo ohne Passwort konfiguriert
+
+## Netzwerk
+- Subnetz: 10.47.11.0/24
+- Fritz!Box: 10.47.11.1
+- Synology: 10.47.11.10 (dsm.motocamp.de)
+
+## Installations-Workflow (WICHTIG)
+1. **Stock Ubuntu 24.04 Server ISO** auf USB-Stick (dd) - **NICHT** das custom ISO (build-iso.sh)!
+2. Interaktiv installieren: Sprache, Tastatur, **WLAN im Installer einrichten**, User `rene`, LVM
+3. Neustarten, einloggen als rene
+4. `curl -fsSL https://git.motocamp.de/rene/macbook-setup/raw/branch/main/setup-base.sh | sudo bash -s -- 16`
+5. Neustarten, in XFCE einloggen
+6. `curl -fsSL https://git.motocamp.de/rene/macbook-setup/raw/branch/main/setup-desktop.sh | bash`
+
+**Warum kein custom ISO:** Broadcom-WLAN hat keinen Treiber in der Live-Umgebung.
+Der interaktive Installer hat einen eingebauten WLAN-Schritt. Ohne Netzwerk koennen
+die Setup-Skripte nicht heruntergeladen werden.
+
+## Arbeitsweise
+- Rene verbindet sich per SSH auf das MacBook und fuehrt Befehle dort aus
+- Wenn Befehle auf dem MacBook noetig sind: per `ssh rene@<ip>` verbinden und dort ausfuehren (statt den User bitten, Befehle abzutippen)
+
+## Paketquellen-Zuordnung
+- **apt:** System-Pakete, xubuntu-desktop, Thunderbird, KeePassXC, default-jre etc.
+- **Snap:** FreeCAD, LibreOffice (wegen "benutzerdefinierte Installation nicht abgeschlossen" Bug bei .deb)
+- **Flatpak:** Brave Browser (wegen SIGTRAP/int3 Crash bei .deb auf aelterer HW), PrusaSlicer
+- flatpak muss in setup-base.sh (root) installiert werden, nicht in setup-desktop.sh (user)
+
+## Geloeste Probleme (Lessons Learned)
+
+### Brave Browser
+- .deb Version crasht mit SIGTRAP (int3) auf aelterer Hardware
+- AppArmor `apparmor_restrict_unprivileged_userns=1` war NICHT die Ursache
+- Loesung: Flatpak verwenden
+
+### LibreOffice
+- .deb Version zeigt "benutzerdefinierte Installation nicht abgeschlossen"
+- Loesung: Snap verwenden
+- default-jre Paket noetig (behebt "javaldx failed" in Writer)
+
+### HiDPI / Retina Display
+- GDK WindowScalingFactor=2 + DPI=96 (NICHT 128!)
+- Cursor-Groesse: 48
+- xfwm4: Default-xhdpi Theme
+- XFCE Compositor deaktivieren
+- xfce4-display-settings deaktivieren (verursacht Endlosschleife)
+
+### Tastatur
+- iso_layout=1 + de nodeadkeys + lv3:lalt_switch
+- XFCE Keyboard-Override deaktivieren (XkbDisable)
+
+### Netzwerk & WLAN
+- NetworkManager statt netplan fuer WLAN
+- WLAN-Config beim netplan-zu-NM Umstieg erhalten
+- systemd-networkd-wait-online deaktivieren
+- cloud-init deaktivieren nach Installation
+
+### WireGuard VPN
+- Konfiguration via NetworkManager .nmconnection (nicht wg-quick)
+- DNS + dns-search direkt im NM-Profil
+- **Key-Verwechslung:** m16/m13 hatten eigenen PublicKey als Peer-PublicKey eingetragen. NM zeigt keinen Fehler, wg show zeigt einfach keine Peers. Immer pruefen: local public key darf NICHT gleich dem Peer-PublicKey sein.
+- Server-PublicKey gegen funktionierende Clients verifizieren
+
+### WireGuard Server-Referenz
+- Server: 24.134.39.137:443 (VPS, Interface ens3)
+- Server-PublicKey: mp0YKEjsUbnld3aTAnF6cSzTfixhZETQCoKiFHIcF30=
+- Peer-IPs: .2=iPhoneR, .3=iPhoneM, .4=iPadR, .5=iPadM, .6=m1, .7=m16, .8=m13
+- DNS im VPN: 10.47.11.20 (Fritz!Box), 10.47.11.1 (Gateway)
+- Server macht NAT/Masquerade ueber ens3
+
+### Setup-Skripte
+- macOS-Installer hinterlaesst macOS-sudoers: setup-base.sh ersetzt sie durch Linux-Standard
+- setup-desktop.sh: set -e entfernt, Unicode durch ASCII ersetzt
+- setup-desktop.sh Autostart braucht Terminal-Fenster (xfce4-terminal) fuer interaktive Eingaben
+- setup.sh: read von /dev/tty bei curl|bash
+- Sleep/Suspend waehrend Installation verhindern
+- DPMS gestaffelt: 5/6/7 Min (Blank/Sleep/Off)
+
+### Zsh & Tools
+- oh-my-zsh, Powerlevel10k, zsh-syntax-highlighting, MesloLGS NF Font
+- PlatformIO via pipx
+- h2j (HEIC-Konverter), zoxide, micro
+- gitcheck Alias funktioniert in interaktiver Shell (nicht via `zsh -l -c`, das ist normal)
+
+## Autoinstall (archiviert, nicht mehr verwendet)
+- YAML-Heredocs brechen den Parser: printf mit \n verwenden
+- Kernel-Parameter-Syntax fuer autoinstall dokumentiert
+- Wurde verworfen wegen fehlendem WLAN-Treiber im Live-System