docs: add comprehensive project wiki for v1.0

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

droid-wiki/features/reconnect-and-shutdown.md

@@ -0,0 +1,57 @@
+# Reconnect and shutdown
+
+The connector is designed to recover from tunnel interruptions without dropping the SOCKS5 proxy.
+
+## Purpose
+
+Lab networks and development environments are unstable. The connector should tolerate listener restarts, network hiccups, and temporary failures without requiring manual intervention.
+
+## Reconnect behavior
+
+`run_reconnect_loop` in `src/tunnel.rs` continuously attempts to maintain a tunnel:
+
+1. Connect to the target address via TCP.
+2. Perform TLS handshake and server certificate verification.
+3. Send the HTTP auth request and wait for 200 OK.
+4. On success, create a `StreamMux`, publish it via the `watch::channel`, and run the framing loop.
+5. When the tunnel drops (framing task ends), log the disconnection and retry.
+
+### Backoff
+
+- Initial delay: 1 second
+- Exponential doubling up to a maximum of 30 seconds
+- Auth failures are terminal (the loop exits rather than retrying with a bad token)
+
+### SOCKS5 proxy during reconnect
+
+The SOCKS5 proxy stays bound. If a client connects while the tunnel is down, the proxy sees `mux_receiver` is `None` and rejects the connection with a warning log. Once the reconnect loop succeeds, new SOCKS5 requests work immediately.
+
+## Shutdown
+
+Both listener and connector handle graceful shutdown:
+
+- Unix: SIGINT or SIGTERM triggers shutdown via `tokio::signal::unix`.
+- Windows: Ctrl+C or Ctrl+Break triggers shutdown via `tokio::signal::ctrl_c`.
+
+### Listener shutdown
+
+1. The shutdown signal breaks the `tokio::select!` in `run_listener`.
+2. The TCP listener is dropped, releasing the bind port.
+3. The SOCKS5 proxy task (if any) is aborted.
+4. Active framing sessions end when their streams close.
+
+### Connector shutdown
+
+1. The shutdown signal breaks the `tokio::select!` in `run_socks5_proxy`.
+2. The SOCKS5 listener is dropped.
+3. The reconnect loop handle is aborted.
+4. Existing SOCKS5 connections receive EOF when their streams close.
+
+E2E tests `e2e_graceful_shutdown_listener` and `e2e_graceful_shutdown_connector` verify that ports are released within 3 seconds of abort.
+
+## Key source files
+
+| File | Purpose |
+| ---- | ------- |
+| `src/tunnel.rs` | `run_reconnect_loop`, `run_socks5_proxy`, `run_listener`, shutdown handling |
+| `src/signal.rs` | Cross-platform shutdown signal future |