📚 Documentation Reconciliation Report - 2026-03-25

[github-actions]

Summary

Nightly documentation reconciliation identified 1 gap and 1 minor omission between documentation and implementation. The overall documentation quality is high — most claims were verified as accurate.

• Workflow Run: §23562895819
• Date: 2026-03-25
• Branch: main

---

Important Issues 🟡

1. docs/ENVIRONMENT_VARIABLES.md Missing Proxy Mode Variables

Location: docs/ENVIRONMENT_VARIABLES.md, header line
Problem: The file's title claims "Complete reference for MCP Gateway environment variables" and README.md describes it as "All env vars for production, development, Docker, and guard configuration" — but proxy mode (awmg proxy) environment variables are absent from the file entirely.
Missing Variables:

• GITHUB_API_URL — Explicit GitHub API endpoint for proxy upstream; read by internal/proxy/proxy.go:45
• GITHUB_SERVER_URL — Auto-derive API endpoint from server URL for proxy mode; read by internal/proxy/proxy.go:49
• GITHUB_TOKEN / GH_TOKEN — GitHub auth token used by proxy mode; read in internal/cmd/proxy.go

Actual Behavior: These variables ARE used by proxy mode code but are only documented in docs/PROXY_MODE.md, not in the canonical env vars reference.
Impact: Users consulting docs/ENVIRONMENT_VARIABLES.md for proxy mode setup will not find these variables, causing confusion.
Suggested Fix: Add a "Proxy Mode" section to docs/ENVIRONMENT_VARIABLES.md:

## Proxy Mode Variables

When running `awmg proxy`, these variables configure the upstream GitHub API:

| Variable | Description | Default |
|----------|-------------|---------|
| `GITHUB_API_URL` | Explicit GitHub API endpoint (e.g., `(copilotapi.mycompany.ghe.com/redacted)`); used by proxy to set upstream target | (auto-derived) |
| `GITHUB_SERVER_URL` | GitHub server URL; proxy auto-derives API endpoint: `*.ghe.com` → `copilot-api.*.ghe.com`, GHES → `<host>/api/v3`, `github.com` → `api.github.com` | (falls back to `api.github.com`) |
| `GITHUB_TOKEN` / `GH_TOKEN` | GitHub auth token for the proxy to forward requests | (required) |

Code References: internal/proxy/proxy.go:38-56, internal/cmd/proxy.go:95

---

Minor Issues 🔵

2. docs/GATEWAY_COMPATIBILITY_QUICK_REFERENCE.md Not Listed in README Further Reading

Location: README.md "Further Reading" table
Problem: The file docs/GATEWAY_COMPATIBILITY_QUICK_REFERENCE.md exists in the repository but is not referenced in the README's Further Reading table.
Impact: Users browsing docs from the README will not discover this reference document.
Suggested Fix: Add a row to the Further Reading table in README.md:

| **Gateway Compatibility** | [docs/GATEWAY_COMPATIBILITY_QUICK_REFERENCE.md](docs/GATEWAY_COMPATIBILITY_QUICK_REFERENCE.md) — Quick reference for gateway compatibility |

---

Accurate Sections ✅

The following were verified as accurate:

• README.md Quick Start — JSON config structure matches StdinConfig, StdinGatewayConfig, StdinServerConfig struct definitions exactly
• CONTRIBUTING.md Make Targets — All targets (build, test, test-unit, test-integration, test-all, lint, coverage, install, format, clean) exist in Makefile with correct descriptions
• Go Version Requirement — CONTRIBUTING.md states Go 1.25.0; go.mod confirms go 1.25.0
• Binary Name — awmg matches BINARY_NAME in Makefile
• Variable Expansion — Correctly documented: JSON stdin supports \$\{VAR} expansion, TOML does not
• Docker Run Examples — MCP_GATEWAY_PORT, MCP_GATEWAY_DOMAIN, MCP_GATEWAY_API_KEY correctly documented as required by run_containerized.sh's check_required_env_vars()
• --validate-env Flag — Exists and is implemented in internal/cmd/flags_core.go:41 and used in internal/cmd/root.go:170
• All docs/ files referenced from README — Verified all 8 linked docs files exist: CONFIGURATION.md, ENVIRONMENT_VARIABLES.md, PROXY_MODE.md, GUARD_RESPONSE_LABELING.md, HTTP_BACKEND_SESSION_ID.md, MCP_SERVER_ARCHITECTURE_PATTERNS.md, aw-security.md, GATEWAY_COMPATIBILITY_QUICK_REFERENCE.md
• CONTRIBUTING.md Architecture Notes — All 8 features listed verified as implemented in code
• docs/ENVIRONMENT_VARIABLES.md env var values — All 20+ documented gateway env vars confirmed in code with correct defaults
• TOML config field names — guard_policies, command, args, port, api_key etc. match TOML struct tags in internal/config/config_core.go
• JSON stdin field names — mcpServers, apiKey, container, entrypoint, entrypointArgs, mounts, guard-policies all match StdinServerConfig JSON struct tags

Tested Commands

Make targets verified via --dry-run:

• ✅ make build — compiles awmg binary
• ✅ make test — alias for test-unit
• ✅ make test-unit — runs go test ./internal/...
• ✅ make test-integration — runs binary integration tests
• ✅ make test-all — runs both unit + integration tests
• ✅ make lint — runs go vet, gofmt check, golangci-lint
• ✅ make coverage — runs unit tests with coverage profile
• ✅ make install — installs Go toolchain + golangci-lint + go mod download

Code References

• Proxy env vars: internal/proxy/proxy.go:38-56
• Proxy CLI flag: internal/cmd/proxy.go:95
• Config structs: internal/config/config_core.go, internal/config/config_stdin.go
• Env var helpers: internal/cmd/flags_logging.go, internal/cmd/flags_difc.go
• Validate-env flag: internal/cmd/flags_core.go:41

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

• expires on Mar 28, 2026, 8:47 PM UTC