From abab3ccbfcae5cf4fa53ddfa32530d93e21c7a35 Mon Sep 17 00:00:00 2001
From: Manmit Singh <manmits350@gmail.com>
Date: Tue, 30 Jun 2026 21:17:47 +0530
Subject: [PATCH] docs: clarify the headroom CLI is pip-only; npm headroom-ai
 is the TS SDK (#1585)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Description

`npm install headroom-ai` doesn't give you the `headroom` CLI — it's the
TypeScript SDK (a library, no `bin`). The README's "Get started" and
"Install" blocks listed the npm install next to the pip install and then
immediately ran `headroom wrap claude`, so Node/Windows users reasonably
expected npm to provide the CLI and hit `'headroom' is not recognized`.
This spells out the split: CLI = pip, SDK = npm.

The hnswlib/MSVC half of the report was already fixed on main in #1499
(moved hnswlib to the optional `[vector]` extra), so this PR only
addresses the npm-CLI confusion.

Closes #1470

## Type of Change

- [x] Documentation update

## Changes Made

- README "Get started" + "Install" blocks: annotate that pip ships the
`headroom` CLI and npm `headroom-ai` is the TS SDK with no CLI; note the
`headroom` commands come from the pip install.
- `docs/content/docs/installation.mdx`: state the TS SDK does not
install the `headroom` CLI.

## Testing

- [x] Manual testing performed

### Test Output

```text
Docs-only change. Verified against the source of truth:
- pyproject.toml: [project.scripts] headroom = "headroom.cli:main"  (CLI entry point is Python-only)
- sdk/typescript/package.json: name "headroom-ai", no "bin" field  (SDK, no CLI)
```

## Real Behavior Proof

- Environment: repo main @ HEAD
- Exact command / steps: read `[project.scripts]` in pyproject.toml and
the `bin` field in sdk/typescript/package.json
- Observed result: `headroom` console script is defined only by the
Python package; the npm package has no `bin`, so `npm install
headroom-ai` provides no `headroom` command — matching the issue.
- Not tested: n/a (no code paths changed)

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
---
 README.md                          | 12 +++++++-----
 docs/content/docs/installation.mdx |  2 +-
 2 files changed, 8 insertions(+), 6 deletions(-)

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