operator-framework
diff --git a/Makefile b/Makefile
@@ -685,6 +685,10 @@ crd-ref-docs: $(CRD_REF_DOCS) #EXHELP Generate the API Reference Documents.
 	$(CRD_REF_DOCS) --source-path=$(ROOT_DIR)/api/ \
 	--config=$(API_REFERENCE_DIR)/crd-ref-docs-gen-config.yaml \
 	--renderer=markdown --output-path=$(API_REFERENCE_DIR)/$(API_REFERENCE_FILENAME);
+	# crd-ref-docs renders doc-comment text verbatim, including internal <opcon:...> generator
+	# directives; strip them from the published reference (the per-channel contracts remain in prose).
+	sed -E 's#</?opcon:[^>]*>##g' $(API_REFERENCE_DIR)/$(API_REFERENCE_FILENAME) > $(API_REFERENCE_DIR)/$(API_REFERENCE_FILENAME).tmp
+	mv $(API_REFERENCE_DIR)/$(API_REFERENCE_FILENAME).tmp $(API_REFERENCE_DIR)/$(API_REFERENCE_FILENAME)
 
 VENVDIR := $(abspath docs/.venv)
 

diff --git a/api/v1/clusterextension_types.go b/api/v1/clusterextension_types.go
@@ -49,6 +49,7 @@ const (
 
 // ClusterExtensionSpec defines the desired state of ClusterExtension
 type ClusterExtensionSpec struct {
+	// <opcon:standard:description>
 	// namespace specifies a Kubernetes namespace.
 	// It designates the default namespace where namespace-scoped resources for the extension are applied to the cluster.
 	// Some extensions may contain namespace-scoped resources to be applied in other namespaces.
@@ -59,10 +60,31 @@ type ClusterExtensionSpec struct {
 	// and be no longer than 63 characters.
 	//
 	// [RFC 1123]: https://tools.ietf.org/html/rfc1123
+	// </opcon:standard:description>
+	// <opcon:experimental:description>
+	// namespace selects the namespace that namespace-scoped resources for the extension
+	// are applied to.
+	//
+	// namespace is optional. When set, it must reference an existing namespace on the cluster.
+	// When omitted, operator-controller resolves and creates a managed namespace from the
+	// bundle's metadata. Whether namespace is set or omitted is fixed at creation time and
+	// cannot be changed afterwards.
+	//
+	// The namespace field follows the DNS label standard as defined in [RFC 1123].
+	// It must contain only lowercase alphanumeric characters or hyphens (-), start and end with an alphanumeric character,
+	// and be no longer than 63 characters.
+	//
+	// [RFC 1123]: https://tools.ietf.org/html/rfc1123
+	// </opcon:experimental:description>
+	//
+	// <opcon:standard:validation:XValidation:rule="self == oldSelf",message="namespace is immutable">
+	// <opcon:standard:validation:XValidation:rule="self.matches("^[a-z0-9]([-a-z0-9]*[a-z0-9])?$")",message="namespace must be a valid DNS1123 label">
+	// <opcon:experimental:validation:XValidation:rule="self == '' || self.matches("^[a-z0-9]([-a-z0-9]*[a-z0-9])?$")",message="namespace must be a valid DNS1123 label">
+	// <opcon:experimental:validation:XValidation:rule="oldSelf == '' || self == oldSelf",message="namespace is immutable once set">
+	// <opcon:experimental:validation:XValidation:rule="oldSelf != '' || self == ''",message="namespace cannot be set after creation; mode is locked at creation time">
+	// <opcon:experimental:validation:Optional>
 	//
 	// +kubebuilder:validation:MaxLength:=63
-	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="namespace is immutable"
-	// +kubebuilder:validation:XValidation:rule="self.matches(\"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$\")",message="namespace must be a valid DNS1123 label"
 	// +required
 	Namespace string `json:"namespace"`
 
@@ -586,6 +608,8 @@ type ClusterExtension struct {
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
 	// spec is an optional field that defines the desired state of the ClusterExtension.
+	//
+	// <opcon:experimental:validation:XValidation:rule="has(oldSelf.namespace) == has(self.namespace)",message="namespace presence is immutable; it cannot be added or removed after creation">
 	// +optional
 	Spec ClusterExtensionSpec `json:"spec,omitempty"`
 

diff --git a/applyconfigurations/api/v1/clusterextension.go b/applyconfigurations/api/v1/clusterextension.go
diff --git a/applyconfigurations/api/v1/clusterextensionspec.go b/applyconfigurations/api/v1/clusterextensionspec.go
diff --git a/applyconfigurations/api/v1/clusterextensionstatus.go b/applyconfigurations/api/v1/clusterextensionstatus.go
diff --git a/cmd/operator-controller/main.go b/cmd/operator-controller/main.go
@@ -502,11 +502,12 @@ func run() error {
 
 	certProvider := getCertificateProvider()
 	regv1ManifestProvider := &applier.RegistryV1ManifestProvider{
-		BundleRenderer:              registryv1.Renderer,
-		CertificateProvider:         certProvider,
-		IsWebhookSupportEnabled:     certProvider != nil,
-		IsSingleOwnNamespaceEnabled: features.OperatorControllerFeatureGate.Enabled(features.SingleOwnNamespaceInstallSupport),
-		IsDeploymentConfigEnabled:   features.OperatorControllerFeatureGate.Enabled(features.DeploymentConfig),
+		BundleRenderer:               registryv1.Renderer,
+		CertificateProvider:          certProvider,
+		IsWebhookSupportEnabled:      certProvider != nil,
+		IsSingleOwnNamespaceEnabled:  features.OperatorControllerFeatureGate.Enabled(features.SingleOwnNamespaceInstallSupport),
+		IsDeploymentConfigEnabled:    features.OperatorControllerFeatureGate.Enabled(features.DeploymentConfig),
+		IsNamespaceManagementEnabled: features.OperatorControllerFeatureGate.Enabled(features.BoxcutterRuntime),
 	}
 	var cerCfg reconcilerConfigurator
 	if features.OperatorControllerFeatureGate.Enabled(features.BoxcutterRuntime) {
@@ -659,6 +660,7 @@ func (c *boxcutterReconcilerConfigurator) Configure(ceReconciler *controllers.Cl
 		controllers.RetrieveRevisionStates(revisionStatesGetter),
 		controllers.ResolveBundle(c.resolver, c.mgr.GetClient()),
 		controllers.UnpackBundle(c.imagePuller, c.imageCache),
+		controllers.ValidateInstallNamespace(coreClient),
 		controllers.ApplyBundleWithBoxcutter(appl.Apply),
 	}