diff --git a/simulations/mixnet/chat-ui/README.md b/simulations/mixnet/chat-ui/README.md
index f24449fd4..3f986fbed 100644
--- a/simulations/mixnet/chat-ui/README.md
+++ b/simulations/mixnet/chat-ui/README.md
@@ -1,51 +1,83 @@
-# Testing logos-chat-ui against the local mixnet sim
+# E2E: logos-chat-ui over the local mixnet sim
 
 Run two `logos-chat-ui` clients that exchange end-to-end messages **through the
 5-node mix sim** (Sphinx routing + RLN spam protection + exit-node delivery).
 
-The two clients adopt the **two provisioned chat memberships** the sim already
-generates (peer-IDs `…1Qx…` and `…RABscN`, the same identities `run_chat_mix*.sh`
-use), via `CHAT_NODEKEY`. RLN keystores are peer-ID-derived, so fixing the nodekey
-makes the right `rln_keystore_<peerId>.json` resolve.
+This is a full from-scratch runbook: clone → build → provision → run → message.
 
-## Prerequisites
+The two clients adopt the **two provisioned chat memberships** the sim generates
+(peer-IDs `…1Qx…` and `…RABscN`), via `CHAT_NODEKEY`. RLN keystores are
+peer-ID-derived, so fixing the nodekey makes the right `rln_keystore_<peerId>.json`
+resolve.
 
-- Nix (the chat-ui builds via `nix run`).
-- This sim built + provisioned (run from `simulations/mixnet/`):
+---
+
+## 0. Prerequisites
+
+- **Nix** with flakes enabled (the chat client is built/run via `nix run`).
+- **Rust toolchain** (`rustc` + `cargo`, via [rustup](https://rustup.rs)) and the
+  standard dev tools (C compiler, GNU Make, Bash, Git) — needed to build the mix
+  node (`wakunode2`).
+- macOS or Linux.
+
+## 1. Repos & branches
+
+Only **logos-delivery** needs to be cloned. The chat client (and its whole
+dependency chain) is pulled automatically by `nix run`.
+
+| repo | branch | role | how it's consumed |
+|------|--------|------|-------------------|
+| `logos-messaging/logos-delivery` | `feat/logos-testnetv02-mix` | mix sim (5 nodes) + this harness | clone + `make wakunode2` |
+| `logos-co/logos-chat-ui` | `feat/logos-testnetv02-mix` | the GUI client | `nix run github:…` (pulls the rest) |
+| `logos-co/logos-chat-module` | `feat/logos-testnetv02-mix` | `liblogoschat` module | transitive flake input |
+| `logos-messaging/logos-chat` | `feat/logos-testnetv02-mix` | Nim SDK (in-process nwaku) | transitive flake input (`submodules=1`) |
+
+## 2. Build & provision the sim
 
 ```bash
-make -C ../../ wakunode2      # build the mix node binary
-./build_setup.sh             # generate rln_tree.db + 7 keystores
+git clone --recurse-submodules -b feat/logos-testnetv02-mix \
+  https://github.com/logos-messaging/logos-delivery
+cd logos-delivery
+
+make wakunode2          # builds Nim + deps + librln + the mix node (first run is long)
+
+cd simulations/mixnet
+./build_setup.sh        # generates rln_tree.db + 7 keystores (mix nodes + 2 chat slots)
 ```
 
-> `build_setup.sh` regenerates `rln_tree.db` + all keystores from
-> `setup_credentials.nim`. This sim is configured with **cover traffic disabled**
-> and **userMessageLimit = 100** (matches the chat's RLN default).
+> `build_setup.sh` sources the nwaku `env.sh`, so `nim` and `librln_v2.0.2.a`
+> (built by `make wakunode2`) are already in place. The sim is configured with
+> **cover traffic disabled** and **userMessageLimit = 100** (matches the chat's RLN
+> default) in `config*.toml`.
 
-## 1. Start the 5 mix nodes
+## 3. Start the 5 mix nodes
 
-Each in its own terminal, bootstrap first:
+Each in its own terminal, **bootstrap (`run_mix_node.sh`) first**:
 
 ```bash
-./run_mix_node.sh            # bootstrap (tcp/60001)
-./run_mix_node1.sh           # tcp/60002
-./run_mix_node2.sh           # tcp/60003
-./run_mix_node3.sh           # tcp/60004
-./run_mix_node4.sh           # tcp/60005
+cd simulations/mixnet
+./run_mix_node.sh       # bootstrap   tcp/60001
+./run_mix_node1.sh      #             tcp/60002
+./run_mix_node2.sh      #             tcp/60003
+./run_mix_node3.sh      #             tcp/60004
+./run_mix_node4.sh      #             tcp/60005
 ```
 
 Wait for `MixRlnSpamProtection started` + `Node setup complete` on each.
 
-## 2. Start the two chat-ui clients
+## 4. Start the two chat-ui clients
+
+Two more terminals. The first run builds the whole chat chain via nix (slow once,
+cached after):
 
 ```bash
-cd chat-ui
-./run_chat_ui.sh A           # ClientA on tcp/60010
-./run_chat_ui.sh B           # ClientB on tcp/60011
+cd simulations/mixnet/chat-ui
+./run_chat_ui.sh A      # ClientA, tcp/60010
+./run_chat_ui.sh B      # ClientB, tcp/60011
 ```
 
-Each opens a GUI window. The bottom status bar should show **`MIX 5/4`** (mix pool
-full) with the send button enabled.
+Each opens a GUI. The bottom status bar should show **`MIX 5/4`** (mix pool full)
+with the send button enabled.
 
 To iterate on a local chat-ui checkout instead of the pushed branch:
 
@@ -53,29 +85,39 @@ To iterate on a local chat-ui checkout instead of the pushed branch:
 CHAT_UI="$HOME/Code/logos-chat-ui" ./run_chat_ui.sh A
 ```
 
-## 3. Exchange messages
+## 5. Exchange messages
 
 1. In **ClientA**: click **My Bundle** and copy the intro bundle.
 2. In **ClientB**: **+ new** → paste A's bundle + a first message → create.
-3. Send messages each way — they route A↔B through the mixnet.
+3. Send messages each way — they route A↔B **through the mixnet**.
+
+To confirm a message actually traversed the mix, watch a mix node log for
+`onMessage - exit is destination` (the exit hop delivering to the recipient).
 
 ## How the config flows
 
-`run_chat_ui.sh` sets env that `logos-chat-ui` reads into the chat config:
+`run_chat_ui.sh` sources `env.sh` and sets the env `logos-chat-ui` reads into the
+chat config:
 
 | env | meaning |
 |-----|---------|
-| `CHAT_MIX_NODES` | the 5 mix nodes (`multiaddr:curve25519pubkey`) — **hardcoded**, the chat does no mix-peer discovery |
+| `CHAT_MIX_NODES` | the 5 mix nodes as `multiaddr:curve25519pubkey` — **both the node ID and the mix pubkey are hardcoded**; the chat does no mix-peer discovery |
 | `CHAT_STATIC_PEER` | bootstrap node (relay the chat connects to) |
 | `CHAT_CLUSTER_ID` / `CHAT_SHARD_ID` | `2` / `0` (must match the mix nodes) |
 | `CHAT_NODEKEY` | adopt a provisioned chat identity so its RLN keystore resolves |
 | `CHAT_MIX_REQUIRED` | force Required (mix) mode |
+| `CHAT_UI` | flake to run (default: the pushed `feat/logos-testnetv02-mix` branch) |
 
 ## Notes / limitations
 
 - **Load:** 5 mix nodes at `log-level=TRACE` (the default in `config*.toml`) write
-  multi-GB logs and can starve a desktop machine. For real testing prefer fleet
-  nodes; locally, lower `log-level` if the UI feels sluggish.
-- **Static membership only:** the two chat slots are fixed. Adding more clients
-  means adding their peer-IDs to `setup_credentials.nim` + re-running `build_setup.sh`.
-- **No mix discovery on the client:** all mix nodes must be in `CHAT_MIX_NODES`.
+  multi-GB logs and can starve a desktop machine — that, not the mix or the code,
+  is what made messages take ~a minute to render in earlier testing. For real
+  testing prefer fleet nodes; locally, lower `log-level` if the UI feels sluggish.
+- **Static membership only:** the two chat slots are fixed. More clients means
+  adding their peer-IDs to `setup_credentials.nim` + re-running `build_setup.sh`.
+- **No mix discovery on the client:** every mix node must be listed in
+  `CHAT_MIX_NODES` (multiaddr **and** curve25519 mix pubkey). The mix *nodes*
+  discover each other via kad; the chat client does not.
+- **Creds are not checked in** — `rln_tree.db` / `rln_keystore_*.json` are binary
+  and regenerated by `build_setup.sh`.