📚 Documentation Reconciliation Report - 2026-06-01

[github-actions]

Summary

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

• Workflow Run: §26787777436
• Date: 2026-06-01
• Branch: main

---

Critical Issues 🔴

None found. ✅

---

Important Issues 🟡

1. Misleading json: tags on TOML-only fields in ServerConfig

Location: internal/config/config_core.go
Problem: ServerConfig.RateLimitThreshold and ServerConfig.RateLimitCooldown carry json:"..." struct tags, yet code comments on both fields explicitly state they are "Supported in TOML config only." The JSON stdin path uses a separate StdinServerConfig struct that correctly omits these fields, so runtime behavior is correct — but the tags are misleading to developers reading the struct and could cause confusion if the JSON deserialization path changes.
Actual Behavior: The fields are never populated from JSON stdin (correct), but the tags imply they would be.
Impact: Developer confusion; latent risk if the unmarshalling path is ever refactored.
Suggested Fix: Remove the json: struct tags from RateLimitThreshold and RateLimitCooldown, or add an explicit json:"-" tag with an explanatory comment.
Code Reference: internal/config/config_core.go — ServerConfig struct, RateLimitThreshold and RateLimitCooldown fields.

---

Minor Issues 🔵

2. TAVILY_API_KEY missing from AGENTS.md environment variables table

Location: AGENTS.md — Environment Variables section
Problem: TAVILY_API_KEY is referenced in test/integration/tavily_test.go and documented in docs/ENVIRONMENT_VARIABLES.md, but is absent from the AGENTS.md env-vars table that agents use as their primary reference.
Suggested Fix: Add an entry to the AGENTS.md env vars section:

- `TAVILY_API_KEY` — Tavily API key; when unset, integration tests that use it are automatically skipped.

3. Legacy JSON snake_case aliases undocumented

Location: README.md / AGENTS.md — JSON stdin configuration docs
Problem: StdinServerConfig accepts two legacy snake_case aliases via assignLegacyIntAlias:

• connect_timeout (legacy alias for connectTimeout)
• tool_timeout (legacy alias for toolTimeout)

Neither alias is mentioned anywhere in the documentation. Users who pass these keys get silently-accepted values, which can be confusing if they expect an error.
Suggested Fix: Add a note in the JSON stdin configuration section of README.md that these legacy aliases are accepted for backward compatibility.

---

Documentation Completeness

Accurate Sections ✅

• Go version 1.25.0 in go.mod — matches CONTRIBUTING.md prerequisite
• Binary name awmg — matches Makefile build target output
• All Makefile targets listed in CONTRIBUTING.md (build, test, test-unit, test-integration, test-all, lint, coverage, install) — all exist verbatim in Makefile
• GitHub token priority order (GITHUB_MCP_SERVER_TOKEN → GITHUB_TOKEN → GITHUB_PERSONAL_ACCESS_TOKEN → GH_TOKEN) — verified in code
• All 35+ documented environment variables confirmed via os.Getenv/os.LookupEnv audit
• All documented CLI flags (--config, --sequential-launch, --log-dir, --payload-dir, etc.) exist in source
• JSON stdin struct fields (type, container, env, args, entrypoint, entrypointArgs, mounts) — all present in StdinServerConfig
• command field correctly absent from StdinServerConfig (TOML-only) — accurately documented
• Default dirs, ports, and size thresholds match constants in config_core.go
• All internal package directories listed in CONTRIBUTING.md exist on disk
• TOML configuration field names match TOML struct tags

Missing Documentation

• TAVILY_API_KEY not listed in AGENTS.md env vars section
• connect_timeout / tool_timeout legacy snake_case aliases not documented

Outdated Documentation

None found. ✅

---

Tested Commands

Command	Status
make build	✅ works as documented
make test	✅ exists and maps to unit tests
make test-unit	✅ works as documented
make test-integration	✅ works as documented
make test-all	✅ works as documented
make lint	✅ works as documented
make coverage	✅ works as documented
make install	✅ works as documented
./awmg --help	✅ all documented flags present

---

Recommendations

Nice to Have

1. Remove or replace json:"..." tags on RateLimitThreshold/RateLimitCooldown with json:"-" to make TOML-only intent explicit.
2. Add TAVILY_API_KEY to AGENTS.md env vars table.
3. Document connect_timeout and tool_timeout legacy aliases in README.md JSON stdin config section.

Code References

• Configuration structs: internal/config/config_core.go
• JSON stdin structs: internal/config/config_stdin.go
• Validation logic: internal/config/validation.go
• Tavily integration test: test/integration/tavily_test.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 2.8M · ◷

• expires on Jun 4, 2026, 11:20 PM UTC