📚 Documentation Reconciliation Report - 2026-03-21

[github-actions]

Summary

Nightly documentation reconciliation found 2 minor discrepancies between documentation and the current implementation on main.

• Workflow Run: §23372802676
• Date: 2026-03-21
• Branch: main

---

Critical Issues 🔴

None.

---

Important Issues 🟡

None.

---

Minor Issues 🔵

1. internal/proxy/ and internal/strutil/ packages missing from CONTRIBUTING.md project structure

Location: CONTRIBUTING.md, project structure tree (lines 214–237) and Key Directories section (lines 239–257)

Problem: Two packages exist in internal/ that are not listed in the project tree or Key Directories section:

• internal/proxy/ — HTTP forward proxy implementing DIFC filtering for GitHub API requests (powers the documented Proxy Mode feature)
• internal/strutil/ — String utility helpers (DeduplicateStrings, Truncate)

Actual Behavior: Both packages are real, tested packages used by the codebase. internal/proxy/ is especially significant since it is the implementation backing the awmg proxy subcommand documented in README.md.

Impact: A developer contributing to or navigating the codebase would have an incomplete picture of the project structure. The proxy package is particularly notable because it is a substantial package (6 files) tied to a documented feature.

Suggested Fix: Add the two packages to the project structure tree and Key Directories section in CONTRIBUTING.md:

     ├── server/                # HTTP server (routed/unified modes)
+    ├── proxy/                 # HTTP forward proxy for DIFC filtering (awmg proxy subcommand)
+    ├── strutil/               # String utility helpers (deduplicate, truncate)
     ├── sys/                   # System utilities

And in Key Directories:

- **`internal/proxy/`** - HTTP forward proxy for DIFC-filtered GitHub API requests
- **`internal/strutil/`** - String utility helpers (deduplication, truncation)
```

**Code Reference:** `internal/proxy/proxy.go:1-5`, `internal/strutil/deduplicate.go`

---

### 2. `test-container-proxy` appears in `make help` but has no actual Makefile target

**Location:** `Makefile`, line 304 (inside `help` target)

**Problem:** The `help` target lists:
```
test-container-proxy - Run container proxy integration tests (requires Docker)

However, test-container-proxy does not exist as a .PHONY declaration or as an actual target in the Makefile. Running make test-container-proxy silently does nothing (succeeds with no output) because of the wildcard catch-all %: @: target.

Actual Behavior: make test-container-proxy exits 0 without running any tests.

Impact: Developers who try to run make test-container-proxy based on make help output will believe their tests ran when they did not.

Suggested Fix: Either implement the test-container-proxy target (if container proxy integration tests exist or are planned), or remove the entry from the help target output until the target is implemented.

Code Reference: Makefile:304 (help output entry), Makefile:1 (.PHONY list — test-container-proxy absent)

---

Documentation Completeness

Missing Documentation

• internal/proxy/ package is not listed in CONTRIBUTING.md project structure
• internal/strutil/ package is not listed in CONTRIBUTING.md project structure

Outdated Documentation

• Makefile help output promises test-container-proxy target that doesn't exist

Accurate Sections ✅

• Docker Quick Start (README.md) — all field names, env vars, and flags verified against code
• JSON stdin config format — mcpServers, gateway.apiKey, type, container, env, entrypoint, entrypointArgs, mounts, args, url, headers, tools, guard-policies all match StdinServerConfig and StdinGatewayConfig struct tags
• TOML config format — field names match ServerConfig and GatewayConfig struct tags (api_key, port, command, args, guard_policies)
• Go version requirement (1.25.0) — matches go.mod
• All documented make targets exist and descriptions are accurate: build, test, test-unit, test-integration, test-all, test-serena, test-serena-gateway, lint, coverage, test-ci, format, clean, install, agent-finished
• make test is correctly documented as alias for test-unit
• make test-integration correctly documented as auto-building the binary if missing
• --config, --config-stdin, and --validate-env flags all exist in internal/cmd/flags_core.go
• TOML has no \$\{VAR} variable expansion — accurately documented in CONTRIBUTING.md and config.example.toml
• run.sh defaults (port 8000, host 0.0.0.0, routed mode) accurately documented in CONTRIBUTING.md
• Environment variables in docs/ENVIRONMENT_VARIABLES.md — all vars verified against code (os.Getenv/os.LookupEnv grep confirms same list)
• Binary name awmg is correct (matches BINARY_NAME in Makefile)

Tested Commands

Command	Status	Notes
make --dry-run build	✅ Target exists	go build -o awmg .
make --dry-run test	✅ Alias confirmed	Delegates to test-unit
make --dry-run test-unit	✅ Target exists	go test -v ./internal/...
make --dry-run test-integration	✅ Target exists	Auto-builds binary if missing
make --dry-run test-all	✅ Target exists	go test -v ./... with prior build
make --dry-run lint	✅ Target exists	go vet, gofmt, golangci-lint
make --dry-run coverage	✅ Target exists	Runs unit tests with -coverprofile
make --dry-run install	✅ Target exists	Checks Go, installs golangci-lint, go mod download
make --dry-run format	✅ Target exists	gofmt -w .
make --dry-run clean	✅ Target exists	Removes binary, coverage, JSON output
make help	⚠️ Has stale entry	Lists test-container-proxy which doesn't exist

Recommendations

Immediate Actions:

1. Add internal/proxy/ and internal/strutil/ to the project structure and Key Directories section in CONTRIBUTING.md
2. Remove or implement the test-container-proxy entry in the Makefile help target

No Changes Needed:

• README.md — accurate and well-structured
• docs/ENVIRONMENT_VARIABLES.md — complete and accurate
• docs/CONFIGURATION.md — not audited in detail (large file) but cross-referenced fields all verified
• CONTRIBUTING.md (all sections except project structure) — accurate

Code References

• Config structs: internal/config/config_core.go, internal/config/config_stdin.go
• CLI flags: internal/cmd/flags_core.go, internal/cmd/flags_difc.go, internal/cmd/flags_logging.go
• Proxy package: internal/proxy/proxy.go
• String utilities: internal/strutil/deduplicate.go, internal/strutil/truncate.go
• Makefile: Makefile:1 (PHONY), Makefile:304 (help stale entry)

Generated by Nightly Documentation Reconciler · ◷

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.

• expires on Mar 24, 2026, 5:25 AM UTC