diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9ae0f10
--- /dev/null
+++ b/README.md
@@ -0,0 +1,117 @@
+# jviewer – AMI JViewer unter Linux zum Laufen bringen
+
+Startet den alten AMI JViewer (Java-Web-Start-KVM-Client, z.B. für Intel
+S2600WTTR mit AMI BMC) unter einem aktuellen Linux, obwohl weder ein
+passendes Java 8 noch eine funktionierende `javaws`/IcedTea-Web-Konfiguration
+vorinstalliert sind.
+
+Für einen kompletten Neubau ohne Java/IcedTea-Web-Altlasten siehe das parallel
+laufende Projekt `jviewer2` (moderner Nachbau des KVM-Protokolls, in Arbeit).
+
+## Ausgangslage / Warum das nötig ist
+
+- BMC liefert eine alte `jviewer.jnlp` mit `<all-permissions/>` und
+  `<nativelib>`-Einträgen, die von aktuellem Java-Web-Start/IcedTea-Web so
+  nicht mehr akzeptiert werden
+- BMC-Zertifikat ist alt und abgelaufen (RSA 1024, SHA1, abgelaufen seit 2016);
+  TLS1.2 funktioniert, TLS1.0 nicht
+- Auf aktuellen Distributionen gibt es kein passendes OpenJDK-8-Paket mehr
+- `JViewer.jar` ist unsigniert, das Manifest deklariert aber
+  `Permissions: all-permissions` — moderne IcedTea-Web-Versionen erzwingen
+  dafür einen restriktiven Sandbox-Modus, der weder Sockets zum
+  KVM-Redirection-Port (7578) noch das Laden der nativen CD/Floppy-Wrapper-
+  Bibliotheken erlaubt
+
+## Was das Script macht
+
+`start-jviewer.sh` löst das automatisiert, ohne etwas am System zu verändern
+(alles bleibt im Projektordner):
+
+1. Lädt bei Bedarf ein eigenes **Temurin-Java-8-JDK** herunter (nicht nur
+   JRE — `jarsigner`/`keytool` werden für Schritt 4 gebraucht) nach
+   `java8/`, unabhängig von einer eventuell vorhandenen Systeminstallation
+2. Nutzt das im System installierte `javaws` (Paket `icedtea-netx`), erzwingt
+   aber über `JAVA_HOME`/`PATH` das eigene Java 8
+3. Baut eine komplett isolierte IcedTea-Web-Umgebung unter `runtime-home/`
+   (eigenes `XDG_CONFIG_HOME`/`XDG_CACHE_HOME`, eigene
+   `deployment.properties`) — die System-IcedTea-Web-Konfiguration bleibt
+   unangetastet
+4. Patcht die JNLP minimal (`patch_jviewer.py`): nur `<nativelib>` wird zu
+   `<jar>` umbenannt (inkompatibel mit angeforderten `all-permissions`,
+   unabhängig von Signierung); `<security>`/`<all-permissions>` und
+   `<codebase>` bleiben unverändert
+5. Lässt `javaws` in einem ersten, absichtlich fehlschlagenden Lauf die
+   Original-Jars von der BMC in den eigenen Cache laden
+6. **Signiert die gecachten Jars selbst** mit einem einmalig erzeugten,
+   selbstsignierten Zertifikat (`signing/jviewer.jks`) und trägt das
+   Zertifikat automatisch in IcedTea-Webs Trusted-Certs-Store ein — dadurch
+   bekommt die Anwendung reguläre `AllPermission` statt Sandbox, ohne dass
+   ein Zertifikats-Dialog manuell bestätigt werden muss
+7. Startet `javaws` ein zweites Mal mit `-Xoffline`, damit die gepatchten/
+   signierten Cache-Dateien verwendet werden, statt erneut unsignierte
+   Originale von der BMC zu laden
+
+## Voraussetzungen
+
+- Linux mit `bash`, `wget`, `unzip`
+- Paket `icedtea-netx` installiert (liefert `javaws`):
+  ```
+  sudo apt install icedtea-netx
+  ```
+- Netzwerkzugriff zur BMC sowie zu `api.adoptium.net` (für den einmaligen
+  Java-8-Download)
+
+## Benutzung
+
+```
+./start-jviewer.sh -c jviewer.jnlp
+```
+
+Das Script ist pfadunabhängig — es kann aus einem beliebigen Ordner heraus
+aufgerufen werden, solange `patch_jviewer.py` im selben Verzeichnis liegt.
+Der Pfad zur `.jnlp`-Datei kann relativ (zum Skript-Ordner) oder absolut
+angegeben werden.
+
+Alle heruntergeladenen/erzeugten Daten landen im Skript-Ordner:
+
+| Ordner/Datei | Inhalt |
+|---|---|
+| `java8/` | heruntergeladenes Temurin-JDK-8 |
+| `runtime-home/` | isolierte IcedTea-Web-Config und -Cache |
+| `signing/` | selbstsigniertes Schlüsselpaar (`jviewer.jks`) für die Jar-Signierung |
+| `fixed-<name>.jnlp` | gepatchte JNLP, die tatsächlich gestartet wird |
+| `jviewer-debug.log` | vollständiges `javaws`-Log des letzten (zweiten) Laufs |
+| `jviewer-debug-pass1.log` | Log des ersten (Cache-Befüll-)Laufs |
+
+`java8/` und `signing/` bleiben zwischen Läufen erhalten (kein erneuter
+Download/keine neue Signatur nötig). `runtime-home/.cache` wird bei jedem
+Lauf frisch geleert, `runtime-home/.config` bleibt erhalten (falls doch
+einmal ein Zertifikats-Dialog manuell bestätigt werden muss, bleibt diese
+Entscheidung über Neustarts hinweg erhalten).
+
+## Troubleshooting
+
+- **`javaws wurde nicht gefunden`**: `sudo apt install icedtea-netx`
+- **`FEHLER: JNLP wurde NICHT gepatcht (nativelib noch vorhanden)`**: prüfen,
+  ob `patch_jviewer.py` im selben Ordner wie `start-jviewer.sh` liegt und ob
+  die JNLP-Datei tatsächlich `<nativelib>`-Tags enthält (Struktur kann sich
+  je nach BMC-Firmware leicht unterscheiden)
+- **`FEHLER: Nach Lauf 1 wurden keine Jars im Cache gefunden`**: BMC nicht
+  erreichbar, oder TLS-Handshake schlägt fehl — `jviewer-debug-pass1.log`
+  prüfen
+- **Immer noch `access denied`/`SocketPermission`-Fehler im 2. Lauf**: prüfen,
+  ob im Log `verified as SIGNED_OK` und `App already has trusted publisher:
+  true` steht. Falls nicht, kann es sein, dass die verwendete IcedTea-Web-
+  Version einen anderen Pfad/Passwort für den Trusted-Certs-Store erwartet
+  als `runtime-home/.config/icedtea-web/security/trusted.certs` /
+  `changeit` — in diesem Fall erscheint ein GUI-Dialog, in dem einmalig
+  "diesem Zertifikat immer vertrauen" bestätigt werden muss; das bleibt dank
+  Punkt oben danach dauerhaft erhalten
+
+## Bekannte Einschränkungen
+
+- Virtuelle Medien (CD/Floppy-Redirection über `com.ami.iusb.CDROMRedir`)
+  wurden nicht gesondert getestet; der Kern-Anwendungsfall (Bildschirm/
+  Tastatur/Maus per KVM) funktioniert
+- Der zweite `javaws`-Lauf öffnet ein GUI-Fenster (Swing) — für den Einsatz
+  ist also eine grafische Sitzung (lokal oder X11-Forwarding) nötig