docs: update for 0.2.10 — cpu tag, scheduling modes, VERBOSE, GPU troubleshooting, 401 error

FAQ.md

@@ -60,4 +60,4 @@ docker compose pull
 docker compose up -d
 ```
 
-The `latest` tag on GHCR tracks the `main` branch. Pinning to a version tag (e.g. `ghcr.io/sudolulo/winnow:v0.2.0`) is recommended for stability.
+The `latest` and `cpu` tags on GHCR track the `main` branch. Pinning to a specific version is recommended for stability, but winnow doesn't publish versioned image tags — `latest` / `cpu` are the stable release tags, and `dev` / `dev-cpu` are pre-release.

Setup.md

@@ -21,7 +21,16 @@ This is the base URL of your Frigate instance, e.g. `http://192.168.1.10:5000`.
 
 ---
 
-## 3. Deploy with Docker Compose
+## 3. Choose an image tag
+
+| Tag | Arch | GPU | Notes |
+| :-- | :-- | :-- | :-- |
+| `: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.
+
+## 4. Deploy with Docker Compose
 
 Copy [`compose.yml`](../compose.yml) and [`.env.example`](../.env.example) to a directory on your host:
 
@@ -65,7 +74,7 @@ docker compose logs -f winnow
 
 ---
 
-## 4. First run
+## 5. First run
 
 On the first run, winnow downloads the embedding models (~1–2 GB) from HuggingFace and InsightFace. This happens once — subsequent runs use the cached models from your mounted volume and start immediately.
 
@@ -73,13 +82,21 @@ On the first run, winnow downloads the embedding models (~1–2 GB) from Hugging
 
 ## 5. Scheduling
 
-Set `CRON_SCHEDULE` in your `.env` to keep winnow running on a schedule:
+`CRON_SCHEDULE` controls both the run schedule and container lifetime:
+
+| `CRON_SCHEDULE` | Behaviour |
+| :-- | :-- |
+| *(unset)* | Run once on startup, then exit |
+| *(empty string)* | Stay alive; trigger manually with `docker exec -it winnow winnow` |
+| Cron expression | Run on startup, then repeat on schedule |
+
+Example — every Sunday at 3 AM:
 
 ```
-CRON_SCHEDULE=0 3 * * 0   # Every Sunday at 3 AM
+CRON_SCHEDULE=0 3 * * 0
 ```
 
-Without `CRON_SCHEDULE`, the container runs once and exits.
+In scheduled mode the process (and loaded models) stays resident between runs, so each subsequent run starts immediately without re-loading models.
 
 ---
 
@@ -89,7 +106,15 @@ To enable GPU acceleration, include the `deploy` block in `compose.yml` (already
 
 ```bash
 # Verify GPU is accessible to Docker
-docker run --rm --gpus all nvidia/cuda:12.9.2-base-ubuntu22.04 nvidia-smi
+docker run --rm --gpus all nvidia/cuda:13.3.0-base-ubuntu22.04 nvidia-smi
 ```
 
-CPU mode works without any GPU setup — set `FORCE_CPU=true` to disable GPU explicitly.
+CPU mode works without any GPU setup — set `FORCE_CPU=true` to disable GPU explicitly, or use the `:cpu` image tag which omits the CUDA base entirely (~2 GB smaller).
+
+## Debugging
+
+Set `VERBOSE=true` in your `.env` to enable DEBUG-level output on the console. The log file (`/app/winnow.log`) always captures DEBUG regardless of this setting — useful when diagnosing issues without a shell into the container:
+
+```bash
+docker exec winnow cat /app/winnow.log
+```

Troubleshooting.md

@@ -13,6 +13,24 @@ Common causes:
 
 ---
 
+## "Immich API key is invalid or expired (401 Unauthorized)"
+
+Your API key has been revoked or expired. Generate a new one in Immich → **Account Settings** → **API Keys** and update `API_KEY` in your `.env`.
+
+---
+
+## Getting more log detail
+
+Set `VERBOSE=true` in `.env` (or pass `-e VERBOSE=true`) to enable DEBUG-level output on the console. Useful for tracing exactly which images are being fetched, filtered, and selected.
+
+The log file at `/app/winnow.log` always captures DEBUG regardless of `VERBOSE`:
+
+```bash
+docker exec winnow cat /app/winnow.log
+```
+
+---
+
 ## "No people found" / nothing processed
 
 - Make sure Immich has completed face recognition and you have named people in your library
@@ -41,11 +59,14 @@ winnow downloads InsightFace and HuggingFace (SigLIP) models on first run.
 
 ## Running on CPU (no GPU)
 
-Set `FORCE_CPU=true`. Everything works but embedding computation is slower — expect several minutes per person instead of seconds.
+Use the `:cpu` image tag (`ghcr.io/sudolulo/winnow:cpu`) which omits the CUDA base entirely. Or set `FORCE_CPU=true` with `:latest` to disable GPU at runtime.
+
+Everything works on CPU but embedding computation is slower — expect several minutes per person instead of seconds.
 
 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:12.9.2-base-ubuntu22.04 nvidia-smi`
+- 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`)
 
 ---