docs: fix documentation drift — add {{ copilot_version }}, remove phantom {{ workspace }}, document service-connection field

[Copilot]

Three inconsistencies between code and AGENTS.md identified by the weekly doc freshness audit.

Changes

• Remove phantom {{ workspace }} section — neither template file contains this marker; the compiler replacement is dead code. Updated the {{ pipeline_path }} description to reference {{ working_directory }} instead.

• Add {{ copilot_version }} documentation — marker appears in base.yml (lines 37, 298) and 1es-base.yml (line 165), replaced by COPILOT_CLI_VERSION constant in src/compile/common.rs. Documents that it pins the Microsoft.Copilot.CLI.linux-x64 NuGet package version installed from Azure Artifacts.

• Document service-connection in MCP Configuration Properties — McpOptions.service_connection (types.rs:370, used in onees.rs:221–225) overrides the auto-generated mcp-<name>-service-connection naming for 1ES targets but was entirely undocumented:

mcp-servers:
  ado:
    service-connection: my-custom-ado-sc  # overrides default mcp-ado-service-connection
    allowed:
      - create_work_item

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• api.github.com (HTTP Only)
  • Triggering command: /home/REDACTED/work/ado-aw/ado-aw/target/debug/ado-aw /home/REDACTED/work/ado-aw/ado-aw/target/debug/ado-aw proxy --allow api.github.com /home/REDACTED/work/ado-aw/ado-aw/target/debug/deps/async_trait-0d9946b44b5e2a43.a/home/REDACTED/work/ado-aw/ado-aw/target/debug/deps/ado_aw-12332330a3699062.0tq789a8vmenn07qp0vvf0dwx.1n24van.rcgu.o /home/REDACTED/work/ado-aw/ado-aw/target/debug/deps/async_trait-0d9946b44b5e2a43.a/home/REDACTED/work/ado-aw/ado-aw/target/debug/deps/ado_aw-12332330a3699062.0tzcushkpgwxcr6sv53al5k17.1n24van.rcgu.o 4.0e9n4tn2jsjz770vkg9u9zkj3.080b9q3.rcgu.o 4.0fo4o8mez4ycvnf3o20q2znp3.080b9q3.rcgu.o 4.0galxp89m0qufhtiafhjes60t.080b9q3.rcgu.o 4.0kko11vxt9luz7tbwf2bn2uqk.080b9q3.rcgu.o 4.0yimo8hg5u2yuph7dphdx3lnc.080b9q3.rcgu.o 4.180vyceco4m9eb5c6ddlkj9i2.080b9q3.rcgu.o 4.1d6rp8xx7xnof3i1sd78dss8y.080b9q3.rcgu.o 4.1jz6yei2o1eera9o861riuynz.080b9q3.rcgu.o 4.1q6updo27gejellw6ei625f69.080b9q3.rcgu.o 4.1rhaldwggaiglv7hkkn2jglf7.080b9q3.rcgu.o 4.1vrya1a4of4up25205cdtsl4a.080b9q3.rcgu.o 4.1wn2ifqo0y0v6n0tfp7imbko6.080b9q3.rcgu.o 4.2cui6z0qegr6w3c0qg4h26c5w.080b9q3.rcgu.o 4.2g1fsy8r3k2aaf05thl66nqry.080b9q3.rcgu.o (packet block)
• dev.azure.com
  • Triggering command: /home/REDACTED/work/ado-aw/ado-aw/target/debug/ado-aw /home/REDACTED/work/ado-aw/ado-aw/target/debug/ado-aw proxy --allow api.github.com --allow dev.azure.com --allow *.visualstudio.com 4.0galxp89m0qufhtiafhjes60t.080b9q3.rcgu.o 4.0kko11vxt9luz7tbwf2bn2uqk.080b9q3.rcgu.o 4.0yimo8hg5u2yuph7dphdx3lnc.080b9q3.rcgu.o 4.180vyceco4m9eb5c6ddlkj9i2.080b9q3.rcgu.o 4.1d6rp8xx7xnof3i1sd78dss8y.080b9q3.rcgu.o 4.1jz6yei2o1eera9o861riuynz.080b9q3.rcgu.o 4.1q6updo27gejellw6ei625f69.080b9q3.rcgu.o 4.1rhaldwggaiglv7hkkn2jglf7.080b9q3.rcgu.o 4.1vrya1a4of4up25205cdtsl4a.080b9q3.rcgu.o 4.1wn2ifqo0y0v6n0tfp7imbko6.080b9q3.rcgu.o 4.2cui6z0qegr6w3c0qg4h26c5w.080b9q3.rcgu.o 4.2g1fsy8r3k2aaf05thl66nqry.080b9q3.rcgu.o (dns block)
• msazuresphere.visualstudio.com
  • Triggering command: /home/REDACTED/work/ado-aw/ado-aw/target/debug/ado-aw /home/REDACTED/work/ado-aw/ado-aw/target/debug/ado-aw proxy --allow api.github.com --allow dev.azure.com --allow *.visualstudio.com 4.0galxp89m0qufhtiafhjes60t.080b9q3.rcgu.o 4.0kko11vxt9luz7tbwf2bn2uqk.080b9q3.rcgu.o 4.0yimo8hg5u2yuph7dphdx3lnc.080b9q3.rcgu.o 4.180vyceco4m9eb5c6ddlkj9i2.080b9q3.rcgu.o 4.1d6rp8xx7xnof3i1sd78dss8y.080b9q3.rcgu.o 4.1jz6yei2o1eera9o861riuynz.080b9q3.rcgu.o 4.1q6updo27gejellw6ei625f69.080b9q3.rcgu.o 4.1rhaldwggaiglv7hkkn2jglf7.080b9q3.rcgu.o 4.1vrya1a4of4up25205cdtsl4a.080b9q3.rcgu.o 4.1wn2ifqo0y0v6n0tfp7imbko6.080b9q3.rcgu.o 4.2cui6z0qegr6w3c0qg4h26c5w.080b9q3.rcgu.o 4.2g1fsy8r3k2aaf05thl66nqry.080b9q3.rcgu.o (dns block)
• raw.github.com
  • Triggering command: /home/REDACTED/work/ado-aw/ado-aw/target/debug/ado-aw /home/REDACTED/work/ado-aw/ado-aw/target/debug/ado-aw proxy --allow *.github.com -C debuginfo=2 4.0e9n4tn2jsjz770vkg9u9zkj3.080b9q3.rcgu.o 4.0fo4o8mez4ycvnf3o20q2znp3.080b9q3.rcgu.o 4.0galxp89m0qufhtiafhjes60t.080b9q3.rcgu.o 4.0kko11vxt9luz7tbwf2bn2uqk.080b9q3.rcgu.o 4.0yimo8hg5u2yuph7dphdx3lnc.080b9q3.rcgu.o 4.180vyceco4m9eb5c6ddlkj9i2.080b9q3.rcgu.o 4.1d6rp8xx7xnof3i1sd78dss8y.080b9q3.rcgu.o 4.1jz6yei2o1eera9o861riuynz.080b9q3.rcgu.o 4.1q6updo27gejellw6ei625f69.080b9q3.rcgu.o 4.1rhaldwggaiglv7hkkn2jglf7.080b9q3.rcgu.o 4.1vrya1a4of4up25205cdtsl4a.080b9q3.rcgu.o 4.1wn2ifqo0y0v6n0tfp7imbko6.080b9q3.rcgu.o 4.2cui6z0qegr6w3c0qg4h26c5w.080b9q3.rcgu.o 4.2g1fsy8r3k2aaf05thl66nqry.080b9q3.rcgu.o (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>📝 Documentation drift detected — undocumented \{\{ copilot_version }} marker, phantom \{\{ workspace }} marker, and missing
[Content truncated due to length]</issue_title>
<issue_description>## Documentation Freshness Audit

The weekly documentation audit found the following inconsistencies between code and documentation:

Findings

Area	Issue	File(s)
Template Markers	\{\{ copilot_version }} is used in both templates and implemented in code, but is not documented	templates/base.yml, templates/1es-base.yml, src/compile/common.rs:466
Template Markers	\{\{ workspace }} is documented as "an alias for \{\{ working_directory }}" but does not appear in any template file — it is a dead replacement in the compiler	templates/base.yml, templates/1es-base.yml, src/compile/standalone.rs:165, src/compile/onees.rs:166
Front Matter Fields	service_connection field in McpOptions struct is implemented and used (for 1ES MCP config) but not documented in the MCP configuration section	src/compile/types.rs:370, src/compile/onees.rs:221-225

Details

1. Undocumented \{\{ copilot_version }} marker

\{\{ copilot_version }} appears in both templates/base.yml (lines 37 and 298) and templates/1es-base.yml (line 165). It is replaced at compile time with the COPILOT_CLI_VERSION constant defined in src/compile/common.rs:466 (currently "1.0.6"). This marker installs the Microsoft.Copilot.CLI.linux-x64 NuGet package at the pinned version in generated pipelines — but it has no entry in the template markers section of the documentation.

2. Phantom \{\{ workspace }} marker

The documentation describes \{\{ workspace }} as "An alias for \{\{ working_directory }}". The compiler does handle the replacement in standalone.rs:165 and onees.rs:166. However, neither templates/base.yml nor templates/1es-base.yml nor templates/threat-analysis.md contains the \{\{ workspace }} string — meaning the replacement is effectively dead code and the documented marker never triggers. Either the templates should use \{\{ workspace }} where intended (e.g., alongside \{\{ working_directory }}), or the documentation for this marker should be removed.

3. Undocumented service_connection field in McpOptions

src/compile/types.rs:370 defines pub service_connection: Option(String) in the McpOptions struct. This field is consumed in src/compile/onees.rs:221-225 to resolve which service connection to use for a built-in MCP in the 1ES target. The MCP configuration section of the documentation describes command, args, allowed, and env — but does not mention service_connection, which allows callers to override the default naming convention (mcp-(name)-service-connection) for 1ES MCP integration.

Suggested Fixes

• Add \{\{ copilot_version }} to the template markers section of AGENTS.md / .github/copilot-instructions.md, describing it as the pinned version of the Microsoft.Copilot.CLI NuGet package (constant COPILOT_CLI_VERSION in src/compile/common.rs)
• Decide whether \{\{ workspace }} should be removed from the docs (if it's intentionally unused) or added to the templates where it makes sense; either way, align docs and code
• Document the service_connection option under the 1ES-specific MCP configuration section, explaining it overrides the default mcp-(name)-service-connection naming convention

---

This issue was created by the automated documentation freshness check.

Generated by Documentation Freshness Check · ◷

Comments on the Issue (you are @copilot in this section)

• Fixes 📝 Documentation drift detected — undocumented \{\{ copilot_version }} marker, phantom \{\{ workspace }} marker, and missing [Content truncated due to length] #53

---

💬 Send tasks to Copilot coding agent from Slack and Teams to turn conversations into code. Copilot posts an update in your thread when it's finished.