diff --git a/docs/web-research-smoke-test.md b/docs/web-research-smoke-test.md
new file mode 100644
index 0000000..9dad820
--- /dev/null
+++ b/docs/web-research-smoke-test.md
@@ -0,0 +1,27 @@
+# web.py smoke test (webtools box)
+
+Manual checks against SearXNG (:8080) and Firecrawl (:3002) on
+`10.10.20.37`. Not run in CI — exercises live services.
+
+## Search
+```
+./.venv/bin/python web.py search "angelic hierarchy pseudo-dionysius" --max 3 --json
+```
+Expect a JSON array of hits with non-empty `url`s.
+
+**SearXNG JSON note:** if you get an empty list or a `format` error, JSON
+output is disabled. Enable in the box's `searxng/settings.yml`
+(`search: formats: [html, json]`) and restart.
+
+## Scrape
+```
+./.venv/bin/python web.py scrape https://en.wikipedia.org/wiki/Christian_angelic_hierarchy --out /tmp/smoke.md
+```
+Expect `wrote /tmp/smoke.md` and real markdown in the file.
+
+## Env overrides
+Point at a different box without code changes:
+```
+WEBTOOLS_HOST=192.168.1.50 SEARXNG_PORT=8080 FIRECRAWL_PORT=3002 \
+  ./.venv/bin/python web.py search "test" --json
+```