fix(ci): retry flaky documentation link checks

.github/workflows/docs-link-check.yml

@@ -25,10 +25,11 @@ jobs:
           key: cache-lychee-${{ github.run_id }}
           restore-keys: cache-lychee-
 
-      - name: Check documentation links with lychee
+      - name: Check documentation links with lychee (first attempt)
+        id: lychee
         uses: lycheeverse/lychee-action@v2
         with:
-          args: >-
+          args: &lychee_args >-
             --cache
             --no-progress
             --max-retries 4
@@ -46,6 +47,25 @@ jobs:
             --host-request-interval 1s
             --host-stats
             .
+          # Capture the exit code so the retry step can propagate a second failure.
+          fail: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Clear failed links from cache before retry
+        if: steps.lychee.outputs.exit_code != '0'
+        run: |
+          if [ -f .lycheecache ]; then
+            awk -F',' '$(NF-1) ~ /^(2[0-9][0-9]|403|429)$/ { print }' \
+              .lycheecache > .lycheecache.tmp
+            mv .lycheecache.tmp .lycheecache
+          fi
+
+      - name: Retry documentation links with lychee
+        if: steps.lychee.outputs.exit_code != '0'
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: *lychee_args
           fail: true
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -54,13 +74,14 @@ jobs:
         if: always() && github.ref == 'refs/heads/main'
         run: |
           if [ -f .lycheecache ]; then
-            grep -E ',2[0-9]{2},' .lycheecache > .lycheecache.tmp || true
+            awk -F',' '$(NF-1) ~ /^(2[0-9][0-9]|403|429)$/ { print }' \
+              .lycheecache > .lycheecache.tmp
             cutoff=$(( $(date +%s) - 93600 ))
-            stale=$(awk -F',' -v c="$cutoff" '$3 < c' .lycheecache.tmp)
+            stale=$(awk -F',' -v c="$cutoff" '$NF < c' .lycheecache.tmp)
             if [ -n "$stale" ]; then
               echo "Removing stale cache entries (>26h old):"
               echo "$stale"
-              awk -F',' -v c="$cutoff" '$3 >= c' .lycheecache.tmp > .lycheecache.tmp2 || true
+              awk -F',' -v c="$cutoff" '$NF >= c' .lycheecache.tmp > .lycheecache.tmp2 || true
               mv .lycheecache.tmp2 .lycheecache.tmp
             fi
             mv .lycheecache.tmp .lycheecache