Add missing tests and update README for payload path prefix

- Add unit test for savePayload() path remapping behavior
- Add unit test for getDefaultPayloadPathPrefix() env var handling
- Update README to explicitly note payloadPathPrefix not supported in JSON stdin
- Update CLI help output to include --payload-path-prefix flag

Addresses Copilot review comments

Co-authored-by: lpcox <15877973+lpcox@users.noreply.github.com>

Author: Claude

README.md

@@ -225,7 +225,7 @@ See **[Configuration Specification](https://github.com/github/gh-aw/blob/main/do
   - TOML config file: `payload_size_threshold = <bytes>` in `[gateway]` section
   - Payloads **larger** than this threshold are stored to disk and return metadata
   - Payloads **smaller than or equal** to this threshold are returned inline
-- **`payloadPathPrefix`** configures path remapping for clients/agents:
+- **`payloadPathPrefix`** is not supported in JSON stdin format. Use:
   - CLI flag: `--payload-path-prefix <path>` (default: empty - use actual filesystem path)
   - Environment variable: `MCP_GATEWAY_PAYLOAD_PATH_PREFIX=<path>`
   - TOML config file: `payload_path_prefix = "<path>"` in `[gateway]` section
@@ -304,13 +304,14 @@ Flags:
   -l, --listen string                HTTP server listen address (default "127.0.0.1:3000")
       --log-dir string               Directory for log files (falls back to stdout if directory cannot be created) (default "/tmp/gh-aw/mcp-logs")
       --payload-dir string           Directory for storing large payload files (segmented by session ID) (default "/tmp/jq-payloads")
+      --payload-path-prefix string   Path prefix to use when returning payloadPath to clients (allows remapping host paths to client/agent container paths)
       --payload-size-threshold int   Size threshold (in bytes) for storing payloads to disk. Payloads larger than this are stored, smaller ones returned inline (default 524288)
       --routed                       Run in routed mode (each backend at /mcp/<server>)
-      --sequential-launch   Launch MCP servers sequentially during startup (parallel launch is default)
-      --unified             Run in unified mode (all backends at /mcp)
-      --validate-env        Validate execution environment (Docker, env vars) before starting
-  -v, --verbose count       Increase verbosity level (use -v for info, -vv for debug, -vvv for trace)
-      --version             version for awmg
+      --sequential-launch            Launch MCP servers sequentially during startup (parallel launch is default)
+      --unified                      Run in unified mode (all backends at /mcp)
+      --validate-env                 Validate execution environment (Docker, env vars) before starting
+  -v, --verbose count                Increase verbosity level (use -v for info, -vv for debug, -vvv for trace)
+      --version                      version for awmg
 
 Use "awmg [command] --help" for more information about a command.
 ```

internal/cmd/flags_logging_test.go

@@ -163,3 +163,43 @@ func TestPayloadSizeThresholdEnvVar(t *testing.T) {
 	result := getDefaultPayloadSizeThreshold()
 	assert.Equal(t, 4096, result, "Environment variable should override default")
 }
+
+func TestGetDefaultPayloadPathPrefix(t *testing.T) {
+	tests := []struct {
+		name     string
+		envValue string
+		setEnv   bool
+		expected string
+	}{
+		{
+			name:     "no env var - returns default",
+			setEnv:   false,
+			expected: defaultPayloadPathPrefix,
+		},
+		{
+			name:     "env var set - returns custom path",
+			envValue: "/workspace/payloads",
+			setEnv:   true,
+			expected: "/workspace/payloads",
+		},
+		{
+			name:     "empty env var - returns default",
+			envValue: "",
+			setEnv:   true,
+			expected: defaultPayloadPathPrefix,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.setEnv {
+				t.Setenv("MCP_GATEWAY_PAYLOAD_PATH_PREFIX", tt.envValue)
+			} else {
+				t.Setenv("MCP_GATEWAY_PAYLOAD_PATH_PREFIX", "")
+			}
+
+			result := getDefaultPayloadPathPrefix()
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}

internal/middleware/jqschema_test.go

@@ -133,6 +133,34 @@ func TestSavePayload(t *testing.T) {
 	assert.DirExists(t, expectedDir, "Directory should exist")
 }
 
+func TestSavePayloadWithPathPrefix(t *testing.T) {
+	// Create temporary directory for test
+	baseDir := filepath.Join(os.TempDir(), "test-jq-payloads-prefix")
+	defer os.RemoveAll(baseDir)
+
+	sessionID := "test-session-789"
+	queryID := "test-query-abc"
+	payload := []byte(`{"test": "data with prefix"}`)
+	pathPrefix := "/workspace/payloads"
+
+	returnedPath, err := savePayload(baseDir, pathPrefix, sessionID, queryID, payload)
+	require.NoError(t, err, "savePayload should not return error")
+
+	// Verify the actual file was written to the baseDir (filesystem path)
+	actualFilePath := filepath.Join(baseDir, sessionID, queryID, "payload.json")
+	assert.FileExists(t, actualFilePath, "Payload file should exist at actual filesystem path")
+
+	// Verify file content
+	content, err := os.ReadFile(actualFilePath)
+	require.NoError(t, err, "Should be able to read payload file")
+	assert.Equal(t, payload, content, "File content should match payload")
+
+	// Verify the returned path uses the pathPrefix (remapped for client)
+	expectedReturnPath := filepath.Join(pathPrefix, sessionID, queryID, "payload.json")
+	assert.Equal(t, expectedReturnPath, returnedPath, "Returned path should use pathPrefix")
+	assert.NotEqual(t, actualFilePath, returnedPath, "Returned path should differ from actual filesystem path")
+}
+
 func TestWrapToolHandler(t *testing.T) {
 	// Create temporary directory for test
 	baseDir := filepath.Join(os.TempDir(), "test-jq-payloads")