diff --git a/haiku_rag_slim/haiku/rag/capabilities/_base.py b/haiku_rag_slim/haiku/rag/capabilities/_base.py
index ef55c3f3..538e5f5b 100644
--- a/haiku_rag_slim/haiku/rag/capabilities/_base.py
+++ b/haiku_rag_slim/haiku/rag/capabilities/_base.py
@@ -554,16 +554,14 @@ class RAGCapabilityBase[StateT: EvidenceState](AbstractCapability[Any]):
         if missing:
             async with self.rag_lock:
                 rag = await self._ensure_rag()
-                # A chunk id says nothing about which database holds it, so the
-                # fallback looks through everything the question covers — and
-                # nothing it does not.
+                # A chunk id names no database, so the fallback covers exactly
+                # what the question covers, and nothing it does not.
                 lookups = await rag.clients_covering(self.state.sources)
                 synthetic: list[SearchResult] = []
                 documents: dict[tuple[str | None, str], Any] = {}
                 for chunk_id in missing:
-                    # Every database that has it, not the first: taking the first
-                    # would attribute the answer to one of them without ever
-                    # seeing that another had it too.
+                    # Every database that has it, not the first: the first
+                    # alone cannot see that another had it too.
                     holders = await all_found(
                         lookups, lambda owner: owner.get_chunk_by_id(chunk_id)
                     )
diff --git a/haiku_rag_slim/haiku/rag/chat/__init__.py b/haiku_rag_slim/haiku/rag/chat/__init__.py
index 51817129..d256543b 100644
--- a/haiku_rag_slim/haiku/rag/chat/__init__.py
+++ b/haiku_rag_slim/haiku/rag/chat/__init__.py
@@ -42,9 +42,9 @@ def run_chat(
         config.qa.model = model_config
         config.analysis.model = model_config
 
-    # The capabilities read the databases the scope covers, not whatever the
-    # configuration happens to name: `--db PATH` would otherwise leave them on
-    # the default database, and `--db-name NAME` on the whole set.
+    # The capabilities read the databases the scope covers, not what the
+    # configuration names: a `--db PATH` selection is outside the
+    # configuration, and a `--db-name NAME` selection is narrower than it.
     if scope.covers_multiple:
         capability_config, capability_db_path = config, None
     else:
diff --git a/haiku_rag_slim/haiku/rag/chat/app.py b/haiku_rag_slim/haiku/rag/chat/app.py
index 5465c532..442dd3bb 100644
--- a/haiku_rag_slim/haiku/rag/chat/app.py
+++ b/haiku_rag_slim/haiku/rag/chat/app.py
@@ -148,9 +148,8 @@ class ChatApp(App):
         # a client whose __aenter__ failed.
         await client.__aenter__()
         self.client = client
-        # The capabilities read through this one, rather than each opening its
-        # own: it is already the databases they were built for, and lending it
-        # means one connection per database instead of one per capability.
+        # Lent to the capabilities: already the databases they were built for,
+        # and one connection per database however many capabilities read it.
         for capability in self._capabilities:
             capability.borrowed_rag = client
 
diff --git a/haiku_rag_slim/haiku/rag/chat/widgets/document_filter_modal.py b/haiku_rag_slim/haiku/rag/chat/widgets/document_filter_modal.py
index d065b9bb..b5cb5967 100644
--- a/haiku_rag_slim/haiku/rag/chat/widgets/document_filter_modal.py
+++ b/haiku_rag_slim/haiku/rag/chat/widgets/document_filter_modal.py
@@ -138,8 +138,8 @@ class DocumentFilterModal(ModalScreen):
         self._search = ""
         self._page = 0
         # Selections outside the page stay applied, and a checkbox is the only
-        # way to remove one, so they are reachable through their own listing
-        # rather than appended to this one, which the page bound has to hold.
+        # way to remove one, so their own listing keeps them reachable while
+        # this one holds the page bound.
         self._listing_selected = False
 
     def compose(self) -> ComposeResult:
diff --git a/haiku_rag_slim/haiku/rag/client/search.py b/haiku_rag_slim/haiku/rag/client/search.py
index 2d963038..7e96e1fc 100644
--- a/haiku_rag_slim/haiku/rag/client/search.py
+++ b/haiku_rag_slim/haiku/rag/client/search.py
@@ -46,8 +46,7 @@ async def search(
         limit = client._config.search.limit
 
     resolved = _resolved_search_type(query, search_type)
-    # One database embeds inside the repository, which returns early for a filter
-    # that matches nothing, so a text query that finds no documents never embeds.
+    # The repository embeds late, so a filter matching nothing never embeds.
     query_vector = (
         None if isinstance(query, str) else await _embed_query(client, query, resolved)
     )
@@ -92,9 +91,8 @@ async def search_sources(
         return []
     selected = await client.clients_for(names)
     if len(selected) == 1:
-        # One database is an ordinary search, whatever the client covers: fusion
-        # would replace its hybrid scores with ranks, and embedding up front
-        # would embed for a filter the repository can see matches nothing.
+        # One database is an ordinary search: fusion would replace its hybrid
+        # scores with ranks, and embedding up front would defeat the late embed.
         return await selected[0].search(
             query, limit, search_type, filter, include_images
         )
@@ -102,10 +100,9 @@ async def search_sources(
     if resolved != "fts":
         client._require_one_embedder(selected)
 
-    # One over-fetch decision, one query vector, and one reranker, for the whole
-    # set. The databases in a selection share an embedder, so the vector is the
-    # same wherever it is computed, and deciding the over-fetch per database would
-    # have each consult its own reranker.
+    # One over-fetch decision, one query vector and one reranker for the whole
+    # set: the databases share an embedder, and deciding per database would have
+    # each consult its own reranker.
     fetch_limit = _fetch_limit(client, query, limit)
     query_vector = await _embed_query(selected[0], query, resolved)
     text = query if isinstance(query, str) else ""
diff --git a/haiku_rag_slim/haiku/rag/utils.py b/haiku_rag_slim/haiku/rag/utils.py
index 30b07084..d1c8bb8b 100644
--- a/haiku_rag_slim/haiku/rag/utils.py
+++ b/haiku_rag_slim/haiku/rag/utils.py
@@ -509,9 +509,9 @@ def locate_database(location: str) -> tuple[str, Path | None]:
     """Split a configured location into (uri, db_path).
 
     A value with a scheme is a `lancedb.uri`; anything else is a local path.
-    Routing a local path through `uri` would have `ConnectionMode` classify it as
-    object storage, which opens it without the existence check a local database
-    gets.
+    `ConnectionMode` classifies a `uri` as object storage and opens it without
+    the existence check a local database gets, so a local path never travels
+    as one.
     """
     if "://" in location:
         return location, None