#208 README: document the ip/ subfolder (IP-Adapter reference-image bins)

README.md

@@ -59,3 +59,26 @@ Scheduler: **EulerDiscrete** (deterministic), trailing spacing, epsilon predicti
 guidance_scale 0. Runs via the license-clean `libsdxl_qnn_driver` in the TokForge app.
 
 See `manifest.json` for the per-arch file list, sizes, and md5 checksums.
+
+## Reference-image (IP-Adapter / identity-preserving) — `ip/` subfolder
+
+The `ip/` subfolder ships the **IP-Adapter context bins** for identity-preserving
+(reference-image) rendering. When a reference photo is attached, the driver swaps the base
+`unet.bin` for the **IP-baked UNet** (`unet_ip.bin`) and renders **with** the reference's identity;
+no-reference renders are unchanged.
+
+| File | What |
+|------|------|
+| `ip/v75/unet_ip.bin` | IP-Adapter UNet context bin, Hexagon **V75** (device-verified) |
+| `ip/v81/unet_ip.bin` | IP-Adapter UNet context bin, Hexagon **V81** (compiled from the same DLC; on-device validation pending) |
+| `ip/model_w8a16.dlc` | arch-agnostic W8A16 QAIRT 2.40 DLC the per-arch `unet_ip.bin` are compiled from |
+| `ip/ip_kv_proj_weights.npz` | 70× `to_k_ip`/`to_v_ip` Linear weights for the CPU IP side (`k_0..k_69`, `v_0..v_69`, `inner[70]`, `heads[70]`) |
+
+The bins are **identity-agnostic** and safe to publish: the 70 cross-attention `k_ip`/`v_ip` are
+**render-constant** inputs computed on the **CPU per render** (reference → CLIP-ViT-H penultimate →
+plus-face Resampler → 70× `to_k_ip`/`to_v_ip`), so no likeness is baked into the published files.
+The CLIP-ViT-H encoder + plus-face adapter weights are the standard public
+[h94/IP-Adapter](https://huggingface.co/h94/IP-Adapter) SDXL plus-face files and are not re-hosted
+here. The app downloads `unet_ip.bin` as an **optional** bundle file (paired in each set's `files`
+map); its absence degrades to a plain (no-identity) render and never fails the install. IO contract,
+checksums, and per-arch details are in `manifest.json` under the top-level `ip` block.