📚 Documentation Reconciliation Report - 2026-04-12

[github-actions]

Summary

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

• Workflow Run: §24298069562
• Date: 2026-04-12
• Branch: main

---

Critical Issues 🔴

1. Wrong default values for startupTimeout and toolTimeout in docs/CONFIGURATION.md

Location: docs/CONFIGURATION.md, Gateway Configuration Fields table (lines 368–369)

Problem: The table documents incorrect default values for two gateway timeout fields:

Field	Documented Default	Actual Code Default
startupTimeout	60	30
toolTimeout	120	60

Actual Behavior: internal/config/config_core.go defines:

DefaultStartupTimeout = 30   // seconds (per spec §4.1.3)
DefaultToolTimeout    = 60   // seconds (per spec §4.1.3)

These constants are used in both applyGatewayDefaults() and convertStdinConfig(), so they are authoritative for both TOML and JSON stdin loading paths.

Impact: Users relying on documented defaults may be surprised when their backends time out at 30s (startup) or 60s (tool calls) instead of the documented 60s / 120s. This can cause silent failures when migrating from config files that omit these fields.

Suggested Fix:

-| `startupTimeout` | Seconds to wait for backend startup | `60` |
-| `toolTimeout` | Seconds to wait for tool execution | `120` |
+| `startupTimeout` | Seconds to wait for backend startup | `30` |
+| `toolTimeout` | Seconds to wait for tool execution | `60` |

Code Reference: internal/config/config_core.go:41-42

---

Important Issues 🟡

2. Incorrect default comments in config.example.toml

Location: config.example.toml, comments above startup_timeout and tool_timeout fields

Problem: The comment block in the example config documents the wrong defaults:

# Timeout for backend MCP server startup in seconds (default: 60)
startup_timeout = 60

# Timeout for tool execution in seconds (default: 120)
tool_timeout = 120

Actual Behavior: The code defaults (config_core.go) are 30 and 60 respectively. The example file happens to use explicit values (60 and 120) that are double the actual defaults, and the inline comments reinforce the incorrect values as if they were defaults.

Impact: Developers using the example config as a reference will believe the defaults are 60s and 120s. The example values also set production timeouts to double the intended defaults, which may mask performance issues in test environments.

Suggested Fix:

-# Timeout for backend MCP server startup in seconds (default: 60)
+# Timeout for backend MCP server startup in seconds (default: 30)
 startup_timeout = 60

-# Timeout for tool execution in seconds (default: 120)
+# Timeout for tool execution in seconds (default: 60)
 tool_timeout = 120
```
(The example values themselves can remain at 60/120 as explicit overrides, but the default annotations should be corrected.)

**Code Reference:** `internal/config/config_core.go:41-42`

---

## Minor Issues 🔵

### 3. `domain` field default documented as `"localhost"` but has no code-level default

**Location:** `docs/CONFIGURATION.md`, Gateway Configuration Fields table (line 367)

**Problem:** The table shows:
```
| `domain` | Gateway domain (`"localhost"`, `"host.docker.internal"`, or `"\$\{VAR}"`) | `localhost` |

Actual Behavior: applyGatewayDefaults() does not set any default for the Domain field; it remains an empty string unless explicitly configured. The validation in validation_schema.go only activates when domain != "", confirming it is fully optional with no fallback default.

Impact: Minor: users may expect domain to default to "localhost" and be surprised when it is empty. This is low severity because the field is optional and the gateway works without it for most use cases.

Suggested Fix:

-| `domain` | Gateway domain (`"localhost"`, `"host.docker.internal"`, or `"\$\{VAR}"`) | `localhost` |
+| `domain` | Gateway domain (`"localhost"`, `"host.docker.internal"`, or `"\$\{VAR}"`) | (unset) |

Code Reference: internal/config/config_core.go:84, internal/config/config_core.go:218-234

---

Documentation Completeness

Accurate Sections ✅

• README.md Quick Start JSON config — type, container, env, gateway.apiKey fields verified against StdinServerConfig and StdinGatewayConfig structs ✅
• README.md Docker run command — MCP_GATEWAY_PORT, MCP_GATEWAY_DOMAIN, MCP_GATEWAY_API_KEY are used by run_containerized.sh entrypoint ✅
• README.md -i flag explanation — run_containerized.sh does use --config-stdin and depends on stdin being connected ✅
• README.md Guard policy documentation — allow-only, write-sink, field names match implementation ✅
• CONTRIBUTING.md Go version (1.25.0) — matches go.mod ✅
• CONTRIBUTING.md binary name (awmg) — matches Makefile BINARY_NAME=awmg ✅
• CONTRIBUTING.md make install description — accurately describes Go check, golangci-lint install, go mod download/verify ✅
• CONTRIBUTING.md project structure — all 22 listed internal/ directories verified to exist ✅
• CONTRIBUTING.md CLI flags — --config, --config-stdin, --log-dir, --payload-dir, --payload-size-threshold, --env, -v all verified in internal/cmd/flags_*.go ✅
• All documented make targets — build, test, test-unit, test-integration, test-all, test-ci, lint, coverage, format, clean, install, test-serena, test-serena-gateway, test-container-proxy all present in Makefile ✅
• CONTRIBUTING.md test split description — unit vs integration split accurately described ✅

---

Tested Commands

• ⚠️ make build — could not test: Go 1.25.0 toolchain download blocked (network/firewall restriction in CI environment); Dockerfile confirmed using golang:1.25-alpine
• ✅ make --dry-run build/test/lint/coverage/install — all targets resolve without errors
• ✅ Config struct field audit — internal/config/config_core.go and internal/config/config_stdin.go cross-referenced against README and CONFIGURATION.md
• ✅ CLI flags audit — all flags in internal/cmd/flags_*.go verified against CONTRIBUTING.md and AGENTS.md

---

Recommendations

Immediate Actions Required:

1. Fix docs/CONFIGURATION.md table: change startupTimeout default from 60 → 30, toolTimeout from 120 → 60
2. Fix config.example.toml comments: correct the (default: 60) and (default: 120) annotations

Nice to Have:

1. Clarify domain default in docs/CONFIGURATION.md — change from localhost to (unset) to avoid the impression that the gateway resolves to localhost by default

Code References

• Authoritative defaults: internal/config/config_core.go:39-44
• Default application (TOML path): internal/config/config_core.go:221-234
• Default application (JSON stdin path): internal/config/config_stdin.go:303-309
• Example config: config.example.toml
• Configuration docs: docs/CONFIGURATION.md:368-369

Generated by Nightly Documentation Reconciler · ● 1.9M · ◷

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