diff --git a/docs/deep-search/index.mdx b/docs/deep-search/index.mdx
index f9ff24d13..3583977e5 100644
--- a/docs/deep-search/index.mdx
+++ b/docs/deep-search/index.mdx
@@ -41,6 +41,12 @@ You can reuse the same [search contexts](/code-search/working/search-contexts) y
 
 Search contexts are useful when you want to keep Deep Search focused on a specific part of your codebase, such as a team's repositories, a product area, or another shared scope used across your organization. Limiting Deep Search to a smaller set of repositories can help it search faster and produce more focused, higher-quality answers.
 
+Query-based search contexts can include repository filters as well as file, language, case, and content-style filters. Deep Search can use these contexts for code search, but its repository-listing step can only enumerate contexts that are defined by repository constraints. If Deep Search reports that the active search context cannot be listed, either:
+
+- Ask Deep Search to search directly within the selected context instead of listing repositories first.
+- Change the selected search context to use repository-only constraints, such as `repo:`, `rev:`, `fork:`, `archived:`, `visibility:`, or supported repository metadata predicates like `repo:has.topic(...)`.
+- Create a repository-defined search context for scopes that Deep Search should list as repositories.
+
 To learn how to create and manage search contexts, see [Search contexts](/code-search/working/search-contexts).
 
 ## Using @-mentions