Document payload directory configuration options

[Copilot]

Nightly reconciliation identified 3 undocumented features for large payload storage. The code supported --payload-dir flag, MCP_GATEWAY_PAYLOAD_DIR env var, and payload_dir config option, but none were documented.

Changes

• README.md CLI flags: Added --payload-dir flag to usage section with default /tmp/jq-payloads
• README.md environment variables: Added MCP_GATEWAY_PAYLOAD_DIR to optional variables table
• config.example.toml: Documented payload_dir gateway option with session segmentation pattern

All three methods configure the same directory where large tool response payloads are stored, organized as {payload_dir}/{sessionID}/{queryID}/payload.json.

Implementation in internal/cmd/flags_logging.go, internal/config/config_core.go, and internal/config/config_stdin.go unchanged.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>📚 Documentation Reconciliation Report - 2026-02-05</issue_title>
<issue_description>## 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
• ✅ `mak...

Custom agent used: agentic-workflows
GitHub Agentic Workflows (gh-aw) - Create, debug, and upgrade AI-powered workflows with intelligent prompt routing

• Fixes 📚 Documentation Reconciliation Report - 2026-02-05 #701

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Pull request overview

This PR documents three previously undocumented configuration options for large payload storage that were implemented in the code but missing from the main documentation files.

Changes:

• Added --payload-dir CLI flag documentation to README.md usage section
• Added MCP_GATEWAY_PAYLOAD_DIR environment variable to README.md environment variables table
• Added payload_dir configuration option documentation to config.example.toml with directory structure details

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
README.md	Added CLI flag and environment variable documentation for payload directory configuration
config.example.toml	Added commented example and detailed documentation for the payload_dir gateway option

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.