diff --git a/README.md b/README.md
index 6762c413f..13b261adc 100644
--- a/README.md
+++ b/README.md
@@ -80,8 +80,11 @@ powershell -ExecutionPolicy ByPass -c "irm https://msgvault.io/install.ps1 | iex
 
 The installer detects your OS and architecture, downloads the latest release from [GitHub Releases](https://github.com/kenn-io/msgvault/releases), verifies the SHA-256 checksum, and installs the binary. You can review the script ([bash](https://msgvault.io/install.sh), [PowerShell](https://msgvault.io/install.ps1)) before running, or download a release binary directly from GitHub.
 
-To build from source instead (requires **Go 1.27+**, **Bun 1.3.14+**, and a
-C/C++ compiler for CGO and to statically link DuckDB):
+To build from source on macOS or Linux instead (requires **Go 1.27+**, **Bun
+1.3.14+**, **Node.js 20.19+ on 20.x, 22.13+ on 22.x, or 24+**, and a C/C++
+compiler for CGO and to statically link DuckDB; on Debian/Ubuntu also install
+`libsqlite3-dev` for the `sqlite3.h` header used by the default `sqlite_vec`
+build):
 
 ```bash
 git clone https://github.com/kenn-io/msgvault.git
diff --git a/docs/development.md b/docs/development.md
index 35e4254e9..118bf7ab1 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -5,9 +5,13 @@ description: Build, test, lint, and code conventions.
 
 ## Build
 
-Source builds require Go 1.27+, Bun 1.3.14+, and a C/C++ compiler. The Make
-targets install the pinned browser dependencies when `web/package.json` or
-`web/bun.lock` changes, then embed the production UI in the Go binary.
+The macOS and Linux builds require Go 1.27+, Bun 1.3.14+, Node.js (20.19+ on
+20.x, 22.13+ on 22.x, or 24+), and a C/C++ compiler. The Make targets install
+the pinned browser dependencies when `web/package.json` or `web/bun.lock`
+changes, then embed the production UI in the Go binary; Node runs the embed
+validator in that path. On Debian/Ubuntu also install `libsqlite3-dev`, which
+provides the `sqlite3.h` header needed to compile the default `sqlite_vec`
+extension.
 
 ### macOS and Linux
 
diff --git a/docs/setup.md b/docs/setup.md
index c9bb5aacd..7b28fc6c4 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -45,11 +45,20 @@ conda install -c conda-forge msgvault
 
 ## Build From Source
 
-Requires Go 1.27+, Bun 1.3.14+, and a C/C++ compiler (GCC or Clang). Bun builds
-the browser application embedded in the binary. CGO is required because
-msgvault uses `mattn/go-sqlite3` (SQLite with FTS5) and `duckdb-go/v2` (Parquet
+On macOS and Linux, source builds require Go 1.27+, Bun 1.3.14+, Node.js
+(20.19+ on 20.x, 22.13+ on 22.x, or 24+), and a C/C++ compiler (GCC or Clang).
+Bun builds the browser application embedded in the binary, and Node runs the
+embed validator that `make install` invokes. CGO is required because msgvault
+uses `mattn/go-sqlite3` (SQLite with FTS5) and `duckdb-go/v2` (Parquet
 analytics), both of which compile native extensions.
 
+On Debian/Ubuntu also install `libsqlite3-dev`, which provides the `sqlite3.h`
+header needed to compile the default `sqlite_vec` extension:
+
+```bash
+sudo apt install -y libsqlite3-dev
+```
+
 ```bash
 git clone https://github.com/kenn-io/msgvault.git
 cd msgvault
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 35e8609a4..ea08b1931 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -269,6 +269,13 @@ If you get errors about missing C compiler:
 
 CGO is required for `mattn/go-sqlite3` (FTS5 support).
 
+If the build reaches the cgo step and fails with `fatal error: sqlite3.h: No
+such file or directory` (from `asg017/sqlite-vec-go-bindings`), you are missing
+the SQLite development headers that the default `sqlite_vec` build needs:
+
+- **Debian/Ubuntu**: `sudo apt install -y libsqlite3-dev`
+- **Fedora/RHEL**: `sudo dnf install -y sqlite-devel`
+
 ## TUI Not Showing Data
 
 If the TUI launches but shows no data: