diff --git a/CLAUDE.md b/CLAUDE.md
index efb4bdaa7..015a5bc1f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -483,6 +483,7 @@ Follow this order so behavior is **specified**, **proven in Rust**, **proven ove
 
 ## Platform notes
 
+- **Vendored CEF-aware `tauri-cli` (required)**: The default runtime is **CEF**, and only the **vendored** `tauri-cli` at `app/src-tauri/vendor/tauri-cef/crates/tauri-cli` knows how to bundle the Chromium Embedded Framework into the app's `Contents/Frameworks/`. The stock `@tauri-apps/cli` / upstream `cargo-tauri` produces a bundle **without** `Frameworks/` and the app panics at startup inside `cef::library_loader::LibraryLoader::new` with `No such file or directory`. `yarn dev:app` (and every other `cargo tauri` script in `app/package.json`) now calls **`yarn tauri:ensure`** which runs [`scripts/ensure-tauri-cli.sh`](scripts/ensure-tauri-cli.sh) to install the vendored CLI into `~/.cargo/bin/cargo-tauri` on first use. If you ever install a different `tauri-cli` over it (e.g. `npm i -g @tauri-apps/cli`) you'll need to re-run the ensure script / `cargo install --locked --path app/src-tauri/vendor/tauri-cef/crates/tauri-cli`.
 - **macOS deep links**: Often require a built **`.app`** bundle; not only `tauri dev`. See [`docs/telegram-login-desktop.md`](docs/telegram-login-desktop.md) if applicable.
 - **`window.__TAURI__`**: Not assumed at module load; guard Tauri usage accordingly.
 - **Core sidecar**: Must be staged/built so `core_rpc` can reach the `openhuman` binary (see `scripts/stage-core-sidecar.mjs`).
diff --git a/README.md b/README.md
index 6d11e73da..2ee6076db 100644
--- a/README.md
+++ b/README.md
@@ -53,7 +53,7 @@ OpenHuman is an open-source agentic assistant that is designed to integrate with
 
 - **Deep desktop integrations** — OpenHuman is a **native desktop** assistant, not a web-only chat: **memory-aware keyboard autocomplete**, **voice** (**STT** listening and **TTS** replies), **screen intelligence** that understands what is on screen and feeds your local context, plus windowing and OS-level permissions—so the agent meets you **on the machine**, not trapped in a browser tab.
 
-Architecture: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). Contributor orientation: [`CONTRIBUTING.md`](./CONTRIBUTING.md).
+Architecture: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). Contributor orientation: [`CONTRIBUTING.md`](./CONTRIBUTING.md). Running from source: [`docs/install.md`](docs/install.md#running-from-source).
 
 ## OpenHuman vs other agents
 
diff --git a/app/package.json b/app/package.json
index 849682011..48f6531cc 100644
--- a/app/package.json
+++ b/app/package.json
@@ -5,21 +5,22 @@
   "scripts": {
     "dev": "vite",
     "dev:web": "vite",
-    "dev:app": "yarn core:stage && bash ../scripts/setup-chromium-safe-storage.sh && source ../scripts/load-dotenv.sh && APPLE_SIGNING_IDENTITY='OpenHuman Dev Signer' cargo tauri dev",
+    "dev:app": "yarn tauri:ensure && yarn core:stage && bash ../scripts/setup-chromium-safe-storage.sh && source ../scripts/load-dotenv.sh && APPLE_SIGNING_IDENTITY='OpenHuman Dev Signer' cargo tauri dev",
     "dev:cef": "yarn dev:app",
-    "dev:wry": "yarn core:stage && source ../scripts/load-dotenv.sh && cargo tauri dev --no-default-features --features wry",
+    "dev:wry": "yarn tauri:ensure && yarn core:stage && source ../scripts/load-dotenv.sh && cargo tauri dev --no-default-features --features wry",
     "core:stage": "node ../scripts/stage-core-sidecar.mjs",
+    "tauri:ensure": "bash ../scripts/ensure-tauri-cli.sh",
     "build": "tsc && vite build",
     "build:app": "tsc && vite build",
     "compile": "tsc --noEmit",
     "preview": "vite preview",
     "tauri": "tauri",
-    "tauri:build:ui": "cargo tauri build -- --bin OpenHuman",
-    "macos:build:intel": "source ../scripts/load-dotenv.sh && cargo tauri build --bundles app dmg --target x86_64-apple-darwin -- --bin OpenHuman",
-    "macos:build:intel:debug": "source ../scripts/load-dotenv.sh && cargo tauri build --debug --bundles app dmg --target x86_64-apple-darwin -- --bin OpenHuman",
-    "macos:build:debug": "source ../scripts/load-dotenv.sh && cargo tauri build --debug --bundles app dmg -- --bin OpenHuman",
-    "macos:build:release": "source ../scripts/load-dotenv.sh && cargo tauri build --bundles app dmg -- --bin OpenHuman",
-    "macos:build:release:signed": "source ../scripts/load-env.sh && cargo tauri build --bundles app dmg -- --bin OpenHuman",
+    "tauri:build:ui": "yarn tauri:ensure && cargo tauri build -- --bin OpenHuman",
+    "macos:build:intel": "yarn tauri:ensure && source ../scripts/load-dotenv.sh && cargo tauri build --bundles app dmg --target x86_64-apple-darwin -- --bin OpenHuman",
+    "macos:build:intel:debug": "yarn tauri:ensure && source ../scripts/load-dotenv.sh && cargo tauri build --debug --bundles app dmg --target x86_64-apple-darwin -- --bin OpenHuman",
+    "macos:build:debug": "yarn tauri:ensure && source ../scripts/load-dotenv.sh && cargo tauri build --debug --bundles app dmg -- --bin OpenHuman",
+    "macos:build:release": "yarn tauri:ensure && source ../scripts/load-dotenv.sh && cargo tauri build --bundles app dmg -- --bin OpenHuman",
+    "macos:build:release:signed": "yarn tauri:ensure && source ../scripts/load-env.sh && cargo tauri build --bundles app dmg -- --bin OpenHuman",
     "macos:build:sign:release": "yarn macos:build:release:signed",
     "macos:run": "open '../target/debug/bundle/macos/OpenHuman.app'",
     "macos:dev": "yarn macos:build:debug && open '../target/debug/bundle/macos/OpenHuman.app'",
diff --git a/docs/install.md b/docs/install.md
index d4ec4599e..e1b570604 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -181,6 +181,18 @@ echo "$(cat openhuman-core-${VERSION}-${TARGET}.tar.gz.sha256)  openhuman-core-$
 
 ---
 
+## Running from source
+
+The default runtime is **CEF** (bundled Chromium), which requires the **vendored CEF-aware `tauri-cli`** at `app/src-tauri/vendor/tauri-cef/crates/tauri-cli`. The stock `@tauri-apps/cli` does **not** know how to bundle the Chromium Embedded Framework into `OpenHuman.app/Contents/Frameworks/`, so a bundle produced by it panics at startup inside `cef::library_loader::LibraryLoader::new` with `No such file or directory`.
+
+All `cargo tauri` scripts in `app/package.json` (`yarn dev:app`, `yarn macos:build:*`, etc.) run [`scripts/ensure-tauri-cli.sh`](../scripts/ensure-tauri-cli.sh) first, which installs the vendored CLI into `~/.cargo/bin/cargo-tauri` on first use. If you ever overwrite it (e.g. `npm i -g @tauri-apps/cli` or `cargo install tauri-cli`), re-run:
+
+```bash
+cargo install --locked --path app/src-tauri/vendor/tauri-cef/crates/tauri-cli
+```
+
+---
+
 ## Release artifacts reference
 
 Each release attaches the following files:
diff --git a/scripts/ensure-tauri-cli.sh b/scripts/ensure-tauri-cli.sh
new file mode 100755
index 000000000..c971cd835
--- /dev/null
+++ b/scripts/ensure-tauri-cli.sh
@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Ensure the vendored CEF-aware tauri-cli is installed as `cargo-tauri`.
+#
+# The stock `@tauri-apps/cli` / upstream `tauri-cli` does NOT know how to bundle
+# the CEF (Chromium Embedded Framework) runtime into the `.app` bundle's
+# `Contents/Frameworks/` — so running `cargo tauri dev` with it produces an
+# `OpenHuman.app` that panics at startup inside
+# `cef::library_loader::LibraryLoader::new(...)` with:
+#   "No such file or directory" (Os { code: 2 })
+#
+# The vendored fork at `app/src-tauri/vendor/tauri-cef/crates/tauri-cli` has the
+# CEF bundler logic. Install it once and cargo will use it for every
+# `cargo tauri ...` invocation.
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+VENDOR_CLI="$ROOT_DIR/app/src-tauri/vendor/tauri-cef/crates/tauri-cli"
+VENDOR_CARGO_TOML="$VENDOR_CLI/Cargo.toml"
+
+if [[ ! -f "$VENDOR_CARGO_TOML" ]]; then
+  echo "[ensure-tauri-cli] vendored tauri-cli not found at $VENDOR_CLI" >&2
+  echo "[ensure-tauri-cli] did you forget to init the submodule? try:" >&2
+  echo "    git submodule update --init --recursive" >&2
+  exit 1
+fi
+
+# Detect whether the currently installed cargo-tauri came from our vendored path.
+CRATES_TOML="${CARGO_HOME:-$HOME/.cargo}/.crates.toml"
+if [[ -f "$CRATES_TOML" ]] && grep -q "tauri-cli.*$VENDOR_CLI" "$CRATES_TOML" 2>/dev/null; then
+  # Already installed from this exact path. Cargo won't rebuild unless sources change.
+  exit 0
+fi
+
+echo "[ensure-tauri-cli] installing vendored CEF-aware tauri-cli from $VENDOR_CLI"
+echo "[ensure-tauri-cli] (first install only — takes a few minutes; subsequent runs are instant)"
+cargo install --locked --path "$VENDOR_CLI"