From 94da5c8c5d6b7b592eaf885a50c8167a10513d9c Mon Sep 17 00:00:00 2001
From: "Danilo M." <danix@danix.xyz>
Date: Mon, 14 Sep 2026 19:05:40 +0200
Subject: docs: KDE Connect state protocol carries the pair flags

The pairing flow needs isPairRequested, isPairRequestedByPeer and the
verification key, so the polled line carries them; the key is only queried
with a pairing in flight. A failed daemon query is a non-zero exit with no
output, which is how the module tells it apart from a valid empty list.

Pairing failure comes from the kdeconnect-cli exit code, not the
pairingFailed signal, since there is no generic D-Bus module to watch it.
---
 .../specs/2026-09-14-kdeconnect-design.md          | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

diff --git a/docs/superpowers/specs/2026-09-14-kdeconnect-design.md b/docs/superpowers/specs/2026-09-14-kdeconnect-design.md
index a49a026..24b8041 100644
--- a/docs/superpowers/specs/2026-09-14-kdeconnect-design.md
+++ b/docs/superpowers/specs/2026-09-14-kdeconnect-design.md
@@ -68,15 +68,21 @@ properties and the battery properties, and prints one record per line,
 tab-separated:
 
 ```
-device<TAB><id><TAB><name><TAB><type><TAB><paired 0|1><TAB><reachable 0|1><TAB><charge or empty><TAB><charging 0|1>
+device<TAB><id><TAB><name><TAB><type><TAB><paired 0|1><TAB><reachable 0|1><TAB><pairRequested 0|1><TAB><pairRequestedByPeer 0|1><TAB><verificationKey or empty><TAB><charge or empty><TAB><charging 0|1>
 request<TAB><id>
 ```
 
 `request` lines come first, one per incoming pairing request. Tabs and newlines
 inside a device name are replaced with spaces, so a hostile name cannot break
-the protocol. Empty or unparseable `qdbus6` output is an error and produces no
-lines, never a plausible-looking empty list, the notmuch lesson from
-AGENTS.md: validate the shape rather than trusting the absence of output.
+the protocol. The verification key is only queried for a device with a pairing
+in flight, since it means nothing otherwise.
+
+A daemon query that fails is a non-zero exit with no output, so the module
+keeps the last list it had rather than rendering a clean empty one. A
+successful query that returns no devices is a valid empty list and also prints
+nothing, but exits zero; the exit code is the distinction. This is the notmuch
+lesson from AGENTS.md: validate the shape rather than trusting the absence of
+output.
 
 **The module, in `KdeConnectModule.qml`.** `alwaysActive: false`. A `Process`
 runs the script on a `SplitParser` and rebuilds a JS array of device objects
@@ -160,10 +166,10 @@ the dialog.
 
 Every action that fails raises `notify-send` with `--urgency=critical`, the
 pattern the vm and bluetooth modules use, because the drawer may have closed by
-the time the command returns. Pairing failure is read from
-`org.kde.kdeconnect.device.pairingFailed`, or from the pair button's process
-exit, and shown the same way. A failed `--mount` notifies rather than silently
-opening nothing.
+the time the command returns. Pairing failure is read from the `kdeconnect-cli`
+exit code and shown the same way; the `pairingFailed` signal is not watched,
+since there is no generic D-Bus module to subscribe with. A failed `--mount`
+notifies rather than silently opening nothing.
 
 ## Files
 
-- 
cgit v1.2.3