📚 Documentation Reconciliation Report - 2026-06-29

[github-actions]

Summary

Found 1 minor discrepancy between documentation and implementation during nightly reconciliation check.

• Workflow Run: §28408288822
• Date: 2026-06-29
• Branch: main

---

Minor Issues 🔵

Small inconsistencies or missing details:

1. config.example-payload-threshold.toml uses deprecated api_key field

Location: config.example-payload-threshold.toml, line 12
Problem: The example configuration uses the deprecated api_key field (api_key = "your-api-key-here") instead of the recommended agent_id.
Actual Behavior: At runtime this generates a deprecation warning in logs: "DEPRECATION: gateway.api_key is deprecated in TOML config; use gateway.agent_id instead"
Impact: Users who copy this file as a starting point (the README says "Looking for complete examples? See config.example-payload-threshold.toml") would see deprecation warnings and may be confused about whether their configuration is correct.
Suggested Fix: Replace api_key = "your-api-key-here" with agent_id = "" on line 12, matching the pattern used in config.example.toml (line 19).
Code Reference: internal/config/config_core.go:106-108 (deprecated alias handling)

---

Documentation Completeness

Accurate Sections ✅

All of the following were verified accurate against the implementation:

• README Quick Start — JSON config fields (type, container, env, agentId) are all valid struct fields; Docker run command flags are correct
• Default listen address — (127.0.0.1/redacted) matches DefaultListenIPv4 = "127.0.0.1"andDefaultListenPort = "3000"` in code
• TOML config format — All field names (command, args, servers, agent_id, payload_dir, etc.) match struct tags in internal/config/config_core.go
• JSON stdin format — All fields (agentId, container, entrypoint, entrypointArgs, args, mounts, env, type, url, headers, tools, guard-policies, connectTimeout, toolTimeout) are present in StdinServerConfig
• "local" type alias — Confirmed as alias for "stdio" in server_type.go
• Legacy snake_case timeout aliases — connect_timeout and tool_timeout accepted in JSON stdin via assignLegacyIntAlias
• TOML containerization requirement — command = "docker" enforced by validateTOMLStdioContainerization() in validation.go:482
• command not supported in JSON stdin — StdinServerConfig has no Command field; container required instead
• Go version requirement — go 1.25.0 matches go.mod
• Binary name — awmg matches BINARY_NAME=awmg in Makefile
• Environment variables — All documented env vars (MCP_GATEWAY_*, GITHUB_*, OTEL_*, GH_AW_*) verified present in code
• Default values — DefaultToolTimeout=60, DefaultStartupTimeout=30, DefaultPayloadSizeThreshold=524288, DefaultKeepaliveInterval=1500, DefaultTracingSampleRate=1.0 all match documentation
• --otlp-sample-rate range — 0.0–1.0 range matches flag description in tracing.go:39
• Session and shutdown timeouts — MCP_GATEWAY_SESSION_TIMEOUT default 6h and MCP_GATEWAY_SHUTDOWN_TIMEOUT default 5s match code
• JSONL schema constants — "rpc-message/v2", "rpc_request", "rpc_response", "difc-filtered/v2", "difc_filtered" all match jsonl_logger.go
• /close auth behavior — Auth-protected when agentId is configured; not HMAC-protected — confirmed in handlers.go:133-136
• /reflect unauthenticated — No auth wrapper applied in handlers.go:127-128
• Project directory structure — All 24 listed internal/ packages match actual filesystem layout
• run.sh behavior — Starts on (0.0.0.0/redacted) in routed mode — matches HOST="${HOST:-0.0.0.0}", PORT="${MCP_GATEWAY_PORT:-${PORT:-8000}}", MODE="${MODE:---routed}"`

Tested Make Targets ✅

All make targets mentioned in CONTRIBUTING.md exist in the Makefile:

• ✅ make build — creates awmg binary, runs go mod tidy first
• ✅ make test — alias for test-unit (test: test-unit)
• ✅ make test-unit — go test -v ./internal/...
• ✅ make test-integration — auto-builds binary if not present
• ✅ make test-all — rebuilds binary first (test-all: build), then go test -v ./...
• ✅ make test-race — go test -race ./internal/...
• ✅ make test-rust — runs Rust guard unit tests
• ✅ make lint — go vet, gofmt check, golangci-lint
• ✅ make coverage — go test -coverprofile=coverage.out ./internal/...
• ✅ make test-ci — unit tests with coverage and JSON output
• ✅ make format — gofmt -w .
• ✅ make clean — removes binary, coverage files
• ✅ make install — verifies Go, installs golangci-lint, downloads modules
• ✅ make agent-finished — format + build + lint + go test ./... + Rust guard tests

Note: Build Not Possible in CI Environment

make build could not be executed in this run because the Go module proxy (proxy.golang.org) is blocked. This is expected behavior in the network-restricted sandbox. See the note in CONTRIBUTING.md: "In network-restricted environments, ensure required modules are already cached or use direct go build -o awmg . when appropriate."

External Link Unverified

The upstream spec link https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md referenced in README and CONFIGURATION.md could not be verified due to network restrictions.

---

Recommendations

Immediate Actions Required:

1. In config.example-payload-threshold.toml, change line 12 from:

   api_key = "your-api-key-here"

   to:

   agent_id = ""

   This matches the pattern in config.example.toml and avoids deprecation warnings for users who copy this example.

---

Code References

• Config structs: internal/config/config_core.go
• Stdin config: internal/config/config_stdin.go
• Validation logic: internal/config/validation.go
• CLI flags: internal/cmd/flags_core.go, flags_logging.go, flags_launch.go, flags_tls.go
• Log format: internal/logger/jsonl_logger.go, global_state.go

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• proxy.golang.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "proxy.golang.org"

See Network Configuration for more information.

Generated by Nightly Documentation Reconciler · 228.8 AIC · ⊞ 5.2K · ◷

• expires on Jul 2, 2026, 11:11 PM UTC