Problem

make bom-docs renders docs/user/container-images.md from each component's registry defaultVersion, not from the version a recipe actually resolves after overlay pins are applied. Since overlays routinely pin component versions (componentRefs[].version) that override the registry default, the BOM can advertise a version that no real recipe installs — and per-overlay version drift is therefore invisible in the BOM.

Evidence (surfaced by #1418)

aws-efa is pinned in two places:

• recipes/registry.yaml → defaultVersion
• recipes/overlays/eks.yaml → componentRefs[].version (overrides the registry default for every EKS recipe — and EKS is the only aws-efa consumer)

In #1418 the registry default was bumped (v0.5.26 → v0.5.29) and the BOM regenerated to v0.5.29, but eks.yaml still pinned v0.5.26. Result: the BOM (and PR summary) advertised v0.5.29 while every EKS recipe actually rendered v0.5.26. Nothing flagged the mismatch — the BOM is generated from the registry default, so it looked correct. The fix in #1418 only re-aligned the two pins by hand; the underlying invisibility remains.

Impact

• The BOM is the user-facing source of truth for shipped image/chart versions (and feeds supply-chain expectations). It can misreport the actual installed version for any component whose overlay pin diverges from the registry default.
• Version bumps can appear applied (green BOM regen) while real recipes are unchanged — a silent correctness gap, exactly the class of bug chore(recipes): bump aws-efa to v0.5.29, align image tag to appVersion #1418 hit.

Underlying question — version-management model

Version pinning is currently split and inconsistent:

• Some components carry a registry defaultVersion.
• Most are pinned per-overlay (base.yaml, aks.yaml, oke.yaml, …) — 6+ components, 35+ pins.
• aws-efa has both (registry default and an overlay pin), which is what allows divergence.

So the real decision is where the canonical version lives (registry default vs overlay pin vs both), and how the BOM should reflect it.

Options

1. Render the BOM from resolved recipes (per service/accelerator/intent) instead of registry defaults, so it reflects what actually installs. Most correct; changes the BOM generator and likely the doc's shape (a component may render multiple versions across overlays).
2. Consistency guard — a test asserting overlay version pins match the registry defaultVersion unless an explicit exemption is declared. Cheap; prevents unintended divergence, but needs an exemption mechanism for legitimate per-overlay pins.
3. Single source of truth — pick one location per component (registry default OR overlay pin, not both) and lint that the other is absent. Removes the divergence class structurally.

Acceptance

• The BOM cannot silently advertise a version that no recipe installs (either it renders resolved versions, or a check fails when a pin diverges unexpectedly).
• A bump to a component version is reflected in both the BOM and the recipes that install it, or CI fails.

Notes

• Not a regression introduced by chore(recipes): bump aws-efa to v0.5.29, align image tag to appVersion #1418 — pre-existing on main; chore(recipes): bump aws-efa to v0.5.29, align image tag to appVersion #1418 removed the one concrete instance (re-aligned the aws-efa pins) and surfaced the general gap.