Reconcile docs with MCP_GATEWAY_PORT runtime behavior and Rust guard test guidance (#6039)

Nightly docs reconciliation found mismatches between documented env/test
behavior and implementation, centered on `MCP_GATEWAY_PORT`
semantics/defaults and incomplete contributor guidance. This PR aligns
docs and one config comment with current runtime behavior.

- **Environment variable semantics (`docs/ENVIRONMENT_VARIABLES.md`)**
- Corrects `MCP_GATEWAY_PORT` wording: it is used by `run.sh` /
`run_containerized.sh` to construct `--listen`, and by `awmg` only for
`--validate-env` checks.
- Removes conflicting value by aligning the production-table value with
the script default (`8000`).
- Expands the note to clearly separate script-read vars
(`HOST`/`PORT`/`MODE`) from binary behavior.

- **Contributor workflow clarity (`CONTRIBUTING.md`)**
- Adds a dedicated **Rust Guard Tests** section for `make test-rust` and
its `cargo` requirement.
- Tightens `make agent-finished` wording to reflect what it actually
runs (`go test ./...` + Rust guard tests).

- **Agent quick reference alignment (`AGENTS.md`)**
- Updates `Agent-Finished` description to explicitly include unit,
integration, and Rust guard tests.

- **JSON stdin config intent (`internal/config/config_stdin.go`)**
- Adds a `StdinServerConfig` comment clarifying intentional omission of
`command` in JSON stdin format (stdio uses `container`).

```md
`MCP_GATEWAY_PORT` is read by the binary for `--validate-env` port-mapping checks only; it does **not** auto-configure the listen address.
```

Author: lpcox

AGENTS.md

@@ -15,7 +15,7 @@ Quick reference for AI agents working with MCP Gateway (Go-based MCP proxy serve
 **Coverage**: `make coverage` (unit tests with coverage report)  
 **Format**: `make format` (auto-format code with gofmt)  
 **Clean**: `make clean` (remove build artifacts)  
-**Agent-Finished**: `make agent-finished` (run format, build, lint, and all tests - ALWAYS run before completion)  
+**Agent-Finished**: `make agent-finished` (run format, build, lint, and all tests (unit, integration, Rust guard) - ALWAYS run before completion)  
 **Run**: `./awmg --config config.toml`  
 **Run sequentially**: `./awmg --config config.toml --sequential-launch`  
 **Run with Custom Log Directory**: `./awmg --config config.toml --log-dir /path/to/logs`  

CONTRIBUTING.md

@@ -97,6 +97,13 @@ Run both unit and integration tests (always rebuilds the binary first):
 make test-all
 ```
 
+#### Rust Guard Tests
+Run Rust guard unit tests (requires `cargo`):
+```bash
+make test-rust
+```
+Install the Rust toolchain from [rustup.rs](https://rustup.rs/) if not already present.
+
 #### Serena MCP Tests (Optional)
 Run Serena MCP Server tests (requires Docker and network access):
 ```bash
@@ -589,7 +596,7 @@ Required environment variables:
 3. **Add tests** for new functionality
 4. **Run linters and tests** before submitting:
    ```bash
-   make agent-finished  # format + build + lint + all tests (unit, integration, rust-guard)
+   make agent-finished  # format + build + lint + go test ./... + Rust guard tests
    ```
 5. **Update documentation** if you change behavior or add features
 6. **Keep changes minimal** - smaller PRs are easier to review

docs/ENVIRONMENT_VARIABLES.md

@@ -8,7 +8,7 @@ When running in a container (`run_containerized.sh`), these variables **must** b
 
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `MCP_GATEWAY_PORT` | The port the gateway listens on (used for `--listen` address) | `8080` |
+| `MCP_GATEWAY_PORT` | Port used by `run.sh`/`run_containerized.sh` to build the `--listen` address; also read by `awmg --validate-env` for port-mapping checks | `8000` |
 | `MCP_GATEWAY_DOMAIN` | The domain name for the gateway | `localhost` |
 | `MCP_GATEWAY_API_KEY` | API key checked by `run_containerized.sh` as a deployment gate; must be referenced in your JSON config via `"${MCP_GATEWAY_API_KEY}"` to enable authentication | `your-secret-key` |
 
@@ -18,7 +18,7 @@ When running locally (`run.sh`), these variables are optional (warnings shown if
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `MCP_GATEWAY_PORT` | Gateway listening port | `8000` |
+| `MCP_GATEWAY_PORT` | Port used by `run.sh` to build the `--listen` address; also read by `awmg --validate-env` for port-mapping checks | `8000` |
 | `MCP_GATEWAY_DOMAIN` | Gateway domain | `localhost` |
 | `MCP_GATEWAY_API_KEY` | Informational only — not read directly by the binary; must be referenced in your config via `"${MCP_GATEWAY_API_KEY}"` to enable authentication | (disabled) |
 | `MCP_GATEWAY_LOG_DIR` | Log file directory (sets default for `--log-dir` flag) | `/tmp/gh-aw/mcp-logs` |
@@ -39,7 +39,7 @@ When running locally (`run.sh`), these variables are optional (warnings shown if
 | `DEBUG_COLORS` | Control colored debug output (0 to disable, auto-disabled when piping) | Auto-detect |
 | `RUNNING_IN_CONTAINER` | Manual override; set to `"true"` to force container detection when `/.dockerenv` and cgroup detection are unavailable | (unset) |
 
-**Note:** `PORT`, `HOST`, and `MODE` are not read by the `awmg` binary directly. However, `run.sh` uses `HOST` (default: `0.0.0.0`), `MODE` (default: `--routed`), and falls back to `PORT` (when `MCP_GATEWAY_PORT` is unset) to set the bind address and routing mode. Use the `--listen` and `--routed`/`--unified` flags when running `awmg` directly.
+**Note:** `PORT`, `HOST`, and `MODE` are not read by the `awmg` binary directly. `MCP_GATEWAY_PORT` is read by the binary for `--validate-env` port-mapping checks only; it does **not** auto-configure the listen address. `run.sh` uses `HOST` (default: `0.0.0.0`), `MODE` (default: `--routed`), and falls back to `PORT` (when `MCP_GATEWAY_PORT` is unset) to set the bind address and routing mode. Use the `--listen` and `--routed`/`--unified` flags when running `awmg` directly.
 
 ## Test / Development Overrides
 

internal/config/config_stdin.go

@@ -80,6 +80,8 @@ type StdinGuardConfig struct {
 }
 
 // StdinServerConfig represents a single server configuration in stdin JSON format.
+// Note: unlike TOML ServerConfig, this struct intentionally has no Command field;
+// stdio servers must use Container instead.
 type StdinServerConfig struct {
 	// Type is the server type: "stdio", "local", or "http"
 	Type string `json:"type"`