Summary

Closes the second half of #741 (1b — content/prose). The first half landed via #763 (tooling, deterministic output, scheduled refresh); this PR adds the explanation around the auto-generated table that customers need to interpret it.

Refs #739, #741. Filed alongside as a follow-up: #765 (gpu-operator BOM extracts a bare vgpu-manager ref — surfaced by publishing the doc, scoped out of this PR).

Type of Change

• Documentation update

Component(s) Affected

• Docs (docs/user/container-images.md)
• Build/tooling (Makefile — bom-docs splice logic)
• Core libraries (pkg/bom — NoTitle flag)

Implementation Notes

Doc structure. docs/user/container-images.md is now wrapped:

[hand-written intro: page purpose, refresh cadence, JSON companion]

<!-- BEGIN AICR-BOM -->
[auto-generated body: summary, components table, per-component image lists]
<!-- END AICR-BOM -->

[hand-written outro: explicit-vs-implicit, registry rationale,
 reproducibility caveat, regeneration instructions, related links]

make bom-docs splices instead of overwriting. The target now:

1. Requires the doc and its markers to exist (errors clearly otherwise).
2. Runs the BOM tool with -no-title to a temp dir.
3. Uses awk to replace content between <!-- BEGIN AICR-BOM --> and <!-- END AICR-BOM --> with the fresh body, preserving everything outside.

Verified idempotent: two consecutive make bom-docs runs produce identical md5.

pkg/bom API addition. Metadata.NoTitle bool opt-in flag (off by default) that suppresses the H1 line so the body can be embedded as a section of a larger document. The same pattern will be useful for the planned per-bundle SBOM in pkg/bundler (#750).

Numbering note. I'd drifted from the actual issue numbering in earlier work; cross-references in this PR's commit message, the doc itself, and the freshly-corrected #739 epic body now consistently use:

Testing

unset GITLAB_TOKEN && make qualify
# Codebase qualification completed

Idempotency check:

$ md5sum docs/user/container-images.md
c937c78eb0966f884b8f127a6287c826  docs/user/container-images.md

$ make bom-docs
Updated docs/user/container-images.md (prose preserved, auto-generated section refreshed)

$ md5sum docs/user/container-images.md
c937c78eb0966f884b8f127a6287c826  docs/user/container-images.md

pkg/bom coverage held with new TestWriteMarkdown_NoTitleSuppressesH1.

Risk Assessment

• Low — Doc-only change for the prose; new NoTitle flag is opt-in and defaults off (no behavior change for existing callers); make bom-docs is now safer (errors on missing markers instead of clobbering prose). Easy to revert.

Rollout notes: Future contributors who edit recipes need to run make bom-docs to refresh the auto-generated section; the splice preserves their prose untouched. The weekly refresh action keeps the same behavior.

Checklist

• Tests pass locally (make test with -race)
• Linter passes (make lint)
• I did not skip/disable tests to make CI green
• I added/updated tests for new functionality
• I updated docs if user-facing behavior changed (the doc page itself is what's changing)
• Changes follow existing patterns in the codebase
• Commits are cryptographically signed (git commit -S)