From fe6838ffac4de2aeb6e212ebe2445220f1344606 Mon Sep 17 00:00:00 2001
From: roysaurav <sauravroy_personal@outlook.com>
Date: Thu, 16 Jul 2026 23:48:54 -0400
Subject: [PATCH] docs: add macOS 26.x Tahoe PGLite WASM workaround + native
 Postgres setup guide (#1671)

PGLite's embedded WASM engine crashes on macOS 26.x (Tahoe) on Apple
Silicon during engine initialization. This adds:

- A Troubleshooting section in docs/INSTALL.md with step-by-step
  instructions for using native Homebrew PostgreSQL 17 + pgvector
  as a workaround
- A callout in README.md's Troubleshooting section pointing users
  to the detailed setup guide

Tested on macOS 26.5 (arm64), Bun 1.3.14, gbrain 0.41.29.0,
PostgreSQL 17.10 (Homebrew), pgvector 0.8.0. All 102 schema
migrations pass. gbrain doctor green.

Co-authored-by: Saurav Roy <roysaurav@users.noreply.github.com>
---
 README.md       |  2 ++
 docs/INSTALL.md | 35 +++++++++++++++++++++++++++++++++++
 2 files changed, 37 insertions(+)

diff --git a/README.md b/README.md
index c3ea8086c..9807cadb8 100644
--- a/README.md
+++ b/README.md
@@ -289,6 +289,8 @@ Data flowing into the brain. Each integration is a recipe — markdown + setup h
 
 ## Troubleshooting
 
+**`gbrain init --pglite` crashes on macOS 26.x (Tahoe)?** PGLite's embedded WASM engine is incompatible with macOS 26.x on Apple Silicon. The fix is to use native Homebrew PostgreSQL + pgvector instead. Full step-by-step setup in [`docs/INSTALL.md` — Troubleshooting: PGLite crashes on macOS 26.x](docs/INSTALL.md#pglite-crashes-on-macos-26x-tahoe).
+
 **`gbrain import` fails with `expected N dimensions, not M`?** Run `gbrain doctor`. It will print the exact `gbrain config set ...` or `gbrain retrieval-upgrade` command to repair the mismatch. You should not need to delete `~/.gbrain`. Fresh `gbrain init --pglite` auto-detects your embedding provider from API keys in your environment: set `OPENAI_API_KEY` (or `ZEROENTROPY_API_KEY` / `VOYAGE_API_KEY`) before running init, or pass `--embedding-model <provider>:<model>` explicitly. With multiple keys set, init fires an interactive picker. In non-TTY contexts (CI, Docker) with no keys, init exits 1 with a paste-ready setup hint; pass `--no-embedding` to defer setup until runtime. See [`docs/integrations/embedding-providers.md`](docs/integrations/embedding-providers.md) for the full provider matrix and [`docs/operations/headless-install.md`](docs/operations/headless-install.md) for Docker/CI sequencing.
 
 **Hourly cron sync keeps timing out on a federated brain?** v0.41.13.0 ships
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index 91002d6c5..f3517161b 100644
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -111,3 +111,38 @@ gbrain models doctor              # 1-token probe per configured model
 ```
 
 If anything's yellow, `gbrain doctor` names the fix command in the message. Most issues are missing API keys or stale schema (`gbrain upgrade --force-schema`).
+
+## Troubleshooting
+
+### PGLite crashes on macOS 26.x (Tahoe)
+
+PGLite's embedded WASM engine is incompatible with macOS 26.x (Tahoe) on Apple Silicon. If `gbrain init --pglite` crashes during engine initialization, switch to native Homebrew PostgreSQL:
+
+```bash
+# Install PostgreSQL + pgvector
+brew install postgresql@17
+brew services start postgresql@17
+createdb gbrain
+
+# Build pgvector from source (required for vector search)
+cd /tmp && git clone --branch v0.8.0 https://github.com/pgvector/pgvector.git
+cd pgvector && make && make install
+psql gbrain -c "CREATE EXTENSION IF NOT EXISTS vector;"
+
+# Point gbrain at your local Postgres
+cat > ~/.gbrain/config.json << 'EOF'
+{
+  "engine": "postgres",
+  "database_url": "postgresql://localhost:5432/gbrain",
+  "schema_pack": "gbrain-base-v2"
+}
+EOF
+
+# Run migrations and verify
+gbrain apply-migrations --yes
+gbrain doctor
+```
+
+All 102 migrations run on first try. Once `gbrain doctor` shows green, the brain works identically to PGLite — same commands, same skills, same data model. The only difference is the storage backend.
+
+> **Note:** This workaround is temporary. When the upstream WASM runtime fix ships (likely via a Bun update), `--pglite` will work on Tahoe again.