diff --git a/docs/hud-bridge-integration.md b/docs/hud-bridge-integration.md
new file mode 100644
index 0000000..e419fbe
--- /dev/null
+++ b/docs/hud-bridge-integration.md
@@ -0,0 +1,79 @@
+# Fox HUD — Electron Bridge Integration
+
+Änderungen in `~/fox` (Laravel App). Alle Punkte sind **optional** —
+ohne `window.foxBridge` (normaler Browser) läuft das HUD unverändert weiter.
+
+## 1. ESC → HUD schließen
+
+In `fox-hud.blade.php` oder dem HUD-JavaScript:
+
+```javascript
+document.addEventListener('keydown', (e) => {
+  if (e.key === 'Escape') window.foxBridge?.hideHud();
+});
+```
+
+## 2. Mac-Aktionen in onAction()
+
+Im bestehenden `onAction()` Handler am Anfang ergänzen:
+
+```javascript
+if (payload.action === 'spotify_play')  { await window.foxBridge?.macCommand('spotify_play'); return; }
+if (payload.action === 'spotify_pause') { await window.foxBridge?.macCommand('spotify_pause'); return; }
+if (payload.action === 'spotify_next')  { await window.foxBridge?.macCommand('spotify_next'); return; }
+if (payload.action === 'spotify_prev')  { await window.foxBridge?.macCommand('spotify_prev'); return; }
+if (payload.action === 'mail_open')     { await window.foxBridge?.macCommand('mail_open'); return; }
+if (payload.action === 'calendar_open') { await window.foxBridge?.macCommand('calendar_open'); return; }
+if (payload.action === 'notes_open')    { await window.foxBridge?.macCommand('notes_open'); return; }
+if (payload.action === 'volume_up')     { await window.foxBridge?.macCommand('volume_up'); return; }
+if (payload.action === 'volume_down')   { await window.foxBridge?.macCommand('volume_down'); return; }
+if (payload.action === 'screenshot')    { await window.foxBridge?.macCommand('screenshot'); return; }
+
+if (payload.action === 'open_url' && payload.url) {
+  await window.foxBridge?.macCommand('open:' + payload.url);
+  return;
+}
+if (payload.action === 'open_app' && payload.app) {
+  await window.foxBridge?.macCommand('app:' + payload.app);
+  return;
+}
+if (payload.action === 'save_desktop' && payload.filename) {
+  await window.foxBridge?.macCommand('save:' + JSON.stringify({
+    filename: payload.filename,
+    content: payload.content || '',
+  }));
+  return;
+}
+```
+
+## 3. Nachrichten senden (optional)
+
+Wenn Nachrichten direkt über Electron statt Livewire gesendet werden sollen:
+
+```javascript
+window.foxBridge?.sendMessage(text);
+```
+
+## 4. Laravel Route für /fox/message
+
+In `routes/api.php` oder `routes/web.php`:
+
+```php
+Route::post('/fox/message', function (\Illuminate\Http\Request $request) {
+    $text = $request->input('text', '');
+    if (empty(trim($text))) {
+        return response()->json(['error' => 'Kein Text'], 400);
+    }
+    $userMessage = app(\App\Services\FoxAgent::class)
+        ->recordUserMessage($text, ['source' => 'electron']);
+    dispatch(fn() => app(\App\Services\FoxAgent::class)
+        ->processUserMessage($userMessage));
+    return response()->json(['status' => 'ok']);
+})->middleware('api');
+```
+
+## 5. Electron erkennen
+
+```javascript
+const isElectron = typeof window.foxBridge !== 'undefined';
+```