📚 Documentation Reconciliation Report - 2026-05-10

[github-actions]

Summary

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

• Workflow Run: §25642129821
• Date: 2026-05-10
• Branch: main

---

Critical Issues 🔴

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

1. MCP_GATEWAY_PORT, MCP_GATEWAY_DOMAIN, MCP_GATEWAY_API_KEY documented as automatic overrides but are dead code

Location: AGENTS.md — Environment Variables section

Problem: These three variables are documented as overriding the corresponding config fields automatically (e.g. "overrides config port field"). In reality the getter functions GetGatewayPortFromEnv(), GetGatewayDomainFromEnv(), and GetGatewayAPIKeyFromEnv() are defined in config_env.go but are never called from production code. They are only referenced in validation_env.go for the --validate-env Docker port-mapping check.

Actual Behavior: No automatic override occurs. To use an env var value, users must explicitly write ${MCP_GATEWAY_API_KEY} etc. in their config file. The listen address is controlled exclusively via the --listen flag (default 0.0.0.0:3000).

Impact: Users following the docs may set these environment variables expecting them to take effect and then be confused when nothing changes — especially for MCP_GATEWAY_API_KEY, where a silent no-op is a potential security misconfiguration.

Suggested Fix: Either:

1. Wire the getters into the startup path so the env vars actually override config values (the likely intent), OR
2. Update AGENTS.md to say these are used for environment validation only (via --validate-env) and document that ${VAR} syntax in config files is the actual override mechanism.

Code References: internal/config/config_env.go:37-66, internal/config/validation_env.go:16-18, internal/cmd/flags_core.go:37

---

Important Issues 🟡

2. tool_response_filters server field is completely undocumented

Location: docs/CONFIGURATION.md, config.example.toml, README.md — Server Configuration Fields

Problem: The tool_response_filters field (type map[string]string, accepts per-tool jq expressions that transform tool responses before large-payload processing) is a production-validated feature that appears in zero documentation files.

Actual Behavior: Field is defined and validated in config_core.go:206 and config_stdin.go:115. Validation logic at config_core.go:427 compiles jq expressions at startup.

Suggested Fix: Add a section under Server Configuration Fields in docs/CONFIGURATION.md and a commented example in config.example.toml.

Code References: internal/config/config_core.go:206,427, internal/config/config_stdin.go:115

3. github.com/spf13/pflag direct dependency missing from CONTRIBUTING.md

Location: CONTRIBUTING.md — Dependencies section

Problem: github.com/spf13/pflag is a direct (non-indirect) dependency in go.mod and is directly imported in production code (internal/cmd/tracing.go:33 as *pflag.FlagSet), but it is not listed in the Dependencies section of CONTRIBUTING.md.

Suggested Fix: Add github.com/spf13/pflag to the Dependencies list in CONTRIBUTING.md.

Code References: go.mod:15, internal/cmd/tracing.go:33

---

Minor Issues 🔵

4. CONTRIBUTING.md project structure shows awmg/ as root directory

Location: CONTRIBUTING.md line ~250 — Project Structure section

Problem: The project structure diagram labels the root as awmg/, which is the binary name, not the repository/directory name (gh-aw-mcpg).

Suggested Fix: Change awmg/ to gh-aw-mcpg/ in the diagram.

Code References: CONTRIBUTING.md:250, Makefile:8 (BINARY_NAME=awmg)

5. config.example.toml missing per-server operational fields

Location: config.example.toml

Problem: Several high-impact server-level fields documented in docs/CONFIGURATION.md are absent from config.example.toml: connect_timeout, rate_limit_threshold, rate_limit_cooldown, per-server tool_timeout, working_directory, auth block (github-oidc), registry. Users using the example file as a template may not discover these options.

Suggested Fix: Add commented examples for at least connect_timeout, rate_limit_threshold, rate_limit_cooldown, and the auth block.

Code References: internal/config/config_core.go:174-240, config.example.toml

6. AGENTS.md note conflates PORT (run.sh) with MCP_GATEWAY_PORT (binary)

Location: AGENTS.md — bottom note in Environment Variables section

Problem: The note says "PORT, HOST, and MODE are not read by the awmg binary directly" — but MCP_GATEWAY_PORT is read by the binary (validation_env.go:111). The note correctly refers to the bare PORT shell variable used by run.sh, but the wording is confusing given that MCP_GATEWAY_PORT appears right above it.

Suggested Fix: Clarify that MCP_GATEWAY_PORT is read by the binary for validation, while the plain PORT (no prefix) is only used by run.sh.

Code References: AGENTS.md, internal/config/validation_env.go:111, run.sh

---

Documentation Completeness

Missing Documentation

• tool_response_filters server field — not in docs/CONFIGURATION.md or config.example.toml despite being a production feature with jq expression validation
• GetGatewayPortFromEnv / GetGatewayDomainFromEnv / GetGatewayAPIKeyFromEnv — dead code (defined but never called from production); either document intended future use or remove
• config.example.toml lacks commented examples for: connect_timeout, rate_limit_threshold, rate_limit_cooldown, per-server tool_timeout, auth block, working_directory, registry

Outdated Documentation

• AGENTS.md: MCP_GATEWAY_PORT — documented as automatic override but getter is dead code
• AGENTS.md: MCP_GATEWAY_DOMAIN — same (dead code)
• AGENTS.md: MCP_GATEWAY_API_KEY — same (dead code; silent no-op is a potential security concern)

Accurate Sections ✅

• Go version: go.mod go 1.25.0 matches CONTRIBUTING.md exactly
• Binary name awmg: consistent across Makefile, CONTRIBUTING.md, README.md
• golangci-lint version v2.8.0: matches AGENTS.md and Makefile
• All make targets in CONTRIBUTING.md verified to exist in Makefile: build, test, test-unit, test-integration, test-all, lint, format, coverage, test-ci, clean, install, agent-finished
• Session timeout default (6h): confirmed in internal/config/config_env.go:83
• Default payload size threshold (524288 bytes): confirmed in internal/config/config_payload.go:20
• Default port 3000: consistent across all docs and code
• Auth header format (plain API key, no Bearer): correctly documented and implemented
• TLS flags (--tls-cert, --tls-key, --tls-ca) and env vars: correctly documented
• HMAC secret flag and MCP_GATEWAY_HMAC_SECRET: correctly documented
• Guard policy documentation (allow-only, write-sink): matches code behavior

---

Tested Commands

Command	Status	Note
make --dry-run build	✅	Runs go mod tidy && go build -o awmg . as documented
make --dry-run test	✅	Delegates to test-unit → go test -v ./internal/...
make --dry-run test-unit	✅	Correct
make --dry-run test-integration	✅	Auto-builds binary if missing, then go test ./test/integration/...
make --dry-run test-all	✅	Builds first then runs go test -v ./...
make --dry-run lint	✅	Runs go mod tidy, go vet, gofmt check, golangci-lint
make --dry-run coverage	✅	Runs go test -coverprofile=coverage.out ./internal/...
make --dry-run install	✅	Checks Go version, installs golangci-lint, runs go mod download
make build (actual)	⚠️	Network restricted in CI — cannot download Go 1.25.0 toolchain; Makefile logic is correct
./awmg --help	⚠️	Binary not built; --config-stdin flag verified to exist via internal/cmd/flags_core.go:36

---

Recommendations

Immediate Actions Required

1. Resolve the dead-code vs. docs mismatch for MCP_GATEWAY_PORT/DOMAIN/API_KEY — either wire the getters into startup or correct the docs
2. Document tool_response_filters in docs/CONFIGURATION.md and config.example.toml

Nice to Have

1. Add spf13/pflag to CONTRIBUTING.md dependencies
2. Fix awmg/ → gh-aw-mcpg/ in CONTRIBUTING.md project structure diagram
3. Enrich config.example.toml with commented examples for per-server operational fields
4. Clarify PORT vs MCP_GATEWAY_PORT note in AGENTS.md

Code References

• Configuration structs: internal/config/config_core.go
• Validation logic: internal/config/validation.go, internal/config/validation_env.go
• Env var getters (dead code): internal/config/config_env.go:37-66
• CLI flags: internal/cmd/flags_core.go, internal/cmd/flags_tls.go
• Tracing (pflag usage): internal/cmd/tracing.go:33

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 · ● 4.2M · ◷

• expires on May 13, 2026, 11:08 PM UTC