Add docs for push notification feat

docs/push-notification.md

@@ -6,12 +6,121 @@ VibeTunnel provides real-time alerts for terminal events via native macOS notifi
 
 The **Session Monitor** is the core of the notification system. It observes terminal sessions for key events and dispatches them to the appropriate notification service (macOS or web).
 
-### Key Monitored Events
+### Notification Settings Explained
-- **Session Start/Exit**: Get notified when a terminal session begins or ends.
+
-- **Command Completion**: Alerts for long-running commands.
+When you enable notifications in VibeTunnel, you can choose which events to be notified about:
-- **Errors**: Notifications for commands that fail.
+
-- **Terminal Bell**: Triggered by programs sending a bell character (`^G`).
+#### 1. Session starts ✓
-- **Claude "Your Turn"**: A special notification when Claude AI finishes a response and is awaiting your input.
+- **Notification**: "Session Started" with the session name
+- **Triggers when**: A new terminal session is created
+- **Use case**: Know when someone starts using your shared terminal
+
+#### 2. Session ends ✓
+- **Notification**: "Session Ended" with the session name
+- **Shows exit code**: If the session crashed or exited abnormally
+- **Triggers when**: A terminal session closes
+- **Use case**: Monitor when sessions terminate, especially if unexpected
+
+#### 3. Commands complete (> 3 seconds) ✓
+- **Notification**: "Your Turn" with the command that finished
+- **Shows duration**: How long the command took to complete
+- **Triggers when**: Any command that runs for more than 3 seconds finishes
+- **Use case**: Get notified when long builds, tests, or scripts complete
+
+#### 4. Commands fail ✓
+- **Notification**: "Command Failed" with the failed command
+- **Shows exit code**: The specific error code returned
+- **Triggers when**: Any command returns a non-zero exit code
+- **Use case**: Immediately know when something goes wrong
+
+#### 5. Terminal bell (\u{0007}) ✓
+- **Notification**: "Terminal Bell" with the session name
+- **Triggers when**: A program outputs the bell character (ASCII 7/^G)
+- **Common sources**: vim alerts, IRC mentions, completion sounds
+- **Use case**: Get alerts from terminal programs that use the bell
+
+#### 6. Claude turn notifications ✓
+- **Notification**: "Your Turn" when Claude finishes responding
+- **Smart detection**: Monitors Claude CLI sessions automatically
+- **Triggers when**: Claude transitions from typing to waiting for input
+- **How it works**: 
+  - Detects sessions running Claude (by command or app name)
+  - Tracks when Claude stops outputting text
+  - Only notifies once per response (won't spam)
+- **Use case**: Know when Claude has finished its response and needs your input
+
+## Architecture
+
+### System Overview
+
+The notification system in VibeTunnel follows a layered architecture:
+
+```
+Terminal Events → Session Monitor → Event Processing → Notification Service → OS/Browser
+```
+
+### Key Components
+
+#### 1. Session Monitor (`SessionMonitor.swift`)
+- **Role**: Tracks all terminal sessions and their state changes
+- **Key responsibilities**:
+  - Monitors session lifecycle (start/exit)
+  - Tracks command execution and duration
+  - Detects Claude CLI activity transitions
+  - Filters events based on thresholds (e.g., 3-second rule)
+
+#### 2. Server Event System (`ServerEvent.swift`)
+- **Event types**: 
+  - `sessionStart`, `sessionExit`: Session lifecycle
+  - `commandFinished`, `commandError`: Command execution
+  - `bell`: Terminal bell character detection
+  - `claudeTurn`: Claude AI idle detection
+- **Event data**: Each event carries session ID, display name, duration, exit codes, etc.
+
+#### 3. Notification Service (`NotificationService.swift`)
+- **macOS integration**: Uses `UserNotifications` framework
+- **Event source**: Connects to server via SSE at `/api/events`
+- **Preference management**: Checks user settings before sending
+- **Permission handling**: Manages notification authorization
+
+#### 4. Configuration Manager (`ConfigManager.swift`)
+- **Settings storage**: Persists user notification preferences
+- **Default values**: All notification types enabled by default
+- **Real-time updates**: Changes take effect immediately
+
+### Event Flow
+
+1. **Terminal Activity**: User runs commands, sessions start/stop
+2. **Event Detection**: Session Monitor detects changes
+3. **Event Creation**: Creates typed `ServerEvent` objects
+4. **Filtering**: Checks user preferences and thresholds
+5. **Notification Dispatch**: Sends to OS notification center
+6. **User Interaction**: Shows native macOS notifications
+
+### Special Features
+
+#### Claude Detection Algorithm
+```swift
+// Detects Claude sessions by command or app name
+let isClaudeSession = session.command.contains("claude") || 
+                     session.app.lowercased().contains("claude")
+
+// Tracks activity state transitions
+if previousActive && !currentActive && !alreadyNotified {
+    // Claude went from typing to idle - send notification
+}
+```
+
+#### Command Duration Tracking
+- Only notifies for commands > 3 seconds
+- Tracks start time when command begins
+- Calculates duration on completion
+- Formats duration for display (e.g., "5 seconds", "2 minutes")
+
+#### Bell Character Detection
+- Terminal emulator detects ASCII 7 (`\u{0007}`)
+- Forwards bell events through WebSocket
+- Server converts to notification event
 
 ## Native macOS Notifications
 
@@ -27,6 +136,38 @@ For non-macOS clients or remote access, VibeTunnel supports web push notificatio
 - **Enable**: Click the notification icon in the web UI and grant browser permission.
 - **Technology**: Uses Service Workers and the Web Push API.
 
+### HTTPS Requirement
+
+⚠️ **Important**: Web push notifications require HTTPS to function. This is a security requirement enforced by all modern browsers.
+
+- **Local development**: Works on `http://localhost:4020` without HTTPS
+- **Remote access**: Requires HTTPS with a valid SSL certificate
+- **Why**: Service Workers (which power push notifications) only work on secure origins to prevent man-in-the-middle attacks
+
+### Enabling HTTPS for Remote Access
+
+If you need web push notifications when accessing VibeTunnel remotely, you'll need to serve it over HTTPS. Here are some solutions:
+
+#### Tailscale Serve (Recommended)
+[Tailscale Serve](https://tailscale.com/kb/1242/tailscale-serve) is an excellent solution for automatically creating HTTPS connections within your network:
+
+```bash
+# Install Tailscale and connect to your network
+# Then expose VibeTunnel with HTTPS:
+tailscale serve https / http://localhost:4020
+```
+
+Benefits:
+- Automatic HTTPS with valid certificates
+- Works within your Tailscale network
+- No port forwarding or firewall configuration needed
+- Push notifications will work for all devices on your Tailnet
+
+#### Other Options
+- **Ngrok**: Provides HTTPS tunnels but requires external exposure
+- **Cloudflare Tunnel**: Free HTTPS tunneling service
+- **Let's Encrypt**: For permanent HTTPS setup with your own domain
+
 ## Troubleshooting
 
 - **No Notifications**: Ensure they are enabled in both VibeTunnel settings and your OS/browser settings.