docs: deployment guide + per-client setup + connect matrix

- doc/deployment.md: run familiar as a remote MCP server — secure defaults,
  bearer vs OAuth modes, the full env-var reference, one-time login / token-store
  provisioning, the published images, docker compose, and TLS reverse-proxy
  blocks for nginx (proxy_buffering off + long read timeout), Caddy, and Traefik.
- doc/clients/: one page per client with exact working steps — Claude Code,
  VS Code (.vscode/mcp.json with a masked token input, and the workspace
  .mcp.json header gotcha), Mistral Le Chat, Claude Desktop + Cowork (mcp-remote
  bridge, per-OS config paths), and Claude web (oauth mode + external IdP, with
  "use Desktop + bearer" as the simpler alternative). Plus a clients/ index.
- README: a "Connect a client" matrix (client -> auth -> guide) and a compact
  "Deploy with Docker" section linking to doc/deployment.md; oauth mode noted.
- doc/README.md index: rows for Deployment and Client setup.
- doc/getting-started.md: pointer from the HTTPS quickstart to the full docs.
- CLAUDE.md: FAMILIAR_AUTH_MODE / FAMILIAR_OAUTH_* / FAMILIAR_ALLOW_INSECURE_BIND
  and /healthz in the transport note; the split ci.yml / docker.yml workflows.

Deployment docs live under the existing doc/ tree (the repo uses doc/, not a
separate docs/) to keep a single documentation directory.

CLAUDE.md

@@ -30,7 +30,14 @@ There is no separate build step; `uv build` produces the wheel (CI does this on
 
 **Server assembly.** [src/familiar/server.py](src/familiar/server.py) creates the single `FastMCP` instance and calls `register(mcp)` on each tool module. Every tool module (market, universe, account, industry, trade, structures, killmails, profile, corp, corp_economy, misc, comms, contacts, fittings, fleet, ui, planets, writes) follows the same shape: **module-level async functions** + a `TOOLS` list + `register(mcp)` that loops `mcp.tool(fn)`. Tools are plain importable functions (so tests call them directly); registration is separate. To add tools: new module → import + register in server.py.
 
-**Transport (stdio default, opt-in HTTP).** `familiar` (no args) runs `mcp.run()` over **stdio** (how Claude launches it) — local, no auth. `familiar serve` runs `server.serve_http()`: the FastMCP **streamable-HTTP** transport bound to loopback (`FAMILIAR_HTTP_HOST`/`FAMILIAR_HTTP_PORT`/`FAMILIAR_HTTP_PATH`, default `127.0.0.1:8080/mcp`) behind a TLS reverse proxy, for remote MCP clients (e.g. a Mistral custom connector). `configure_http()` attaches a FastMCP `StaticTokenVerifier` from `FAMILIAR_HTTP_TOKEN` (bad/missing bearer → 401 + `WWW-Authenticate: Bearer`) and **refuses to start (`SystemExit`) if the token is unset**. This transport-level bearer token is separate from the EVE-SSO/ESI auth in auth.py. In HTTP mode `configure_http` also calls `writes.set_http_context(True)`, flipping the **write default to disabled** unless `FAMILIAR_ENABLE_WRITES` is explicitly truthy (only the default resolution changes; `writes.guard` is untouched).
+**Transport (stdio default, opt-in HTTP).** `familiar` (no args) runs `mcp.run()` over **stdio** (how Claude launches it) — local, no auth. `familiar serve` runs `server.serve_http()`: the FastMCP **streamable-HTTP** transport bound to loopback (`FAMILIAR_HTTP_HOST`/`FAMILIAR_HTTP_PORT`/`FAMILIAR_HTTP_PATH`, default `127.0.0.1:8080/mcp`) behind a TLS reverse proxy, for remote MCP clients (Mistral, Claude web/desktop/code, VS Code — see [doc/clients/](doc/clients/)). An unauthenticated `GET /healthz` liveness route (returns only status/server/version) is served for Docker/proxy probes. This transport-level auth is separate from the EVE-SSO/ESI auth in auth.py.
+
+`configure_http(host=, token=, verifier=)` picks the auth provider from `FAMILIAR_AUTH_MODE`:
+
+- **`bearer`** (default): a `StaticTokenVerifier` from `FAMILIAR_HTTP_TOKEN` (bad/missing bearer → 401 + `WWW-Authenticate: Bearer`). **Fail-closed** — no token → `SystemExit`, unless `FAMILIAR_ALLOW_INSECURE_BIND=true` explicitly permits a tokenless bind (the message distinguishes loopback vs a public interface via `config.is_loopback`).
+- **`oauth`**: familiar is an OAuth 2.1 **resource server** only — a `JWTVerifier` (JWKS from `FAMILIAR_OAUTH_JWKS_URI` or discovered from `FAMILIAR_OAUTH_ISSUER`'s OIDC metadata, validating `issuer` + `audience`) wrapped in a `RemoteAuthProvider` that serves `/.well-known/oauth-protected-resource/<path>`. Config: `FAMILIAR_OAUTH_ISSUER`, `FAMILIAR_OAUTH_RESOURCE` (this server's public URL, required), `FAMILIAR_OAUTH_AUDIENCE` (defaults to resource). No DCR/authorization-server in familiar; needs an external IdP (Authentik/Keycloak) for the claude.ai web connector.
+
+Either mode calls `writes.set_http_context(True)`, flipping the **write default to disabled** unless `FAMILIAR_ENABLE_WRITES` is explicitly truthy (only the default resolution changes; `writes.guard` is untouched).
 
 **ESI access.** [esi.py](src/familiar/esi.py) is a thin async httpx wrapper (`client()` singleton, `get/post/put/delete`, `get_all_pages` for `X-Pages` pagination, Bearer `token=` for authed calls, uniform `EsiError`). Base URL and datasource are env-overridable. [zkill.py](src/familiar/zkill.py) mirrors it for zKillboard. Both expose `set_client()` so tests inject an `httpx.MockTransport`.
 
@@ -48,5 +55,5 @@ Tests use [tests/conftest.py](tests/conftest.py): the `mock_esi` fixture install
 
 - Work happens on `dev`. Feature branches → PR → fast-forward merge into `dev` → delete branch. Cut a release by bumping the version in `pyproject.toml` / `src/familiar/__init__.py` and opening a `dev → main` fast-forward PR (publishes the clean version).
 - `main` and `dev` are protected: no direct pushes, **signed commits required** (the user's git auto-signs), merge via PR.
-- CI (`.gitea/workflows/ci.yml`) runs lint + test on every PR/push; on a merge to main/dev it builds and publishes to the Gitea PyPI registry (auth via the `REGISTRY_TOKEN` secret; twine must NOT use `--skip-existing`). dev publishes a unique `.devN` pre-release.
+- Two workflows run lint + test on every PR/push. `.gitea/workflows/ci.yml` additionally builds + publishes the Python wheel to the Gitea PyPI registry on a merge to main/dev (auth via the `REGISTRY_TOKEN` secret; twine must NOT use `--skip-existing`; dev publishes a unique `.devN` pre-release). `.gitea/workflows/docker.yml` additionally builds + smoke-tests the Docker image (`docker/Dockerfile`, runs `familiar serve`; checks non-root, `/healthz` 200, MCP 401 without / 200 with a token) on every run and, on a merge to main/dev, pushes it to the Gitea container registry `git.hiddenden.cafe/hiddenden/familiar` (main → `:latest`/`:main`, dev → `:dev`, plus `:sha-<12>`) using the same `REGISTRY_TOKEN`. The two workflows are independent and must not interfere.
 - **Do NOT attribute commits, merges, or PRs to Claude / Claude Code.** No `Co-Authored-By: Claude ...` trailer on commits and no "Generated with Claude Code" footer in PR descriptions. Keep messages plain and authored by the user.