feat(runner): add always-on systemd unit + wire into runbook step 5

System service running as the desktop user (already in docker group); starts
at boot, auto-restarts, auto-claims queued jobs. WorkingDirectory under $HOME
because snap Docker can't read build contexts outside home. README step 5 now
covers binary install, registration, and enabling the service.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

README.md

@@ -127,18 +127,31 @@ Then:
 - Create a **Personal Access Token** with **`write:package`** scope
   (`Settings → Applications`). The automatic Actions token CANNOT push packages.
 
-### 5. Register the desktop runner
+### 5. Register the desktop runner (always-on)
-On the **home desktop** (has Docker + ssh):
+On the **home desktop** (already has Docker + is in the `docker` group). Put the
+binary in place, register in a home-dir working folder (snap Docker needs the
+build context under `$HOME`), then install the systemd unit so it survives
+reboots and auto-claims jobs:
 ```sh
-# Get a registration token: Forgejo → Site Admin → Actions → Runners → Create
+sudo install -m 0755 forgejo-runner /usr/local/bin/forgejo-runner
+mkdir -p ~/forgejo-runner && cp runner/config.yml ~/forgejo-runner/
+cd ~/forgejo-runner
+
+# Registration token: Forgejo → Site Admin → Actions → Runners → Create
 forgejo-runner register --no-interactive \
   --instance https://git.joshbairstow.com \
   --token <REGISTRATION_TOKEN> \
-  --name desktop --labels desktop:host
+  --name desktop --labels desktop:host        # ':host' => run jobs on the host, use host Docker
-forgejo-runner daemon --config /path/to/jb-infra/runner/config.yml
+
+sudo cp runner/forgejo-runner.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now forgejo-runner
+systemctl status forgejo-runner               # expect active (running); runner shows green in Forgejo
 ```
-(For always-on, wrap the daemon in a systemd user service.) See
+The `:host` label is what lets the `docker build` step work (the job runs on the
-[`runner/config.yml`](runner/config.yml).
+host using its Docker, not in a socket-less container). See
+[`runner/config.yml`](runner/config.yml) and
+[`runner/forgejo-runner.service`](runner/forgejo-runner.service).
 
 ### 6. Wire the jb-website repo
 In the `jb-website` repo settings on Forgejo (`Settings → Actions`):

runner/forgejo-runner.service

@@ -0,0 +1,47 @@
+# ----------------------------------------------------------------------------
+# forgejo-runner.service — always-on Forgejo Actions runner on the home desktop.
+#
+# System service: starts at boot, no login required. Runs as your user (already
+# in the `docker` group) so host-execution jobs can run `docker build`.
+#
+# Install:
+#   sudo install -m 0755 forgejo-runner /usr/local/bin/forgejo-runner   # the binary
+#   mkdir -p ~/forgejo-runner && cp config.yml ~/forgejo-runner/
+#   cd ~/forgejo-runner
+#   forgejo-runner register --no-interactive \
+#       --instance https://git.joshbairstow.com \
+#       --token <REGISTRATION_TOKEN> --name desktop --labels desktop:host
+#   #  ^ writes ./.runner (credentials) into ~/forgejo-runner
+#   sudo cp forgejo-runner.service /etc/systemd/system/
+#   #  (edit User=/paths below if your username differs)
+#   sudo systemctl daemon-reload
+#   sudo systemctl enable --now forgejo-runner
+#   systemctl status forgejo-runner          # expect: active (running)
+#   journalctl -u forgejo-runner -f          # watch it claim jobs
+#
+# Why WorkingDirectory is under $HOME: this machine's Docker is snap-based, and
+# snap confinement blocks the daemon from reading build contexts outside the
+# user's home — so the checkout/build must happen there, not in /opt.
+# ----------------------------------------------------------------------------
+
+[Unit]
+Description=Forgejo Actions runner (jb CI)
+Documentation=https://forgejo.org/docs/latest/admin/actions/runner-installation/
+After=network-online.target snap.docker.dockerd.service docker.service
+Wants=network-online.target
+# Disable the start-rate limiter so it keeps retrying until Docker is ready at boot.
+StartLimitIntervalSec=0
+
+[Service]
+Type=simple
+User=joshbairstow
+SupplementaryGroups=docker
+WorkingDirectory=/home/joshbairstow/forgejo-runner
+Environment=HOME=/home/joshbairstow
+Environment=PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/snap/bin
+ExecStart=/usr/local/bin/forgejo-runner daemon --config /home/joshbairstow/forgejo-runner/config.yml
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target