📚 Documentation Reconciliation Report - 2026-07-25

[github-actions]

Summary

Found 2 minor discrepancies between documentation and implementation during nightly reconciliation check.

• Workflow Run: §30178593472
• Date: 2026-07-25
• Branch: main

Critical Issues 🔴

None.

Important Issues 🟡

None.

Minor Issues 🔵

1. AGENTS.md missing MCP_GATEWAY_API_KEY environment variable

Location: AGENTS.md, Environment Variables section (line ~391)
Problem: MCP_GATEWAY_API_KEY is not listed in the AGENTS.md Environment Variables section, even though it is a recognized (deprecated) alias for MCP_GATEWAY_AGENT_ID that is accepted by run_containerized.sh and the validation layer.
Actual Behavior: The variable is recognized in internal/config/validation_env.go and handled in run_containerized.sh. It is documented in README.md (line 89) and docs/ENVIRONMENT_VARIABLES.md, but AGENTS.md omits it.
Impact: AI agents using AGENTS.md as their primary reference may not know this deprecated alias exists, potentially missing that legacy configurations using MCP_GATEWAY_API_KEY are still supported.
Suggested Fix: Add after the MCP_GATEWAY_AGENT_ID entry:

- `MCP_GATEWAY_API_KEY` - *Deprecated alias for `MCP_GATEWAY_AGENT_ID`*; still accepted with a deprecation warning (lower precedence when both are set). Use `MCP_GATEWAY_AGENT_ID` instead.

Code Reference: internal/config/validation_env.go:157, README.md:89

---

2. AGENTS.md missing MCP_GATEWAY_CONTAINER_RUNTIME environment variable

Location: AGENTS.md, Environment Variables section (line ~391)
Problem: MCP_GATEWAY_CONTAINER_RUNTIME is not listed in the AGENTS.md Environment Variables section, even though it is a supported and frequently used environment variable for overriding the container runtime.
Actual Behavior: The variable is read in internal/config/container_runtime.go and documented in README.md (line 84) and docs/ENVIRONMENT_VARIABLES.md, but AGENTS.md omits it entirely.
Impact: AI agents using AGENTS.md as their reference will not know this variable can be used to switch between docker and podman runtimes for JSON stdin container servers.
Suggested Fix: Add after MCP_GATEWAY_AGENT_ID:

- `MCP_GATEWAY_CONTAINER_RUNTIME` - Overrides stdio container runtime selection for JSON stdin `container` servers (`docker` default, `podman` supported)

Code Reference: internal/config/container_runtime.go:12, README.md:84

---

Documentation Completeness

Accurate Sections ✅

• README.md Docker Quick Start — All fields in the JSON example (type, container, env) verified against internal/config/config_stdin.go. Structure is correct.
• README.md JSON stdin format — Fields (container, entrypoint, entrypointArgs, mounts, env, type, args, url) all verified present in StdinServerConfig. Correct note that command is NOT supported in JSON stdin.
• README.md TOML format — Fields (command, args, servers, gateway) all verified in internal/config/config_core.go.
• README.md schema requirements — Correctly states: port, domain, and one of agentId or apiKey required. Verified against internal/config/schema/mcp-gateway-config.schema.json (required: ["port","domain"] + anyOf[{required:["agentId"]},{required:["apiKey"]}]).
• README.md Gateway Configuration table — All fields verified against GatewayConfig and StdinGatewayConfig structs.
• README.md environment variables — All listed env vars confirmed in codebase usage.
• CONTRIBUTING.md Go version — 1.26.4 matches go.mod exactly.
• CONTRIBUTING.md make targets — All documented targets (build, test, test-unit, test-integration, test-all, lint, coverage, install, format, clean, agent-finished, test-race, test-rust, test-serena, test-serena-gateway, test-container-proxy, test-ci) verified present in Makefile.
• CONTRIBUTING.md binary name — awmg matches Makefile build output.
• CONTRIBUTING.md project structure — All internal/ directories listed (including jqutil/) verified to exist on disk.
• AGENTS.md feature references — Variable expansion (internal/config/expand.go), routing modes (internal/server/), Docker support (internal/launcher/), Config modes (internal/cmd/) all verified present.
• Example config files — config.example.toml, config.example-payload-threshold.toml, example-http-config.json, config.json all confirmed present.
• Default values — DefaultPayloadSizeThreshold=524288, DefaultPayloadDir="/tmp/jq-payloads", DefaultLogDir="/tmp/gh-aw/mcp-logs", DefaultKeepaliveInterval=1500, DefaultToolTimeout=60, DefaultStartupTimeout=30 all verified in internal/config/config_core.go.

Missing Documentation (minor)

• AGENTS.md Environment Variables section omits MCP_GATEWAY_API_KEY and MCP_GATEWAY_CONTAINER_RUNTIME (both are fully documented in README.md and docs/ENVIRONMENT_VARIABLES.md).

Tested Commands

Make targets (verified via make --dry-run):

• ✅ make build — target exists, builds awmg binary
• ✅ make test / make test-unit — targets exist
• ✅ make test-integration — target exists
• ✅ make test-all — target exists
• ✅ make lint — target exists
• ✅ make coverage — target exists
• ✅ make install — target exists
• ✅ make format, make clean, make agent-finished, make help — all exist

Recommendations

Nice to Have:

1. Add MCP_GATEWAY_API_KEY and MCP_GATEWAY_CONTAINER_RUNTIME to the AGENTS.md Environment Variables section for completeness.

Code References

• Configuration structs: internal/config/config_core.go, internal/config/config_stdin.go
• Validation logic: internal/config/validation_schema.go, internal/config/schema/mcp-gateway-config.schema.json, internal/config/validation_server.go, internal/config/validation_gateway.go, internal/config/validation_rules.go
• Container runtime: internal/config/container_runtime.go
• Env validation: internal/config/validation_env.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 · sonnet46 · 132 AIC · ⊞ 5.7K · ◷

• expires on Jul 28, 2026, 11:08 PM UTC