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.