plan NUMA interleave on multi-socket Linux

docs/ENVIRONMENT.md

@@ -43,7 +43,7 @@ Format: `VAR` — default — effect.
 | `URING` | `0` (off) | Linux-only queued expert I/O. `URING=1` implies `PIPE=1`, forces cold reads through io-wq (`IOSQE_ASYNC`), replaces blocking loader pthreads and spin waits with batched SQEs/CQEs, and batches `PILOT_REAL` loads on a separate ring. Use `DIRECT=1` for cold NVMe to avoid page-cache copy/readahead limits. Fails clearly if the kernel denies io_uring; incompatible with `COLI_MMAP=1`. |
 | `DIRECT` | `0` (off) | Use `O_DIRECT`/unbuffered reads for expert slabs. Helps sustained NVMe; keeps the zero-copy GPU path. |
 | `COLI_NO_OMP_TUNE` | off | **Kill-switch** for the OpenMP hot-thread tuning (`OMP_WAIT_POLICY=active` spin + proc-bind). Set `=1` when the CPU is mostly waiting on the GPU (Metal) so spin doesn't steal the shared power budget. |
-| `COLI_NUMA` | off (Linux only) | `COLI_NUMA=1` interleaves expert slabs across NUMA nodes via `mbind` (raw syscall, no libnuma). Helps multi-socket hosts (+7–40% expert matmul); silent no-op on single-node or non-Linux. |
+| `COLI_NUMA` | auto in generated plans on multi-socket Linux; otherwise off | `COLI_NUMA=1` selectively interleaves large expert and dense slabs across NUMA nodes via `mbind` (raw syscall, no libnuma). Helps multi-socket hosts (+7–40% expert matmul); silent no-op on single-node or non-Linux. Explicit `COLI_NUMA=0` overrides the generated plan. |
 | `MLOCK` | `-1` (auto: on for macOS) | Wire the streamed expert cache into physical RAM (`mlock`) to dodge the memory compressor. `0` off, `1` force. |
 | `CAP_RAISE` | `1` (on) | Let the engine raise the expert-cache cap above `topk` when RAM allows (bigger batches). `0` fixes the cap. |
 | `PREFETCH` | `0` | Prefetch depth for streamed experts. |

docs/benchmarks.md

@@ -116,8 +116,12 @@ can match an RTX 5090 on expert matmul ([#101](https://github.com/JustVugg/colib
 so **the GPU tier earns its VRAM only when the CPU is the weak link**. On
 multi-socket hosts, NUMA placement is a further lever: interleaving the resident
 weights across nodes measured **+13% (2-socket) and +40% (4-socket CPU-only)**
-([#82](https://github.com/JustVugg/colibri/issues/82)) — but never blanket-interleave
-a GPU host (measured 10× regression via the DMA staging pages).
+([#82](https://github.com/JustVugg/colibri/issues/82)). On a 2-socket Xeon Silver
+4510 host with 6× RTX 5090, selective `COLI_NUMA=1` raised effective CPU-expert
+bandwidth from **42.42 to 58.26/65.89 GB/s** and greedy decode from **7.66 to
+9.02/9.17 tok/s** (64 tokens, `TEMP=0 DRAFT=0`, byte-identical output). Do not
+blanket-interleave a GPU host: it also spreads DMA staging pages and has measured
+up to a 10× regression; generated plans enable only the selective slab policy.
 
 ## Quality benchmark