docs(aim-catalog): describe shipped catalog behaviour, not pending work

[Q-Dub]

Summary

Follow-up to #831. That PR aligned the AIM catalog docs with the in-tree chart
templates, but left in place several statements that describe behaviour from
work still in flight (EAI-8054,
EAI-8192) rather than what a
main install actually does today. This corrects them.

1. AIM_HARDWARE_FAMILY auto-detection is not shipped

docs/aim_model_management.md and the chart README claimed the family is
"auto-detected when omitted", and that "a typical new cluster-bloom install
injects a non-empty list, so it uses profiles".

On cluster-bloom main the setting has default: ""
(pkg/config/bloom.yaml.schema.yaml) and is injected only
when: AIM_HARDWARE_FAMILY | default('') | length > 0
(bootstrap_gitea.yaml). So an install that leaves it unset injects nothing,
the chart default [] applies, and the cluster gets the unfiltered
catalog — the opposite of what the docs said.

Auto-detection is silogen/cluster-bloom#298, still open. Documented the
current behaviour instead.

2. Source of truth described a publish pipeline that does not exist

The doc said the AIM team's lists "are published into the
aim-cluster-model-source Helm chart for clusters to consume" and linked
github.com/amd-enterprise-ai/aim-build as a public repo (it is not
reachable; the real repo is private).

Today the chart templates are a hand-copied point-in-time snapshot.
Generating them from .releases is
EAI-8192 (Backlog), and
silogen/aim-build#1487 states in its own description that "Catalog YAML is
still a hand-copied snapshot". Reworded to say so, and added the
helm template one-liner operators can use to read the catalog a release
will install.

3. Smaller corrections

• aim-cluster-model-source-additional is not shipped in Cluster Forge at
  all; noted that it needs one-time operator setup before the
  cluster-managed path works.
• Removed the speculative "when ROCm ships multi-hardware base images…"
  sentence and replaced it with the actual per-family base split, including
  the unfiltered exception.
• root/values.yaml still said Empty = legacy after the
  legacy.yaml → unfiltered.yaml rename in docs: align AIM catalog lifecycle with in-tree chart templates #831.

Verification

Rendered both branches against the chart in this tree:

$ helm template aim-cluster-model-source sources/aim-cluster-model-source \
    --set-json 'hardwareFamilies=["instinct"]' | grep -E '^  name:'
  name: aim-base-models
  name: amd-aim-release-0.8.5
  name: amd-aim-release-0.9.0
  name: amd-aim-release-0.10.0
  name: amd-aim-release-0.11.0
  name: amd-aim-instinct-0.11.1
  name: amd-aim-instinct-0.12.0
  name: amd-aim-instinct-0.13.0

$ helm template aim-cluster-model-source sources/aim-cluster-model-source \
    | grep -E '^  name:'
  name: aim-base-models
  name: amd-aim-instinct-0.11.1
  name: amd-aim-instinct-0.12.0
  name: amd-aim-instinct-0.13.0

The second invocation confirms the corrected claim: no families set means
unfiltered, not profiles.

Also confirmed apps.aim-cluster-model-source in root/values.yaml is still
path: aim-cluster-model-source (in-tree chart, not an OCI pointer), so the
docs correctly continue to describe in-tree packaging.

Test plan

• Docs render correctly on GitHub; all intra-page anchors resolve
  (#one-time-setup, #add-a-model, #replace-or-remove-a-source,
  #before-a-platform-upgrade, #cluster-managed-catalog-additions)
• Confirm with AIM team that the catalog lists are hand-copied at release
  time (no automated feed) as described
• Revisit after feat(cli): auto-detect AIM_HARDWARE_FAMILY and gate incompatible catalogs with human confirmation cluster-bloom#298 merges to reinstate the
  auto-detection description

Made with Cursor