diff --git a/README.md b/README.md
index cf8a45b62..db130526d 100644
--- a/README.md
+++ b/README.md
@@ -104,7 +104,14 @@ The `install` command auto-detects all installed coding agents and configures MC
 
 ### Graph Visualization UI
 
-If you downloaded the `ui` variant:
+The UI ships as a separate `ui` build (it embeds the frontend). The default install on every channel is the lean, headless server; opt into the UI build with:
+
+- **install.sh:** add `--ui` (see [Quick Start](#quick-start))
+- **npm:** `CBM_VARIANT=ui npm install -g codebase-memory-mcp`
+- **PyPI:** `CBM_VARIANT=ui pip install codebase-memory-mcp`
+- **Manual:** download the `codebase-memory-mcp-ui-<os>-<arch>` archive
+
+Then run it:
 
 ```bash
 codebase-memory-mcp --ui=true --port=9749
diff --git a/pkg/npm/install.js b/pkg/npm/install.js
index 0b960ef0e..25bb6a80f 100644
--- a/pkg/npm/install.js
+++ b/pkg/npm/install.js
@@ -109,10 +109,14 @@ async function main() {
   // dynamically links glibc 2.38+ and fails on older distros. macOS/Windows
   // have no such variant. Keep in sync with install.sh / pypi _cli.py / cli.c.
   const variant = platform === 'linux' ? '-portable' : '';
-  const archive = `codebase-memory-mcp-${platform}-${arch}${variant}.${ext}`;
+  // Opt into the UI build (embedded graph visualization) with CBM_VARIANT=ui.
+  // Default is the standard (headless) build. Mirrors install.sh --ui.
+  const ui = (process.env.CBM_VARIANT || '').toLowerCase() === 'ui' ? 'ui-' : '';
+  const archive = `codebase-memory-mcp-${ui}${platform}-${arch}${variant}.${ext}`;
   const url = `https://github.com/${REPO}/releases/download/v${VERSION}/${archive}`;
 
-  process.stdout.write(`codebase-memory-mcp: downloading v${VERSION} for ${platform}/${arch}...\n`);
+  const uiLabel = ui ? '(ui) ' : '';
+  process.stdout.write(`codebase-memory-mcp: downloading v${VERSION} ${uiLabel}for ${platform}/${arch}...\n`);
 
   const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cbm-install-'));
   const tmpArchive = path.join(tmpDir, `cbm.${ext}`);
diff --git a/pkg/pypi/src/codebase_memory_mcp/_cli.py b/pkg/pypi/src/codebase_memory_mcp/_cli.py
index 2ed915e49..d192f1352 100644
--- a/pkg/pypi/src/codebase_memory_mcp/_cli.py
+++ b/pkg/pypi/src/codebase_memory_mcp/_cli.py
@@ -157,7 +157,10 @@ def _download(version: str) -> Path:
     # dynamically links glibc 2.38+ and fails on older distros. macOS/Windows
     # have no such variant. Keep in sync with install.sh / install.js / cli.c.
     variant = "-portable" if os_name == "linux" else ""
-    archive = f"codebase-memory-mcp-{os_name}-{arch}{variant}.{ext}"
+    # Opt into the UI build (embedded graph visualization) with CBM_VARIANT=ui.
+    # Default is the standard (headless) build. Mirrors install.sh --ui.
+    ui = "ui-" if os.environ.get("CBM_VARIANT", "").lower() == "ui" else ""
+    archive = f"codebase-memory-mcp-{ui}{os_name}-{arch}{variant}.{ext}"
     url = f"https://github.com/{REPO}/releases/download/v{version}/{archive}"
     _validate_url_scheme(url)