fix (platform): add registration of host clusters

platform/_partials/cluster/connect-cli.mdx

@@ -1,13 +1,42 @@
+import Flow, { Step } from '@site/src/components/Flow'
 import NavStep from '@site/src/components/NavStep'
+import Button from '@site/src/components/Button'
+import Label from '@site/src/components/Label'
+import Input from '@site/src/components/Input'
+import Expander from '@site/src/components/Expander'
 
-When connecting a cluster from the vCluster CLI, you will need to provide a name for the cluster. This name will be used for the Cluster resource that gets created in Kubernetes. Optionally, you can use the `display-name` flag to specify a name for this cluster, when it gets displayed under the <NavStep>Clusters</NavStep> view in vCluster Platform.
+<Flow id="cluster-connect-cli">
+    <Step>
+        When connecting a cluster from the vCluster CLI, you will need to provide a name for the cluster. This name will be used for the Cluster resource that gets created in Kubernetes. Optionally, you can use the `display-name` flag to specify a name for this cluster, when it gets displayed under the <NavStep>Clusters</NavStep> view in vCluster Platform.
 
-```bash
-vcluster platform add cluster cluster-name --display-name [display-name]
-```
+        ```bash
+        vcluster platform add cluster cluster-name --display-name [display-name]
+        ```
 
-The above command will automatically install the vCluster Platform Agent in the cluster that is one's current context. If you want to connect a cluster that is not your current context, you can use the `--context` flag to specify the context of the cluster you want to connect.
+        The above command automatically installs the [vCluster Platform Agent](/docs/platform/administer/clusters/advanced/agent-config) in the cluster that corresponds to your current Kubernetes context. The host cluster where the vCluster Platform itself is deployed is automatically connected to the platform during installation. Therefore, this command should be executed in a different host cluster from the one where the vCluster Platform is running.
 
-```bash
-vcluster platform add cluster cluster-name --display-name [display-name] --context [context]
-```
+        By default, the `vcluster-platform` namespace is created automatically if it does not already exist on the cluster. The vCluster Platform Agent resources are deployed into this namespace. You can override this behavior by explicitly specifying a different namespace using the `--namespace` flag. If you want to connect a cluster that is not associated with your current Kubernetes context, use the `--context` flag to specify the context of the target cluster. 
+:::info
+For more information about available CLI flags, refer to the [CLI documentation](/docs/vcluster/cli/vcluster_platform_add_cluster).
+:::
+
+        ```bash
+        vcluster platform add cluster cluster-name --display-name [display-name] --context [context]
+        ```
+    </Step>
+    <Step>
+        You can verify that the cluster is connected to the platform by running:
+        ```bash
+        vcluster platform list clusters
+        ```
+
+        and the expected output is:
+        ```bash
+                CLUSTER      |  AGE
+        --------------------+--------
+            cluster-name     | 7s
+            host-cluster     | 10m4s   
+        ```
+        The `host-cluster` is the cluster name where the vCluster Platform is deployed.
+    </Step>
+</Flow>

platform/_partials/cluster/connect-helm.mdx

@@ -1,82 +1,101 @@
+import Flow, { Step } from '@site/src/components/Flow'
 import NavStep from '@site/src/components/NavStep'
-
-
-If you prefer to use Helm, you need to make sure that you have a valid Access Key.
-
-You can either reuse the CLI Access Key or create a new one by following the
-[Access Key guide](../../administer/users-permissions/access-keys.mdx#create-an-access-key).
-
-
-- Reusing the CLI Access Key
-
-  ```bash
-  export ACCESS_KEY=$(vcluster platform access-key | jq -r .status.token)
-  ```
-
-- Create new Access Key by following the [Access
-Key](/platform/administer/users-permissions/access-keys#create-an-access-key) guide.
-
-  ```bash
-  export ACCESS_KEY="[Newly Created Access Key]"
-  ```
-
-After that, you need to provide a name for the cluster.
-
-```bash
-export CLUSTER_NAME="cluster-name"
-```
-
-Next, you must create the Cluster custom resource within the platform using the following code:
-
-```bash
-cat <<EOF | kubectl apply -f -
-apiVersion: management.loft.sh/v1
-kind: Cluster
-metadata:
-  name: $CLUSTER_NAME
-spec:
-  displayName: $CLUSTER_NAME
-  networkPeer: true
-  managementNamespace: vcluster-platform
-EOF
-```
-
-Then, you need to set the Platform Host using the following code:
-
-```bash
-export PLATFORM_HOST="YOUR_LOFT_HOST"
-```
-
-To get the Platform version, you should run the following command:
-
-```bash
-export PLATFORM_VERSION=$(curl -s "https://$PLATFORM_HOST/version" | jq -r '.version | .[0:]')
-```
-
-To get the Cluster Connect token, you should run the following command:
-
-```bash
-export CLUSTER_ACCESS_KEY=$(curl -s "https://$PLATFORM_HOST/kubernetes/management/apis/management.loft.sh/v1/clusters/$CLUSTER_NAME/accesskey" -H "Authorization: bearer $ACCESS_KEY")
-```
-
-Finally, you can connect the cluster using the following command:
-
-```bash
-helm upgrade loft vcluster-platform --install \
-  --repo https://charts.loft.sh/ \
-  --version $PLATFORM_VERSION \
-  --namespace vcluster-platform \
-  --create-namespace \
-  --set agentOnly=true \
-  --set url=https://$PLATFORM_HOST \
-  --set token=$(echo $CLUSTER_ACCESS_KEY | jq -r .accessKey) \
-  --set additionalCA=$(echo $CLUSTER_ACCESS_KEY | jq -r .caCert) \
-  --set insecure=$(echo $CLUSTER_ACCESS_KEY | jq -r .insecure)
-```
-:::warning
-vCluster Platform exclusively supports the default `secret` backend for storing Helm releases. Alternative `HELM_DRIVER` configurations (such as `configmap` or `sql`) are not supported.
-:::
-
-This command automatically installs the Platform Agent in the cluster that is your current context.
-However, if you want to connect a cluster that is not your current context, you can append the `--kube-context` flag to specify the context of the cluster you want to connect.
-
+import Button from '@site/src/components/Button'
+import Label from '@site/src/components/Label'
+import Input from '@site/src/components/Input'
+import Expander from '@site/src/components/Expander'
+
+<Flow id="cluster-connect-helm">
+  <Step>
+    If you prefer to use Helm, you need to make sure that you have a valid Access Key.
+
+    You can either reuse the CLI Access Key or create a new one by following the
+    [Access Key guide](../../administer/users-permissions/access-keys.mdx#create-an-access-key).
+
+
+    - Reusing the CLI Access Key
+
+      ```bash
+      export ACCESS_KEY=$(vcluster platform access-key | jq -r .status.token)
+      ```
+
+    - Create new Access Key by following the [Access
+    Key](/platform/administer/users-permissions/access-keys#create-an-access-key) guide.
+
+      ```bash
+      export ACCESS_KEY="[Newly Created Access Key]"
+      ```
+  </Step>
+  <Step>
+    After that, you need to provide a name for the cluster.
+
+    ```bash
+    export CLUSTER_NAME="cluster-name"
+    ```
+  </Step>
+  <Step>
+    Next, you must create the `Cluster` custom resource within the platform using the following code:
+
+    ```bash
+    cat <<EOF | kubectl apply -f -
+    apiVersion: management.loft.sh/v1
+    kind: Cluster
+    metadata:
+      name: $CLUSTER_NAME
+    spec:
+      displayName: $CLUSTER_NAME
+      networkPeer: true
+      managementNamespace: vcluster-platform
+    EOF
+    ```
+  </Step>
+  <Step>
+    Then, you need to set the Platform Host using the following code:
+
+    ```bash
+    export PLATFORM_HOST="YOUR_PLATFORM_HOST"
+    ```
+  </Step>
+  <Step>
+    To get the Platform version, you should run the following command:
+
+    ```bash
+    export PLATFORM_VERSION=$(curl -s "https://$PLATFORM_HOST/version" | jq -r '.version | .[0:]')
+    ```
+  </Step>
+  <Step>
+    To get the Cluster Connect token, you should run the following command:
+
+    ```bash
+    export CLUSTER_ACCESS_KEY=$(curl -s "https://$PLATFORM_HOST/kubernetes/management/apis/management.loft.sh/v1/clusters/$CLUSTER_NAME/accesskey" -H "Authorization: bearer $ACCESS_KEY")
+    ```
+  </Step>
+  <Step>
+    Finally, you can connect the cluster using the following command:
+
+    ```bash
+    helm upgrade loft vcluster-platform --install \
+      --repo https://charts.loft.sh/ \
+      --version $PLATFORM_VERSION \
+      --namespace vcluster-platform \
+      --create-namespace \
+      --set agentOnly=true \
+      --set url=https://$PLATFORM_HOST \
+      --set token=$(echo $CLUSTER_ACCESS_KEY | jq -r .accessKey) \
+      --set additionalCA=$(echo $CLUSTER_ACCESS_KEY | jq -r .caCert) \
+      --set insecure=$(echo $CLUSTER_ACCESS_KEY | jq -r .insecure)
+    ```
+
+    This command automatically installs the [vCluster Platform Agent](/docs/platform/administer/clusters/advanced/agent-config) in the cluster that is your current context.
+    However, if you want to connect a cluster that is not your current context, you can append the `--kube-context` flag to specify the context of the cluster you want to connect.
+
+    You can also retrieve pre-configured agent values from your platform by appending the `--values` flag with the platform endpoint `--values "https://$HOST/clusters/agent-values/$CLUSTER_NAME?token=$TOKEN"`.
+    - `$HOST` — your vCluster Platform domain
+    - `$CLUSTER_NAME` — the name you're assigning to the cluster being connected (e.g., `cluster-name`)
+    - `$TOKEN` — the authentication token to access your vCluster Platform
+    The endpoint returns an intelligently merged content of
+    - Platform-level defaults configured in the `agentValues` field of your vCluster Platform Helm values
+    - Cluster-specific overrides from the `loft.sh/agent-values` annotation (when present)
+
+  </Step>
+</Flow>

platform/_partials/cluster/upgrade-cli.mdx

@@ -0,0 +1,41 @@
+import Flow, { Step } from '@site/src/components/Flow'
+import NavStep from '@site/src/components/NavStep'
+import Button from '@site/src/components/Button'
+import Label from '@site/src/components/Label'
+import Input from '@site/src/components/Input'
+import Expander from '@site/src/components/Expander'
+
+
+<Flow id="upgrade-cluster-cli">
+    <Step>
+        You can verify that the [vCluster Platform Agent](/docs/platform/administer/clusters/advanced/agent-config) is installed in the cluster by running:
+
+        ```bash
+        vcluster platform list clusters
+        ```
+
+        The expected output would be:
+
+        ```bash
+                CLUSTER      |  AGE
+        --------------------+--------
+            cluster-name      |  7s
+        ```
+
+        In this example, the host cluster where the platform agent is installed is named `cluster-name`.
+    </Step>
+    <Step>
+        By providing the Helm chart version and values configuration, you can install or upgrade the existing platform agent deployment for the `cluster-name` cluster using:
+
+        ```
+        vcluster platform add cluster cluster-name \
+            --helm-chart-version v4.5 \
+            --helm-values my-helm-values \
+            --context cluster-name-context
+        ```
+
+        Choose the appropriate version in `--helm-chart-version` and Helm chart configuration in `--helm-values`. Replace `--context` with the Kubernetes context of your target cluster. 
+        If you are already operating within that cluster’s context, you can omit the --context flag — the command will automatically install or upgrade the platform agent in the current cluster.
+        You can find more details about the available flags for the `vcluster platform add cluster` command in the [CLI documentation](/docs/vcluster/cli/vcluster_platform_add_cluster).
+    </Step>
+</Flow>

platform/_partials/cluster/upgrade-helm.mdx

@@ -0,0 +1,60 @@
+import Flow, { Step } from '@site/src/components/Flow'
+import NavStep from '@site/src/components/NavStep'
+import Button from '@site/src/components/Button'
+import Label from '@site/src/components/Label'
+import Input from '@site/src/components/Input'
+import Expander from '@site/src/components/Expander'
+
+<Flow id="upgrade-cluster-helm">
+    <Step>
+        If you prefer to use Helm, ensure that you have a valid access key. You can only obtain an access key after the cluster has been connected to the Platform.
+    </Step>
+    <Step>
+        To retrieve the access key for a connected cluster, run:
+
+        ```bash
+        vcluster platform get cluster-access-key cluster-name
+        ```
+
+        The expected output is:
+
+        ```bash
+        14:43:35 info vCluster platform host: https://loftg2fei.loft.host
+        14:43:35 info Access Key: xxxxxxxx
+        ```
+        In this example, `cluster-name` refers to the host cluster containing the [vCluster Platform Agent](/docs/platform/administer/clusters/advanced/agent-config) to be upgraded.
+
+        <!-- vale off -->
+        Here, `https://loftg2fei.loft.host` represents the `url`, and `xxxxxxxx` is the `token`.
+        <!-- vale on -->
+    </Step>
+    <Step>
+        Next, use the following Helm command to upgrade the platform agent by providing the retrieved `url` and `token`:
+
+        ```yaml
+        helm upgrade loft vcluster-platform \
+            --repo https://charts.loft.sh \
+            --install \
+            --create-namespace \
+            --namespace vcluster-platform \
+            --set agentOnly=true \
+            --set url=https://loftg2fei.loft.host \
+            --set token=xxxxxxxx
+        ```   
+        Ensure that the namespace specified with `--namespace` exists. This is the namespace where the platform agent is installed.
+        If you deploy the platform agent’s resources into a different namespace, make sure to set `--namespace` accordingly.
+
+        You can also retrieve pre-configured agent values from your platform by appending the `--values` flag with platform endpoint
+        `--values "https://$HOST/clusters/agent-values/$CLUSTER_NAME?token=$TOKEN"`.
+        - `$HOST` — your platform domain.
+        - `$CLUSTER_NAME` — the name of the cluster you are connecting.
+        - `$TOKEN` — the authentication token.
+        In this example, `$HOST=loftg2fei.loft.host`, `$CLUSTER_NAME=cluster-name` and `$TOKEN=xxxxxxxx`.
+        The endpoint returns a YAML file with agent values that are configured in the `agentValues` field of your vCluster 
+        Platform Helm values, merged with any cluster-specific overrides from the `loft.sh/agent-values` annotation (when present).
+
+        If the platform agent is not yet installed, you can include the `--install` and `--create-namespace` flags. The combination 
+        of `--create-namespace` and `--namespace vcluster-platform` will create the `vcluster-platform` namespace in the host cluster
+        if it does not already exist. All platform agent resources will then be deployed and run within that namespace.
+    </Step>
+</Flow>

platform/administer/clusters/advanced/cluster-upgrades.mdx

@@ -6,8 +6,9 @@ sidebar_label: Agent Upgrades
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem'
 
-import PartialClusterConnectUI from '../../../_partials/cluster/connect-ui.mdx'
-import PartialClusterConnectCLI from '../../../_partials/cluster/connect-cli.mdx'
+import ConnectPlatform from '../../../_fragments/cli-steps/connect-platform.mdx';
+import PartialClusterUpgradeCLI from '../../../_partials/cluster/upgrade-cli.mdx'
+import PartialClusterUpgradeHelm from '../../../_partials/cluster/upgrade-helm.mdx'
 
 import BeforeSvg from '@site/static/media/agent/before-agent-upgrade.excalidraw.svg';
 import DuringSvg1 from '@site/static/media/agent/during-agent-upgrade-1.excalidraw.svg';
@@ -49,7 +50,33 @@ Once the agent upgrade is complete, the platform will remove the proxy-only agen
 <AfterSvg width="100%" />
 
 ## Self-managed agents
+If the platform does not manage your agents, you can still manually upgrade them.
 
-If the platform does not manage your agents, manually upgrade them by repeating the installation steps using the CLI or Helm command.
-Instructions on how to do can be found [here](../connect-cluster.mdx).
+<Tabs
+  defaultValue="cli"
+  values={[
+    {label: 'CLI', value: 'cli'},
+    {label: 'Helm', value: 'helm'},
+  ]}>
+  <TabItem value="cli">
+    <PartialClusterUpgradeCLI />
 
+
+  :::info platform login
+    <ConnectPlatform />
+
+  If your kubectl context is not set to the cluster with running platform, it's
+  possible to login to the platform using the CLI and access key.
+  If you haven't already, you need to [create access key](/docs/platform/api/authentication#create-an-access-key) to be able to login to the platform.
+
+  ```bash title="Login to the platform using access key"
+  vcluster platform login [platform-url] --access-key [access-key]
+  ```
+
+  :::
+
+  </TabItem>
+  <TabItem value="helm">
+    <PartialClusterUpgradeHelm />
+  </TabItem>
+</Tabs>