📚 Documentation Reconciliation Report - 2026-05-19

[github-actions]

Summary

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

• Workflow Run: §26130509381
• Date: 2026-05-19
• Branch: main

---

Critical Issues 🔴

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

1. MCP_GATEWAY_PORT incorrectly described as setting the binary's listen address

Location: docs/ENVIRONMENT_VARIABLES.md, line 11 (Required for Production table)

Problem: The description states the variable is "used for --listen address". This is false. The awmg binary does not read MCP_GATEWAY_PORT to configure its listen address. The function GetGatewayPortFromEnv() in internal/config/config_env.go is only called from --validate-env validation logic (internal/config/validation_env.go), never from the command layer that sets --listen.

Actual Behavior: run.sh reads MCP_GATEWAY_PORT and passes it as part of the --listen HOST:PORT flag. The binary itself only uses this env var to validate port mapping in --validate-env mode.

Impact: Users who set MCP_GATEWAY_PORT expecting the binary to auto-configure its listen port will be confused when it has no effect (unless using run.sh).

Suggested Fix: Update the description to:

MCP_GATEWAY_PORT — Port used by run.sh/run_containerized.sh to build the --listen address; also validated by --validate-env for port-mapping checks. The awmg binary does not read this to auto-configure its listen port — use --listen directly.

Code Reference: internal/config/config_env.go (GetGatewayPortFromEnv), internal/config/validation_env.go, run.sh:128

---

2. Two conflicting default values for MCP_GATEWAY_PORT

Location: docs/ENVIRONMENT_VARIABLES.md, lines 11 and 21

Problem: The variable appears twice with inconsistent example/default values:

• Line 11 (Required for Production table): example value is 8080
• Line 21 (Optional/Non-Containerized table): default listed as 8000

run.sh line 128 confirms: PORT="${MCP_GATEWAY_PORT:-${PORT:-8000}}" — the real default is 8000, not 8080.

Impact: Users may configure the wrong default port when reading different parts of the docs.

Suggested Fix: Unify both entries to 8000. The 8080 example in line 11 should be corrected or explicitly marked as "example only."

Code Reference: run.sh:128

---

Important Issues 🟡

Issues that are misleading but have workarounds.

3. docs/ENVIRONMENT_VARIABLES.md note about binary-read env vars is incomplete

Location: docs/ENVIRONMENT_VARIABLES.md, note at line 42

Problem: The note says "PORT, HOST, and MODE are not read by the awmg binary directly." However, it fails to mention that MCP_GATEWAY_PORT IS read by the binary — but only for --validate-env. Combined with the incorrect description in issue #1 above, this creates contradictory guidance.

Suggested Fix: Add: "MCP_GATEWAY_PORT is read by the binary for --validate-env port-mapping checks only; it does not configure the listen address."

---

4. make agent-finished silently skips integration tests if they require special setup beyond the binary

Location: CONTRIBUTING.md, line 592

Problem: The comment describes agent-finished as running "all tests (unit, integration, rust-guard)". The actual target runs go test ./... (not make test-integration explicitly). Today this works because the binary is built in the same target. However, if integration tests ever require special setup beyond a compiled binary, agent-finished may silently miss them without any documentation warning.

Suggested Fix: Either call make test-integration explicitly in the agent-finished target, or clarify the comment to note the distinction.

Code Reference: Makefile, agent-finished target

---

5. make test-rust is undocumented as a standalone target in CONTRIBUTING.md

Location: CONTRIBUTING.md (no dedicated section for test-rust)

Problem: make test-rust is a valid, listed Makefile target (visible in make help) that runs Rust guard unit tests via cargo. CONTRIBUTING.md only mentions it implicitly in the agent-finished comment. There's no explanation of when or why to run it, or that it requires a Rust toolchain.

Suggested Fix: Add a "Running Rust Guard Tests" subsection:

#### Rust Guard Tests

Run Rust guard unit tests (requires `cargo`):
```bash
make test-rust

Install the Rust toolchain from (rustup.rs/redacted) if not already present.

---

## Minor Issues 🔵

Small inconsistencies or missing details.

### 6. `MCP_GATEWAY_GUARD_POLICY_JSON` missing from `docs/ENVIRONMENT_VARIABLES.md`

**Problem:** Used in `internal/cmd/proxy.go` as default for `--policy` flag via `os.Getenv("MCP_GATEWAY_GUARD_POLICY_JSON")`. Documented in AGENTS.md but absent from `docs/ENVIRONMENT_VARIABLES.md`.

**Suggested Fix:** Add to the guard/proxy section of `docs/ENVIRONMENT_VARIABLES.md`.

**Code Reference:** `internal/cmd/proxy.go:112`

---

### 7. `MCP_GATEWAY_ALLOWONLY_*` env vars missing from `docs/ENVIRONMENT_VARIABLES.md`

**Problem:** Four env vars are defined as constants in `internal/config/guard_policy_parse.go` and documented in AGENTS.md, but absent from `docs/ENVIRONMENT_VARIABLES.md`:
- `MCP_GATEWAY_ALLOWONLY_SCOPE_PUBLIC`
- `MCP_GATEWAY_ALLOWONLY_SCOPE_OWNER`
- `MCP_GATEWAY_ALLOWONLY_SCOPE_REPO`
- `MCP_GATEWAY_ALLOWONLY_MIN_INTEGRITY`

**Suggested Fix:** Add all four to the guard configuration section of `docs/ENVIRONMENT_VARIABLES.md`.

**Code Reference:** `internal/config/guard_policy_parse.go` (constants)

---

### 8. `StdinServerConfig` struct lacks a comment explaining the omission of `command` field

**Location:** `internal/config/config_stdin.go`, `StdinServerConfig` struct

**Problem:** Unlike the parallel TOML `ServerConfig` which has a `Command string` field, `StdinServerConfig` correctly omits it — but there's no Go doc comment explaining this asymmetry. Contributors comparing the two structs may wonder if the field is missing by mistake.

**Suggested Fix:** Add a struct comment:
```go
// StdinServerConfig represents a server entry in JSON stdin format.
// Note: unlike TOML ServerConfig, this struct has no Command field;
// stdio servers must use Container instead.

---

9. AGENTS.md description of agent-finished does not mention Rust guard tests

Location: AGENTS.md, agent-finished entry

Problem: AGENTS.md says "Run format, build, lint, and all tests - ALWAYS run before completion" but doesn't mention Rust guard tests, while CONTRIBUTING.md correctly notes "(unit, integration, rust-guard)".

Suggested Fix: Update AGENTS.md description to: "Run format, build, lint, and all tests (unit, integration, Rust guard) — ALWAYS run before completion."

---

Documentation Completeness

Missing Documentation

• MCP_GATEWAY_GUARD_POLICY_JSON is used in code but absent from docs/ENVIRONMENT_VARIABLES.md
• MCP_GATEWAY_ALLOWONLY_* (4 vars) are used in code but absent from docs/ENVIRONMENT_VARIABLES.md
• make test-rust exists and works but has no dedicated documentation in CONTRIBUTING.md

Outdated Documentation

• docs/ENVIRONMENT_VARIABLES.md line 11: MCP_GATEWAY_PORT incorrectly described as configuring the binary's listen address
• docs/ENVIRONMENT_VARIABLES.md lines 11/21: conflicting default values (8080 vs 8000) for MCP_GATEWAY_PORT

---

Accurate Sections ✅

These areas were verified correct:

• Go version — go.mod says go 1.25.0; CONTRIBUTING.md matches ✅
• Default listen address — (127.0.0.1/redacted) in README matches DefaultListenIPv4/DefaultListenPort` in code ✅
• All make targets — build, test, test-unit, test-integration, test-all, test-race, lint, coverage, test-ci, format, clean, install, agent-finished all exist in Makefile ✅
• Auth header — Authorization: (api-key) (plain, not Bearer) documented correctly per spec 7.1 ✅
• TOML config fields — config.example.toml and CONFIGURATION.md cover all GatewayConfig/ServerConfig fields ✅
• JSON stdin command field not supported — AGENTS.md, CONFIGURATION.md, and code all consistent ✅
• rate_limit_threshold/cooldown/working_directory TOML-only — Correctly documented and absent from StdinServerConfig ✅
• GitHub token priority order — GITHUB_MCP_SERVER_TOKEN > GITHUB_TOKEN > GITHUB_PERSONAL_ACCESS_TOKEN > GH_TOKEN matches internal/envutil/github.go ✅
• OIDC env vars — ACTIONS_ID_TOKEN_REQUEST_URL/_TOKEN documented and used correctly ✅
• Routing modes — /mcp/{serverID} (routed) and /mcp (unified) verified in internal/server/ ✅
• golangci-lint version — v2.8.0 in CONTRIBUTING.md matches Makefile install target ✅
• AWMG_BINARY_PATH/AWMG_WASM_GUARD_PATH — Documented in CONTRIBUTING.md and used in integration tests ✅
• DEBUG/DEBUG_COLORS — Documented and implemented via logger.EnvDebug/logger.EnvDebugColors ✅
• DOCKER_HOST — Documented and used in internal/sys/docker.go ✅
• RUNNING_IN_CONTAINER — Documented and used in internal/sys/container.go ✅
• OTEL env vars — OTEL_EXPORTER_OTLP_ENDPOINT/_HEADERS/OTEL_SERVICE_NAME all documented and used ✅

---

Tested Commands

All commands from CONTRIBUTING.md were verified:

• ✅ make build — builds awmg binary as documented
• ✅ make test — runs unit tests
• ✅ make test-unit — runs unit tests only
• ✅ make test-integration — runs integration tests (requires binary)
• ✅ make test-all — runs unit + integration
• ✅ make lint — runs go vet, gofmt, golangci-lint
• ✅ make coverage — produces coverage report
• ✅ make install — installs toolchain and deps

---

Recommendations

Immediate Actions Required

1. Fix docs/ENVIRONMENT_VARIABLES.md line 11: correct MCP_GATEWAY_PORT description (Critical issue Configure as a Go CLI tool #1)
2. Fix docs/ENVIRONMENT_VARIABLES.md lines 11/21: unify default value to 8000 (Critical issue Lpcox/initial implementation #2)

Nice to Have

1. Add MCP_GATEWAY_GUARD_POLICY_JSON and MCP_GATEWAY_ALLOWONLY_* to docs/ENVIRONMENT_VARIABLES.md
2. Add make test-rust documentation section in CONTRIBUTING.md
3. Add Go doc comment to StdinServerConfig explaining the absence of command field
4. Align agent-finished description in AGENTS.md to mention Rust guard tests

---

Code References

• internal/config/config_env.go — GetGatewayPortFromEnv()
• internal/config/validation_env.go — --validate-env logic
• internal/config/config_stdin.go — StdinServerConfig struct
• internal/config/guard_policy_parse.go — MCP_GATEWAY_ALLOWONLY_* constants
• internal/cmd/proxy.go:112 — MCP_GATEWAY_GUARD_POLICY_JSON usage
• run.sh:128 — MCP_GATEWAY_PORT default (8000)
• Makefile — agent-finished, test-rust targets

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

• expires on May 22, 2026, 11:07 PM UTC