docs: fix documentation drift — template markers, model table, env default

[github-actions]

Documentation Freshness Audit

This audit found the following inconsistencies between code and documentation:

Findings

Area	Issue	File(s)
Template markers	{{ mcp_client_config }} section was misleading — described as "Removed" but included a detailed 4-step pipeline that duplicated the {{ prepare_steps }} description, confusing readers about what replaced it	docs/template-markers.md
Template markers	Three internal compile-time substitution aliases ({{ agent }}, {{ pipeline_name }}, {{ workspace }}) used in src/compile/common.rs were completely undocumented	docs/template-markers.md
Workflow authoring prompt	Model table presented only 2 models as if exhaustive; compiler actually accepts any valid model string (no allowlist validation in src/engine.rs)	prompts/create-ado-agentic-workflow.md
README front matter table	env field default shown as — instead of {} (empty map) — misleading because env is parsed and sanitized even if not yet applied in code generation	README.md

Details

{{ mcp_client_config }} section (docs/template-markers.md)
The section correctly noted the marker was "Removed," but then described the replacement runtime logic in a way that duplicated and partially contradicted the {{ prepare_steps }} section. Rewrote to clearly state the marker is absent from all base templates and point readers to the canonical {{ prepare_steps }} / {{ mcpg_config }} markers.

Internal substitution aliases (docs/template-markers.md)
src/compile/common.rs applies three substitutions — {{ agent }}, {{ pipeline_name }}, {{ workspace }} — in programmatically-generated YAML content. These are aliases for {{ agent_name }}, {{ pipeline_agent_name }}, and {{ working_directory }} respectively. Not documented anywhere. Added a table under the {{ working_directory }} section warning contributors not to use these aliases in custom steps:.

Model table in workflow authoring prompt (prompts/create-ado-agentic-workflow.md)
The compiler validates model strings against a character-class regex only ([a-zA-Z0-9._:-]+) — no model allowlist. The prompt implied the two listed models were the only options. Added a clarifying sentence and reframed the table as "recommended choices."

env default in README (README.md)
src/compile/types.rs defines pub env: HashMap<String, String> with #[serde(default)], which produces an empty map {} when omitted. The README table showed — (used for "no default/optional" fields), which was inconsistent with the actual behaviour.

Applied Fixes

• Rewrote {{ mcp_client_config }} section to clearly state it is removed and cross-reference the correct markers
• Added "Internal compile-time substitution aliases" table under {{ working_directory }} in docs/template-markers.md
• Added clarifying note to model table in prompts/create-ado-agentic-workflow.md
• Fixed env default from — to {} in README.md front matter 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

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

# Create a new branch
git checkout -b docs/freshness-audit-2026-05-23-6cb9faabbfa4f5f6 main

# Apply the patch (--3way handles cross-repo patches)
git am --3way /tmp/agent-26333078402/aw-docs-freshness-audit-2026-05-23.patch

# Push the branch and create the pull request
git push origin docs/freshness-audit-2026-05-23-6cb9faabbfa4f5f6
gh pr create --title 'docs: fix documentation drift — template markers, model table, env default' --base main --head docs/freshness-audit-2026-05-23-6cb9faabbfa4f5f6 --repo githubnext/ado-aw

Generated by Documentation Freshness Check · ● 34.9M · ◷