diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f615abbc4..cb047ea0e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -5,7 +5,7 @@ Thank you for your interest in contributing to MCP Gateway! This document provid
 ## Prerequisites
 
 1. **Docker** installed and running
-2. **Go 1.26.4 or later** (see [installation instructions](https://go.dev/dl/))
+2. **Go 1.26.4** (see [installation instructions](https://go.dev/dl/))
 3. **Make** for running build commands
 
 ## Getting Started
@@ -190,8 +190,13 @@ Or run manually:
 # Run with TOML config
 ./awmg --config config.toml
 
-# Run with JSON stdin config
-echo '{"mcpServers": {...}}' | ./awmg --config-stdin
+# Run with JSON stdin config (the CLI requires --config or --config-stdin)
+# The JSON schema requires a top-level "gateway" object with port, domain,
+# and one of agentId or apiKey before any server is started.
+echo '{
+  "gateway": {"port": 3000, "domain": "localhost", "agentId": "your-agent-id"},
+  "mcpServers": {"github": {"type": "stdio", "container": "ghcr.io/github/github-mcp-server:latest"}}
+}' | ./awmg --config-stdin
 ```
 
 ### Advanced Flags
@@ -602,7 +607,7 @@ The container uses `run_containerized.sh` as the entrypoint, which:
 - Requires the `-i` flag for JSON configuration via stdin
 - Requires `MCP_GATEWAY_PORT` and `MCP_GATEWAY_DOMAIN`, plus an agent gate value via `MCP_GATEWAY_AGENT_ID` (`MCP_GATEWAY_API_KEY` is only a deprecated alias that `run_containerized.sh` maps to `MCP_GATEWAY_AGENT_ID`; reference `"gateway": {"agentId": "${MCP_GATEWAY_AGENT_ID}"}` in your JSON config to enable authentication)
 - Queries the Docker daemon API version (falls back to 1.44)
-- Validates Docker socket, port mapping, and environment before starting
+- Validates Docker socket and environment before starting; validates port mapping only when the container ID can be determined and host networking is not in use
 
 See `config.json` for an example JSON configuration file.
 
diff --git a/README.md b/README.md
index 9166a0b9b..50ce89702 100644
--- a/README.md
+++ b/README.md
@@ -31,7 +31,7 @@ This gateway is used with [GitHub Agentic Workflows](https://github.com/github/g
    }
    ```
 
-   Note: In JSON stdin config, `gateway.port`, `gateway.domain`, and one of `gateway.agentId` or `gateway.apiKey` are schema-required fields.
+   Note: The JSON schema requires a top-level `gateway` object containing `port`, `domain`, and one of `agentId` or `apiKey`. All three are validated before any server is started.
 
    Looking for complete examples? See [`config.example.toml`](config.example.toml), [`config.example-payload-threshold.toml`](config.example-payload-threshold.toml), and [`example-http-config.json`](example-http-config.json).
 
@@ -48,7 +48,7 @@ This gateway is used with [GitHub Agentic Workflows](https://github.com/github/g
    ```
 
 > [!NOTE]
-> The container entrypoint script (`run_containerized.sh`) automatically adds `--config-stdin` when it starts `awmg`. If you run `awmg` directly (outside the container) and want to pipe JSON config, you must pass `--config-stdin` explicitly.
+> The CLI requires either `--config` or `--config-stdin`; piping JSON configuration requires `--config-stdin`. The container entrypoint script (`run_containerized.sh`) automatically adds `--config-stdin` when it starts `awmg`. If you run `awmg` directly (outside the container) and want to pipe JSON config, you must pass `--config-stdin` explicitly.
 
 Inside the container, the gateway starts in routed mode on `http://0.0.0.0:8000`, proxying MCP requests to your configured backend servers. When running `awmg` directly without `--listen`, the default listen address is `http://127.0.0.1:3000`.
 
@@ -122,7 +122,7 @@ The gateway supports OpenTelemetry distributed tracing. Set these variables to e
 | `GH_AW_OTLP_ENDPOINTS` | Comma-separated OTLP URLs (or JSON array with per-endpoint `headers`) for multi-backend fan-out; all listed endpoints receive every span. Takes precedence over `OTEL_EXPORTER_OTLP_ENDPOINT`. |
 | `OTEL_SERVICE_NAME` | Service name reported in traces (default: `mcp-gateway`) |
 
-Use `--otlp-sample-rate <float>` to control trace sampling (range `0.0`–`1.0`, default `1.0`).
+Use `--otlp-sample-rate <float>` to control trace sampling (range `0.0`–`1.0`, default `1.0`). Note: unlike `--otlp-endpoint` and `--otlp-service-name`, `--otlp-sample-rate` has no environment-variable fallback and can only be set via this flag or TOML `sample_rate` under `[gateway.opentelemetry]` (preferred) or legacy `[gateway.tracing]`; it is not supported in JSON stdin config.
 
 See [`docs/ENVIRONMENT_VARIABLES.md`](docs/ENVIRONMENT_VARIABLES.md) for full details.