diff --git a/prod/docs/H5I_MESSAGING_SETUP.md b/prod/docs/H5I_MESSAGING_SETUP.md
new file mode 100644
index 00000000..23cd9f23
--- /dev/null
+++ b/prod/docs/H5I_MESSAGING_SETUP.md
@@ -0,0 +1,85 @@
+# h5i — Cross-Agent Messaging (AUTHORITATIVE — read this to connect)
+
+**This is THE single source of truth for agent comms. If anything elsewhere conflicts, this wins.**
+Last updated 2026-06-22 by claude (integrator) to fix a bus split that left agents unable to see each
+other's messages.
+
+---
+
+## 0. TL;DR — how to be reachable (do this first)
+
+```bash
+cd /mnt/dolphinng5_predict          # ← THE CANONICAL BUS lives here. Always run h5i from here.
+export H5I_AGENT=<your-handle>      # e.g. codex / cmd-PASS9 / cmd-pass6 / cmd-pass5 / claude
+h5i msg inbox                       # read + mark your unread
+```
+
+**Rule: always operate h5i with cwd = `/mnt/dolphinng5_predict`.** That checkout's `refs/h5i/msg` is
+the ONE canonical bus everyone shares. Do not send/read from a fork clone — that's what split us.
+
+---
+
+## 1. Why we split (so it doesn't happen again)
+
+`refs/h5i/msg` is **per-clone**. We had two diverged copies:
+- **CANONICAL:** `/mnt/dolphinng5_predict` refs/h5i/msg (also mirrored read-only at `/mnt/vp-oa4`).
+- **FORK:** `/mnt/vp-PASS9` refs/h5i/msg — where PASS9 had been reading/writing.
+
+They never reconciled because **`h5i share push` targets the Gitea origin
+(`…/siloqy.git`), which HANGS** (broken server-side hook). So claude's messages (on canonical) never
+reached PASS9 (on the fork), and vice-versa. **Do not rely on share-to-Gitea.**
+
+## 2. The fix — converge on the canonical bus
+
+**Everyone reads/writes the canonical bus by running h5i from `/mnt/dolphinng5_predict`.** That path
+is the shared checkout all agents can reach; one ref, no push/pull, no divergence.
+
+If you are forced to work inside a fork clone (e.g. `/mnt/vp-PASS9`, whose git `origin` is the LOCAL
+path `/mnt/dolphinng5_predict`), sync the bus **locally** (this does NOT touch Gitea, so it works):
+```bash
+cd /mnt/vp-PASS9
+h5i share pull      # pulls h5i refs from your local origin (/mnt/dolphinng5_predict)
+# … work, send …
+h5i share push      # pushes back to the LOCAL origin (fine). NEVER push to the Gitea remote.
+```
+But the simpler, recommended path is just: **don't** — run h5i from `/mnt/dolphinng5_predict` directly.
+
+## 3. Identities (current)
+
+| Handle | Role | Current PASS2 task |
+|---|---|---|
+| **claude** | Integrator (owns merges to `main`, bit-verification) | — |
+| **codex** | Parity / V3.4b live-factor / HZ | **PASS2.5** conviction soak |
+| **cmd-PASS9** | ASEx kernel / race-safety | **PASS2.2** arming-gate, **PASS2.6** HZ client |
+| **cmd-pass6** | Execution internals (OrderFSM/FillPump/Reconciler) | **PASS2.3** VST adapter, **PASS2.4** wiring |
+| **cmd-pass5** | Mock-BingX adapter | **PASS2.1** VST creds + isolation |
+
+Set yours: `export H5I_AGENT=<handle>` (or `h5i msg as <handle>`).
+
+## 4. Usage
+
+```bash
+h5i msg                       # inbox dashboard (glance)
+h5i msg inbox                 # show unread, mark read (numbers them)
+h5i msg send <recipient> "…"  # free-text ( 'all' = broadcast )
+h5i msg ask <recipient> "…"   # a request expecting a reply
+h5i msg reply <n> "…"         # threaded reply to message #n
+h5i msg ack|done|decline <n> "…"
+h5i msg wait --timeout 600    # block until a reply arrives (run as a background waiter)
+git show refs/h5i/msg:messages.jsonl   # raw view
+```
+Types: ASK · REVIEW_REQUEST · RISK · HANDOFF · BROADCAST · ACK · DONE.
+
+## 5. Code workflow (so comms + code don't re-split) — see `VIOLET_PASS2_SERIES_INDEX.md`
+
+- **Single trunk:** `/root/violet` `main` on local disk; shared bare origin **`/root/violet.git`**
+  (NOT Gitea). Your PASS2 worktree is `/root/violet-wt/pass2.<n>-<slug>` on branch
+  `agent/pass2.<n>-<slug>`. **Work there, push to `/root/violet.git`.** Do not branch from `/mnt`
+  CIFS clones.
+- Sub-specs: `prod/docs/VIOLET_PASS2.<n>_*.md` (also replicated to `/mnt/dolphinng5_predict/prod/docs/`).
+- Commit hygiene: explicit staging (never `git add .`), `Co-Authored-By:` trailer, tests in-commit.
+
+## 6. De-confliction note
+
+This file supersedes the comms sections of `VIOLET_CMD_ONBOARDING__PASS5.md` and any per-pass spec —
+those defer here for *how to connect*. Operator points all agents at THIS file.