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/clients/vscode.md

@@ -0,0 +1,38 @@
+# Connect VS Code (Copilot / MCP)
+
+**Auth:** bearer token. **Prereq:** familiar deployed over HTTPS (see [deployment](../deployment.md)).
+
+VS Code's MCP support reads an **`http`** server entry with custom headers. Put it in **`.vscode/mcp.json`** (per-workspace) or your user `mcp.json`.
+
+> ⚠️ Use **`.vscode/mcp.json`**, not a workspace-root **`.mcp.json`**. The workspace `.mcp.json` format ignores `headers`, so the bearer token never gets sent and you'll get a silent 401. This is a known VS Code quirk.
+
+`.vscode/mcp.json`:
+
+```json
+{
+  "inputs": [
+    {
+      "id": "familiar_token",
+      "type": "promptString",
+      "description": "familiar bearer token",
+      "password": true
+    }
+  ],
+  "servers": {
+    "familiar": {
+      "type": "http",
+      "url": "https://familiar.yourdomain.tld/mcp",
+      "headers": {
+        "Authorization": "Bearer ${input:familiar_token}"
+      }
+    }
+  }
+}
+```
+
+On first use VS Code prompts for the token (masked, thanks to `password: true`) and reuses it. Start the server from the MCP view or the `MCP: List Servers` command, then use it from Copilot Chat's agent mode.
+
+## Troubleshooting
+
+- **Silent 401 / "no tools"** — you're almost certainly in a root `.mcp.json`; move the config to `.vscode/mcp.json` so `headers` is honored.
+- **401 after entering a token** — wrong token; clear it via `MCP: Reset Cached Tokens` (or restart) and re-enter.