📚 Documentation Reconciliation Report - 2026-05-25

[github-actions]

Summary

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

• Workflow Run: §26423144160
• Date: 2026-05-25
• Branch: main

Important Issues 🟡

1. Incorrect wazero cache default path in docs/ENVIRONMENT_VARIABLES.md

Location: docs/ENVIRONMENT_VARIABLES.md, line 25
Problem: The documentation states the wazero compilation cache defaults to <log-dir>/wazero-cache and shows the example path as /tmp/gh-aw/mcp-logs/wazero-cache — implying the cache lives inside the log directory.
Actual Behavior: The code in internal/cmd/wasm_cache.go uses:

return filepath.Join(filepath.Dir(logDir), config.DefaultWasmCacheDirName)

This places the cache at filepath.Dir(logDir)/wazero-cache — i.e., a sibling of the log directory. With the default logDir=/tmp/gh-aw/mcp-logs, the cache defaults to /tmp/gh-aw/wazero-cache (not /tmp/gh-aw/mcp-logs/wazero-cache).
Impact: Operators who follow the documentation to locate or pre-warm the wazero cache will look in the wrong directory. This could cause confusion when diagnosing WASM compilation performance or cache-related startup failures.
Suggested Fix:

-| `MCP_GATEWAY_WASM_CACHE_DIR` | Disk-backed wazero compilation cache directory (sets default for `--wasm-cache-dir`; defaults to `<log-dir>/wazero-cache`) | `/tmp/gh-aw/mcp-logs/wazero-cache` |
+| `MCP_GATEWAY_WASM_CACHE_DIR` | Disk-backed wazero compilation cache directory (sets default for `--wasm-cache-dir`; defaults to a sibling of `<log-dir>` named `wazero-cache`) | `/tmp/gh-aw/wazero-cache` |

Code Reference: internal/cmd/wasm_cache.go:34 — return filepath.Join(filepath.Dir(logDir), config.DefaultWasmCacheDirName)

Note: README.md already describes this correctly as "a sibling of --log-dir by default". Only docs/ENVIRONMENT_VARIABLES.md is wrong.

---

Also note: AGENTS.md (internal contributor instructions) contains the same incorrect description (defaults to <log-dir>/wazero-cache), which may mislead contributors. Consider fixing that too.

Documentation Completeness

Accurate Sections ✅

• README.md Quick Start — Docker config JSON structure, container fields, environment variables, docker run command verified accurate
• README.md wazero cache description — correctly says "sibling of --log-dir by default" (<parent-of-log-dir>/wazero-cache)
• CONTRIBUTING.md Prerequisites — Go version 1.25.0 matches go.mod
• CONTRIBUTING.md Make targets — all documented targets (build, test, test-unit, test-integration, test-all, coverage, test-ci, lint, format, clean, test-rust, test-serena, test-serena-gateway, test-container-proxy, test-race, help, install) verified to exist in Makefile
• CONTRIBUTING.md make test alias — correctly documented as alias for test-unit
• CONTRIBUTING.md Project Structure — directory listing matches actual internal/ structure
• JSON stdin config fields — type, container, entrypoint, entrypointArgs, args, mounts, env, url, headers, tools, guard-policies, auth, connectTimeout, toolTimeout all verified in internal/config/config_stdin.go
• command field not in JSON stdin — correctly documented; StdinServerConfig has no Command field (code comment confirms this intentionally)
• Environment variable names — MCP_GATEWAY_PORT, MCP_GATEWAY_DOMAIN, MCP_GATEWAY_API_KEY, MCP_GATEWAY_LOG_DIR, MCP_GATEWAY_PAYLOAD_DIR, MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD, MCP_GATEWAY_GUARDS_MODE, DEBUG, DOCKER_HOST, ACTIONS_ID_TOKEN_REQUEST_URL, ACTIONS_ID_TOKEN_REQUEST_TOKEN, RUNNING_IN_CONTAINER all verified in code
• MCP_GATEWAY_HOST/MCP_GATEWAY_MODE are containerized-only — verified in run_containerized.sh; run.sh uses plain HOST and MODE

Tested Commands

Make targets were verified via make --dry-run:

• ✅ make build — exists and creates awmg binary
• ✅ make test / make test-unit — exist and run ./internal/...
• ✅ make test-integration — exists, auto-builds binary if needed
• ✅ make test-all — exists
• ✅ make lint — exists, runs go vet, gofmt, golangci-lint
• ✅ make coverage — exists
• ✅ make install — exists
• ⚠️ make build (actual execution) — could not execute; Go 1.25.0 toolchain download is blocked by network policy in this sandbox environment (not a documentation issue)

Recommendations

Immediate Action Required:

1. Fix docs/ENVIRONMENT_VARIABLES.md line 25: change <log-dir>/wazero-cache → <parent-of-log-dir>/wazero-cache and example from /tmp/gh-aw/mcp-logs/wazero-cache → /tmp/gh-aw/wazero-cache

Nice to Have:

1. Fix same incorrect description in AGENTS.md (internal contributor instructions)

Code References

• wazero cache logic: internal/cmd/wasm_cache.go:30-34
• wazero cache constant: internal/config/config_core.go:50-51
• JSON stdin config struct: internal/config/config_stdin.go:85-148
• GatewayConfig struct: internal/config/config_core.go:100-155

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 1.8M · ◷

• expires on May 28, 2026, 11:05 PM UTC