📚 Documentation Reconciliation Report - 2026-04-01

[github-actions]

Summary

Nightly documentation reconciliation audit found 1 important undocumented feature and 1 minor gap against the current main branch implementation. The core documentation (Quick Start, build commands, project structure) is accurate and working.

• Workflow Run: §23831043886
• Date: 2026-04-01
• Branch: main

Critical Issues 🔴

None found. All documented instructions are accurate and functional.

Important Issues 🟡

1. GitHub OIDC Authentication for HTTP Servers Not Documented

Location: docs/CONFIGURATION.md (Server Configuration Fields section), docs/ENVIRONMENT_VARIABLES.md

Problem: The auth field for HTTP MCP backend servers (enabling github-oidc authentication) is fully implemented in the codebase but is not mentioned anywhere in user-facing documentation.

Actual Behavior: HTTP servers support an auth field with type: "github-oidc" and optional audience to automatically obtain OIDC tokens from GitHub Actions and attach them as Authorization: Bearer <token> headers. When configured, the launcher reads ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN from the environment (set automatically by GitHub Actions when permissions: { id-token: write } is granted).

Code References:

• internal/config/config_stdin.go:102 — Auth *AuthConfig \json:"auth,omitempty"``
• internal/config/validation.go:165-210 — validateAuthConfig (only github-oidc is currently supported)
• internal/launcher/launcher.go:67-137 — OIDC provider initialization and per-server auth assignment
• internal/oidc/provider.go — OIDC token provider implementation

Impact: Users who deploy HTTP MCP backends requiring OIDC JWT authentication in GitHub Actions cannot discover this feature without reading the source code.

Suggested Fix for docs/CONFIGURATION.md (add to Server Configuration Fields section):

- **`auth`** (optional, HTTP servers only): Upstream authentication configuration
  - Only supported for `type: "http"` servers; using `auth` with stdio servers returns a validation error
  - Currently supports one `type`:
    - `"github-oidc"` — Obtains a GitHub Actions OIDC token and attaches it as `Authorization: Bearer <token>` on every request to the HTTP backend. Requires the GitHub Actions job to have `permissions: { id-token: write }`.
  - **`audience`** (optional): OIDC token audience. Defaults to the server's `url` value.
  - Example:
    ```json
    "my-http-server": {
      "type": "http",
      "url": "(myinternalservice.example.com/redacted),
      "auth": {
        "type": "github-oidc",
        "audience": "(myinternalservice.example.com/redacted)"
      }
    }
    ```

Suggested Fix for docs/ENVIRONMENT_VARIABLES.md (add a new section or table row):

Add to the "Proxy Mode Variables" or create a new "GitHub Actions OIDC Variables" section:

Variable	Description	Default
ACTIONS_ID_TOKEN_REQUEST_URL	GitHub Actions OIDC token endpoint (set automatically by GitHub Actions runner when permissions: { id-token: write } is granted). Required when any HTTP server uses auth.type = "github-oidc".	(set by GitHub Actions)
ACTIONS_ID_TOKEN_REQUEST_TOKEN	GitHub Actions OIDC bearer token used to authenticate the token request (set automatically by GitHub Actions runner). Used alongside ACTIONS_ID_TOKEN_REQUEST_URL.	(set by GitHub Actions)

Minor Issues 🔵

2. Several CLI Flags Not Mentioned in CONTRIBUTING.md or README.md

Location: CONTRIBUTING.md (Running Locally section)

Problem: The following flags are implemented and used in common workflows, but are not shown in any awmg usage examples in CONTRIBUTING.md or README.md:

Flag	Env Var	Description
--env <file>	—	Load environment variables from a .env file
--verbose / -v	DEBUG	Increase verbosity (can be passed multiple times)
--log-dir <dir>	MCP_GATEWAY_LOG_DIR	Directory for log files
--payload-dir <dir>	MCP_GATEWAY_PAYLOAD_DIR	Directory for large payload storage
--payload-path-prefix	MCP_GATEWAY_PAYLOAD_PATH_PREFIX	Client-visible path prefix for payload files
--payload-size-threshold	MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD	Byte threshold above which payloads are written to disk

Code Reference: internal/cmd/flags_core.go, internal/cmd/flags_logging.go

Impact: These flags are documented in docs/ENVIRONMENT_VARIABLES.md and AGENTS.md, but a developer reading only CONTRIBUTING.md would not know about them.

Suggested Fix: Add an "Advanced Flags" subsection to the "Running Locally" section in CONTRIBUTING.md:

### Advanced Flags

```bash
# Custom log directory
./awmg --config config.toml --log-dir /path/to/logs

# Load environment file
./awmg --config config.toml --env .env

# Increase verbosity
./awmg --config config.toml -v

# Custom payload directory and size threshold
./awmg --config config.toml --payload-dir /tmp/payloads --payload-size-threshold 1048576

See docs/ENVIRONMENT_VARIABLES.md for the full list of environment variable overrides.

## Documentation Completeness

### Missing Documentation
- `auth` field (HTTP server OIDC configuration) — implemented, not documented
- `ACTIONS_ID_TOKEN_REQUEST_URL` / `ACTIONS_ID_TOKEN_REQUEST_TOKEN` — used by launcher, not listed in `docs/ENVIRONMENT_VARIABLES.md`
- Several runtime flags missing from `CONTRIBUTING.md` examples

### Accurate Sections ✅
- README.md Quick Start (Docker command, JSON config format, required flags) — verified accurate
- README.md Guard Policies (`allow-only`, `write-sink`) — verified against code
- README.md Proxy Mode (`awmg proxy`) — command exists
- CONTRIBUTING.md make targets (`build`, `test`, `test-unit`, `test-integration`, `test-all`, `lint`, `coverage`, `test-ci`, `format`, `clean`, `install`) — all exist in Makefile with correct descriptions
- CONTRIBUTING.md Go version (`1.25.0`) — matches `go.mod`
- CONTRIBUTING.md binary name (`awmg`) — matches Makefile `BINARY_NAME`
- CONTRIBUTING.md project structure — all listed `internal/` packages exist in codebase
- CONTRIBUTING.md default port (3000 for binary, 8000 for Docker/`run.sh`) — correctly documented
- CONTRIBUTING.md Docker development section — verified against Dockerfile and `run_containerized.sh`
- Variable expansion `\$\{VAR_NAME}` syntax — JSON stdin format only, TOML is accurately noted as not supporting expansion

## Tested Commands

- ✅ `make --dry-run build` — target exists, runs `go build -o awmg .`
- ✅ `make --dry-run test` — alias for `test-unit`
- ✅ `make --dry-run test-unit` — runs `go test -v ./internal/...`
- ✅ `make --dry-run test-integration` — auto-builds binary if needed
- ✅ `make --dry-run test-all` — runs unit + integration
- ✅ `make --dry-run lint` — runs go vet, gofmt check, golangci-lint
- ✅ `make --dry-run coverage` — runs unit tests with coverage report
- ✅ `make --dry-run install` — installs Go dependencies and golangci-lint
- ⚠️ `make build` — **could not execute**: environment has Go 1.24.13 but `go.mod` requires 1.25.0; documentation correctly states this requirement

## Code References

- `auth` field implementation: `internal/config/config_stdin.go:102`, `internal/config/validation.go:165-210`
- OIDC provider: `internal/launcher/launcher.go:67-137`, `internal/oidc/provider.go`
- Flag definitions: `internal/cmd/flags_core.go`, `internal/cmd/flags_logging.go`
- Env var helpers: `internal/config/config_env.go`




> Generated by [Nightly Documentation Reconciler](https://github.com/github/gh-aw-mcpg/actions/runs/23831043886/agentic_workflow) · [◷](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)
> - [x] expires <!-- gh-aw-expires: 2026-04-04T04:00:01.298Z --> on Apr 4, 2026, 4:00 AM UTC

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

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