📚 Documentation Reconciliation Report - 2026-02-05

[github-actions]

Summary

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

• Date: 2026-02-05
• Branch: main
• Status: Minor documentation gaps found

Important Issues 🟡

Issues that are misleading but have workarounds:

1. Missing --payload-dir Flag in README Usage Section

Location: README.md, line 214-226 (Usage section)

Problem: The README's Usage section shows CLI flags but is missing the --payload-dir flag that actually exists in the codebase.

Actual Behavior: The code defines --payload-dir flag in internal/cmd/flags_logging.go:

cmd.Flags().StringVar(&payloadDir, "payload-dir", getDefaultPayloadDir(), 
    "Directory for storing large payload files (segmented by session ID)")
``````

**Impact:** Users reading the CLI help in the README won't know about the `--payload-dir` flag and may not discover this feature for managing large tool response payloads.

**Suggested Fix:** Add the missing flag to the Usage section in README.md after line 220:
``````
      --payload-dir string  Directory for storing large payload files (segmented by session ID) (default "/tmp/jq-payloads")

Code Reference: internal/cmd/flags_logging.go:26-27

Minor Issues 🔵

Small inconsistencies or missing details:

1. Missing MCP_GATEWAY_PAYLOAD_DIR Environment Variable Documentation

Location: README.md, line 232-263 (Environment Variables section)

Problem: The environment variable MCP_GATEWAY_PAYLOAD_DIR is not documented in the Environment Variables section, even though it's used in the code.

Actual Behavior: The code checks for MCP_GATEWAY_PAYLOAD_DIR in internal/cmd/flags_logging.go:

func getDefaultPayloadDir() string {
    if envPayloadDir := os.Getenv("MCP_GATEWAY_PAYLOAD_DIR"); envPayloadDir != "" {
        return envPayloadDir
    }
    return defaultPayloadDir
}

Impact: Users won't know they can set this environment variable to customize the payload directory location, especially useful in containerized environments.

Suggested Fix: Add to the "Optional (Non-Containerized Mode)" table in the Environment Variables section:

| `MCP_GATEWAY_PAYLOAD_DIR` | Large payload storage directory (sets default for `--payload-dir` flag) | `/tmp/jq-payloads` |

Code Reference: internal/cmd/flags_logging.go:40-46

2. Quick Start payload_dir Configuration Not Mentioned

Location: README.md, line 38-51 (Quick Start configuration example)

Problem: The Quick Start configuration example doesn't show the optional payload_dir field in the gateway configuration, even though it's supported.

Actual Behavior: The code supports payload_dir in both TOML and JSON configurations:

• internal/config/config_core.go: PayloadDir string field in GatewayConfig
• internal/config/config_stdin.go: PayloadDir string field in StdinGatewayConfig

Impact: Users won't know they can configure the payload directory in their configuration files.

Suggested Fix: Add a note or example showing the payload_dir field can be set in gateway configuration. Note: config.example.toml already documents this correctly, so this is just about the README examples.

Code Reference:

• internal/config/config_core.go:56
• internal/config/config_stdin.go:33

Documentation Completeness

Missing Documentation

• --payload-dir CLI flag - implemented but missing from Usage section
• MCP_GATEWAY_PAYLOAD_DIR environment variable - implemented but not in Environment Variables table

Accurate Sections ✅

The following sections were verified to be accurate and match the implementation:

• ✅ Docker Quick Start section - verified accurate
• ✅ TOML configuration format - verified accurate
• ✅ JSON stdin format - verified accurate
• ✅ Configuration validation rules - verified accurate
• ✅ Variable expansion (${VAR_NAME}) - verified accurate
• ✅ Schema normalization - verified accurate
• ✅ Routing modes (routed/unified) - verified accurate
• ✅ Docker support - verified accurate
• ✅ All make targets in CONTRIBUTING.md - verified all exist and work
• ✅ Prerequisites (Go 1.25.0) - matches go.mod
• ✅ Binary name (awmg) - verified correct
• ✅ Authentication (MCP spec 7.1) - verified accurate
• ✅ All other documented environment variables - verified accurate

Tested Commands

All commands from CONTRIBUTING.md were verified against the Makefile:

• ✅ make build - works as documented
• ✅ make test / make test-unit - works as documented
• ✅ make test-integration - works as documented
• ✅ make test-all - works as documented
• ✅ make lint - works as documented
• ✅ make coverage - works as documented
• ✅ make install - works as documented
• ✅ make format - works as documented
• ✅ make clean - works as documented
• ✅ make agent-finished - works as documented

Recommendations

Immediate Actions Required:

1. Add --payload-dir flag to README Usage section (line ~221)
2. Add MCP_GATEWAY_PAYLOAD_DIR to Environment Variables table (line ~257)

Nice to Have:

1. Mention payload_dir configuration option in Quick Start or Configuration examples

Code References

Key files validated:

• Configuration: internal/config/config_core.go, internal/config/config_stdin.go
• Validation: internal/config/validation.go
• CLI flags: internal/cmd/flags_core.go, internal/cmd/flags_logging.go
• Build system: Makefile
• Startup scripts: run.sh, run_containerized.sh
• Example config: config.example.toml (already accurate)

AI generated by Nightly Documentation Reconciler

• expires on Feb 8, 2026, 5:27 AM UTC