Apply suggestions from code review

Signed-off-by: Kent Rancourt <kent.rancourt@gmail.com>

docs/docs/30-how-to-guides/25-argo-cd-integration.md

@@ -5,43 +5,62 @@ sidebar_label: Argo CD Integration
 
 # Argo CD Integration
 
-Kargo integrates seamlessly with Argo CD to facilitate a more streamlined application lifecycle
-management process. While Argo CD helps with deploying Kubernetes objects and synchronizing changes
-in the cluster, Kargo focuses on orchestrating the promotion of these changes through various
-`Stage`s of development, such as from `development` to `testing` and then to `production`.
+Argo CD excels at syncing Kubernetes clusters to desired state stored in
+a Git repository, but lacks any concept of a "promotion", i.e. updating
+the desired state of some application instance to reflect the validated
+state of some other application instance. Kargo was created to orchestrate
+such processes. Because such orchestration naturally entails some direct
+and indirect integration with Argo CD, this page details certain key
+elements of the interactions between the two systems.
 
 :::note
-This page is a work in progress.
-During this process, you may find limited details here. Please bear with us as we work to add more information.
+This page is a work in progress. Thank you for your patience as as we work to add more details.
 :::
 
-### Authorizing Kargo `Stage`s to Modify Argo CD Applications
+## Updating Argo CD Applications
 
-To enable Kargo `Stage`s to interact with and modify Argo CD applications, applications need
-to explicitly authorize Kargo to perform these actions. This is accomplished using the
-`kargo.akuity.io/authorized-stage` annotation.
+In the course of orchestrating the transition of an application instance
+from one state to another, it is common for Kargo to updated Argo CD
+`Application` resources in some way. Such updates are enabled through the
+use of the
+[`argocd-update` promotion step](./35-references/10-promotion-steps.md#argocd-update).
+Often, these updates entail little more than modifying an `Application`'s 
+`operation` field to force the `Application` to be synced to recently
+updated desired state.
 
-Kargo requires the annotation in the following format:
+### Authorizing Updates
+
+Performing updates of any kind to an `Application` resource naturally
+requires Kargo to be _authorized_ to do so. Kargo controllers have the
+requisite RBAC permissions to perform such updates, but being a
+multi-tenant system, Kargo must also understand, internally, when it
+is acceptable to utilize those broad permissions to update a specific 
+`Application` resource _on behalf of_ a given `Stage`.
+
+To enable Kargo controllers to update an Argo CD `Application` on behalf of
+a given `Stage`, that `Application` must be explicitly annotated as follows:
 
 ```yaml
 kargo.akuity.io/authorized-stage: "<project-name>:<stage-name>"
 ```
 
-This annotation signifies consent for Kargo to manage the application on behalf of the designated `Project` and `Stage`.
+Because an annotation such as the one above could only be added to
+an `Application` by a user who, themselves, is authorized to update
+that `Application`, Kargo interprets the presence of such an annotation
+as delegation of that user's authority to do so.
 
-In the following example, the `Application` manifest is configured to
-authorize the `test` `Stage` of the `kargo-demo` `Project` to manage
-the application by including the `kargo.akuity.io/authorized-stage: kargo-demo:test`
-annotation:
+In the following example, an `Application` has been annotated to
+authorize Kargo to update it on behalf of a `Stage` named `test`
+in the `kargo-demo` `Project`:
 
 ```yaml
-    apiVersion: argoproj.io/v1alpha1
-    kind: Application
-    metadata:
-        name: kargo-demo-test
-        namespace: argocd
-        annotations:
-            kargo.akuity.io/authorized-stage: kargo-demo:test
-    spec:
-        # Application Specifications
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: kargo-demo-test
+  namespace: argocd
+  annotations:
+    kargo.akuity.io/authorized-stage: kargo-demo:test
+spec:
+  # Application Specifications
 ```