docs: update wiki for 0.2.11 (memory guidance, GPU troubleshooting)

FAQ.md

@@ -41,7 +41,9 @@ Yes. By default it processes every named person in your Immich library. Use `ONL
 
 ## What GPU is needed?
 
-Any NVIDIA GPU with CUDA 12.x support. The models (InsightFace Buffalo_L + SigLIP) fit comfortably in 4 GB VRAM. CPU mode works but is significantly slower.
+Any NVIDIA GPU with CUDA 12.x support. The models (InsightFace Buffalo_L + SigLIP) fit comfortably in 4 GB VRAM. CPU mode works but is significantly slower — typically tens of seconds per person instead of under a second on GPU.
+
+**CPU memory:** If running without a GPU, set a container memory limit of at least **2 GB** (`mem_limit: 2g`). The models use roughly 1–1.5 GB and thumbnails are processed in bounded batches, so usage stays flat even for large libraries. Without a limit a large person library can trigger an OOM kill and restart loop.
 
 ARM builds (linux/arm64) use CPU-only — CUDA is not available on ARM.
 

Setup.md

@@ -28,7 +28,7 @@ This is the base URL of your Frigate instance, e.g. `http://192.168.1.10:5000`.
 | `:latest` | amd64 + arm64 | CUDA 13.3 (amd64) | Requires NVIDIA Container Toolkit on amd64 |
 | `:cpu` | amd64 | None | ~2 GB smaller; use if you have no NVIDIA GPU |
 
-Use `:cpu` if your host has no NVIDIA GPU — it skips the entire CUDA stack and runs InsightFace on CPU.
+Use `:cpu` if your host has no NVIDIA GPU — it skips the entire CUDA stack and runs InsightFace on CPU. **Set a container memory limit of at least 2 GB** (`mem_limit: 2g`) — the embedding models need roughly 1–1.5 GB and thumbnails are batched, but without a limit an OOM kill will restart the container mid-run.
 
 ## 4. Deploy with Docker Compose
 
@@ -80,7 +80,7 @@ On the first run, winnow downloads the embedding models (~1–2 GB) from Hugging
 
 ---
 
-## 5. Scheduling
+## 6. Scheduling
 
 `CRON_SCHEDULE` controls both the run schedule and container lifetime:
 

Troubleshooting.md

@@ -63,10 +63,34 @@ Use the `:cpu` image tag (`ghcr.io/sudolulo/winnow:cpu`) which omits the CUDA ba
 
 Everything works on CPU but embedding computation is slower — typically tens of seconds per person instead of under a second on GPU.
 
-If you have a GPU but it's not being used:
-- Confirm the NVIDIA container toolkit is installed: `docker run --rm --gpus all nvidia/cuda:13.3.0-base-ubuntu22.04 nvidia-smi`
-- Confirm the `deploy.resources.reservations.devices` block is present in `compose.yml`
-- Set `VERBOSE=true` and check the logs — winnow logs which ONNX execution providers are active at startup (should show `CUDAExecutionProvider`)
+**Memory:** CPU mode requires more host RAM than GPU mode. Set a minimum container memory limit of **2 GB** (`mem_limit: 2g` in compose). If you have a large library — hundreds of images per person — allow more. Thumbnails are processed in bounded batches of 32 so peak RAM stays flat regardless of library size, but the embedding models themselves use roughly 1–1.5 GB.
+
+---
+
+## GPU not being used / "No GPU execution provider found"
+
+If you have a GPU and the container is running but winnow reports no GPU provider:
+
+1. **Confirm the GPU device is visible** inside the container:
+   ```bash
+   docker exec winnow nvidia-smi
+   ```
+   If this fails, the container doesn't have GPU access — check the `deploy.resources.reservations.devices` block in `compose.yml` and that the NVIDIA container toolkit is installed on the host.
+
+2. **Check which ONNX providers are available**:
+   ```bash
+   docker exec winnow /app/.venv/bin/python3 -c \
+     "import onnxruntime as ort; ort.preload_dlls(cuda=True, cudnn=True); print(ort.get_available_providers())"
+   ```
+   Expected (GPU working): `['CUDAExecutionProvider', 'CPUExecutionProvider', ...]`  
+   GPU not working: `['AzureExecutionProvider', 'CPUExecutionProvider']` — only CPU providers listed.
+
+3. **If only CPU providers appear even though `nvidia-smi` works**, you may be running an image older than 0.2.11. A packaging bug in 0.2.10 caused the CPU `onnxruntime` package to silently overwrite `onnxruntime-gpu`, removing GPU support without any error. Update to `:latest` to fix it:
+   ```bash
+   docker compose pull && docker compose up -d
+   ```
+
+4. **Set `VERBOSE=true`** and check startup logs — winnow logs `ONNX providers available: [...]` at DEBUG level on every start.
 
 ---