evo2-sae dashboard: rewrite feature_explorer README for the three run modes

Document the actual ways to run now that the API is under /api and the frontend can be baked into
the image: (1) single container (docker run, UI + /api on one port, no Node at runtime) for sharing;
(2) local dev (Vite + backend, Node >=18, tsh tunnel of :5176, /api proxied straight through with no
rewrite); (3) offline/static (precompute artifacts, atlas always + sequence-UMAP from a bundle).
Adds a tab summary and notes the in-app per-tab Limitations. Touches only this PR's README.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Polina Binder <pbinder@nvidia.com>

Author: polinabinder1

interpretability/sparse_autoencoders/recipes/evo2/feature_explorer/README.md

@@ -1,34 +1,62 @@
 # Evo2 SAE Feature Explorer (front-end)
 
-Interactive dashboard for Evo2 SAE features — feature atlas, sequence inspector, and
-generative steering.
+Interactive dashboard for Evo2 SAE features, with four tabs:
+**Feature atlas**, **Sequence inspector**, **Generative steering**, and **Sequence UMAP**.
 
-This directory is the **front-end only**. Its backend is the standalone
-[`evo2_sae`](../src/evo2_sae) engine — the viz is just a UI over its
-`serve` mode, so there is no model code here.
+This directory is the **front-end only** (React + Vite). Its backend is the standalone
+[`evo2_sae`](../src/evo2_sae) engine — the viz is just a UI over its HTTP API, so there is no
+model code here. The front-end always calls the API under **`/api`** (same path in dev and
+production), so the only thing that ever changes is *where* `/api` is served from.
+
+## Three ways to run
+
+### 1. One container — recommended for sharing / deploy
+
+The recipe [`Dockerfile`](../Dockerfile) builds this front-end to static files and bakes them
+into the image, so a **single container serves the dashboard and the API on one port** — no
+Node and no second process at runtime. This is what to hand a coworker or put behind an SSO proxy.
+
+```bash
+# build from the REPO ROOT (the build context needs the recipes/evo2_megatron sibling):
+docker build -f interpretability/sparse_autoencoders/recipes/evo2/Dockerfile -t evo2-sae .
+
+# run with a GPU + your checkpoints, then open http://localhost:8001
+docker run --gpus all -p 8001:8001 \
+  -e EVO2_CKPT_DIR=/ckpt/evo2 -e SAE_CKPT_PATH=/ckpt/sae.pt -e EMBEDDING_LAYER=26 \
+  -v /path/to/checkpoints:/ckpt evo2-sae scripts/launch_inference.sh serve
+# -> dashboard + API both on http://localhost:8001  (/ = UI, /api = backend)
+```
+
+The first build compiles the megatron stack (~30 min) and is layer-cached afterward; a Node build
+stage produces the static bundle (`DASHBOARD_DIST`) and the server mounts it at `/`. No Node ends
+up in the runtime image. See the [recipe Dockerfile](../Dockerfile) for the layer layout.
+
+### 2. Local dev — UI iteration with hot reload
+
+Needs **Node ≥ 18** (for Vite), plus a GPU + checkpoints for the live tabs. Two processes:
 
 ```bash
-# 1. Backend: loads Evo2 + the SAE and serves the HTTP API on :8001
-../scripts/launch_inference.sh serve          # or: python -m evo2_sae.cli serve
+# backend: loads Evo2 + the SAE, serves the API under /api on :8001
+../scripts/launch_inference.sh serve            # or: python -m evo2_sae.cli serve
 
-# 2. Dashboard (from recipes/evo2): stages data (if any) + starts Vite
-python ../scripts/launch_dashboard.py                          # inspector + steering tabs
-python ../scripts/launch_dashboard.py --data-dir /path/to/data # + Feature-atlas tab
+# front-end: Vite dev server on :5176 (hot reload)
+../scripts/launch_dashboard.py                  # stages atlas data if --data-dir is given, then runs Vite
+#   or, for raw front-end dev:  npm install && npm run dev
 ```
 
-`launch_dashboard.py` is the entry point — it validates/stages the atlas parquets into
-`public/` (when `--data-dir` is given) and runs Vite. The **inspector** and **steering** tabs
-work with no atlas data (they call the backend); the **Feature-atlas** tab needs the three
-parquets (`features_atlas`, `feature_metadata`, `feature_examples`) via `--data-dir` —
-producing them is a separate offline step. (`npm install && npm run dev` also works for raw
-front-end dev, but skips data staging.)
+Vite proxies `/api` **straight through** to `http://localhost:8001` (no path rewrite — see
+`vite.config.js`), so dev hits the same `/api/*` paths as the single-container build. Point it at a
+different backend with `VITE_BACKEND`. Configure the backend via the env vars in `launch_inference.sh`.
 
-The Vite dev server proxies `/api` → `http://localhost:8001` (see `vite.config.js`); point it
-elsewhere with `VITE_BACKEND`. Configure the backend via the env vars in `launch_inference.sh`.
+To reach a remote box, tunnel the Vite port only (Vite proxies `/api` on the box):
+
+```bash
+tsh ssh -L 5176:localhost:5176 <gpu-box>        # then open http://localhost:5176
+```
 
-## Running without a backend (offline / static)
+### 3. Offline / static — no backend
 
-The dashboard degrades gracefully: it probes `/health`, and when there's **no live backend** it
+The dashboard degrades gracefully: it probes `/api/health`, and when there's **no live backend** it
 hides the tabs that need the model and keeps the ones that read static files.
 
 | Tab                     | Needs backend?           | Offline source                                                |
@@ -38,22 +66,35 @@ hides the tabs that need the model and keeps the ones that read static files.
 | **Generative steering** | yes                      | hidden offline                                                |
 | **Sequence inspector**  | yes                      | hidden offline                                                |
 
-So with no backend you get the **Feature atlas** always, and **Sequence UMAP** if you precompute
-its bundle. Steering and the live inspector require `serve`.
+So with no backend you always get the **Feature atlas**, plus **Sequence UMAP** if you precompute its
+bundle. Steering and the live inspector require `serve`.
 
 ```bash
-# (one-time, needs the 7B) precompute all the static artifacts into one dir:
+# (one-time, needs the model) precompute the static artifacts into one dir:
 python ../scripts/dashboard.py atlas      --activations-dir $STORE --output-dir dashboard_data   # atlas tab
 python ../scripts/dashboard.py examples   --examples-fasta lib.fa  --output-dir dashboard_data   # example cards
 python ../scripts/dashboard.py embeddings --examples-fasta lib.fa  --output-dir dashboard_data   # Sequence-UMAP bundle
 #   (env: SAE_CKPT_PATH, EVO2_CKPT_DIR, FEATURE_ANNOTATIONS — same as launch_inference.sh)
 
-# serve the static dashboard — NO backend, NO GPU:
+# serve the static dashboard — NO backend, NO GPU (needs Node for the dev server, or `npm run build`):
 python ../scripts/launch_dashboard.py --data-dir dashboard_data
 ```
 
-`dashboard.py embeddings` writes `sequmap_embeddings.json` (the same shape `/gene_embed` returns;
-bounded by sequence count). The viz auto-detects it (override the path with `?embeddings=<url>`).
-With all artifacts staged, `npm run build` produces a fully static site you can host anywhere
-(HF Spaces static / S3 / Pages) — interactive steering/inspector light up automatically if a
-backend is later reachable.
+`dashboard.py embeddings` writes `sequmap_embeddings.json` (the same shape `/api/gene_embed` returns).
+The viz auto-detects it (override the path with `?embeddings=<url>`). With all artifacts staged,
+`npm run build` produces a fully static site you can host anywhere (HF Spaces static / S3 / Pages) —
+the interactive steering/inspector tabs light up automatically if a backend later becomes reachable.
+
+## Tabs
+
+- **Feature atlas** — browse every SAE feature: firing rate, decoder-space UMAP, top-activating
+  examples, labels. Reads precomputed static files.
+- **Sequence inspector** — paste a sequence, see per-base SAE activations (top-k or picked features).
+  Live encode.
+- **Generative steering** — generate DNA while clamping chosen features on the continuation, vs. the
+  unsteered baseline. Live generation.
+- **Sequence UMAP** — embed a set of sequences (pooled per-feature vectors), UMAP them, color/re-project
+  by a feature. Live backend or a precomputed bundle.
+
+Each tab shows its own **Limitations** note in-app (context-length caps, the ±300 steering clamp,
+stochastic 2-D UMAP, etc.).