Clarify missing firmware result for bootflash check

AGENTS.md

@@ -12,3 +12,24 @@ cx-skills install ACI-PUV-Developers/aci-integration-tests --dir <temporary-dire
 
 Read the installed `SKILL.md` before acting. Refresh it at the start of each
 integration-test task, and never commit the downloaded skill files here.
+
+## Test scope
+
+Automated tests must cover only data, logic, and `RESULT` values. Do not add or
+update tests for user-facing wording, messages, recommended actions,
+documentation prose, punctuation, capitalization, or other presentation text.
+For wording-only changes, run the existing relevant tests without creating or
+modifying test coverage for the wording.
+
+## Manual result messaging
+
+For a `MANUAL` result, populate `msg` only as a short heads-up when neither
+`data` nor `recommended_action` is provided. When a result includes data or
+needs explanation or remediation guidance, leave `msg` empty and put the full
+explanation and action in `recommended_action`.
+
+## Documentation links
+
+Never put link destinations directly in documentation prose. Use the
+document's existing numbered reference-link system, adding the next appropriate
+reference definition when a new destination is needed.

aci-preupgrade-validation-script.py

@@ -2355,8 +2355,11 @@ def missing_images(image_rows):
             headers=["Image Role", "Architecture", "Filename", "Status"],
             data=[row + ["Missing"] for row in image_rows],
             recommended_action=(
-                "Make the listed images available in the Firmware Repository, "
-                "then rerun this check."
+                "Bootflash capacity was not evaluated because image size information "
+                "is unavailable for the listed switch firmware. "
+                "Upload or restore each listed switch image in the APIC Firmware Repository. "
+                "For ACI 6.0(2)+ targets, both 32-bit and 64-bit (-cs_64) switch images "
+                "are required. Wait for repository synchronization, then rerun this check."
             ),
             doc_url=doc_url,
         )

docs/docs/validations.md

@@ -694,6 +694,8 @@ The ACI Pre-Upgrade Validation script uses APIC API data to compare each switch'
 
 The calculation generally reserves twice the applicable target image size. This accounts for space used by the downloaded image and additional space needed while the image is extracted. For an upgrade that crosses the 6.0(2) image boundary, the calculation accounts for both the 32-bit and 64-bit target images and the space recovered when the current image is removed.
 
+The calculation requires size information for every listed current or target switch image. For 6.0(2)+ targets, both the 32-bit and 64-bit (`-cs_64`) images must be in the APIC Firmware Repository; see [6.0(2)+ requires 32 and 64 bit switch images][g16]. If an image is missing, the check requires manual review because `/bootflash` capacity was not evaluated, not because insufficient space was detected.
+
 Switches that have already downloaded the target image are still checked because image extraction and later upgrade stages can require additional space. Because the downloaded image is already reflected in the switch's available-space value, the check evaluates only the remaining space required to complete the upgrade.
 
 If a switch does not have enough available space, the check reports an upgrade failure and displays the available and required space. Remove old, unused switch images to recover space, then run the validation again. Contact Cisco TAC if sufficient space cannot be recovered. If the current switch version, target firmware image, or `/bootflash` information is unavailable, the check reports that a manual review is required.

tests/checks/test_result_details.py

@@ -116,7 +116,7 @@ def communicate(self):
     ('6.0(3a)', '6.0(2h)', [IMAGE_64], [['Target', '32-bit', IMAGE_32, 'Missing']]),
     ('5.2(8h)', '6.0(2h)', [IMAGE_32, IMAGE_64], [['Current', '32-bit', OLD_IMAGE, 'Missing']]),
 ])
-def test_missing_images_are_results_with_repository_action(monkeypatch, current, target, available, missing):
+def test_missing_images_are_structured_manual_results(monkeypatch, current, target, available, missing):
     def icurl(_, query):
         if query.startswith('eqptcapacityFSPartition.'):
             return [{'eqptcapacityFSPartition': {'attributes': {
@@ -131,8 +131,4 @@ def icurl(_, query):
     name = 'switch_bootflash_usage_check'
     result = run_check(name, sw_cversion=script.AciVersion(current), tversion=script.AciVersion(target))
     assert result.result == script.MANUAL
-    assert result.msg == ''
-    assert result.headers == ['Image Role', 'Architecture', 'Filename', 'Status']
     assert result.data == missing
-    assert result.recommended_action
-    assert_outputs(monkeypatch, name, result, missing[0][2])