📚 Documentation Reconciliation Report - 2026-11-13

Open Beginner friendly
  • Is something wrong?
#16,482 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
76/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
go
Domain
cli, documentation

Research direction

Start with the flag registrations in internal/cmd/proxy.go (around lines 158-185), noting each flag's default and help text, including the registerTracingFlags call for the OTLP flags. Then open the Flags table in docs/PROXY_MODE.md (around lines 172-188) and compare it against those registrations. Done means the table has rows for --force-public-repos, --wasm-cache-dir, and the three --otlp-* flags, with defaults that match the code.

Written by the indexing model from the issue text.

Description

automated documentation maintenance

Summary

Found 1 minor discrepancy between documentation and implementation during the nightly reconciliation check.

Critical Issues 🔴

None found.

Important Issues 🟡

None found.

Minor Issues 🔵

1. awmg proxy flag table in docs/PROXY_MODE.md is missing several flags

Location: docs/PROXY_MODE.md, "Flags" table (around lines 172-188)
Problem: The table does not list these flags, which are registered in internal/cmd/proxy.go:

  • --force-public-repos (line 173; default is taken from MCP_GATEWAY_FORCE_PUBLIC_REPOS, otherwise true)
  • --wasm-cache-dir (line 165; default is a sibling wazero-cache directory next to --log-dir)
  • --otlp-endpoint, --otlp-service-name and --otlp-sample-rate, registered through registerTracingFlags

Actual Behavior: All of these flags are accepted by awmg proxy. --force-public-repos is not mentioned in any Markdown file. --wasm-cache-dir appears only in the gateway flag list in README.md (line 67) and in the MCP_GATEWAY_WASM_CACHE_DIR entry of docs/ENVIRONMENT_VARIABLES.md.
Impact: Proxy users cannot discover these flags from the proxy documentation. This is especially relevant for --force-public-repos, which changes the effective guard policy.
Suggested Fix: Add rows for the flags above to the docs/PROXY_MODE.md Flags table, with defaults and descriptions taken from the flag help text in internal/cmd/proxy.go.
Code Reference: internal/cmd/proxy.go:158-185

Documentation Completeness

Missing Documentation
  • The proxy flags listed above.
Outdated Documentation
  • None found.
Accurate Sections ✅
  • Go version: go.mod, Makefile (GO_VERSION), CONTRIBUTING.md, README.md and AGENTS.md all say 1.26.10.
  • Quick Start JSON stdin example: the gateway section is required with port and domain, matching internal/config/schema/mcp-gateway-config.schema.json (required port and domain, with agentId or agentIds).
  • Server fields (type, container, entrypoint, entrypointArgs, args, mounts, env, connectTimeout, toolTimeout) all exist in StdinServerConfig. No command field is documented for JSON stdin.
  • Gateway fields in the README.md table match StdinGatewayConfig in internal/config/config_stdin.go.
  • Every non-test os.Getenv / os.LookupEnv variable in internal/ and main.go is documented. The only undocumented names in the scan were test fixtures and GITHUB_ACTIONS, which I did not investigate further.
  • Every awmg flag registered in internal/cmd is documented somewhere in the docs, apart from the proxy flags above. The scan also flagged --verbose, a Cobra counter flag shown as -v/-vv in CONTRIBUTING.md.
  • All relative links in README.md and CONTRIBUTING.md that point into docs/, internal/, scripts/ and test/ resolve to existing files.

Tested Commands

  • ✅ Every make target named in CONTRIBUTING.md and AGENTS.md exists in the Makefile: build, test, test-unit, test-integration, test-all, test-ci, lint, coverage, install, format, clean, agent-finished.
  • ⚠️ make build could not be verified. The sandbox firewall blocked proxy.golang.org (TLS certificate error), so module downloads failed and the awmg binary was not produced. As a result ./awmg --help was not run; I checked flags statically from internal/cmd/*.go instead.
  • ⚠️ The external spec link (https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md) and the token page link were not checked, because network access is restricted.

Recommendations

Immediate Actions Required:

None.

Nice to Have:
  1. Add the missing proxy flags to docs/PROXY_MODE.md.

Code References

  • Proxy flags: internal/cmd/proxy.go
  • Configuration structs: internal/config/config_core.go, internal/config/config_stdin.go
  • Validation logic: internal/config/validation_schema.go (and internal/config/schema/mcp-gateway-config.schema.json)

Generated by Nightly Documentation Reconciler · copilot · routed: sonnet55 high · ~35 AIC · ⊞ 2.1K · ◷

  • expires on Nov 16, 2026, 10:45 PM UTC
Dominant language
Go
Stars
188
Forks
60
Avg merge
6h 45m
Merged PRs (30d)
198

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from github/gh-aw-mcpg

All issues in github/gh-aw-mcpg

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.