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.

doc/architecture.md

@@ -40,6 +40,31 @@ Adding tools is mechanical: **write a new module, import it in `server.py`, and
 > text predates the write actions and is historical framing; the real behaviour is read **and**
 > guarded write (see [Write Safety](write-safety.md)).
 
+## Transport — stdio (default) and HTTP (opt-in)
+
+The same `mcp` instance is served over one of two transports; the tools and every layer below are
+identical either way.
+
+- **stdio (default).** `familiar` with no arguments calls `mcp.run()` — the local transport Claude
+  Desktop / Claude Code / Cowork launch over the process's stdin/stdout. No network, no auth layer:
+  the transport is local to the machine and trusted.
+- **streamable-HTTP (opt-in).** `familiar serve` calls `server.serve_http()`, which runs the FastMCP
+  streamable-HTTP transport bound to loopback (`FAMILIAR_HTTP_HOST`/`PORT`/`PATH`, default
+  `127.0.0.1:8080/mcp`) behind a TLS-terminating reverse proxy. `configure_http()` attaches a FastMCP
+  `StaticTokenVerifier` built from `FAMILIAR_HTTP_TOKEN`, so a request must present a matching
+  `Authorization: Bearer <token>` — anything else is a `401` with a `WWW-Authenticate: Bearer` header.
+  Serving **refuses to start without a token** (a `SystemExit` from `configure_http`), so the endpoint
+  is never open to the internet unauthenticated.
+
+The EVE-SSO/ESI auth in `auth.py` is unrelated to this transport-level bearer token: the bearer token
+gates the *MCP client* (e.g. Mistral) reaching familiar, while `auth.py` gates familiar reaching ESI.
+
+**Write default depends on the transport.** `configure_http()` calls `writes.set_http_context(True)`,
+which flips the *default* write policy: over HTTP writes are **disabled** unless `FAMILIAR_ENABLE_WRITES`
+is explicitly truthy, because a network-reachable, LLM-driven endpoint should not send mail or set
+waypoints by accident. Over stdio the default is unchanged (writes on). This only changes the default
+resolution — the `writes.guard` choke point and the per-call `confirm=true` requirement are untouched.
+
 ## The tool-module pattern
 
 Every tool module — market, universe, account, industry, trade, structures, killmails, profile, corp,
@@ -91,7 +116,9 @@ when to call it, so docstrings are written for that audience.
 **multi-character** encrypted store. Full details in [Authentication](authentication.md). The
 short version:
 
-- `interactive_login()` runs the browser flow once per character and persists a bundle.
+- `interactive_login()` runs the browser flow once per character and persists a bundle;
+  `manual_login()` is the headless variant (`familiar login --no-browser`) that prints the authorize
+  URL and reads the pasted callback URL from stdin — no local browser or callback listener needed.
 - The store is a dict of characters keyed by id, in one Fernet-encrypted file; a legacy
   single-character file is migrated on load.
 - `get_auth(character_id)` returns a valid access token, transparently refreshing via the rotating

doc/getting-started.md

@@ -99,7 +99,72 @@ uv run familiar writes            # show current state
 
 Full details in [Write Safety](write-safety.md).
 
-## 7. Verify everything works
+## 7. Serve over HTTPS (remote MCP)
+
+Everything above uses **stdio** — the local transport an MCP client launches on your machine.
+To reach familiar 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. stdio stays the default;
+nothing here changes how `uv run familiar` behaves with no arguments.
+
+```bash
+FAMILIAR_HTTP_TOKEN=$(openssl rand -hex 32) uv run familiar serve
+```
+
+`familiar serve` binds `127.0.0.1:8080/mcp` behind a TLS-terminating reverse proxy. It **refuses to
+start without `FAMILIAR_HTTP_TOKEN`** — an internet-reachable account window must never run
+unauthenticated. A request without a valid `Authorization: Bearer <token>` gets `401` with a
+`WWW-Authenticate: Bearer` header; a valid token lets the MCP handshake through.
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `FAMILIAR_HTTP_TOKEN` | *(required)* | Bearer token the client must send; serve refuses to start without it. |
+| `FAMILIAR_HTTP_HOST` | `127.0.0.1` | Bind address. Leave loopback; 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 default off over HTTP.** A network-reachable, LLM-driven endpoint should not send mail or
+> set waypoints unless you opt in explicitly with `FAMILIAR_ENABLE_WRITES=1`. (Over stdio they stay on
+> by default, as in section 6.)
+
+### nginx location block
+
+Streamable HTTP holds a long-lived response open, so turn off buffering and raise the 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
+}
+```
+
+### Logging in on a headless server
+
+`familiar login` needs a local browser and the `localhost:8765` callback. On a headless box:
+
+- **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 fails to load — that's expected; copy its address bar
+  (it holds the `code`) and paste it at the prompt.
+- **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.
+
+### Add 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 your
+`FAMILIAR_HTTP_TOKEN`.
+
+## 8. Verify everything works
 
 ```bash
 uv run pytest          # full test suite (fails under 80% coverage)