From 351b980b4228db8c100af12efb12e27d00796c14 Mon Sep 17 00:00:00 2001
From: Username <user@mymx.me>
Date: Tue, 24 Feb 2026 14:54:40 +0100
Subject: [PATCH] docs: add reconnection and error recovery docs

---
 README.md     |  1 +
 docs/DEBUG.md | 23 +++++++++++++++++++++++
 docs/USAGE.md | 15 +++++++++++++++
 3 files changed, 39 insertions(+)

diff --git a/README.md b/README.md
index 4ea9227..e0d3eca 100644
--- a/README.md
+++ b/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
diff --git a/docs/DEBUG.md b/docs/DEBUG.md
index a69ed6d..11e0875 100644
--- a/docs/DEBUG.md
+++ b/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.
diff --git a/docs/USAGE.md b/docs/USAGE.md
index 00acab2..24a7f85 100644
--- a/docs/USAGE.md
+++ b/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;