docs: clarify searxng local endpoint and fallback setup

README.md

@@ -490,6 +490,22 @@ Optional local SearXNG container (for self-hosted web search):
 docker compose --profile search up -d searxng
 ```
 
+Local-first + homelab fallback pattern:
+
+- If Flynn runs in Docker Compose, set `endpoint: "http://searxng:8080"`.
+- If Flynn runs on the host (`pnpm dev` / `pnpm start`), set `endpoint: "http://localhost:18803"`.
+- Set `fallback_endpoint` to your existing homelab SearXNG URL.
+
+Example for host-run Flynn with local compose SearXNG and homelab backup:
+
+```yaml
+web_search:
+  provider: searxng
+  endpoint: "http://localhost:18803"
+  fallback_endpoint: "https://searxng.homelab.local"
+  max_results: 5
+```
+
 Note: Flynn's built-in `web.search*` tools call Brave's HTTP API directly and use `web_search.api_key`; they do not route through the `brave-search` MCP container.
 
 ### Text-to-Speech (TTS) Reply Audio

config/default.yaml

@@ -254,7 +254,7 @@ models:
 #   provider: brave
 #   api_key: "${BRAVE_API_KEY}"
 #   max_results: 5
-#   # endpoint: "http://searxng:8080"     # Used when provider=searxng
+#   # endpoint: "http://searxng:8080"     # Used when provider=searxng (or http://localhost:18803 if Flynn runs on host)
 #   # fallback_endpoint: "https://searxng.homelab.local"  # Optional backup endpoint for provider=searxng
 #
 # Optional local Brave Search MCP container (for MCP workflows only):

docs/plans/state.json

@@ -3,6 +3,18 @@
   "updated_at": "2026-02-23",
   "description": "Tracks the status of all Flynn plans and implementation phases",
   "plans": {
+    "searxng-fallback-runtime-endpoint-doc-clarity": {
+      "status": "completed",
+      "date": "2026-02-23",
+      "updated": "2026-02-23",
+      "summary": "Clarified operator docs for local SearXNG with homelab fallback by documenting endpoint selection based on Flynn runtime location (Compose-internal service DNS vs host localhost port mapping) and adding an explicit host-run example.",
+      "files_modified": [
+        "README.md",
+        "config/default.yaml",
+        "docs/plans/state.json"
+      ],
+      "test_status": "docs/config comments update only; no runtime code changes"
+    },
     "local-searxng-compose-with-fallback-endpoint": {
       "status": "completed",
       "date": "2026-02-23",