diff --git a/crates/search/src/lib.rs b/crates/search/src/lib.rs
index 94e370f..c1f521c 100644
--- a/crates/search/src/lib.rs
+++ b/crates/search/src/lib.rs
@@ -1,4 +1,10 @@
 //! Full-text search over catalogue objects, backed by Meilisearch.
+//!
+//! This crate provides the search *capability* plus a `reindex_all` rebuild path.
+//! On-write index sync (calling `index_object`/`remove_object` after a catalogue
+//! mutation commits) is wired at the API/service layer (Plan 7+). Meilisearch is not
+//! transactional with Postgres, so the index is eventually consistent; `reindex_all`
+//! is the recovery path.
 
 use db::Db;
 use domain::{CatalogueObject, ObjectId};
@@ -140,7 +146,7 @@ impl SearchClient {
             .collect()
     }
 
-    /// Rebuild the whole index from the database. (build_document is filled in Task 2.)
+    /// Rebuild the whole index from the database (clears then re-adds all objects).
     pub async fn reindex_all(&self, db: &Db) -> Result<(), SearchError> {
         let index = self.client.index(&self.index_uid);