Initial commit: local SDXL image generation on Intel Arc B580

Containerized SDXL-base generation targeting a 12GB Arc B580 under
Slackware. The container carries the Intel Level Zero runtime the host
distro does not package; the fp16-fix VAE removes the fp32 upcast that
would otherwise OOM at decode.

- imggen: host wrapper (GPU passthrough, /out bind-mount, model cache)
- generate.py: in-container XPU pipeline, scope-bounded to SDXL base
- Dockerfile: pinned to the known-good torch-XPU / diffusers stack
- README.md, CLAUDE.md: rationale, limits, and version-pinning notes

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

1 files changed, 48 insertions, 0 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..3c19091
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,48 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+Local SDXL-base image generation on an Intel Arc B580 (12GB) under Slackware. Three files:
+`imggen` (host bash wrapper) → `docker run` → `generate.py` (in-container, XPU). README.md carries
+the full rationale and VRAM measurements; read it before changing behavior.
+
+## Build and run
+
+```
+docker build -t imggen:local .        # image tag is hardcoded as imggen:local in the wrapper
+cp imggen ~/bin/imggen && chmod +x ~/bin/imggen
+imggen "a prompt" --steps 30 --seed 42 -o out.png -n "blurry"
+```
+
+No test suite, no lint config. Verification is running `imggen` end to end and checking the PNG.
+
+## Architecture constraints (the whole point of the project)
+
+- **12GB VRAM is the hard limit.** Stock SDXL fp16 OOMs at VAE decode because diffusers upcasts
+  the VAE to fp32. The fix is the fp16-fix VAE (`madebyollin/sdxl-vae-fp16-fix`, hardcoded in
+  `generate.py`). This one swap is why the pipeline fits. Do not remove it. Peak VRAM in the
+  working config is 9.07 GB.
+- **Scope is deliberately bounded:** SDXL base, single 1024x1024 image, 25 steps, no refiner,
+  no Flux, no batching. Refiner/Flux/heavy work is explicitly out of scope and belongs on a
+  RunPod endpoint, not here. Don't add them "to be helpful."
+- **XPU only.** `build_pipe()` fails loud (`sys.exit(2)`) if `torch.xpu` is unavailable rather
+  than falling back to CPU (which would be minutes per image). Keep that behavior.
+
+## Version pinning is load-bearing
+
+The Dockerfile pins EXACT versions (torch 2.12.1+xpu, diffusers 0.39.0, transformers 5.13.0,
+etc.) captured from the known-good container. XPU-for-diffusion is young and fast-moving. Never
+`pip install -U` or loosen a pin casually. torch comes from the Intel XPU wheel index
+(`download.pytorch.org/whl/xpu`); everything else from PyPI. If you rebuild with newer versions,
+keep the old Dockerfile in git to revert.
+
+## Container boundaries
+
+- `imggen` bind-mounts host `$IMGGEN_OUT` (default `~/imggen-out`) → `/out`, and
+  `$IMGGEN_CACHE` (default `~/.cache/imggen-models`) → `/models`. `HF_HOME=/models` so the
+  ~7.5GB weights download once. Output paths in `generate.py` are all under `/out`.
+- All wrapper args pass straight through to `generate.py` argparse. Adding a CLI flag means
+  editing `generate.py` only; the wrapper needs no change.
+- GPU passthrough is `--device /dev/dri`.