diff --git a/codebundles/gcp-bucket-crossplane-health/.runwhen/generation-rules/gcp-bucket-crossplane-health.yaml b/codebundles/gcp-bucket-crossplane-health/.runwhen/generation-rules/gcp-bucket-crossplane-health.yaml
index efb135a..4b4b1e0 100644
--- a/codebundles/gcp-bucket-crossplane-health/.runwhen/generation-rules/gcp-bucket-crossplane-health.yaml
+++ b/codebundles/gcp-bucket-crossplane-health/.runwhen/generation-rules/gcp-bucket-crossplane-health.yaml
@@ -4,12 +4,15 @@ spec:
   platform: kubernetes
   generationRules:
     # Discover every Crossplane GCP Bucket in the cluster.
-    # Resource type syntax: plural.group/version
+    # Resource type syntax: plural.group[/version]
     #   plural  = buckets            (from `kubectl api-resources | grep storage.gcp.upbound.io`)
     #   group   = storage.gcp.upbound.io
-    #   version = v1beta1            (omit /version to use the API server's preferred version)
+    #   version = omitted            (use the API server's preferred version — currently v1beta2)
+    #
+    # Pin an explicit version like `buckets.storage.gcp.upbound.io/v1beta1`
+    # if you need schema stability across CRD upgrades.
     - resourceTypes:
-        - buckets.storage.gcp.upbound.io/v1beta1
+        - buckets.storage.gcp.upbound.io
       matchRules:
         # Match every Bucket by name. Swap this regex to scope by naming
         # convention (for example `^prod-.*` to only cover prod buckets) or
diff --git a/docs/03-crossplane-crd-discovery.md b/docs/03-crossplane-crd-discovery.md
index 80be1ed..0fab275 100644
--- a/docs/03-crossplane-crd-discovery.md
+++ b/docs/03-crossplane-crd-discovery.md
@@ -24,12 +24,18 @@ Three things to note:
 
 1. **`buckets`** — this is the *plural resource name*. It is what you
    put in the generation rule, not the singular `Bucket`.
-2. **`storage.gcp.upbound.io/v1beta1`** — the API group and preferred
-   version.
+2. **`storage.gcp.upbound.io/v1beta2`** — the API group and preferred
+   version (older `v1beta1` may also be served for compatibility).
 3. **`false` in the "NAMESPACED" column** — Crossplane managed resources
    are **cluster-scoped**. This is why our generation rule uses
    `qualifiers: ["resource", "cluster"]` and not `namespace`.
 
+> **Version pinning:** our rule uses just `buckets.storage.gcp.upbound.io`
+> (no `/version`), which tells the indexer to use whatever the API server
+> reports as preferred. That's the most resilient choice across CRD
+> upgrades. Pin `/v1beta1` or `/v1beta2` only when you deliberately need
+> a specific schema.
+
 Screenshot placeholder: `images/03-kubectl-api-resources.png` — output of
 the above command.
 
diff --git a/docs/04-generation-rule-walkthrough.md b/docs/04-generation-rule-walkthrough.md
index f673e7e..689cd9b 100644
--- a/docs/04-generation-rule-walkthrough.md
+++ b/docs/04-generation-rule-walkthrough.md
@@ -14,7 +14,7 @@ spec:
   platform: kubernetes
   generationRules:
     - resourceTypes:
-        - buckets.storage.gcp.upbound.io/v1beta1
+        - buckets.storage.gcp.upbound.io
       matchRules:
         - type: pattern
           pattern: ".+"
@@ -53,9 +53,13 @@ spec:
 
 ```yaml
 resourceTypes:
-  - buckets.storage.gcp.upbound.io/v1beta1
+  - buckets.storage.gcp.upbound.io
 ```
 
+Omitting `/v1beta2` (or `/v1beta1`) tells the indexer to use the API
+server's preferred version, which survives CRD schema upgrades. Pin the
+version only when you rely on a specific schema shape.
+
 This is the *selective discovery* signal. Because this string appears in
 a loaded rule, the Kubernetes indexer knows to enumerate that CRD.
 Without any rule mentioning a CRD, it would not be listed.