Summary

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

• Workflow Run: §21890623217
• Date: February 11, 2026
• Branch: main

Critical Issues 🔴

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

1. Payload Size Threshold Default Value Mismatch

Location: README.md, lines 206, 281, 319

Problem: Documentation states the default payload size threshold is 1024 bytes (1KB), but the actual implementation uses 10240 bytes (10KB).

Actual Behavior:

• Code: internal/cmd/flags_logging.go:14 defines defaultPayloadSizeThreshold = 10240
• Code: internal/config/config_payload.go:11 defines DefaultPayloadSizeThreshold = 10240
• Tests: internal/cmd/flags_logging_test.go confirms default is 10240 bytes

Impact: Users expecting the documented 1KB threshold will actually get a 10KB threshold, which could result in:

• More payloads being stored inline than expected (up to 10KB instead of 1KB)
• Less disk I/O than anticipated
• Different memory usage patterns
• Confusion when testing payload storage behavior

Suggested Fix: Update README.md to reflect the actual default:

# Line 206
- CLI flag: `--payload-size-threshold (bytes)` (default: 10240)

# Line 281
--payload-size-threshold int   Size threshold (in bytes) for storing payloads to disk. Payloads larger than this are stored, smaller ones returned inline (default 10240)

# Line 319
| `MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD` | Size threshold in bytes for payload storage (sets default for `--payload-size-threshold` flag) | `10240` |

Code Reference:

• internal/cmd/flags_logging.go:14
• internal/config/config_payload.go:11
• internal/cmd/flags_logging_test.go:46

Minor Issues 🔵

Small inconsistencies or missing details:

1. Internal Directory Structure Incomplete in CONTRIBUTING.md

Location: CONTRIBUTING.md, lines 206-233 (Project Structure section)

Problem: Documentation lists only 7 internal directories, but 16 actually exist.

Missing Directories:

• internal/difc/ - Data Information Flow Control
• internal/envutil/ - Environment variable utilities
• internal/middleware/ - HTTP middleware (jq schema processing)
• internal/sys/ - System utilities
• internal/testutil/ - Test utilities and helpers
• internal/tty/ - Terminal detection utilities
• internal/version/ - Version management

Impact: Developers may be unaware of these internal packages when working on the codebase, potentially duplicating functionality or missing useful utilities.

Suggested Fix: Update the Project Structure section to include all internal directories with brief descriptions.

Code Reference: Directory listing shows all 16 directories exist and contain working code.

2. Internal Directory Structure Incomplete in AGENTS.md

Location: AGENTS.md, lines 12-20 (Project Structure section)

Problem: Similar to CONTRIBUTING.md, lists only 9 internal directories instead of 16.

Missing Directories: Same as above (difc, envutil, middleware, sys, testutil, tty, version)

Impact: AI agents working with the codebase may not be aware of all available internal packages.

Suggested Fix: Update the Project Structure section to include all internal directories.

Code Reference: Same directory listing as above.

Documentation Completeness

Accurate Sections ✅

The following sections were verified and found to be accurate:

• Go Version Requirement - Correctly documented as 1.25.0 (matches go.mod)
• Make Targets - All 11 documented targets exist and work correctly:
  • make build, test, test-unit, test-integration, test-all
  • make lint, coverage, install, agent-finished
  • make format, clean
• Configuration Fields - All documented fields match code struct definitions in internal/config/
• Environment Variables - Correctly documented and extensively used (140+ references in code)
• External Links:
  • MCP Gateway spec link is valid (returns HTTP 200)
  • GitHub token URL is valid (redirects properly)
• Feature Documentation:
  • HTTP transport correctly marked as "fully supported"
  • Container field requirement for stdio servers matches validation code
  • Command field restriction for JSON stdin format accurately documented
  • Sequential launch flag exists and works as documented
• CLI Flags - All documented flags exist and match actual implementation
• Docker Configuration Examples - Format and field names match actual usage
• Configuration Validation - Documented behavior matches internal/config/validation*.go

Tested Commands

All commands from CONTRIBUTING.md were verified using make --dry-run:

• ✅ make build - Works as documented (creates awmg binary)
• ✅ make test - Works as documented (alias for test-unit)
• ✅ make test-unit - Works as documented (runs unit tests)
• ✅ make test-integration - Works as documented (requires built binary)
• ✅ make test-all - Works as documented (runs all tests)
• ✅ make lint - Works as documented (go vet + gofmt + golangci-lint)
• ✅ make coverage - Works as documented (unit tests with coverage)
• ✅ make install - Works as documented (installs toolchains)
• ✅ make agent-finished - Works as documented (full verification pipeline)
• ✅ make format - Works as documented (auto-formats code)
• ✅ make clean - Works as documented (removes artifacts)

Recommendations

Immediate Actions Required:

1. Fix critical payload threshold discrepancy - Update README.md to reflect actual default of 10240 bytes
2. Update CONTRIBUTING.md project structure - Add missing internal directories
3. Update AGENTS.md project structure - Add missing internal directories

Nice to Have:

1. Consider documenting the purpose of each internal directory for developer clarity
2. Add cross-references between documentation files to maintain consistency
3. Consider adding a CI check to validate default values match between docs and code

Code References

• Configuration structs: internal/config/config_core.go, internal/config/config_payload.go
• Validation logic: internal/config/validation*.go
• CLI flags: internal/cmd/flags_logging.go
• Default constants: internal/config/config_payload.go:11, internal/cmd/flags_logging.go:14

AI generated by Nightly Documentation Reconciler

• expires on Feb 14, 2026, 2:43 AM UTC