diff --git a/CLAUDE.md b/CLAUDE.md
index 4fb54fd..0a33b53 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -111,6 +111,11 @@ does the new behaviour have a test?
 code changes (not on `requirements.txt` changes; restart the container/script after
 adding a dependency). Deploy only when a feature is complete and tested.
 
+**The full suite takes about 200 seconds** — longer than a two-minute command timeout, and a
+run killed mid-suite can leave `core_api_test` between migrations. Give `make test` at least
+five minutes, and confirm the test database is at head (`.venv/bin/alembic -x target=test
+current`) after an interrupted run.
+
 Run tests through the venv explicitly, to avoid environment mismatch:
 
 ```bash