📚 Documentation Reconciliation Report - 2026-04-06

[github-actions]

Summary

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

• Workflow Run: §24017859528
• Date: 2026-04-06
• Branch: main

---

Minor Issues 🔵

Small inconsistencies or missing details that don't break user workflows.

1. internal/tracing/ package missing from CONTRIBUTING.md project structure

Location: CONTRIBUTING.md — Project Structure section (directory tree) and Key Directories section
Problem: The internal/tracing/ package exists in the codebase but is not listed in either the directory tree or the "Key Directories" reference section of CONTRIBUTING.md.
Actual Behavior: internal/tracing/ is a real package providing OpenTelemetry OTLP trace export helpers (WrapHTTPHandler, Tracer, Provider) used by the MCP gateway middleware and the GitHub API proxy.
Impact: Contributors looking up internal package locations won't find tracing/ in the reference and may be surprised to discover it.
Suggested Fix:
Add to the directory tree:

    ├── tracing/               # OpenTelemetry OTLP tracing helpers
```
And add to the Key Directories section:
```
- **`internal/tracing/`** - OpenTelemetry OTLP trace export helpers (HTTP handler wrapping, provider management)
```
**Code Reference:** `internal/tracing/http.go`, `internal/tracing/provider.go`

---

### 2. OpenTelemetry dependency missing from CONTRIBUTING.md Dependencies section

**Location:** `CONTRIBUTING.md` — Dependencies section  
**Problem:** `go.opentelemetry.io/otel` (and related `otel/sdk`, `otel/trace`, `otel/exporters/otlp/otlptrace/otlptracehttp`) are direct dependencies used for distributed tracing, but the Dependencies section only lists 8 packages and omits OpenTelemetry entirely.  
**Actual Behavior:** `go.mod` lists OpenTelemetry packages as direct (non-indirect) dependencies:
```
go.opentelemetry.io/otel v1.43.0
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.43.0
go.opentelemetry.io/otel/sdk v1.43.0
go.opentelemetry.io/otel/trace v1.43.0
```
**Impact:** Contributors adding tracing features won't know the library is already available as a direct dependency.  
**Suggested Fix:** Add to the Dependencies section:
```
- `go.opentelemetry.io/otel` - OpenTelemetry distributed tracing (OTLP export, span/trace management)

Code Reference: go.mod:17-20, internal/tracing/provider.go

---

Documentation Completeness

Missing Documentation

• internal/tracing/ package (implemented but not mentioned in CONTRIBUTING.md)
• OpenTelemetry as a direct dependency (in go.mod but not in CONTRIBUTING.md Dependencies)

Accurate Sections ✅

• README Quick Start — JSON config structure (type, container, env, gateway.apiKey) matches StdinServerConfig and StdinGatewayConfig structs exactly
• README API endpoints — /health response shape (status, specVersion, gatewayVersion, servers) matches HealthResponse struct in internal/server/health.go
• README Docker quick start — MCP_GATEWAY_PORT, MCP_GATEWAY_DOMAIN, MCP_GATEWAY_API_KEY env vars are all used by run_containerized.sh and validated; port mapping guidance is correct
• CONTRIBUTING.md build commands — All documented make targets (build, test, test-unit, test-integration, test-all, test-race, coverage, test-ci, lint, format, clean, install, test-serena, test-serena-gateway, test-container-proxy) exist in the Makefile with correct descriptions
• CONTRIBUTING.md prerequisites — Go 1.25.0 matches go.mod exactly; Docker requirement is accurate
• CONTRIBUTING.md project structure — All 21 listed internal packages exist (only tracing/ is omitted)
• CONTRIBUTING.md testing instructions — Unit vs integration split, coverage, CI targets all accurate
• CONTRIBUTING.md curl examples — Port 3000 default (DefaultListenPort = "3000" in internal/cmd/root.go) matches the binary default; run.sh default of 8000 is correctly noted
• docs/CONFIGURATION.md server fields — All fields (container, entrypoint, entrypointArgs, args, mounts, env, url, headers, auth, tools, guard, registry, working_directory) match StdinServerConfig struct definitions; behavioral notes (e.g., tools not enforced, working_directory not yet implemented) verified against code
• docs/ENVIRONMENT_VARIABLES.md — All documented env vars verified against code (MCP_GATEWAY_PORT, MCP_GATEWAY_DOMAIN, MCP_GATEWAY_API_KEY, MCP_GATEWAY_LOG_DIR, MCP_GATEWAY_PAYLOAD_DIR, MCP_GATEWAY_PAYLOAD_PATH_PREFIX, MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD, MCP_GATEWAY_SESSION_TIMEOUT, MCP_GATEWAY_WASM_GUARDS_DIR, MCP_GATEWAY_GUARDS_MODE, MCP_GATEWAY_GUARDS_SINK_SERVER_IDS, MCP_GATEWAY_GUARD_POLICY_JSON, MCP_GATEWAY_ALLOWONLY_*, OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, RUNNING_IN_CONTAINER)
• config.example.toml — Note that the port field does not control the listen address (verified: GatewayConfig.Port is validated but not passed to --listen in internal/cmd/root.go)

Tested Commands

All commands from CONTRIBUTING.md were dry-run validated against the Makefile:

• ✅ make build — target exists, builds awmg binary
• ✅ make test — alias for test-unit (confirmed in Makefile line 52-53)
• ✅ make test-unit — runs go test -v ./internal/...
• ✅ make test-integration — auto-builds if binary missing, runs ./test/integration/...
• ✅ make test-all — depends on build, runs all tests
• ✅ make test-race — runs go test -race ./internal/...
• ✅ make coverage — generates coverage.out
• ✅ make test-ci — generates JSON output with coverage
• ✅ make lint — runs go vet, gofmt, golangci-lint
• ✅ make format — runs gofmt -w .
• ✅ make clean — removes binary, coverage.out, tidies modules
• ✅ make install — checks Go version, installs golangci-lint, downloads deps
• ✅ make test-serena / test-serena-gateway — shell scripts in test/serena-mcp-tests/
• ✅ make test-container-proxy — Docker-dependent integration tests
• ⚠️ Build test skipped — Go 1.25.0 toolchain download blocked in sandbox (network restriction); binary not verifiable in this environment

Recommendations

Nice to Have:

1. Add internal/tracing/ to the CONTRIBUTING.md project structure tree and Key Directories section
2. Add OpenTelemetry to the CONTRIBUTING.md Dependencies section

Code References

• Project structure source: internal/ (directory listing)
• Configuration structs: internal/config/config_core.go, internal/config/config_stdin.go
• CLI flags and defaults: internal/cmd/root.go, internal/cmd/flags_core.go
• Health endpoint: internal/server/health.go
• Tracing package: internal/tracing/http.go, internal/tracing/provider.go
• go.mod: go.mod:17-20

Generated by Nightly Documentation Reconciler · ● 2.5M · ◷

• expires on Apr 9, 2026, 3:56 AM UTC