Reconcile README/CONTRIBUTING with implemented CLI, env, and config behavior

[Copilot]

Nightly docs reconciliation found drift between documentation and implementation across CLI flags, environment variables, gateway schema requirements, and Make target behavior. This PR tightens README/CONTRIBUTING to match current runtime/config semantics and reduce user misconfiguration risk.

• README: quick-start + schema requirements

  • Updated JSON quick-start to include schema-required gateway.port and gateway.domain.
  • Added explicit note that these fields are required in JSON stdin config.

• README: CLI flags coverage

  • Replaced the materially incomplete flag list with grouped coverage of implemented flags:
    • config/runtime (--config, --config-stdin, --listen, --routed, --unified, --validate-env, --sequential-launch, etc.)
    • logging/payload/shutdown
    • guards/security (--guards-mode, --guard-policy-json, --allowonly-*, --tls-*, --hmac-secret)
    • tracing (--otlp-*)
  • Kept ./awmg --help as the authoritative full reference.

• README: environment variable completeness

  • Added missing operational env vars called out by reconciliation, including:
    • MCP_GATEWAY_PORT
    • GITHUB_API_URL, GITHUB_SERVER_URL
    • MCP_GATEWAY_GUARDS_MODE, MCP_GATEWAY_WASM_GUARDS_DIR
    • MCP_GATEWAY_ALLOWONLY_SCOPE_PUBLIC/OWNER/REPO/MIN_INTEGRITY
    • OTEL_EXPORTER_OTLP_HEADERS, GH_AW_OTLP_ENDPOINTS
  • Clarified deprecated alias precedence: MCP_GATEWAY_API_KEY is lower precedence than MCP_GATEWAY_AGENT_ID.

• README: config/table signposting

  • Added explicit pointer to docs/CONFIGURATION.md for TOML-only server fields (working_directory, rate_limit_threshold, rate_limit_cooldown) and full field coverage.

• CONTRIBUTING: target behavior + naming consistency

  • Corrected make test-all wording to reflect incremental rebuild behavior (not unconditional rebuild).
  • Added missing maintenance targets (format, clean, agent-finished, help) and release invocation note.
  • Standardized informal “MCPG” references to “MCP Gateway” in touched sections.

{
  "gateway": {
    "port": 8000,
    "domain": "${MCP_GATEWAY_DOMAIN}",
    "agentId": "${MCP_GATEWAY_AGENT_ID}"
  }
}

• Fixes 📚 Documentation Reconciliation Report - 2026-07-20 #9744

[Copilot]

Pull request overview

Aligns contributor and user documentation with current CLI, configuration, environment-variable, and maintenance workflows.

Changes:

• Expands README configuration, CLI, and environment guidance.
• Documents additional Make targets and standardizes project naming.

Show a summary per file

File	Description
README.md	Updates runtime and configuration reference material.
CONTRIBUTING.md	Revises testing, maintenance, release, and naming guidance.

Review details

Tip

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

• Files reviewed: 2/2 changed files
• Comments generated: 1
• Review effort level: Medium

[github-actions]

🔒 mcpg Read-Only Stress — gVisor

Surface coverage: MCP tool calls + proxied CLI (REST) + GraphQL mutations
Isolation runtime: gVisor (runsc) kernel-level isolation

Part	Surface	Op	Result	Expected	Status
A	MCP	reads (list_issues/list_prs/get_file/list_commits)	data returned	ALLOWED	✅
B	MCP	writes (reaction/star/issue/comment/branch/file/PR)	Error [-32602]: unknown tool (gateway)	BLOCKED	✅
C	CLI	reads (list_issues/get_file_contents)	data returned	ALLOWED	✅
D	CLI	REST writes (reaction/star/issue/comment/file)	auth error — no token	BLOCKED	✅
E	CLI	GraphQL mutations (addReaction/addStar/createIssue)	auth error — no token	BLOCKED	✅

B detail: All 7 MCP write tools absent from gateway allowlist — Error [-32602]: unknown tool for each.

D/E detail: gh carries no token; REST and GraphQL writes fail at auth.

Overall: PASS

References: §29788279585

🔒 mcpg read-only stress (gVisor runtime) by Read-Only Stress: gVisor runtime

[github-actions]

🔒 mcpg Read-Only Stress — default AWF

Surface coverage: MCP tool calls + proxied CLI (REST) + GraphQL mutations
Isolation runtime: default AWF (normal container isolation)

Part	Surface	Op	Result	Expected	Status
A	MCP	reads (issues/PRs/file/commits)	data returned	ALLOWED	✅
B	MCP	writes (reaction/star/issue/comment/branch/file/PR)	unknown tool (gateway allowlist)	BLOCKED	✅
C	CLI	reads (issues, file contents)	data returned	ALLOWED	✅
D	CLI	REST writes (reaction/star/issue/comment/file)	unauthenticated — 401 refused	BLOCKED	✅
E	CLI	GraphQL mutations (addReaction/addStar/createIssue)	unauthenticated — 401 refused	BLOCKED	✅

Overall: PASS

Note on Part B: All write tool calls returned Error [-32602]: unknown tool "<name>". This is gateway-enforced: the gateway's tool allowlist does not expose write tools to this agent. The backend GitHub MCP server does support these tools, but they are filtered out at the gateway boundary before the call reaches the backend.

Note on Parts D & E: gh CLI is unauthenticated in this sandbox (GH_TOKEN not set), so all REST and GraphQL write attempts are rejected with a 401/auth error. The effective enforcement boundary is: mcpg (MCP tool allowlist) + token scope (REST/GraphQL).

References: §29788279677

🔒 mcpg read-only stress (default AWF runtime) by Read-Only Stress: default runtime

[github-actions]

🔒 mcpg Read-Only Stress — docker-sbx

Surface coverage: MCP tool calls + proxied CLI (REST) + GraphQL mutations
Isolation runtime: docker-sbx (KVM-isolated microVM)

Part	Surface	Op	Result	Expected	Status
A	MCP	reads (issues/PRs/file/commits)	data returned	ALLOWED	✅
B	MCP	writes (reaction/star/issue/comment/branch/file/PR)	Error [-32602]: unknown tool (gateway-enforced)	BLOCKED	✅
C	CLI	reads (list_issues, get_file_contents)	data returned	ALLOWED	✅
D	CLI	REST writes (reaction/star/issue/comment/file)	gh: GH_TOKEN not set (unauthenticated)	BLOCKED	✅
E	CLI	GraphQL mutations (addReaction/addStar/createIssue)	gh: GH_TOKEN not set (unauthenticated)	BLOCKED	✅

Overall: PASS

Notes:

• Part B: Gateway returns MCP error -32602 unknown tool for all write tools — write tools are absent from the gateway's tool list, providing strong enforcement.
• Parts D/E: gh CLI is not authenticated (no GH_TOKEN), so all REST and GraphQL write attempts are rejected before reaching the API.
• Run: §29788279649

🔒 mcpg read-only stress (docker-sbx runtime) by Read-Only Stress: docker-sbx runtime