📚 Documentation Reconciliation Report - 2026-05-18

[github-actions]

Summary

Found 6 discrepancies between documentation and implementation during nightly reconciliation check.

• Workflow Run: §26065417123
• Date: 2026-05-18
• Branch: main

---

Important Issues 🟡

Issues that are misleading but have workarounds:

1. AGENTS.md — GH_TOKEN missing from Environment Variables list

Location: AGENTS.md, Environment Variables section
Problem: Lists GITHUB_MCP_SERVER_TOKEN, GITHUB_TOKEN, and GITHUB_PERSONAL_ACCESS_TOKEN as the token priority chain — but omits GH_TOKEN.
Actual Behavior: internal/envutil/github.go defines a 4-entry priority list:

1. GITHUB_MCP_SERVER_TOKEN
2. GITHUB_TOKEN
3. GITHUB_PERSONAL_ACCESS_TOKEN
4. GH_TOKEN ← missing from docs

Impact: AI agents reading AGENTS.md are unaware that GH_TOKEN (set by GitHub CLI) is a valid fallback. They may incorrectly report no token is configured when GH_TOKEN is present.
Suggested Fix: Add GH_TOKEN to the Environment Variables list: `GH_TOKEN` - Lowest-priority GitHub auth fallback (set by GitHub CLI)
Code Reference: internal/envutil/github.go

---

2. AGENTS.md — GITHUB_PERSONAL_ACCESS_TOKEN missing priority annotation

Location: AGENTS.md, Environment Variables section
Problem: The entry for GITHUB_PERSONAL_ACCESS_TOKEN has no priority annotation, while GITHUB_MCP_SERVER_TOKEN says "Highest-priority" and GITHUB_TOKEN says "Second-priority".
Actual Behavior: It is the 3rd-priority token fallback per internal/envutil/github.go.
Impact: The token priority chain appears incomplete/inconsistent, potentially confusing AI agents and users about authentication fallback order.
Suggested Fix: Update to: `GITHUB_PERSONAL_ACCESS_TOKEN` - Third-priority GitHub auth fallback
Code Reference: internal/envutil/github.go

---

Minor Issues 🔵

3. AGENTS.md — entrypoint, entrypointArgs, mounts JSON stdin fields not mentioned

Location: AGENTS.md, JSON stdin config examples section
Problem: The JSON example in AGENTS.md only shows type, container, and env fields.
Actual Behavior: internal/config/config_stdin.go defines additional supported fields:

Entrypoint     string   `json:"entrypoint,omitempty"`
EntrypointArgs []string `json:"entrypointArgs,omitempty"`
Mounts         []string `json:"mounts,omitempty"`

Impact: Agents consulting only AGENTS.md don't know these fields exist. (They are documented in docs/CONFIGURATION.md.)
Suggested Fix: Add a brief note pointing to docs/CONFIGURATION.md for additional optional fields, or list entrypoint, entrypointArgs, mounts in the quick reference.
Code Reference: internal/config/config_stdin.go

---

4. AGENTS.md — connectTimeout per-server JSON stdin field not mentioned

Location: AGENTS.md, JSON stdin config section
Problem: The connectTimeout per-server field (for HTTP backends) is not mentioned.
Actual Behavior: internal/config/config_stdin.go defines ConnectTimeout *int \json:"connectTimeout,omitempty"` **Impact:** Minor; only affects HTTP backend configuration. Documented inconfig.example.tomlanddocs/CONFIGURATION.md. **Suggested Fix:** Add brief mention of connectTimeout(HTTP backends) to the quick reference or ensuredocs/CONFIGURATION.mdis referenced for the full field list. **Code Reference:**internal/config/config_stdin.go`

---

5. CONTRIBUTING.md — make help target not documented

Location: CONTRIBUTING.md, make targets section
Problem: make help is not listed among the documented targets.
Actual Behavior: Makefile defines a help: target that prints all available commands.
Impact: Very minor; users may not discover the built-in help target.
Suggested Fix: Add make help to the documented targets list in CONTRIBUTING.md.
Code Reference: Makefile

---

6. AGENTS.md — keepalive_interval, sequential_launch, guards_mode TOML fields absent from quick reference

Location: AGENTS.md, Config Examples section
Problem: The TOML example in AGENTS.md only shows port, api_key, and a [servers.X] block; it omits keepalive_interval, sequential_launch, and guards_mode.
Actual Behavior: These are valid TOML fields per internal/config/config_core.go and are documented in config.example.toml.
Impact: Minor; these fields are well-documented elsewhere. Only affects AI agent context.
Suggested Fix: Either add a note pointing to config.example.toml for the full TOML reference, or list the most common gateway-level fields.
Code Reference: internal/config/config_core.go

---

Documentation Completeness

Missing Documentation

• GH_TOKEN env var entirely absent from AGENTS.md (but is present in docs/ENVIRONMENT_VARIABLES.md)
• entrypoint, entrypointArgs, mounts JSON stdin fields not in AGENTS.md quick reference

Accurate Sections ✅

• Go version: CONTRIBUTING.md and go.mod both say 1.25.0 ✅
• Binary name: awmg — consistent across CONTRIBUTING.md, Makefile, and docs ✅
• GITHUB_MCP_SERVER_TOKEN (Configure as a Go CLI tool #1) and GITHUB_TOKEN (Lpcox/initial implementation #2) token priority — correct ✅
• make test documented as alias for make test-unit — correct ✅
• make agent-finished pipeline (format → build → lint → tests) — correct ✅
• command field correctly noted as NOT supported in JSON stdin format ✅
• All documented make targets in CONTRIBUTING.md verified to exist in Makefile ✅
• config.example.toml field names match config_core.go struct tags ✅
• docs/CONFIGURATION.md correctly documents entrypoint/entrypointArgs/mounts ✅
• docs/ENVIRONMENT_VARIABLES.md is comprehensive and accurate (includes GH_TOKEN, all ALLOWONLY_* vars, etc.) ✅

Tested Commands

All make targets from CONTRIBUTING.md were verified against Makefile:

• ✅ make build — target exists
• ✅ make test — target exists (alias for test-unit)
• ✅ make test-unit — target exists
• ✅ make test-integration — target exists
• ✅ make test-all — target exists
• ✅ make lint — target exists
• ✅ make coverage — target exists
• ✅ make install — target exists
• ✅ make agent-finished — target exists

Recommendations

Immediate Actions:

1. Add GH_TOKEN entry to AGENTS.md Environment Variables section (4th-priority, GitHub CLI token)
2. Update GITHUB_PERSONAL_ACCESS_TOKEN entry in AGENTS.md to note it's 3rd-priority

Nice to Have:

1. Add entrypoint, entrypointArgs, mounts to the AGENTS.md JSON stdin quick reference (or add a pointer to docs/CONFIGURATION.md)
2. Add make help to CONTRIBUTING.md target list
3. Add brief mention of common gateway TOML fields (keepalive_interval, etc.) or a pointer to config.example.toml in AGENTS.md

Code References

• Token priority chain: internal/envutil/github.go
• JSON stdin config structs: internal/config/config_stdin.go
• TOML config structs: internal/config/config_core.go
• Full environment variables reference: docs/ENVIRONMENT_VARIABLES.md
• Full configuration reference: docs/CONFIGURATION.md

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• proxy.golang.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "proxy.golang.org"

See Network Configuration for more information.

Generated by Nightly Documentation Reconciler · ● 2M · ◷

• expires on May 21, 2026, 11:08 PM UTC