diff --git a/docs/proxy.md b/docs/proxy.md
index 752462868..2dc58091b 100644
--- a/docs/proxy.md
+++ b/docs/proxy.md
@@ -248,7 +248,12 @@ Or with Docker:
 
 ```dockerfile
 FROM python:3.11-slim
-RUN pip install headroom[proxy]
+RUN apt-get update && apt-get install -y --no-install-recommends build-essential \
+    && pip install "headroom-ai[proxy]" \
+    && apt-get purge -y build-essential && apt-get autoremove -y \
+    && rm -rf /var/lib/apt/lists/*
 EXPOSE 8787
 CMD ["headroom", "proxy", "--host", "0.0.0.0"]
 ```
+
+> **Note:** `build-essential` is required at install time because `headroom-ai` includes `hnswlib`, a C++ extension that must be compiled from source. It is removed after installation to keep the image slim.
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 1524a87b5..e2af281c4 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -219,6 +219,39 @@ client = HeadroomClient(
 
 ## Import/Installation Issues
 
+### "pip install fails with C++ compilation error"
+
+**Symptom**: Installation fails with an error like:
+
+```
+RuntimeError: Unsupported compiler -- at least C++11 support is needed!
+ERROR: Failed building wheel for hnswlib
+```
+
+**Cause**: `headroom-ai` depends on `hnswlib`, a C++ extension that must be compiled from source. Slim environments (Docker slim images, minimal CI runners) lack the required build tools.
+
+**Solutions**:
+
+```bash
+# Linux / Debian-based (including Docker)
+apt-get install -y build-essential && pip install headroom-ai
+
+# macOS (Xcode command line tools)
+xcode-select --install && pip install headroom-ai
+```
+
+In a Dockerfile, install and remove build tools in one layer to keep the image slim:
+
+```dockerfile
+FROM python:3.11-slim
+RUN apt-get update && apt-get install -y --no-install-recommends build-essential \
+    && pip install "headroom-ai[proxy]" \
+    && apt-get purge -y build-essential && apt-get autoremove -y \
+    && rm -rf /var/lib/apt/lists/*
+```
+
+---
+
 ### "ModuleNotFoundError: No module named 'headroom'"
 
 ```bash