diff --git a/crates/omnigraph/src/embedding.rs b/crates/omnigraph/src/embedding.rs
index 9c8aba3f..c7f5c62b 100644
--- a/crates/omnigraph/src/embedding.rs
+++ b/crates/omnigraph/src/embedding.rs
@@ -70,6 +70,24 @@ impl EmbeddingConfig {
     /// 5. provider api-key env (`OPENROUTER_API_KEY`/`OPENAI_API_KEY`, or `GEMINI_API_KEY`).
     pub fn from_env() -> Result<Self> {
         if env_flag("OMNIGRAPH_EMBEDDINGS_MOCK") {
+            // The mock flag deliberately wins (pinned by
+            // from_env_mock_flag_wins) — but overriding an EXPLICITLY
+            // configured real provider must be loud: mock vectors are
+            // indistinguishable from real ones (correct dimension, unit
+            // norm), so a leaked test env var would otherwise silently
+            // poison persisted embeds and query-time nearest().
+            if let Some(provider) = env_string("OMNIGRAPH_EMBED_PROVIDER")
+                && provider != "mock"
+            {
+                tracing::warn!(
+                    target: "omnigraph::embedding",
+                    overridden_provider = %provider,
+                    "OMNIGRAPH_EMBEDDINGS_MOCK is set and overrides the \
+                     explicitly configured OMNIGRAPH_EMBED_PROVIDER — all \
+                     embeddings in this process are deterministic mock \
+                     vectors, not real ones"
+                );
+            }
             return Ok(Self::mock());
         }
 
diff --git a/docs/user/search/embeddings.md b/docs/user/search/embeddings.md
index 2f5a55e5..dd5065eb 100644
--- a/docs/user/search/embeddings.md
+++ b/docs/user/search/embeddings.md
@@ -61,7 +61,7 @@ Direct (`--store`) access, embedded callers, and the offline
 | `OMNIGRAPH_EMBED_DEADLINE_MS` | total wall-clock budget for one embed call across all retries (default `60000`; `0` = unbounded) |
 | `OMNIGRAPH_EMBED_TIMEOUT_MS` | per-request HTTP timeout (default `30000`) |
 | `OMNIGRAPH_EMBED_RETRY_ATTEMPTS` / `OMNIGRAPH_EMBED_RETRY_BACKOFF_MS` | retry policy (defaults `4` / `200`) |
-| `OMNIGRAPH_EMBEDDINGS_MOCK` | set truthy to force the deterministic mock provider |
+| `OMNIGRAPH_EMBEDDINGS_MOCK` | set truthy to force the deterministic mock provider. Takes precedence over an explicitly configured `OMNIGRAPH_EMBED_PROVIDER` — the override is logged as a warning (`omnigraph::embedding` target), since mock vectors are indistinguishable from real ones (correct dimension, unit norm) |
 
 The default zero-config path is OpenRouter: set `OPENROUTER_API_KEY` and run. Reaching Gemini takes
 `OMNIGRAPH_EMBED_PROVIDER=gemini` plus `GEMINI_API_KEY`.