docs(desktop): document the network module

2 files changed, 37 insertions, 1 deletions

diff --git a/desktop/README.md b/desktop/README.md
index 29223b7..01ed1ce 100644
--- a/desktop/README.md
+++ b/desktop/README.md
@@ -24,6 +24,8 @@ the IPC layer rejects. The page-less grid entry is therefore the zero-argument
 ## The modules
 
     modules/sound/       output and input volume, the OSD, the player
+    modules/network/     wired and wifi, radio, scan, join, forget
+    modules/bluetooth/   adapter, scan, pair, connect, forget, trust
     modules/mail/        unread per account, threads, the watcher dot
     modules/vm/          libvirt state, live stats, snapshots
     modules/appearance/  a tile that opens the separate appearance shell
@@ -99,7 +101,8 @@ The top of the panel is an empty reserved area for the notification engine. It
 is an empty `Item` claiming the space, not a placeholder graphic, so the grid
 below it sits where it will sit once notifications arrive. The bottom is a
 fixed, never-scrolled `Flow` grid: three columns at 180px minimum, wrapping
-and adding rows up to a 3x3 ceiling for the modules that exist.
+and adding rows up to a 3x3 ceiling for the modules that exist, in the order
+Sound, Network, Bluetooth, Mail, Appearance, Machines.
 
 ## Hyprland and waybar
 
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.