📚 Documentation Reconciliation Report - 2026-03-31

[github-actions]

Summary

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

• Workflow Run: §23779382869
• Date: 2026-03-31
• Branch: main

---

Important Issues 🟡

1. CONTRIBUTING.md Project Structure Missing internal/proxy/ Package

Location: CONTRIBUTING.md, "Project Structure" section (the awmg/ tree) and the "Key Directories" section
Problem: The project structure trees in CONTRIBUTING.md list 16 internal packages, but the actual codebase has 21. Most notably internal/proxy/ is missing — this implements the HTTP forward proxy (awmg proxy command), a major documented feature in README.md with its own reference doc at docs/PROXY_MODE.md.
Actual Behavior: internal/proxy/ exists and is the core of the proxy mode feature. internal/httputil/, internal/oidc/, internal/strutil/, and internal/syncutil/ also exist but are not listed.
Impact: Developers contributing to proxy mode won't find the package in the structure overview. Someone reading CONTRIBUTING.md to understand the codebase gets an incomplete picture of the architecture.
Suggested Fix: Add the missing packages to the project structure tree and Key Directories list:

internal/proxy/   # HTTP forward proxy for DIFC filtering of gh CLI and REST/GraphQL requests
internal/httputil/ # Shared HTTP response helpers
internal/oidc/    # OIDC authentication for HTTP MCP backends
internal/strutil/ # String utility helpers
internal/syncutil/ # Concurrency utility helpers

Code Reference: ls internal/ (confirmed: proxy/, httputil/, oidc/, strutil/, syncutil/ all present)

---

2. CONTRIBUTING.md Architecture Notes Missing Proxy Mode Feature

Location: CONTRIBUTING.md, "Architecture Notes" → "Core Features" section
Problem: The Core Features list does not mention the proxy mode (awmg proxy), even though:

• README.md has a full "Proxy Mode" section describing it
• docs/PROXY_MODE.md exists as a dedicated reference
• make test-container-proxy is a documented test target
• The proxy is a significant feature (~25 REST URL patterns + GraphQL)

Actual Behavior: awmg proxy is a fully implemented subcommand (internal/cmd/proxy.go, internal/proxy/) that runs an HTTP forward proxy applying the same DIFC pipeline.
Impact: Contributors reading CONTRIBUTING.md for an architecture overview won't know the proxy mode exists as a distinct feature.
Suggested Fix: Add to the Core Features list:

- HTTP forward proxy mode (`awmg proxy`) with DIFC filtering for `gh` CLI and REST/GraphQL requests

Code Reference: internal/cmd/proxy.go, internal/proxy/handler.go

---

Accurate Sections ✅

The following documentation was verified accurate against the implementation:

• README.md Docker Quick Start — JSON config structure (mcpServers, type, container, env, gateway.apiKey) all match StdinConfig/StdinServerConfig structs
• README.md Docker run command — env vars (MCP_GATEWAY_PORT, MCP_GATEWAY_DOMAIN, MCP_GATEWAY_API_KEY) verified against run_containerized.sh as required
• README.md Guard Policies — allow-only and write-sink formats match GuardPolicies field in config structs
• README.md API Endpoints — /mcp/{serverID}, /mcp, /health confirmed in internal/server/
• CONTRIBUTING.md Go version — "Go 1.25.0" matches go.mod
• CONTRIBUTING.md Dependencies — all 8 listed packages verified in go.mod
• CONTRIBUTING.md Binary name — awmg matches Makefile BINARY_NAME
• CONTRIBUTING.md Architecture Notes — Variable expansion (\$\{VAR} for JSON stdin, none for TOML) correctly matches validation.go and config_core.go
• CONTRIBUTING.md Architecture Notes — --validate-env flag verified in internal/cmd/flags_core.go
• CONTRIBUTING.md Architecture Notes — HTTP type support, WASM guards, payload handling, health endpoint all confirmed in code

Tested Commands

All make targets from CONTRIBUTING.md verified via make --dry-run:

• ✅ make build — correct (builds awmg binary)
• ✅ make test — correct (alias for test-unit)
• ✅ make test-unit — correct (runs ./internal/...)
• ✅ make test-integration — correct (builds binary then tests ./test/integration/...)
• ✅ make test-all — correct (builds + runs ./...)
• ✅ make lint — correct (go vet + gofmt + golangci-lint)
• ✅ make coverage — correct (unit tests with coverage report)
• ✅ make install — correct (verifies Go, installs golangci-lint, downloads modules)
• ✅ make test-serena — target exists
• ✅ make test-serena-gateway — target exists
• ✅ make test-container-proxy — target exists

Note: make build could not be executed (network-restricted environment prevented Go toolchain download for Go 1.25.0), but the Makefile structure and commands were verified via --dry-run.

Configuration Fields Audit

All documented config fields cross-referenced with struct definitions:

Field	JSON Tag	TOML Tag	Documented
mcpServers	✅	N/A	✅ README + CONTRIBUTING
type	✅	✅	✅
container	✅ (JSON only)	N/A	✅
command	N/A	✅ (TOML only)	✅
args	✅	✅	✅
env	✅	✅	✅
url (http)	✅	✅	✅
entrypoint	✅	N/A	✅
entrypointArgs	✅	N/A	✅
mounts	✅	N/A	✅
guard-policies	✅	guard_policies ✅	✅
gateway.apiKey	✅	api_key ✅	✅
gateway.port	✅	✅	✅

Recommendations

Immediate Actions Suggested:

1. Update CONTRIBUTING.md project structure tree to include the 5 missing internal packages
2. Add proxy mode to CONTRIBUTING.md "Core Features" list

Code References

• CONTRIBUTING.md project structure: lines 224–247
• CONTRIBUTING.md key directories: lines 249–267
• CONTRIBUTING.md architecture notes: lines 608–621
• Missing packages: internal/proxy/, internal/httputil/, internal/oidc/, internal/strutil/, internal/syncutil/

Generated by Nightly Documentation Reconciler · ◷

• expires on Apr 3, 2026, 3:50 AM UTC