📚 Documentation Reconciliation Report - 2026-04-05

[github-actions]

Summary

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

• Workflow Run: §23993646215
• Date: 2026-04-05
• Branch: main

---

Critical Issues 🔴

None found.

---

Important Issues 🟡

None found.

---

Minor Issues 🔵

1. Missing test-race Make Target in CONTRIBUTING.md

Location: CONTRIBUTING.md, Testing section
Problem: The make test-race target exists in the Makefile and is listed in make help output, but is not documented anywhere in CONTRIBUTING.md.
Actual Behavior: Running make test-race executes go test -race -timeout=5m ./internal/... to detect data races in concurrent server code.
Impact: Contributors who are unfamiliar with the project may miss race detection testing, which is especially important for a concurrent HTTP server. The Makefile comment says "The MCP Gateway is a concurrent server; use this to validate thread safety."
Suggested Fix: Add a "Race Detection Tests" subsection under the Testing section of CONTRIBUTING.md:

#### Race Detection Tests
Run unit tests with race detection to catch concurrent data races:
```bash
make test-race

This is especially useful when modifying concurrent server code.

**Code Reference:** `Makefile:63-69`

---

### 2. Missing OpenTelemetry Environment Variables in `docs/ENVIRONMENT_VARIABLES.md`

**Location:** `docs/ENVIRONMENT_VARIABLES.md` (no tracing section exists)  
**Problem:** `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_SERVICE_NAME` environment variables are read by the gateway (via `envutil.GetEnvString`) to set defaults for `--otlp-endpoint` and `--otlp-service-name` flags, but are not documented in `docs/ENVIRONMENT_VARIABLES.md`.  
**Actual Behavior:**  
- `OTEL_EXPORTER_OTLP_ENDPOINT` → sets the default OTLP HTTP endpoint for trace export (tracing disabled when empty)  
- `OTEL_SERVICE_NAME` → sets the default service name reported in traces  
**Impact:** Users who want to configure OpenTelemetry tracing via environment variables (a common pattern in containerized/CI environments) cannot discover these supported variables from the docs.  
**Suggested Fix:** Add a "OpenTelemetry / Tracing Variables" section to `docs/ENVIRONMENT_VARIABLES.md`:
```markdown
## OpenTelemetry / Tracing Variables

These standard OpenTelemetry environment variables set defaults for the corresponding `--otlp-*` CLI flags:

| Variable | Description | Default |
|----------|-------------|---------|
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP HTTP endpoint for trace export (e.g. `(localhost/redacted) Tracing is disabled when empty. Sets default for `--otlp-endpoint`. | (disabled) |
| `OTEL_SERVICE_NAME` | Service name reported in traces. Sets default for `--otlp-service-name`. | `mcp-gateway` |

Code Reference: internal/cmd/flags_tracing.go:29-38

---

Documentation Completeness

Missing Documentation

• make test-race target exists in Makefile but is undocumented in CONTRIBUTING.md
• OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_SERVICE_NAME env vars exist in code but missing from docs/ENVIRONMENT_VARIABLES.md

Accurate Sections ✅

• Go version requirement — CONTRIBUTING.md documents Go 1.25.0, matches go.mod ✅
• All documented make targets — build, test, test-unit, test-integration, test-all, lint, coverage, install, test-ci, format, clean, test-serena, test-serena-gateway, test-container-proxy all exist in Makefile ✅
• Binary name — awmg matches BINARY_NAME in Makefile ✅
• JSON stdin config fields — type, container, entrypoint, entrypointArgs, mounts, env, guard-policies all verified in StdinServerConfig struct ✅
• command field not supported in JSON stdin — correctly noted in docs/CONFIGURATION.md ✅
• TOML config fields — command, args, servers, gateway.port, gateway.api_key all verified in Config/GatewayConfig structs ✅
• Variable expansion — \$\{VAR_NAME} syntax works in JSON stdin, documented correctly ✅
• Default listen address — binary defaults to 127.0.0.1:3000 (direct run), Docker uses 0.0.0.0:8000 via run_containerized.sh; both documented correctly ✅
• Guard policy fields — allow-only, write-sink, repos, min-integrity, blocked-users, approval-labels, trusted-users all implemented and documented ✅
• Environment variables — All env vars documented in docs/ENVIRONMENT_VARIABLES.md verified present in code ✅
• Docker quick start — JSON config structure and docker run command verified correct ✅
• Auth spec compliance — Authorization: <api-key> (plain, not Bearer) documented and implemented ✅

Tested Commands

• ✅ make build — target verified in Makefile
• ✅ make test / make test-unit — targets verified in Makefile
• ✅ make test-integration — target verified in Makefile
• ✅ make test-all — target verified in Makefile
• ✅ make lint — target verified in Makefile
• ✅ make coverage — target verified in Makefile
• ✅ make install — target verified in Makefile
• ✅ make test-ci — target verified in Makefile
• ✅ make format — target verified in Makefile
• ✅ make clean — target verified in Makefile
• ✅ make test-serena / make test-serena-gateway — targets verified in Makefile
• ✅ make test-container-proxy — target verified in Makefile
• ⚠️ make test-race — exists in Makefile but not documented in CONTRIBUTING.md
• ℹ️ Binary build not tested directly (Go toolchain download blocked in sandbox)

Recommendations

Nice to Have:

1. Add test-race documentation to CONTRIBUTING.md — especially since the gateway is a concurrent server where race conditions matter
2. Add OpenTelemetry env vars (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME) to docs/ENVIRONMENT_VARIABLES.md for tracing configuration discoverability

Code References

• Make targets: Makefile
• CLI flags: internal/cmd/flags_core.go, internal/cmd/flags_tracing.go
• Config structs: internal/config/config_core.go, internal/config/config_stdin.go
• Validation: internal/config/validation.go, internal/config/validation_env.go
• Server startup: run.sh, run_containerized.sh

Generated by Nightly Documentation Reconciler · ◷

• expires on Apr 8, 2026, 3:53 AM UTC