From eb81e68dd86f514c2c33f4905a9e9431cd699163 Mon Sep 17 00:00:00 2001
From: William Valentin <william.valentin.info@gmail.com>
Date: Sun, 22 Feb 2026 22:16:39 -0800
Subject: [PATCH] docs: clarify searxng local endpoint and fallback setup

---
 README.md             | 16 ++++++++++++++++
 config/default.yaml   |  2 +-
 docs/plans/state.json | 12 ++++++++++++
 3 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 3c63e63..0b0bb08 100644
--- a/README.md
+++ b/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
diff --git a/config/default.yaml b/config/default.yaml
index 65cb98d..5d151b5 100644
--- a/config/default.yaml
+++ b/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):
diff --git a/docs/plans/state.json b/docs/plans/state.json
index 304d017..599da19 100644
--- a/docs/plans/state.json
+++ b/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",