search(query) -> ranked URLs/snippets   (local SearXNG, Docker, 127.0.0.1:8888, normally stopped)
read(url)     -> cleaned Markdown       (controlled fetch + Trafilatura, SSRF-protected)

# with uv (recommended)
uv sync
uv sync --extra mcp      # for MCP server
uv sync --extra dev      # for tests

# or pip
pip install -e .
pip install -e ".[mcp]"

# global tool (so `webx` works in `pi`'s bash and any shell)
uv tool install .        # installs to ~/.local/bin/webx — ensure ~/.local/bin is on PATH
# or pipx
pipx install .

# per-project (no global install)
uv sync && uv run webx --help
# or add .venv/bin to PATH for this shell/session (useful for pi coding agent)
export PATH="$PWD/.venv/bin:$PATH"
which webx && webx --help

webx init                # materialize ~/.local/share/webx/{compose.yml,settings.yml,.env,cache}
webx doctor              # check docker, templates, SearXNG reachability (does NOT start SearXNG)
webx status              # {initialized, docker_available, searxng_running, url, runtime_dir}
webx status --json

webx search "SearXNG documentation" --limit 5 --pretty
webx status              # now running

webx read "https://docs.searxng.org/" --max-chars 12000
webx read "https://docs.searxng.org/" --json | jq

# denials are exit 5
webx read "http://127.0.0.1:8888/"      # -> exit 5 unsafe URL
webx read "http://192.168.1.1/"         # -> exit 5
webx read "file:///etc/passwd"          # -> exit 5

webx stop                # docker compose stop (retains container)
webx status              # stopped

For this task you are allowed to use the local WebX utility when external/current
information materially helps.
Available commands:
- webx search "<query>" to discover relevant public-web sources.
- webx read "<url>" to read a relevant public page as cleaned text/Markdown.
...
When the web-research portion is finished, run webx stop.

{
  "mcpServers": {
    "webx": {
      "command": "webx-mcp",
      "env": { "WEBX_DATA_DIR": "/home/you/.local/share/webx" }
    }
  }
}

webx --help
webx --version
webx init [--force-templates] [--show-path]   # idempotent, never rotates secret
webx doctor                                   # inspection only
webx up                                       # ensure SearXNG running
webx stop                                     # compose stop (normal shutdown)
webx status [--json]
webx logs [--tail 100]
webx search QUERY [--limit 8] [--category general] [--language en] [--page 1]
              [--time {day,month,year}] [--safe-search {0,1,2}] [--engine NAME] [--pretty]
webx read URL [--max-chars N] [--json] [--links] [--no-tables] [--precision] [--recall]

webx search "python httpx" --engine wikipedia --engine github --pretty
webx search "SearXNG" --category it --pretty
webx search "SearXNG documentation" --time month --pretty

webx read "https://en.wikipedia.org/wiki/Python_(programming_language)" --max-chars 2000 --links | head -n 40
webx read "https://en.wikipedia.org/wiki/Python_(programming_language)" --max-chars 2000 | head -n 40
webx read "https://api.github.com/zen" --json | jq  # application/json is returned raw (engine=raw), not trafilatura

services:
  searxng:
    image: ${SEARXNG_IMAGE:-docker.io/searxng/searxng:latest}
    container_name: webx-searxng
    ports: ["127.0.0.1:8888:8080"]
    env_file: [.env]
    volumes: ["./settings.yml:/etc/searxng/settings.yml:ro", "./cache:/var/cache/searxng"]
    restart: "no"

WEBX_DATA_DIR, WEBX_SEARXNG_URL (default http://127.0.0.1:8888), WEBX_DOCKER_CMD,
WEBX_STARTUP_TIMEOUT (30s), WEBX_SEARCH_TIMEOUT (15s), WEBX_READ_TIMEOUT (15s),
WEBX_MAX_RESPONSE_BYTES (10 MiB), WEBX_MAX_READ_CHARS (40000), WEBX_MCP_STOP_ON_EXIT (true)

webx stop
docker compose -f $(webx init --show-path)/compose.yml pull   # or: SEARXNG_IMAGE=... docker compose pull
webx up
webx search "test" --limit 1 --pretty
webx stop

uv sync --extra dev --extra mcp
uv run pytest                # fast unit tests, no Docker/net required
uv run pytest -m integration # live tests (needs Docker + net, marked integration)
uv run pytest --cov=webx

webx --help; webx init; webx doctor; webx status   # stopped
webx search "SearXNG documentation" --limit 5 --pretty
webx status                                        # running
webx read "https://docs.searxng.org/" --max-chars 12000
webx read "http://127.0.0.1:8888/"      # -> exit 5
webx read "http://192.168.1.1/"         # -> exit 5
webx read "file:///etc/passwd"          # -> exit 5
webx stop; webx status                 # stopped
# MCP: inspector 2 tools, web_read while stopped, first search starts, second reuses, stop-on-exit ownership

src/webx/
  __init__.py, cli.py, config.py, lifecycle.py, searxng.py, security.py, reader.py, core.py, mcp_server.py
  assets/{compose.yml,settings.yml}
tests/{unit,integration}
docs/{instructions,PLAN.md}