docs: reconcile env-variable semantics and server config docs with implementation (#5475)

## Bug Fix

### What was the bug?
Nightly reconciliation found multiple doc/implementation mismatches:
`MCP_GATEWAY_PORT/DOMAIN/API_KEY` were documented as automatic config
overrides (they are not), `tool_response_filters` was undocumented, and
contributor/example docs were missing or inaccurate in a few high-impact
spots.

### How did you fix it?
- **Environment variable behavior clarified (`AGENTS.md`)**
- Updated `MCP_GATEWAY_PORT`, `MCP_GATEWAY_DOMAIN`, and
`MCP_GATEWAY_API_KEY` descriptions to match actual runtime behavior
(validation/container checks vs. automatic gateway field override).
- Clarified `MCP_GATEWAY_PORT` vs plain `PORT` semantics in the note at
the end of the environment variable section.

- **Missing server field documentation added (`docs/CONFIGURATION.md`)**
  - Added `tool_response_filters` under server configuration fields.
- Documented expected shape (`map[toolName]jqExpression`) and startup
validation behavior for jq expressions.

- **Configuration example coverage expanded (`config.example.toml`)**
  - Added commented examples for:
    - `tool_response_filters`
    - `connect_timeout`
    - per-server `tool_timeout`
    - `rate_limit_threshold`
    - `rate_limit_cooldown`
    - HTTP `auth` (`github-oidc`)
    - `working_directory`
    - `registry`

- **Contributor docs corrected (`CONTRIBUTING.md`)**
  - Added missing direct dependency `github.com/spf13/pflag`.
  - Corrected project tree root label from `awmg/` to `gh-aw-mcpg/`.

### Testing
Docs-only change; no production logic changes.

```toml
# Example now documented in config.example.toml
[servers.github.tool_response_filters]
search_code = ".results[:20]"
get_file_contents = "{path: .path, sha: .sha}"
```

Author: lpcox

AGENTS.md

@@ -376,9 +376,9 @@ DEBUG_COLORS=0 DEBUG=* ./awmg --config config.toml
 - `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`
 - `ACTIONS_ID_TOKEN_REQUEST_URL` - GitHub Actions OIDC token endpoint URL; required for `github-oidc` auth type
 - `ACTIONS_ID_TOKEN_REQUEST_TOKEN` - GitHub Actions OIDC request token; required for `github-oidc` auth type
-- `MCP_GATEWAY_PORT` - Gateway listen port (overrides config `port` field; validated 1-65535)
-- `MCP_GATEWAY_DOMAIN` - Gateway domain name (overrides config `domain` field)
-- `MCP_GATEWAY_API_KEY` - Gateway API key (overrides config `api_key` field)
+- `MCP_GATEWAY_PORT` - Used by environment validation (`--validate-env`) for container port-mapping checks (validated 1-65535); does not override the gateway listen address
+- `MCP_GATEWAY_DOMAIN` - Used by environment validation (`--validate-env`) and containerized startup checks; to set config values use `gateway.domain` (or `"${MCP_GATEWAY_DOMAIN}"` in JSON stdin config)
+- `MCP_GATEWAY_API_KEY` - Used by environment validation (`--validate-env`) and containerized startup checks; to enable auth set `gateway.apiKey` (commonly `"${MCP_GATEWAY_API_KEY}"` in JSON stdin config)
 - `DEBUG` - Enable debug logging (e.g., `DEBUG=*`, `DEBUG=server:*,launcher:*`)
 - `DEBUG_COLORS` - Control colored output (0 to disable, auto-disabled when piping)
 - `MCP_GATEWAY_LOG_DIR` - Log file directory (sets default for `--log-dir` flag, default: `/tmp/gh-aw/mcp-logs`)
@@ -403,7 +403,7 @@ DEBUG_COLORS=0 DEBUG=* ./awmg --config config.toml
 - `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`)
 - `RUNNING_IN_CONTAINER` - Set to `"true"` to force container detection when `/.dockerenv` and cgroup detection are unavailable
 
-**Note:** `PORT`, `HOST`, and `MODE` are not read by the `awmg` binary directly. However, `run.sh` does use `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 `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

@@ -247,7 +247,7 @@ make clean
 ## Project Structure
 
 ```
-awmg/
+gh-aw-mcpg/
 ├── main.go                    # Entry point
 ├── go.mod                     # Dependencies
 ├── Dockerfile                 # Container image
@@ -425,6 +425,7 @@ DEBUG=server:* ./awmg --config config.toml   # Enable specific package
 The project uses:
 
 - `github.com/spf13/cobra` - CLI framework
+- `github.com/spf13/pflag` - POSIX/GNU-style flag parsing used by tracing and CLI integrations
 - `github.com/BurntSushi/toml` - TOML parser
 - `github.com/modelcontextprotocol/go-sdk` - MCP protocol implementation
 - `github.com/itchyny/gojq` - JQ schema processing

config.example.toml

@@ -75,6 +75,13 @@ GITHUB_PERSONAL_ACCESS_TOKEN = ""  # Pass through from host
 # tools = ["*"]                    # Allow all tools (default)
 # tools = ["read_file", "list_files"]  # Allow specific tools only
 
+# Optional: Per-tool response filters (jq expressions)
+# Transforms tool response payloads before they are returned and before large-payload
+# preview/schema processing runs.
+# [servers.github.tool_response_filters]
+# search_code = ".results[:20]"
+# get_file_contents = "{path: .path, sha: .sha}"
+
 # Optional: Guard policies for access control at the MCP gateway level
 # The structure is server-specific. For GitHub MCP server, this controls repository access.
 # Example: Restrict access to specific GitHub organization and repositories
@@ -143,6 +150,11 @@ args = [
 # (The [gateway.opentelemetry] and [gateway.tracing] sections DO support ${VAR} expansion.)
 [servers.custom]
 command = "docker"
+# Optional: Working directory for server process (currently parsed but not used by launcher)
+# working_directory = "/workspace"
+#
+# Optional: Informational URI to this server entry in an MCP registry
+# registry = "https://example.com/mcp-registry/servers/custom"
 args = [
     "run",
     "--rm",
@@ -157,11 +169,21 @@ args = [
 # [servers.http-example]
 # type = "http"
 # url = "https://example.com/mcp"
+# connect_timeout = 45       # Optional: Per-transport connect timeout in seconds (default: 30)
+# tool_timeout = 600         # Optional: Per-server tool timeout in seconds (default: gateway.tool_timeout)
+# rate_limit_threshold = 3   # Optional: Consecutive rate-limit errors before circuit opens
+# rate_limit_cooldown = 60   # Optional: Seconds before OPEN→HALF-OPEN probe
+# registry = "https://example.com/mcp-registry/servers/http-example"
 # 
 # Optional: HTTP headers for authentication
 # [servers.http-example.headers]
 # Authorization = "Bearer token123"
 # X-API-Key = "api-key-123"
+#
+# Optional: GitHub Actions OIDC auth for upstream HTTP server
+# [servers.http-example.auth]
+# type = "github-oidc"
+# audience = "https://example.com/mcp"
 
 # ============================================================================
 # Advanced Options

docs/CONFIGURATION.md

@@ -166,6 +166,17 @@ Run `./awmg --help` for full CLI options. Key flags:
   - Use `["*"]` (wildcard) to allow all tools (default behavior when field is omitted)
   - Example: `["get_file_contents", "search_code"]` (only these tools are accessible)
 
+- **`tool_response_filters`** (optional): Per-tool jq expressions that transform tool response data before it is returned to the agent and before large-payload preview/schema processing runs
+  - Map key: tool name; map value: jq expression string
+  - Expressions are validated at startup (compile check); invalid jq causes startup/config validation failure
+  - Example:
+    ```json
+    "tool_response_filters": {
+      "search_code": ".results[:20]",
+      "get_file_contents": "{path: .path, sha: .sha, content: .content}"
+    }
+    ```
+
 - **`registry`** (optional): Informational URI to the server's entry in an MCP registry
   - Used for documentation and discoverability purposes only; not used at runtime