diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d2d893a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,99 @@
+# whisper-local
+
+Lokales Speech-to-Text mit globalem Hotkey. Hotkey halten → Sprechen → loslassen → faster-whisper transkribiert lokal → Text wird ins aktive Textfeld eingefügt. Kein Netzwerk, kein Cloud-Service.
+
+Läuft als Hintergrunddienst mit Tray-Icon auf **Linux (KDE Plasma / Wayland)** und **Windows 10/11**.
+
+## Features
+
+- Systemweiter Hotkey (Standard: `F12`), konfigurierbar über den Einstellungs-Dialog im Tray
+- Einfügen ins aktive Textfeld unabhängig von der Anwendung (Browser, Terminal, IDE …)
+- Mikrofon-Auswahl über Tray-Einstellungen
+- Lokale Transkription via [faster-whisper](https://github.com/SYSTRAN/faster-whisper)
+- Tray-Icon mit drei Zuständen: warten / aufnehmen / transkribieren
+
+## Systemabhängigkeiten
+
+### Linux (Arch / CachyOS)
+
+```bash
+sudo pacman -S ydotool wl-clipboard libayatana-appindicator gobject-introspection
+```
+
+- `ydotool` — simuliert Tastatureingaben unter Wayland (Text-Einfügen via `Ctrl+V`)
+- `wl-clipboard` — Clipboard-Zugriff unter Wayland (`wl-copy`)
+- `libayatana-appindicator` + `gobject-introspection` — Tray-Icon über StatusNotifierItem (KDE/Wayland)
+
+Damit `ydotool` ohne `sudo` funktioniert, muss der `ydotoold`-Daemon laufen und der Benutzer in der `input`-Gruppe sein:
+
+```bash
+sudo systemctl enable --now ydotool
+sudo usermod -aG input $USER
+# Neu-Login nötig
+```
+
+Der Benutzer braucht außerdem Lesezugriff auf `/dev/input/event*`, was die `input`-Gruppen-Mitgliedschaft abdeckt.
+
+### Windows
+
+Keine System-Dependencies. `pynput` und `pywin32` werden automatisch via uv installiert.
+
+## Installation
+
+Voraussetzung: [uv](https://github.com/astral-sh/uv) (Python-Paketmanager).
+
+```bash
+git clone <repo-url> whisper-local
+cd whisper-local
+uv sync
+```
+
+`uv sync` installiert plattformspezifisch:
+
+- **Linux**: `evdev`, `PyGObject`, `pystray`, `Pillow`, `sv-ttk`, `darkdetect`
+- **Windows**: `pynput`, `pywin32`, `pystray`, `Pillow`, `sv-ttk`, `darkdetect`
+
+## Konfiguration
+
+Die Konfigurationsdatei wird beim ersten Start angelegt. Vorlage: [config.example.toml](config.example.toml).
+
+- **Linux**: `~/.config/whisper-local/config.toml`
+- **Windows**: `%APPDATA%\whisper-local\config.toml`
+
+Hotkey und Mikrofon lassen sich auch direkt über den Einstellungs-Dialog im Tray ändern (Rechtsklick aufs Tray-Symbol → „Einstellungen"). Änderungen greifen sofort ohne Neustart.
+
+Key-Namen folgen dem evdev-Format (`KEY_F12`, `KEY_LEFTSHIFT`, …) — auch unter Windows.
+
+## Starten
+
+```bash
+uv run whisper-local
+```
+
+Beim ersten Start lädt faster-whisper das Whisper-Modell (Standard: `small`) herunter. Danach erscheint das Tray-Icon und der Hotkey ist aktiv.
+
+### Autostart unter Linux (systemd user unit)
+
+```bash
+mkdir -p ~/.config/systemd/user
+cp systemd/whisper-local.service ~/.config/systemd/user/
+systemctl --user daemon-reload
+systemctl --user enable --now whisper-local.service
+```
+
+Das `whisper-local`-Executable muss dafür in `~/.local/bin` verfügbar sein (`uv tool install .` oder Pfad in der Unit anpassen).
+
+## Entwicklung
+
+```bash
+uv run pytest                    # Tests
+uv run python -m whisper_local   # Direkt starten
+```
+
+Plattform-spezifische Tests werden über `@pytest.mark.skipif(sys.platform != ...)` übersprungen.
+
+Architektur- und Designdokumente liegen unter [docs/superpowers/](docs/superpowers/).
+
+## Lizenz
+
+TBD