📚 Documentation Reconciliation Report - 2026-08-15

[github-actions]

Summary

Found 1 verified discrepancy between README.md and the implementation during nightly reconciliation (workflow run §31912977374), checked against commit 2e2455f.

Critical Issues 🔴

1. README claims gateway section (and all its fields) is optional for JSON stdin config, but it is required

Location: README.md:34

Problem: The Quick Start note states:

Note: port, domain, and agentId shown above are example/recommended values; the gateway section and all of its fields are optional. When a field is present it is validated, but omitting gateway entirely is valid and uses built-in defaults.

Actual Behavior: The embedded JSON schema marks gateway as a required top-level property, and within gatewayConfig, port, domain, and one of agentId/apiKey are required. This is directly exercised by tests:

• internal/config/validation_schema_test.go:106-116 — "missing required field - gateway" expects a validation error when gateway is omitted.
• internal/config/validation_schema_test.go:118-131 — "missing required field - gateway.port" expects an error.
• internal/config/validation_schema_test.go:133-146 — "missing required field - gateway.domain" expects an error.
• internal/config/validation_schema_test.go:148-161 — "missing required field - gateway.apiKey" (agentId/apiKey) expects an error.
• Schema definition: internal/config/schema/mcp-gateway-config.schema.json:57-60 ("required": ["mcpServers", "gateway"]) and internal/config/schema/mcp-gateway-config.schema.json:467-476 (anyOf requiring agentId or apiKey).

Impact: Users following the README's guidance that gateway can be omitted entirely will get a JSON schema validation error at startup, causing confusion since the docs explicitly say this configuration is valid.

Suggested Fix: Update the note in README.md:34 to state that for JSON stdin configuration, gateway is required, along with gateway.port, gateway.domain, and one of gateway.agentId/gateway.apiKey. Remove or correct the "omitting gateway entirely is valid and uses built-in defaults" claim (at minimum for the JSON stdin path — TOML behavior may differ and should be verified separately if intended to differ).

Code Reference: internal/config/schema/mcp-gateway-config.schema.json:57-60,467-476, internal/config/validation_schema_test.go:106-161

Accurate Sections ✅

• CONTRIBUTING.md Go version (1.26.4) and binary name (awmg) match go.mod and Makefile.
• Make targets referenced in CONTRIBUTING.md (build, test, test-unit, test-integration, test-all, lint, coverage, install) exist in the Makefile.
• TOML stdio containerization requirement (command = "docker") is accurately documented.
• JSON stdin format correctly does not document a command field (matches code — only container is supported for JSON stdin).
• containerRuntimeArgs in the "Gateway Configuration" table (README.md:241) is correctly categorized as a GatewayConfig/JSON stdin gateway field (internal/config/config_core.go:135), not a server field.
• Legacy connect_timeout/tool_timeout aliases are implemented and documented consistently.

Notes

• make build could not be fully verified in the reconciliation sandbox due to Go toolchain download restrictions; this is an environment limitation, not a documentation defect, and does not need to be tracked here.
• The external spec link (https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md) referenced in README.md was not fetched during this run; recommend periodic manual verification that it resolves.

Code References

• Schema: internal/config/schema/mcp-gateway-config.schema.json
• Validation tests: internal/config/validation_schema_test.go
• Config structs: internal/config/config_core.go, internal/config/config_stdin.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 · auto · 79.4 AIC · ⊞ 8.4K · ◷

• expires on Aug 18, 2026, 10:50 PM UTC