Feature/optimize image integrity: Adds automated orphaned image cleanup

.github/skills/audit-images/SKILL.md

@@ -66,6 +66,45 @@ Use path/guide-level review to:
 6. After the reviewer accepts suggestions, rewrite text, then re-run the audit on the same scope.
 7. Report before/after counts, files changed, and any remaining issues.
 
+## Orphan and reference-integrity workflow
+
+Use `scripts/orphan_images.py` when the task concerns unreferenced image files,
+broken local image paths, filename case mismatches, or malformed Markdown image
+destinations. This is separate from the alt-text audit so existing editorial
+findings do not block image-integrity checks.
+
+1. Run the checker in report mode before deleting anything.
+2. When reference repairs are needed, run
+   `scripts/orphan_images.py --fix-references` separately because it changes
+   Learning Path Markdown. Review those changes and any ambiguous references
+   instead of guessing.
+3. Run every full audit with a Hugo render passed to `--generated-site`. The
+   checker always combines tracked source references, rendered references,
+   exact Git blob matches, and unresolved-reference proximity before cleanup.
+4. Inspect every candidate in the report. Handle `requires review` candidates
+   manually outside the checker.
+5. Use the workflow's **Create cleanup PR** option to propose blob-verified
+   deletions for `safe-deletion candidate` paths.
+6. Review every proposed deletion before merging. The classification is audit
+   evidence, not a semantic decision. The workflow rebuilds Hugo and verifies
+   the staged deletion set automatically.
+
+Case-colliding duplicate paths are removed from the Git index without deleting
+the shared worktree file on case-insensitive systems. GitHub Actions never
+writes deletions directly to the default branch. The Orphaned images cleanup
+workflow performs one full, Hugo-rendered audit at 09:00 UTC on March 1
+and September 1 and creates or updates a bot-owned cleanup PR when safe
+candidates exist. Scheduled runs are restricted to the canonical Arm
+repository; forks can still start manual runs. The workflow rebuilds Hugo and
+verifies the staged deletion set before pushing that proposal branch. It writes
+Markdown and JSON from one audit pass, then applies only manifest paths whose
+Git blob IDs still match the audited snapshot. The PR is never auto-merged, and
+`requires review` images remain untouched.
+
+Markdown is the default human-readable report format and provides clickable
+GitHub source links. JSON is the machine-readable cleanup manifest used by the
+workflow; the checker does not maintain a duplicate plain-text report.
+
 ## Validation rules
 
 - Treat the script as a detector, not the final authority. It flags likely problems for review.
@@ -100,3 +139,57 @@ Write JSON for tracking:
 ```bash
 python3 .github/skills/audit-images/scripts/audit_images.py --format json --output image-audit.json
 ```
+
+Report image-integrity problems without changing files:
+
+```bash
+python3 .github/skills/audit-images/scripts/orphan_images.py
+```
+
+Fail when any current problems exist:
+
+```bash
+python3 .github/skills/audit-images/scripts/orphan_images.py --check
+```
+
+Apply deterministic reference repairs in bulk:
+
+```bash
+python3 .github/skills/audit-images/scripts/orphan_images.py --fix-references
+```
+
+Build the site and classify candidates with independent rendered evidence:
+
+```bash
+hugo --destination /tmp/arm-learning-paths-image-integrity
+python3 .github/skills/audit-images/scripts/orphan_images.py \
+  --generated-site /tmp/arm-learning-paths-image-integrity
+```
+
+Use the **Orphaned images cleanup** workflow's **Run workflow** control to start
+the same full Hugo-backed audit without waiting for the six-month schedule.
+Select **Create cleanup PR** to propose verified safe-deletion candidates, or leave it
+clear for a report-only run. Scheduled canonical-repository runs automatically
+create or update the proposal. Pushes and pull requests do not trigger this
+workflow.
+The repository's Actions settings must grant the workflow token read/write
+access and allow GitHub Actions to create pull requests. If those permissions
+are disabled, the audit report still completes before the proposal step fails.
+
+Every workflow report lists both `requires review` and `safe-deletion candidate`
+groups for manual inspection. Records contain the image path, a high-level
+category, and any related source file and line; they do not attempt to infer the
+author's intent. Review every candidate during the initial cleanup and each
+six-month report. The full audit uses both source references and the rendered
+Hugo site to avoid treating images used by published pages as deletion candidates.
+The cleanup PR contains deletion-only content changes, links every proposed
+deletion at the audited commit, and links the protected review group. Before
+opening the PR, the workflow requires the staged deletions to exactly match the
+JSON dry-run manifest, rebuilds the complete site, and rejects any newly
+introduced non-orphan problem. Rendered-site scans skip copied raster images
+before reading file contents while retaining text-based SVG reference checks.
+
+Do not delete reported candidates directly through the checker. Fix protected
+`requires review` cases manually, and use the workflow-generated cleanup PR for
+safe-deletion candidates. The workflow applies the `safe_delete_images` list,
+verifies the manifest and rebuilt site, and leaves the proposal for human review.

.github/skills/audit-images/references/image-guidance.md

@@ -91,3 +91,9 @@ Preferred example:
 - Keep the repository-specific `#center` syntax when fixing alt text
 - Do not remove valid alignment syntax during cleanup
 - For bulk cleanup, update the guidance first, then fix content by category or directory in manageable batches
+- Repair malformed, missing, and case-mismatched references before classifying files as orphaned
+- Combine tracked source references with rendered Hugo output in every full audit before deleting unique files
+- Review every candidate; fix `requires review` cases manually and use the workflow to propose `safe-deletion candidate` paths in a reviewable PR
+- Run `orphan_images.py --fix-references` separately because it changes Markdown; review those repairs, rerun the full audit, and leave ambiguous matches for manual review
+- Run the full Hugo-backed audit on the workflow schedule (currently March and September at 09:00 UTC), or start it manually when an up-to-date report is needed
+- Put automated deletions on a bot-owned branch, rebuild and verify the site, and require human review through a non-auto-merged PR