diff --git a/USING_GBRAIN_WITH_GSTACK.md b/USING_GBRAIN_WITH_GSTACK.md
index 7507f3be0..49781d7b8 100644
--- a/USING_GBRAIN_WITH_GSTACK.md
+++ b/USING_GBRAIN_WITH_GSTACK.md
@@ -57,7 +57,9 @@ Best for: you'd rather click through supabase.com yourself than paste a PAT.
 
 Best for: try-it-first, no account, no cloud, no sharing. Or a dedicated "this Mac's brain" that stays isolated from any cloud agent.
 
-**What happens:** `gbrain init --pglite`. Brain lives at `~/.gbrain/brain.pglite`. No network calls. Done in 30 seconds.
+**What happens:** `gbrain init --pglite`. Brain lives at `~/.gbrain/brain.pglite`. No network calls for the init itself. Done in 30 seconds.
+
+**Embedding model.** When `VOYAGE_API_KEY` is set, gstack inits PGLite with `voyage-code-3` (1024-dim) — Voyage's code-specialized embedding model, which beats their general-purpose `voyage-4-large` and OpenAI `text-embedding-3-large` head-to-head on this codebase's symbol queries. Without `VOYAGE_API_KEY`, gbrain auto-selects (OpenAI 1536-dim when `OPENAI_API_KEY` is present, else falls down its provider chain). Either way, the embeddings call out to the chosen provider's API during sync — set the key for the provider you want before running `/sync-gbrain`.
 
 This is the best first choice if you just want to see what gbrain feels like before committing to cloud. You can always migrate later with `/setup-gbrain --switch`.
 
diff --git a/bin/gstack-gbrain-install b/bin/gstack-gbrain-install
index d9c30396b..e7e029ce0 100755
--- a/bin/gstack-gbrain-install
+++ b/bin/gstack-gbrain-install
@@ -217,4 +217,13 @@ if ! gbrain sources --help >/dev/null 2>&1; then
 fi
 
 echo ""
-echo "Next: gbrain init --pglite   (or run /setup-gbrain for the full setup flow)"
+if [ -n "${VOYAGE_API_KEY:-}" ]; then
+  echo "Next: gbrain init --pglite --embedding-model voyage:voyage-code-3 --embedding-dimensions 1024"
+  echo "      (or run /setup-gbrain for the full setup flow)"
+else
+  echo "Next: gbrain init --pglite   (or run /setup-gbrain for the full setup flow)"
+  echo ""
+  echo "Tip: set VOYAGE_API_KEY before init to use voyage-code-3 (best embedding"
+  echo "model for code retrieval on Voyage). Without it, gbrain falls back to its"
+  echo "auto-selected provider (OpenAI when OPENAI_API_KEY is set, etc.)."
+fi
diff --git a/setup-gbrain/SKILL.md.tmpl b/setup-gbrain/SKILL.md.tmpl
index a0bc59769..731e875f7 100644
--- a/setup-gbrain/SKILL.md.tmpl
+++ b/setup-gbrain/SKILL.md.tmpl
@@ -125,7 +125,14 @@ with `GSTACK_DETECT_NO_CACHE=1` (busts the 60s cache). If the new
 ```bash
 BACKUP="$HOME/.gbrain/config.json.gstack-bak-$(date +%s)"
 mv "$HOME/.gbrain/config.json" "$BACKUP"
-if ! gbrain init --pglite --json; then
+# gstack default: voyage-code-3 (1024d) when VOYAGE_API_KEY is set — best for
+# code retrieval. Without the key, fall back to gbrain's own auto-selected
+# embedding provider chain (OpenAI 1536d when OPENAI_API_KEY is present, etc.).
+GBRAIN_EMBED_FLAGS=""
+if [ -n "${VOYAGE_API_KEY:-}" ]; then
+  GBRAIN_EMBED_FLAGS="--embedding-model voyage:voyage-code-3 --embedding-dimensions 1024"
+fi
+if ! gbrain init --pglite --json $GBRAIN_EMBED_FLAGS; then
   # Restore on failure
   mv "$BACKUP" "$HOME/.gbrain/config.json"
   echo "gbrain init failed. Your previous config was restored at $HOME/.gbrain/config.json." >&2
@@ -332,10 +339,18 @@ Then follow the same secret-read + verify + init flow as Path 1.
 ### Path 3 (PGLite local)
 
 ```bash
-gbrain init --pglite --json
+# gstack default: voyage-code-3 (1024d) when VOYAGE_API_KEY is set — code
+# retrieval beats general-purpose embeddings on real code queries (validated
+# A/B). Without the key, gbrain auto-selects (OpenAI 1536d when available).
+GBRAIN_EMBED_FLAGS=""
+if [ -n "${VOYAGE_API_KEY:-}" ]; then
+  GBRAIN_EMBED_FLAGS="--embedding-model voyage:voyage-code-3 --embedding-dimensions 1024"
+fi
+gbrain init --pglite --json $GBRAIN_EMBED_FLAGS
 ```
 
-Done. No network, no secrets.
+Done. No network, no secrets (beyond Voyage embedding API calls during sync, if
+`VOYAGE_API_KEY` is set — ~$0.18 per 1M tokens, pennies per repo).
 
 ### Path 4 (Remote gbrain MCP — HTTP transport with bearer token)
 
@@ -415,7 +430,15 @@ if [ -f "$HOME/.gbrain/config.json" ]; then
   BACKUP="$HOME/.gbrain/config.json.gstack-bak-$(date +%s)"
   mv "$HOME/.gbrain/config.json" "$BACKUP"
 fi
-if ! gbrain init --pglite --json; then
+# gstack default for local code-search PGLite: voyage-code-3 (1024d) when
+# VOYAGE_API_KEY is set. It wins the A/B over voyage-4-large and OpenAI
+# text-embedding-3-large on this codebase's symbol queries. Falls back to
+# gbrain's auto-selected provider when the key isn't present.
+GBRAIN_EMBED_FLAGS=""
+if [ -n "${VOYAGE_API_KEY:-}" ]; then
+  GBRAIN_EMBED_FLAGS="--embedding-model voyage:voyage-code-3 --embedding-dimensions 1024"
+fi
+if ! gbrain init --pglite --json $GBRAIN_EMBED_FLAGS; then
   if [ -n "${BACKUP:-}" ] && [ -f "$BACKUP" ]; then mv "$BACKUP" "$HOME/.gbrain/config.json"; fi
   echo "gbrain init failed. Existing config (if any) was restored. PGLite at ~/.gbrain/pglite/ may be in a partial state — \`rm -rf ~/.gbrain/pglite\` to reset." >&2
   echo "Continuing setup without local code search; you can re-run /setup-gbrain to retry." >&2
diff --git a/sync-gbrain/SKILL.md.tmpl b/sync-gbrain/SKILL.md.tmpl
index b05c39066..91a8bb1a4 100644
--- a/sync-gbrain/SKILL.md.tmpl
+++ b/sync-gbrain/SKILL.md.tmpl
@@ -101,7 +101,9 @@ BEFORE invoking the orchestrator:
   "Your brain queries (the `mcp__gbrain__*` tools) work via remote MCP, but
   symbol code search needs a local PGLite. Run `/setup-gbrain` and pick
   'Yes' at the new 'local code index' prompt (Step 4.5), or run
-  `gbrain init --pglite --json` directly. Continuing without code stage."
+  `gbrain init --pglite --json --embedding-model voyage:voyage-code-3 --embedding-dimensions 1024`
+  directly (drop the voyage flags if `VOYAGE_API_KEY` isn't set). Continuing
+  without code stage."
   Then proceed to Step 2 — the orchestrator's `runCodeImport()` and
   `runMemoryIngest()` will return SKIP per plan D12; only `runBrainSyncPush()`
   will run. Do NOT abort.
@@ -114,7 +116,8 @@ BEFORE invoking the orchestrator:
     1. Re-run /setup-gbrain — Step 1.5 offers Retry / Switch to PGLite /
        Switch brain mode / Quit (plan D4).
     2. Repair manually: mv ~/.gbrain/config.json ~/.gbrain/config.json.bak
-       && gbrain init --pglite --json
+       && gbrain init --pglite --json --embedding-model voyage:voyage-code-3 \
+          --embedding-dimensions 1024   (drop voyage flags if VOYAGE_API_KEY unset)
   Re-run /sync-gbrain after.
   ```
   Do NOT continue — the orchestrator would skip code+memory and only run