📚 Documentation Reconciliation Report - 2026-07-20

[github-actions]

Summary

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

• Workflow Run: 29785804108
• Date: 2026-07-20
• Branch: main

---

Critical Issues

1. CLI flags section in README is materially incomplete

Location: README.md (CLI flags section)
Problem: The section lists only a few flags, but the binary registers 20+ flags.
Actual Behavior: Binary also registers: --listen, --routed, --unified, --validate-env, --log-dir, --payload-dir, --payload-path-prefix, --payload-size-threshold, --wasm-cache-dir, --url-domain-audit, --shutdown-timeout, --guards-mode, --guards-sink-server-ids, --guard-policy-json, --allowonly-scope-public, --allowonly-scope-owner, --allowonly-scope-repo, --allowonly-min-integrity, --tls-cert, --tls-key, --tls-ca, --hmac-secret, --otlp-endpoint, --otlp-service-name, --otlp-sample-rate.
Impact: Users are unaware of critical security/DIFC/TLS/HMAC runtime flags.
Suggested Fix: Expand README CLI flags section or link to awmg --help output.
Code Reference: internal/cmd/flags_core.go, flags_logging.go, flags_difc.go, flags_tls.go, flags_serve.go, tracing.go, flags_launch.go

2. Environment variable list in README is incomplete

Location: README.md (environment variables section)
Problem: Multiple implemented env vars are missing from the README list.
Actual Behavior: Missing: GITHUB_MCP_SERVER_TOKEN, GITHUB_TOKEN, GH_TOKEN, GITHUB_API_URL, GITHUB_SERVER_URL, GH_AW_OTLP_ENDPOINTS, MCP_GATEWAY_GUARDS_MODE, MCP_GATEWAY_ALLOWONLY_SCOPE_PUBLIC/OWNER/REPO/MIN_INTEGRITY, MCP_GATEWAY_WASM_GUARDS_DIR, OTEL_EXPORTER_OTLP_HEADERS, MCP_GATEWAY_PORT.
Impact: Users cannot discover all supported env vars from README.
Suggested Fix: Add missing vars or note the list is non-exhaustive and reference docs/CONFIGURATION.md.
Code Reference: internal/envutil/github.go:18-76, internal/config/gateway_env.go:51-123

---

Important Issues

3. Gateway configuration field table is incomplete

Location: README.md (gateway configuration section)
Problem: JSON schema-required fields (gateway.port, gateway.domain) and advanced gateway fields (keepaliveInterval, payloadPathPrefix, payloadSizeThreshold, trustedBots, forcePublicRepos, sinkVisibilityExemptServers) are undocumented in README.
Impact: Users may create invalid configurations without realising fields are required.
Suggested Fix: Add a note about schema-required fields and reference docs/CONFIGURATION.md.
Code Reference: internal/config/config_stdin.go:36-54, internal/config/schema/mcp-gateway-config.schema.json:330-452

4. make test-all wording in CONTRIBUTING is inaccurate

Location: CONTRIBUTING.md:97-101
Problem: Says "always rebuilds the binary first" but Makefile only lists build as a prerequisite.
Actual Behavior: test-all: build -- standard make dependency, not forced rebuild.
Suggested Fix: Change to "depends on build" or force rebuild if always rebuilding is intended.
Code Reference: CONTRIBUTING.md:97-101, Makefile:45-49

5. Several Makefile targets are undocumented in CONTRIBUTING

Location: CONTRIBUTING.md
Problem: agent-finished, format, clean, help, and release targets are available but not mentioned.
Impact: Contributors are unaware of make agent-finished (completion checklist) and make format (auto-format).
Suggested Fix: Document these targets, especially agent-finished and help.
Code Reference: Makefile:90-125, Makefile:166-180

6. README server field overview omits TOML-only server fields

Location: README.md (server configuration section)
Problem: working_directory, rate_limit_threshold, and rate_limit_cooldown exist in ServerConfig and docs/CONFIGURATION.md but are not mentioned in README.
Suggested Fix: Add a sentence pointing to docs/CONFIGURATION.md for the full TOML server field list.
Code Reference: internal/config/config_core.go:269-321, docs/CONFIGURATION.md:232-237

---

Minor Issues

7. Missing precedence note for deprecated MCP_GATEWAY_API_KEY

Location: README.md (environment variables section)
Problem: No mention of precedence when both MCP_GATEWAY_API_KEY and MCP_GATEWAY_AGENT_ID are set.
Actual Behavior: MCP_GATEWAY_AGENT_ID takes precedence; MCP_GATEWAY_API_KEY is ignored with a deprecation warning.
Suggested Fix: Add: "When both are set, MCP_GATEWAY_AGENT_ID takes precedence."
Code Reference: internal/config/gateway_env.go:74-95

8. JSON schema requirements not signposted in quick-start example

Location: README.md (JSON quick start)
Problem: Quick-start example omits gateway.port and gateway.domain, which are schema-required; users copying the example will get a validation error.
Suggested Fix: Include required fields in the snippet or add a note.
Code Reference: internal/config/schema/mcp-gateway-config.schema.json:57-60, :436-452

9. CONTRIBUTING uses informal project nickname inconsistently

Location: CONTRIBUTING.md:170
Problem: Uses "MCPG" while binary and help text say awmg/MCP Gateway.
Suggested Fix: Standardize to "MCP Gateway" or "awmg" throughout.
Code Reference: CONTRIBUTING.md:170, internal/cmd/root.go:45-57

---

Documentation Completeness

Missing Documentation

• CLI flags: --listen, --routed, --unified, --validate-env, --shutdown-timeout, --wasm-cache-dir, --payload-path-prefix, --url-domain-audit, --guards-mode, --guards-sink-server-ids, --guard-policy-json, --allowonly-*, --tls-*, --hmac-secret, --otlp-*
• Environment variables: GITHUB_API_URL, GITHUB_SERVER_URL, GH_AW_OTLP_ENDPOINTS, OTEL_EXPORTER_OTLP_HEADERS, MCP_GATEWAY_GUARDS_MODE, MCP_GATEWAY_ALLOWONLY_*, MCP_GATEWAY_WASM_GUARDS_DIR, MCP_GATEWAY_PORT
• Makefile targets: agent-finished, help, clean, format, release

Outdated Documentation

• CONTRIBUTING.md:97-101 overstates make test-all rebuild behavior
• README CLI flags section does not reflect current breadth of flags

Accurate Sections

• Authentication token priority order (GITHUB_MCP_SERVER_TOKEN > GITHUB_TOKEN > GITHUB_PERSONAL_ACCESS_TOKEN > GH_TOKEN) -- verified correct
• Legacy timeout alias documentation (connect_timeout / tool_timeout in JSON stdin) -- verified correct
• stdio containerization requirement and TOML command="docker" enforcement -- verified correct
• docs/CONFIGURATION.md TOML-only server fields (rate_limit_threshold, rate_limit_cooldown, working_directory) -- verified correct

---

Tested Commands

Command	Status	Notes
make --dry-run build test test-unit test-integration test-all lint coverage install	Pass	All targets exist; dry-run confirms correct recipes
make build	Warn	Failed in CI sandbox -- Go toolchain download (go1.25.0) blocked by HTTP 403; not a documentation bug
./awmg --help	Warn	Could not run -- binary not built due to above

---

Code References

• Configuration structs: internal/config/config_core.go, internal/config/config_stdin.go
• JSON schema: internal/config/schema/mcp-gateway-config.schema.json
• Validation logic: internal/config/validation_schema.go, validation_server.go, validation_gateway.go, validation_rules.go
• CLI flags: internal/cmd/flags_core.go, flags_difc.go, flags_tls.go, flags_serve.go, flags_logging.go, tracing.go
• Environment: internal/envutil/github.go, internal/config/gateway_env.go

Warning

Firewall blocked 2 domains

The following domains were blocked by the firewall during workflow execution:

• awmgmcpg
• proxy.golang.org

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

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

See Network Configuration for more information.

Generated by Nightly Documentation Reconciler · 92.6 AIC · ⊞ 4.7K · ◷

• expires on Jul 23, 2026, 11:06 PM UTC