diff --git a/docs/PACKAGE_PLAN.md b/docs/PACKAGE_PLAN.md
new file mode 100644
index 0000000..88dfabb
--- /dev/null
+++ b/docs/PACKAGE_PLAN.md
@@ -0,0 +1,124 @@
+# Hermes-Houdini Bridge — Offizielle Houdini-Package-Integration
+
+## Recherche-Ergebnis
+
+Houdini hat seit Version 18 ein **offizielles Package-System** (JSON-basiert), das das alte `houdini.env` ablöst. Das ist der korrekte Weg, Plugins, Python Panels und Shelf-Tools zu installieren — ohne `scripts/python/` oder `toolbar/` manuell zu befüllen.
+
+### Wie Houdini Packages funktionieren
+
+```
+~/houdini21.0/
+├── packages/                          ← Houdini scannt dieses Verzeichnis beim Start
+│   └── hermes_houdini_bridge.json     ← Package-Descriptor (zeigt auf unser Plugin)
+│
+└── (keine manuellen scripts/python/, toolbar/, python_panels/ mehr nötig!)
+```
+
+**Package-Descriptor** (`hermes_houdini_bridge.json`):
+```json
+{
+    "hpath": "/pfad/zum/plugin",
+    "env": [
+        {"HHB_PATH": "/pfad/zum/plugin"}
+    ],
+    "load_package_once": true
+}
+```
+
+`hpath` prepended das Plugin-Verzeichnis in `$HOUDINI_PATH`. Houdini findet dann automatisch:
+- `scripts/python/` → Python-Module
+- `python_panels/` → `.pypanel` Interface-Dateien
+- `toolbar/` → Shelf-Tools
+- `help/` → Hilfedateien
+- `config/` → Konfiguration
+
+Keine manuelle Installation in `~/houdini21.0/` nötig — das Plugin lebt in einem eigenen Verzeichnis (z.B. Git-Repo).
+
+### Python Panel Integration
+
+Statt `exec(open(...).read()); show()` registriert man ein `.pypanel`-File:
+
+**`python_panels/hermes_bridge.pypanel`**:
+```json
+{
+    "interface": "hermes_bridge_panel",
+    "label": "Hermes Bridge",
+    "icon": "MISC_python",
+    "help_url": "https://git.niklashmotion.art/Hermes/hermes-houdini-bridge"
+}
+```
+
+Dann via Houdini-Menü: **Windows → Hermes Bridge** — kein Python-Shell-Pasten mehr nötig.
+
+### Vorteile gegenüber aktuellem Ansatz
+
+| Aktuell | Package-System |
+|---------|---------------|
+| `exec(open().read())` im Python Shell | Menü-Eintrag oder Shelf-Button |
+| Manuelles Kopieren nach `scripts/python/` | `git clone` + 1 JSON-Datei |
+| Kein Update-Mechanismus | `git pull` = Update |
+| Python-Panel nur per Code aufrufbar | Registriert im Windows-Menü |
+| Keine Versionierung im Houdini-Kontext | Package-Browser zeigt installierte Version |
+
+---
+
+## Ziel-Struktur
+
+```
+hermes-houdini-bridge/              ← Git-Repo, überall clonbar
+├── hermes_houdini_bridge.json      ← [NEU] Package-Descriptor (wird nach ~/houdini21.0/packages/ symlinked)
+├── python_panels/                  ← [NEU] Houdini findet Panels automatisch
+│   └── hermes_bridge.pypanel
+├── scripts/
+│   └── python/
+│       ├── hermes_bridge_panel.py  ← UI-Klasse (unverändert, aber mit PanelInterface)
+│       └── hermes_bridge_core.py   ← [NEU] Bridge-Logik als Modul (wiederverwendbar)
+├── toolbar/
+│   └── hermes_bridge.shelf         ← Shelf-Button (optional)
+├── help/                           ← [NEU] Doku-Integration
+│   └── index.html
+├── hermes/                         ← hhb Client (unverändert)
+│   └── bin/hhb
+├── examples/
+├── docs/
+└── README.md
+```
+
+---
+
+## Implementierungs-Schritte
+
+### Schritt 1: Package-Descriptor erstellen
+- `hermes_houdini_bridge.json` mit `hpath`, `env`, `load_package_once`
+- Optional: `enable`-Expression für Houdini-Version-Check
+
+### Schritt 2: Python Panel als Interface registrieren
+- `hermes_bridge.pypanel` erstellen
+- Panel-Klasse von `hou.PanelInterface` ableiten (statt `QWidget`)
+- `show()` läuft dann über `hou.PanelInterface.showPanel()`
+
+### Schritt 3: Bridge-Logik extrahieren
+- `hermes_bridge_core.py`: Port-Open/Close, Status-Check als sauberes Modul
+- Panel nutzt das Modul → testbar, wiederverwendbar
+
+### Schritt 4: Installation vereinfachen
+- `install.sh`: Symlink des `.json`-Descriptors nach `~/houdini21.0/packages/`
+- `git clone` = Installation, `git pull` = Update
+- Optional: `install.py` für Cross-Plattform (Windows/Mac)
+
+### Schritt 5: Auto-Start (optional)
+- `scripts/456.py`: Wird beim Houdini-Start ausgeführt
+- Kann automatisch den Port öffnen oder das Panel anzeigen
+
+### Schritt 6: Package-Browser-Support
+- `show: true` im JSON → erscheint im Houdini Package Browser
+- `recommends`/`requires` für Abhängigkeiten
+
+---
+
+## Offene Fragen
+
+1. **Repository-Pfad**: Soll das Git-Repo direkt als Package-Verzeichnis dienen, oder ein separates `package/`-Subdir?
+2. **Auto-Start**: Soll der Port automatisch beim Houdini-Start geöffnet werden?
+3. **Updates**: `git pull` reicht — oder brauchen wir einen expliziten Update-Button im Panel?
+4. **Multi-Session**: Mehrere Houdini-Instanzen auf verschiedenen Ports — relevant?