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

@@ -158,26 +158,28 @@ 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 clean up after pushing to the registry:
+**Fix:** Have Docker-build workflows prune dangling images after pushing:
 
 ```yaml
-      - name: Clean up build images on host
+      - name: Prune dangling images on host
         if: always()
-        run: |
+        run: docker image prune -f 2>/dev/null || true   # host-wide
-          IMAGE="registry.alwisp.com/${{ gitea.repository }}"
-          docker image rm -f "${IMAGE}:latest" 2>/dev/null || true
-          docker image prune -f 2>/dev/null || true   # removes dangling layers (host-wide)
 ```
 
-The image lives in the registry after `docker push`, so removing the local copy is
+`docker image prune -f` only removes **dangling** images — untagged leftovers from
-safe. `docker image prune -f` only removes **dangling** (untagged) images, not
+previous builds. It never touches tagged images (the freshly built `:latest`, base
-tagged base images, so rebuilds stay fast. Note it acts host-wide — fine on a
+images) or any image a container references, even a stopped one. This matters when
-dedicated runner host; be aware if the host runs unrelated build tooling.
+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.
 
-**One-time cleanup** of images left by earlier builds (run on the host):
+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 images --format '{{.Repository}}:{{.Tag}}' \
-  | grep '^registry.alwisp.com/' | xargs -r docker rmi -f
 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