[no-ci] ci: clarify Lychee cache misses and manual refreshes

.github/actions/lychee-links/action.yml

@@ -84,6 +84,7 @@ runs:
         echo "key=${prefix}${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" >> "${GITHUB_OUTPUT}"
 
     - name: Restore successful link checks
+      id: cache-restore
       # Refresh mode deliberately skips earlier URL results.
       if: ${{ inputs.refresh != 'true' }}
       uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v6.1.0
@@ -93,6 +94,25 @@ runs:
         restore-keys: ${{ steps.cache.outputs.prefix }}
         enableCrossOsArchive: true
 
+    - name: Explain a missing shared Lychee cache
+      # Prefix restores are normal; cache-hit only identifies exact key matches.
+      if: ${{ inputs.refresh != 'true' && steps.cache-restore.outputs.cache-matched-key == '' }}
+      shell: bash --noprofile --norc -euo pipefail {0}
+      env:
+        KIND: ${{ inputs.kind }}
+        DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        WORKFLOW_URL: ${{ github.server_url }}/${{ github.repository }}/actions/workflows/lychee.yml
+      run: |
+        message="No shared Lychee ${KIND} cache was restored for this checker configuration. Checking links without this baseline may take longer and make more network requests."
+        context="This is expected after checker changes in a PR; a refresh on ${DEFAULT_BRANCH} cannot seed settings that exist only in a PR."
+        hint="For an unexpected miss on ${DEFAULT_BRANCH}, maintainers can run CI: Lychee checks and caches (lychee.yml) on ${DEFAULT_BRANCH} with refresh-cache enabled."
+        echo "::notice title=Lychee ${KIND} cache::${message} ${context} ${hint} ${WORKFLOW_URL}"
+        {
+          printf '### Lychee %s cache\n\n' "$KIND"
+          printf '%s\n\n%s\n\n%s\n\n' "$message" "$context" "$hint"
+          printf '[Open the cache refresh workflow](%s).\n' "$WORKFLOW_URL"
+        } >> "$GITHUB_STEP_SUMMARY"
+
     - name: Check links through the configured pre-commit hook
       shell: bash --noprofile --norc -euo pipefail {0}
       env:
@@ -107,7 +127,7 @@ runs:
           --report "${RUNNER_TEMP}/lychee-reports/lychee-${KIND}.json"
 
     - name: Publish fresh successful link checks
-      # Only nightly refreshes publish, so every pull request restores the same
+      # Only refresh runs publish, so every pull request restores the same
       # baseline. Saving keeps original timestamps and never caches failures.
       if: ${{ !cancelled() && inputs.refresh == 'true' }}
       uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v6.1.0

.github/workflows/lychee.yml

@@ -4,10 +4,10 @@
 
 # Warm authored and rendered link caches through the configured pre-commit
 # hooks. Ordinary PRs reuse authored results; full docs CI reuses rendered
-# results. Nightly starts afresh, reports unresolved links as warnings, and is
-# the only producer of both shared baselines.
+# results. Nightly and manual dispatches with refresh-cache=true start afresh,
+# report unresolved links as warnings, and can produce both shared baselines.
 
-name: "CI: Documentation links"
+name: "CI: Lychee checks and caches"
 
 on:
   workflow_call:

ci/README.md

@@ -88,9 +88,9 @@ existing allowance for at most ten distinct HTTP 429 URLs.
 
 ### Shared URL Caches
 
-Nightly is the only producer. It skips restoring, checks afresh, and publishes
-successful results; every other job restores the newest baseline and never
-publishes. Failed URLs and filesystem targets are never cached. Successes keep
+Nightly and manual refreshes skip restoring, check afresh, and publish
+successful results; ordinary checks restore the newest baseline and never
+publish. Failed URLs and filesystem targets are never cached. Successes keep
 their original timestamps and expire after three days, so a missed nightly
 refresh does not break reuse, but a link that breaks after a nightly success
 can stay unnoticed for up to 72 hours.
@@ -104,6 +104,21 @@ fragments and Lychee's cache does not record which validation ran. URL results
 are shared across operating systems; pre-commit's installed environments keep
 their OS- and Python-specific caches.
 
+#### Refreshing Shared Caches
+
+To rebuild both shared caches manually, open
+[CI: Lychee checks and caches](https://github.com/NVIDIA/cuda-python/actions/workflows/lychee.yml)
+(`.github/workflows/lychee.yml`), select the default branch, and enable
+`refresh-cache` before choosing **Run workflow**. This runs the cache refresh
+without the rest of nightly CI.
+
+Checks that restore no matching baseline add a notice and a job-summary hint.
+They still check links, with potentially more runtime and network traffic.
+Checker changes in a PR intentionally start with a cold cache; refreshing the
+default branch cannot seed a cache for settings that exist only in that PR.
+Refreshing rebuilds cached successes; broken links and upstream rate limits
+still need their usual investigation.
+
 ### Repository Links
 
 Documentation can link to a path added or moved in the same PR using its