From 3b0335f34e8f271e398a5df05061ffd13698cbb1 Mon Sep 17 00:00:00 2001
From: pi <pi@devbox>
Date: Thu, 11 Jun 2026 11:23:15 +0200
Subject: [PATCH] docs(studio): clarify studio-expose foreground + token, add
 remote/mosh end-to-end recipe

---
 README.md | 44 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 43 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 66e8fa4..db97673 100644
--- a/README.md
+++ b/README.md
@@ -199,9 +199,15 @@ With `STUDIO_EXPOSE=1`, the entrypoint starts the bridge for you; just run
 (leave `STUDIO_EXPOSE` unset), run `studio-expose` in a container shell:
 
 ```bash
-studio-expose            # bridges $STUDIO_PORT (default 8765); --help for details
+studio-expose &          # bridges $STUDIO_PORT (default 8765); --help for details
 ```
 
+> **`studio-expose` runs in the foreground** (it's a `socat` relay) — it
+> blocks the shell until Ctrl-C. Background it with `&` or run it in its
+> own tmux pane. It only relays traffic; it does **not** print a token.
+> The lines it prints ending in `...token=...` are literal help text, not
+> a truncated URL — the real token comes from `/studio` (see below).
+
 > **Security:** the bridge intentionally exposes Studio beyond loopback;
 > its tokenized URL is the only auth. Keep the host-side publish on
 > `127.0.0.1:` and use `ssh -L` for remote access. Default is **off**.
@@ -221,6 +227,42 @@ tunnel alongside mosh (mosh for the shell, ssh for the port), or reach the
 host's published port directly over a trusted network (LAN / Tailscale /
 WireGuard).
 
+#### End-to-end recipe: remote host, mosh shell, `studio-expose` bridge
+
+The full path has four network hops, each added by one step:
+
+```
+laptop browser →[ssh -L]→ host :8765 →[docker -p]→ container eth0 :8765
+              →[studio-expose]→ container 127.0.0.1 :8765 ← pi-studio
+```
+
+Assuming the compose file publishes `127.0.0.1:8765:8765` (see method B):
+
+1. **In a container shell** — start the bridge (skip if `STUDIO_EXPOSE=1`
+   is set in compose, which auto-starts it):
+   ```bash
+   studio-expose &
+   ```
+2. **In your pi session** (the pi TUI in the container) — start Studio and
+   print the tokenized URL. `/studio` is a slash command you type in the
+   TUI, not a shell command:
+   ```
+   /studio --no-browser --port 8765
+   /studio --status                  # reprint the URL anytime
+   ```
+   Copy the `http://…:8765/?token=<token>` it prints. **This** is where
+   the real token comes from — not `studio-expose`.
+3. **On your laptop** — open the ssh port-forward alongside mosh:
+   ```bash
+   ssh -L 8765:127.0.0.1:8765 user@docker-host
+   ```
+4. **In your laptop browser** — open `http://127.0.0.1:8765/?token=<token>`
+   (keep the port and token verbatim; only the host part is `127.0.0.1`).
+
+> **Order check:** nothing listens on the container's `127.0.0.1:8765`
+> until step 2 runs. If the browser can't connect, verify Studio is up
+> (`/studio --status`) and the bridge is running (`ps aux | grep socat`).
+
 > PDF export (`/studio-pdf`, `studio_export_pdf`) needs a LaTeX engine,
 > which is **not** in `-studio` (only the planned `-studio-tex`). HTML
 > export, KaTeX, Mermaid, and all REPL features work without it.