Sandboxes: add v1 to v2 migration guide

docs/learn/sandboxes/index.md

@@ -3,6 +3,8 @@ title: 'Sandboxes'
 sidebar_position: 1
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
 import PaidFeature from '../\_paid_feature.md';
 
 <PaidFeature />
@@ -13,7 +15,49 @@ Using Sandboxes currently requires installation of an external tooling available
 
 ## Installation
 
-First, download the install script for our Sandboxing tool `deployment-manager` from its Rossum GitHub repository:
+<Tabs groupId="prd">
+  <TabItem value="prd2" label="v2 (latest)" default>
+
+First, download the installation script for our Sandboxing tool `deployment-manager` from its Rossum GitHub repository:
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/rossumai/deployment-manager/main/install.sh)"
+```
+
+The script will automatically run and install the Sandboxing tool in the `~/.local/bin` folder making it available globally under the command `prd2`.
+
+To upgrade to the latest version, run:
+
+```bash
+prd2 update
+```
+
+You can find more information here: https://github.com/rossumai/deployment-manager
+
+:::warning[Using Microsoft Windows?]
+
+Sandboxes are currently not supported on Windows. You can, however, use WSL to run the `prd2` command: https://learn.microsoft.com/en-us/windows/wsl/install
+
+:::
+
+Alternatively, you can install the tool manually (advanced):
+
+```bash
+cd $(mktemp -d)
+git clone git@github.com:rossumai/deployment-manager.git
+cd deployment-manager
+
+python3 -m venv .
+source bin/activate
+python3 -m pip install pipx
+
+python3 -m pipx install . --force
+```
+
+  </TabItem>
+  <TabItem value="prd" label="v1 (deprecated)">
+
+First, download the installation script for our Sandboxing tool `deployment-manager` from its Rossum GitHub repository:
 
 ```bash
 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/rossumai/deployment-manager/main/install.sh)"
@@ -35,6 +79,9 @@ Sandboxes are currently not supported on Windows. You can, however, use WSL to r
 
 :::
 
+  </TabItem>
+</Tabs>
+
 ## Available CLI commands
 
 `prd` is a CLI tool and offers the following main commands:
@@ -139,7 +186,7 @@ ORGANIZATION:
           targets:
             # ID(s) of the `target` queue(s) (there can be none or more than one):
             - target_id: null
-              # (optional) You could override attribute on the target using `attribute_override` 
+              # (optional) You could override attribute on the target using `attribute_override`
               ## - for example you can have `name:` on `target` different from the `source`
               attribute_override:
                 name: Invoices (PROD)

docs/learn/sandboxes/migrate-v1-to-v2.md

@@ -0,0 +1,47 @@
+---
+sidebar_position: 2
+sidebar_label: 'Migrate from v1 to v2'
+title: 'Sandboxes: Migration guide from v1 to v2'
+---
+
+# Migration guide from v1 to v2
+
+The second version of our Sandboxing tool `prd` is **not backward compatible** with the first version. We recommend downloading the whole project again via the new version and going from there. You can keep using the old version (v1) command under `prd` and new version (v2) command under `prd2`.
+
+To get the latest `prd` version, run the following command:
+
+```bash
+prd update
+```
+
+This will make the `prd2` command available, so you can initialize and download the project from scratch. First, you need to initialize a new project (in the relevant folder):
+
+```bash
+prd2 init
+```
+
+This command will prompt you for the following information (your options and preferences might slightly differ):
+
+```bash
+? ORG-LEVEL directory name: sandbox-org
+? ORG ID: 255255
+? Base API URL: (e.g., https://my-org.rossum.app/api/v1) https://example.rossum.app/api/v1
+? API token: b1946ac92492d2347c6235b4d2611184
+? SUBDIR name: default
+? subdir regex (OPTIONAL):
+? Would you like to specify another **SUBDIR** inside sandbox-org? No
+? Would you like to specify another **ORG-LEVEL** directory? No
+╭──────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ Initialized a new PRD directory in "."                                                           │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+In case you made a mistake, or you want to add new folders, run the `init` command again. Later, you can pull your project configuration from the Rossum app:
+
+```bash
+prd2 pull sandbox-org
+```
+
+Learn more on how to work with this new version [here](./index.md)
+
+Once everything is migrated and working, you can delete the original folder structure (created via `prd`) and use the new one instead (created via `prd2`).