diff --git a/docs/architecture/embedded-mpv-native.md b/docs/architecture/embedded-mpv-native.md
index 67a11a765..a8126967d 100644
--- a/docs/architecture/embedded-mpv-native.md
+++ b/docs/architecture/embedded-mpv-native.md
@@ -129,12 +129,10 @@ The Electron backend build consumes the staged runtime, copies Mach-O runtime fi
 For local development before the vendored runtime exists, Homebrew can be used explicitly:
 
 ```bash
-IPTVNATOR_EMBEDDED_MPV_ALLOW_HOMEBREW=1 \
-IPTVNATOR_ENABLE_EMBEDDED_MPV_EXPERIMENT=1 \
-pnpm nx serve electron-backend
+pnpm run serve:backend:embedded-mpv
 ```
 
-This path is intentionally development-only. Packaged macOS builds reject `homebrew-dev` manifests and any `/opt/homebrew` or `/usr/local` embedded MPV links.
+That script first runs the local native build with `IPTVNATOR_EMBEDDED_MPV_ALLOW_HOMEBREW=1`, then starts Electron with `IPTVNATOR_ENABLE_EMBEDDED_MPV_EXPERIMENT=1`. This path is intentionally development-only. Packaged macOS builds reject `homebrew-dev` manifests and any `/opt/homebrew` or `/usr/local` embedded MPV links.
 
 If the settings page does not show `Embedded MPV (Experimental, macOS)` after starting with those flags, check the native build output:
 
@@ -142,7 +140,7 @@ If the settings page does not show `Embedded MPV (Experimental, macOS)` after st
 ls apps/electron-backend/native/build/Release/embedded_mpv.node
 ```
 
-If only `embedded-mpv-unavailable.txt` exists, the dev app started from a build where no runtime was available. Stop the Electron dev process and restart it with the flags. The native MPV build target is intentionally uncached because it depends on local runtime files and environment variables such as `IPTVNATOR_EMBEDDED_MPV_ALLOW_HOMEBREW` and `IPTVNATOR_EMBEDDED_MPV_ARCH`.
+If only `embedded-mpv-unavailable.txt` exists, the dev app started from a build where no runtime was available. Stop the Electron dev process and rerun `pnpm run serve:backend:embedded-mpv` so the native target is rebuilt before Electron starts. The native MPV build target is intentionally uncached because it depends on local runtime files and environment variables such as `IPTVNATOR_EMBEDDED_MPV_ALLOW_HOMEBREW` and `IPTVNATOR_EMBEDDED_MPV_ARCH`.
 
 If opening Settings hard-crashes Electron on macOS and the crash report says `Code Signature Invalid`, one of the copied runtime binaries was modified by `install_name_tool` without being re-signed. Rebuild the native target and verify the copied addon/runtime files:
 
diff --git a/tools/embedded-mpv/README.md b/tools/embedded-mpv/README.md
index 4d9e6b74b..f1dde6138 100644
--- a/tools/embedded-mpv/README.md
+++ b/tools/embedded-mpv/README.md
@@ -70,6 +70,14 @@ The build manifest records source URLs, downloaded archive SHA-256 values where
 
 `apps/electron-backend/build-embedded-mpv.js` links the native addon against the staged runtime, copies dylibs into `apps/electron-backend/native/build/Release/lib/`, rewrites Mach-O paths to `@loader_path`, and writes `embedded-mpv-runtime.json`.
 
+For local macOS development with Homebrew `mpv`, use:
+
+```bash
+pnpm run serve:backend:embedded-mpv
+```
+
+The script rebuilds the native addon with `IPTVNATOR_EMBEDDED_MPV_ALLOW_HOMEBREW=1` before starting Electron with the experimental player enabled. Use this only for local testing; release packaging rejects the resulting `homebrew-dev` runtime manifest.
+
 The macOS `afterPack` hook copies `dist/apps/electron-backend/native/` into `app.asar.unpacked/electron-backend/native/` so the addon, runtime manifest, dylibs, and non-`.dylib` Mach-O runtime files are available as real files. Linux and Windows artifacts do not include that native directory.
 
 During release packaging, `tools/packaging/electron-after-pack.cjs` verifies that the packaged app uses a `vendored-lgpl` runtime and has no `/opt/homebrew` or `/usr/local` dynamic links for embedded MPV.