[esp32_ble] Document connection_timeout configuration option (#5196)

* [esp32_ble] Document connection_timeout configuration option

* sanity

Author: bdraco

components/esp32_ble.rst

@@ -23,6 +23,7 @@ can run.
     esp32_ble:
       io_capability: keyboard_only
       disable_bt_logs: true  # Default, saves flash
+      connection_timeout: 20s  # Default, matches client timeout
 
 Configuration variables:
 ------------------------
@@ -48,6 +49,15 @@ Configuration variables:
 
     The ``disable_bt_logs`` option intelligently disables only the Bluetooth logging categories that are not required by your configuration. Each Bluetooth component registers the specific loggers it needs, and all unused loggers are automatically disabled during compilation. This includes loggers for Classic Bluetooth features (like RFCOMM, A2DP, HID) that are not used by ESPHome's BLE implementation.
 
+- **connection_timeout** (*Optional*, :ref:`config-time`): The maximum time to wait for a BLE connection to be established. Only available when using ESP-IDF framework. Defaults to ``20s``.
+
+  - Range: 10 to 180 seconds
+  - This timeout should align with the timeout used by your BLE client software to prevent connection slot waste
+
+.. note::
+
+    The ``connection_timeout`` option is particularly important when using ESPHome as a Bluetooth proxy. The default of 20 seconds matches the timeout used by aioesphomeapi and bleak-retry-connector. If a connection attempt times out on the client side but ESP-IDF continues trying to connect, the connection slot remains occupied and unavailable for new connections. Setting this to match your client timeout ensures connection slots are freed immediately when a connection fails.
+
 ``ble.disable`` Action
 -----------------------