docs: README — PortManager architecture section

README.md

@@ -447,6 +447,30 @@ User (Telegram) → Webhook → Bot → Intent Detection
                           └─────────────────────┘
 ```
 
+### PortManager — Smart Port Lifecycle
+
+Handles HTTP server port binding with intelligent recovery, replacing the old probe→kill→exit pattern that caused crash-loops under systemd.
+
+```
+PortManager (EventEmitter)
+├── States: idle → probing → claiming → owned → releasing → failed
+├── Holder Detection (3 methods):
+│   ├── pidfile read (fast path)
+│   ├── ss -tlnp (system socket lookup)
+│   └── lsof -ti (fallback)
+├── Recovery:
+│   ├── Age-based kill strategy (young siblings waited, not killed)
+│   ├── Exponential backoff retry (5 attempts, 500ms → 5000ms)
+│   └── State events: stateChange, claimed, retry, failed
+└── API:
+    ├── claim(server) — acquire port with retry loop
+    ├── release() — cleanup on shutdown
+    ├── probe() — check if port is free
+    └── getStatus() — diagnostics for health checks
+```
+
+**File**: `src/bot/port-manager.js` | **Exposed via**: `bot.portManager`
+
 ---
 
 ## 📊 Feature Comparison