diff --git a/README.md b/README.md
new file mode 100644
index 0000000..96e3f4a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,97 @@
+# HA starten — Tailscale + Home Assistant launcher
+
+Minimalistische Android app die in één tik **Tailscale VPN aanzet** en daarna de
+**Home Assistant** app opent. Ideaal als je HA alleen bereikbaar is via de
+Tailscale MagicDNS-naam (bijv. `https://homeassistant.tail…ts.net`): buiten je
+thuisnetwerk moet eerst de tunnel omhoog, pas dan kan de HA-app verbinden.
+
+## Waarom
+
+- HA-app staat louter op de **tailnet-URL** (geen LAN-IP), dus de tunnel moet
+  actief zijn vóór HA een verbinding kan maken.
+- `getLaunchIntentForPackage`/broadcasts overnemen in Tasker was fragiel en
+  verward (accessibility-service, package-visibility, exit-condities). Eén
+  knop-app is simpeler en betrouwbaarder.
+
+## Werking
+
+Op basis van de [officiële Tailscale Android intents](https://github.com/tailscale/tailscale-android/pull/87):
+
+| Knop | BroadCast intent |
+|---|---|
+| **VPN aan + HA openen** | `com.tailscale.ipn.CONNECT_VPN` |
+| **VPN uit** (sluit daarna de app) | `com.tailscale.ipn.DISCONNECT_VPN` |
+
+Beide gericht op `com.tailscale.ipn/.IPNReceiver` (Broadcast Receiver). De app
+wacht ~3 s na CONNECT (Tailscale-handshake) voordat hij de HA-app start.
+
+### Knoppen
+- Verbind-knop bovenaan, uit-knop onderaan — ver uit elkaar om fouttappen te
+  voorkomen.
+
+## Vereisten
+
+- Android 8.0+ (minSdk 26, targetSdk 34)
+- **Tailscale** app geïnstalleerd en ingelogd
+- **Home Assistant** Companion app geïnstalleerd (`io.homeassistant.companion.android`)
+
+> Batterijoptimalisatie uitzetten voor Tailscale werkt het betrouwbaarst;
+> direct na een telefoon-reboot kan de broadcast-intent kort falen (startlag van
+> Tailscale's `IPNReceiver`).
+
+## Bouwen
+
+De app is bewust Gradle-vrij — een handmatige `aapt2`/`javac`/`d8`-pipeline op een
+machine met Android SDK build-tools + platform 34:
+
+```bash
+SDK=/opt/homebrew/share/android-commandlinetools
+BT=$SDK/build-tools/34.0.0
+AJ=$SDK/platforms/android-34/android.jar
+
+mkdir -p classes dex out out/res
+
+# 1. resources compilen + linken
+aapt2 compile --dir res -o out/res/
+aapt2 link -o out/app-unsigned.apk -I "$AJ" \
+  --manifest AndroidManifest.xml \
+  --min-sdk-version 26 --target-sdk-version 34 \
+  --version-code 1 --version-name 1.0 \
+  $(find out/res -name '*.flat')
+
+# 2. Java -> dex (gebruik een recente d8; oudere build-tools-d8 faalt op inner classes)
+javac --release 8 -classpath "$AJ" -d classes src/nl/eddy/tailscalehalauncher/MainActivity.java
+d8 --release --lib "$AJ" --output dex classes/nl/eddy/tailscalehalauncher/*.class
+
+# 3. dex in apk, align, sign
+(cd out && zip -qj app-unsigned.apk ../dex/classes.dex)
+zipalign -f 4 out/app-unsigned.apk out/app-aligned.apk
+apksigner sign --ks debug.keystore --ks-pass pass:android \
+  --out out/app.apk out/app-aligned.apk
+```
+
+Resultaat: `out/app.apk`.
+
+## Installeren
+
+```bash
+adb install -r out/app.apk
+```
+
+of kopieer `out/app.apk` naar de telefoon en tik hem aan (sideload; "onbekende
+bronnen" toestaan).
+
+## Projectstructuur
+
+```
+AndroidManifest.xml                     # manifest + <queries> voor HA-zichtbaarheid
+src/nl/eddy/tailscalehalauncher/        # MainActivity (enige bron)
+res/mipmap-{mdpi..xxxhdpi}/ic_launcher.png  # launcher-icoon (HA-blauw + dikke L)
+```
+
+## Aanpassen
+
+- **Wachttijd VPN → HA-start:** `WAIT_FOR_VPN_MS` in `MainActivity.java`.
+- **Andere target-app:** `HA_PKG` in `MainActivity.java`.
+- **Icoon regenereren:** de `res/mipmap-*/ic_launcher.png` worden uit een 512px-PNG
+  gemaakt (`Image.LANCZOS` downscale); pas ze direct aan als je er een wilt wijzigen.
\ No newline at end of file