docs: document the remote-HTTP serve mode, env vars, nginx and Mistral setup

- README + getting-started: a "Serve over HTTPS (remote MCP)" section with the
  `familiar serve` command, the FAMILIAR_HTTP_* env vars, the write-off-by-
  default note, an nginx location block (proxy_buffering off, long read
  timeout), the headless-login / copy-the-store options, and the steps to add
  it as a Mistral custom connector.
- architecture: describe the stdio/HTTP transport split, the bearer-auth gate,
  and the HTTP write default.
- CLAUDE.md: add the new commands and env vars to Commands + Architecture.

README.md

@@ -77,6 +77,62 @@ To opt out and block all writes globally:
 uv run familiar writes disable   # turn writes off (uv run familiar writes enable to re-allow)
 ```
 
+## Serve over HTTPS (remote MCP)
+
+By default familiar talks over **stdio** — the local transport Claude launches. To reach it from a remote MCP client (for example a [chat.mistral.ai](https://chat.mistral.ai) custom connector), run the opt-in **streamable-HTTP** transport instead:
+
+```bash
+FAMILIAR_HTTP_TOKEN=$(openssl rand -hex 32) uv run familiar serve
+```
+
+`familiar serve` binds `127.0.0.1:8080/mcp` and expects a TLS-terminating reverse proxy in front of it. It **refuses to start without `FAMILIAR_HTTP_TOKEN`** — an internet-reachable account window must never run unauthenticated. Requests without a valid `Authorization: Bearer <token>` get `401` with a `WWW-Authenticate: Bearer` header; a valid token lets the MCP handshake through. stdio (`familiar` with no args) is unchanged and never token-gated.
+
+Environment variables:
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `FAMILIAR_HTTP_TOKEN` | *(required)* | Bearer token the client must send. No default — serve refuses to start without it. |
+| `FAMILIAR_HTTP_HOST` | `127.0.0.1` | Bind address. Leave loopback and let the proxy face the internet. |
+| `FAMILIAR_HTTP_PORT` | `8080` | Bind port. |
+| `FAMILIAR_HTTP_PATH` | `/mcp` | MCP endpoint path. |
+| `FAMILIAR_ENABLE_WRITES` | *(unset)* | In HTTP mode **writes default off**; set to `1`/`true` to opt in. |
+
+**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
+
+Streamable HTTP keeps a long-lived response open, so disable proxy buffering and give it a generous read timeout:
+
+```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
+}
+```
+
+### Add characters on a headless server
+
+`familiar login` opens a browser and captures the callback on localhost, which needs a desktop. On a headless box you have two options:
+
+1. **Headless login** — print the SSO URL, authorize in any browser, paste the redirected URL back:
+
+   ```bash
+   uv run familiar login --no-browser
+   ```
+
+   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.
+
 ## Roadmap
 
 Built in phases. Each phase is independently useful, so the project stays shippable.