Feature/optimize image integrity: Adds automated orphaned image cleanup

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

@@ -66,6 +66,38 @@ 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. Run `scripts/orphan_images.py --fix-references` to repair deterministic
+   malformed, missing, and case-mismatched references. Review any ambiguous
+   references that remain instead of guessing.
+3. Render the site with Hugo and pass the output to `--generated-site`. The
+   checker combines tracked source references, rendered references, exact Git
+   blob matches, and unresolved-reference proximity to classify candidates.
+4. Run `--delete-safe` to remove only high-confidence candidates. Without a
+   rendered site, only byte-identical duplicates of referenced images qualify.
+5. Review only the smaller `needs review` group. Do not maintain a repository-wide
+   keep-list for historical candidates.
+6. Re-run the checker and Hugo build after cleanup.
+
+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 January 1,
+May 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
+`needs review` images remain untouched.
+
 ## Validation rules
 
 - Treat the script as a detector, not the final authority. It flags likely problems for review.
@@ -100,3 +132,75 @@ 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
+```
+
+Delete only candidates supported by the available confidence evidence:
+
+```bash
+python3 .github/skills/audit-images/scripts/orphan_images.py \
+  --generated-site /tmp/arm-learning-paths-image-integrity \
+  --delete-safe
+```
+
+Use the **Orphaned images cleanup** workflow's **Run workflow** control to start
+the same full Hugo-backed audit without waiting for the four-month schedule.
+Select **Create cleanup PR** to propose verified safe deletions, 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 the actionable `needs review` group even when those
+images are historical. Markdown reports link each protected image and related
+source line, explain why automatic deletion was blocked, and recommend the next
+review action. The full audit uses both source references and the rendered Hugo
+site to avoid treating images used by published pages as safe to delete.
+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.
+
+For a manual Git cleanup, build Hugo first and let the checker stage only the
+safe deletion set:
+
+```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 \
+  --delete-safe
+git diff --cached --name-status
+git diff --cached --stat
+```
+
+Review the staged deletion list before committing. The automated workflow uses
+the same `safe_delete_images` list and adds the post-deletion verification and
+pull-request boundary.

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

@@ -91,3 +91,10 @@ 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 before deleting unique files
+- Automatically delete only candidates classified as safe; review the smaller ambiguous group
+- Use `orphan_images.py --fix-references` for deterministic bulk repairs; leave ambiguous matches for review
+- Use `orphan_images.py --delete-safe` to remove only confidence-qualified candidates
+- Run the full Hugo-backed audit weekly, 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