feat: stage the wallpaper on homepage and notify on completion

bin/udt-homepage replaces install.sh's inline scp. It stages custom.css
and the current wallpaper, keeping the wallpaper's own extension, then
raises a desktop notification with the root commands that install both
and point settings.yaml at the new background. Plain root commands, not
sudo: the login user on that host has no sudo rights.

udt-accent starts it detached on every run, so it follows a wallpaper
change (wallp) as well as a scheme switch (install.sh) without holding
either up when the host is unreachable.

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

4 files changed, 69 insertions, 22 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 73f6b2c..490932d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -97,12 +97,16 @@ that block is templated.
 Signal, Discord and Spotify cannot be consumers: they ship closed bundles with
 no user-CSS hook, and patching a signed app bundle breaks on every update.
 
-The homepage stylesheet is the one output that leaves this machine.
-`install.sh` scp's it to `homepage:hp-stage/`, with a five second timeout and a
-warning rather than a failure when the host is down, so installing the local
-theme still works off that network. It stages only: `/opt/homepage/config` is
-root-owned, and the final copy plus a `systemctl restart homepage` is a manual
-step the script prints. homepage's `settings.yaml` must keep `color: gray`, the
+The homepage stylesheet and the wallpaper are the outputs that leave this
+machine. `bin/udt-homepage` scp's both to `homepage:hp-stage/`, the wallpaper
+as `background.<ext>` with its own extension, and the finish command rewrites
+`settings.yaml`'s `background.image` line to that name.
+`udt-accent` starts it detached on every run, so it follows both a wallpaper
+change and a scheme switch without holding either up; a five second timeout
+and silence when the host is down keep it harmless off that network. It stages
+only: `/opt/homepage` is root-owned, and the final copy plus a `systemctl
+restart homepage` is a manual step, whose command arrives as a desktop
+notification. homepage's `settings.yaml` must keep `color: gray`, the
 theme class the generated CSS targets. The last is
 imported by `udt-accent`, which is why its accent table follows the scheme.
 
diff --git a/bin/udt-accent b/bin/udt-accent
index 6462aae..c0b6529 100755
--- a/bin/udt-accent
+++ b/bin/udt-accent
@@ -463,6 +463,12 @@ def main(image):
     # Hyprland only rereads its config on request, and may not be running.
     subprocess.run(["hyprctl", "reload"], capture_output=True, check=False)
 
+    # The dashboard host. Detached, because wallp runs this synchronously and
+    # an unreachable host would hold the wallpaper change for the scp timeout.
+    subprocess.Popen([Path(__file__).resolve().parent / "udt-homepage"],
+                     stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
+                     stderr=subprocess.DEVNULL, start_new_session=True)
+
     before, after = hue_neighbours(name)
     print(f"{name} {ACCENTS[name]} (border: {before} .. {name} .. {after})")
 
diff --git a/bin/udt-homepage b/bin/udt-homepage
new file mode 100755
index 0000000..7be5d16
--- /dev/null
+++ b/bin/udt-homepage
@@ -0,0 +1,53 @@
+#!/bin/bash
+# udt-homepage: stage the homepage stylesheet and wallpaper on the dashboard host.
+# Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+# Licensed under the GNU General Public License v2 only.
+#
+# Staged, not installed: /opt/homepage is root-owned and this script does not
+# hold root there, so it copies into ~/hp-stage/ and a notification carries
+# the command that finishes the job.
+#
+# udt-accent starts this detached on every run, which covers both a wallpaper
+# change (wallp) and a scheme switch (install.sh). Never slow and never loud
+# when the host is away: a laptop off that network gets a short connect
+# timeout and no notification, since there is nothing for the user to do.
+
+repo="$(dirname "$(readlink -f "$0")")/.."
+css="$repo/templates/homepage/custom.css"
+wall="$HOME/.cache/udt/wpaper"
+opts=(-q -o ConnectTimeout=5 -o BatchMode=yes)
+
+[ -f "$css" ] && [ -e "$wall" ] || exit 0
+
+# The wallpaper keeps its own extension, so settings.yaml has to follow it: the
+# finish command rewrites its background.image line to match. The extension
+# ends up in a command the user runs as root, so only known image types pass.
+real="$(readlink -f "$wall")"
+ext="${real##*.}"
+ext="${ext,,}"
+case "$ext" in
+    png|jpg|jpeg|webp|gif|avif) ;;
+    *) echo "homepage: $real is not a known image type, skipped" >&2; exit 1 ;;
+esac
+bg="background.$ext"
+
+scp "${opts[@]}" "$css" homepage:hp-stage/custom.css &&
+    scp "${opts[@]}" "$real" "homepage:hp-stage/$bg" || {
+    echo "homepage: unreachable, skipped" >&2
+    exit 1
+}
+
+# Root commands, not sudo: the login user there has no sudo rights. Root's ~
+# is not the staging directory, so it is named through the ssh login user,
+# which ssh -G resolves from the config without connecting.
+stage="~$(ssh -G homepage 2>/dev/null | awk '/^user /{print $2}')/hp-stage"
+finish="cp $stage/custom.css /opt/homepage/config/
+cp $stage/$bg /opt/homepage/public/images/
+sed -i 's|/images/background\.[a-z]*|/images/$bg|' /opt/homepage/config/settings.yaml
+systemctl restart homepage"
+echo "homepage: staged, finish as root on homepage:"
+echo "$finish"
+command -v notify-send >/dev/null 2>&1 &&
+    notify-send -a udt "homepage: theme staged" "As root on homepage:
+$finish"
+exit 0
diff --git a/install.sh b/install.sh
index 6fba4db..7b68ad6 100755
--- a/install.sh
+++ b/install.sh
@@ -175,22 +175,6 @@ ln -sfn "$gtk_theme/gtk-4.0" "$HOME/.config/gtk-4.0/theme"
 # already listed there. Skipped silently when neither app is installed.
 "$repo/bin/udt-appthemes" || true
 
-# Stage the homepage stylesheet on the dashboard host. Staged, not installed:
-# /opt/homepage/config is root-owned and this script does not hold root there.
-# Never fatal, and never slow: a laptop away from that network must still be
-# able to install the local theme, so the connect timeout is short and any
-# failure is a warning.
-if command -v scp >/dev/null 2>&1; then
-    if scp -q -o ConnectTimeout=5 -o BatchMode=yes \
-           "$repo/templates/homepage/custom.css" \
-           homepage:hp-stage/custom.css 2>/dev/null; then
-        echo "homepage: staged custom.css ($scheme)"
-        echo "  finish with: ssh homepage 'sudo cp ~/hp-stage/custom.css /opt/homepage/config/custom.css'"
-    else
-        echo "homepage: unreachable, skipped" >&2
-    fi
-fi
-
 # conky reads one config at startup and never rereads it, so the generated file
 # has to be in place before the restart below.
 #