docs: troubleshooting entry for host orphan-image accumulation

Document why host-label builds leave orphan images on the Docker host and the
post-push cleanup + one-time prune pattern.

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

docs/troubleshooting.md

@@ -143,3 +143,41 @@ 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 clean up after pushing to the registry:
+
+```yaml
+      - name: Clean up build images on host
+        if: always()
+        run: |
+          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
+safe. `docker image prune -f` only removes **dangling** (untagged) images, not
+tagged base images, so rebuilds stay fast. Note it acts host-wide — fine on a
+dedicated runner host; be aware if the host runs unrelated build tooling.
+
+**One-time cleanup** of images left by 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
+```