1 files changed, 38 insertions, 0 deletions
diff --git a/desktop/modules/bluetooth/README.md b/desktop/modules/bluetooth/README.md
new file mode 100644
index 0000000..2de634a
--- /dev/null
+++ b/desktop/modules/bluetooth/README.md
@@ -0,0 +1,38 @@
+# bluetooth
+
+The adapter, its devices, and pairing, in one module.
+
+The tile names the connected device, or a count when several, `No devices`
+when the adapter is on and idle, `Off` when it is down.
+
+The page carries the adapter power switch, a visible toggle, a scan toggle,
+then the connected devices, the paired ones, and anything found while
+scanning. A paired device offers Connect, Trust and Forget; an unpaired one
+offers Pair.
+
+## Pairing is the one shell-out
+
+Quickshell ships no BlueZ pairing agent and no generic D-Bus module, so a
+device that requires a passkey or PIN confirmation has no way to prompt from
+QML. `Pairing.qml` runs `bluetoothctl --timeout 20 pair <address>`, whose own
+agent handles the prompt.
+
+Everything else is native `Quickshell.Bluetooth`. The cost is that
+`bluetoothctl` is the ceiling: a device it cannot auto-confirm times out and
+the error shows, rather than pairing. `Pairing.qml` carries a `ponytail:`
+comment naming that and the upgrade path.
+
+## Not built
+
+Connecting and forgetting report no failure signal in the BlueZ binding; only
+pairing does, through the `bluetoothctl` exit code. A connect that fails
+shows only as the device staying unconnected.
+
+## Service lifetime
+
+`alwaysActive: true`, and truthfully: the BlueZ backend pushes, there is no
+poll to gate, and there is no `Service.qml`. Referencing `Bluetooth` in
+`BluetoothModule.qml` instantiates it at shell start.
+
+The adapter is null and the device list empty for about two seconds after
+launch. Every access navigates safely; nothing caches the first paint.