Correct host image cleanup: prune dangling only, keep tagged :latest

The previous cleanup guidance removed the tagged :latest after push,
which deleted images still deployed on the Unraid host. Replace with
a dangling-only prune in both the troubleshooting doc and the sample
docker-build-push workflow; validated on jason/wfh (reclaimed 4.3GB).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/troubleshooting.md

@@ -143,3 +143,43 @@ This is an image build problem — the binary should always be present if the im
 ```bash
 ./scripts/verify-runtime.sh custom-gitea-runner:latest
 ```
+
+---
+
+## Orphan images piling up on the host (disk filling)
+
+**Symptom:** The Unraid Docker page (or `docker images`) shows a growing list of
+`(orphan image)` entries — both tagged (`registry.alwisp.com/<owner>/<repo>:latest`)
+and untagged (bare image IDs) — that nothing created intentionally.
+
+**Cause:** Jobs that run on the `host` label use the **host Docker daemon** via the
+mounted socket. Every `docker build` leaves its output image on the host, and each
+rebuild orphans the previous one (the moved tag leaves the old image dangling).
+Multi-stage build layers add more. Nothing removes them automatically, so they
+accumulate and consume the array.
+
+**Fix:** Have Docker-build workflows prune dangling images after pushing:
+
+```yaml
+      - name: Prune dangling images on host
+        if: always()
+        run: docker image prune -f 2>/dev/null || true   # host-wide
+```
+
+`docker image prune -f` only removes **dangling** images — untagged leftovers from
+previous builds. It never touches tagged images (the freshly built `:latest`, base
+images) or any image a container references, even a stopped one. This matters when
+the built `:latest` is itself deployed on the host (e.g. as an Unraid container):
+do **not** add `docker image rm "${IMAGE}:latest"` to the cleanup — that deletes
+the local tagged image out from under the deployment. The tagged image will still
+show as "(orphan image)" on the Unraid Docker page unless a template container
+uses it; that label is cosmetic, not a problem.
+
+Note the prune acts host-wide — fine on a dedicated runner host; be aware if the
+host runs unrelated build tooling.
+
+**One-time cleanup** of untagged leftovers from earlier builds (run on the host):
+
+```bash
+docker image prune -f
+```

test/sample-workflows/docker-build-push.yml

@@ -36,3 +36,11 @@ jobs:
             .
           docker push "${IMAGE}:latest"
           docker push "${IMAGE}:${{ gitea.sha }}"
+
+      # Dangling-only prune: removes untagged leftovers from previous builds.
+      # Never removes tagged images (the fresh :latest may be deployed on the
+      # host) or any image referenced by a container. See
+      # docs/troubleshooting.md "Orphan images piling up on the host".
+      - name: Prune dangling images on host
+        if: always()
+        run: docker image prune -f 2>/dev/null || true