diff --git a/tests/e2e/CLAUDE.md b/tests/e2e/CLAUDE.md
index 2c9dadb0ff2..b155a1a7024 100644
--- a/tests/e2e/CLAUDE.md
+++ b/tests/e2e/CLAUDE.md
@@ -2,6 +2,22 @@
 
 Code-style rules for writing tests under `tests/e2e/`. The harness already encodes the plumbing; your job is the feature-specific behavior, not reinventing it. For what a complete test must do (the lifecycle contract, asserting both recorded state and enforced behavior) and how to run a suite, see `CONTRIBUTING.md` in this directory. Repo-wide conventions live in the root `CLAUDE.md`
 
+## Suite folders
+
+Each subdirectory under `tests/e2e/` is one suite, scoped to an endpoint family or behavior area. If you add a new folder, you must add a line here describing what kind of tests belong in it, so the layout stays self-describing. `gateway/` is the exception: it holds proxy configuration only and never tests
+
+- `llm_translation/` - LLM endpoint and provider-translation behavior: passthrough, custom pricing, OCR
+- `embeddings/` - the `/embeddings` endpoint across providers
+- `batches/` - the `/batches` endpoint (placeholder until the first test lands)
+- `realtime/` - realtime websocket sessions, including the pipecat audio path
+- `budgets/` - budget definition, enforcement, and reset windows (key, team, tag, soft, multi-window)
+- `spend_tracking/` - spend logging and cost attribution on `/spend/*`
+- `models_mgmt/` - model-management routes (add/update, tpm persistence)
+- `logging/` - logging-integration delivery (datadog and friends)
+- `security/` - secret handling and log-leak protection
+- `router/` - routing and reliability behavior (rate limits, fallbacks, cooldowns)
+- `gateway/` - proxy configuration only (`litellm-config.yml`); no tests
+
 ## Lay the pattern down in a class
 
 Keep the cases for one feature inside a class so the file reads as a spec for how that feature behaves in production. The class name says what is under test; each method is one behavior. Think of it as documenting the contract, with the rough intent being