docs: document YAML anchors, aliases and merge keys

[Sayt-0]

What

Documents that Docker Agent already supports YAML anchors (&name), aliases (*name) and merge keys (<<), and adds a runnable example. Covers the same-file DRY use cases from #3112.

Why

#3112 asks for reusable config fragments. The recommended option there (native YAML anchors) needs no code: the parser already resolves anchors, aliases and merge keys. What was missing is documentation.

Changes

File	Change
docs/configuration/overview/index.md	New "Reusable YAML (anchors & aliases)" section
examples/yaml-anchors.yaml	Runnable example using &anchor, *alias and <<

Documented behavior (verified against the loader)

Pattern	agents:	models: / mcps: / others
Anchor + alias a whole value	works	works
<< adding only new keys	works	works
<< overriding a merged key	works	fails (duplicate key, strict parse)
Anchors in a top-level defaults: block	rejected (unknown field)	rejected

The override asymmetry comes from the strict parser. The agents: section round-trips each entry through a MapSlice before decoding, so the merge resolves first. Other sections are decoded directly under yaml.Strict(), which flags the overridden key as a duplicate.

Out of scope

The cross-file !include and ${var} templating ideas from #3112 are separate features and are not part of this change. The doc points users to the existing env-var expansion for dynamic values, and notes that !include tags are ignored rather than acted on.

Testing

Test	Coverage
TestParseExamples / TestParseExamplesAfterMarshalling	new example loads, validates, round-trips
TestDocYAMLSnippetsAreValid	new doc snippets parse and validate against agent-schema.json

Closes #3112

[docker-agent]

Assessment: 🟢 APPROVE

Reviewed: docs/configuration/overview/index.md, examples/yaml-anchors.yaml

This is a documentation-only PR. The automated analysis examined the added content for factual inaccuracies, YAML validity issues, schema path correctness, and consistency between the doc snippets and the runnable example.

No confirmed bugs or issues were found. Specific checks that passed:

• yaml-language-server: $schema=../agent-schema.json resolves correctly from examples/ to the repo root agent-schema.json
• toolsets is the correct field name in AgentConfig (not tools)
• The merge-key override example in documenter correctly uses <<: *specialist + description: override, which the PR notes works in agents: due to MapSlice pre-resolution
• The documented behavior table (anchor+alias works everywhere; << override fails outside agents:) matches the callout warnings in the added doc text
• The chained anchor pattern (&house_rules → *house_rules inside &specialist → *specialist) is valid YAML
• The warning about defaults: top-level block being rejected is consistent with the known behavior

Note: The drafter agent returned review_complete: false (likely context exhaustion on a small diff). All hypotheses examined were dismissed as non-issues. No findings were escalated to verification.