docs: fix env var discrepancies across markdown files

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

@@ -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 &

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
 ```
 
 ---

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:**

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
 ```
 
 ---

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.
 
 ---
 

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:

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://...
 ```
 
 ---

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
 ```
 

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` |

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:
 <key>EnvironmentVariables</key>
 <dict>
     <!-- Required: Proxy port -->
-    <key>HEADROOM_PROXY_PORT</key>
+    <key>HEADROOM_PORT</key>
     <string>8787</string>
 
     <!-- Optional: API key (or set in shell) -->
@@ -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
 ```