docs: add reconnection and error recovery docs

README.md

@@ -12,6 +12,7 @@ TUI Mumble client with voice support and push-to-talk.
 - Self-deafen toggle
 - Volume control (input/output gain)
 - Client certificate authentication
+- Auto-reconnect on network loss
 - Config hot-reload (F5)
 
 ## Key Bindings

docs/DEBUG.md

@@ -58,3 +58,26 @@ openssl rsa -in key.pem -check -noout
 - Verify server address and port
 - Check firewall allows outbound TCP/UDP to port 64738
 - Test with: `nc -zv <host> 64738`
+
+### Connection drops / reconnection
+
+When tuimble loses connection, it retries automatically with backoff.
+The chatlog shows each attempt:
+
+```
+✗ disconnected from server
+reconnecting in 2s (attempt 1/10)...
+✗ attempt 1: network error: [Errno 111] Connection refused
+reconnecting in 4s (attempt 2/10)...
+✓ connected as myname
+```
+
+Common causes:
+
+- **Server restart** — normal, reconnect succeeds when server is back
+- **Network loss** — check connectivity, tuimble retries automatically
+- **Auth timeout** — server may drop idle connections; reconnect handles this
+- **"rejected" with no retry** — wrong password or certificate issue
+
+If reconnection fails after 10 attempts, press `F5` to retry manually.
+Update `config.toml` if server details changed.

docs/USAGE.md

@@ -83,6 +83,21 @@ gain values.
 shown as warnings. Press `F5` again to confirm reconnect, or any
 other key to cancel.
 
+## Reconnection
+
+On unexpected disconnect (server restart, network loss), tuimble
+automatically retries with exponential backoff:
+
+- Initial delay: 2 seconds, doubling each attempt (2, 4, 8, 16, 30...)
+- Maximum delay: 30 seconds
+- Maximum attempts: 10
+
+The status bar shows `◐ reconnecting` during retry. If the server
+rejects authentication, retries stop immediately.
+
+After all attempts are exhausted, press `F5` to retry manually.
+`F5` also cancels an in-progress reconnect and starts a fresh attempt.
+
 ## Configuration
 
 See `~/.config/tuimble/config.toml`. All fields are optional;