docs(desktop): document the network module

1 files changed, 33 insertions, 0 deletions

diff --git a/desktop/modules/network/README.md b/desktop/modules/network/README.md
new file mode 100644
index 0000000..fbf43e1
--- /dev/null
+++ b/desktop/modules/network/README.md
@@ -0,0 +1,33 @@
+# network
+
+Wired and wifi in one module, because a connected `eth0` must not mask the
+wifi state.
+
+The tile shows one line per active link. When both wired and wifi are up it
+shows both: the API exposes no route metric, so it does not guess which link
+carries traffic.
+
+The page lists managed wired devices, then a wifi radio switch and list. A
+row click connects; a secured network that is not yet known reveals an inline
+password field. Known networks offer Forget, the connected one Disconnect.
+
+## Service lifetime
+
+`alwaysActive: true`, and truthfully: the `Quickshell.Networking` backend
+pushes and there is no poll to gate. There is no `Service.qml`, unlike sound
+and vm, because there is no loop to own. Referencing `Networking` in
+`NetworkModule.qml` is what instantiates it at shell start.
+
+The backend is empty for about two seconds after launch and then fills. Every
+binding repaints when it arrives; nothing caches the first paint.
+
+## Not built
+
+Joining a hidden network. It would need a NetworkManager settings profile
+built from scratch, and `NMSettings` is not in QML scope (`typeof` is
+`undefined`), so there is no way to construct one from QML. Enterprise and
+802.1x networks are out for the same class of reason.
+
+Disconnect and forget failures. Neither backend exposes a failure signal for
+them, so a failure shows only as the list not changing. Noted rather than
+faked.