diff --git a/AGENTS.md b/AGENTS.md
index e15485e9dc..4ec2eea26c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -75,7 +75,19 @@ cmake --build "l:\Telegram\tx64\out" --config Debug --target Telegram
 ### macOS
 - Requires Xcode
 - Dependencies: `../Libraries/local/Qt-*`
-- Set `QT` environment variable: `export QT=6.8`
+- First-time configure of a new `out/` tree: set the `QT` environment variable
+  to the Qt version this checkout actually has, for example `export QT=6.11.1`
+  when `../Libraries/local/Qt-6.11.1` is the installed one. The value names a
+  directory, so it is the checkout's version, not a constant.
+- Reconfiguring an existing `out/` tree: do **not** export `QT`. Run
+  `env -u QT cmake -S . -B out` instead. `cmake/external/qt/package.cmake`
+  writes an exported `QT` into the `qt_requested` cache entry with `FORCE`, so
+  it overwrites the version the tree was already configured with instead of
+  being ignored. A value that disagrees with the configured tree then fails the
+  regeneration, and the generated project keeps the source list it was last
+  generated with: newly added sources are never compiled — which surfaces later
+  as undefined-symbol link errors rather than as a configure error — and newly
+  added `.style` modules leave the generated `style_*.h` includes stale.
 
 ### Linux
 - Build dependencies in `../Libraries`