Update requirements regarding target replica set state

docs/architecture.md

@@ -2,6 +2,8 @@
 
 Percona ClusterSync for MongoDB (PCSM) is a middleware synchronization tool that connects source and target clusters. It reads the change stream from the source cluster and applies those changes to the target cluster. 
 
+For comprehensive information on how {{pcsm.full_name}} works, refer to the section [Replication Workflows](intro.md#replication-workflows).
+
 Since PCSM operates as a standalone binary process, its placement within your infrastructure can significantly impact performance, particularly in terms of network latency, which can affect replication time. 
 
 You can deploy PCSM using one of three different architectures.

docs/install/usage.md

@@ -8,13 +8,6 @@
 
 You can interact with {{pcsm.full_name}} using the command-line interface or via the HTTP API. Read more about [{{pcsm.short}} HTTP API](../api.md).
 
-!!! note "CLI exit codes and error output"
-    The examples on the page show `{"ok": true}` as the expected output for successful commands. This is correct for successful responses. However, client subcommands now exit with a non-zero code when the server returns an error response (for example, `{"ok": false, "error": "..."}`). Previously, they exited with code `0` and printed the error JSON to **stdout**. Now, the error message is written to **stderr** and the process exits non-zero.
-
-
-## Before you start
-
-Your target MongoDB cluster may be empty or contain data. {{pcsm.short}} replicates data from the source to the target but doesn't manage the target's data. If the target already has the same data as the source, {{pcsm.short}} overwrites it. However, if the target contains different data, {{pcsm.short}} doesn't delete it during replication. This leads to inconsistencies between the source and target. To ensure consistency, manually delete any existing data from the target before starting replication.
 
 ## Start the replication
 

docs/intro.md

@@ -1,6 +1,6 @@
 # How {{pcsm.full_name}} works
 
-{{pcsm.full_name}} is a binary process that replicates data between MongoDB deployments in real time until you manually finalize it. You can also make a one-time data migration from the source to the target with near-zero downtime.
+{{pcsm.full_name}} is a binary process that replicates data between MongoDB deployments in real time until you manually finalize it. You can also make a one-time data migration from the source to the target with near zero downtime.
 
 You operate with {{pcsm.full_name}} using the [set of commands](pcsm-commands.md) or [API calls](api.md). Depending on the request it receives, {{pcsm.full_name}} has several states as shown in the following diagram:
 
@@ -43,16 +43,48 @@ The workflow for {{pcsm.short}} depends on your MongoDB deployment topology. Sel
 
     Let's use a data migration from MongoDB Atlas to Percona Server for MongoDB as an example to understand how {{pcsm.short}} works with replica sets.
 
-    You run a MongoDB Atlas 8.0.8 deployed as a replica set. You need to migrate to Percona Server for MongoDB 8.0.8-3, also a replica set. You have a strict requirement to migrate with zero downtime; therefore, using logical backups with [Percona Backup for MongoDB :octicons-link-external-16:](https://docs.percona.com/percona-backup-mongodb/features/logical.html) is not an option.
+    You run a MongoDB Atlas 8.0 deployed as a replica set. You need to migrate to the latest 8.0 release of Percona Server for MongoDB, which also supports replica sets. You have a strict requirement to migrate with near-zero downtime; therefore, using logical backups with [Percona Backup for MongoDB :octicons-link-external-16:](https://docs.percona.com/percona-backup-mongodb/features/logical.html) is not an option.
 
-    A solution is to use {{pcsm.full_name}}. MongoDB Atlas is your source. An empty Percona Server for MongoDB replica set is your target. Data migration is a resource-intensive task. Therefore, we recommend installing {{pcsm.short}} on a dedicated host closest to the target to reduce the network lag as much as possible.
+
+    A solution is to use {{pcsm.full_name}}. MongoDB Atlas is your source and a Percona Server for MongoDB replica set is your target. During startup, {{pcsm.short}} prepares the target by dropping and recreating the selected collections, which overwrites any existing data in them. Because this process can generate substantial network traffic and put additional load on the source and target, run {{pcsm.short}} on a dedicated host located as close to the target as possible to minimize latency.
 
     ### Workflow steps
 
+    The following is the workflow for {{pcsm.short}}:
+    {.power-number}
+
     1. **Set up authentication**: Create users for {{pcsm.short}} in both MongoDB deployments. Start and connect {{pcsm.short}} to your source and target using these user credentials and the `mongos` hostname and port. See [Configure authentication in MongoDB](install/authentication.md) for details.
 
-    2. **Start the replication**: Call the `start` command. {{pcsm.short}} starts copying the data from the source to the target. First it does the initial sync by cloning the data and then applying all the changes that happened since the clone start. See [Start the replication](install/usage.md#start-the-replication) for command details.
+    2. **Start the replication**
+
+        !!! info "Important"
+            During the replication startup phase:
+
+            - Only the collections selected for replication are dropped and recreated. 
+            - Existing databases and collections on the target that are not part of the sync selection **remain untouched**.
+
+        Call the `start` command. {{pcsm.short}} prepares the target collections and begins the replication process. For each selected collection, {{pcsm.short}} performs the following actions:
+        { .power-number}
+
+        1. **Drop collection on target**
+
+            If the target collection already exists, {{pcsm.short}} drops it to ensure a clean state for incoming data.
+
+        2. **Recreate collection**
+
+            The collection is recreated on the target with the same options as the source (such as capped settings, collation, validators, and other collection-level options).
+
+        3. **Create indexes**
+
+            Indexes are created on the target to match those defined on the source collection.
 
+
+        4. **Initial sync**
+
+            {{pcsm.short}} copies the documents from the source collection to the target.
+
+    See [Start the replication](install/usage.md#start-the-replication) for command details.
+
     3. **Real-time replication**: After the initial data sync, {{pcsm.short}} monitors changes in the source and replicates them to the target at runtime. You don't have to stop your source deployment—it operates as usual, accepting client requests. {{pcsm.short}} uses [change streams :octicons-link-external-16:](https://www.mongodb.com/docs/manual/changeStreams/) to track the changes to your data and replicate them to the target.
 
     4. **Control replication**: You can `pause` the replication and `resume` it later. When paused, {{pcsm.short}} saves the timestamp when it stops the replication. After you resume {{pcsm.short}}, it starts watching for the changes from the moment when the replication was paused and continues real-time replication. See [Pause the replication](install/usage.md#pause-the-replication) and [Resume the replication](install/usage.md#resume-the-replication) for command details.
@@ -77,19 +109,34 @@ The workflow for {{pcsm.short}} depends on your MongoDB deployment topology. Sel
 
     ### Workflow steps
 
+    The following is the workflow for {{pcsm.short}} for sharded clusters:
+    {.power-number}
+
     1. **Set up authentication**: Create users for {{pcsm.short}} in both MongoDB deployments. Configure connection strings using `mongos` hostname and port for both source and target clusters. See [Configure authentication in MongoDB](install/authentication.md) for details.
 
-    2. **Start the replication**: Call the `start` command. You don't have to disable the balancer on the target. Before starting the data copying, {{pcsm.short}} retrieves the information about the shard keys for collections on the source cluster and creates these collections on the target with the same shard key. Then {{pcsm.short}} starts copying all data from the source to the target. First it does the initial sync by cloning the data and then applying all the changes that happened since the clone start. See [Start the replication](install/usage.md#start-the-replication) for command details.
+    2. **Apply sharding (if applicable)**
+
+        If the source collection is sharded, {{pcsm.short}} shards the target collection using the same sharding configuration.
 
-    3. **Real-time replication**: During the replication stage, {{pcsm.short}} captures change stream events from the source cluster through `mongos` and applies them to the target cluster, ensuring real-time synchronization of data changes. The target cluster's balancer handles chunk distribution. For details about sharding-specific behavior, see [Sharding behavior](sharding.md#sharding-specific-behavior).
+    3. **Start the replication**: 
 
-    4. **Control replication**: You can `pause` the replication and `resume` it later, just like with replica sets. When paused, {{pcsm.short}} saves the timestamp when it stops the replication. See [Pause the replication](install/usage.md#pause-the-replication) and [Resume the replication](install/usage.md#resume-the-replication) for command details.
+        !!! info "Important"
+            During the replication startup phase:
 
-    5. **Monitor progress**: Track the migration status in logs and using the `status` command. See [Check the replication status](install/usage.md#check-the-replication-status) for details.
+            - Only the collections selected for replication are dropped and recreated. 
+            - Existing databases and collections on the target that are not part of the sync selection **remain untouched**.
+
+        Call the `start` command. You don't have to disable the balancer on the target. Before starting the data copying, {{pcsm.short}} retrieves the information about the shard keys for collections on the source cluster and creates these collections on the target with the same shard key. Then {{pcsm.short}} starts copying all data from the source to the target. First it does the initial sync by cloning the data and then applying all the changes that happened since the clone start. See [Start the replication](install/usage.md#start-the-replication) for command details.
+
+    4. **Real-time replication**: During the replication stage, {{pcsm.short}} captures change stream events from the source cluster through `mongos` and applies them to the target cluster, ensuring real-time synchronization of data changes. The target cluster's balancer handles chunk distribution. For details about sharding-specific behavior, see [Sharding behavior](sharding.md#sharding-specific-behavior).
+
+    5. **Control replication**: You can `pause` the replication and `resume` it later, just like with replica sets. When paused, {{pcsm.short}} saves the timestamp when it stops the replication. See [Pause the replication](install/usage.md#pause-the-replication) and [Resume the replication](install/usage.md#resume-the-replication) for command details.
+
+    6. **Monitor progress**: Track the migration status in logs and using the `status` command. See [Check the replication status](install/usage.md#check-the-replication-status) for details.
 
-    6. **Finalize**: When the data migration is complete and you no longer need to run clusters in sync, call the `finalize` command to complete the migration. This makes {{pcsm.short}} finalize the replication, create the required indexes on the target, and stop. Note that finalizing is a one-time operation. If you try to start {{pcsm.short}} again, it will start data copy anew. See [Finalize the replication](install/usage.md#finalize-the-replication) for command details.
+    7. **Finalize**: When the data migration is complete and you no longer need to run clusters in sync, call the `finalize` command to complete the migration. This makes {{pcsm.short}} finalize the replication, create the required indexes on the target, and stop. Note that finalizing is a one-time operation. If you try to start {{pcsm.short}} again, it will start data copy anew. See [Finalize the replication](install/usage.md#finalize-the-replication) for command details.
 
-    7. **Cutover**: Switch your clients to connect to the target Percona Server for MongoDB cluster.
+    8. **Cutover**: Switch your clients to connect to the target Percona Server for MongoDB cluster.
 
     For detailed information about sharded cluster replication, see [Sharding support in {{pcsm.full_name}}](sharding.md).