diff --git a/.github/workflows/reference-docs.yaml b/.github/workflows/reference-docs.yaml
index af70c9c4d..fe807cce9 100644
--- a/.github/workflows/reference-docs.yaml
+++ b/.github/workflows/reference-docs.yaml
@@ -225,8 +225,20 @@ jobs:
           # underlying types (e.g. `map[string]CELExpression` -> #map[string]celexpression,
           # which never gets a heading), keeping the readable type text.
           sed -i.bak -E 's/_Underlying type:_ _\[(map\[[^]]*\][^]]*)\]\(#[^)]*\)_/_Underlying type:_ _\1_/g' "$TARGET_FILE"
+          # Repoint the PullPolicy link. crd-ref-docs templates a kubernetes.io URL for
+          # every k8s.io type, but PullPolicy is a type alias with no section of its own,
+          # so #pullpolicy-v1-core does not exist and the link lands a reader nowhere.
+          # knownTypes cannot override it (see scripts/crd-ref-docs-config.yaml).
+          sed -i.bak -E 's|https://kubernetes\.io/docs/reference/generated/kubernetes-api/v?[0-9.]+/#pullpolicy-v1-core|https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy|g' "$TARGET_FILE"
           rm -f "$TARGET_FILE.bak"
 
+          # A sed that silently stops matching would quietly reintroduce the broken
+          # anchor, so fail the run instead of opening a PR that carries it.
+          if grep -q '#pullpolicy-v1-core' "$TARGET_FILE"; then
+            echo "Error: PullPolicy anchor rewrite did not match in $TARGET_FILE"
+            exit 1
+          fi
+
           rm "./out.md"
           echo "API docs generated successfully at $TARGET_FILE"
 
diff --git a/scripts/crd-ref-docs-config.yaml b/scripts/crd-ref-docs-config.yaml
index 22d96f082..3e3a43aed 100644
--- a/scripts/crd-ref-docs-config.yaml
+++ b/scripts/crd-ref-docs-config.yaml
@@ -60,5 +60,12 @@ render:
     # knownTypes entry for them is silently ignored. Entries for PullPolicy and
     # metav1.Duration used to live here and never took effect. When a generated
     # kubernetes.io anchor is broken (for example #pullpolicy-v1-core, which is a
-    # type alias with no section of its own), rewrite it in the post-processing
-    # step of .github/workflows/reference-docs.yaml instead.
+    # type alias with no section of its own), add a sed to the post-processing
+    # block in the "Generate API docs" step of .github/workflows/reference-docs.yaml
+    # instead. Do not patch the generated api-*.md files by hand: the next regen
+    # reverts the edit, and the regen runs nightly.
+    #
+    # Reserve those rewrites for links that are genuinely wrong for a reader.
+    # Links that merely redirect (git.k8s.io, for one) belong in the exclude list
+    # in docs-link-checking/lychee.toml, not here: rewriting them pins a URL that
+    # can rot, which is worse than the redirect.