Fix environment variable documentation discrepancies (#901)

The documentation listed `HOST` and `MODE` as functional environment
variables when they're only used by test scripts. Meanwhile, the
functional `DEBUG` and `DEBUG_COLORS` variables were missing from the
environment variables table.

## Changes

**README.md - Optional Environment Variables:**
- Removed `HOST` and `MODE` from the table (test-only, not read by
gateway)
- Added `DEBUG` and `DEBUG_COLORS` with descriptions (functional but
undocumented)
- Added note directing users to `--listen` flag and
`--routed`/`--unified` flags
- Clarified `DOCKER_API_VERSION` is set by scripts but not read by Go
code (Docker client auto-negotiates)

**AGENTS.md - Environment Variables:**
- Removed `PORT`, `HOST`, `MODE` from list
- Added note explaining these are test-only variables and the gateway
uses CLI flags

## Context

The gateway application reads environment variables through
`os.Getenv()` calls in production code. Searching the codebase shows:
- `HOST` and `MODE` only appear in
`test/integration/pipe_launch_test.go` and helper scripts
- Gateway bind address is controlled by `--listen` flag
(internal/cmd/flags_core.go:37)
- Gateway mode is controlled by `--routed`/`--unified` flags
(internal/cmd/flags_core.go:38-39)
- `DEBUG` and `DEBUG_COLORS` are actively used by
internal/logger/logger.go but were only documented in the Logging
section, not the comprehensive environment variables table

> [!WARNING]
>
> <details>
> <summary>Firewall rules blocked me from connecting to one or more
addresses (expand for details)</summary>
>
> #### I tried to connect to the following addresses, but was blocked by
firewall rules:
>
> - `example.com`
> - Triggering command: `/tmp/go-build895006319/b279/launcher.test
/tmp/go-build895006319/b279/launcher.test
-test.testlogfile=/tmp/go-build895006319/b279/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -test.v=true 64/src/runtime/cgo
HEAD x_amd64/link get 6778014/b038/ .12/x64/git x_amd64/link /hom��
ache/go/1.25.6/x64/src/runtime/cgo1.25.6 git x_amd64/vet --local
credential.userndocker-cli-plugin-metadata .12/x64/git x_amd64/vet` (dns
block)
> - `invalid-host-that-does-not-exist-12345.com`
> - Triggering command: `/tmp/go-build895006319/b264/config.test
/tmp/go-build895006319/b264/config.test
-test.testlogfile=/tmp/go-build895006319/b264/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -test.v=true 64/src/runtime/cgo
64/src/internal/race/doc.go ache/go/1.25.6/x64/pkg/tool/linu-o unset
--global ndor/bin/which 07.o rev-�� 64/src/runtime/c-p
mon/httpcommon.ggo/ast x_amd64/compile get /maps rgo/bin/git
x_amd64/compile` (dns block)
> - `nonexistent.local`
> - Triggering command: `/tmp/go-build895006319/b279/launcher.test
/tmp/go-build895006319/b279/launcher.test
-test.testlogfile=/tmp/go-build895006319/b279/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -test.v=true 64/src/runtime/cgo
HEAD x_amd64/link get 6778014/b038/ .12/x64/git x_amd64/link /hom��
ache/go/1.25.6/x64/src/runtime/cgo1.25.6 git x_amd64/vet --local
credential.userndocker-cli-plugin-metadata .12/x64/git x_amd64/vet` (dns
block)
> - `slow.example.com`
> - Triggering command: `/tmp/go-build895006319/b279/launcher.test
/tmp/go-build895006319/b279/launcher.test
-test.testlogfile=/tmp/go-build895006319/b279/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -test.v=true 64/src/runtime/cgo
HEAD x_amd64/link get 6778014/b038/ .12/x64/git x_amd64/link /hom��
ache/go/1.25.6/x64/src/runtime/cgo1.25.6 git x_amd64/vet --local
credential.userndocker-cli-plugin-metadata .12/x64/git x_amd64/vet` (dns
block)
> - `this-host-does-not-exist-12345.com`
> - Triggering command: `/tmp/go-build895006319/b288/mcp.test
/tmp/go-build895006319/b288/mcp.test
-test.testlogfile=/tmp/go-build895006319/b288/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -test.v=true
ache/go/1.25.6/xgo1.25.6 US0A/9-_MkWPRpSv-c=4 x_amd64/vet --local
pull.rebase bin/node x_amd64/vet go_.�� 64/src/net a/fips.go x_amd64/vet
-p 6778014/b126/ -lang=go1.25 x_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](https://gh.io/copilot/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](https://github.com/github/gh-aw-mcpg/settings/copilot/coding_agent)
(admins only)
>
> </details>

<!-- START COPILOT ORIGINAL PROMPT -->



<details>

<summary>Original prompt</summary>


----

*This section details on the original issue you should resolve*

<issue_title>📚 Environment Variables Documentation Discrepancies - HOST
and MODE</issue_title>
<issue_description>## Summary

Found 2 environment variables documented in README.md that are not
actually used in production code, and 2 functional environment variables
that are undocumented.

- Workflow Run:
[§21904121957](https://github.com/github/gh-aw-mcpg/actions/runs/21904121957)
- Date: 2026-02-11
- Branch: main

## Important Issues 🟡

### 1. HOST Environment Variable - Documented But Not Used

**Location:** README.md, line 315

**Problem:** The `HOST` variable is documented as "Gateway bind address"
with default `0.0.0.0`, but this variable is NOT used anywhere in the
production Go code.

**Actual Behavior:** 
- Only appears in test file: `test/integration/pipe_launch_test.go`
- The actual bind address is controlled by the `--listen` flag (default:
`127.0.0.1:3000`)
- `run.sh` script sets `HOST` but the Go application ignores it

**Impact:** Users may set `HOST` expecting it to work, but it has no
effect. This could cause confusion when trying to bind to different
addresses.

**Suggested Fix:** 
```markdown
### Optional (Non-Containerized Mode)

When running locally (`run.sh`), these variables are optional (warnings shown if missing):

| Variable | Description | Default |
|----------|-------------|---------|
| `MCP_GATEWAY_PORT` | Gateway listening port | `8000` |
| `MCP_GATEWAY_DOMAIN` | Gateway domain | `localhost` |
| `MCP_GATEWAY_API_KEY` | API authentication key | (disabled) |
- | `HOST` | Gateway bind address | `0.0.0.0` |
+ | **Note:** Use `--listen` flag to set bind address (default: `127.0.0.1:3000`) |
| `MODE` | Gateway mode flag | `--routed` |
```

**Code Reference:** `internal/cmd/flags_core.go` defines `--listen` flag
but no `HOST` environment variable handling

---

### 2. MODE Environment Variable - Documented But Not Used

**Location:** README.md, line 316

**Problem:** The `MODE` variable is documented as "Gateway mode flag"
with default `--routed`, but this variable is NOT used in the production
Go code.

**Actual Behavior:**
- Only appears in test file: `test/integration/pipe_launch_test.go`
- The actual mode is controlled by the `--routed` or `--unified` flags
- `run.sh` script sets `MODE` but the Go application ignores it

**Impact:** Users may set `MODE` expecting to switch between
routed/unified modes, but it has no effect. Must use command-line flags
instead.

**Suggested Fix:**
```markdown
- | `MODE` | Gateway mode flag | `--routed` |
+ | **Note:** Use `--routed` or `--unified` flags to set gateway mode |
```

**Code Reference:** `internal/cmd/flags_core.go` defines `--routed` and
`--unified` flags but no `MODE` environment variable handling

---

### 3. DEBUG Environment Variable - Functional But Undocumented

**Location:** Not documented in README.md Environment Variables section
(lines 292-326)

**Problem:** The `DEBUG` environment variable is fully functional and
controls debug logging, but it's only documented in the "Logging"
section (line 481), not in the comprehensive environment variables
table.

**Actual Behavior:** 
- Enables debug logging with pattern matching (e.g., `DEBUG=*`,
`DEBUG=server:*,launcher:*`)
- Implemented in `internal/logger/logger.go:46`
- Widely used throughout the codebase

**Impact:** Users may miss this important debugging feature when
reviewing the environment variables section.

**Suggested Fix:** Add to environment variables table:
```markdown
| Variable | Description | Default |
|----------|-------------|---------|
+ | `DEBUG` | Enable debug logging with pattern matching (e.g., `*`, `server:*`) | (disabled) |
+ | `DEBUG_COLORS` | Control colored debug output (0 to disable) | Auto-detect |
```

**Code Reference:** `internal/logger/logger.go:26,46`

---

### 4. DEBUG_COLORS Environment Variable - Functional But Undocumented

**Location:** Not documented in README.md Environment Variables section

**Problem:** The `DEBUG_COLORS` environment variable controls colored
output for debug logs but is not documented.

**Actual Behavior:**
- Controls whether debug logs use ANSI color codes
- Auto-disabled when piping output
- Implemented in `internal/logger/logger.go:26`

**Impact:** Users may want to disable colors in specific scenarios but
don't know this option exists.

**Suggested Fix:** Add to environment variables table (see suggestion
above)

**Code Reference:** `internal/logger/logger.go:26`

---

## Minor Issues 🔵

### 5. DOCKER_API_VERSION - Set But Not Read

**Location:** README.md, line 326

**Problem:** Documentation states "Auto-detected (1.43 for arm64, 1.44
for amd64)", but the Go code doesn't actually read this environment
variable. It's set by `run.sh` and `run_containerized.sh` but never
used.

**Actual Behavior:** 
- Shell scripts set it based on architecture
- Go code doesn't reference this variable
- Docker client auto-negotiates API version

**Impact:** Low -...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes #896

Author: lpcox

AGENTS.md

@@ -366,12 +366,13 @@ DEBUG_COLORS=0 DEBUG=* ./awmg --config config.toml
 
 - `GITHUB_PERSONAL_ACCESS_TOKEN` - GitHub auth
 - `DOCKER_API_VERSION` - 1.43 (arm64) or 1.44 (amd64)
-- `PORT`, `HOST`, `MODE` - Server config (via run.sh)
 - `DEBUG` - Enable debug logging (e.g., `DEBUG=*`, `DEBUG=server:*,launcher:*`)
 - `DEBUG_COLORS` - Control colored output (0 to disable, auto-disabled when piping)
 - `MCP_GATEWAY_LOG_DIR` - Log file directory (sets default for `--log-dir` flag, default: `/tmp/gh-aw/mcp-logs`)
 - `MCP_GATEWAY_PAYLOAD_DIR` - Large payload storage directory (sets default for `--payload-dir` flag, default: `/tmp/jq-payloads`)
 
+**Note:** The `PORT`, `HOST`, and `MODE` environment variables are used only by test scripts and are not read by the gateway application. The gateway uses command-line flags instead: `--listen` for bind address and `--routed`/`--unified` for mode selection.
+
 **File Logging:**
 - Operational logs are always written to log files in the configured log directory
 - Default log directory: `/tmp/gh-aw/mcp-logs` (configurable via `--log-dir` flag or `MCP_GATEWAY_LOG_DIR` env var)

README.md

@@ -312,18 +312,20 @@ When running locally (`run.sh`), these variables are optional (warnings shown if
 | `MCP_GATEWAY_PORT` | Gateway listening port | `8000` |
 | `MCP_GATEWAY_DOMAIN` | Gateway domain | `localhost` |
 | `MCP_GATEWAY_API_KEY` | API authentication key | (disabled) |
-| `HOST` | Gateway bind address | `0.0.0.0` |
-| `MODE` | Gateway mode flag | `--routed` |
 | `MCP_GATEWAY_LOG_DIR` | Log file directory (sets default for `--log-dir` flag) | `/tmp/gh-aw/mcp-logs` |
 | `MCP_GATEWAY_PAYLOAD_DIR` | Large payload storage directory (sets default for `--payload-dir` flag) | `/tmp/jq-payloads` |
 | `MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD` | Size threshold in bytes for payload storage (sets default for `--payload-size-threshold` flag) | `10240` |
+| `DEBUG` | Enable debug logging with pattern matching (e.g., `*`, `server:*,launcher:*`) | (disabled) |
+| `DEBUG_COLORS` | Control colored debug output (0 to disable, auto-disabled when piping) | Auto-detect |
+
+**Note:** The `HOST` and `MODE` environment variables are not used by the gateway application. Use the `--listen` flag to set the bind address (default: `127.0.0.1:3000`) and the `--routed` or `--unified` flags to set the gateway mode.
 
 ### Docker Configuration
 
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `DOCKER_HOST` | Docker daemon socket path | `/var/run/docker.sock` |
-| `DOCKER_API_VERSION` | Docker API version | Auto-detected (1.43 for arm64, 1.44 for amd64) |
+| `DOCKER_API_VERSION` | Docker API version (set by helper scripts, Docker client auto-negotiates) | Set by run.sh based on architecture |
 
 ## Containerized Mode