📚 Documentation Reconciliation Report - 2026-06-25

[github-actions]

Summary

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

• Workflow Run: §28205999391
• Date: 2026-06-25
• Branch: main

---

Minor Issues 🔵

Small inconsistencies that would confuse developers but don't break user workflows.

---

1. Wrong jsonschema Major Version in CONTRIBUTING.md Dependencies

Location: CONTRIBUTING.md, line 463, "Dependencies" section
Problem: The listed dependency version is incorrect — it says v5 but the codebase uses v6:

- `github.com/santhosh-tekuri/jsonschema/v5` - JSON schema validation

Actual Behavior: go.mod declares and the code imports github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 (e.g. internal/config/validation.go:14 and internal/config/validation_schema.go:18–19).
Impact: A developer following the docs to add a direct import of the JSON schema library would import the wrong (older) major version.
Suggested Fix: Change v5 → v6 in the dependency list entry.
Code Reference: go.mod:14, internal/config/validation.go:14, internal/config/validation_schema.go:18

---

2. AGENTS.md Project Structure Missing Three Internal Packages

Location: AGENTS.md, "Project Structure" section, lines 26–51
Problem: Three packages that exist under internal/ are not listed:

• internal/mcpresult/ — MCP result text content helpers
• internal/sanitize/ — Sensitive data redaction utilities for logging
• internal/urlutil/ — URL hostname extraction utilities for domain audit logging

CONTRIBUTING.md correctly lists all three of these packages; AGENTS.md does not.
Impact: AI agents working from AGENTS.md would not know these packages exist, potentially leading to duplication or overlooked helpers.
Suggested Fix: Add the three missing entries to the Project Structure list in AGENTS.md, matching the descriptions already present in CONTRIBUTING.md.
Code Reference: internal/mcpresult/, internal/sanitize/, internal/urlutil/ directories (all present on main)

---

Documentation Completeness ✅

No further structural completeness issues found. The following were audited and confirmed accurate:

• README.md Quick Start (JSON config structure, Docker run command, required flags, port behaviour)
• README.md Authentication token priority order (GITHUB_MCP_SERVER_TOKEN → GITHUB_TOKEN → GITHUB_PERSONAL_ACCESS_TOKEN → GH_TOKEN)
• README.md Tracing environment variables (OTEL_EXPORTER_OTLP_ENDPOINT, GH_AW_OTLP_ENDPOINTS, etc.)
• README.md Guard policy configuration (allow-only, write-sink, min-integrity levels, blocked-users, approval-labels, trusted-users, tool-call-limits)
• README.md Gateway configuration table (agent_id/agentId, api_key/apiKey deprecation, port, payload_dir, trustedBots, customSchemas)
• README.md API endpoints (/mcp/{serverID}, /mcp, /health, /close, /reflect)
• README.md Architecture and routing modes — confirmed routed and unified modes exist in internal/server/
• README.md Variable expansion (${VAR_NAME}) — confirmed in internal/config/expand.go
• README.md External doc links all resolve to local files under docs/ that exist (CONFIGURATION.md, ENVIRONMENT_VARIABLES.md, PROXY_MODE.md, etc.)
• CONTRIBUTING.md Go version requirement (1.25.0) — matches go.mod:1
• CONTRIBUTING.md Binary name (awmg) — matches Makefile:BINARY_NAME=awmg
• CONTRIBUTING.md Default listen ports (3000 for awmg direct, 8000 for run.sh) — matches internal/cmd/root.go:DefaultListenPort="3000" and run.sh:PORT="${MCP_GATEWAY_PORT:-${PORT:-8000}}"
• CONTRIBUTING.md Project structure directory listing — all packages listed exist under internal/
• CONTRIBUTING.md All make targets mentioned (build, test, test-unit, test-integration, test-all, lint, coverage, install, format, clean, test-race, test-rust, test-ci, test-serena, test-serena-gateway, test-container-proxy) — all present in Makefile
• CONTRIBUTING.md JSON stdin format does not support command field for stdio servers — confirmed: StdinServerConfig has no Command field (internal/config/config_stdin.go:108–174)
• config.example.toml fields — all verified against internal/config/config_core.go struct tags

Tested Commands

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

• ✅ make build — target present, produces awmg binary
• ✅ make test / make test-unit — aliased, runs go test -v ./internal/...
• ✅ make test-integration — auto-builds binary if missing, then runs ./test/integration/...
• ✅ make test-all — depends on build, then runs go test -v ./...
• ✅ make lint — runs go vet, gofmt check, golangci-lint
• ✅ make coverage — runs tests with coverage profile
• ✅ make install — checks Go version, installs golangci-lint, downloads deps
• ✅ make format — runs gofmt -w .
• ✅ make clean — removes binary and coverage artifacts
• ✅ make test-race, make test-ci, make test-rust, make test-serena, make test-serena-gateway, make test-container-proxy — all present

Recommendations

Immediate Actions Required:

1. Fix the jsonschema/v5 → jsonschema/v6 typo in CONTRIBUTING.md (line 463)
2. Add internal/mcpresult/, internal/sanitize/, and internal/urlutil/ to AGENTS.md Project Structure section

No User-Facing Breaking Issues Found

All instructions that end users or contributors would follow (Quick Start, Docker run, build steps, test commands) are accurate and would work as documented.

Code References

• Dependency list: go.mod
• Config structs: internal/config/config_core.go, internal/config/config_stdin.go
• Validation logic: internal/config/validation.go
• CLI flags: internal/cmd/flags_core.go, internal/cmd/flags_logging.go, internal/cmd/flags_launch.go
• Missing packages: internal/mcpresult/, internal/sanitize/, internal/urlutil/

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 · 941.7 AIC · ⊞ 32.1K · ◷

• expires on Jun 28, 2026, 11:12 PM UTC