📝 Documentation drift detected — undocumented `service-connection` field and misleading `\{\{ workspace }}` marker description

[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: override field in mcp-servers is not documented	src/compile/types.rs:331, src/compile/onees.rs:194-197
Template Markers	\{\{ workspace }} is documented as a first-class template marker but does not appear in either .yml template file directly	templates/base.yml, templates/1es-base.yml, .github/copilot-instructions.md

Details

1. Undocumented service-connection: field in McpOptions

The McpOptions struct in src/compile/types.rs (line 331) exposes a service-connection field:

#[serde(default, rename = "service-connection")]
pub service_connection: Option(String),

The 1ES compiler (src/compile/onees.rs, lines 194–197) uses this field to let users override the auto-generated service connection name:

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

The documentation describes only the auto-generated naming convention (mcp-{name}-service-connection) and makes no mention of the service-connection: override field. Users targeting the 1es pipeline format who need a custom service connection name have no documentation to guide them.

What's missing: An example showing how to configure the override in front matter, e.g.:

mcp-servers:
  kusto:
    service-connection: my-org-kusto-connection  # overrides default mcp-kusto-service-connection
    allowed:
      - query

2. \{\{ workspace }} documented as a template marker but absent from template files

The documentation dedicates a ## \{\{ workspace }} section describing it as "An alias for \{\{ working_directory }}. Both markers are replaced with the same value." However, a grep over both template files shows \{\{ workspace }} does not appear in templates/base.yml or templates/1es-base.yml directly.

What actually happens is that \{\{ source_path }} and \{\{ pipeline_path }} are generated in src/compile/common.rs (lines 473, 486) as strings containing \{\{ workspace }} as an intermediate placeholder (e.g. \{\{ workspace }}/agents/foo.md). After those markers are replaced in the template, the resulting string contains \{\{ workspace }}, which is then resolved by the subsequent replacement.

This means \{\{ workspace }} is a real, functioning marker — but it is an intermediate one injected by source_path/pipeline_path computation, not one written directly in the template files. Documenting it at the same level as markers like \{\{ working_directory }} (which appears explicitly in both template files) can mislead anyone reading the templates or trying to add a new marker.

Suggested improvement: Clarify in the docs that \{\{ workspace }} is an intermediate placeholder introduced during source-path generation, not written directly in .yml templates; or move the note into the \{\{ source_path }} / \{\{ pipeline_path }} sections where it naturally belongs.

Suggested Fixes

• Add service-connection: to the mcp-servers field documentation (under the 1ES section and/or the McpOptions table) with a usage example showing how to override the auto-generated service connection name.
• Clarify the \{\{ workspace }} documentation: either note it is an intermediate marker produced during path generation (not present directly in template files), or fold the explanation into the \{\{ source_path }} and \{\{ pipeline_path }} sections.

---

This issue was created by the automated documentation freshness check.

Generated by Documentation Freshness Check · ◷