doc(argocd): editorial polish across argo cd integration docs

Prose improvements across overview, connect-argocd, connect-akuity, and
deploy-applications: active voice, 25-word sentence target, no em dashes,
click/select distinction, table-before-tabs ordering, and parallel structure
between connector pages.

Structural changes: split akuity field reference into two tables, moved
agent sizing to a reference appendix after next steps, collapsed redundant
h3 into the deploy-to-tenant-cluster section, fixed broken relative links.

Added Akuity and kustomization to Vale vocabulary. Updated style guide with
click/select guidance.

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

Author: djwfyi

.claude/skills/vcluster-docs-writer/references/style-guide.md

@@ -204,6 +204,19 @@ When writing documentation for vCluster features, follow this structure:
 - Include expected output where relevant
 - Group related examples under descriptive headings
 
+#### UI interaction language in Flow steps
+
+Use **"Click"** when the user interacts with a single item — a button, tab, link, or nav item.
+Use **"Select"** when the user is making a choice between options — a dropdown, list, or set of radio buttons.
+
+Never write "Click on", "Click the", or "Click on the" — just "Click".
+
+| Correct | Incorrect |
+|---|---|
+| `Click <Button>Save</Button>` | `Click the <Button>Save</Button> button` |
+| `Click <NavStep>Virtual Clusters</NavStep>` | `Click on <NavStep>Virtual Clusters</NavStep>` |
+| `Select the project from the dropdown` | `Click the project dropdown` |
+
 ### 5. Known Limitations Section
 - Clearly document any limitations at the end
 - Use subsections for different limitation categories

.github/styles/config/vocabularies/Loft/accept.txt

@@ -1,4 +1,5 @@
 [aA]dmin
+[Aa]kuity
 Alpine
 ArgoCD
 AWS
@@ -37,6 +38,8 @@ JavaScript
 [jJ]ob
 apiserver
 kubeadm
+[kK]ustomize
+[kK]ustomization
 KubeVirt
 kubelet
 Let's Encrypt

platform/integrations/argocd/connect-akuity.mdx

@@ -10,29 +10,27 @@ import Flow, { Step } from "@site/src/components/Flow";
 import Button from "@site/src/components/Button";
 import Label from "@site/src/components/Label";
 
-This guide connects vCluster Platform to an [Akuity](https://akuity.io)-managed Argo CD instance. At the end you will have a connector that registers tenant clusters and control plane clusters with Akuity and provisions the Akuity agent inside each cluster automatically.
+This guide connects vCluster Platform to an [Akuity](https://akuity.io)-managed Argo CD instance. After successful completion of the steps, you should have a connector that registers tenant clusters and control plane clusters with Akuity and provisions the Akuity agent inside each cluster automatically.
 
 For a self-hosted Argo CD server, see [Connect to Argo CD](./connect-argocd.mdx) instead.
 
 ## How the Akuity agent works
 
-When you use an Akuity connector, Argo CD does not connect directly to your cluster's API server. Instead, Akuity uses a lightweight agent running inside each registered cluster that establishes an outbound connection to the Akuity control plane. The managed Akuity Argo CD instance communicates with the cluster through that persistent connection.
-
-This means the cluster's API server does not need to be publicly reachable — the agent runs inside the cluster and connects outward — so private clusters are fully supported.
+When you use an Akuity connector, Argo CD does not connect directly to your cluster's API server. Instead, Akuity uses a lightweight agent running inside each registered cluster that establishes an outbound connection to the Akuity control plane. The agent's outbound connection becomes a bidirectional channel. Argo CD communicates with the cluster through it without requiring the cluster's API server to be directly reachable. Since the agent connects outward, private clusters are fully supported.
 
 You do not install or manage the agent manually. When a cluster is registered with an Akuity connector, Platform:
 
 1. Calls the Akuity API to register the cluster and retrieve the agent installation manifest.
-2. Applies the manifest to the cluster. The agent is installed in its own namespace within the cluster.
+2. Applies the manifest to the cluster. The agent installs in its own namespace within the cluster.
 3. Stores a hash of the applied manifest in a cluster annotation. If the manifest changes (for example, after an Akuity agent version update), Platform detects the drift and applies the updated manifest automatically.
 
-When the integration is disabled or the connector is changed, Platform removes the agent namespace from the cluster and deregisters it from Akuity.
+When you disable the integration, Platform removes the agent namespace and deregisters the cluster from Akuity. When you change which connector a cluster references, Platform deregisters from the previous Akuity instance before registering with the new one.
 
 ## Prerequisites
 
-- vCluster Platform running with admin access
+- vCluster Platform running with [platform admin access](../../administer/users-permissions/overview.mdx)
 - An Akuity organization with an active Argo CD instance
-- An Akuity API key (see below)
+- An Akuity API key. See [Akuity API key permissions](#akuity-api-key-permissions) for required permissions.
 
 ### Akuity API key permissions
 
@@ -49,11 +47,40 @@ See the [Akuity API key documentation](https://docs.akuity.io/organizations/api-
 
 ## Step 1: Create a connector
 
+The connector Secret supports the following fields.
+
+**Standard connection fields:**
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `server` | Yes | Akuity instance URL. Format: `https://<akuityInstanceId>.cd.akuity.cloud/` |
+| `token` | If not using `username` and `password` | Argo CD API bearer token for the Akuity instance |
+| `username` | If not using `token` | Argo CD username |
+| `password` | If not using `token` | Argo CD password |
+| `namespace` | No | Namespace where Argo CD is installed. Defaults to `argocd` |
+| `insecure` | No | Set to `"true"` to skip TLS verification. Defaults to `"false"` |
+
+**Akuity-specific fields:**
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `connectorType` | Yes | Must be `"akuity"` |
+| `akuityOrgId` | Yes | Akuity organization ID |
+| `akuityInstanceId` | Yes | Argo CD instance ID within your Akuity organization |
+| `akuityApiKeyId` | Yes | Akuity API key ID, used to register and manage clusters via the Akuity API |
+| `akuityApiKeySecret` | Yes | Akuity API key secret |
+| `akuityAgentSize` | No | Agent size profile: `CLUSTER_SIZE_SMALL`, `CLUSTER_SIZE_MEDIUM` (default), or `CLUSTER_SIZE_LARGE`. See [Agent sizing](#agent-sizing). |
+| `akuityRepoServerReplicas` | No | Override the `argocd-repo-server` replica count. See [Agent sizing](#agent-sizing). |
+| `akuityRepoServerMemory` | No | Override `argocd-repo-server` memory. Sets both `requests` and `limits`. See [Agent sizing](#agent-sizing). |
+
+Select your authentication method and apply the Secret with `kubectl apply`:
+
 <Tabs
   defaultValue="ui"
   values={[
     { label: "Platform UI", value: "ui" },
-    { label: "YAML", value: "yaml" },
+    { label: "YAML (token)", value: "yaml-token" },
+    { label: "YAML (basic auth)", value: "yaml-basic" },
   ]}
 >
   <TabItem value="ui">
@@ -66,7 +93,7 @@ See the [Akuity API key documentation](https://docs.akuity.io/organizations/api-
     Click <Button>Add ArgoCD Connector</Button>.
   </Step>
   <Step>
-    In the <Label>Display name</Label> field, enter a human-readable name for the connector.
+    In <Label>Display name</Label>, enter a human-readable name for the connector.
     The <Label>ArgoCD Connector ID</Label> is auto-generated from the display name and is used to reference this connector from clusters.
   </Step>
   <Step>
@@ -76,10 +103,10 @@ See the [Akuity API key documentation](https://docs.akuity.io/organizations/api-
     - <Label>API Key ID</Label> and <Label>API Key Secret</Label>: your Akuity API key credentials
   </Step>
   <Step>
-    In the <Label>Server URL</Label> field, enter the Akuity instance URL. The format is `https://<akuityInstanceId>.cd.akuity.cloud/`.
+    In <Label>Server URL</Label>, enter the Akuity instance URL. The format is `https://<akuityInstanceId>.cd.akuity.cloud/`.
   </Step>
   <Step>
-    If Argo CD is installed in a namespace other than `argocd`, update the <Label>Argo CD Namespace</Label> field.
+    If Argo CD is installed in a namespace other than `argocd`, update <Label>Argo CD Namespace</Label>.
   </Step>
   <Step>
     Select an authentication method and fill in the credentials:
@@ -88,26 +115,15 @@ See the [Akuity API key documentation](https://docs.akuity.io/organizations/api-
   </Step>
   <Step>
     In the <Label>Agent Configuration</Label> section, select an <Label>Agent Size</Label> for the cluster workload.
-    Optionally override <Label>Replicas</Label> and <Label>Memory</Label> for the `argocd-repo-server` (see [Agent sizing](#agent-sizing) below).
+    Optionally override <Label>Replicas</Label> and <Label>Memory</Label> for the `argocd-repo-server` (see [Agent sizing](#agent-sizing)).
   </Step>
   <Step>
     Click <Button>Create ArgoCD Connector</Button>.
   </Step>
 </Flow>
 
   </TabItem>
-  <TabItem value="yaml">
-
-Set `connectorType: "akuity"` to use Akuity. Akuity supports two authentication methods for the Argo CD API, controlled by the `authType` field. Apply the Secret with `kubectl apply`.
-
-<Tabs
-  defaultValue="token"
-  values={[
-    { label: "Token", value: "token" },
-    { label: "Basic auth", value: "basic" },
-  ]}
->
-  <TabItem value="token">
+  <TabItem value="yaml-token">
 
 ```yaml
 apiVersion: v1
@@ -120,7 +136,6 @@ metadata:
 type: Opaque
 stringData:
   connectorType: "akuity"
-  authType: "token"
   server: "https://<akuity-instance-id>.cd.akuity.cloud/"
   token: "<argocd-api-token>"
   namespace: "argocd"
@@ -135,7 +150,7 @@ stringData:
 ```
 
   </TabItem>
-  <TabItem value="basic">
+  <TabItem value="yaml-basic">
 
 ```yaml
 apiVersion: v1
@@ -148,7 +163,6 @@ metadata:
 type: Opaque
 stringData:
   connectorType: "akuity"
-  authType: "basic"
   server: "https://<akuity-instance-id>.cd.akuity.cloud/"
   username: "<argocd-username>"
   password: "<argocd-password>"
@@ -166,55 +180,13 @@ stringData:
   </TabItem>
 </Tabs>
 
-| Field | Required | Description |
-|-------|----------|-------------|
-| `connectorType` | Yes | Must be `"akuity"` |
-| `authType` | Yes | Argo CD authentication method: `"token"` or `"basic"` |
-| `server` | Yes | Akuity instance URL. Format: `https://<akuityInstanceId>.cd.akuity.cloud/` |
-| `token` | If `authType` is `"token"` | Argo CD API bearer token for the Akuity instance |
-| `username` | If `authType` is `"basic"` | Argo CD username |
-| `password` | If `authType` is `"basic"` | Argo CD password |
-| `namespace` | No | Namespace where Argo CD is installed. Defaults to `argocd` |
-| `insecure` | No | Set to `"true"` to skip TLS verification. Defaults to `"false"` |
-| `akuityOrgId` | Yes | Akuity organization ID |
-| `akuityInstanceId` | Yes | Argo CD instance ID within your Akuity organization |
-| `akuityApiKeyId` | Yes | Akuity API key ID, used to register and manage clusters via the Akuity API |
-| `akuityApiKeySecret` | Yes | Akuity API key secret |
-| `akuityAgentSize` | No | Agent size profile: `CLUSTER_SIZE_SMALL`, `CLUSTER_SIZE_MEDIUM` (default), or `CLUSTER_SIZE_LARGE`. See [Agent sizing](#agent-sizing). |
-| `akuityRepoServerReplicas` | No | Override the `argocd-repo-server` replica count. See [Agent sizing](#agent-sizing). |
-| `akuityRepoServerMemory` | No | Override `argocd-repo-server` memory. Sets both `requests` and `limits`. See [Agent sizing](#agent-sizing). |
-
-  </TabItem>
-</Tabs>
-
-## Agent sizing
-
-Three fields in the connector Secret control how the Akuity agent is provisioned inside each registered cluster.
-
-### `akuityAgentSize`
-
-This field is sent to the Akuity API when the cluster is registered and determines the overall resource profile of the agent as defined by Akuity. It is an Akuity-level concept, not a direct Kubernetes resource value — Akuity translates this into the appropriate CPU and memory requests for the agent workloads on its end.
-
-| Value | Recommended for |
-|-------|----------------|
-| `CLUSTER_SIZE_SMALL` | Development or low-traffic clusters with few Applications |
-| `CLUSTER_SIZE_MEDIUM` | General-purpose clusters (default) |
-| `CLUSTER_SIZE_LARGE` | High-throughput clusters with many Applications or frequent syncs |
-
-### `akuityRepoServerReplicas` and `akuityRepoServerMemory`
-
-These fields let you override specific resource settings on the `argocd-repo-server` Deployment inside the cluster, independently of the size profile. Platform applies a kustomization patch to the agent manifest before installing it:
-
-- `akuityRepoServerReplicas` sets `spec.replicas` on the `argocd-repo-server` Deployment.
-- `akuityRepoServerMemory` sets both `resources.requests.memory` and `resources.limits.memory` to the same value on the `argocd-repo-server` container. Accepts standard Kubernetes memory quantity strings, for example `"1Gi"` or `"512Mi"`.
-
-Both fields are optional and independent of `akuityAgentSize`. Use them when the size profile alone does not give you the control you need over repo server memory or replica count.
+For details on the three sizing fields, see [Agent sizing](#agent-sizing).
 
 ## Step 2: Enable the connector on a cluster
 
 ### On a tenant cluster
 
-Add the `integrations.argoCD` block to the tenant cluster's `vcluster.yaml`. The `connector` field references the Secret name from Step 1.
+Add the `integrations.argoCD` block to the tenant cluster's `vcluster.yaml`. The `connector` field references the Secret name from [Step 1](#step-1-create-a-connector).
 
 ```yaml
 integrations:
@@ -223,7 +195,7 @@ integrations:
     connector: akuity-prod
 ```
 
-The connector can also be set directly in the `VirtualClusterInstance` manifest:
+You can also set the connector directly in the `VirtualClusterInstance` manifest:
 
 ```yaml
 apiVersion: management.loft.sh/v1
@@ -233,15 +205,12 @@ metadata:
   namespace: p-team-a
 spec:
   template:
-    metadata:
-      name: vcluster
-    spec:
-      helmRelease:
-        values: |
-          integrations:
-            argoCD:
-              enabled: true
-              connector: akuity-prod
+    helmRelease:
+      values: |
+        integrations:
+          argoCD:
+            enabled: true
+            connector: akuity-prod
 ```
 
 When the `VirtualClusterInstance` reconciles, Platform registers the tenant cluster with Akuity, retrieves the agent manifest, and installs the agent into the cluster.
@@ -262,9 +231,31 @@ spec:
 ```
 
 :::warning Disabling the integration
-Disabling the integration removes the cluster from Akuity, uninstalls the agent namespace from the cluster, and deletes all `ArgoCDApplication` objects managed by Platform. This applies whether the integration is configured via `vcluster.yaml`, a `VirtualClusterInstance` manifest, or a `Cluster` object. Any applications deployed by the integration will be removed from Argo CD.
+Disabling the integration removes the cluster from Akuity, uninstalls the agent namespace, and deletes all `ArgoCDApplication` objects managed by Platform. This applies whether you configure the integration using `vcluster.yaml`, a `VirtualClusterInstance` manifest, or a `Cluster` object. Any applications deployed by the integration are removed from Argo CD.
 :::
 
 ## Next step
 
 With the connector enabled, you can declare Argo CD Applications in your tenant cluster or control plane cluster configuration. See [Deploy applications](./deploy-applications.mdx).
+
+## Agent sizing
+
+Three fields in the connector Secret control how the Akuity agent is provisioned inside each registered cluster.
+
+### `akuityAgentSize`
+
+When you register a cluster, Platform sends this field to the Akuity API to set the agent's overall resource profile. This is an Akuity-level concept, not a direct Kubernetes resource value. Akuity translates it into the appropriate CPU and memory requests for the agent workloads.
+
+| Value | Recommended for |
+|-------|----------------|
+| `CLUSTER_SIZE_SMALL` | Development or low-traffic clusters with few Applications |
+| `CLUSTER_SIZE_MEDIUM` | General-purpose clusters (default) |
+| `CLUSTER_SIZE_LARGE` | High-throughput clusters with many Applications or frequent syncs |
+
+### `akuityRepoServerReplicas`
+
+This optional field overrides `spec.replicas` on the `argocd-repo-server` Deployment inside the cluster. Platform applies it as a kustomization patch to the agent manifest before installing. It is independent of `akuityAgentSize`.
+
+### `akuityRepoServerMemory`
+
+This optional field overrides memory on the `argocd-repo-server` container inside the cluster. Platform sets both `resources.requests.memory` and `resources.limits.memory` to the same value via a kustomization patch to the agent manifest. It is independent of `akuityAgentSize`. It accepts standard Kubernetes memory quantity strings, for example `"1Gi"` or `"512Mi"`.