docs improvement

Author: brendan-kellam

docs/self-hosting/more/search-contexts.mdx

@@ -7,13 +7,16 @@ sidebarTitle: Search contexts (EE)
 This is only available in the Enterprise Edition. Please add your [license key](/self-hosting/license-key) to activate it.
 </Note>
 
-A **search context** is a user-defined grouping of repositories that helps focus searches on specific areas of your codebase, like frontend, backend, or infrastructure code. This reduces noise in search results and improves developer productivity.
+A **search context** is a user-defined grouping of repositories that helps focus searches on specific areas of your codebase, like frontend, backend, or infrastructure code. Some example queries using search contexts:
 
-## Getting started
+- `context:data_engineering userId` - search for `userId` across all repos related to Data Engineering. 
+- `context:k8s ingress` - search for anything related to ingresses in your k8's configs.
+- `( context:project1 or context:project2 ) logger\.debug` - search for debug log calls in project1 and project2 
 
-<Note>
-The following will walkthrough an example of how search contexts can be used. For a full reference, see [here](#schema-reference).
-</Note>
+
+Search contexts are defined in the `context` object inside of a [declarative config](/self-hosting/more/declarative-config). Repositories can be included / excluded from a search context by specifying the repo's URL in either the `include` array or `exclude` array. Glob patterns are supported.
+
+## Example
 
 Let's assume we have a GitLab instance hosted at `https://gitlab.example.com` with three top-level projects, `web`, `backend`, and `shared`:
 
@@ -36,51 +39,59 @@ shared/
 ├─ ...
 ```
 
-To make searching easier, we can create three search contexts:
+To make searching easier, we can create three search contexts in our [config.json](/self-hosting/more/declarative-config):
 - `web`: For all frontend-related code
 - `backend`: For backend services and shared APIs
 - `pipelines`: For all CI/CD configurations
 
-Add these contexts to your [config.json](/self-hosting/more/declarative-config):
 
 ```json
 {
     "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
-    "connections": {
-        "gitlab-connection": {
-            "type": "gitlab",
-            "url": "https://gitlab.example.com",
-            "groups": ["web", "backend", "shared"]
-        }
-    },
     "contexts": {
         "web": {
-            "description": "Frontend related repos.",
+            // To include repositories in a search context,
+            // you can reference them...
             "include": [
-                "gitlab.example.com/web/**",
+                // ... individually by specifying the repo URL.
+                "gitlab.example.com/web/admin_panel/core",
+
+
+                // ... or as groups using glob patterns. This is
+                // particularly useful for including entire "sub-folders"
+                // of repositories in one go.
+                "gitlab.example.com/web/customer_portal/**",
                 "gitlab.example.com/shared/react/**",
                 "gitlab.example.com/shared/protobufs/**"
-            ]
-        },
-        "backend": {
-            "description": "Backend related repos.",
-            "include": [
-                "gitlab.example.com/backend/**",
-                "gitlab.example.com/shared/protobufs/**"
-            ]
+            ],
+
+            // Same with excluding repositories.
+            "exclude": [
+                "gitlab.example.com/web/customer_portal/pipelines",
+                "gitlab.example.com/shared/react/hooks/**",
+            ],
+
+            // Optional description of the search context
+            // that surfaces in the UI.
+            "description": "Web related repos."
         },
-        "pipelines": {
-            "description": "Devops related repos.",
-            "include": [
-                "gitlab.example.com/web/pipelines/**",
-                "gitlab.example.com/backend/pipelines/**",
-                "gitlab.example.com/shared/pipelines/**"
-            ]
-        }
+        "backend": { /* ... specifies backend replated repos ... */},
+        "pipelines": { /* ... specifies pipeline related repos ... */ }
+    },
+    "connections": {
+        /* ...connection definitions... */
     }
 }
 ```
 
+<Accordion title="Repository URL details">
+    Repo URLs are expected to be formatted without the leading http(s):// prefix. For example:
+    - `github.com/sourcebot-dev/sourcebot` ([link](https://github.com/sourcebot-dev/sourcebot))
+    - `gitlab.com/gitlab-org/gitlab` ([link](https://gitlab.com/gitlab-org/gitlab))
+    - `chromium.googlesource.com/chromium` ([link](https://chromium-review.googlesource.com/admin/repos/chromium,general))
+</Accordion>
+
+
 Once configured, you can use these contexts in the search bar by prefixing your query with the context name. For example:
 - `context:web login form` searches for login form code in frontend repositories
 - `context:backend auth` searches for authentication code in backend services