AGENTS.md git:20260828.00975deA

Immutable. This exact content never changes and is served at /api/v1/blob/ae2ddf3630c4847e.

# Repository guidance

## Purpose

Web Forager provides web search, news search, and URL fetching for AI agents. It
exposes the capabilities through a FastMCP STDIO server and a CLI, and packages
agent workflows under `skills/`.

Search and news use `ddgs`. Fetching tries direct HTTP with `trafilatura`, then
falls back to Jina Reader.

## Change contract

- Read the relevant implementation and tests before editing.
- Keep changes focused and consistent with existing patterns.
- Treat `src/web_forager/_version.py` as generated by `setuptools_scm`.
- When CLI flags or MCP tool behavior changes, update the corresponding tests
  and `README.md` documentation in the same change.
- Keep credentials and other secrets out of source, configuration, fixtures,
  logs, and documentation.

## Development

Install the development dependencies:

```bash
uv pip install -e ".[dev]"
```

Run the narrowest relevant test first, then use the full checks when the change
can affect multiple components:

```bash
pytest
mypy src
black --check src
isort --check-only src
```

Use the CLI smoke tests documented in `README.md` when changing search, news,
fetch, or CLI behavior.

## Agent workflow references

- Before editing README prose or structure, read
  `docs/agents/readme-style.md`.