docs: fix documentation drift — missing CLI commands and env field description

[github-actions]

Documentation Freshness Audit

This audit found the following inconsistencies between code and documentation:

Findings

Area	Issue	File(s)
CLI command index	AGENTS.md docs index for docs/cli.md was missing 7 public commands added after the initial list	AGENTS.md
Front-matter field description	env: field described as "reserved, not yet implemented" — inaccurate since it IS parsed	README.md

Details

1. Missing CLI commands in AGENTS.md docs index

The AGENTS.md reference entry for docs/cli.md listed only the original set of commands:

`init`, `compile`, `check`, `mcp`, `mcp-http`, `execute`, `secrets`, `enable`, `disable`, `remove`, `list`, `status`, `run`, `audit`

But the actual codebase (src/main.rs Commands enum) also exposes these public commands:

• mcp-author — author-facing MCP server (stdio)
• trace — trace a build's failing-job chain
• inspect — inspect an agent source file's typed IR
• graph — query the resolved dependency graph
• whatif — static downstream skip classification
• lint — structural lint checks
• catalog — list in-tree registries

All seven are already documented in docs/cli.md and README.md; the AGENTS.md index just hadn't been updated.

2. Inaccurate env: field description in README.md

The front-matter fields table in README.md said:

env | map | — | Workflow-level environment variables (reserved, not yet implemented)

But the field IS implemented at the parser level — it's deserialized from YAML and sanitized. It is simply not yet forwarded to the compiled pipeline output. docs/front-matter.md already uses the more accurate wording "accepted by parser, not yet forwarded to compiled pipeline output". README.md now matches.

Applied Fixes

• AGENTS.md: Added mcp-author, trace, inspect, graph, whatif, lint, catalog to the docs/cli.md index entry
• README.md: Updated env: field description from "reserved, not yet implemented" to "accepted by parser, not yet forwarded to compiled pipeline output"

---

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 27924240246 -n agent -D /tmp/agent-27924240246

# Create a new branch
git checkout -b docs/fix-documentation-drift-535acd920e964d1c main

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

# Push the branch and create the pull request
git push origin docs/fix-documentation-drift-535acd920e964d1c
gh pr create --title 'docs: fix documentation drift — missing CLI commands and env field description' --base main --head docs/fix-documentation-drift-535acd920e964d1c --repo githubnext/ado-aw

Generated by Documentation Freshness Check · 1.9K AIC · ⌖ 18.9 AIC · ⊞ 36.2K · ◷