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.

README.md

@@ -99,39 +99,28 @@ Environment variables:
 
 **Writes are disabled by default over HTTP** — a network-reachable, LLM-driven endpoint should not send mail or set waypoints unless you explicitly opt in with `FAMILIAR_ENABLE_WRITES=1`. (Over stdio they stay on by default, as before.)
 
-### nginx
+By default familiar authenticates with a static bearer token (`FAMILIAR_AUTH_MODE=bearer`). For clients that only speak OAuth (the claude.ai web connector), there's an opt-in `oauth` mode where familiar acts as an OAuth 2.1 resource server in front of your own IdP — see [claude-web](doc/clients/claude-web.md).
 
-Streamable HTTP keeps a long-lived response open, so disable proxy buffering and give it a generous read timeout:
+### Deploy with Docker
 
-```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
-}
-```
+CI builds and publishes a hardened image on every merge to `dev`/`main` (`git.hiddenden.cafe/hiddenden/familiar`, tags `:dev`, `:main`/`:latest`). It runs `familiar serve` non-root on port `8080`, has a `/healthz` healthcheck, and keeps the encrypted token store under a `/data` volume. A [`docker-compose.yml`](docker-compose.yml) + [`.env.example`](.env.example) are included.
 
-### Add characters on a headless server
+**Full guide — Docker, reverse proxy (nginx / Caddy / Traefik), TLS, token provisioning, and the env-var reference — is in [doc/deployment.md](doc/deployment.md).**
 
-`familiar login` opens a browser and captures the callback on localhost, which needs a desktop. On a headless box you have two options:
+### Connect a client
 
-1. **Headless login** — print the SSO URL, authorize in any browser, paste the redirected URL back:
+Pick your client for exact steps:
 
-   ```bash
-   uv run familiar login --no-browser
-   ```
+| Client | Auth | Guide |
+| --- | --- | --- |
+| Claude Code | Bearer | [doc/clients/claude-code.md](doc/clients/claude-code.md) |
+| VS Code (Copilot) | Bearer | [doc/clients/vscode.md](doc/clients/vscode.md) |
+| Mistral Le Chat | Bearer | [doc/clients/mistral.md](doc/clients/mistral.md) |
+| Claude Desktop | Bearer (via `mcp-remote`) | [doc/clients/claude-desktop.md](doc/clients/claude-desktop.md) |
+| Claude Cowork | Bearer (via `mcp-remote`) | [doc/clients/claude-cowork.md](doc/clients/claude-cowork.md) |
+| Claude web (claude.ai) | OAuth 2.1 (external IdP) | [doc/clients/claude-web.md](doc/clients/claude-web.md) |
 
-   The localhost page the browser lands on will fail to load — that's expected; copy its address bar (it contains the `code`) and paste it at the prompt.
-
-2. **Copy the store** — run `familiar login` on your desktop, then copy the encrypted store (`token.enc` + `key` from your `FAMILIAR_DATA_DIR`) to the server's data dir.
-
-### Connect it in Mistral
-
-In [chat.mistral.ai](https://chat.mistral.ai): **Intelligence → Connectors → Add custom connector**, set the URL to `https://your-host/mcp`, choose **Bearer Token** auth, and paste the `FAMILIAR_HTTP_TOKEN` value.
+Bearer works everywhere except the claude.ai web connector, which requires OAuth with Dynamic Client Registration. The quickest path for a Claude user who doesn't want to run an IdP is the **Desktop** app with a bearer token.
 
 ## Roadmap