Fix documentation discrepancies: payload threshold and internal directories

[Claude]

Nightly documentation reconciliation identified critical discrepancies between documented and actual default values, plus incomplete internal directory listings.

Changes

Critical: Payload Size Threshold Default

Updated README.md (3 locations) to reflect actual implementation default of 10240 bytes (10KB) instead of incorrectly documented 1024 bytes:

• CLI flag description (line 206)
• Flags usage table (line 281)
• Environment variables table (line 319)

Implementation sources:

• internal/cmd/flags_logging.go:14 - defaultPayloadSizeThreshold = 10240
• internal/config/config_payload.go:11 - DefaultPayloadSizeThreshold = 10240

Minor: Complete Internal Directory Listings

Added missing internal packages to project structure documentation:

CONTRIBUTING.md: Added 9 missing directories (auth, difc, envutil, middleware, sys, testutil, version, tty, timeutil) to both tree diagram and Key Directories section

AGENTS.md: Added 7 missing directories (difc, envutil, middleware, sys, testutil, tty, version) to project structure list

All 16 internal directories now documented in alphabetical order:
auth, cmd, config, difc, envutil, guard, launcher, logger, mcp, middleware, server, sys, testutil, timeutil, tty, version

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• example.com
  • Triggering command: /tmp/go-build2370360416/b279/launcher.test /tmp/go-build2370360416/b279/launcher.test -test.testlogfile=/tmp/go-build2370360416/b279/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true 64/src/runtime/cgo git ache/go/1.25.6/x64/pkg/tool/linu-o --global r it 08.o -d go git x_amd64/vet e/REDACTED/work/gh/opt/hostedtoolcache/go/1.25.6/x64/pkg/tool/linux_amd64/vet 64/src/runtime/c-unsafeptr=false 64/bin/git x_amd64/vet (dns block)
• invalid-host-that-does-not-exist-12345.com
  • Triggering command: /tmp/go-build2370360416/b264/config.test /tmp/go-build2370360416/b264/config.test -test.testlogfile=/tmp/go-build2370360416/b264/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true 64/src/runtime/cgo HEAD ache/go/1.25.6/x64/pkg/tool/linu-fmessage-length=0 get --global rgo/bin/git 06.o -d 1.2.0/auth/auth.go git x_amd64/compile get --global .12/x64/which x_amd64/compile (dns block)
• nonexistent.local
  • Triggering command: /tmp/go-build2370360416/b279/launcher.test /tmp/go-build2370360416/b279/launcher.test -test.testlogfile=/tmp/go-build2370360416/b279/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true 64/src/runtime/cgo git ache/go/1.25.6/x64/pkg/tool/linu-o --global r it 08.o -d go git x_amd64/vet e/REDACTED/work/gh/opt/hostedtoolcache/go/1.25.6/x64/pkg/tool/linux_amd64/vet 64/src/runtime/c-unsafeptr=false 64/bin/git x_amd64/vet (dns block)
• slow.example.com
  • Triggering command: /tmp/go-build2370360416/b279/launcher.test /tmp/go-build2370360416/b279/launcher.test -test.testlogfile=/tmp/go-build2370360416/b279/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true 64/src/runtime/cgo git ache/go/1.25.6/x64/pkg/tool/linu-o --global r it 08.o -d go git x_amd64/vet e/REDACTED/work/gh/opt/hostedtoolcache/go/1.25.6/x64/pkg/tool/linux_amd64/vet 64/src/runtime/c-unsafeptr=false 64/bin/git x_amd64/vet (dns block)
• this-host-does-not-exist-12345.com
  • Triggering command: /tmp/go-build2370360416/b288/mcp.test /tmp/go-build2370360416/b288/mcp.test -test.testlogfile=/tmp/go-build2370360416/b288/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true g_.a 64/src/internal/bisect/bisect.go--64 86_64/as --global abis p/bin/git ache/go/1.25.6/x/tmp/go-build2370360416/b059/vet.cfg -d ; then \ $GOPATH/bin/golangci-lint run --timeout=5m || echo "��� Warning: golangci-lint failed /opt/hostedtoolcache/go/1.25.6/x64/pkg/tool/linux_amd64/link -wdcAJ1yv x_amd64/vet rt-size '1280, 7/opt/hostedtoolcache/go/1.25.6/x64/pkg/tool/linux_amd64/vet (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>📚 Documentation Reconciliation Report - February 11, 2026</issue_title>
<issue_description>## 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....

• Fixes 📚 Documentation Reconciliation Report - February 11, 2026 #886

[Copilot]

Pull request overview

This PR reconciles repository documentation with the implemented defaults and the actual internal/ package layout, reducing drift between docs and code.

Changes:

• Update README.md to document the correct default payload size threshold (10240 bytes).
• Expand CONTRIBUTING.md project structure to list all existing internal/ packages.
• Expand AGENTS.md project structure to list all existing internal/ packages for agent guidance.

Reviewed changes

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

File	Description
README.md	Updates documented default payload size threshold to 10240 bytes.
CONTRIBUTING.md	Completes the internal/ directory tree and “Key Directories” list.
AGENTS.md	Completes the internal/ package list for AI agent reference.

Comments suppressed due to low confidence (1)

CONTRIBUTING.md:238

• This entry expands DIFC as “Data Information Flow Control”, but the difc package documentation defines DIFC as “Decentralized Information Flow Control”. Please correct the expansion here for accuracy.

- **`internal/difc/`** - Data Information Flow Control
- **`internal/envutil/`** - Environment variable utilities

---

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

[Copilot]

internal/difc/ is described as “Data Information Flow Control”, but the package documentation defines DIFC as “Decentralized Information Flow Control”. Please update the description here (and keep it consistent across docs).

This issue also appears on line 237 of the same file.

Suggested change

	└── internal/
	├── auth/ # Authentication header parsing and middleware
	├── cmd/ # CLI commands (cobra)
	├── config/ # Configuration loading (TOML/JSON)
	├── difc/ # Data Information Flow Control
	└── internal/
	├── auth/ # Authentication header parsing and middleware
	├── cmd/ # CLI commands (cobra)
	├── config/ # Configuration loading (TOML/JSON)
	├── difc/ # Decentralized Information Flow Control

[Copilot]

internal/difc/ is described as “Data Information Flow Control”, but the package docs define DIFC as “Decentralized Information Flow Control” (see internal/difc/DIFC_RULES.md). Please update the wording here for accuracy/consistency.

Suggested change

	- `internal/difc/` - Data Information Flow Control
	- `internal/difc/` - Decentralized Information Flow Control

[Copilot]

README is updated to 10240 bytes for the default payload size threshold, but PAYLOAD_THRESHOLD_IMPLEMENTATION.md in this repo still documents the default as 1024 bytes in multiple places. Please update that doc as well (or remove it if it’s obsolete) to avoid ongoing documentation drift.

Suggested change

	- CLI flag: `--payload-size-threshold <bytes>` (default: 10240)
	- Environment variable: `MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD=<bytes>`
	- CLI flag: `--payload-size-threshold <bytes>` (default value is implementation-defined)
	- Environment variable: `MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD=<bytes>` (uses the same default as the CLI flag when unset)