From 42b1cd24de62449d47ebe46b9e26e10c758dfec1 Mon Sep 17 00:00:00 2001
From: pratikbin <68642400+pratikbin@users.noreply.github.com>
Date: Fri, 29 May 2026 15:04:13 +0530
Subject: [PATCH] docs: fix env var discrepancies across markdown files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Audit all .md files against codebase; fix wrong names, remove phantom
variables, and correct outdated values:
- HEADROOM_PROXY_PORT → HEADROOM_PORT (proxy.py envvar="HEADROOM_PORT")
- HEADROOM_BIND → HEADROOM_HOST + HEADROOM_PORT (RUST_DEV.md)
- HEADROOM_LEARN_{CLAUDE,CODEX,GEMINI}_ENABLED → HEADROOM_LEARN_CLI
(only HEADROOM_LEARN_CLI exists in learn/analyzer.py)
- HEADROOM_TRACING_ENABLED → HEADROOM_LANGFUSE_ENABLED=1 with correct
LANGFUSE_PUBLIC_KEY/SECRET_KEY vars (tracing.py)
- HEADROOM_LOG_LEVEL/LOG_FORMAT → --log-level CLI flag / RUST_LOG
(no HEADROOM_LOG_LEVEL var exists in code)
- HEADROOM_LOG_LEVEL/HEADROOM_STORE_URL/HEADROOM_DEFAULT_MODE rows
removed from wiki/configuration.md (all phantom)
- HEADROOM_SUMMARY_{ENABLED,THRESHOLD,RATIO} noted as not yet
implemented (no code exists)
- HEADROOM_DB_URL/HEADROOM_CACHE_BACKEND → explanatory notes pointing
to HEADROOM_WORKSPACE_DIR (no external DB support in code)
- HEADROOM_DB_PATH/HEADROOM_CACHE_PATH table rows replaced with actual
HEADROOM_WORKSPACE_DIR/CONFIG_DIR (paths.py)
---
RUST_DEV.md | 2 +-
docs/spec/005-integrations.md | 7 +++----
docs/spec/008-capabilities.md | 5 ++---
docs/spec/010-data.md | 11 +++++------
docs/spec/013-disaster-recovery.md | 5 +----
docs/spec/016-observability.md | 15 +++++++++------
docs/spec/017-operations.md | 13 +++++--------
examples/deployment/macos-launchagent/README.md | 2 +-
wiki/configuration.md | 3 ---
wiki/macos-deployment.md | 8 ++++----
10 files changed, 31 insertions(+), 40 deletions(-)
diff --git a/RUST_DEV.md b/RUST_DEV.md
index 68a6ea67f..45b9c78e7 100644
--- a/RUST_DEV.md
+++ b/RUST_DEV.md
@@ -67,7 +67,7 @@ curl -s http://127.0.0.1:8787/healthz/upstream # => 200 if upstream reachable
```bash
# 1. Move the Python proxy to a private port (e.g. 8788)
-HEADROOM_BIND=127.0.0.1:8788 python -m headroom.proxy & # or your existing launcher
+HEADROOM_HOST=127.0.0.1 HEADROOM_PORT=8788 python -m headroom.proxy & # or your existing launcher
# 2. Run the Rust proxy on the previously-public port (8787) pointing at it
./target/release/headroom-proxy --listen 0.0.0.0:8787 --upstream http://127.0.0.1:8788 &
diff --git a/docs/spec/005-integrations.md b/docs/spec/005-integrations.md
index 7fe9e2bb2..0763e5e1b 100644
--- a/docs/spec/005-integrations.md
+++ b/docs/spec/005-integrations.md
@@ -44,8 +44,7 @@ class ClaudeLearnPlugin(LearnPlugin, ConversationScanner):
**Configuration:**
```bash
-HEADROOM_LEARN_CLAUDE_ENABLED=true
-HEADROOM_LEARN_CLAUDE_SESSION_MODES=auto,learn,disabled
+HEADROOM_LEARN_CLI=claude
```
---
@@ -85,7 +84,7 @@ class CodexLearnPlugin(LearnPlugin, ConversationScanner):
**Configuration:**
```bash
-HEADROOM_LEARN_CODEX_ENABLED=true
+HEADROOM_LEARN_CLI=codex
```
---
@@ -125,7 +124,7 @@ class GeminiLearnPlugin(LearnPlugin, ConversationScanner):
**Configuration:**
```bash
-HEADROOM_LEARN_GEMINI_ENABLED=true
+HEADROOM_LEARN_CLI=gemini
```
---
diff --git a/docs/spec/008-capabilities.md b/docs/spec/008-capabilities.md
index acbc573e8..fabf11305 100644
--- a/docs/spec/008-capabilities.md
+++ b/docs/spec/008-capabilities.md
@@ -58,9 +58,8 @@ class CCRConfig:
**Configuration:**
```bash
-HEADROOM_SUMMARY_ENABLED=true
-HEADROOM_SUMMARY_THRESHOLD=5000 # tokens
-HEADROOM_SUMMARY_RATIO=0.3 # compress to 30%
+# Note: HEADROOM_SUMMARY_* env vars are not yet implemented.
+# Summary compression is currently configured programmatically only.
```
**Behavior:**
diff --git a/docs/spec/010-data.md b/docs/spec/010-data.md
index ca2aa5892..c1a75234d 100644
--- a/docs/spec/010-data.md
+++ b/docs/spec/010-data.md
@@ -93,9 +93,8 @@ CREATE TABLE compression_store (
| Variable | Default | Description |
|----------|---------|-------------|
-| `HEADROOM_DB_PATH` | `~/.headroom/` | Base path for databases |
-| `HEADROOM_DB_URL` | - | External database URL (overrides default) |
-| `HEADROOM_CACHE_PATH` | `~/.headroom/cache/` | Compression cache location |
+| `HEADROOM_WORKSPACE_DIR` | `~/.headroom` | Workspace root; all DBs live under this directory |
+| `HEADROOM_CONFIG_DIR` | `~/.headroom/config` | Config root (read-mostly: models.json, per-plugin config) |
### Cache
@@ -158,12 +157,12 @@ curl http://localhost:8787/stats
tar -czf headroom-backup.tar.gz ~/.headroom/
```
-### External Database
+### Storage Location
-Set `HEADROOM_DB_URL` for external storage:
+Relocate all storage by setting the workspace root:
```bash
-export HEADROOM_DB_URL=postgresql://user:pass@host:5432/headroom
+export HEADROOM_WORKSPACE_DIR=/mnt/state
```
---
diff --git a/docs/spec/013-disaster-recovery.md b/docs/spec/013-disaster-recovery.md
index 335482bf7..dcc5f6a08 100644
--- a/docs/spec/013-disaster-recovery.md
+++ b/docs/spec/013-disaster-recovery.md
@@ -51,10 +51,7 @@ sqlite3 ~/.headroom/headroom_memory.db ".backup /tmp/headroom_incremental.db"
### External Storage
-```bash
-export HEADROOM_DB_URL=postgresql://user:pass@host:5432/headroom
-export HEADROOM_CACHE_BACKEND=redis
-```
+> **Note:** External PostgreSQL/Redis storage is not yet implemented. Headroom uses SQLite at `~/.headroom/` (configurable via `HEADROOM_WORKSPACE_DIR`). The `HEADROOM_DB_URL` and `HEADROOM_CACHE_BACKEND` vars do not exist.
---
diff --git a/docs/spec/016-observability.md b/docs/spec/016-observability.md
index d9f797819..fae8b5fcf 100644
--- a/docs/spec/016-observability.md
+++ b/docs/spec/016-observability.md
@@ -36,11 +36,14 @@ scrape_configs:
OpenTelemetry tracing support.
-**Configuration:**
+**Configuration (Langfuse):**
```bash
-OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
-OTEL_SERVICE_NAME=headroom
-HEADROOM_TRACING_ENABLED=true
+LANGFUSE_PUBLIC_KEY=pk-lf-...
+LANGFUSE_SECRET_KEY=sk-lf-...
+HEADROOM_LANGFUSE_ENABLED=1
+# Optional: override endpoint and service name
+# LANGFUSE_BASE_URL=https://cloud.langfuse.com
+# HEADROOM_LANGFUSE_SERVICE_NAME=headroom
```
**Spans:**
@@ -78,8 +81,8 @@ HEADROOM_TRACING_ENABLED=true
**Configuration:**
```bash
-HEADROOM_LOG_LEVEL=INFO
-HEADROOM_LOG_FORMAT=json
+# Logging level is controlled via the --log-level CLI flag (headroom proxy --log-level debug)
+# or RUST_LOG env var for the Rust proxy. No HEADROOM_LOG_LEVEL env var exists.
```
Or in config:
diff --git a/docs/spec/017-operations.md b/docs/spec/017-operations.md
index 41f3c7a62..ec429ba10 100644
--- a/docs/spec/017-operations.md
+++ b/docs/spec/017-operations.md
@@ -66,16 +66,13 @@ curl http://localhost:8787/readyz
### Log Levels
-Set via environment:
+Set via CLI flag or `RUST_LOG` env var for the Rust proxy:
```bash
-HEADROOM_LOG_LEVEL=INFO
-```
+# Python proxy
+headroom proxy --log-level debug
-Or in config:
-```yaml
-logging:
- level: INFO
- format: json
+# Rust proxy
+RUST_LOG=debug headroom-proxy --upstream http://...
```
---
diff --git a/examples/deployment/macos-launchagent/README.md b/examples/deployment/macos-launchagent/README.md
index fa77796ea..37ea9bd8c 100644
--- a/examples/deployment/macos-launchagent/README.md
+++ b/examples/deployment/macos-launchagent/README.md
@@ -9,7 +9,7 @@ This directory contains templates and scripts for running the headroom proxy ser
./install.sh
# Add shell integration to ~/.bashrc or ~/.zshrc
-export HEADROOM_PROXY_PORT=8787
+export HEADROOM_PORT=8787
source /path/to/shell-integration.sh
```
diff --git a/wiki/configuration.md b/wiki/configuration.md
index d5808f9d3..15c9a515c 100644
--- a/wiki/configuration.md
+++ b/wiki/configuration.md
@@ -267,9 +267,6 @@ Some settings can be configured via environment variables:
| Variable | Description | Default |
|----------|-------------|---------|
-| `HEADROOM_LOG_LEVEL` | Logging level | `INFO` |
-| `HEADROOM_STORE_URL` | Database URL | temp directory |
-| `HEADROOM_DEFAULT_MODE` | Default mode | `optimize` |
| `HEADROOM_MODEL_LIMITS` | Custom model config (JSON string or file path) | - |
| `HEADROOM_CONFIG_DIR` | Canonical config (read-mostly) root. Derives `models.json` and per-plugin config paths when set. | `~/.headroom/config` |
| `HEADROOM_WORKSPACE_DIR` | Canonical workspace (read-write state) root. Derives savings ledger, memory DB, logs, TOIN, subscription state, and more when set. | `~/.headroom` |
diff --git a/wiki/macos-deployment.md b/wiki/macos-deployment.md
index 5e7e34350..19a577ba9 100644
--- a/wiki/macos-deployment.md
+++ b/wiki/macos-deployment.md
@@ -171,7 +171,7 @@ The default port is 8787. To use a custom port:
1. Uninstall: `./uninstall.sh`
2. Reinstall with new port: `./install.sh --port 9000`
-3. Update shell integration: `export HEADROOM_PROXY_PORT=9000`
+3. Update shell integration: `export HEADROOM_PORT=9000`
### Log Location
@@ -195,7 +195,7 @@ Configure additional options in the plist `EnvironmentVariables` section:
EnvironmentVariables
- HEADROOM_PROXY_PORT
+ HEADROOM_PORT
8787
@@ -235,7 +235,7 @@ Add to `~/.bashrc` (bash) or `~/.zshrc` (zsh):
```bash
# Configure port (optional, defaults to 8787)
-export HEADROOM_PROXY_PORT=8787
+export HEADROOM_PORT=8787
# Source shell integration
source /path/to/headroom/examples/deployment/macos-launchagent/shell-integration.sh
@@ -518,7 +518,7 @@ This will:
# Remove shell integration from ~/.bashrc or ~/.zshrc
# Delete or comment out:
-# export HEADROOM_PROXY_PORT=8787
+# export HEADROOM_PORT=8787
# source .../shell-integration.sh
```