From dd38117e79616cd6c3478df705aa3379c532ec2b Mon Sep 17 00:00:00 2001
From: alex <alex.camilo@gmail.com>
Date: Tue, 8 Sep 2026 05:13:31 -0400
Subject: [PATCH] CONTRIBUTING: cmake >=3.25 requirement and the uv workaround

---
 CONTRIBUTING.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8101fd0..c23ee58 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -12,3 +12,15 @@ provenance header. Everything else is written from understanding, in our own wor
 
 Real-data tests read `$SOTS_DATA_DIR` (the owner's installed copy) and must skip cleanly when unset.
 Run `tools/clean_room_check.sh` before committing.
+
+## Build toolchain gotcha
+
+The engine needs **CMake >= 3.25**. Debian/Ubuntu hosts ship 3.22, which fails with an
+unhelpful preset error. Either build on CT111 (which has 3.31), or locally:
+
+```sh
+uv run --with cmake --with ninja cmake --preset host -DPython3_EXECUTABLE=/usr/bin/python3
+```
+
+Pass `-DPython3_EXECUTABLE=/usr/bin/python3` explicitly — without it the fixture step
+captures uv's ephemeral interpreter, which disappears after the run.