diff --git a/modules/pacman/README.md b/modules/pacman/README.md
index eb5ebaa8..7356c322 100644
--- a/modules/pacman/README.md
+++ b/modules/pacman/README.md
@@ -23,6 +23,19 @@ that seat (ADR 0207).
   list stays reflector's to write, not the mesh's.
 - **Cache cleaning.** The `pacman-contrib` package and `paccache.timer` running and enabled. Each
   week it keeps the last three versions of each package.
+- **The weekly upgrade (ADR 0477 clause 5, issue 1574).** `mesh-pacman-weekly-upgrade.timer` and its
+  oneshot service, placed whole in `/etc/systemd/system`. The timer fires every Saturday at 04:00 in the
+  node's local time, the same moment on every node (no random delay), and is `Persistent=true`: a node that
+  was off or asleep then upgrades at its next start. The service runs `/usr/bin/pacman -Syu --noconfirm`, the
+  same arguments `pacman_upgrade` starts (`UpgradeArgs` in the code; a manifest test holds the two together).
+  No other moment upgrades but a hand `pacman_upgrade`, and the mesh restarts no machine for an upgrade: a new
+  kernel waits for the next restart.
+  - **The outcome is the module's health.** The timer's resource asks `pacman_upgrade_health`: unhealthy,
+    naming the exit and the last `error:` line of the journal, when the last weekly upgrade failed; healthy
+    while it runs, after it passed, and before it ever ran. The controller raises the module's condition for
+    the node from it. A failed service stays failed until the next run, so the condition stands until an
+    upgrade passes, a hand `pacman_upgrade` does not clear it. A restart of the machine forgets the failed
+    state (the service manager's), so it is the condition raised before it that keeps the record.
 
 ## What it improves