Fix environment variable documentation discrepancies

[Claude]

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

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-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 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>📚 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
• 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:

### 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:

- | `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:

| 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 -...

• Fixes 📚 Environment Variables Documentation Discrepancies - HOST and MODE #896

[Copilot]

Pull request overview

Updates documentation to better reflect which environment variables are actually honored by the gateway vs helper scripts, and to surface missing debug-related env vars.

Changes:

• README: removes HOST/MODE from the “Optional (Non-Containerized Mode)” env var table; adds DEBUG/DEBUG_COLORS; adds guidance note about using CLI flags.
• README: revises DOCKER_API_VERSION description/default.
• AGENTS: removes PORT/HOST/MODE from env var list; adds note claiming these are test-only and that the gateway uses CLI flags.

Reviewed changes

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

File	Description
README.md	Updates environment variable tables/notes and clarifies Docker-related env var behavior.
AGENTS.md	Adjusts documented env vars and adds a note about script-only variables vs gateway CLI flags.

---

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

[Copilot]

The note states HOST and MODE are not used and instructs users to use --listen/--routed/--unified. While the Go binary doesn’t read HOST/MODE, run.sh does read HOST, PORT, and MODE and converts them into those flags (FLAGS="$MODE --listen ${HOST}:${PORT}"). In this “running locally (run.sh)” section, the current wording is misleading because run.sh doesn’t forward arbitrary CLI args, so users can’t actually supply --listen/--routed/--unified unless they bypass run.sh and run ./awmg directly. Consider documenting HOST/MODE as run.sh-only inputs (or clarify the note to distinguish run.sh vs awmg).

Suggested change

**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.

**Note:** When using `run.sh`, the script reads the `HOST`, `PORT`, and `MODE` environment variables and translates them into the equivalent `--listen` and `--routed`/`--unified` flags for the gateway binary. The gateway application itself does not read `HOST` or `MODE` directly. If you invoke `./awmg` manually (without `run.sh`), use the `--listen` flag to set the bind address (default: `127.0.0.1:3000`) and the `--routed` or `--unified` flags to select the gateway mode.

[Copilot]

The updated DOCKER_API_VERSION default/description doesn’t match what the helper scripts actually do: run.sh/run_containerized.sh first try to set DOCKER_API_VERSION from docker version --format '{{.Server.APIVersion}}' and only fall back to an architecture-based value. The table currently says “Set by run.sh based on architecture”, which omits the primary (server API) behavior and may be inaccurate if the server API differs. Please align the wording/default with the scripts’ logic (server API version when available; architecture fallback).

Suggested change

	| `DOCKER_API_VERSION` | Docker API version (set by helper scripts, Docker client auto-negotiates) | Set by run.sh based on architecture |
	| `DOCKER_API_VERSION` | Docker API version (set by helper scripts: uses `docker version --format '{{.Server.APIVersion}}'` when available, with an architecture-based fallback) | Server API version when available; architecture-based fallback |

[Copilot]

This note claims PORT, HOST, and MODE are used only by test scripts, but run.sh also reads all three and uses them to construct the ./awmg invocation (--listen ${HOST}:${PORT} and $MODE). The note should be revised to reflect that these vars are script-level inputs (used by run.sh and some test helpers), not strictly test-only.

Suggested change

**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.

**Note:** The `PORT`, `HOST`, and `MODE` environment variables are consumed by the `run.sh` wrapper and some test helper scripts to construct the `./awmg` invocation (for example, `--listen ${HOST}:${PORT}` and the selected mode), but they are not read directly by the gateway binary. The gateway itself uses command-line flags instead: `--listen` for bind address and `--routed`/`--unified` for mode selection.