docs: fix documentation drift — remove duplicate ir/ tree entry and add missing CLI commands to README

[github-actions]

Documentation Freshness Audit

This audit found the following inconsistencies between code and documentation:

Findings

Area	Issue	File(s)
Architecture tree	ir/ directory listed twice in the compile/ module tree — first entry (missing summary.rs) duplicates the authoritative second entry	AGENTS.md
CLI Reference	7 commands present in the binary are absent from the CLI Reference table	README.md

Details

AGENTS.md — duplicate ir/ section

The src/compile/ir/ directory appears twice in the architecture tree:

1. A first, incomplete entry (missing summary.rs) inserted immediately after agentic_pipeline.rs
2. A second, complete entry at the end of the compile/ module block that correctly includes summary.rs

The first entry was a stale artifact — the directory was listed with its pre-summary.rs contents. This creates confusion about which entry is authoritative.

README.md — missing CLI commands

The CLI Reference commands table listed 14 commands but the binary exposes 21 (plus 2 hidden build-time tools). The following 7 commands were absent:

Command	Description
mcp-author	Author-facing stdio MCP server (IDE/Copilot Chat integration)
trace	Trace a build's failing-job chain using audit data + IR graph
inspect	Inspect an agent source file's typed IR
graph	Query the resolved dependency graph
whatif	Statically classify downstream jobs skipped on failure
lint	Run structural lint checks over an agent source file
catalog	List the compiler's in-tree registries

All 7 are fully documented in docs/cli.md — they were simply missing from the README's quick-reference table.

Applied Fixes

• AGENTS.md: Removed the first (incomplete) ir/ directory entry; the authoritative entry with summary.rs remains
• README.md: Added mcp-author, trace, inspect, graph, whatif, lint, and catalog to the CLI Reference Commands table

---

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

• README.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 27681272408 -n agent -D /tmp/agent-27681272408

# Create a new branch
git checkout -b docs/fix-documentation-drift-0bbfc1ca69a81f71 main

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

# Push the branch and create the pull request
git push origin docs/fix-documentation-drift-0bbfc1ca69a81f71
gh pr create --title 'docs: fix documentation drift — remove duplicate ir/ tree entry and add missing CLI commands to README' --base main --head docs/fix-documentation-drift-0bbfc1ca69a81f71 --repo githubnext/ado-aw

Generated by Documentation Freshness Check · 990.7 AIC · ⌖ 30.7 AIC · ⊞ 36.2K · ◷