📚 Documentation Reconciliation Report - 2026-07-29 #10373

Summary

Found 7 discrepancies between documentation and implementation during nightly reconciliation check.

• Workflow Run: §30498041859
• Date: 2026-07-29
• Branch: main

Critical Issues 🔴

Issues that would cause user confusion or broken workflows if followed:

1. Gateway Quick Start implies required fields that are optional; dockerless undocumented in field table

Location: README.md, Quick Start section (lines ~34, 58)
Problem: README implies gateway.port, gateway.domain, and agentId/apiKey are required in JSON stdin config; gateway.dockerless is advertised in Quick Start but not listed in the Gateway Configuration field table.
Actual Behavior: Gateway validation only checks optional fields when present; JSON configs can omit gateway entirely and defaults are applied. dockerless, containerRuntime, containerRuntimeCommand, and containerRuntimeArgs are all implemented and validated.
Impact: Users may add unnecessary fields thinking they are required, or fail to find dockerless in the field reference.
Suggested Fix: Change Quick Start note to say those fields are recommended/example values, not universally required. Add dockerless, containerRuntime, containerRuntimeCommand, and containerRuntimeArgs to the Gateway Configuration field table.
Code Reference: internal/config/validation_gateway.go:10-93, internal/config/config_stdin.go:36-58

2. README claims sample_rate can be set via TOML/JSON config, but the field does not exist in config structs

Location: README.md, OpenTelemetry/Tracing section (line ~126)
Problem: README claims --otlp-sample-rate can be set via sample_rate under [gateway.opentelemetry] or [gateway.tracing] in TOML/JSON config.
Actual Behavior: TracingConfig supports endpoint, traceId, spanId, serviceName, headers — no sample_rate field is present in any config struct. Sample rate is CLI-flag only.
Impact: Users who try to set sample_rate in config will silently have it ignored, causing unexpected behavior.
Suggested Fix: Remove the sample_rate config claim from the TOML/JSON sections, or add the field to the implementation.
Code Reference: internal/cmd/tracing.go:32-40, internal/config/config_tracing.go, internal/config/config_stdin.go:82-95

3. CONTRIBUTING.md incorrectly states integration tests require manually building first

Location: CONTRIBUTING.md, lines ~520, 530–531
Problem: States that integration tests require building the binary first / running make build.
Actual Behavior: make test-integration auto-builds awmg if the binary is missing. Only make test-all is described as "always builds first."
Impact: Users may perform redundant manual steps or misunderstand the testing workflow.
Suggested Fix: Reword to: "Integration tests use the compiled binary and auto-build it if not present. Use make test-all to always rebuild before running both test suites."
Code Reference: Makefile:66-73

Important Issues 🟡

Issues that are misleading but have workarounds:

4. Gateway Configuration table omits several real JSON gateway fields

Location: README.md, Gateway Configuration section (lines ~218–240)
Problem: Table omits dockerless, containerRuntime, containerRuntimeCommand, containerRuntimeArgs, and OpenTelemetry JSON support details. trustedBots validation semantics are also absent.
Actual Behavior: All these fields are implemented and validated.
Suggested Fix: Expand the Gateway Configuration table to include all fields exposed by StdinGatewayConfig.
Code Reference: internal/config/config_stdin.go:36-58, internal/config/validation_gateway.go:37-90

5. Quick Start JSON example lacks a reference to optional JSON server fields

Location: README.md, Quick Start section (lines ~14–36)
Problem: The Quick Start JSON example does not reference optional supported JSON server fields (entrypoint, entrypointArgs, mounts, args, connectTimeout, toolTimeout), making the example feel incomplete relative to the full feature set.
Actual Behavior: All audited fields are supported; command is intentionally unsupported for JSON stdin (correctly omitted).
Suggested Fix: Add a compact "supported JSON server fields" example or add a direct link to docs/CONFIGURATION.md from the Quick Start section.
Code Reference: internal/config/config_stdin.go:112-178, internal/config/validation_server.go:52-107

6. Environment variables list missing OTEL_EXPORTER_OTLP_ENDPOINT and GITHUB_REPOSITORY

Location: README.md, Environment Variables section (lines ~74–100)
Problem: OTEL_EXPORTER_OTLP_ENDPOINT and GITHUB_REPOSITORY are used by implementation but not listed in the environment variables section.
Actual Behavior: OTEL_EXPORTER_OTLP_ENDPOINT sets the OTLP endpoint default; GITHUB_REPOSITORY influences force_public_repos guard logic.
Suggested Fix: Add OTEL_EXPORTER_OTLP_ENDPOINT and GITHUB_REPOSITORY to the documented environment variables with accurate descriptions.
Code Reference: internal/cmd/tracing.go:34-37, internal/cmd/proxy.go:346, internal/server/guard_visibility.go:41-215

Minor Issues 🔵

7. Gateway Configuration field table mixes TOML-only and shared fields without clear labeling

Location: README.md, lines ~239–240
Problem: working_directory, rate_limit_threshold, rate_limit_cooldown are listed without clarifying they are TOML-only. registry is supported on both TOML and JSON paths but its cross-format availability is not noted.
Actual Behavior: registry exists on both config paths.
Suggested Fix: Add a column or note to the field table clarifying which fields are TOML-only vs. shared with JSON stdin.
Code Reference: internal/config/config_stdin.go:150-152

Accurate Sections ✅

The following sections were verified accurate against the implementation:

• Quick Start JSON format — valid JSON stdin keys (type, container, env, mcpServers, gateway.agentId/domain/port)
• command field correctly absent from JSON stdin — container is used instead ✅
• Legacy snake_case timeout aliases (connect_timeout, tool_timeout) documented accurately ✅
• Environment variables — the large env vars table (MCP_GATEWAY_PORT, MCP_GATEWAY_DOMAIN, MCP_GATEWAY_AGENT_ID, MCP_GATEWAY_API_KEY, MCP_GATEWAY_TOOL_TIMEOUT, MCP_GATEWAY_CONTAINER_RUNTIME, MCP_GATEWAY_FORCE_PUBLIC_REPOS, MCP_GATEWAY_GUARDS_MODE, MCP_GATEWAY_WASM_GUARDS_DIR, ACTIONS_ID_TOKEN_REQUEST_URL/TOKEN, DOCKER_HOST, RUNNING_IN_CONTAINER, DEBUG, DEBUG_COLORS, MCP_GATEWAY_LOG_DIR, MCP_GATEWAY_PAYLOAD_DIR, MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD, MCP_GATEWAY_SESSION_TIMEOUT, MCP_GATEWAY_SHUTDOWN_TIMEOUT, MCP_GATEWAY_WASM_CACHE_DIR, MCP_GATEWAY_PAYLOAD_PATH_PREFIX, MCP_GATEWAY_URL_DOMAIN_AUDIT, MCP_GATEWAY_TLS_CERT/KEY/CA_CERT, MCP_GATEWAY_HMAC_SECRET, MCP_GATEWAY_GUARD_POLICY_JSON, MCP_GATEWAY_GUARDS_SINK_SERVER_IDS) all match code usage ✅
• Feature claims — variable expansion, routed/unified modes, Docker/container-runtime support all verified ✅
• TOML examples in config.example.toml match parser naming ([gateway], [servers.<id>], command, args, env) ✅
• Go version and binary name — go 1.26.4 in go.mod matches CONTRIBUTING.md; binary awmg matches Makefile ✅
• Make targets — build, test, test-unit, test-integration, test-all, lint, coverage, install all exist ✅

Tested Commands

Recommendations

Immediate Actions Required:

1. README.md: Remove sample_rate from TOML/JSON tracing config sections (critical — field does not exist)
2. CONTRIBUTING.md: Clarify make test-integration auto-builds; reserve "always rebuilds" description for make test-all

Nice to Have:

1. README.md: Add dockerless, containerRuntime, containerRuntimeCommand, containerRuntimeArgs to the Gateway Configuration field table
2. README.md: Add OTEL_EXPORTER_OTLP_ENDPOINT and GITHUB_REPOSITORY to the env vars section
3. README.md: Add TOML-only vs. JSON-shared labeling to the field table

Code References

• Configuration structs: internal/config/config_core.go, internal/config/config_stdin.go
• Validation logic: internal/config/validation_schema.go, internal/config/validation_server.go, internal/config/validation_gateway.go, internal/config/validation_rules.go
• Tracing config: internal/config/config_tracing.go, internal/cmd/tracing.go
• Guard visibility: internal/server/guard_visibility.go

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

Generated by Nightly Documentation Reconciler · sonnet46 · 51.2 AIC · ⊞ 5.8K · ◷

• expires on Aug 1, 2026, 11:04 PM UTC