📚 Documentation Reconciliation Report - 2026-04-20

[github-actions]

Summary

Found 1 discrepancy between documentation and implementation during nightly reconciliation check.

• Workflow Run: §24647615222
• Date: 2026-04-20
• Branch: main

Important Issues 🟡

Issues that are misleading but have workarounds:

1. docs/CONFIGURATION.md — variable expansion incorrectly listed as a common rule for both config formats

Location: docs/CONFIGURATION.md, "Validation Rules" section
Problem: The section lists \$\{VAR_NAME} variable expansion as a "common rule (both formats)":

- **Common rules** (both formats):
  - Variable expansion with `\$\{VAR_NAME}` fails fast on undefined variables

But \$\{VAR} expansion in TOML format is restricted to the [gateway.opentelemetry] / [gateway.tracing] config section only. Server env values, URL fields, gateway api_key, and args are not expanded in TOML.

For JSON stdin, ExpandRawJSONVariables is called on the entire JSON before parsing — expansion applies everywhere.
For TOML, only expandTracingVariables is called (scoped to the tracing config only).

Actual Behavior:

• JSON stdin: All \$\{VAR} patterns in any field are expanded at load time via ExpandRawJSONVariables (internal/config/config_stdin.go:249)
• TOML: Only [gateway.opentelemetry] / [gateway.tracing] fields are expanded via expandTracingVariables (internal/config/expand.go:95–133); all other fields (server env, URL, args, gateway api_key, etc.) are not expanded

Impact: A user reading CONFIGURATION.md may try to use \$\{MY_API_KEY} in a TOML server env value or gateway.api_key expecting expansion, and find it silently doesn't work.

Suggested Fix: Change the "Common rules" bullet to be JSON-specific and add a TOML clarification:

- **JSON stdin format** (in addition to above):
  - Variable expansion with `\$\{VAR_NAME}` is applied globally — all fields in the JSON config are expanded before parsing; expansion fails fast on undefined variables
- **TOML format**:
  - Variable expansion with `\$\{VAR_NAME}` is only supported in `[gateway.opentelemetry]` and `[gateway.tracing]` fields; server env values, URL, args, and other gateway fields are **not** expanded
  - For passthrough of host env vars to containers, use an empty string `""` in the `env` map (e.g., `GITHUB_PERSONAL_ACCESS_TOKEN = ""`)

Code Reference:

• JSON stdin expansion: internal/config/config_stdin.go:247–252
• TOML tracing expansion: internal/config/expand.go:95–133
• TOML load path (no global expansion): internal/config/config_core.go:321–441

Minor Issues 🔵

2. docs/CONFIGURATION.md — env field description in "Server Configuration Fields" could note JSON-only \$\{VAR} expansion

Location: docs/CONFIGURATION.md, "Server Configuration Fields" → env field
Problem: The env field description says "Use "\$\{VAR_NAME}" for environment variable expansion (fails if undefined)" without qualifying that this is only applicable to JSON stdin format.

Actual Behavior: \$\{VAR_NAME} expansion in the env field only works for JSON stdin (via ExpandRawJSONVariables). In TOML format, the env map values are passed as-is to the Docker launcher; \$\{VAR_NAME} syntax is not evaluated.

Impact: Low — TOML users typically use "" for passthrough rather than \$\{VAR_NAME} expansion. The config.example.toml file already documents the TOML limitation correctly.

Suggested Fix: Append a note to the env field description:

Note: \$\{VAR_NAME} expansion is only supported in JSON stdin format. For TOML format, use "" (empty string) for host env passthrough or provide explicit values.

Code Reference: internal/config/expand.go:73–90 (expandEnvVariables called only from JSON stdin path in config_stdin.go:380)

Documentation Completeness

Missing Documentation

• None identified

Outdated Documentation

• None identified

Accurate Sections ✅

• README.md Docker Quick Start — docker run command, required flags (-i, -v, -p), env vars (MCP_GATEWAY_PORT, MCP_GATEWAY_DOMAIN, MCP_GATEWAY_API_KEY) all verified accurate
• CONTRIBUTING.md Build Commands — All documented make targets (build, test, test-unit, test-integration, test-all, test-race, lint, coverage, test-ci, format, clean, install, test-serena, test-serena-gateway, test-container-proxy, agent-finished) verified present in Makefile
• CONTRIBUTING.md Prerequisites — Go 1.25.0 requirement matches go.mod exactly
• CONTRIBUTING.md Binary Name — awmg verified correct
• CONTRIBUTING.md CLI Flags — --config, --config-stdin, --log-dir, --env, -v, --payload-dir, --payload-size-threshold all verified in internal/cmd/flags_core.go and flags_logging.go
• CONTRIBUTING.md Project Structure — All 20 internal/ subdirectories verified present on disk
• CONTRIBUTING.md Dependencies — All listed packages verified present in go.mod
• CONTRIBUTING.md Default Ports — ./run.sh defaults to 0.0.0.0:8000; binary defaults to 127.0.0.1:3000 — both documented correctly
• docs/CONFIGURATION.md JSON Stdin Fields — StdinServerConfig and StdinGatewayConfig struct fields match documentation (type, container, entrypoint, entrypointArgs, args, mounts, env, url, headers, tools, registry, guard-policies, guard, auth, apiKey, domain, etc.)
• docs/CONFIGURATION.md TOML command = "docker" requirement — Enforced by validateTOMLStdioContainerization in internal/config/validation.go:422
• docs/CONFIGURATION.md write-sink Accept/accept casing — Accept for TOML, accept for JSON — matches struct tags and Go JSON case-insensitive matching
• docs/CONFIGURATION.md gateway.port metadata-only — Correctly notes port is stored for metadata only; actual listen address is set by --listen flag
• docs/ENVIRONMENT_VARIABLES.md — All documented env vars verified used in code (MCP_GATEWAY_PORT, MCP_GATEWAY_DOMAIN, MCP_GATEWAY_LOG_DIR, MCP_GATEWAY_PAYLOAD_DIR, MCP_GATEWAY_SESSION_TIMEOUT, MCP_GATEWAY_WASM_GUARDS_DIR, MCP_GATEWAY_GUARDS_MODE, RUNNING_IN_CONTAINER, DEBUG, DEBUG_COLORS, DOCKER_HOST, etc.)
• Auth mechanism — Plain API key in Authorization header (not Bearer) verified in spec and code

Tested Commands

All make targets from CONTRIBUTING.md were dry-run verified:

• ✅ make build — target exists, builds awmg binary (Makefile:14)
• ✅ make test — alias for test-unit (Makefile:52)
• ✅ make test-unit — runs go test ./internal/... (Makefile:40)
• ✅ make test-integration — auto-builds binary if needed (Makefile:66)
• ✅ make test-all — runs unit + integration (Makefile:46)
• ✅ make lint — runs go vet, gofmt, golangci-lint (Makefile:21)
• ✅ make coverage — runs with coverage profile (Makefile:127)
• ✅ make test-ci — JSON output for CI (Makefile:159)
• ✅ make format — gofmt -w (Makefile:167)
• ✅ make clean — removes build artifacts (Makefile:173)
• ✅ make install — installs Go toolchain + golangci-lint (Makefile:283)
• ✅ make test-race — race detection tests (Makefile:75)
• ✅ make agent-finished — full verification pipeline (Makefile:92)

Recommendations

Immediate Actions Required:

1. Fix docs/CONFIGURATION.md "Validation Rules" section to clarify that \$\{VAR_NAME} expansion is not a common rule for both formats — it is comprehensive for JSON stdin and limited to tracing fields for TOML

Nice to Have:

1. Add a format-qualifier note to the env field description in "Server Configuration Fields"

Code References

• JSON stdin expansion: internal/config/config_stdin.go:247–252
• TOML tracing-only expansion: internal/config/expand.go:95–133
• TOML load path: internal/config/config_core.go:321–441
• config.example.toml correctly notes TOML limitation at line 142

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

• expires on Apr 23, 2026, 4:04 AM UTC