Reconcile docs with runtime behavior for env vars, launch flags, and config semantics (#5779)

Nightly reconciliation found drift between docs/comments and
implementation across environment variables, startup behavior, and
config field support. This PR aligns operator-facing docs and inline
config comments with current code paths to remove ambiguity in
day-to-day usage.

- **Environment variable reference alignment**
  - Added missing vars to `AGENTS.md`:
- `GITHUB_MCP_SERVER_TOKEN` (documented as highest-priority auth token)
- `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_SERVICE_NAME` (CLI default
sources for tracing flags)
- `AWMG_BINARY_PATH`, `AWMG_WASM_GUARD_PATH` (integration test
overrides)
- Corrected `run.sh` note in `AGENTS.md` to reflect actual priority:
`MCP_GATEWAY_PORT` first, then `PORT`.
- Updated `docs/ENVIRONMENT_VARIABLES.md` so `DOCKER_API_VERSION` is
documented under helper-script variables (not binary-consumed vars).

- **Launch/config discoverability**
- Documented `--sequential-launch` in both `AGENTS.md` and
`CONTRIBUTING.md`.
- Documented JSON stdin server `args` behavior in `AGENTS.md` (extra
Docker runtime args inserted before image).

- **Terminology and package description consistency**
  - Aligned `CONTRIBUTING.md` package descriptions with `AGENTS.md`:
    - `internal/guard`: `WriteSinkGuard` naming
- `internal/httputil`: “Shared HTTP helper utilities (server responses,
proxy transport)”

- **Config semantics clarification**
- Corrected `ServerConfig` comments for `RateLimitThreshold` and
`RateLimitCooldown` in `internal/config/config_core.go` to state
TOML-only support (not JSON stdin).

- **Example guidance cleanup**
- Added a clarifying comment in `config.example-payload-threshold.toml`
that `/tmp` there is a runtime data-dir example, distinct from agent
file-editing guidance.

```go
// Supported in TOML config only; the JSON stdin config does not currently accept this field.
RateLimitThreshold int `toml:"rate_limit_threshold" json:"rate_limit_threshold,omitempty"`

// Supported in TOML config only; the JSON stdin config does not currently accept this field.
RateLimitCooldown int `toml:"rate_limit_cooldown" json:"rate_limit_cooldown,omitempty"`
```

Author: lpcox

AGENTS.md

@@ -16,9 +16,10 @@ Quick reference for AI agents working with MCP Gateway (Go-based MCP proxy serve
 **Format**: `make format` (auto-format code with gofmt)  
 **Clean**: `make clean` (remove build artifacts)  
 **Agent-Finished**: `make agent-finished` (run format, build, lint, and all tests - ALWAYS run before completion)  
-**Run**: `./awmg --config config.toml`
-**Run with Custom Log Directory**: `./awmg --config config.toml --log-dir /path/to/logs`
-**Run with Custom Payload Directory**: `./awmg --config config.toml --payload-dir /path/to/payloads`
+**Run**: `./awmg --config config.toml`  
+**Run sequentially**: `./awmg --config config.toml --sequential-launch`  
+**Run with Custom Log Directory**: `./awmg --config config.toml --log-dir /path/to/logs`  
+**Run with Custom Payload Directory**: `./awmg --config config.toml --payload-dir /path/to/payloads`  
 
 ## Project Structure
 
@@ -97,6 +98,7 @@ args = ["run", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "-i", "ghcr.io/gith
 - Required fields: `container` for stdio, `url` for http
 - **Containerization Requirement**: TOML stdio servers must use `command = "docker"` per [MCP Gateway Specification Section 3.2.1](https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#321-containerization-requirement)
 - **Note**: In JSON stdin format, the `command` field is not supported - stdio servers must use `container` field
+- **Note**: In JSON stdin format, `args` is optional and provides extra Docker runtime arguments inserted before the container image name
 - Port range validation: 1-65535
 - Timeout validation: positive integers only
 
@@ -374,6 +376,7 @@ DEBUG_COLORS=0 DEBUG=* ./awmg --config config.toml
 
 ## Environment Variables
 
+- `GITHUB_MCP_SERVER_TOKEN` - Highest-priority GitHub auth token (takes precedence over `GITHUB_TOKEN`, `GITHUB_PERSONAL_ACCESS_TOKEN`, `GH_TOKEN`)
 - `GITHUB_PERSONAL_ACCESS_TOKEN` - GitHub auth
 - `GITHUB_API_URL` - Explicit GitHub API endpoint (e.g., `https://copilot-api.mycompany.ghe.com`); used by proxy to set upstream target
 - `GITHUB_SERVER_URL` - GitHub server URL; proxy auto-derives API endpoint: `*.ghe.com` → `copilot-api.*.ghe.com`, GHES → `<host>/api/v3`, `github.com` → `api.github.com`
@@ -404,9 +407,13 @@ DEBUG_COLORS=0 DEBUG=* ./awmg --config config.toml
 - `MCP_GATEWAY_TLS_KEY` - Path to TLS server private key PEM file; required when `MCP_GATEWAY_TLS_CERT` is set (sets default for `--tls-key`)
 - `MCP_GATEWAY_CA_CERT` - Path to CA certificate PEM file for client certificate verification; enables mutual TLS (mTLS) when set alongside `MCP_GATEWAY_TLS_CERT`/`MCP_GATEWAY_TLS_KEY` (sets default for `--tls-ca`)
 - `MCP_GATEWAY_HMAC_SECRET` - Shared HMAC-SHA256 secret for request signing and replay protection; when set, requests to MCP handlers must carry valid `X-MCP-Timestamp`, `X-MCP-Nonce`, and `X-MCP-Signature` headers (sets default for `--hmac-secret`)
+- `OTEL_EXPORTER_OTLP_ENDPOINT` - OTLP HTTP endpoint for trace export; sets default for `--otlp-endpoint`
+- `OTEL_SERVICE_NAME` - Service name in traces; sets default for `--otlp-service-name`
+- `AWMG_BINARY_PATH` - Override binary path for integration tests
+- `AWMG_WASM_GUARD_PATH` - Override WASM guard path for proxy integration tests
 - `RUNNING_IN_CONTAINER` - Set to `"true"` to force container detection when `/.dockerenv` and cgroup detection are unavailable
 
-**Note:** `MCP_GATEWAY_PORT` is read by the `awmg` binary for environment validation (`--validate-env`) only. Plain `PORT`, `HOST`, and `MODE` are not read by `awmg` directly. However, `run.sh` uses `PORT`, `HOST` (default: `0.0.0.0`), and `MODE` (default: `--routed`) to set the bind address and routing mode. Use the `--listen` and `--routed`/`--unified` flags when running `awmg` directly.
+**Note:** `MCP_GATEWAY_PORT` is read by the `awmg` binary for environment validation (`--validate-env`) only. Plain `PORT`, `HOST`, and `MODE` are not read by `awmg` directly. However, `run.sh` uses `MCP_GATEWAY_PORT` (falling back to `PORT`), `HOST` (default: `0.0.0.0`), and `MODE` (default: `--routed`) to set the bind address and routing mode. Use the `--listen` and `--routed`/`--unified` flags when running `awmg` directly.
 
 **File Logging:**
 - Operational logs are always written to log files in the configured log directory

CONTRIBUTING.md

@@ -175,6 +175,9 @@ echo '{"mcpServers": {...}}' | ./awmg --config-stdin
 # Increase verbosity
 ./awmg --config config.toml -v
 
+# Launch MCP servers sequentially during startup
+./awmg --config config.toml --sequential-launch
+
 # Custom payload directory and size threshold (payload dir must be absolute)
 ./awmg --config config.toml --payload-dir /tmp/payloads --payload-size-threshold 1048576
 ```
@@ -263,8 +266,8 @@ gh-aw-mcpg/
     ├── config/                # Configuration loading (TOML/JSON)
     ├── difc/                  # Decentralized Information Flow Control
     ├── envutil/               # Environment variable utilities
-    ├── guard/                 # Security guards (NoopGuard, WasmGuard, WriteSink)
-    ├── httputil/              # Shared HTTP response helpers
+    ├── guard/                 # Security guards (NoopGuard, WasmGuard, WriteSinkGuard)
+    ├── httputil/              # Shared HTTP helper utilities (server responses, proxy transport)
     ├── launcher/              # Backend server management
     ├── logger/                # Debug logging framework
     ├── mcp/                   # MCP protocol types & connection
@@ -289,7 +292,7 @@ gh-aw-mcpg/
 - **`internal/difc/`** - Decentralized Information Flow Control
 - **`internal/envutil/`** - Environment variable utilities
 - **`internal/guard/`** - Guard framework for resource labeling
-- **`internal/httputil/`** - Shared HTTP response helpers (JSON responses, error formatting)
+- **`internal/httputil/`** - Shared HTTP helper utilities (server responses, proxy transport)
 - **`internal/launcher/`** - Backend process management (Docker, stdio)
 - **`internal/logger/`** - Micro logger for debug output
 - **`internal/mcp/`** - MCP protocol types and JSON-RPC handling

config.example-payload-threshold.toml

@@ -17,6 +17,7 @@ api_key = "your-api-key-here"
 # - Flag: --payload-dir /custom/path
 # - Env:  MCP_GATEWAY_PAYLOAD_DIR=/custom/path
 # Default: /tmp/jq-payloads
+# Note: This runtime storage path may live under /tmp and is separate from any agent editing workspace.
 payload_dir = "/tmp/jq-payloads"
 
 # Payload path prefix for remapping file paths returned to clients

docs/ENVIRONMENT_VARIABLES.md

@@ -55,7 +55,12 @@ When using `run_containerized.sh`, these additional variables are available:
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `DOCKER_HOST` | Docker daemon socket path | `/var/run/docker.sock` |
-| `DOCKER_API_VERSION` | Docker API version (set by helper scripts, Docker client auto-negotiates) | Set by querying Docker daemon's current API version; falls back to `1.44` if detection fails |
+
+### Helper/CLI Docker Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `DOCKER_API_VERSION` | Docker API version used by helper scripts such as `run.sh`, integration test scripts, and `run_containerized.sh`. The Docker Go client in `awmg` auto-negotiates API version, but an exported `DOCKER_API_VERSION` can still affect `docker` CLI subprocesses launched with the inherited environment. | Set by querying Docker daemon's current API version; falls back to `1.44` if detection fails |
 
 ## GitHub Authentication
 

internal/config/config_core.go

@@ -252,13 +252,13 @@ type ServerConfig struct {
 	// RateLimitThreshold is the number of consecutive rate-limit errors from this backend
 	// that will trip the circuit breaker (transition CLOSED → OPEN). When OPEN, requests
 	// are immediately rejected until the cooldown period elapses. Default: 3.
-	// Supported in file-based config (TOML/JSON); stdin JSON config does not currently accept this field.
+	// Supported in TOML config only; the JSON stdin config does not currently accept this field.
 	RateLimitThreshold int `toml:"rate_limit_threshold" json:"rate_limit_threshold,omitempty"`
 
 	// RateLimitCooldown is the number of seconds the circuit breaker stays OPEN before
 	// allowing a single probe request (transition OPEN → HALF-OPEN). If the probe
 	// succeeds the circuit closes; if rate-limited again it re-opens. Default: 60.
-	// Supported in file-based config (TOML/JSON); stdin JSON config does not currently accept this field.
+	// Supported in TOML config only; the JSON stdin config does not currently accept this field.
 	RateLimitCooldown int `toml:"rate_limit_cooldown" json:"rate_limit_cooldown,omitempty"`
 }