Add README documentation

Documents service purpose, endpoints, authentication flow, rate limiting, and configuration.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

README.md

@@ -0,0 +1,74 @@
+# Relay Service
+
+API gateway for Egregore.
+
+## Purpose
+
+Provides authenticated programmatic API access for external clients (mobile apps, integrations). Relays requests to backend services after validating JWT tokens.
+
+## Endpoints
+
+### Public
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Health check with backend status |
+| `/auth/token` | POST | Exchange API key for JWT |
+
+### Protected (requires JWT)
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/v1/chat` | POST | Send message, get AI response |
+| `/v1/history` | GET | Get message history |
+| `/v1/history/search` | GET | Search messages |
+| `/v1/tools` | GET | List available AI tools |
+
+### Admin
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/admin/clients` | GET/POST | List or create API clients |
+| `/admin/clients/{id}` | GET/PATCH/DELETE | Manage a client |
+| `/admin/clients/{id}/regenerate-key` | POST | Regenerate API key |
+
+## Authentication Flow
+
+1. Create API client via admin endpoint
+2. Client exchanges API key for JWT via `/auth/token`
+3. JWT used in `Authorization: Bearer <token>` header
+4. Tokens expire after 1 hour (configurable)
+
+## Configuration
+
+Environment variables (from `~/.env`):
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `JWT_SECRET` | Token signing secret | Auto-generated |
+| `JWT_EXPIRY` | Token lifetime (seconds) | `3600` |
+| `DATABASE_URL` | PostgreSQL for API clients | Standard connection |
+
+## Running
+
+```bash
+# Activate venv
+source ~/.venv/bin/activate
+
+# Run directly
+python main.py
+
+# Or via systemd
+sudo systemctl start relay
+sudo systemctl status relay
+```
+
+## Rate Limiting
+
+- General: 100 requests per client bucket
+- `/v1/chat`: 10/minute (Claude API costs)
+
+## Dependencies
+
+- FastAPI
+- PyJWT (token handling)
+- bcrypt (key hashing)
+- asyncpg (PostgreSQL)
+- slowapi (rate limiting)