diff --git a/docs/gs-sync.md b/docs/gs-sync.md
index 2cd7dbb..c8402cd 100644
--- a/docs/gs-sync.md
+++ b/docs/gs-sync.md
@@ -96,6 +96,17 @@ bundled with it (v4.3.1) replaces the active `engram` with v1.
 
 Check: `scripts/test-engram-auto-setup.sh`.
 
+## gentle-ai uses our Engram binary
+
+On the beta channel, `gentle-ai sync` and installs run
+`go install github.com/Gentleman-Programming/engram/cmd/engram@main`. That is the
+pre-v3 module path, so it installs Engram v1 over the v3 binary.
+`zsh/cortex-dotfiles.zsh` exports `GENTLE_AI_ENGRAM_BIN=$HOME/.local/bin/engram`,
+which makes gentle-ai use that binary instead of installing one. `gs sync`
+installs v3 at that path.
+
+Check: `engram version` reports 3.x after `gs sync` and after starting Pi.
+
 ## Tests
 
 `tests/gs_test.sh` runs offline in a throwaway HOME with stub binaries and covers
diff --git a/zsh/cortex-dotfiles.zsh b/zsh/cortex-dotfiles.zsh
index 86f17a1..f27561a 100644
--- a/zsh/cortex-dotfiles.zsh
+++ b/zsh/cortex-dotfiles.zsh
@@ -298,6 +298,10 @@ export GENTLE_AI_CHANNEL="${GENTLE_AI_CHANNEL:-beta}"
 # Stop gentle-shell startup auto-setup: it reprovisions companions and its
 # bundled gentle-ai replaces Engram with v1. Set to 0 to opt back in.
 export GENTLE_SHELL_NO_AUTO_SETUP="${GENTLE_SHELL_NO_AUTO_SETUP:-1}"
+# On the beta channel gentle-ai installs Engram with `go install .../engram/cmd/engram@main`,
+# the pre-v3 module path, which yields Engram v1. Pointing it at our own binary
+# makes gentle-ai use that one instead of installing; gs sync keeps it on v3.
+export GENTLE_AI_ENGRAM_BIN="${GENTLE_AI_ENGRAM_BIN:-$HOME/.local/bin/engram}"
 #endregion
 
 #region Herdr Clipboard