📚 Documentation Reconciliation Report - 2026-05-30

[github-actions]

Summary

Found 1 minor discrepancy between documentation and implementation during nightly reconciliation check.

• Workflow Run: §26697226310
• Date: 2026-05-30
• Branch: main

Minor Issues 🔵

Small inconsistencies or missing details:

1. --otlp-sample-rate flag is undocumented

Location: README.md (Tracing section) and CONTRIBUTING.md (Advanced Flags section)

Problem: The --otlp-sample-rate flag is registered in internal/cmd/tracing.go but is not mentioned in README.md or CONTRIBUTING.md. Users configuring OpenTelemetry tracing have no way to discover this flag through the docs.

Actual Behavior: Flag exists and controls the OTLP trace sample rate. Default value comes from config.DefaultTracingSampleRate. Defaults from the OTEL_EXPORTER_OTLP_ENDPOINT env var when set.

Impact: Users enabling tracing won't know they can control the sample rate without reading the source code or running awmg --help.

Suggested Fix: Add --otlp-sample-rate to the Tracing section in README.md alongside the existing OTLP variable table, and optionally mention it in CONTRIBUTING.md Advanced Flags section.

Code Reference: internal/cmd/tracing.go — registerTracingFlags() function, flags.Float64Var(sampleRate, "otlp-sample-rate", ...)

Documentation Completeness

Missing Documentation

• --otlp-sample-rate flag: implemented in internal/cmd/tracing.go but not documented in README.md or CONTRIBUTING.md

Accurate Sections ✅

• Docker Quick Start section — verified accurate (JSON config structure, docker run command, port mappings, env vars)
• TOML/JSON configuration format — verified accurate (all struct fields match internal/config/config_core.go and config_stdin.go)
• JSON stdin does NOT support command field — correctly documented (StdinServerConfig intentionally omits Command)
• Go version requirement (1.25.0) in CONTRIBUTING.md — matches go.mod ✅
• Binary name (awmg) — matches Makefile BINARY_NAME ✅
• Default listen address (127.0.0.1:3000) — matches DefaultListenIPv4 + DefaultListenPort in internal/cmd/root.go ✅
• Default payload dir (/tmp/jq-payloads) — matches DefaultPayloadDir in internal/config/config_core.go ✅
• Default log dir (/tmp/gh-aw/mcp-logs) — matches DefaultLogDir ✅
• Auth token priority order (GITHUB_MCP_SERVER_TOKEN → GITHUB_TOKEN → GITHUB_PERSONAL_ACCESS_TOKEN → GH_TOKEN) — matches internal/envutil/github.go ✅
• All referenced example files exist (config.example.toml, config.example-payload-threshold.toml, example-http-config.json, example.env, agent-configs/codex.config.toml) ✅

Tested Commands

All make targets from CONTRIBUTING.md were verified against Makefile:

• ✅ make build — target exists, creates awmg binary as documented
• ✅ make test — alias for test-unit as documented
• ✅ make test-unit — runs ./internal/... as documented
• ✅ make test-integration — auto-builds binary if not present, as documented
• ✅ make test-all — depends on build target, rebuilds binary first as documented
• ✅ make test-rust — Rust guard tests with cargo, as documented
• ✅ make test-race — race detection tests, as documented
• ✅ make test-serena — Serena MCP tests, as documented
• ✅ make test-serena-gateway — Serena via gateway tests, as documented
• ✅ make test-container-proxy — container proxy tests, as documented
• ✅ make lint — go vet + gofmt + golangci-lint, as documented
• ✅ make coverage — unit tests with coverage report, as documented
• ✅ make install — installs golangci-lint v2.8.0 + Go deps, as documented
• ✅ make format — gofmt -w, as documented
• ✅ make clean — removes awmg, coverage.out, test-result-unit.json, as documented
• ✅ make agent-finished — format + build + lint + all tests, as documented

Recommendations

Nice to Have:

1. Add --otlp-sample-rate <float> to the Tracing section of README.md (after the OTLP env var table) with a brief description of its effect on trace sampling

Code References

• Tracing flag registration: internal/cmd/tracing.go — registerTracingFlags()
• Configuration structs: internal/config/config_core.go, internal/config/config_stdin.go
• Auth token resolution: internal/envutil/github.go
• CLI flag defaults: internal/cmd/flags_core.go, internal/cmd/flags_launch.go

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 · sonnet46 3.3M · ◷

• expires on Jun 2, 2026, 11:05 PM UTC