diff --git a/README.md b/README.md
index 3d5db3a..4d1ee1c 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 | Defining header | Limit |
+|---|---|---:|
+| `kMaxPathKnots` | `motionkit/core/cartesian.hpp` | 65 |
+| `kMaxWaypoints` | `motionkit/core/cartesian.hpp` | 16 |
+| `kMaxObstacles` | `motionkit/core/collision.hpp` | 32 |
+
 ## Use it downstream
 
 ```cmake
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)