Phase 5: ESI Expires caching, error-limit back-off, setup docs (#16)

EsiClient now caches GET responses honoring the Expires header and backs off
when the rolling ESI error window is nearly exhausted (X-Esi-Error-Limit-*).
README gains Setup / Connect-to-Claude / enabling-writes sections.

Closes #16. SDE bulk-load split out to its own follow-up (#51).
135 tests, coverage 90%.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

README.md

@@ -19,7 +19,43 @@ Two data sources sit behind the server:
 - **ESI** (the [EVE Swagger Interface](https://esi.evetech.net/)) — the official REST API. Public endpoints (market, universe, industry indices) need no login. Character and corp data (wallet, assets, skills, industry, contracts, mail, location, and more) come through EVE SSO with **read and write OAuth2 scopes** across both character and corp; write scopes power the opt-in actions.
 - **SDE** (the [Static Data Export](https://developers.eveonline.com/resource/resources)) — the full static dataset of items, blueprints, systems and stations, cached locally for fast lookups and anything name- or recipe-based.
 
-Built in **Python with FastMCP**, OAuth via PKCE with a localhost callback, refresh token stored encrypted on disk. ESI `Expires` headers are respected for caching, and the SDE is loaded into a local store.
+Built in **Python with FastMCP**, OAuth via PKCE with a localhost callback, refresh token stored encrypted on disk. ESI `Expires` headers are respected for caching, the rolling ESI error limit is honored with back-off, and (eventually) the SDE is loaded into a local store.
+
+## Setup
+
+Requires [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync                 # install
+uv run familiar login   # browser EVE SSO login; run once per character
+uv run familiar status  # list logged-in characters
+```
+
+Re-run `login` for each character (switch EVE accounts in the browser as needed); they all live in one encrypted store. Changing the requested scopes requires logging in again.
+
+### Connect to Claude
+
+Claude Code:
+
+```bash
+claude mcp add familiar -- uv --directory /path/to/familiar run familiar
+```
+
+Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{ "mcpServers": { "familiar": { "command": "uv", "args": ["--directory", "/path/to/familiar", "run", "familiar"] } } }
+```
+
+Then ask in natural language — "what's Tritanium worth in Jita?", "how much ISK across all my characters?", "where are my characters?".
+
+### Enabling writes
+
+Write actions (send mail, set waypoints, edit contacts/fittings, fleet commands) are **off by default**. Every write tool also returns a dry-run preview unless called with `confirm=true`, and each executed write is recorded in an audit log.
+
+```bash
+uv run familiar writes enable   # allow writes (uv run familiar writes disable to revoke)
+```
 
 ## Roadmap
 
@@ -51,7 +87,7 @@ Built in phases. Each phase is independently useful, so the project stays shippa
 
 ## Status
 
-Phases 0–2 done on `dev`: public market & universe lookups, EVE SSO (PKCE) login with an encrypted token store, and read-only account tools (wallet, skills, location, clones, assets) across multiple characters and accounts. Now expanding to full character + corp coverage with opt-in writes (Phases 3–5). `main` stays untouched until the first complete version is ready.
+Phases 0–4 done on `dev`, plus Phase 5 caching/back-off and docs: public market & universe lookups; EVE SSO (PKCE) login with an encrypted, multi-character token store; full character **and** corp coverage across skills, wallet, assets, industry, trade, structures, killmails, profile, fleet, mail, contacts, fittings, PI and more; and opt-in, audited write actions. ~80 tools. Remaining: the full SDE bulk-load. `main` stays untouched until the first complete version is ready.
 
 ## License