Docs: rewrite documentation for concise, natural engineering prose

.env.example

@@ -1,74 +1,60 @@
-# Copy to .env and set the gateway URL. Docker Compose reads .env automatically.
-# After changes, run: docker compose up -d
-# Setup: README.md. Full reference: docs/CONFIGURATION.md.
-# The native binary reads process environment variables, not this file.
+# Copy to .env and set PROXY_UPSTREAM_URL. Docker Compose loads .env automatically.
+# Apply changes with: docker compose up -d
+# Note: the native binary reads process environment variables directly, not .env.
+# Docs: README.md (setup) | docs/CONFIGURATION.md (full reference)
 
-# Required. The proxy appends the client path, such as /v1/messages, to this URL.
-# Use http(s)://host[:port][/prefix], usually without a trailing /v1.
+# Required. Gateway root URL (http/https, optional path prefix, usually no trailing /v1).
+# Incoming paths like /v1/messages are appended directly to this URL.
 PROXY_UPSTREAM_URL=
 
-# Compose runs as 1000:1000 by default. If your host IDs differ, uncomment these
-# and use the results of `id -u` and `id -g` so archive files are owned by you.
+# Host user/group IDs for container file ownership (used when writing ./logs).
+# Uncomment and set to `id -u` / `id -g` if your host user is not 1000:1000.
 #UID=1000
 #GID=1000
 
-# Anthropic Messages: buffer for up to 10 minutes, then stream live.
-# Keep client timeouts above this window. For Claude Code, use settings.json:
+# Anthropic Messages buffering window (10m default).
+# Client timeouts must exceed this value. In ~/.claude/settings.json:
 #   CLAUDE_CODE_CONNECT_TIMEOUT_MS=660000
 #   API_TIMEOUT_MS=720000
 #   API_FORCE_IDLE_TIMEOUT=0
-# Header waits, retries, backoff, and fallback all share this one window.
 PROXY_KEEPALIVE_MS=600000
 
-# Claude Code Workflow agents use a shorter window to avoid their content watchdog.
-# Keep this below the script's stallMs. Pings do not count as progress, so a long
-# gap in actual upstream content may still need a larger script-side stallMs.
-# 0 disables the timed switch to live output for Workflow requests.
+# Claude Code Workflow agent window (10s default). Keeps buffering below the
+# Workflow runtime's content-stall watchdog (stallMs). 0 disables the timed live switch.
 PROXY_WORKFLOW_KEEPALIVE_MS=10000
 
-# Abort an upstream SSE stream or error-body read after 10 minutes without bytes.
+# Abort an upstream SSE stream or error read after 10m with no bytes received.
 PROXY_UPSTREAM_BYTE_IDLE_MS=600000
 
-# OpenAI Responses: default mode streams as soon as output arrives. This window
-# bounds a silent start; the client's stream idle timeout must exceed it.
+# OpenAI Responses silent-start window (30s default) when early commit is enabled.
 PROXY_RESPONSES_KEEPALIVE_MS=30000
 
-# With early commit disabled, Responses buffers under this independent window.
-# The client's stream idle timeout must exceed it. For Codex, use
-# stream_idle_timeout_ms=660000 to cover the default.
+# OpenAI Responses full-buffering window (10m default) when early commit is disabled.
+# Set Codex stream_idle_timeout_ms=660000 to cover this window.
 PROXY_RESPONSES_BUFFER_MS=600000
 
-# Set 0 to buffer Responses until completion or the window ends. This protects
-# against later stream failures, but delays visible output while buffering.
+# Set to 0 to buffer Responses streams until completion (or the buffer window ends).
 #PROXY_RESPONSES_EARLY_COMMIT=1
 
-# Native Gemini streamGenerateContent?alt=sse: buffer through clean completion,
-# then replay unchanged. Client timeouts must exceed this window. 0 keeps full
-# buffering without a timed live switch; upstream idle/request deadlines remain.
+# Native Gemini streamGenerateContent?alt=sse buffering window (10m default).
+# 0 buffers until completion without a timed live switch.
 PROXY_GEMINI_BUFFER_MS=600000
 
-# Extra attempts for recoverable streaming failures before sending a response.
-# 0 retains only one limited fast retry for selected connection/HTTP failures.
-# Positive values enable broader retries on Messages, Responses, and Gemini SSE.
+# Extra in-proxy retries for recoverable streaming failures before commit.
+# 0 keeps only a single fast retry (<3s failure, 250ms wait) for connection/HTTP errors.
 PROXY_TRANSACTIONAL_LOCAL_RETRIES=0
 
-# Local retries wait for upstream Retry-After plus an exponential extra delay.
-# This caps only the extra delay, not the upstream-requested wait.
+# Cap on the exponential backoff added on top of upstream Retry-After during local retries.
 PROXY_LOCAL_RETRY_EXTRA_BACKOFF_CAP_MS=10000
 
-# Backstop based on X-Stainless-Retry-Count; it does not raise client retry limits.
-# Clients without this header, including Codex, must enforce their own limit.
-# 0 disables retry conversion and local retries, but not model fallback.
+# Backstop on X-Stainless-Retry-Count (does not raise client retry limits; ignored by
+# clients that do not send the header, such as Codex). 0 disables retry conversion.
 #PROXY_SDK_RETRY_CAP=100
 
-# Anthropic only: before sending a response, retry a structured refusal or a
-# recognized Fable safeguards error with this model. All other fields retain
-# their values. The substitution happens at most once per client request.
-# Choose a model your gateway supports. off / none / disabled / empty disables it.
+# Anthropic only: retry pre-commit structured refusals or recognized Fable safeguard
+# errors once with this model. Set to off, none, disabled, or empty to disable.
 #PROXY_REFUSAL_FALLBACK_MODEL=claude-opus-5
 
-# Optional full payload archives. Under Compose, ./logs maps to the host's logs.
-# Known credential headers and query parameters are redacted, but bodies are
-# preserved unencrypted. There is no rotation or retention; disable capture after
-# debugging or manage retention yourself. See docs/OPERATIONS.md.
+# Optional directory for full JSON request/response archives (mapped to ./logs in Compose).
+# Archives are unencrypted (auth headers/params redacted, bodies raw) with no auto-retention.
 #PROXY_REQUEST_LOG_DIR=./logs