docs: rewrite README to cover all proxy features

README.md

@@ -1,63 +1,62 @@
 # anthropic-proxy
 
-Reverse proxy that lets OpenCode (and similar tools) use a Claude subscription instead of an API key.
+Reverse proxy for the Anthropic Messages API that authenticates with a Claude subscription (OAuth) instead of an API key. Lets you use tools like [OpenCode](https://github.com/opencode-ai/opencode) through your existing Claude Pro/Team plan.
 
-## Prerequisites
+## How it works
 
-- Go 1.26+
+Clients send standard Anthropic API requests to the proxy. The proxy authenticates upstream using OAuth credentials from your Claude subscription, forwards the request, and streams the response back. Requests are optionally sanitized (tool name remapping, string replacement) before forwarding and de-sanitized on return.
 
-Optional: [Nix](https://nixos.org/) flake for dev shell (`nix develop`).
+## Features
 
-## Setup
+- **OAuth credential management** — reuses `~/.claude/.credentials.json`, auto-refreshes tokens
+- **Request sanitization** — rename tools, replace strings in system prompts and body (configurable, hot-reloadable)
+- **Rate limit tracking** — polls Anthropic usage API and reads response headers to track 5h/7d utilization windows
+- **OpenTelemetry metrics** — request counts, latency, token usage, errors (optional OTLP export)
+- **Structured logging** — zerolog with file rotation via lumberjack
+
+## Quick start
 
 ```
 cp config.example.yaml config.yaml
-```
+# edit config.yaml — set api_keys and optionally claude_binary
 
-Edit `config.yaml`:
-- `api_keys` — key(s) your clients use to authenticate with the proxy
-- `claude_binary` — optional path to `claude` binary (used for request fingerprinting via sniff only)
-
-## Authentication
-
-On first run, if no credentials are found at `~/.claude/.credentials.json`, the proxy starts an OAuth login flow in your browser. Credentials are stored at `~/.claude/.credentials.json` (the same file Claude Code CLI uses). On subsequent runs, existing credentials are reused and refreshed automatically.
-
-If running headlessly (SSH/server), the authorization URL is printed to stdout and you can paste the authorization code manually.
-
-If you've already logged in with Claude Code CLI, the proxy will use the same credentials.
-
-## Build and run
-
-```
 go build -o anthropic-proxy .
 ./anthropic-proxy
 ```
 
-## Usage with OpenCode
+On first run, if no credentials exist at `~/.claude/.credentials.json`, an OAuth login flow starts in your browser. If running headlessly, the authorization URL is printed to stdout. If you've already logged in with Claude Code CLI, the proxy reuses those credentials.
+
+### Nix
+
+```
+nix develop   # dev shell with Go
+nix build     # build the binary
+```
+
+## Client configuration
+
+Point any Anthropic-compatible client at the proxy:
 
 ```
 export ANTHROPIC_API_KEY=your-proxy-api-key
 export ANTHROPIC_BASE_URL=http://localhost:8082
-opencode
 ```
 
 ## Endpoints
 
 | Method | Path | Description |
 |--------|------|-------------|
-| POST | `/v1/messages` | Anthropic messages API (proxied) |
+| POST | `/v1/messages` | Anthropic Messages API (proxied) |
 | POST | `/messages` | Same, without `/v1` prefix |
 | GET | `/healthz` | Health check |
-| POST | `/reload` | Hot-reload `config.yaml` |
+| POST | `/reload` | Hot-reload config (sanitize rules + API keys) |
 
-## Request sanitization
+## Configuration
 
-The `sanitize` section in config renames tool names and replaces strings in system prompts before forwarding to Anthropic. Responses are de-sanitized before returning to the client.
+See [`config.example.yaml`](config.example.yaml) for all options. Key sections:
 
-See `config.example.yaml` for the default rules.
+- **`api_keys`** — keys clients use to authenticate with the proxy
-
+- **`sanitize`** — tool renames, system prompt replacements, body replacements
-Reload after editing config:
+- **`telemetry`** — OTLP endpoint, service name, auth headers
-
+- **`logging`** — level, file path, rotation settings
-```
+- **`claude_binary`** — path to `claude` CLI for request fingerprinting (optional)
-curl -X POST localhost:8082/reload
-```