diff --git a/docs/conf.py b/docs/conf.py
index 1908d46b9f..3c73e86e97 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -232,7 +232,8 @@
     "https://matrix.to/*",
     "https://portal.azure.com/*",
     "https://dev.mysql.com/*",
-    "https://www.mysql.com/*"
+    "https://www.mysql.com/*",
+    "https://www.terraform.io/*"
     ]
 
 
diff --git a/docs/explanation/juju.md b/docs/explanation/juju.md
index 16c0f50773..8d25c46ce5 100644
--- a/docs/explanation/juju.md
+++ b/docs/explanation/juju.md
@@ -31,12 +31,14 @@ See the [Juju 3.0 release notes](https://documentation.ubuntu.com/juju/3.6/refer
 The response is to therefore substitute the documented command with the equivalent 2.9.x command. For example:
 
 ### Juju 3.x:
+
 ```shell
 juju integrate mysql:database mysql-test-app
 
 juju run mysql/leader get-password 
 ```
 ### Juju 2.9.x:
+
 ```shell
 juju relate mysql:database mysql-test-app
 
@@ -46,7 +48,9 @@ juju run-action --wait mysql/leader get-password
 This section is based on the [OpenStack guide.](https://docs.openstack.org/charm-guide/latest/project/support-notes.html#breaking-changes-between-juju-2-9-x-and-3-x)
 ```
 
+(explanation-juju-upgrades)=
 ## Juju  upgrades
+
 Newly released charm revisions might require a new Juju version. This is usually because the new revision requires new Juju features, e.g. [Juju secrets](https://juju.is/docs/juju/secret).
 
 Information about Juju requirements will be clearly indicated in the charm's [release notes](/reference/releases) and in the repository's [metadata.yaml](https://github.com/canonical/mysql-operator/blob/14c06ff88c4e564cd6d098aa213bd03e78e84b52/metadata.yaml#L72-L80) file.
@@ -62,5 +66,5 @@ ERROR Charm feature requirements cannot be met:
       - charm requires feature "juju" (version >= 3.1.5) but model currently supports version 3.1.4
 ```
 
-You must then [upgrade to the required Juju version](/how-to/upgrade/upgrade-juju) before proceeding with the charm upgrade.
+You must then [upgrade to the required Juju version](/how-to/refresh/upgrade-juju) before proceeding with the charm upgrade.
 
diff --git a/docs/how-to/cross-regional-async-replication/clients.md b/docs/how-to/cluster-cluster-replication/clients.md
similarity index 85%
rename from docs/how-to/cross-regional-async-replication/clients.md
rename to docs/how-to/cluster-cluster-replication/clients.md
index af6dcc9b7f..47abadb238 100644
--- a/docs/how-to/cross-regional-async-replication/clients.md
+++ b/docs/how-to/cluster-cluster-replication/clients.md
@@ -2,7 +2,7 @@
 
 ## Pre-requisites
 
-Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/how-to/cross-regional-async-replication/deploy)!
+Make sure both `rome` and `lisbon` clusters are deployed according to [](/how-to/cluster-cluster-replication/deploy).
 
 ## Offer and consume database endpoints
 
diff --git a/docs/how-to/cross-regional-async-replication/deploy.md b/docs/how-to/cluster-cluster-replication/deploy.md
similarity index 80%
rename from docs/how-to/cross-regional-async-replication/deploy.md
rename to docs/how-to/cluster-cluster-replication/deploy.md
index b55fe47ad9..1c1b6b3a39 100644
--- a/docs/how-to/cross-regional-async-replication/deploy.md
+++ b/docs/how-to/cluster-cluster-replication/deploy.md
@@ -1,14 +1,4 @@
-# Deploy async replication
-
-The following table shows the source and target controller/model combinations that are currently supported:
-
-|  | AWS | GCP | Azure |
-|---|---|:---:|:---:|
-| AWS | ![ check ] |  |  |
-| GCP |  | ![ check ] |  |
-| Azure |  | | ![ check ] |
-
-## Deploy
+# Deploy
 
 Deploy two MySQL Clusters, named `Rome` and `Lisbon`:
 
@@ -24,7 +14,7 @@ juju deploy mysql db2 --channel=8.0/edge --config profile=testing --config clust
 ```
 
 ```{caution}
-Remove profile configuration for production deployments. Check [Profiles](/reference/profiles) for documentation.
+Remove [profile](/reference/profiles) configuration for production deployments. 
 ```
 
 ## Offer
@@ -107,8 +97,5 @@ juju add-unit db2 -n 2 -m lisbon
 ```
 
 ```{caution}
-**Note**: The scaling is possible before and after the asynchronous replication established/created.
+The scaling is possible before and after the asynchronous replication is established/created.
 ```
-
-[check]: https://img.shields.io/badge/%E2%9C%93-brightgreen
-
diff --git a/docs/how-to/cluster-cluster-replication/index.md b/docs/how-to/cluster-cluster-replication/index.md
new file mode 100644
index 0000000000..32e292be48
--- /dev/null
+++ b/docs/how-to/cluster-cluster-replication/index.md
@@ -0,0 +1,30 @@
+# Cluster-cluster replication
+
+Cluster-cluster asynchronous replication focuses on disaster recovery by distributing data across different servers.
+
+For increased safety, it is recommended to deploy each cluster in a different geographical region.
+
+## Substrate dependencies
+
+The following table shows the source and target controller/model combinations that are currently supported:
+
+|       |     AWS    |     GCP    |    Azure   |
+|-------|------------|:----------:|:----------:|
+| AWS   | ![ check ] |            |            |
+| GCP   |            | ![ check ] |            |
+| Azure |            |            | ![ check ] |
+
+## Guides
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+Deploy <deploy>
+Clients <clients>
+Switchover/failover <switchover-failover>
+Recovery <recovery>
+Removal <removal>
+```
+
+[check]: https://img.shields.io/badge/%E2%9C%93-brightgreen
\ No newline at end of file
diff --git a/docs/how-to/cross-regional-async-replication/recovery.md b/docs/how-to/cluster-cluster-replication/recovery.md
similarity index 94%
rename from docs/how-to/cross-regional-async-replication/recovery.md
rename to docs/how-to/cluster-cluster-replication/recovery.md
index 4c5747d203..258f61d1c5 100644
--- a/docs/how-to/cross-regional-async-replication/recovery.md
+++ b/docs/how-to/cluster-cluster-replication/recovery.md
@@ -2,7 +2,7 @@
 
 ## Pre-requisites
 
-Make sure both `Rome` and `Lisbon` clusters are deployed following the [async deployment guide](/how-to/cross-regional-async-replication/deploy).
+Make sure both `Rome` and `Lisbon` clusters are deployed following the [async deployment guide](/how-to/cluster-cluster-replication/deploy).
 
 ## Recover detached cluster
 
diff --git a/docs/how-to/cross-regional-async-replication/removal.md b/docs/how-to/cluster-cluster-replication/removal.md
similarity index 84%
rename from docs/how-to/cross-regional-async-replication/removal.md
rename to docs/how-to/cluster-cluster-replication/removal.md
index 749dde22cd..d0a0b662a7 100644
--- a/docs/how-to/cross-regional-async-replication/removal.md
+++ b/docs/how-to/cluster-cluster-replication/removal.md
@@ -2,12 +2,12 @@
 
 ## Pre-requisites
 
-Make sure both `Rome` and `Lisbon` clusters are deployed following the [async deployment guide](/how-to/cross-regional-async-replication/deploy).
+Make sure both `Rome` and `Lisbon` clusters are deployed following the [async deployment guide](/how-to/cluster-cluster-replication/deploy).
 
 ## Detach cluster from ClusterSet
 
 ```{important} 
-It is important to [switchover](/how-to/cross-regional-async-replication/switchover-failover) the `Primary` cluster before detaching it from ClusterSet!
+It is important to [switchover](/how-to/cluster-cluster-replication/switchover-failover) the `Primary` cluster before detaching it from ClusterSet!
 ```
 
 Assuming the `Lisbon` is a current `Primary` and we want to detach `Rome` (for removal or reuse):
diff --git a/docs/how-to/cross-regional-async-replication/switchover-failover.md b/docs/how-to/cluster-cluster-replication/switchover-failover.md
similarity index 91%
rename from docs/how-to/cross-regional-async-replication/switchover-failover.md
rename to docs/how-to/cluster-cluster-replication/switchover-failover.md
index dbf9e24dd0..f2888b9da0 100644
--- a/docs/how-to/cross-regional-async-replication/switchover-failover.md
+++ b/docs/how-to/cluster-cluster-replication/switchover-failover.md
@@ -2,7 +2,7 @@
 
 ## Pre-requisites
 
-Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/how-to/cross-regional-async-replication/deploy)!
+Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/how-to/cluster-cluster-replication/deploy)!
 
 ## Switchover (safe)
 
diff --git a/docs/how-to/cross-regional-async-replication/index.md b/docs/how-to/cross-regional-async-replication/index.md
deleted file mode 100644
index 8048c4905f..0000000000
--- a/docs/how-to/cross-regional-async-replication/index.md
+++ /dev/null
@@ -1,12 +0,0 @@
-# Cross-regional asynchronous replication
-
-```{toctree}
-:titlesonly:
-:maxdepth: 2
-
-Deploy <deploy>
-Clients <clients>
-Switchover/failover <switchover-failover>
-Recovery <recovery>
-Removal <removal>
-```
diff --git a/docs/how-to/development/migrate-data-via-backup-restore.md b/docs/how-to/development/migrate-data-via-backup-restore.md
index 03eca7e5ff..1b4d5aafa4 100644
--- a/docs/how-to/development/migrate-data-via-backup-restore.md
+++ b/docs/how-to/development/migrate-data-via-backup-restore.md
@@ -1,4 +1,4 @@
-# Migrate data via backup/restore
+# How to migrate data via backup/restore
 
 Charmed MySQL is able to restore [its own backups](/how-to/back-up-and-restore/restore-a-backup) stored on [S3-compatible storage](/how-to/back-up-and-restore/configure-s3-aws). 
 
diff --git a/docs/how-to/index.md b/docs/how-to/index.md
index 2d2fd75e4f..3e84beb0de 100644
--- a/docs/how-to/index.md
+++ b/docs/how-to/index.md
@@ -47,22 +47,22 @@ Integrate with observability services like Grafana, Prometheus, and Tempo.
 Monitoring (COS) <monitoring-cos/index>
 ```
 
-## Upgrades
+## Refresh (upgrade)
 
 ```{toctree}
 :titlesonly:
 :maxdepth: 2
 
-Upgrade <upgrade/index>
+Refresh (upgrade) <refresh/index>
 ```
 
-## Cross-regional (cluster-cluster) async replication
+## Cluster-cluster replication
 
 ```{toctree}
 :titlesonly:
 :maxdepth: 2
 
-Cross-regional async replication <cross-regional-async-replication/index>
+Cluster-cluster replication <cluster-cluster-replication/index>
 ```
 
 ## Development
diff --git a/docs/how-to/monitoring-cos/enable-tracing.md b/docs/how-to/monitoring-cos/enable-tracing.md
index 47b2b5c01a..45973364e7 100644
--- a/docs/how-to/monitoring-cos/enable-tracing.md
+++ b/docs/how-to/monitoring-cos/enable-tracing.md
@@ -9,7 +9,7 @@ This is feature is in development. It is **not recommended** for production envi
 ## Prerequisites
 
 * Charmed MySQL revision 237 or higher 
-  * See [](/how-to/upgrade/index)
+  * See [](/how-to/refresh/index)
 * `cos-lite` bundle deployed in a Kubernetes environment
   * See the [COS Microk8s tutorial](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)
 
diff --git a/docs/how-to/primary-switchover.md b/docs/how-to/primary-switchover.md
index 0d577c8a26..ab0bd1c906 100644
--- a/docs/how-to/primary-switchover.md
+++ b/docs/how-to/primary-switchover.md
@@ -16,5 +16,6 @@ secondary.
 
 ```{caution}
 The `promote-to-primary` action can be used in cluster scope, when using async replication.
-Check [Switchover / Failover](cross-regional-async-replication/switchover-failover) for more information.
+
+See [](/how-to/cluster-cluster-replication/switchover-failover) for more information.
 ```
\ No newline at end of file
diff --git a/docs/how-to/refresh/index.md b/docs/how-to/refresh/index.md
new file mode 100644
index 0000000000..8f8dfc1a95
--- /dev/null
+++ b/docs/how-to/refresh/index.md
@@ -0,0 +1,65 @@
+# Refresh (upgrade)
+
+This charm supports in-place upgrades to higher versions via Juju's [`refresh`](https://documentation.ubuntu.com/juju/3.6/reference/juju-cli/list-of-juju-cli-commands/refresh/#details) command.
+
+## Supported refreshes
+
+```{eval-rst}
++------------+------------+----------+------------+
+| From                    | To                    |
++------------+------------+----------+------------+
+| Charm      | MySQL      | Charm    | MySQL      |
+| revision   | Version    | revision | Version    |
++============+============+==========+============+
+| 366, 367   | ``8.0.41`` |          |            |
++------------+------------+----------+------------+
+| 312, 313   | ``8.0.39`` | 366, 367 | ``8.0.41`` |
++------------+------------+----------+------------+
+| 240        | ``8.0.36`` | 366, 367 | ``8.0.41`` |
+|            |            +----------+------------+
+|            |            | 312, 313 | ``8.0.39`` |
++------------+------------+----------+------------+
+| 196        | ``8.0.34`` | None     |            |
++------------+------------+----------+------------+
+| 151        | ``8.0.32`` | 240      | ``8.0.36`` |
+|            |            +----------+------------+
+|            |            | 196      | ``8.0.34`` |
++------------+------------+----------+------------+
+```
+
+Due to an upstream issue with MySQL Server version `8.0.35`, Charmed MySQL versions below [Revision 240](https://github.com/canonical/mysql-operator/releases/tag/rev240) **cannot** be upgraded using Juju's `refresh`.
+
+To upgrade from older versions to Revision 240 or higher, the data must be migrated manually. See: [](/how-to/development/migrate-data-via-backup-restore).
+
+### Juju version upgrade
+
+Before refreshing the charm, make sure to check the [](/reference/releases) page to see if there any requirements for the new revision, such as a Juju version upgrade.
+
+* [](/how-to/refresh/upgrade-juju)
+
+## Refresh guides
+
+To refresh a **single cluster**, see:
+
+* [](/how-to/refresh/single-cluster/refresh-single-cluster)
+* [](/how-to/refresh/single-cluster/roll-back-single-cluster)
+
+To refresh a **multi-cluster** deployment, see
+
+* [](/how-to/refresh/multi-cluster/refresh-multi-cluster)
+* [](/how-to/refresh/multi-cluster/roll-back-multi-cluster)
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+:hidden:
+
+Single cluster <single-cluster/index>
+Multi-cluster <multi-cluster/index>
+Upgrade Juju <upgrade-juju>
+```
+
+<!--Links-->
+
+[cross]: https://img.icons8.com/?size=16&id=CKkTANal1fTY&format=png&color=D00303
+[check]: https://img.icons8.com/color/20/checkmark--v1.png
\ No newline at end of file
diff --git a/docs/how-to/refresh/multi-cluster/index.md b/docs/how-to/refresh/multi-cluster/index.md
new file mode 100644
index 0000000000..d8b642acdc
--- /dev/null
+++ b/docs/how-to/refresh/multi-cluster/index.md
@@ -0,0 +1,8 @@
+# Refresh a multi-cluster deployment
+
+```{toctree}
+:titlesonly:
+
+Refresh <refresh-multi-cluster>
+Roll back <roll-back-multi-cluster>
+```
\ No newline at end of file
diff --git a/docs/how-to/refresh/multi-cluster/refresh-multi-cluster.md b/docs/how-to/refresh/multi-cluster/refresh-multi-cluster.md
new file mode 100644
index 0000000000..cd8cf2598d
--- /dev/null
+++ b/docs/how-to/refresh/multi-cluster/refresh-multi-cluster.md
@@ -0,0 +1,33 @@
+# How to refresh a multi-cluster deployment
+
+A MySQL multi-cluster deployment (also known as a cluster set) can be upgraded by performing a refresh of each cluster individually.
+
+This guide goes over the steps and important considerations before refreshing multiple MySQL clusters.
+
+## Determine cluster order
+
+To upgrade a multi-cluster deployment, each cluster must be refreshed one by one - starting with the standby clusters.
+
+**The primary cluster must be the last one to get refreshed.**
+
+This ensures that availability is not affected if there are any issues with the upgrade. Refreshing all the standbys first also minimizes the cost of the leader re-election process.
+
+To identify the primary cluster, run
+
+```shell
+juju run mysql/<n> get-cluster-status cluster-set=true
+```
+
+## Refresh each cluster
+
+For each cluster, follow the instructions in [](/how-to/refresh/single-cluster/refresh-single-cluster).
+
+**Perform a health check before proceeding to the next cluster.**
+
+Use the [`get-cluster-status`](https://charmhub.io/mysql/actions#get-cluster-status) Juju action to check that everything is healthy after refreshing a cluster.
+
+## Roll back
+
+If something goes wrong, roll back the cluster. See: [](/how-to/refresh/single-cluster/roll-back-single-cluster)
+
+
diff --git a/docs/how-to/refresh/multi-cluster/roll-back-multi-cluster.md b/docs/how-to/refresh/multi-cluster/roll-back-multi-cluster.md
new file mode 100644
index 0000000000..525040342a
--- /dev/null
+++ b/docs/how-to/refresh/multi-cluster/roll-back-multi-cluster.md
@@ -0,0 +1,7 @@
+# Roll back a multi-cluster deployment
+
+A multi-cluster rollback is the same as a single-cluster rollback, but repeated for each cluster that was fully or partially upgraded.
+
+```{include} ../single-cluster/roll-back-single-cluster.md
+    :start-after: "How to roll back a single cluster"
+```
\ No newline at end of file
diff --git a/docs/how-to/refresh/single-cluster/index.md b/docs/how-to/refresh/single-cluster/index.md
new file mode 100644
index 0000000000..a33c11d90e
--- /dev/null
+++ b/docs/how-to/refresh/single-cluster/index.md
@@ -0,0 +1,8 @@
+# Refresh a single cluster
+
+```{toctree}
+:titlesonly:
+
+Refresh <refresh-single-cluster>
+Roll back <roll-back-single-cluster>
+```
\ No newline at end of file
diff --git a/docs/how-to/upgrade/perform-a-minor-upgrade.md b/docs/how-to/refresh/single-cluster/refresh-single-cluster.md
similarity index 55%
rename from docs/how-to/upgrade/perform-a-minor-upgrade.md
rename to docs/how-to/refresh/single-cluster/refresh-single-cluster.md
index a312be7211..da750cf846 100644
--- a/docs/how-to/upgrade/perform-a-minor-upgrade.md
+++ b/docs/how-to/refresh/single-cluster/refresh-single-cluster.md
@@ -1,41 +1,32 @@
-# How to perform a minor upgrade
+# How to refresh a single cluster
 
-**Example**: MySQL 8.0.33 -> MySQL 8.0.34<br/>
-(including charm revision bump: e.g. Revision 193 -> Revision 196)
-
-This is part of the [Upgrade section](/how-to/upgrade/index). Refer to the landing page for more information and an overview of the content.
+This guide covers refresh for single cluster MySQL deployments. To refresh a multi-cluster deployment, see [](/how-to/refresh/multi-cluster/refresh-multi-cluster) first.
 
 ## Important information
 
-We strongly recommend to **NOT** perform any other extraordinary operations on a Charmed MySQL cluster while upgrading. These may be (but not limited to) the following:
+**Check if your current Juju version is compatible with the new charm version**.
 
-1. Adding or removing units
-2. Creating or destroying new relations
-3. Changes in workload configuration
-4. Upgrading other connected/related/integrated applications simultaneously
+For information about charm versions, see [](/reference/releases).
 
-Concurrency with other operations is not supported, and it can lead the cluster into inconsistent states.
+To upgrade Juju, see [](/how-to/refresh/upgrade-juju).
 
-```{caution}
-Make sure to have a backup of your data when running any type of upgrades!
-See: [How to create a backup](/how-to/back-up-and-restore/create-a-backup)
-```
+**Create and test a backup of your data before running any type of refresh.** See [](/how-to/back-up-and-restore/create-a-backup).
 
-It is recommended to deploy your application in conjunction with [Charmed MySQL Router](https://charmhub.io/mysql-router). This will ensure minimal service disruption, if any.
+**It is recommended to integrate your application with [Charmed MySQL Router](https://charmhub.io/mysql-router).** This will ensure minimal service disruption, if any.
 
-## Summary of the upgrade steps
+## Summary of the refresh steps
 
-1. [**Collect**](step-1-collect) all necessary pre-upgrade information. It will be necessary for the rollback (if requested). Do not skip this step!
-2. [**Prepare**](step-2-prepare) the Charmed MySQL application for the in-place upgrade
-3. [**Upgrade**](step-3-upgrade). Once started all units in a cluster will be executed sequentially. The upgrade will be aborted (paused) if the unit upgrade has failed.
+1. [**Collect**](step-1-collect) all necessary pre-refresh information. It will be necessary for the rollback (if requested). Do not skip this step!
+2. [**Prepare**](step-2-prepare) the Charmed MySQL application for the in-place refresh
+3. [**Refresh**](step-3-refresh). Once started all units in a cluster will be executed sequentially. The refresh will be aborted (paused) if the unit refresh has failed.
 4. Consider a [**rollback**](step-4-rollback-optional) in case of disaster. Please inform and include us in your case scenario troubleshooting to trace the source of the issue and prevent it in the future. [Contact us](/reference/contacts)!
-5. [Post-upgrade **check**](step-5-check). Make sure all units are in a healthy state.
+5. [Post-refresh **check**](step-5-check). Make sure all units are in a healthy state.
 
 (step-1-collect)=
 ## Step 1: Collect
 
 ```{note}
-This step is only valid when deploying from [charmhub](https://charmhub.io/). 
+This step is only valid when deploying from [Charmhub](https://charmhub.io/mysql). 
 
 If a [local charm](https://juju.is/docs/sdk/deploy-a-charm) is deployed (revision is small, e.g. 0-10), make sure the proper/current local revision of the `.charm` file is available BEFORE going further. You might need it for a rollback.
 ```
@@ -44,10 +35,10 @@ The first step is to record the revision of the running application as a safety
 
 ```shell
 Model    Controller  Cloud/Region         Version  SLA          Timestamp
-default  vmc         localhost/localhost  2.9.44   unsupported  17:58:37Z
+default  vmc         localhost/localhost  3.5.2    unsupported  17:58:37Z
 
 App    Version          Status  Scale  Charm  Channel  Rev  Exposed  Message
-mysql  8.0.33-0ubun...  active      3  mysql           182  no       
+mysql  8.0.39-0ubun...  active      3  mysql           182  no       
 
 Unit       Workload  Agent  Machine  Public address  Ports               Message
 mysql/9    active    idle   13       10.169.158.70   3306/tcp,33060/tcp  
@@ -65,7 +56,7 @@ For this example, the current revision is `182`. Store it safely to use in case
 (step-2-prepare)=
 ## Step 2: Prepare
 
-Before running the [`juju refresh`](https://juju.is/docs/juju/juju-refresh) command, it’s necessary to run the `pre-upgrade-check` action against the leader unit:
+Before running the [`juju refresh`](https://juju.is/docs/juju/juju-refresh) command, it’s necessary to run the `pre-upgrade-check` action against the [leader unit](https://documentation.ubuntu.com/juju/latest/reference/unit/index.html#leader-unit):
 
 ```shell
 juju run mysql/leader pre-upgrade-check
@@ -73,7 +64,7 @@ juju run mysql/leader pre-upgrade-check
 
 The output of the action should look like:
 
-```shell
+```yaml
 unit-mysql-10:
   ...
   results: {}
@@ -81,41 +72,60 @@ unit-mysql-10:
   ...
 ```
 
-The action will configure the charm to minimize the amount of primary switchover, among other preparations for a safe upgrade process. After successful execution, the charm is ready to be upgraded.
+The action will configure the charm to minimize the amount of primary switchover, among other preparations for a safe refresh process. After successful execution, the charm is ready to be refreshed.
 
-(step-3-upgrade)=
-## Step 3: Upgrade
+(step-3-refresh)=
+## Step 3: Refresh
 
-Use the [`juju refresh`](https://juju.is/docs/juju/juju-refresh) command to trigger the charm upgrade process.
+If you are refreshing multiple clusters, make sure to refresh the standby clusters first. See [](/how-to/refresh/multi-cluster/refresh-multi-cluster) for more information.
 
-Example with channel selection
+Use the [`juju refresh`](https://juju.is/docs/juju/juju-refresh) command to trigger the charm refresh process. 
+
+Example with channel selection:
 
 ```shell
-juju refresh mysql --channel 8.0/edge
+juju refresh mysql --channel 8.0/stable
 ```
 
-Example with specific revision selection
+Example with specific revision selection:
 
 ```shell
-juju refresh mysql --revision=183
+juju refresh mysql --revision=366
 ```
 
-Example with a local charm file
+Example with a local charm file:
 
 ```shell
 juju refresh mysql --path ./mysql_ubuntu-22.04-amd64.charm
 ```
 
-All units are going to be refreshed (i.e. receive new charm content), and the upgrade will execute one unit at the time. 
+```{admonition} During an ongoing refresh
+:class: warning
+
+**Do NOT perform any other extraordinary operations on the cluster**, such as:
+
+* Adding or removing units
+* Creating or destroying new relations
+* Changes in workload configuration
+* Refreshing other connected/related/integrated applications simultaneously
+
+Concurrency with other operations is not supported, and it can lead the cluster into inconsistent states.
+
+**Do NOT trigger a rollback**. Status changes during the process are expected (e.g. `waiting`, `maintenance`, `active`) 
+
+Make sure the refresh has failed/stopped and cannot be continued before triggering a rollback.
+```
+
+Once the `refresh` command is executed, all units will receive new charm content. The refresh will run on one unit at a time. 
 
 `juju status` will look like similar to the output below:
 
 ```shell
 Model    Controller  Cloud/Region         Version  SLA          Timestamp
-default  vmc         localhost/localhost  2.9.44   unsupported  18:10:30Z
+default  vmc         localhost/localhost  3.5.2    unsupported  18:10:30Z
 
 App    Version          Status  Scale  Charm  Channel  Rev  Exposed  Message
-mysql  8.0.33-0ubun...  active      3  mysql             7  no       
+mysql  8.0.39-0ubun...  active      3  mysql             7  no       
 
 Unit       Workload     Agent      Machine  Public address  Ports               Message
 mysql/9    waiting      idle       13       10.169.158.70   3306/tcp,33060/tcp  other units upgrading first...
@@ -128,16 +138,16 @@ Machine  State    Address         Inst id         Series  AZ  Message
 13       started  10.169.158.70   juju-b72e25-13  jammy       Running
 ```
 
-After each unit completes the upgrade, the message `upgrade completed` is displayed, and the next unit follows.
+After each unit completes the refresh, the message `refresh completed` is displayed, and the next unit follows.
 
-Example `juju status` during an upgrade:
+Example `juju status` during an refresh:
 
 ```shell
 Model    Controller  Cloud/Region         Version  SLA          Timestamp
-default  vmc         localhost/localhost  2.9.44   unsupported  18:11:21Z
+default  vmc         localhost/localhost  3.5.2    unsupported  18:11:21Z
 
 App    Version          Status  Scale  Charm  Channel  Rev  Exposed  Message
-mysql  8.0.33-0ubun...  active      3  mysql             7  no       
+mysql  8.0.39-0ubun...  active      3  mysql             7  no       
 
 Unit       Workload     Agent      Machine  Public address  Ports               Message
 mysql/9    maintenance  executing  13       10.169.158.70   3306/tcp,33060/tcp  upgrading snap...
@@ -150,40 +160,29 @@ Machine  State    Address         Inst id         Series  AZ  Message
 13       started  10.169.158.70   juju-b72e25-13  jammy       Running
 ```
 
-**Do NOT trigger `rollback` procedure during the running `upgrade` procedure.**
-It is expected to have some status changes during the process: `waiting`, `maintenance`, `active`. 
-
-Make sure `upgrade` has failed/stopped and cannot be fixed/continued before triggering `rollback`!
-
 **Please be patient during huge installations.**
-Each unit should recover shortly after the upgrade, but time can vary depending on the amount of data written to the cluster while the unit was not part of it. 
+Each unit should recover shortly after the refresh, but time can vary depending on the amount of data written to the cluster while the unit was not part of it. 
 
 **Incompatible charm revisions or dependencies will halt the process.**
-After a `juju refresh`, if there are any version incompatibilities in charm revisions, its dependencies, or any other unexpected failure in the upgrade process, the upgrade process will be halted and enter a failure state.
+After a `juju refresh`, if there are any version incompatibilities in charm revisions, its dependencies, or any other unexpected failure in the refresh process, the refresh will be halted and enter a failure state.
 
 (step-4-rollback-optional)=
-## Step 4: Rollback (optional)
+## Step 4: Roll back
 
-The step must be skipped if the upgrade went well! 
+If there was an issue with the refresh, even if the underlying MySQL cluster continues to work, it’s important to roll back the charm to the previous revision. 
 
-If there was an issue with the upgrade, even if the underlying MySQL cluster continues to work, it’s important to roll back the charm to the previous revision. That way, the update can be attempted again after a further inspection of the failure. 
+The update can be attempted again after a further inspection of the failure. 
 
-> See: [How to perform a minor rollback](/how-to/upgrade/perform-a-minor-rollback) 
+See: [](/how-to/refresh/single-cluster/roll-back-single-cluster) 
 
 (step-5-check)=
-## Step 5: Check
+## Step 5: Check cluster health
 
-Future improvements are [planned](https://warthogs.atlassian.net/browse/DPE-2621) to check the state of a cluster on a low level. 
+<!--TODO: Jira issue referenced below is no longer available. Is this referring to get-cluster-status? Should we recommend this check instead of juju status?
 
-For now, use `juju status` to make sure the cluster [state](/reference/charm-statuses) is OK.
+  Future improvements are [planned](https://warthogs.atlassian.net/browse/DPE-2621) to check the state of a cluster on a low level. 
+-->
 
-<!---
-**TODOs:**
+Use `juju status` to make sure the cluster [state](/reference/charm-statuses) is OK.
 
-* Clearly describe "failure state"!!!
-* How to check progress of upgrade (is it failed or running?)?
-* Hints how to fix failed upgrade? mysql-shell hints....
-* Describe pre-upgrade check: free space, etc.
-* Hint to add extra unit to upgrade first keeping cluster "safe".
---->
 
diff --git a/docs/how-to/upgrade/perform-a-minor-rollback.md b/docs/how-to/refresh/single-cluster/roll-back-single-cluster.md
similarity index 58%
rename from docs/how-to/upgrade/perform-a-minor-rollback.md
rename to docs/how-to/refresh/single-cluster/roll-back-single-cluster.md
index ddee68647e..df99280244 100644
--- a/docs/how-to/upgrade/perform-a-minor-rollback.md
+++ b/docs/how-to/refresh/single-cluster/roll-back-single-cluster.md
@@ -1,16 +1,15 @@
-# How to perform a minor rollback
+# How to roll back a single cluster
 
-**Example**: MySQL 8.0.34 -> MySQL 8.0.33<br/>
-(including charm revision bump: e.g Revision 43 -> Revision 42)
+After a `juju refresh`, if there are any version incompatibilities in charm revisions, its dependencies, or any other unexpected failure in the refresh process, the process will be halted and enter a failure state.
 
-After a `juju refresh`, if there are any version incompatibilities in charm revisions, its dependencies, or any other unexpected failure in the upgrade process, the process will be halted and enter a failure state.
+Even if the underlying MySQL cluster continues to work, it’s important to roll back the charm to a previous revision so that an update can be attempted after further inspection of the failure.
 
-Even if the underlying MySQL cluster continue to work, it’s important to roll back the charm to a previous revision so that an update can be attempted after further inspection of the failure.
-
-```{caution}
-**Warning:** Do NOT trigger `rollback` during the running `upgrade` action! It may cause an  unpredictable MySQL cluster state!
+```{warning}
+Do NOT trigger `rollback` during a running `refresh` action! It may cause an  unpredictable MySQL cluster state!
 ```
 
+This guide covers rollbacks for single cluster MySQL deployments. Before rolling back a **multi-cluster** refresh, see [](/how-to/refresh/multi-cluster/refresh-multi-cluster).
+
 ## Summary of the rollback steps
 
 1. **Prepare** the Charmed MySQL application for the in-place rollback.
@@ -19,9 +18,10 @@ Even if the underlying MySQL cluster continue to work, it’s important to roll
 
 ## Step 1: Prepare
 
-To execute a rollback, we use a similar procedure to the upgrade. The difference is the charm revision to upgrade to. In this guide's example, we will refresh the charm back to revision `182`.
+To execute a rollback, we use a similar procedure to the refresh. The difference is the charm revision to refresh to. In this guide's example, we will refresh the charm back to revision `312`.
+
+It is necessary to re-run `pre-upgrade-check` action on the leader unit in order to enter the refresh recovery state:
 
-It is necessary to re-run `pre-upgrade-check` action on the leader unit in order to enter the upgrade recovery state:
 ```shell
 juju run mysql/leader pre-upgrade-check
 ```
@@ -29,15 +29,18 @@ juju run mysql/leader pre-upgrade-check
 ## Step 2: Rollback
 
 When using charm from charmhub:
+
 ```shell
-juju refresh mysql --revision=182
+juju refresh mysql --revision=312
 ```
 
 When deploying from a local charm file, one must have the previous revision charm file and run the following command:
+
 ```shell
 juju refresh mysql --path=./mysql_ubuntu-22.04-amd64.charm
 ```
-> where `mysql_ubuntu-22.04-amd64.charm` is the previous revision charm file.
+
+where `mysql_ubuntu-22.04-amd64.charm` is the previous revision charm file.
 
 The first unit will be rolled out and should rejoin the cluster after settling down. After the refresh command, the juju controller revision for the application will be back in sync with the running Charmed MySQL revision.
 
@@ -46,4 +49,3 @@ The first unit will be rolled out and should rejoin the cluster after settling d
 Future [improvements are planned](https://warthogs.atlassian.net/browse/DPE-2621) to check the state on pods/clusters on a low level. 
 
 For now, check `juju status` to make sure the cluster [state](/reference/charm-statuses) is OK.
-
diff --git a/docs/how-to/upgrade/upgrade-juju.md b/docs/how-to/refresh/upgrade-juju.md
similarity index 95%
rename from docs/how-to/upgrade/upgrade-juju.md
rename to docs/how-to/refresh/upgrade-juju.md
index b1a4eafbc5..56d8efdc0c 100644
--- a/docs/how-to/upgrade/upgrade-juju.md
+++ b/docs/how-to/refresh/upgrade-juju.md
@@ -1,15 +1,15 @@
-# Upgrade Juju for a new database revision
+(upgrade-juju)=
+# How to upgrade Juju for a new database revision
 
 This guide contains instructions to perform a patch or major/minor Juju upgrade to a controller and model containing a database charm. 
 
-For more background about Juju upgrades in the context of database charms, check  [Explanation > Juju > Juju upgrades](/explanation/juju).
-
+For more background about Juju upgrades in the context of database charms, see [](explanation-juju-upgrades).
 
 ## Patch version upgrade
-A [PATCH](https://semver.org/#summary) Juju upgrade (e.g. Juju `3.1.5` → `3.1.8`) can be easily applied in-place.
 
+A [PATCH](https://semver.org/#summary) Juju upgrade (e.g. Juju `3.1.5` → `3.1.8`) can be easily applied in-place.
 
-```text
+```shell
 sudo snap refresh juju 
 
 juju upgrade-controller 
@@ -18,13 +18,15 @@ juju upgrade-controller
 juju upgrade-model 
 # wait until complete
 ```
-Once the model has finished upgrading, you can proceed with the [charm upgrade](/how-to/upgrade/perform-a-minor-upgrade).
 
+Once the model has finished upgrading, you can proceed with the [charm upgrade](/how-to/refresh/single-cluster/refresh-single-cluster).
 
 ## Major/minor version upgrade
+
 The easiest way to perform a [MAJOR/MINOR](https://semver.org/#summary) Juju version upgrade (e.g. Juju `3.1.8` → `3.5.1`),  is to update the controller and model to the new version, then [migrate](https://juju.is/docs/juju/juju-migrate) the model.
 
 ### Commands summary
+
 The following is a summary of commands that upgrade Juju to `3.5/stable`:
 
 ```text
@@ -38,9 +40,10 @@ juju upgrade-model -m lxd_3.5.1:mydatabase
 # wait until complete
 ```
 
-Once the model has finished upgrading, you can proceed with the [charm upgrade](/how-to/upgrade/perform-a-minor-upgrade).
+Once the model has finished upgrading, you can proceed with the [charm upgrade](/how-to/refresh/single-cluster/refresh-single-cluster).
 
 ### Example
+
 This section goes over the commands listed in the summary above with more details and sample outputs.
 
 <details><summary>In this example scenario, we have <code>mysql</code> deployed in model <code>mydatabase</code> on the Juju controller <code>lxd_3.1.8</code>.</summary> 
@@ -181,7 +184,7 @@ mydatabase  lxd_3.5.1   localhost/localhost  3.5.1    unsupported  22:59:01+02:0
 
 At this stage, the application continues running under the supervision of the new controller version and is ready to be refreshed to the new charm revision.
 
-You can now proceed with the [charm upgrade](/how-to/upgrade/perform-a-minor-upgrade).
+You can now proceed with the [charm upgrade](/how-to/refresh/single-cluster/refresh-single-cluster).
 
 ## Resources
 Further documentation about Juju upgrades: 
diff --git a/docs/how-to/upgrade/index.md b/docs/how-to/upgrade/index.md
deleted file mode 100644
index fdda0f1b04..0000000000
--- a/docs/how-to/upgrade/index.md
+++ /dev/null
@@ -1,36 +0,0 @@
-# Upgrade
-
-This section contains documentation about performing upgrades (and rollbacks) on:
-* [MySQL Server (workload)](mysql-upgrades)
-* [Juju version](#juju-upgrades)
-
-(mysql-upgrades)=
-## MySQL upgrades
-There are two types of in-place workload upgrades:
-* **Major upgrades** -  E.g. MySQL `8.0` -> MySQL `9.0`
-  * *Not supported*
-* **Minor upgrades** -  E.g. MySQL `8.0.33` -> `8.0.34` (includes charm revision bump)
-  * See: [How to perform a minor upgrade](/how-to/upgrade/perform-a-minor-upgrade)
-  * See: [How to perform a minor rollback](/how-to/upgrade/perform-a-minor-rollback)
-
-```{caution}
-This charm only supports in-place **minor** upgrades. 
-
-To upgrade to a major MySQL version, one must install a new cluster separately and migrate the data from the old to the new installation. This documentation will be updated with the migration instructions when a new MySQL version becomes available.
-```
-(juju-upgrades)=
-## Juju upgrades
-
-New revisions of the charm may require that you do a major or minor Juju upgrade.
-
-See the guide: [How to upgrade Juju](/how-to/upgrade/upgrade-juju)
-
-```{toctree}
-:titlesonly:
-:maxdepth: 2
-:hidden:
-
-Upgrade Juju <upgrade-juju>
-Perform a minor rollback <perform-a-minor-rollback>
-Perform a minor upgrade <perform-a-minor-upgrade>
-```
diff --git a/docs/redirects.txt b/docs/redirects.txt
index b002b59cfa..de82ea988a 100644
--- a/docs/redirects.txt
+++ b/docs/redirects.txt
@@ -50,17 +50,17 @@ h-enable-monitoring/ how-to/monitoring-cos/enable-monitoring
 h-enable-alert-rules/ how-to/monitoring-cos/enable-alert-rules
 h-enable-tracing/ how-to/monitoring-cos/enable-tracing
 
-h-upgrade/ how-to/upgrade/
-h-upgrade-juju/ how-to/upgrade/upgrade-juju
-h-upgrade-minor/ how-to/upgrade/perform-a-minor-upgrade
-h-rollback-minor/ how-to/upgrade/perform-a-minor-rollback
-
-h-async/ how-to/cross-regional-async-replication/
-h-async-deployment/ how-to/cross-regional-async-replication/deploy
-h-async-clients/ how-to/cross-regional-async-replication/clients
-h-async-failover/ how-to/cross-regional-async-replication/switchover-failover
-h-async-recovery/ how-to/cross-regional-async-replication/recovery
-h-async-removal/ how-to/cross-regional-async-replication/removal
+h-upgrade/ how-to/refresh/
+h-upgrade-juju/ how-to/refresh/upgrade-juju
+h-upgrade-minor/ how-to/refresh/single-cluster/refresh-single-cluster
+h-rollback-minor/ how-to/refresh/single-cluster/roll-back-single-cluster
+
+h-async/ how-to/cluster-cluster-replication/
+h-async-deployment/ how-to/cluster-cluster-replication/deploy
+h-async-clients/ how-to/cluster-cluster-replication/clients
+h-async-failover/ how-to/cluster-cluster-replication/switchover-failover
+h-async-recovery/ how-to/cluster-cluster-replication/recovery
+h-async-removal/ how-to/cluster-cluster-replication/removal
 
 h-development-integrate/ how-to/development/integrate-with-your-charm
 h-migrate-mysqldump/ how-to/development/migrate-data-via-mysqldump
diff --git a/docs/reference/charm-statuses.md b/docs/reference/charm-statuses.md
index fff40863fe..04f6895bcb 100644
--- a/docs/reference/charm-statuses.md
+++ b/docs/reference/charm-statuses.md
@@ -12,7 +12,7 @@ The charm follows [standard Juju applications statuses](https://documentation.ub
 | **waiting** | any | Charm is waiting for relations to be finished | No actions required |
 | **maintenance** | any | Charm is performing the internal maintenance (e.g. cluster re-configuration) | No actions required |
 | **blocked** | any | The manual user activity is required! | Follow the message hints (see below) |
-| **blocked** | Failed to set up relation | The relation between two applications failed to be created. Most probably it is a regression of the recent changes in applications | Check Juju [debug-log](https://juju.is/docs/olm/juju-debug-log). Increase debug level and reproduce the issue. Report as an issue with debug logs attached (if reproducible). Consider to try previous revision for both applications |
+| **blocked** | Failed to set up relation | The relation between two applications failed to be created. Most probably it is a regression of the recent changes in applications | Check Juju [debug-log](https://documentation.ubuntu.com/juju/3.6/reference/juju-cli/list-of-juju-cli-commands/debug-log/). Increase debug level and reproduce the issue. Report as an issue with debug logs attached (if reproducible). Consider to try previous revision for both applications |
 | **blocked** | Failed to initialize MySQL relation | The same as "Failed to set up relation" | See "Failed to set up relation" |
 | **blocked** | Failed to remove relation user | TODO: clean manually? How to unblock? | |
 | **blocked** | Failed to install and configure MySQL | TODO |  |
diff --git a/docs/reference/releases.md b/docs/reference/releases.md
index d1e676789d..e4488a470a 100644
--- a/docs/reference/releases.md
+++ b/docs/reference/releases.md
@@ -14,7 +14,7 @@ For a given release, this table shows:
    > This charm still supports older versions of Juju down to 2.9. See the [Juju section of the system requirements](/reference/system-requirements) for more details.
 * Support for specific features
 
-| Release | MySQL version | Juju version | [TLS encryption](/how-to/enable-tls)* | [COS monitoring](/how-to/monitoring-cos/enable-monitoring) | [Minor version upgrades](/how-to/upgrade/perform-a-minor-upgrade) | [Cross-regional async replication](/how-to/cross-regional-async-replication/deploy) |
+| Release | MySQL version | Juju version | [TLS encryption](/how-to/enable-tls)* | [COS monitoring](/how-to/monitoring-cos/enable-monitoring) | [In-place upgrades](/how-to/refresh/single-cluster/refresh-single-cluster) | [Cluster-cluster replication](/how-to/cluster-cluster-replication/deploy) |
 |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
 | [366], [367] | 8.0.41 | `3.4.3+` | ![check] | ![check] | ![check] | ![check] |
 | [312], [313] | 8.0.39 | `3.4.3+` | ![check] | ![check] | ![check] | ![check] |
diff --git a/docs/reference/system-requirements.md b/docs/reference/system-requirements.md
index c4cf43a375..f0df4ad953 100644
--- a/docs/reference/system-requirements.md
+++ b/docs/reference/system-requirements.md
@@ -19,7 +19,7 @@ The charm supports several Juju releases from [2.9 LTS](https://documentation.ub
 | ![3.1] | `3.1.6+` | [196]+ |     |
 | ![2.9 LTS] | `2.9.32+` | [151]+ |     |
 
-See the guide [How to upgrade Juju for a new database revision](/how-to/upgrade/upgrade-juju).
+See the guide [How to upgrade Juju for a new database revision](/how-to/refresh/upgrade-juju).
 
 ### MySQL Group replication requirements
 * In order to integrate with this charm, every table created by the integrated application **must have a primary key**. This is required by the [group replication plugin](https://dev.mysql.com/doc/refman/8.0/en/group-replication-requirements.html) enabled in this charm.
diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md
index 5f20e6477c..daaec1c9cf 100644
--- a/docs/tutorial/index.md
+++ b/docs/tutorial/index.md
@@ -132,7 +132,7 @@ Machine  State    Address         Inst id        Base          AZ  Message
 1        started  10.234.188.135  juju-ff9064-0  ubuntu@22.04      Running
 ```
 
-You can also watch juju logs with the [`juju debug-log`](https://juju.is/docs/juju/juju-debug-log) command.
+You can also watch juju logs with the [`juju debug-log`](https://documentation.ubuntu.com/juju/3.6/reference/juju-cli/list-of-juju-cli-commands/debug-log/) command.
 
 ## Access MySQL