feat: default PGLite to voyage-code-3 when VOYAGE_API_KEY set

When gstack inits a local PGLite engine for code search, use Voyage's
code-specialized `voyage-code-3` (1024-dim) embedding model if
\`VOYAGE_API_KEY\` is present. Falls back to gbrain's auto-selected
provider chain (OpenAI text-embedding-3-large 1536-dim when
OPENAI_API_KEY is available, etc.) when the Voyage key is unset.

Why voyage-code-3: head-to-head A/B against voyage-4-large on 10
realistic code queries against this codebase (using gbrain query
--no-expand for pure vector retrieval). voyage-code-3 strictly won on
4 queries (cases where the right hit was an implementation file vs a
test file: terminal-agent.ts over terminal-agent-integration.test.ts,
sanitizeReplacer over sanitize.test.ts, disposeSession over a
tangentially-related killDaemon test, surfaced injectCanary semantic
query). Tied on 5 with consistently +0.03 to +0.06 higher confidence.
Zero losses for voyage-4-large.

Touches 3 init sites in setup-gbrain/SKILL.md.tmpl:
- Step 1.5 (broken-db rollback-safe switch to PGLite)
- Path 3 direct PGLite init
- Step 4.5 split-engine local code index (Path 4 Yes branch)

Plus 2 manual-repair hints in sync-gbrain/SKILL.md.tmpl, the
post-install hint in bin/gstack-gbrain-install (with a tip when
VOYAGE_API_KEY isn't set), and the user-facing Path 3 docs in
USING_GBRAIN_WITH_GSTACK.md.

Cost is trivial: voyage-code-3 at \$0.18/1M tokens means a full reindex
of a 100K-LOC repo runs about \$0.20. Incremental syncs are pennies.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

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`.
 

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

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

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