📚 Documentation Reconciliation Report - 2026-03-28

[github-actions]

Summary

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

• Workflow Run: §23676640075
• Date: 2026-03-28
• Branch: main

---

Important Issues 🟡

1. gateway.port config field has no runtime effect on the listen port

Location: docs/CONFIGURATION.md (Gateway Configuration Fields table), config.example.toml (comment on line ~26)

Problem: The port field in the gateway configuration section is described as "HTTP port (1-65535)" with a note "From --listen flag" in the default column of docs/CONFIGURATION.md. The comment in config.example.toml says # Port number for the HTTP server (default: 3000). Both descriptions imply that setting this field controls which port the gateway listens on.

Actual Behavior: The port field is parsed, validated (range check), and stored — but it is never used to control the actual HTTP listen address. The server always binds to the address from the --listen CLI flag (default 127.0.0.1:3000). Setting port = 4000 in TOML config or "port": 4000 in JSON stdin has no effect on where the server listens.

Impact: A user who sets port = 4000 in config.toml and runs ./awmg --config config.toml will be surprised to find the server still listens on port 3000 (the --listen default). There is no validation error or warning when the config port differs from the --listen port, so the mismatch is silently ignored.

Suggested Fix:

1. In docs/CONFIGURATION.md Gateway Configuration Fields table, clarify the port field:

   | `port` | Validated and stored but **not used to control the listen port** — the actual listen address is always set by the `--listen` CLI flag (default `127.0.0.1:3000`) | Informational; defaults to `3000` |

   Or add a note/callout below the table explaining this.

2. In config.example.toml, update the comment:

   # Note: This field is parsed and validated but does NOT control the actual listen port.
   # To change the listen port, use the --listen flag: ./awmg --config config.toml --listen 127.0.0.1:4000
   # This field is stored for metadata purposes only.
   port = 3000

Code Reference:

• internal/config/config_core.go:76 — Port int toml:"port" json:"port,omitempty"
• internal/config/config_core.go:177-178 — applyGatewayDefaults sets Port = 3000 if zero
• internal/config/validation.go:338-341 — Port range validated
• internal/cmd/flags_core.go:14 — defaultListenAddr = "127.0.0.1:3000" (actual listen default)
• internal/cmd/root.go:318,326,336 — Server is created using listenAddr (from --listen flag), not cfg.Gateway.Port

---

Minor Issues 🔵

2. trustedBots/trusted_bots gateway field missing from docs/CONFIGURATION.md

Location: docs/CONFIGURATION.md (Gateway Configuration Fields table)

Problem: The gateway configuration supports a trustedBots field (JSON stdin camelCase) / trusted_bots field (TOML snake_case) for extending the built-in trusted bot list. This field is fully implemented with validation (per spec §4.1.3.4) and is referenced in AGENTS.md, but it is absent from the Gateway Configuration Fields table in docs/CONFIGURATION.md.

Actual Behavior:

• JSON stdin: "gateway": { "trustedBots": ["my-bot[bot]", "org-automation"] }
• TOML: [gateway] section, trusted_bots = ["my-bot[bot]"]
• Validation: must be a non-empty array when present; each entry must be a non-empty string
• Effect: additional bot usernames treated as trusted (receive "approved" integrity level); additive to the guard's built-in trusted bot list

Impact: Users who need to trust additional automation bots have no documentation pointing them to this feature in the configuration reference.

Suggested Fix: Add a row to the Gateway Configuration Fields table in docs/CONFIGURATION.md:

| `trustedBots` (JSON) / `trusted_bots` (TOML) | Optional list of additional bot usernames to trust with "approved" integrity level. Additive to the built-in trusted bot list. Must be non-empty array when present (spec §4.1.3.4). Example: `["my-bot[bot]", "automation"]` | (disabled) |

Code Reference:

• internal/config/config_core.go:104-111 — GatewayConfig.TrustedBots field definition and doc comment
• internal/config/config_stdin.go:41 — StdinGatewayConfig.TrustedBots json:"trustedBots"
• internal/config/validation.go:379-391 — validateTrustedBots enforcement

---

Accurate Sections ✅

The following areas were verified against the implementation and found accurate:

• README Quick Start — Docker command flags (-i, -v /var/run/docker.sock, -p), JSON config fields (type, container, env, apiKey), and env vars (MCP_GATEWAY_PORT, MCP_GATEWAY_DOMAIN, MCP_GATEWAY_API_KEY) all match code
• Auth scheme — Authorization: <api-key> (not Bearer) matches internal/auth/
• API endpoints — /mcp/{serverID}, /mcp, /health match server implementation
• CONTRIBUTING.md Go version — 1.25.0 matches go.mod
• All Makefile targets — make build, make test, make test-unit, make test-integration, make test-all, make lint, make coverage, make install, make format, make clean all verified present and described correctly
• Binary name — awmg matches Makefile BINARY_NAME=awmg
• Config format (JSON stdin) — container, entrypoint, entrypointArgs, args, mounts, env, url, headers, tools, registry, guard-policies, guard all match StdinServerConfig struct
• command field not supported in JSON stdin — confirmed by validation code; container is required
• TOML requires command = "docker" — validateTOMLStdioContainerization enforces this
• Variable expansion \$\{VAR} in JSON stdin — ExpandRawJSONVariables and expandEnvVariables confirmed
• TOML: no variable expansion — LoadFromFile does not call expansion functions
• tools field note — "stored but not currently enforced at runtime" confirmed; no runtime filtering in launcher/server
• working_directory note — "not yet implemented in launcher" confirmed; no uses of WorkingDirectory in launcher code
• ENVIRONMENT_VARIABLES.md — All env vars verified in code: MCP_GATEWAY_LOG_DIR, MCP_GATEWAY_PAYLOAD_DIR, MCP_GATEWAY_PAYLOAD_PATH_PREFIX, MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD, MCP_GATEWAY_WASM_GUARDS_DIR, MCP_GATEWAY_GUARDS_MODE, MCP_GATEWAY_GUARDS_SINK_SERVER_IDS, DEBUG, DEBUG_COLORS, RUNNING_IN_CONTAINER, MCP_GATEWAY_HOST, DOCKER_HOST, DOCKER_API_VERSION, all DIFC env vars
• CLI flags — --config, --config-stdin, --listen, --routed, --unified, --log-dir, --payload-dir, --payload-path-prefix, --payload-size-threshold, --sequential-launch, --guards-mode all confirmed in flags_*.go
• Gateway config field defaults — startupTimeout: 60, toolTimeout: 120, payloadDir: /tmp/jq-payloads all match DefaultStartupTimeout, DefaultToolTimeout, DefaultPayloadDir
• run.sh default port — 8000 (correct per PORT="\$\{MCP_GATEWAY_PORT:-\$\{PORT:-8000}}")
• Binary default port — 3000 (correct per DefaultListenPort = "3000")

Tested Commands

• ✅ go.mod — Go 1.25.0 requirement matches CONTRIBUTING.md
• ✅ Makefile target existence — all documented targets verified via file inspection
• ⚠️ make build — not testable in this environment (Go toolchain download blocked); binary did not build
• ✅ Config struct field cross-reference — all fields verified against source code

Recommendations

Immediate Actions Required:

1. Clarify gateway.port field documentation in docs/CONFIGURATION.md and config.example.toml to prevent user confusion about whether it controls the listen port

Nice to Have:

1. Add trustedBots/trusted_bots to the Gateway Configuration Fields table in docs/CONFIGURATION.md
2. Consider whether gateway.port should be wired to override --listen port (currently it's validated but unused — either use it or remove it)

Code References

• internal/config/config_core.go — GatewayConfig, ServerConfig struct definitions
• internal/config/config_stdin.go — StdinGatewayConfig, StdinServerConfig struct definitions
• internal/config/validation.go — Validation rules for gateway and server config
• internal/cmd/flags_core.go — Core CLI flags (--config, --listen, --config-stdin)
• internal/cmd/root.go — Server startup, listenAddr usage, writeGatewayConfig

Generated by Nightly Documentation Reconciler · ◷

• expires on Mar 31, 2026, 3:46 AM UTC