Automate sync for hand-written guides that snapshot upstream data (e.g. vm-image.md) #532

Problem

Some hand-written guides under content/en/docs/<version>/ embed snapshots of data whose source of truth lives in the upstream cozystack/cozystack repo. These lists drift silently every time upstream changes.

The triggering case is #520, which updated the default image catalog in virtualization/vm-image.md. The 16-image list it hardcodes comes from cozystack/cozystack:packages/system/vm-default-images/values.yaml. Today there's no automation keeping it in sync — the next image addition/rename upstream will silently put the docs out of date until someone notices.

Why the existing automation doesn't cover this

make update-vms / update-apps / update-services / update-networking (driven by hack/update_apps.sh) work by copying README.md from packages/{apps,extra}/<name>/ and appending the autogenerated notice. That assumes:

1. The package has a README.md.
2. The README is the entire docs page.

Neither holds for vm-default-images:

• It's a system package (packages/system/vm-default-images/) — no README, just Chart.yaml / templates/dv.yaml / values.yaml.
• The relevant data is structured (images[].name, .url, .storage, .os.{family,name,version}, .description), not prose.
• The data needs to be embedded in a section of an otherwise hand-written guide, not replace the whole page.

Scope of the gap

The default-images list in vm-image.md is the known case. There are likely other hand-written guides under virtualization/, networking/, operations/ that embed values from upstream charts (e.g. resource defaults, supported flavors, port lists). Worth surveying before designing the solution.

Possible directions (not prescriptive)

1. Upstream README + sync target. Add README.md to packages/system/vm-default-images/ and similar packages, then add a system-package sync target to the Makefile parallel to SERVICES. Cheapest if upstream is willing.
2. Structured-data generator. New hack/render_*.py (or shell+yq) per data source that reads upstream values.yaml and renders a partial included by the guide. Hooked into a make update-* target. Most flexible; slightly more machinery.
3. Linter / drift check. CI job that diffs the embedded snapshot against the upstream source and fails if they diverge. Doesn't auto-update but stops silent rot.

Acceptance

• A documented mechanism exists for keeping snapshots-of-upstream-data in hand-written guides in sync.
• vm-image.md's default-images list uses that mechanism.
• The mechanism is wired into the upstream tags.yaml flow (or an equivalent) so it runs on each release tag.

Context

• Triggering PR: docs(virtualization): update vm-image guide for golden images / vm-default-images #520
• Upstream source for the default images list: cozystack/cozystack:packages/system/vm-default-images/values.yaml
• Existing sync contract docs: CLAUDE.md ("Autogenerated files" and "How new-version docs arrive" sections)