Add CRD namespace consistency note for operator deployment

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ChrisJBurns

docs/toolhive/guides-k8s/deploy-operator.mdx

@@ -37,6 +37,24 @@ Choose an installation method based on your needs:
 helm upgrade --install toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds
 ```
 
+:::warning[Namespace consistency]
+
+When you install this chart, Helm stamps all CRDs with a
+`meta.helm.sh/release-namespace` annotation set to the namespace used at install
+time. This annotation **cannot be changed** by subsequent `helm upgrade`
+commands targeting a different namespace.
+
+You can install this chart in any namespace, but you **must use the same
+namespace consistently** for all future upgrades. If you plan to install the
+operator in `toolhive-system`, install the CRD chart there too:
+
+```bash
+helm upgrade --install toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds \
+  -n toolhive-system --create-namespace
+```
+
+:::
+
 This command installs the latest version of the ToolHive operator CRDs Helm
 chart. To install a specific version, append `--version <VERSION>` to the
 command, for example:
@@ -480,6 +498,34 @@ Common causes include:
 
 </details>
 
+<details>
+<summary>CRD upgrade fails with namespace mismatch</summary>
+
+If you see an error like the following when upgrading the CRD chart:
+
+```text
+Error: invalid ownership metadata; annotation validation error:
+key "meta.helm.sh/release-namespace" must equal "toolhive-system":
+current value is "default"
+```
+
+This means the CRD chart was originally installed in a different namespace than
+the one you're now targeting. To fix this, patch the ownership annotations on
+all CRDs to match your desired namespace:
+
+```bash
+for crd in $(kubectl get crd -o name | grep toolhive.stacklok.dev); do
+  kubectl annotate "$crd" \
+    meta.helm.sh/release-namespace=<TARGET_NAMESPACE> --overwrite
+done
+```
+
+Replace `<TARGET_NAMESPACE>` with the namespace you want to use going forward
+(for example, `toolhive-system`). This is a one-time operation. After patching,
+future upgrades work as long as you use the same namespace consistently.
+
+</details>
+
 <details>
 <summary>CRDs installation fails</summary>