4828 update migration page

sites/platform/src/learn/tutorials/migrating.md

@@ -1,14 +1,14 @@
 ---
-title: Migrating to {{% vendor/name %}}
-description: See how to migrate your app to {{% vendor/name %}} so it's ready to be deployed.
+title: Converting to {{% vendor/name %}}
+description: See how to convert your app to {{% vendor/name %}} so it's ready to be deployed.
 keywords:
   - "set remote"
-  - migration
 ---
 
-If you already have an app running somewhere else, you want to migrate it to {{% vendor/name %}} and deploy it.
+If you already have an app running somewhere else, you want to convert it to {{% vendor/name %}} and deploy it.
 To do so, follow these steps.
 
+
 ## Before you begin
 
 You need:

sites/platform/src/projects/region-migration.md

@@ -145,16 +145,10 @@ Once the new project is running and the DNS has fully propagated, delete the old
 
 ## Alternative process
 
-**These tools are not directly supported by {{% vendor/name %}} support team, but you can open issues in their respective repositories directly.**
+We have open-sourced [the {{< vendor/name >}} cloning tool](https://github.com/upsun/clonsun), which allows you to clone a project from one region to another. This cloning tool helps you migrate most of your project assets from one region to another with some remaining manual steps like moving your domain names from one region to the other (or at the CDN level) and update your DNS records.
 
-We have open-sourced [ClonSun](https://github.com/upsun/clonsun), a tool that allows you to clone a project from one region to another.
-ClonSun helps you migrate most of your project assets from one region to another with some remaining manual steps like moving your domain names from 
-one region to the other (or at the CDN level) and update your DNS records.
+We also have [the {{< vendor/name >}} converting tool](https://github.com/upsun/convsun), which allows you to change existing configuration files to another format. It converts details from files like `services.yaml` and `routes.yaml`, and generates a new `config.yaml` file. This streamlines the conversion process by significantly reducing the manual effort required to adapt your app’s infrastructure setup.
 
-Although not directly supported by {{% vendor/name %}},
-an agency named [Contextual Code](https://www.contextualcode.com/) has built a bash migration script.
-This script automates most common configurations.
-If your site is a typical single app with a single SQL database,
-the script should take care of most of the process for you.
+Although not directly supported by {{% vendor/name %}}, an agency named [Contextual Code](https://www.contextualcode.com/) has built a bash migration script. This script automates most common configurations. If your site is a typical single app with a single SQL database, the script should take care of most of the process for you.
 
 See more at the [{{% vendor/name %}} Project Migration repository](https://gitlab.com/contextualcode/platformsh-migration).

sites/upsun/src/learn/tutorials/migrating/_index.md

@@ -1,7 +1,7 @@
 ---
-title: "Migrate your site to {{% vendor/name %}} "
+title: "Convert to {{% vendor/name %}}"
 weight: -91
-description: How to migrate from another hosting solution to {{% vendor/name %}}.
+description: How to convert from another hosting solution to {{% vendor/name %}}.
 ---
 
-Learn how you can migrate your site from another hosting solution to {{% vendor/name %}}.
+Learn how you can convert your site from another hosting solution to {{% vendor/name %}}.

sites/upsun/src/learn/tutorials/migrating/from-psh.md

@@ -1,29 +1,78 @@
 ---
-title: From Platform.sh
-description: See how to migrate your app to {{% vendor/name %}} so it's ready to be deployed.
+title: Converting from Platform.sh 
+description: See how to configure your Platform.sh app to {{% vendor/name %}} so it's ready to be deployed.
 keywords:
   - "set remote"
 ---
 
-If you already have an app running somewhere else, you want to migrate it to {{% vendor/name %}} and deploy it.
-To do so, follow these steps.
+There are two ways to change the configuration files of your Platform.sh projects to make them {{% vendor/name %}} compatible. 
+
+1. [Convert projects with the CLI](#convert-with-the-cli)
+2. [Convert projects manually](#convert-manually)
 
 ## Before you begin
 
 You need:
 
-- An app that works and is ready to be built
-- Code in Git
-- A {{< vendor/name >}} account -- if you don't already have one, [register](https://upsun.com/register/).
+- A Platform.sh application that works and is ready to be built
+- The code in Git
+- A {{< vendor/name >}} account - if you don't already have one, [register](https://upsun.com/register/).
 - The [{{< vendor/name >}} CLI](/administration/cli/_index.md) installed locally
 
-## 1. Export from previous system
+## Convert with the CLI
+
+To assist with converting applications from Platform.sh to {{% vendor/name %}}, the {{< vendor/name >}} converting tool is available as part of the {{% vendor/name %}} CLI. This feature automates the conversion of Platform.sh config files into a format required by {{% vendor/name %}}, significantly reducing manual effort.
+
+### Key functions
+The converting tool performs the following transformations:
+
+1. Generation of Upsun `config.yaml`
+- Creates a new `config.yaml` file - the primary configuration file for {{% vendor/name %}} projects.
+- Extracts relevant information from `.platform.app.yaml`, `services.yaml`, and `routes.yaml`.
+
+2. Refactoring of obsolete or incompatible fields
+Removes resource-related fields that are not applicable in {{% vendor/name %}}. This includes:
+
+- Disk values
+- Size settings (e.g., S, M, L)
+- Legacy resources blocks
+- Any deprecated or unsupported container options in the source configuration
+
+3. Mount and storage adjustments
+- Converts mounts of type local into {{% vendor/name %}}'s storage format to support horizontal scaling and infrastructure consistency.
+- Ensures that volumes and file persistence are aligned with how {{% vendor/name %}} manages data across containers.
+
+4. Reorganization of custom service configuration
+- Moves custom configuration for services such as `Solr` into the `.upsun/ directory`, which is used to hold project-specific overrides and custom assets.
+
+5. Support for cron jobs
+- Identifies cron jobs defined in Platform.sh and provides guidance on how to replicate similar functionality in {{% vendor/name %}}.
+- Flags any cron schedules requiring special support and prepares the `config.yaml` accordingly.
+
+### Example usage
+
+```bash
+uspun project:convert
+```
+You will be prompted to enter the path to the Platform.sh project you would like to convert. 
+
+The conversion then takes place within the {{% vendor/name %}} CLI and outputs the updated `config.yaml` file to the specified destination directory.
+
+## Convert manually
+
+The [CLI tool described above](#convert-with-the-cli) allows you to easily convert projects from Platform.sh to {{% vendor/name %}}, however, if your project has custom requirements that require a more hands-on approach, you can manually update your Platform.sh configuration to be compatible with {{% vendor/name %}}.
+
+Manual conversion gives you full control over the transition process and can be useful for projects with non-standard setups or advanced customizations.
+
+Follow the steps below to begin a manual migration.
+
+## 1. Export your source Platform.sh project
 
 Start by exporting everything you might need from your current app.
 This includes data in databases, files on a file system,
 and for some apps, such as Drupal, configuration that you need to export from the system into files.
 
-## 2. Create a project
+## 2. Create a new {{% vendor/name %}} project
 
 {{< codetabs >}}
 
@@ -62,7 +111,7 @@
 
 {{< /codetabs >}}
 
-## 3. Add configuration
+## 3. Convert your configuration files
 
 The exact configuration you want depends on your app.
 You likely want to configure three areas:
@@ -71,6 +120,12 @@
 - [Services](/add-services/_index.md)
 - [Routes](/define-routes/_index.md)
 
+{{< note theme="tip" >}}
+
+If you'd rather not do this manually, you can use [the converting tool](#convert-with-the-cli) via the {{% vendor/name %}} CLI to make all the necessary changes to your configuration files.
+
+{{< /note >}}
+
 When you've added your configuration, make sure to commit it to Git.
 
 ## 4. Optional: Define a resource initialization strategy
@@ -82,7 +137,7 @@
 
 Alternatively, you can [amend those default container resources](/manage-resources/adjust-resources.md) after your project is deployed.
 
-## 5. Push your code
+## 5. Push your changes
 
 The way to push your code to {{% vendor/name %}} depends on
 whether you're hosting your code with a third-party service using a [source integration](/integrations/source/_index.md).
@@ -198,7 +253,7 @@
 ```
 
 `instance` mounts on {{% vendor/name %}} are the equivalent of `local` mounts on {{% vendor/psh_ref %}}.
-To ensure continuity when migrating from {{% vendor/psh_ref %}} to {{% vendor/name %}},
+To ensure continuity when converting from {{% vendor/psh_ref %}} to {{% vendor/name %}},
 the `local` mount type works as an alias for the `instance` mount type.
 
 However, it is recommended to change the type of your `local` mounts to `instance` or another [supported mount type](/create-apps/app-reference/single-runtime-image.html#define-a-mount).

sites/upsun/src/projects/region-migration.md

@@ -137,6 +137,16 @@ Once the new project is running and the DNS has fully propagated, delete the old
 
 ## Alternative process
 
+We have open-sourced [the {{< vendor/name >}} cloning tool](https://github.com/upsun/clonsun), which allows you to clone a project from one region to another. This cloning tool helps you migrate most of your project assets from one region to another with some remaining manual steps like moving your domain names from one region to the other (or at the CDN level) and update your DNS records.
+
+We also have [the {{< vendor/name >}} converting tool](https://github.com/upsun/convsun), which allows you to change existing configuration files to another format. It converts details from files like `services.yaml` and `routes.yaml`, and generates a new `config.yaml` file. This streamlines the conversion process by significantly reducing the manual effort required to adapt your app’s infrastructure setup.
+
+{{< note theme="info" >}}
+
+To learn more about the converter tool and how it works, read the [converting projects](https://docs.upsun.com/learn/tutorials/migrating/from-psh.html) page.
+
+{{< /note >}}
+
 Although not directly supported by {{% vendor/name %}},
 an agency named [Contextual Code](https://www.contextualcode.com/) has built a bash migration script.
 This script automates most common configurations.