Refresh-refcache PR fix

Follow these steps to resolve non-2XX static/refcache.json entries in the otelbot/refcache-refresh PR. This process may involve updating or removing dead links on the site, then refreshing the refcache again until no non-2XX entries remain.

Preparation

These steps assume you have a local clone of the repository with the upstream remote configured to point to the main repository. Run these steps locally from the repository root.

1. Determine the PR associated with upstream otelbot/refcache-refresh.

2. If none exists, stop.

3. If a local otelbot/refcache-refresh branch already exists and contains commits that are not in upstream/otelbot/refcache-refresh, back them up or stop before resetting anything.

4. Check out the PR branch with gh pr checkout <num>. If that fails because the local branch has diverged and you have already backed up any local-only commits, realign it with upstream:

   git fetch upstream
   git checkout otelbot/refcache-refresh
   git reset --hard upstream/otelbot/refcache-refresh
   

5. If any content modules are out of date, run npm run get:submodule.

Resolve non-2XX entries

1. Run ./scripts/double-check-refcache-4XX.mjs to retry transient 4XX failures and update static/refcache.json.

2. Scan static/refcache.json for remaining non-2XX statuses.

3. If none remain, commit and push any changed files (only static/refcache.json should have changed) to upstream/otelbot/refcache-refresh, then stop.

4. List remaining non-2XX URLs and their statuses:

   jq -r 'to_entries[] | select(.value.StatusCode < 200 or .value.StatusCode >= 300) | "\(.key) \(.value.StatusCode)"' \
     static/refcache.json
   

5. For each remaining status, fix or remove the source link that produced it:

   • For a 404, identify the site pages that refer to the dead URL and update or remove that link.
   • For any other non-2XX status, inspect it manually and update or remove the source link as needed before continuing.

6. Run npm run fix:refcache to refresh static/refcache.json after those source-link changes, then repeat the steps in this section until no non-2XX statuses remain.