docs(desktop): document the kdeconnect module

Records that the phone-to-PC clipboard is the daemon's plugin and not the
indicator's, so removing the indicator does not break it, and that polling
stops when the drawer closes.

1 files changed, 45 insertions, 0 deletions

diff --git a/desktop/modules/kdeconnect/README.md b/desktop/modules/kdeconnect/README.md
new file mode 100644
index 0000000..b92cb2d
--- /dev/null
+++ b/desktop/modules/kdeconnect/README.md
@@ -0,0 +1,45 @@
+# kdeconnect
+
+KDE Connect devices in the drawer, replacing the `kdeconnect-indicator` tray
+icon. Status, battery, pairing, ping, clipboard send, file share, refresh and
+filesystem mount.
+
+The tile names the reachable device and its battery when the battery plugin
+reports one, a count when several are reachable, `Offline` when paired devices
+exist but none is reachable, and `No devices` otherwise.
+
+The page lists paired devices, then any discovered unpaired ones, with a
+refresh control at the top and an incoming-pairing banner. A reachable row
+offers Ring, Clipboard, Share and Mount; a paired row offers Unpair; an
+unpaired reachable one offers Pair.
+
+## The daemon does the clipboard
+
+Quickshell 0.3.1 has no generic D-Bus module, only `Quickshell.DBusMenu`, so
+nothing here binds to `org.kde.kdeconnect`. State is read by `qdbus6` and
+actions run through `kdeconnect-cli`, with `qdbus6` for pair accept and reject,
+which the CLI does not expose.
+
+The phone-to-PC clipboard is not this module's. `kdeconnectd` loads the
+clipboard plugin and writes the system clipboard itself (through
+`KSystemClipboard`), and the indicator was never part of that path, so removing
+the indicator does not break it. If it fails on Hyprland it is the compositor
+refusing `set_selection` from a daemon with no keyboard focus, which no code
+here can fix.
+
+## Service lifetime
+
+`alwaysActive: false`. There is no push to listen to, so the state is polled
+every 5s while the drawer is open. The tile is created when the drawer panel
+loads and destroyed when it unloads, and it is the tile that turns polling on
+and off, so nothing polls while the drawer is closed. A consequence: an
+incoming pairing request that arrives while the drawer is closed is not noticed
+until it is opened, though the daemon keeps the request.
+
+## Not built
+
+SMS, notification forwarding, remote input, media control, presenter mode,
+find-this-device and remote commands. The daemon supports them and the
+indicator surfaced some; this module does not. Pairing failure comes from the
+`kdeconnect-cli` exit code, not the `pairingFailed` signal, since there is no
+D-Bus module to subscribe with.