📝 Documentation drift detected — undocumented field, stale markers

[github-actions]

Documentation Freshness Audit

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

Findings

Area	Issue	File(s)
Front Matter Fields	service-connection option in mcp-servers is implemented but never documented	src/compile/types.rs:369, src/compile/onees.rs:219–221
Template Markers	\{\{ agent }} replacement is registered in the standalone compiler but is absent from the template and undocumented	src/compile/standalone.rs:157, templates/base.yml
Template Markers	\{\{ workspace }} is documented as a valid marker alias, but it is not present in any template file and is not applied by the 1ES compiler	src/compile/standalone.rs:164, src/compile/onees.rs, templates/base.yml, templates/1es-base.yml

Details

1. Undocumented service-connection field in McpOptions (1ES target)

src/compile/types.rs defines:

/// Service connection name (1ES only, auto-generated if not specified)
#[serde(default, rename = "service-connection")]
pub service_connection: Option(String),

And src/compile/onees.rs uses it at compile time:

let service_connection = opts
    .and_then(|o| o.service_connection.clone())
    .unwrap_or_else(|| format!("mcp-{}-service-connection", name));

The 1ES documentation says MCP service connection names are auto-generated via the convention mcp-(name)-service-connection, but it never mentions that the auto-generated name can be overridden with a service-connection: key. This field is useful for 1ES users whose service connections use non-standard names.

2. \{\{ agent }} replacement is dead / undocumented

src/compile/standalone.rs line 157 registers:

("\{\{ agent }}", &agent_name),

This marker does not appear in templates/base.yml or templates/1es-base.yml, and it is not documented in copilot-instructions.md. It silently fires on nothing. Either this is dead code to be removed, or it should be documented.

3. \{\{ workspace }} marker not present in any template

The documentation states:

\{\{ workspace }} — An alias for \{\{ working_directory }}. Both markers are replaced with the same value based on the effective workspace setting.

However:

• grep '\{\{ workspace }}' templates/base.yml → 0 matches
• grep '\{\{ workspace }}' templates/1es-base.yml → 0 matches
• The 1ES compiler (src/compile/onees.rs) does not register a replacement for \{\{ workspace }} at all

The replacement exists only in standalone.rs (line 164) and fires on nothing in the current template. The documentation implies both markers work in both contexts, which is inaccurate.

Suggested Fixes

• Document the service-connection: override in the 1ES MCP configuration section of copilot-instructions.md (e.g., under \{\{ mcp_configuration }} and the MCP Configuration section)
• Either remove the \{\{ agent }} replacement from standalone.rs (if it is dead code) or add it to base.yml where needed and document it
• Update the \{\{ workspace }} documentation to clarify it is a standalone-only alias that can be used in custom template overrides, or add the marker to both template files if it is intended to be universally available; also add the replacement to onees.rs if 1ES support is desired

---

This issue was created by the automated documentation freshness check.

Generated by Documentation Freshness Check · ◷