📚 Documentation Reconciliation Report - 2026-07-24

[github-actions]

Summary

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

• Workflow Run: §30132590066
• Date: 2026-07-24
• Branch: main

---

Critical Issues 🔴

None found.

---

Important Issues 🟡

1. Tracing sample-rate has no env-var fallback

Location: README.md ~line 125
Problem: Tracing documentation implies full env/config parity, but --otlp-sample-rate has no environment variable fallback — only the endpoint and service name do.
Actual Behavior: CLI defines --otlp-sample-rate with a hardcoded default of 1.0 and no env fallback; only --otlp-endpoint and --otlp-service-name use env defaults.
Impact: Operators may expect to tune sampling via an environment variable and silently run at 100% sampling.
Suggested Fix: Clarify that otlp-sample-rate is CLI/config only, or add MCP_GATEWAY_OTLP_SAMPLE_RATE env-var support if desired.
Code Reference: internal/cmd/tracing.go:34-39

---

2. Container startup validation is overstated

Location: CONTRIBUTING.md ~lines 603–606
Problem: Documentation says startup always validates port mapping and environment before starting.
Actual Behavior: Port mapping validation is skipped when the container ID cannot be derived or host networking is used.
Impact: Readers may assume stricter startup guarantees than are actually provided in ARC/containerd or host-network cases.
Suggested Fix: Qualify the statement: port mapping is validated only when container ID/network mode inspection is available.
Code Reference: run_containerized.sh:178-210

---

3. README note on --config-stdin is incomplete

Location: README.md ~lines 51–53
Problem: The note says --config-stdin must be passed explicitly when piping, but doesn't explain that the CLI enforces one of --config or --config-stdin via MarkFlagsOneRequired.
Actual Behavior: Cobra enforces the mutual requirement; it is not just a recommendation.
Impact: The note is directionally correct but incomplete — the enforcement is by the CLI, not just convention.
Suggested Fix: State: "The CLI requires either --config or --config-stdin; piped JSON requires --config-stdin."
Code Reference: internal/cmd/flags_core.go:35-50

---

Minor Issues 🔵

4. Schema-required fields description is imprecise

Location: README.md ~line 34
Problem: "Schema-required fields" is vague.
Actual Behavior: JSON schema requires a top-level gateway object containing port, domain, and one of agentId/apiKey (anyOf).
Suggested Fix: Say: "the JSON schema requires a top-level gateway object containing port, domain, and one of agentId/apiKey."
Code Reference: internal/config/schema/mcp-gateway-config.schema.json:457-473

---

5. CONTRIBUTING.md Go version phrasing may imply broader support

Location: CONTRIBUTING.md ~line 8
Problem: "Go 1.26.4 or later" may suggest broader version support than is tested.
Actual Behavior: go.mod pins exactly go 1.26.4; Makefile also targets that version.
Suggested Fix: Prefer "Go 1.26.4" or "tested with Go 1.26.4+."
Code Reference: go.mod:3; Makefile:10-17

---

6. CONTRIBUTING.md JSON stdin example omits required gateway fields

Location: CONTRIBUTING.md ~lines 186–195
Problem: The manual JSON stdin example omits gateway.port, gateway.domain, and gateway.agentId/apiKey, which the JSON schema requires.
Actual Behavior: LoadFromStdin validates against the schema before conversion; missing gateway fields cause a fail-fast validation error.
Impact: Users copying the snippet will hit validation errors.
Suggested Fix: Show a minimal valid example including all required gateway fields, or reference example-http-config.json.
Code Reference: internal/config/config_stdin.go:359-368; internal/config/schema/mcp-gateway-config.schema.json:457-473

---

Documentation Completeness

Missing Documentation

• CONTRIBUTING.md should note that JSON stdin schema validation is fail-fast and requires a gateway object with port, domain, and one of agentId/apiKey before showing --config-stdin examples.
• README.md and CONTRIBUTING.md do not clearly explain that MCP_GATEWAY_SESSION_TIMEOUT is read directly by the HTTP server for routed/unified session TTL (internal/server/http_server.go:52-55).
• README.md and CONTRIBUTING.md do not mention that MCP_GATEWAY_CONTAINER_RUNTIME may be ignored when invalid/whitespace and that containerRuntimeCommand overrides the runtime executable (internal/config/container_runtime.go:51-90).

Outdated Documentation

• No major outdated sections found; most command, env-var, and architecture documentation matches current code.

Accurate Sections ✅

• README.md make/build/test target references align with Makefile targets (build, test, test-unit, lint, coverage, test-ci, test-integration, test-all, format, clean, agent-finished, etc.)
• README.md authentication token priority matches internal/envutil/github.go:22-42 (GITHUB_MCP_SERVER_TOKEN → GITHUB_TOKEN → GITHUB_PERSONAL_ACCESS_TOKEN → GH_TOKEN)
• README.md env var docs for MCP_GATEWAY_API_KEY deprecation align with internal/config/gateway_env.go:74-95
• README.md gateway field docs for payloadDir, payloadPathPrefix, payloadSizeThreshold, trustedBots, forcePublicRepos, sinkVisibilityExemptServers all align with code
• README.md note that gateway port is metadata-only aligns with config.example.toml comments and internal/cmd/root.go
• CONTRIBUTING.md test target descriptions match Makefile implementations
• CONTRIBUTING.md logger guidance matches logger.ForFile() usage patterns across the codebase

---

Tested Commands

Command	Status	Note
make --dry-run build	✅	Expands to go mod tidy + go build -o awmg .
make --dry-run test	✅	Alias to test-unit; runs go test -v -p=8 -parallel=8 -timeout=3m ./internal/...
make --dry-run lint	✅	Runs go mod tidy, go vet, gofmt check, golangci-lint
make build	⚠️	Blocked in CI: Go tried to download toolchain go1.26.4 from proxy.golang.org and got Forbidden
./awmg --help	⚠️	Not executed (binary not built due to above)

---

Recommendations

Immediate Actions

1. Fix the CONTRIBUTING.md JSON stdin example to include required gateway fields (or reference the example config file).
2. Clarify README tracing section: --otlp-sample-rate is CLI-only, no env-var equivalent exists.
3. Qualify container-startup validation claims in CONTRIBUTING.md to note conditional port-mapping checks.

Nice to Have

1. Add a short "minimal valid JSON stdin config" snippet shared by README.md and CONTRIBUTING.md.
2. Document exact precedence for runtime/config/env overrides in one canonical table (especially for tracing and container runtime fields).
3. Add a note in build docs about Go toolchain auto-download requirements for Go 1.21+ toolchain directives.

---

Code References

• Configuration structs: internal/config/config_core.go, internal/config/config_stdin.go
• Validation logic: internal/config/validation_schema.go, internal/config/schema/mcp-gateway-config.schema.json, internal/config/validation_server.go, internal/config/validation_gateway.go
• CLI flags: internal/cmd/flags_core.go, internal/cmd/tracing.go
• Container runtime: internal/config/container_runtime.go, run_containerized.sh

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 · 115.2 AIC · ⊞ 5.7K · ◷

• expires on Jul 27, 2026, 11:06 PM UTC