diff --git a/src/docs/deployment.md b/src/docs/deployment.md
index 37bccba..86ea92f 100644
--- a/src/docs/deployment.md
+++ b/src/docs/deployment.md
@@ -74,6 +74,8 @@ cd src/xceadmin && pip install -e .
 ```
 `/xce-build xceadmin` always does a clean, non-editable `pip install` into an out-of-tree venv (`--system-site-packages`, inheriting nix-provided `pycapnp`/`pyyaml`/`jsonschema`), runs the full pytest suite, syncs the bundled schemas fresh from `src/schema/`, and produces a standalone `xceadmin` wrapper script — this is what ships in the AppImage and `nix build` output.
 
+**This venv only works from inside `nix develop ./src` (or the AppImage's bundled env) — it is not a portable, standalone venv.** `--system-site-packages` means `pip install` sees `click`/`pycapnp`/`pyyaml`/`jsonschema` already satisfied by nix's site-packages and skips vendoring its own copies — deliberately, since `pycapnp` is ABI-sensitive to the exact `capnproto` C library version, and letting pip resolve/build its own would risk a version mismatch that crashes at runtime. If you `source .venv/bin/activate` (or run the `xceadmin` binary directly) outside `nix develop`, none of those packages are on `sys.path` and you'll hit `ModuleNotFoundError: No module named 'click'` (or similar) immediately. Either stay inside `nix develop ./src` when invoking the built `xceadmin`, or use the AppImage, which bundles a working environment on `PATH` already.
+
 ### Usage
 
 ```bash