From ef8fbca9b26c3cc4bf82cf08e564ed10697f3833 Mon Sep 17 00:00:00 2001
From: Florian Krebs <fkrebs@nucli.de>
Date: Fri, 22 May 2026 17:02:31 +0200
Subject: [PATCH] update README with extended parameters and v2 features

---
 README.md | 67 ++++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 47 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 26523d7..ad509e6 100644
--- a/README.md
+++ b/README.md
@@ -15,10 +15,11 @@ Anthropic API key.
 4. It parses the NDJSON stdout, computes text deltas from partial assistant
    messages, and re-emits them as OpenAI SSE chunks (or buffers for
    non-streaming).
-5. Usage totals from the `result` event are forwarded in the final response.
+5. Usage totals and cost from the `result` event are forwarded in the response.
 
-Authentication is handled entirely by the `claude` binary; the bridge just
-bind-mounts the existing `~/.claude` credentials directory.
+Authentication is handled entirely by the `claude` binary; the bridge
+bind-mounts the existing `~/.claude` credentials directory (rw, so the CLI
+can refresh expired OAuth tokens automatically).
 
 ## Environment variables
 
@@ -38,43 +39,68 @@ docker run -d \
   --name claude-max-bridge \
   -p 8000:8000 \
   -v /usr/local/bin/claude:/usr/local/bin/claude:ro \
-  -v /root/.claude:/root/.claude:ro \
+  -v /root/.claude:/root/.claude:rw \
+  -v /root/.claude.json:/root/.claude.json:rw \
   claude-max-bridge
 ```
 
 ## Supported models
 
 - `claude-sonnet-4-6` (default fallback)
-- `claude-opus-4-5`
+- `claude-opus-4-7`
 - `claude-haiku-4-5`
+- `claude-opus-4-5`
 - `claude-opus-4-0`
 - `claude-sonnet-3-7`
 - `claude-haiku-3-5`
+- Short aliases: `sonnet`, `opus`, `haiku`
 
-Unknown model names in requests fall back to `claude-sonnet-4-6`.
+Unknown model names fall back to `claude-sonnet-4-6`.
+
+## Extended parameters (`extra_body`)
+
+The bridge maps several CLI flags via the `extra_body` field:
+
+| `extra_body` key                          | CLI flag                               | Notes |
+|-------------------------------------------|----------------------------------------|-------|
+| `effort`                                  | `--effort <level>`                     | `low`/`medium`/`high`/`xhigh`/`max`. Overrides `temperature` mapping. |
+| `fallback_model`                          | `--fallback-model <model>`             | Model used when primary hits rate limit |
+| `system_prompt_mode`                      | `--system-prompt` / `--append-system-prompt` | `"replace"` (default) or `"append"` |
+| `max_turns`                               | `--max-turns <n>`                      | Cap agentic turns (non-interactive) |
+| `max_budget_usd`                          | `--max-budget-usd <amount>`            | Per-request cost cap |
+| `json_schema`                             | `--json-schema <schema>`               | Structured JSON output |
+| `exclude_dynamic_system_prompt_sections`  | `--exclude-dynamic-system-prompt-sections` | Better cache reuse for multi-user |
+
+`temperature` is also mapped to `--effort` when no explicit `effort` is set:
+`<0.2→low`, `<0.4→medium`, `<0.7→high`, `<0.9→xhigh`, `≥0.9→max`.
+
+`response_format.json_schema` (OpenAI standard) is also recognised and
+forwarded to `--json-schema` automatically.
+
+## Response extensions
+
+Non-streaming responses and streaming done-chunks include:
+
+| Field                  | Description |
+|------------------------|-------------|
+| `x_claude_cost_usd`    | Actual cost as reported by CLI (`total_cost_usd`). $0 for Max subscription. |
+| `x_claude_rate_limit`  | Rate-limit info: `utilization`, `resetsAt`, `rateLimitType` |
 
 ## LiteLLM configuration
 
-Add these entries to your `litellm_config.yaml`:
-
 ```yaml
 model_list:
   - model_name: claude-sonnet-4-6
     litellm_params:
       model: openai/claude-sonnet-4-6
       api_base: http://claude-max-bridge:8000/v1
-      api_key: "unused"           # required by LiteLLM but ignored by bridge
-
-  - model_name: claude-opus-4-5
-    litellm_params:
-      model: openai/claude-opus-4-5
-      api_base: http://claude-max-bridge:8000/v1
       api_key: "unused"
+      stream_timeout: 120
+      timeout: 120
+      input_cost_per_token: 0.000003    # for dashboard visibility; actual cost $0
+      output_cost_per_token: 0.000015
 ```
 
-Replace `claude-max-bridge` with the actual hostname or IP where the bridge
-container is running.
-
 ## Endpoints
 
 | Method | Path                   | Description                              |
@@ -85,8 +111,9 @@ container is running.
 
 ## Notes
 
-- `temperature`, `top_p`, and other sampling parameters are silently ignored
-  (logged at DEBUG level) because the CLI does not expose them.
 - Rate-limit responses from the CLI are translated to HTTP `429`.
-- Auth errors from the CLI are translated to HTTP `401`.
+- Auth errors are translated to HTTP `401`.
 - The subprocess is killed on client disconnect or timeout.
+- `top_p`, `frequency_penalty`, `presence_penalty`, `seed`, `stop`, `n` are ignored.
+- MCP servers are explicitly disabled (`--mcp-config '{"mcpServers":{}}'`
+  `--strict-mcp-config`) to prevent credential leakage and side-effects.