docs: the supported way to reach a TUI-hosted document over https

Per the user's ruling on improvise-o8fa: document the reverse-proxy path
properly, implement no TLS.

The existing text already named the symptom correctly -- an https origin
refuses `ws://` as mixed content, `improvise-ws-server` has no TLS, so
`wss://` is unobtainable from it -- but it gestured at "a reverse proxy or a
tunnel" and stopped, which is not something a reader can follow. So README
gains a worked Caddy example (Caddyfile, both commands, and the `?ws=` value
to reload with), the nginx difference that actually bites (`proxy_http_version
1.1` plus the Upgrade/Connection headers, without which the handshake is
answered as an ordinary request), the cloudflared/ngrok one-liners, and the
note that `--bind` should be left at loopback behind a proxy on the same host.

It also says the cost rather than papering it: the documented path to sharing
involves a second piece of software, which is a poor answer for a tool whose
selling point is being one binary. And it says what that cost buys against --
the standalone worker deployment is the point of the Pages site and needs no
server at all, and `http://localhost` pairing needs none of this either.

Native `wss://` is recorded as DECLINED WITH REASON rather than left as a gap.
The substance is the certificate, not rustls: a self-signed cert makes the
browser refuse the socket with no usable error, because a websocket handshake
has no interstitial to click through. A real cert or mkcert are the only
pleasant options and both are a second piece of software too -- so the choice
is not one binary versus two, it is two either way, with one option
additionally shipping a TLS stack in a pivot-table binary.

web/index.html is the second home for the same fact and is updated to point at
the worked example rather than restating it (gotcha 48: a fact stated twice is
a grep). Both were checked for text the correction left stale.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

README.md

@@ -216,10 +216,77 @@ address as mixed content. An explicit `ws://` from an https page is upgraded
 rather than passed through — passing it through can only produce a failure
 that reads like "the server is not running".
 
-So the local pairing above works as written. Reaching a server from the
-**deployed** https page means terminating TLS in front of it (a reverse proxy
-or a tunnel): `improvise-ws-server` speaks plain `ws://` only, and native
-`wss://` is not implemented.
+So the local pairing above works as written, and it is the case worth
+optimising for: `http://localhost` is not a secure-context problem, so nothing
+below is needed to develop, to demo locally, or to share a TUI-hosted document
+with another tab on the same machine.
+
+### Sharing a TUI-hosted document with a remote browser
+
+Reaching `improvise-ws-server` from the **deployed** https page means
+terminating TLS in front of it. `improvise-ws-server` speaks plain `ws://`
+only — there is no rustls, no native-tls, nothing in the crate or its
+dependencies — so `wss://` is not obtainable from the binary itself, and this
+is the supported way to get it.
+
+**Say the cost first, because it is real.** This means the documented path to
+sharing involves a second piece of software, which is a poor answer for a tool
+whose selling point is that it is one binary. It is the answer anyway, for a
+reason given under "Why not native `wss://`" below. If you only want *a*
+document in *a* browser, you do not need any of this — that is the standalone
+worker deployment, it is what the Pages site is for, and it needs no server
+process at all.
+
+A worked example with [Caddy](https://caddyserver.com/), which obtains and
+renews the certificate itself. Point a DNS name at the host, then:
+
+```caddyfile
+# Caddyfile
+improvise.example.com {
+    reverse_proxy 127.0.0.1:8787
+}
+```
+
+```sh
+improvise-ws-server bank-info.improv --port 8787   # still plain ws, still loopback
+caddy run                                          # terminates TLS, proxies to it
+```
+
+Then, from <https://fiddlerwoaroof.github.io/improvise/>, reload with
+`?ws=improvise.example.com`. Caddy preserves the request path, so the
+multi-document form works too: serve several files and name one with
+`?ws=improvise.example.com/bank-info`.
+
+Caddy needs no websocket-specific configuration — `reverse_proxy` passes the
+`Upgrade` handshake through. nginx does: it needs `proxy_http_version 1.1` and
+the `Upgrade`/`Connection` headers set explicitly, or the handshake is
+answered as an ordinary request and the socket never opens.
+
+For a one-off share with no DNS name and no certificate of your own,
+`cloudflared tunnel --url http://127.0.0.1:8787` or `ngrok http 8787` each
+print an https hostname that works the same way — pass the hostname to `?ws=`
+without a scheme.
+
+Note the server binds `127.0.0.1` by default and `--bind` is the only way to
+widen that. Behind a proxy on the same host you should *not* widen it: the
+proxy reaches loopback, and leaving the default means the unencrypted port is
+not reachable from anywhere else.
+
+### Why not native `wss://`
+
+Declined deliberately rather than merely unimplemented (improvise-o8fa). Adding
+rustls is the easy half; the certificate is the hard one, and it is what makes
+the feature worse than the proxy rather than better. A self-signed certificate
+makes the browser refuse the socket outright — a websocket handshake has no
+interstitial to click through, so the failure arrives as a bare connection
+error with no usable indication that a certificate was the reason. That leaves
+a real certificate or an explicitly trusted local CA (`mkcert`) as the only
+pleasant options, and both of those are a second piece of software too. So the
+choice is not "one binary versus two", it is "two either way, and one of the
+options additionally ships a TLS stack and a certificate-loading surface in a
+binary whose job is a pivot table". If sharing a TUI-hosted document to a
+remote browser ever becomes a common case rather than an occasional one, this
+is worth revisiting on that evidence.
 
 Caveat worth stating plainly: **no line of the browser JavaScript has ever
 run.** There is no browser and no headless DOM in the development environment,

web/index.html

@@ -65,9 +65,13 @@
       <code>wss://</code></strong>, because this page is served over https and
       an https origin refuses a <code>ws://</code> address as mixed content.
       Note that <code>improvise-ws-server</code> speaks plain
-      <code>ws://</code> only, so reaching it from here means terminating TLS
-      in front of it. Served over <code>http://localhost</code> the same page
-      defaults to <code>ws://</code> and pairs with it directly.
+      <code>ws://</code> only, so reaching it from <em>this</em> page means
+      terminating TLS in front of it with a reverse proxy or a tunnel — the
+      README has a worked Caddy example. Served over
+      <code>http://localhost</code> the same page defaults to
+      <code>ws://</code> and pairs with it directly, with nothing in between;
+      that is the case the pairing is really for. Sharing a document is what
+      the server is for — not running one is what everything above is for.
     </p>
 
     <main>