docs: v10 migration guide (#1107)

## 🧰 Changes

in [#1106](#1106), i removed the
v10 migration guide language so we can ship v9 properly without being
blocked by the `rdme openapi` replacement command status. this PR adds
back that language.

see #1113 for the sequencing of all
of this.

documentation/migration-guide.md

@@ -28,12 +28,71 @@ npx markdown-toc documentation/migration-guide.md --maxdepth 2 --bullets="-" -i
 ## Migrating to `rdme@10`
 
 <!-- prettier-ignore-start -->
-> [!WARNING]
-> `rdme@10` has not been released yet, so this section is still under construction.
->
-> [Please verify that you're looking at the latest docs for v9](https://github.com/readmeio/rdme/tree/v9/documentation/migration-guide.md). If you're using ReadMe Refactored, stay tuned!
+> [!NOTE]
+> `rdme@10` has not been released yet, so the following section is subject to change. If you're using ReadMe Refactored, stay tuned!
+<!-- prettier-ignore-end -->
+
+### Overview
+
+A [bi-directional syncing](https://docs.readme.com/main/docs/bi-directional-sync) workflow with [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored) mostly eliminates the need for a tool like `rdme`. For syncing Markdown files, syncing API definitions, and managing project hierarchy (e.g., project versions and categories) with ReadMe Refactored, you'll want to set up bi-directional syncing.
+
+`rdme@10` is recommended for the following use cases:
+
+- Syncing your API definition (generated via a build process and not tracked via Git) to your ReadMe Refactored-enabled project
+- Syncing Markdown files to the Changelog for your ReadMe Refactored-enabled project
+
+<!-- prettier-ignore-start -->
+> [!NOTE]
+> `rdme@10` only works with ReadMe projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). If you are not yet using ReadMe Refactored, [you'll want to use `rdme@9`](#migrating-to-rdme9).
 <!-- prettier-ignore-end -->
 
+### Upgrading to `v10`
+
+#### Step 1: Upgrade via `npm`
+
+To install this version of the `rdme` CLI globally, run the following command:
+
+```sh
+npm install -g rdme@10
+```
+
+More installation options can be found in [our docs](https://github.com/readmeio/rdme/tree/v10?tab=readme-ov-file#setup).
+
+#### Step 2: Update GitHub Actions Workflow
+
+If you're using the `rdme` GitHub Action, update your GitHub Actions workflow file so your `rdme` usage uses the `v10` reference like so:
+
+```yaml
+- uses: readmeio/rdme@v10
+  with:
+    rdme: openapi validate petstore.json
+```
+
+#### Step 3: Address `v10` Breaking Changes
+
+1. **Enable Bi-Directional Syncing** _(recommended)_
+
+   We recommend setting up [bi-directional syncing](https://docs.readme.com/main/docs/bi-directional-sync) for managing your Markdown files, API definitions and project hierarchy.
+
+2. **Command Replacements**
+
+   - Replace: `openapi` → `openapi upload` (see more in step 3 below)
+   - Replace: `categories` → use [Git-based workflow](https://docs.readme.com/main/docs/bi-directional-sync)
+   - Replace: `custompages` → use [Git-based workflow](https://docs.readme.com/main/docs/bi-directional-sync)
+   - Replace: `docs` (and its `guides` alias) → use [Git-based workflow](https://docs.readme.com/main/docs/bi-directional-sync)
+   - Replace: `versions` → use [Git-based workflow](https://docs.readme.com/main/docs/bi-directional-sync)
+   - Remove: `open`
+
+3. **`openapi` has been replaced by `openapi upload`**
+
+   If you previously uploaded API definitions to ReadMe via `rdme openapi`, the command is now `rdme openapi upload`. There are now two main updates:
+
+   - There is no prompt to select your ReadMe project version if you omit the `--version` flag. It now defaults to `stable` (i.e., your main ReadMe project version).
+
+   - Previously with `openapi`, the `--id` flag was an ObjectID that required an initial upload to ReadMe, which made it difficult to upsert API definitions and manage many at scale. With `openapi upload`, the `--id` flag has been renamed to `--slug` and is now optional. The slug (i.e., the unique identifier for your API definition resource in ReadMe) is inferred from the file path or URL to your API definition.
+
+   Read more in [the `openapi upload` command docs](https://github.com/readmeio/rdme/tree/v10/documentation/commands/openapi.md#rdme-openapi-upload-spec).
+
 ## Migrating to `rdme@9`
 
 ### Overview
@@ -125,7 +184,7 @@ If you're using the `rdme` GitHub Action, update your GitHub Actions workflow fi
    - `versions`
    - `open`
 
-   The `openapi` command is deprecated and will be replaced in `rdme@10` by a command with a simpler flag setup based on community feedback.
+   The `openapi` command will be replaced by `openapi upload` and will have a simpler flag setup based on community feedback.
 
 6. **Verify any scripts that utilize raw CLI outputs**