more fixes

On-behalf-of: @SAP robert.vasek@sap.com
Signed-off-by: Robert Vasek <rvasek01@gmail.com>

Author: gman0

how-to-guides/bootstrap-provider.md

@@ -55,7 +55,7 @@ my-service   Ready   True
 The controller writes a kubeconfig Secret into the workspace where the `Provider` lives. Retrieve it:
 
 ```bash
-kubectl get secret my-service-provider-kubeconfig -o jsonpath='{.data.kubeconfig}' | base64 -d > provider-kubeconfig.yaml
+kubectl get secret my-service-provider-kubeconfig -n default -o jsonpath='{.data.kubeconfig}' | base64 -d > provider-kubeconfig.yaml
 ```
 
 Use this kubeconfig to authenticate against the provider workspace in kcp.

how-to-guides/onboard-managed-service.md

@@ -75,7 +75,7 @@ kubectl logs -n platform-mesh-system -l app=platform-mesh-operator --tail=50
 
 ## Step 3: Verify the kubeconfig Secret
 
-Once `Ready`, the controller writes a kubeconfig Secret into the runtime cluster. Verify it exists:
+The controller writes the kubeconfig Secret during the `CopyingKubeconfig` phase. Once the resource is `Ready`, verify it exists:
 
 ```bash
 kubectl get secret my-service-provider-kubeconfig -n platform-mesh-system
@@ -95,8 +95,10 @@ kubectl get pods -n platform-mesh-system -l app.kubernetes.io/name=my-service-op
 
 | Symptom | Likely cause |
 | --- | --- |
-| Stuck at `WaitingForProvider` | The `Provider` has not yet reached `Ready` — check the Provider controller logs for workspace or kubeconfig provisioning errors |
-| Stuck at `CopyingKubeconfig` | The Provider workspace is ready but the kubeconfig copy failed — check the ManagedProvider controller logs for Secret write errors |
+| Stuck at `WaitingForPlatformMesh` | The referenced `PlatformMesh` resource is not yet `Ready` — check the platform-mesh-operator logs and the `PlatformMesh` conditions |
+| Stuck at `WaitingForProvider` | The associated `Provider` has not yet reached `Ready` — check the Provider controller logs for workspace or kubeconfig provisioning errors |
+| Stuck at `CopyingKubeconfig` | The Provider controller has not yet populated the kubeconfig Secret — check the Provider controller logs |
+| Stuck at `CopyingKubeconfigFailed` | The `providerKubeconfigSecret` spec on the `Provider` does not match what the `ManagedProvider` expects — ensure the `providerKubeconfigSecret` fields are aligned between both resources |
 | Stuck at `Deploying` | The OCM component version does not exist in the registry, or FluxCD is not reconciling — check HelmRelease status in the namespace |
 | `Ready` but pods not running | The operator chart values may be misconfigured — check the HelmRelease events and operator pod logs |
 

reference/resources/provider-resource.md

@@ -54,9 +54,9 @@ The **Provider controller**, part of the [Platform Mesh operator](/reference/com
 ## What happens when you apply one
 
 1. Finalizers are added for ordered cleanup.
-2. A workspace (WorkspaceType **`root:provider`**) is created under `root:providers`.
+2. A workspace (WorkspaceType **`root:provider`**) is created under `root:providers`. Its name is `<Provider.name>-<random-suffix>`.
 3. Inside that workspace, a ServiceAccount, ClusterRoleBinding, and token Secret are created.
-4. A kubeconfig is generated from those credentials and written to the Secret specified by `providerKubeconfigSecret` (or the default location).
+4. A kubeconfig is generated from those credentials and written to the Secret specified by `providerKubeconfigSecret` (or the default location). The Secret is placed in the workspace where the `Provider` object lives, not in the provider workspace itself.
 5. `status.phase` transitions to `Ready` once provisioning completes.
 
 ## Lifecycle