diff --git a/deployments/PERFORMANCE.md b/deployments/PERFORMANCE.md
index bf38f99a..0cdb76f6 100644
--- a/deployments/PERFORMANCE.md
+++ b/deployments/PERFORMANCE.md
@@ -259,6 +259,12 @@ ROUTES — top 3 by total
   requests are being rejected before any DB work — usually unauthenticated load
   (see the auth note in Step 2).
 
+> **Statement truncation.** Query statements are normalized and truncated to a
+> fixed prefix (2000 chars) before logging, so queries that differ only past the
+> cutoff — large `IN (...)` lists, big CTEs — collapse into a single row in the
+> `QUERIES` report. If a row's `count` looks suspiciously high or its statement
+> ends in `…`, it may be several distinct queries merged together.
+
 ---
 
 ## Comparing variants (data volume / params)
diff --git a/deployments/api/src/stitch/api/observability/query_timing.py b/deployments/api/src/stitch/api/observability/query_timing.py
index 6909069f..8668d17e 100644
--- a/deployments/api/src/stitch/api/observability/query_timing.py
+++ b/deployments/api/src/stitch/api/observability/query_timing.py
@@ -30,6 +30,10 @@
 
 
 def _normalize_statement(statement: str, max_chars: int) -> str:
+    # NB: statements longer than max_chars are truncated to a shared prefix, so
+    # queries that differ only past the cutoff (large IN (...) lists, big CTEs)
+    # collapse into one group in the analyzer. Acceptable tradeoff; documented in
+    # deployments/PERFORMANCE.md so users aren't surprised by merged rows.
     collapsed = _WHITESPACE.sub(" ", statement).strip()
     if len(collapsed) > max_chars:
         return collapsed[:max_chars] + "…"
diff --git a/docker-compose.local.yml b/docker-compose.local.yml
index 0ff70d32..68399351 100644
--- a/docker-compose.local.yml
+++ b/docker-compose.local.yml
@@ -36,7 +36,7 @@ services:
     command: ["alembic", "-c", "deployments/api/alembic.ini", "revision", "--autogenerate", "-m", "baseline"]
     # On-demand only (via `make alembic-autogenerate`). Must NOT be in the
     # `tools`/`full` profiles, or it autogenerates a blank revision on every
-    # `make api-dev` / `reboot-docker` startup.
+    # `make api-dev` / `make reboot-docker` startup.
     profiles: ["alembic-generate"]
     restart: "no"