Update documentation for mount absolute path requirement and DOCKER_API_VERSION behavior

[Claude]

The nightly documentation reconciliation workflow identified two discrepancies between documentation and code implementation.

Changes

• README.md: Added absolute path requirement for mount specifications in validation rules

  • Source and destination paths must be absolute (start with /)
  • Matches enforcement in internal/config/rules/rules.go:156-184 per MCP Gateway spec v1.8.0 section 4.1.5

• AGENTS.md: Updated DOCKER_API_VERSION documentation to reflect actual implementation

  • Changed from "1.43 (arm64) or 1.44 (amd64)" to "Set by querying Docker daemon's current API version; falls back to 1.44 for all architectures if detection fails"
  • Matches run_containerized.sh:240-244 behavior

Example

Users attempting relative paths in mount specifications will now understand why validation fails:

{
  "mounts": [
    "data:/app/data:ro"  // ❌ Fails: source must be absolute
  ]
}

Should be:

{
  "mounts": [
    "/host/data:/app/data:ro"  // ✅ Valid: both paths absolute
  ]
}

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-build573668252/b279/launcher.test /tmp/go-build573668252/b279/launcher.test -test.testlogfile=/tmp/go-build573668252/b279/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true rtcfg HEAD x_amd64/compile (dns block)
• invalid-host-that-does-not-exist-12345.com
  • Triggering command: /tmp/go-build573668252/b264/config.test /tmp/go-build573668252/b264/config.test -test.testlogfile=/tmp/go-build573668252/b264/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true 64/src/runtime/cgo 64/src/math/exp_amd64.s 64/bin/as (dns block)
• nonexistent.local
  • Triggering command: /tmp/go-build573668252/b279/launcher.test /tmp/go-build573668252/b279/launcher.test -test.testlogfile=/tmp/go-build573668252/b279/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true rtcfg HEAD x_amd64/compile (dns block)
• slow.example.com
  • Triggering command: /tmp/go-build573668252/b279/launcher.test /tmp/go-build573668252/b279/launcher.test -test.testlogfile=/tmp/go-build573668252/b279/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true rtcfg HEAD x_amd64/compile (dns block)
• this-host-does-not-exist-12345.com
  • Triggering command: /tmp/go-build573668252/b288/mcp.test /tmp/go-build573668252/b288/mcp.test -test.testlogfile=/tmp/go-build573668252/b288/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true 64/src/runtime/cgo lkem/cast.go x_amd64/compile (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 - 2026-02-22</issue_title>
<issue_description>## Summary

Found 1 discrepancy and 1 minor internal-doc inaccuracy between documentation and implementation during nightly reconciliation check.

• Workflow Run: §22271138666
• Date: 2026-02-22
• Branch: main

---

Important Issues 🟡

1. Mount Specification Validation — Missing Absolute Path Requirement

Location: README.md, Validation Rules section under "Server Configuration Fields → mounts"

Problem: The documentation states mount specifications must follow "source:dest:mode" format and lists these constraints:

• mode must be either "ro" or "rw"
• Both source and destination paths are required (cannot be empty)

However, the code also requires that both source and destination must be absolute paths (starting with /). This constraint is not mentioned in the README.

Actual Behavior: The validation code in internal/config/rules/rules.go:156-183 (per "MCP Gateway specification v1.8.0 section 4.1.5") enforces:

• Mount source MUST be an absolute path (starts with /)
• Mount destination MUST be an absolute path (starts with /)

Users attempting "./(redacted) or "(redacted) will receive:

Configuration error at mcpServers.(name).mounts[0]: mount source must be an absolute path, got 'data'

Impact: Users who read the documentation and try relative paths will get unexpected validation errors without any hint from the docs that absolute paths are required.

Suggested Fix: Update the Validation Rules bullet for mounts in README.md from:

- **Mount specifications** must follow `"source:dest:mode"` format
  - `mode` must be either `"ro"` or `"rw"`
  - Both source and destination paths are required (cannot be empty)

to:

- **Mount specifications** must follow `"source:dest:mode"` format
  - `source` must be an absolute path (e.g., `/host/data`)
  - `dest` must be an absolute path (e.g., `/app/data`)
  - `mode` must be either `"ro"` or `"rw"`
  - Both source and destination paths are required (cannot be empty)

Code Reference: internal/config/rules/rules.go:123-196 (MountFormat function)

---

Minor Issues 🔵

2. AGENTS.md — DOCKER_API_VERSION Documentation Outdated

Location: AGENTS.md, Environment Variables section

Problem: AGENTS.md states:

DOCKER_API_VERSION - 1.43 (arm64) or 1.44 (amd64)

Actual Behavior: run_containerized.sh uses 1.44 as the fallback for all architectures (both arm64 and amd64):

if [ "$arch" = "arm64" ] || [ "$arch" = "aarch64" ]; then
    export DOCKER_API_VERSION=1.44
else
    export DOCKER_API_VERSION=1.44
fi

README.md already correctly documents this as "falls back to 1.44 if detection fails." AGENTS.md is inconsistent with both README.md and the implementation.

Impact: AI agents using AGENTS.md as a reference may be confused about the architecture-specific API versions.

Suggested Fix: Update AGENTS.md to:

DOCKER_API_VERSION - Set by querying Docker daemon's current API version; falls back to 1.44 for all architectures if detection fails

Code Reference: run_containerized.sh:228-245

---

Documentation Completeness

Missing Documentation

• Mount specification absolute path requirement is enforced in code but not documented in README.md
• customSchemas field in JSON stdin format (StdinConfig.CustomSchemas) exists in code but is undocumented (this appears intentional as an advanced/experimental feature)

Outdated Documentation

• AGENTS.md DOCKER_API_VERSION mentions architecture-specific fallback values (1.43 arm64, 1.44 amd64) that no longer reflect the code (both use 1.44)

Accurate Sections ✅

• All CLI flags in README Usage section verified against internal/cmd/flags_*.go
• Environment variables table in README verified against code (envutil.GetEnvString calls)
• Default values (listen address 127.0.0.1:3000, log dir /tmp/gh-aw/mcp-logs, payload dir /tmp/jq-payloads, threshold 10240) all match code constants
• Go version requirement 1.25.0 matches go.mod
• All documented make targets verified: build, test, test-unit, test-integration, test-all, lint, coverage, install, format, clean
• JSON stdin format field names (camelCase) and TOML field names (snake_case) match struct tags
• Validation rules for required fields (container for stdio, url for http) match code
• payloadSizeThreshold correctly documented as not supported in JSON stdin format
• Dependencies listed in CONTRIBUTING.md match go.mod
• Project structure in CONTRIBUTING.md matches actual directories
• External spec link https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md returns HTTP 200

Tested Commands

...

• Fixes 📚 Documentation Reconciliation Report - 2026-02-22 #1287

[Copilot]

Pull request overview

Updates documentation to match existing implementation details surfaced by the nightly docs reconciliation workflow, reducing user confusion around config validation and container runtime behavior.

Changes:

• Documented that mount source and dest paths must be absolute in mount specs.
• Updated DOCKER_API_VERSION docs to reflect daemon-version detection with a universal 1.44 fallback.

Reviewed changes

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

File	Description
README.md	Adds the absolute-path requirement for mount source/dest in the validation rules section.
AGENTS.md	Corrects DOCKER_API_VERSION documentation to match run_containerized.sh behavior (daemon query; fallback 1.44).

---

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