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.

doc/deployment.md

@@ -0,0 +1,140 @@
+# Deployment — familiar as a remote MCP server
+
+familiar runs two ways from the **same** code and token store:
+
+1. **Local (stdio)** — the default. How Claude Desktop / Claude Code / Cowork launch it. Nothing here changes; see [getting-started](getting-started.md).
+2. **Remote (HTTP)** — opt-in via `familiar serve`. Streamable HTTP behind a TLS reverse proxy, gated by a bearer token (or external OAuth). This page covers (2).
+
+Once it's running, see [doc/clients/](clients/) for exact per-client setup.
+
+## Secure defaults
+
+- **stdio unless told otherwise.** `familiar serve` (not the bare `familiar`) starts HTTP.
+- **Loopback bind by default** (`127.0.0.1`). The Docker image binds `0.0.0.0` so the reverse proxy can reach it.
+- **Fail closed.** familiar refuses to start without authentication. In bearer mode that means no `FAMILIAR_HTTP_TOKEN` → it won't boot; a non-loopback bind without a token is called out explicitly. The only override is the explicit `FAMILIAR_ALLOW_INSECURE_BIND=true` escape hatch.
+- **Writes off over HTTP.** A network-reachable, LLM-driven endpoint keeps writes disabled unless you set `FAMILIAR_ENABLE_WRITES=true`. Local stdio keeps writes on.
+- **Token never in the URL.** Clients authenticate with an `Authorization: Bearer <token>` header only.
+
+## Authentication modes
+
+`FAMILIAR_AUTH_MODE` picks how the HTTP transport authenticates:
+
+- **`bearer`** (default) — one static token in `FAMILIAR_HTTP_TOKEN`. Simple, and every client below except Claude web supports it. Recommended.
+- **`oauth`** — familiar runs as an OAuth 2.1 **resource server**: it validates incoming JWT access tokens against an external issuer's JWKS and serves `/.well-known/oauth-protected-resource/<path>` so OAuth-only clients can discover the authorization server. familiar is **not** an authorization server and does **no** Dynamic Client Registration — you must run an external IdP that does (Authentik, Keycloak, …). Only needed for the native **Claude web** connector. See [doc/clients/claude-web.md](clients/claude-web.md).
+
+## Environment variables
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `FAMILIAR_HTTP_HOST` | `127.0.0.1` | Bind address (image sets `0.0.0.0`). |
+| `FAMILIAR_HTTP_PORT` | `8080` | Bind port. |
+| `FAMILIAR_HTTP_PATH` | `/mcp` | MCP endpoint path. |
+| `FAMILIAR_AUTH_MODE` | `bearer` | `bearer` or `oauth`. |
+| `FAMILIAR_HTTP_TOKEN` | *(unset)* | Bearer token. **Required** in bearer mode. |
+| `FAMILIAR_ALLOW_INSECURE_BIND` | `false` | Allow a bind without a token (don't). |
+| `FAMILIAR_OAUTH_ISSUER` | *(unset)* | Authorization-server URL (oauth mode). |
+| `FAMILIAR_OAUTH_RESOURCE` | *(unset)* | This server's public URL, e.g. `https://familiar.example.com` (oauth mode). |
+| `FAMILIAR_OAUTH_AUDIENCE` | = resource | Expected token audience (oauth mode). |
+| `FAMILIAR_OAUTH_JWKS_URI` | *(discovered)* | JWKS URL; if unset, discovered from the issuer's OIDC metadata. |
+| `FAMILIAR_DATA_DIR` | per-user | Where `token.enc` + `key` + `audit.log` + write toggle live. Image sets `/data`. |
+| `FAMILIAR_ENABLE_WRITES` | on (stdio) / off (HTTP) | `true` allows guarded writes; over HTTP it's off unless set. |
+
+`/healthz` is an unauthenticated liveness probe (used by the Docker healthcheck and reverse-proxy probes). It returns only `{"status":"ok","server":"familiar","version":"…"}` — no account data. Every MCP call under `FAMILIAR_HTTP_PATH` requires authentication.
+
+## One-time login (why it happens on the host)
+
+EVE SSO login is a browser PKCE flow with a `localhost` callback — awkward inside a container. Authenticate **once on a machine with a browser**, then hand the resulting token store to the container. The container only ever *refreshes* tokens.
+
+```bash
+uv run familiar login          # opens the browser, writes token.enc + key
+uv run familiar status         # confirm the character(s)
+```
+
+Then make that data dir available to the container. Point `FAMILIAR_DATA_DIR_HOST` at it, or copy `token.enc` + `key` into `./data`:
+
+```bash
+mkdir -p ./data
+# Linux/macOS host default:
+cp ~/.local/share/familiar/{token.enc,key} ./data/
+# Windows host default:
+#   copy %LOCALAPPDATA%\familiar\token.enc .\data\ ; copy %LOCALAPPDATA%\familiar\key .\data\
+```
+
+**Headless host?** Use `uv run familiar login --no-browser`: it prints the SSO URL, you authorize in any browser, and paste the redirected callback URL back on stdin. The `/data` volume is mounted read-write so token refresh (which rotates the refresh token) and the audit log persist.
+
+## Published images (Gitea)
+
+`.gitea/workflows/docker.yml` builds, smoke-tests (non-root, `/healthz` 200, MCP 401 without / 200 with a token), and pushes on every push to `main`/`dev`:
+
+| Branch | Tags |
+| --- | --- |
+| `main` | `git.hiddenden.cafe/hiddenden/familiar:latest`, `:main`, `:sha-<12>` |
+| `dev`  | `git.hiddenden.cafe/hiddenden/familiar:dev`, `:sha-<12>` |
+
+Pushing needs a Gitea PAT with `write:package` scope stored as the repo secret `REGISTRY_TOKEN`. Pick the channel with `FAMILIAR_IMAGE` in `.env`.
+
+## Run with Docker Compose
+
+```bash
+cp .env.example .env
+# edit .env: FAMILIAR_HTTP_TOKEN (openssl rand -hex 32), FAMILIAR_DOMAIN,
+#            cert resolver, FAMILIAR_IMAGE (:latest prod / :dev dev channel)
+
+docker network create proxy    # once, if your reverse proxy doesn't own it yet
+
+docker login git.hiddenden.cafe
+docker compose pull && docker compose up -d
+#   ...or build locally instead:  docker compose up -d --build
+
+docker compose logs -f familiar
+```
+
+The compose service joins the external `proxy` network (not published to the host), runs non-root with a `read_only` rootfs + tmpfs `/tmp`, `no-new-privileges` and `cap_drop: ALL`, and healthchecks `GET /healthz`.
+
+## TLS reverse proxy
+
+familiar terminates no TLS itself — a proxy does. Streamable HTTP holds a long-lived response open, so **disable buffering** and use a **generous read timeout** on the MCP path.
+
+### nginx
+
+```nginx
+location /mcp {
+    proxy_pass http://127.0.0.1:8080/mcp;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_buffering off;          # stream events straight through
+    proxy_read_timeout 3600s;     # don't cut long-lived MCP sessions
+}
+```
+
+(If you run the container on the `proxy` network instead of publishing to the host, point `proxy_pass` at `http://familiar:8080/mcp`.)
+
+### Caddy
+
+```
+familiar.yourdomain.tld {
+    reverse_proxy familiar:8080
+}
+```
+
+Caddy fetches and renews the certificate automatically and streams by default.
+
+### Traefik (labels included)
+
+`docker-compose.yml` already carries Traefik router labels. Set in `.env`:
+
+```
+FAMILIAR_DOMAIN=familiar.yourdomain.tld
+TRAEFIK_CERTRESOLVER=letsencrypt
+```
+
+Traefik terminates HTTPS and forwards to the container's port 8080 on the `proxy` network. Your public URL is then `https://familiar.yourdomain.tld/mcp`.
+
+## Operational notes
+
+- **Rotate the token** by changing `FAMILIAR_HTTP_TOKEN` and restarting; update every client header.
+- **Restrict inbound** at the proxy/firewall to the clients you expect.
+- **Watch** `docker compose logs` for `401` auth failures and `/data/audit.log` for the write trail.
+- **Re-login** (host) whenever you change requested scopes, then refresh the `/data` token store.