addressing feedback

Signed-off-by: Scott Nichols <[email protected]>

Author: n3wscott

content/master/get-started/get-started-with-mrds.md

@@ -51,13 +51,12 @@ You can edit the default activation policy directly:
 {{< tabs >}}
 {{< tab "Edit Existing Policy" >}}
 ```shell
-# Permanently disable by using a non-matching pattern
-kubectl patch mrap crossplane-default-activation-policy --type='merge' \
-  -p='{"spec":{"activations":["nonexistent.example.com"]}}'
-
-# Or remove all activations entirely
-kubectl patch mrap crossplane-default-activation-policy --type='merge' \
-  -p='{"spec":{"activations":[]}}'
+# Delete the default policy and restart Crossplane using Helm
+kubectl delete mrap crossplane-default-activation-policy
+helm upgrade crossplane crossplane-stable/crossplane \
+  --set provider.defaultActivations=null \
+  --namespace crossplane-system --reuse-values
+kubectl rollout restart deployment/crossplane -n crossplane-system
 ```
 
 {{< hint "note" >}}

content/master/guides/implementing-safestart.md

@@ -19,12 +19,12 @@ Plan for breaking changes and thorough testing before implementing.
 safe-start transforms how your provider handles resource installation:
 
 **Without safe-start:**
-- All managed resources become CRDs when provider installs
+- All resources become MRDs that are automatically active and create CRDs
 - Users get all ~200 AWS resources even if they need only 5
 - Higher memory usage and slower API server responses
 
 **With safe-start:**
-- All managed resources become inactive MRDs when provider installs
+- All resources become MRDs that are inactive by default
 - Users activate only needed resources through policies
 - Lower resource overhead and better performance
 
@@ -51,7 +51,7 @@ metadata:
 spec:
   package: registry.example.com/provider-example:v1.0.0
   capabilities:
-  - name: safe-start
+  - safe-start
 ```
 
 {{< hint "tip" >}}
@@ -148,42 +148,27 @@ func configureConnectionDetails(p *ujconfig.Provider) {
 {{< /tab >}}
 {{< /tabs >}}
 
-### Step 3: Handle namespaced resources
+### Step 3: Update RBAC Permissions
 
-safe-start works best with namespaced managed resources. Update your resources 
-to support both cluster and namespaced scopes:
+safe-start providers need extra permissions to manage CRDs dynamically. Crossplane's RBAC manager automatically provides these permissions when you install safe-start providers.
 
-```go
-// Update resource definitions to support namespacing
-type Database struct {
-    metav1.TypeMeta   `json:",inline"`
-    metav1.ObjectMeta `json:"metadata,omitempty"`
-    
-    Spec   DatabaseSpec   `json:"spec"`
-    Status DatabaseStatus `json:"status,omitempty"`
-}
-
-// Update your CRD generation
-//+kubebuilder:resource:scope=Namespaced
-//+kubebuilder:object:root=true
-//+kubebuilder:subresource:status
-type Database struct {
-    // ... resource definition
-}
+{{< hint "note" >}}
+Manual RBAC configuration is only required if you disable Crossplane's RBAC manager (with `--args=--disable-rbac-manager`).
+{{< /hint >}}
 
-// Optionally create cluster-scoped variants
-//+kubebuilder:resource:scope=Cluster
-//+kubebuilder:object:root=true  
-//+kubebuilder:subresource:status
-type ClusterDatabase struct {
-    // ... same spec but cluster scoped
-}
+**Automatically provided permissions:**
+```yaml
+# Crossplane RBAC manager grants these permissions automatically
+# safe-start permissions
+- apiGroups: ["apiextensions.k8s.io"]
+  resources: ["customresourcedefinitions"]
+  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
+- apiGroups: ["apiextensions.crossplane.io"] 
+  resources: ["managedresourcedefinitions"]
+  verbs: ["get", "list", "watch", "update", "patch"]
 ```
 
-### Step 4: Update RBAC Permissions
-
-safe-start providers need extra permissions to manage CRDs dynamically:
-
+**Manual configuration (only if you disable RBAC manager):**
 ```yaml
 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRole
@@ -207,7 +192,7 @@ rules:
   verbs: ["get", "list", "watch", "update", "patch"]
 ```
 
-### Step 5: Implement managed resource definition controller logic
+### Step 4: Implement managed resource definition controller logic
 
 Add controller logic to handle MRD activation and CRD lifecycle:
 
@@ -280,7 +265,7 @@ func (r *MRDReconciler) createCRD(ctx context.Context, mrd *xpv1alpha1.ManagedRe
 }
 ```
 
-### Step 6: Update build and continuous integration processes
+### Step 5: Update build and continuous integration processes
 
 Update your build process to generate MRDs alongside CRDs:
 
@@ -311,7 +296,7 @@ build-package: generate
 	echo "kind: Provider" >> package/provider.yaml
 	echo "spec:" >> package/provider.yaml
 	echo "  capabilities:" >> package/provider.yaml
-	echo "  - name: safe-start" >> package/provider.yaml
+	echo "  - safe-start" >> package/provider.yaml
 ```
 {{< /tab >}}
 
@@ -378,7 +363,7 @@ jobs:
 {{< /tab >}}
 {{< /tabs >}}
 
-### Step 7: Add connection details documentation
+### Step 6: Add connection details documentation
 
 Document connection details in your MRDs to help users understand resource 
 capabilities:
@@ -496,7 +481,7 @@ metadata:
 spec:
   package: registry.example.com/provider-example:latest
   capabilities:
-  - name: safe-start
+  - safe-start
 EOF
 
 # Wait for provider installation

content/master/guides/mrd-activation-policies.md

@@ -92,16 +92,12 @@ You can change the default activation policy directly and changes persist:
 # View current default policy
 kubectl get mrap crossplane-default-activation-policy -o yaml
 
-# Permanently change to disable default activation
-kubectl patch mrap crossplane-default-activation-policy --type='merge' \
-  -p='{"spec":{"activations":["nonexistent.example.com"]}}'
-
-# Or remove all activations
-kubectl patch mrap crossplane-default-activation-policy --type='merge' \
-  -p='{"spec":{"activations":[]}}'
-
-# Or delete the default policy entirely
+# Delete the default policy and restart Crossplane using Helm
 kubectl delete mrap crossplane-default-activation-policy
+helm upgrade crossplane crossplane-stable/crossplane \
+  --set provider.defaultActivations=null \
+  --namespace crossplane-system --reuse-values
+kubectl rollout restart deployment/crossplane -n crossplane-system
 ```
 
 {{< hint "note" >}}

content/master/managed-resources/managed-resource-definitions.md

@@ -9,7 +9,7 @@ Kubernetes Custom Resource Definitions (CRDs) that enables selective
 installation and better documentation of managed resources.
 
 {{< hint "note" >}}
-MRDs are available in Crossplane v2.0+ as an alpha feature.
+MRDs are available in Crossplane v2.0+ as a beta feature.
 {{< /hint >}}
 
 <!-- vale write-good.Passive = NO -->
@@ -193,7 +193,7 @@ Without safe-start, all MRDs are active by default for backward compatibility.
 # In provider package metadata
 spec:
   capabilities:
-  - name: safe-start
+  - safe-start
 ```
 
 {{< hint "note" >}}

content/master/packages/provider-capabilities.md

@@ -22,8 +22,8 @@ metadata:
   name: provider-aws
 spec:
   capabilities:
-  - name: safe-start
-  - name: CustomCapability
+  - safe-start
+  - CustomCapability
 ```
 
 Crossplane reads these capabilities and modifies its behavior when installing 
@@ -39,19 +39,19 @@ The `safe-start` capability changes how Managed Resource Definitions (MRDs) are
 activated when you install the provider.
 
 **Without safe-start:**
-- All MRDs are automatically activated
-- Crossplane creates all corresponding CRDs when provider installs
+- All resources become MRDs that are automatically active
+- Active MRDs create corresponding CRDs
 - Compatible with legacy providers and existing workflows
 
 **With safe-start:**
-- All MRDs start in `Inactive` state
+- All resources become MRDs that start in `Inactive` state
 - No CRDs until you explicitly activate MRDs
 - Reduces initial resource overhead and improves performance
 
 ```yaml
 spec:
   capabilities:
-  - name: safe-start
+  - safe-start
 ```
 
 {{< hint "tip" >}}
@@ -79,7 +79,7 @@ Don't use safe-start when:
 Crossplane supports flexible matching for capability names:
 
 * **Exact match**: `safe-start`
-* **Case variations**: `safestart`, `safe-start`, `safe-start`
+* **Case variations**: `SafeStart`, `safestart`, `safe-start`
 * **Fuzzy matching**: Handles common spelling variations
 
 This flexibility prevents issues when providers use different naming conventions.
@@ -180,7 +180,7 @@ metadata:
 spec:
   package: registry.example.com/my-provider:v2.0.0
   capabilities:
-  - name: safe-start
+  - safe-start
 ```
 
 ### Managed resource definition generation with connection details
@@ -305,15 +305,6 @@ kubectl get mrap -o wide
 kubectl top nodes
 ```
 
-## Future capabilities
-
-The capability system is extendable. Future capabilities might include:
-
-* **ResourceQuotas** - Automatic resource limit management
-* **NetworkPolicies** - Provider-specific network isolation
-* **CustomValidation** - Enhanced resource validation
-* **TelemetryOpt** - Telemetry and observability features
-
 ## Troubleshooting capabilities
 
 ### Common issues