docs: fix three README inaccuracies found by nightly reconciliation (#1514)

Three discrepancies between README documentation and actual
implementation, surfaced by the nightly documentation reconciler.

## Changes

- **Guard-policies JSON example**: remove invalid `"owner"` field, fix
bare repo names → `owner/repo` pattern, add missing `"min-integrity"`
field

  ```json
  // Before (incorrect)
  "guard-policies": {
    "github": {
      "owner": "github",
      "repos": ["gh-aw-mcpg", "gh-aw"]
    }
  }

  // After (correct)
  "guard-policies": {
    "github": {
      "repos": ["github/gh-aw-mcpg", "github/gh-aw"],
      "min-integrity": "reader"
    }
  }
  ```

- **`RUNNING_IN_CONTAINER` env var**: add missing row to the Optional
env vars table — this variable is read by `internal/tty/container.go` to
detect containerised environments but was absent from the docs

- **Script-only variables note**: extend the existing note to include
`PORT` alongside `HOST` and `MODE`; `PORT` is only consumed by `run.sh`
as a fallback for `MCP_GATEWAY_PORT`, not by the Go binary

> [!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-build1260020530/b298/launcher.test
/tmp/go-build1260020530/b298/launcher.test
-test.testlogfile=/tmp/go-build1260020530/b298/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -test.v=true go --local
x_amd64/compile user.name /math` (dns block)
> - `invalid-host-that-does-not-exist-12345.com`
> - Triggering command: `/tmp/go-build1260020530/b280/config.test
/tmp/go-build1260020530/b280/config.test
-test.testlogfile=/tmp/go-build1260020530/b280/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -test.v=true 64/src/runtime/cgo
transform/transform.go ache/go/1.25.7/x64/pkg/tool/linu-lang=go1.25
credential.helpe/opt/hostedtoolcache/go/1.25.7/x64/pkg/tool/linux_amd64/vet`
(dns block)
> - `nonexistent.local`
> - Triggering command: `/tmp/go-build1260020530/b298/launcher.test
/tmp/go-build1260020530/b298/launcher.test
-test.testlogfile=/tmp/go-build1260020530/b298/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -test.v=true go --local
x_amd64/compile user.name /math` (dns block)
> - `slow.example.com`
> - Triggering command: `/tmp/go-build1260020530/b298/launcher.test
/tmp/go-build1260020530/b298/launcher.test
-test.testlogfile=/tmp/go-build1260020530/b298/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -test.v=true go --local
x_amd64/compile user.name /math` (dns block)
> - `this-host-does-not-exist-12345.com`
> - Triggering command: `/tmp/go-build1260020530/b307/mcp.test
/tmp/go-build1260020530/b307/mcp.test
-test.testlogfile=/tmp/go-build1260020530/b307/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -test.v=true 1571780/b029/_pkg_.a
ternal/fips140hash/hash.go x_amd64/asm user.email` (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>📚 Documentation Reconciliation Report -
2026-02-28</issue_title>
<issue_description>## Summary

Found **3 discrepancies** between documentation and implementation
during nightly reconciliation check.

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

---

## Critical Issues 🔴

### 1. Guard-Policies JSON Example Uses Incorrect Schema

**Location:** `README.md`, line 134–140 (JSON stdin format example)

**Problem:** The JSON configuration example shows an `"owner"` field
inside `guard-policies` that does not exist in the implementation.
Additionally, the `repos` array contains bare repo names
(`"gh-aw-mcpg"`, `"gh-aw"`) instead of the required `owner/repo`
patterns. The example also omits the `min-integrity` field.

**Current (incorrect) example:**
```json
"guard-policies": {
  "github": {
    "owner": "github",
    "repos": ["gh-aw-mcpg", "gh-aw"]
  }
}
```

**Correct format (consistent with implementation and tests):**
```json
"guard-policies": {
  "github": {
    "repos": ["github/gh-aw-mcpg", "github/gh-aw"],
    "min-integrity": "reader"
  }
}
```

**Impact:** Any user following this example will produce an unrecognised
`owner` field and bare repo names that don't match the `owner/repo`
pattern required by the guard policy evaluator. This would silently
misconfigure access control.

**Suggested Fix:** Replace the `guard-policies` block in the JSON
example with the correct structure: remove `"owner"`, prefix all repo
names with `owner/`, and add `"min-integrity"`.

**Code References:**
- `internal/config/config_guardpolicies_test.go:14–35` — tests confirm
no `owner` field; repos use `"all"`, `"public"`, or `"owner/repo"`
patterns
- `internal/config/config_stdin.go:83` — `GuardPolicies` defined as
`map[string]interface{}` with no `owner` key
- `README.md:191–215` — the _documentation_ section correctly describes
the format (no `owner`, full `owner/repo` patterns) — only the _example_
is wrong

---

## Minor Issues 🔵

### 2. `RUNNING_IN_CONTAINER` Environment Variable Not Documented

**Location:** `README.md` (Environment Variables section, ~line 351)

**Problem:** The `RUNNING_IN_CONTAINER` environment variable is read by
the gateway application (`internal/tty/container.go:30`) to detect
containerised environments and emit security warnings, but it is not
listed in the README environment variables table.

**Actual Behaviour:** When `RUNNING_IN_CONTAINER=true` is set, the
gateway detects it is running inside a container and adjusts its
behaviour accordingly.

**Suggested Fix:** Add a row to the Optional/Containerised variables
table:

| `RUNNING_IN_CONTAINER` | Signals the gateway is running inside a
container (set automatically by container runtimes) | `true` |

**Code Reference:** `internal/tty/container.go:30`

---

### 3. Note About Script-Only Variables Is Missing `PORT`

**Location:** `README.md`, line 381

**Problem:** The note reads: *"The `HOST` and `MODE` environment
variables are not used by the gateway application."* — but the
unqualified `PORT` variable (without the `MCP_GATEWAY_` prefix) is also
a script-only variable, not read by the Go binary directly.

**Actual Behaviour:** `run.sh` uses `PORT` as a fallback for
`MCP_GATEWAY_PORT` (line 128:
`PORT="\$\{MCP_GATEWAY_PORT:-\$\{PORT:-8000}}"`), but the Go application
only reads `MCP_GATEWAY_PORT`.

**Suggested Fix:** Update the note to include `PORT`:

> **Note:** The `PORT`, `HOST`, and `MODE` environment variables are not
used by the gateway application. Use the `--listen` flag to set the bind
address…

**Code References:** `run.sh:128`, `internal/config/config_env.go:13`
(only `MCP_GATEWAY_PORT` read)

---

## Accurate Sections ✅

- TOML configuration format — verified accurate
- JSON stdin server fields (`type`, `container`, `entrypoint`,
`entrypointArgs`, `args`, `mounts`, `env`, `url`, `headers`) — verified
against `internal/config/config_stdin.go`
- Gateway JSON fields (`port`, `apiKey`, `domain`, `startupTimeout`,
`toolTimeout`, `payloadDir`) — verified camelCase matches
`StdinGatewayConfig` JSON tags
- Payload features (`payloadSizeThreshold`, `payloadPathPrefix`) —
verified accurate
- Environment variables table — verified `MCP_GATEWAY_LOG_DIR`,
`MCP_GATEWAY_PAYLOAD_DIR`, `MCP_GATEWAY_PAYLOAD_PATH_PREFIX`,
`MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD`, `DEBUG`, `DEBUG_COLORS` all
correctly documented
- CONTRIBUTING.md make targets — all targets (`build`, `test`,
`test-unit`, `test-integration`, `test-all`, `lint`, `coverage`,
`format`, `clean`, `install`, `release`) verified against Makefile
- Go version — CONTRIBUTING.md states Go 1.25.0, matches `go.mod`
- Binary name — `awmg` correctly documented

## Tested Commands

- ✅ `make --dry-run build` — dry-run succeeds
- ✅ `make --dry-run test-unit` — dry-run succeeds
- ✅ `make --dry-run test-integration` — dry-run succeeds
- ✅ `make...

</details>


> **Custom agent used: agentic-workflows**
> GitHub Agentic Workflows (gh-aw) - Create, debug, and upgrade
AI-powered workflows with intelligent prompt routing



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

- Fixes #1512

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

🔒 GitHub Advanced Security automatically protects Copilot coding agent
pull requests. You can protect all pull requests by enabling Advanced
Security for your repositories. [Learn more about Advanced
Security.](https://gh.io/cca-advanced-security)

Author: lpcox

README.md

@@ -133,8 +133,8 @@ For the complete JSON configuration specification with all validation rules, see
       },
       "guard-policies": {
         "github": {
-          "owner": "github",
-          "repos": ["gh-aw-mcpg", "gh-aw"]
+          "repos": ["github/gh-aw-mcpg", "github/gh-aw"],
+          "min-integrity": "reader"
         }
       }
     }
@@ -377,8 +377,9 @@ When running locally (`run.sh`), these variables are optional (warnings shown if
 | `MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD` | Size threshold in bytes for payload storage (sets default for `--payload-size-threshold` flag) | `524288` |
 | `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 |
+| `RUNNING_IN_CONTAINER` | Signals the gateway is running inside a container (set automatically by container runtimes) | `true` |
 
-**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:** The `PORT`, `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.
 
 ### Containerized Deployment Variables