docs: fix three README inaccuracies found by nightly reconciliation

[Copilot]

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

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

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

"guard-policies": {
  "github": {
    "owner": "github",
    "repos": ["gh-aw-mcpg", "gh-aw"]
  }
}

Correct format (consistent with implementation and tests):

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

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

• Fixes 📚 Documentation Reconciliation Report - 2026-02-28 #1512

---

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

[Copilot]

Pull request overview

This PR corrects three inaccuracies in README.md that were identified by the nightly documentation reconciliation check. The changes bring the documentation in sync with the actual implementation.

Changes:

• Guard-policies JSON example: Removes the invalid "owner" field, fixes bare repo names to use owner/repo patterns, and adds the missing "min-integrity" field to match the implementation.
• RUNNING_IN_CONTAINER env var: Adds a missing row to the environment variables table for this variable read by internal/tty/container.go.
• Script-only variables note: Adds PORT to the note, alongside HOST and MODE, as it is only consumed by run.sh as a fallback and not by the Go binary directly.

Comments suppressed due to low confidence (1)

README.md:380

• The "Default" column entry for RUNNING_IN_CONTAINER shows true, which is inaccurate. true is not the default value of the variable — when the variable is unset (its actual default state), IsRunningInContainer() falls back to checking /.dockerenv and /proc/1/cgroup. The value true is a trigger value that a user sets to force container detection, similar to how the "Example" column is used in the "Required for Production" table above. This column header should show something like (not set) for the default, or the column header should be changed to "Trigger Value".

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

---

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

[Copilot]

The RUNNING_IN_CONTAINER row has been placed in the "Optional (Non-Containerized Mode)" section, whose heading explicitly says "When running locally (run.sh), these variables are optional." However, RUNNING_IN_CONTAINER is a container-detection variable read by the Go binary (internal/tty/container.go:30) that is specifically relevant to containerized environments, and it is not related to run.sh or non-containerized operation. It would be a better fit in the "Containerized Deployment Variables" section (alongside MCP_GATEWAY_HOST and MCP_GATEWAY_MODE), where the context of containerized execution is already established.

This issue also appears on line 380 of the same file.