# AGENTS.md — The Laws of THIS Land

Listen up, agent. We run a tight ship here. If you want your code merged, you follow these rules. No exceptions.

## 1. Error Handling: Silence is Death
- **NEVER** write a bare `except: pass`. If you swallow an error, you blind us.
- **NEVER** catch `Exception` broadly without logging it with `logger.exception()`.
- If an adapter fails (Qdrant/Neo4j), **RAISE** a specific `HTTPException`. Do not return a fake "error" object.

## 2. Pydantic or Perish
- We use **Pydantic V2**.
- ❌ `class Config: ...` (V1 style)
- ✅ `model_config = SettingsConfigDict(...)` (V2 style)
- **ALWAYS** set constraints: `min_length`, `max_length`, `ge`, `le`. Unbounded strings are a DoS vector.

## 3. Async First
- Use `httpx.AsyncClient`, not `requests`.
- Use `asyncio.gather` for parallel I/O.
- Do not block the event loop.

## 4. Testing: Don't Be Lazy
- **Mocks**: When strict mocks (`spec=...`) fight you, use `side_effect` with real async functions.
- **Integration**: Unit tests are fine, but integration tests prove it works.
- **Paths**: We use `pytest`. Make sure your imports resolve (sometimes you need to patch `src.server` directly, not the library it imports).

## 5. Security: Paranoid Mode
- **API Keys**: Hash them (SHA-256 or better). NEVER store plaintext keys.
- **Injection**: Allowlist your dynamic query parameters (especially for Cypher/SQL).
- **Secrets**: Env vars only. No hardcoded defaults in code.

## 6. Branching: GitHub Flow
- This repository enforces GitHub Flow.
- **NEVER** push directly to `main`.
- Create feature branches: `feature/[task-id]-[description]`.
- Open a PR and ensure CI (lint/test) passes before merging.

Follow these, and we'll get along fine. Break them, and the linter/audit will yell at you.
