docs(updates): the module's README

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 32 insertions, 0 deletions

diff --git a/desktop/modules/updates/README.md b/desktop/modules/updates/README.md
new file mode 100644
index 0000000..59e96e8
--- /dev/null
+++ b/desktop/modules/updates/README.md
@@ -0,0 +1,32 @@
+# updates
+
+What to do next to bring this machine up to date, as a drawer page. Each
+pending update appears once, under the action it needs:
+
+- **Slackware upgrades / new / removed**: the slackpkg mirror's
+  `PACKAGES.TXT` and `ChangeLog.txt` against `/var/log/packages`, the
+  blacklist honoured. `upgrade-all`, `install-new` and `clean-system`.
+- **Upgrade here**: the binary repo (the `danix` slackpkg+ mirror) holds a
+  newer build than installed.
+- **Awaiting build**: the recipe (the user's `.info` or SBo's) has caught up
+  with upstream, the build has not.
+- **Upstream newer**: the recipe lags upstream; bump the `.info` or the
+  slackrepo hint.
+- **App updates**: AppImages and flatpaks behind upstream.
+
+`updatesctl` does all of it and prints JSON; the QML only draws. Upstream
+versions are nvchecker's `new_ver.json`; a result over 30 minutes old is
+followed by `updatesctl --refresh`, which runs nvchecker first. Nothing runs
+while the drawer is closed.
+
+**The mirror and the repo are on a hard NFS mount.** A read during a NAS
+outage blocks, so every NFS read is a `cat` child with a 5s timeout, and an
+unreachable source shows as a line under the section it empties.
+
+**SBo bumps through slackrepo hints are not visible here:** the hint files
+live on the build VM. Such a package stays under *Upstream newer* until its
+build lands in the repo.
+
+Tested with:
+
+    /usr/bin/python3 desktop/modules/updates/test_updatesctl.py