diff --git a/README.md b/README.md
index 8e26ec8f8..ce7b7655a 100644
--- a/README.md
+++ b/README.md
@@ -87,10 +87,10 @@ Headroom compresses everything your AI agent reads — tool outputs, logs, RAG c
 
 ```bash
 # 1 — Install
-pip install "headroom-ai[all]"          # Python
-npm install headroom-ai                 # Node / TypeScript
+pip install "headroom-ai[all]"          # Python — ships the `headroom` CLI
+npm install headroom-ai                 # TypeScript SDK only — no `headroom` CLI
 
-# 2 — Pick your mode
+# 2 — Pick your mode  (the `headroom` commands below come from the pip install)
 headroom wrap claude                    # wrap a coding agent
 headroom proxy --port 8787              # drop-in proxy, zero code changes
 # or: from headroom import compress      # inline library
@@ -101,6 +101,8 @@ headroom perf
 headroom dashboard                      # live savings dashboard (proxy must be running)
 ```
 
+The `headroom` CLI ships **only** via the PyPI package. The npm `headroom-ai` is the TypeScript SDK — a library you import (`import { compress } from 'headroom-ai'`), not a CLI, so it provides no `headroom` command.
+
 Granular extras: `[proxy]`, `[mcp]`, `[ml]`, `[code]`, `[memory]`, `[vector]` (optional HNSW backend — needs a C++ toolchain, not in `[all]`), `[relevance]`, `[image]`, `[agno]`, `[langchain]`, `[evals]`, `[pytorch-mps]` (Apple-GPU memory-embedder offload — set `HEADROOM_EMBEDDER_RUNTIME=pytorch_mps`). Requires **Python 3.10+**.
 
 ## Proof
@@ -319,8 +321,8 @@ Everything in this repo stays open source (Apache 2.0). The managed offering is
 ## Install
 
 ```bash
-pip install "headroom-ai[all]"          # Python, everything
-npm install headroom-ai                 # TypeScript / Node
+pip install "headroom-ai[all]"          # Python, everything — includes the `headroom` CLI
+npm install headroom-ai                 # TypeScript SDK (library only — no `headroom` CLI)
 docker pull ghcr.io/chopratejas/headroom:latest
 ```
 
diff --git a/docs/content/docs/installation.mdx b/docs/content/docs/installation.mdx
index b09dd2596..ee3bbae0c 100644
--- a/docs/content/docs/installation.mdx
+++ b/docs/content/docs/installation.mdx
@@ -127,7 +127,7 @@ python -c "import headroom; print(headroom.__version__)"
 
 ## TypeScript / Node.js
 
-The TypeScript SDK is published as `headroom-ai` on npm. It requires **Node.js 18+**.
+The TypeScript SDK is published as `headroom-ai` on npm. It requires **Node.js 18+**. It is a library you import — it does **not** install the `headroom` CLI (`headroom wrap`, `headroom proxy`, etc.), which ships only with the Python package above.
 
 ```bash
 npm install headroom-ai