docs: fix documentation drift — duplicate ir/ tree, missing CLI commands, mcp-servers fields

[github-actions]

Documentation Freshness Audit

This audit found the following inconsistencies between code and documentation:

Findings

Area	Issue	File(s)
Architecture tree	src/compile/ir/ directory listed twice — first entry missing summary.rs, second missing tasks/	AGENTS.md
Architecture tree	IR file descriptions in first entry were stale (pre-summary.rs wording)	AGENTS.md
CLI index	7 commands absent from the docs/cli.md synopsis: mcp-author, trace, inspect, graph, whatif, lint, catalog	AGENTS.md
MCP config example	mcp-servers: example showed only container/entrypoint/allowed; 6 other McpOptions fields (enabled, args, mounts, env, url, headers) were undocumented in docs/front-matter.md	docs/front-matter.md

Details

Duplicate src/compile/ir/ entry (AGENTS.md)
The architecture tree contained two separate blocks describing src/compile/ir/. The first (early in the compile/ subtree) included tasks/ but omitted summary.rs. The second (at the end of the compile/ subtree, as the └── terminal) included summary.rs but omitted tasks/. Both described the same physical directory. Fixed by merging into a single canonical entry with both tasks/ and summary.rs, and updating file descriptions to match current source comments.

Missing CLI commands in AGENTS.md index
The one-line synopsis for docs/cli.md in AGENTS.md's Documentation Index named 13 commands but omitted mcp-author, trace, inspect, graph, whatif, lint, and catalog — all of which exist in src/main.rs and are fully documented in docs/cli.md itself.

Incomplete mcp-servers: example in docs/front-matter.md
McpOptions (in src/compile/types.rs) accepts 10 fields but the front-matter reference only demonstrated 4. Added enabled, args, mounts, env to the containerized MCP example; added a new HTTP MCP example showing url and headers; added a comment cross-referencing docs/mcp.md for the full reference.

Applied Fixes

• Merge duplicate src/compile/ir/ tree entries into one complete block (with tasks/ + summary.rs)
• Update IR file descriptions to match current source comments
• Add mcp-author, trace, inspect, graph, whatif, lint, catalog to the docs/cli.md index line in AGENTS.md
• Expand mcp-servers: YAML example in docs/front-matter.md to show all McpOptions fields; add HTTP MCP example and cross-reference to docs/mcp.md

---

This pull request was created by the automated documentation freshness check.

---

Warning

Protected Files — Push Permission Denied

This was originally intended as a pull request, but the patch modifies protected files. A human must create the pull request manually.

Protected files

• AGENTS.md

The push was rejected because GitHub Actions does not have workflows permission to push these changes, and is never allowed to make such changes, or other authorization being used does not have this permission.

Create the pull request manually

# Download the patch from the workflow run
gh run download 27839263490 -n agent -D /tmp/agent-27839263490

# Create a new branch
git checkout -b docs/fix-documentation-drift-20260619-9f28265abe6e57bd main

# Apply the patch (--3way handles cross-repo patches)
git am --3way /tmp/agent-27839263490/aw-docs-fix-documentation-drift-20260619.patch

# Push the branch and create the pull request
git push origin docs/fix-documentation-drift-20260619-9f28265abe6e57bd
gh pr create --title 'docs: fix documentation drift — duplicate ir/ tree, missing CLI commands, mcp-servers fields' --base main --head docs/fix-documentation-drift-20260619-9f28265abe6e57bd --repo githubnext/ado-aw

Generated by Documentation Freshness Check · 2.5K AIC · ⌖ 19.6 AIC · ⊞ 35K · ◷