Revert "docs: remove v10 docs (for now)"

This reverts commit cbcef0d.

documentation/migration-guide.md

@@ -28,12 +28,78 @@ 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 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`** changes
+
+   If you previously uploaded API definitions to ReadMe via `rdme openapi`, the command is now `rdme openapi upload`. There are now two main updates:
+
+   - The `--version` flag is now required.
+
+   - 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 is optional and the identifier is inferred from the file path or URL to your API definition.
+
+     See the table below to get a sense of how this identifier is inferred. As long as you maintain these directory/file names and run `rdme` from the same location relative to your file, this identifier will be preserved and any updates you make to this file will be synced to the same resource in ReadMe.
+
+     | File Path Type | Example File Path                        | Resulting Identifier in ReadMe |
+     | -------------- | ---------------------------------------- | ------------------------------ |
+     | Local File     | `docs/api/petstore.json`                 | `docs-api-petstore.json`       |
+     | URL            | `https://example.com/docs/petstore.json` | `petstore.json`                |
+
+     If you wish to override this inference behavior, you can include the `--id` flag and set it to whatever identifier you'd like.
+
 ## Migrating to `rdme@9`
 
 ### Overview