From e0a892ec97b0bd0a9aed244974fb4e5f70ccf3e7 Mon Sep 17 00:00:00 2001
From: Yiorgis Gozadinos <ggozadinos@gmail.com>
Date: Fri, 5 Jun 2026 12:14:14 +0300
Subject: [PATCH] Update embedding-drift docs for read-only opens

---
 docs/configuration/index.md | 2 +-
 docs/python.md              | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/configuration/index.md b/docs/configuration/index.md
index 20c01a2d..a18bca85 100644
--- a/docs/configuration/index.md
+++ b/docs/configuration/index.md
@@ -5,7 +5,7 @@ Configuration is done through YAML configuration files.
 !!! note
     haiku.rag enforces one hard rule on existing databases: the embedding `vector_dim` in your config must match the value stored in the db. A mismatch exits with `ConfigMismatchError` and you must **rebuild** to apply the change (see [Rebuild Database](../cli.md#rebuild-database)).
 
-    Changing only `provider` or `name` (e.g. switching from Ollama to vLLM serving the same model) is treated as soft drift: haiku.rag logs a one-time warning and updates the stored settings to match your config. Subsequent opens are silent. If the change was unintentional, revert your config to match the previously stored settings before running anything that depends on retrieval quality.
+    Opening a database never writes to it, so the stored embedding identity is left untouched. Changing only `provider` or `name` (e.g. switching from Ollama to vLLM serving the same model) is treated as soft drift: read-only opens log a warning and continue, while writable opens exit with `ConfigMismatchError`. Reconcile the stored identity with your config by running `haiku-rag rebuild --set-embedder` (see [Rebuild Database](../cli.md#rebuild-database)). If the change was unintentional, revert your config instead.
 
 ## Getting Started
 
diff --git a/docs/python.md b/docs/python.md
index 229599d7..f9d6f5e0 100644
--- a/docs/python.md
+++ b/docs/python.md
@@ -28,7 +28,7 @@ async with HaikuRAG("path/to/database.lancedb", read_only=True) as client:
     Databases must be explicitly created with `create=True` or via `haiku-rag init` before use. Operations on non-existent databases will raise `FileNotFoundError`.
 
 !!! note
-    Read-only mode is useful for safely accessing databases without risk of modification. It blocks all write operations and prevents settings from being saved.
+    Read-only mode is useful for safely accessing databases without risk of modification. It blocks all write operations and downgrades an embedding provider/name mismatch to a warning instead of raising `ConfigMismatchError`.
 
 !!! warning "Database Migrations"
     When upgrading haiku.rag to a version with schema changes, opening an existing database will raise `MigrationRequiredError`. Run `haiku-rag migrate` to apply pending migrations before using the database. See [CLI Database Management](cli.md#migrate-database) for details.