📚 Documentation Reconciliation Report - 2026-03-22

[github-actions]

Summary

Nightly documentation reconciliation found 1 minor discrepancy between documentation and implementation.

• Workflow Run: §23396478033
• Date: 2026-03-22
• Branch: main

---

Critical Issues 🔴

None found.

---

Important Issues 🟡

None found.

---

Minor Issues 🔵

1. test-container-proxy Make Target Missing from CONTRIBUTING.md

Location: CONTRIBUTING.md — Testing section
Problem: The test-container-proxy make target exists in Makefile and appears in make help output, but is never mentioned in CONTRIBUTING.md's Testing section.
Actual Behavior: Running make test-container-proxy builds a Docker image and runs proxy mode integration tests with TLS — it requires Docker daemon and a GitHub token (GITHUB_TOKEN, GH_TOKEN, or gh auth login).
Impact: Developers working on proxy mode (or verifying it) are unaware this testing option exists unless they read the Makefile directly or run make help.
Suggested Fix: Add the following block to CONTRIBUTING.md under the "Serena MCP Tests (Optional)" section:

#### Container Proxy Tests (Optional)
Run container proxy integration tests (requires Docker daemon and GitHub token):
```bash
make test-container-proxy  # Build Docker image, test proxy mode with TLS

This requires: Docker daemon, GitHub token (GITHUB_TOKEN, GH_TOKEN, or gh auth login), and a network connection.

**Code Reference:** `Makefile` — `.PHONY` line and `test-container-proxy:` target (~line 51–57)

---

## Documentation Completeness

### Missing Documentation
- `test-container-proxy` make target is implemented but not documented in `CONTRIBUTING.md`

### Outdated Documentation
None found.

### Accurate Sections ✅
- **README.md Quick Start** — Docker config JSON structure (`apiKey`, `mcpServers`, `type`, `container`, `env`) verified against `StdinConfig`/`StdinGatewayConfig` structs
- **README.md Guard Policies** — `allow-only` and `write-sink` fields verified against `internal/config/guard_policy.go`
- **CONTRIBUTING.md Prerequisites** — Go 1.25.0 matches `go.mod`
- **CONTRIBUTING.md Build commands** — All `make build`, `make lint`, `make format`, `make clean`, `make install`, `make release` targets verified in `Makefile`
- **CONTRIBUTING.md Test commands** — `make test`, `make test-unit`, `make test-integration`, `make test-all`, `make coverage`, `make test-ci`, `make test-serena`, `make test-serena-gateway` all verified
- **CONTRIBUTING.md Architecture Notes** — TOML "no `\$\{VAR}` expansion" claim verified (LoadFromFile does not call ExpandRawJSONVariables); JSON stdin expansion verified
- **`--config-stdin` flag** — Exists in `internal/cmd/flags_core.go:36`; CONTRIBUTING.md usage correct
- **Environment variables** — All vars in `AGENTS.md` and `docs/ENVIRONMENT_VARIABLES.md` (`MCP_GATEWAY_PORT`, `MCP_GATEWAY_DOMAIN`, `MCP_GATEWAY_API_KEY`, `MCP_GATEWAY_LOG_DIR`, `MCP_GATEWAY_PAYLOAD_DIR`, `MCP_GATEWAY_PAYLOAD_PATH_PREFIX`, `MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD`, `MCP_GATEWAY_WASM_GUARDS_DIR`, `MCP_GATEWAY_GUARDS_MODE`, `MCP_GATEWAY_GUARDS_SINK_SERVER_IDS`, `MCP_GATEWAY_GUARD_POLICY_JSON`, `RUNNING_IN_CONTAINER`, `DOCKER_HOST`, `DEBUG`, `DEBUG_COLORS`, and all `MCP_GATEWAY_ALLOWONLY_*` vars) verified against code
- **JSON stdin config fields** — `container`, `entrypoint`, `entrypointArgs`, `args`, `mounts`, `env`, `url`, `headers`, `tools`, `registry`, `guard-policies`, `guard` verified against `StdinServerConfig`; `command` field correctly documented as NOT supported for JSON stdin
- **TOML config fields** — `command`, `args`, `env`, `working_directory`, `url`, `headers`, `tools`, `registry`, `guard_policies`, `guard` verified against `ServerConfig`
- **Default port 3000** — Matches `DefaultPort = 3000` constant in `config_core.go`
- **Dockerfile** — Correctly uses `run_containerized.sh` as ENTRYPOINT; CONTRIBUTING.md description accurate

---

## Tested Commands

- ✅ `make --dry-run build` — creates `awmg` binary as documented
- ✅ `make --dry-run test` — alias for `test-unit` as documented
- ✅ `make --dry-run test-unit` — runs `go test ./internal/...`
- ✅ `make --dry-run test-integration` — builds binary if needed, then runs `go test ./test/integration/...`
- ✅ `make --dry-run test-all` — builds then runs all tests
- ✅ `make --dry-run lint` — runs `go vet`, `gofmt`, `golangci-lint`
- ✅ `make --dry-run coverage` — runs unit tests with coverage
- ✅ `make --dry-run install` — verifies Go, installs golangci-lint, downloads modules
- ⚠️ `make build` — failed in this sandboxed environment due to network restriction blocking Go 1.25.0 toolchain download; this is an environment limitation, not a documentation issue

---

## Recommendations

### Nice to Have:
1. Add documentation for `test-container-proxy` in `CONTRIBUTING.md` Testing section so developers testing proxy mode can discover this target without reading the Makefile

## Code References

- Configuration 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_difc.go`, `internal/cmd/flags_logging.go`
- Environment variable parsing: `internal/config/config_env.go`, `internal/envutil/envutil.go`
- Missing test target: `Makefile` (`test-container-proxy` target)




> Generated by [Nightly Documentation Reconciler](https://github.com/github/gh-aw-mcpg/actions/runs/23396478033) · [◷](https://github.com/search?q=repo%3Agithub%2Fgh-aw-mcpg+is%3Aissue+%22gh-aw-workflow-call-id%3A+github%2Fgh-aw-mcpg%2Fnightly-docs-reconciler%22&type=issues)

> [!WARNING]
> <details>
> <summary>⚠️ Firewall blocked 1 domain</summary>
>
> 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:
>
> ```yaml
> network:
>   allowed:
>     - defaults
>     - "proxy.golang.org"
> ```
>
> See [Network Configuration](https://github.github.com/gh-aw/reference/network/) for more information.
>
> </details>

> - [x] expires <!-- gh-aw-expires: 2026-03-25T05:34:02.429Z --> on Mar 25, 2026, 5:34 AM UTC

<!-- gh-aw-agentic-workflow: Nightly Documentation Reconciler, engine: copilot, id: 23396478033, workflow_id: nightly-docs-reconciler, run: https://github.com/github/gh-aw-mcpg/actions/runs/23396478033 -->

<!-- gh-aw-workflow-id: nightly-docs-reconciler -->
<!-- gh-aw-workflow-call-id: github/gh-aw-mcpg/nightly-docs-reconciler -->