From ad142a52a651a643ce70773fb5fcbcc4b8b235b9 Mon Sep 17 00:00:00 2001
From: nightcityblade <nightcityblade@gmail.com>
Date: Sat, 12 Sep 2026 23:09:06 +0800
Subject: [PATCH 1/2] docs: document compile-time limits

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

diff --git a/README.md b/README.md
index 3d5db3a..23351a8 100644
--- a/README.md
+++ b/README.md
@@ -63,6 +63,18 @@ scripts/format.sh
 It pins clang-format 18; a different major version formats differently and CI
 will reject the result.
 
+### Compile-time limits
+
+motionkit uses fixed-size storage to keep its core algorithms allocation-free.
+The following public limits are intentionally fixed and cannot currently be
+overridden through CMake:
+
+| Constant | Limit |
+|---|---:|
+| `kMaxPathKnots` | 65 |
+| `kMaxWaypoints` | 16 |
+| `kMaxObstacles` | 32 |
+
 ## Use it downstream
 
 ```cmake

From a98fc5f31cca0c7998b079e618fea789bffd5116 Mon Sep 17 00:00:00 2001
From: nightcityblade <nightcityblade@gmail.com>
Date: Sun, 13 Sep 2026 23:05:50 +0800
Subject: [PATCH 2/2] test: keep documented limits in sync

---
 README.md                       | 12 ++++++------
 tests/CMakeLists.txt            |  6 ++++++
 tests/check_readme_limits.cmake | 19 +++++++++++++++++++
 3 files changed, 31 insertions(+), 6 deletions(-)
 create mode 100644 tests/check_readme_limits.cmake

diff --git a/README.md b/README.md
index 23351a8..4d1ee1c 100644
--- a/README.md
+++ b/README.md
@@ -63,17 +63,17 @@ scripts/format.sh
 It pins clang-format 18; a different major version formats differently and CI
 will reject the result.
 
-### Compile-time limits
+## Compile-time limits
 
 motionkit uses fixed-size storage to keep its core algorithms allocation-free.
 The following public limits are intentionally fixed and cannot currently be
 overridden through CMake:
 
-| Constant | Limit |
-|---|---:|
-| `kMaxPathKnots` | 65 |
-| `kMaxWaypoints` | 16 |
-| `kMaxObstacles` | 32 |
+| Constant | Defining header | Limit |
+|---|---|---:|
+| `kMaxPathKnots` | `motionkit/core/cartesian.hpp` | 65 |
+| `kMaxWaypoints` | `motionkit/core/cartesian.hpp` | 16 |
+| `kMaxObstacles` | `motionkit/core/collision.hpp` | 32 |
 
 ## Use it downstream
 
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index 4a32384..d7d8048 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -10,6 +10,12 @@ FetchContent_MakeAvailable(googletest)
 
 include(GoogleTest)
 
+add_test(NAME readme_limits
+  COMMAND ${CMAKE_COMMAND}
+    -DPROJECT_SOURCE_DIR=${PROJECT_SOURCE_DIR}
+    -P ${CMAKE_CURRENT_SOURCE_DIR}/check_readme_limits.cmake)
+set_tests_properties(readme_limits PROPERTIES LABELS unit)
+
 add_executable(motionkit_tests
   test_vec3.cpp
   test_so3.cpp
diff --git a/tests/check_readme_limits.cmake b/tests/check_readme_limits.cmake
new file mode 100644
index 0000000..baed08a
--- /dev/null
+++ b/tests/check_readme_limits.cmake
@@ -0,0 +1,19 @@
+file(READ "${PROJECT_SOURCE_DIR}/README.md" readme)
+
+function(check_limit name header)
+  file(READ "${PROJECT_SOURCE_DIR}/include/${header}" declaration)
+  string(REGEX MATCH "${name} = ([0-9]+)" match "${declaration}")
+  if(NOT match)
+    message(FATAL_ERROR "Could not find ${name} in ${header}")
+  endif()
+  set(value "${CMAKE_MATCH_1}")
+  string(FIND "${readme}" "| `${name}` | `${header}` | ${value} |" documented)
+  if(documented EQUAL -1)
+    message(FATAL_ERROR
+      "README limit for ${name} does not match ${header} (${value})")
+  endif()
+endfunction()
+
+check_limit(kMaxPathKnots motionkit/core/cartesian.hpp)
+check_limit(kMaxWaypoints motionkit/core/cartesian.hpp)
+check_limit(kMaxObstacles motionkit/core/collision.hpp)