diff --git a/changelog.mdx b/changelog.mdx
index 691f4a644..4c4910bd2 100644
--- a/changelog.mdx
+++ b/changelog.mdx
@@ -1340,7 +1340,7 @@ noindex: true
   </Frame>
   We've introduced a new `docs.json` schema as a replacement for `mint.json`, to support better multi-level versioning, easier visual comprehension, and more consistent terminology. For more information on what's changed, [check out our blog](https://mintlify.com/blog/refactoring-mint-json-into-docs-json).
 
-  Upgrade from `mint.json` to `docs.json` with the following steps:
+  To upgrade from `mint.json` to `docs.json`:
 
   1. Make sure your CLI is the latest version
 
@@ -1348,13 +1348,9 @@ noindex: true
   npm i mint@latest -g
   ```
 
-  1. In your docs repository, run
+  2. Run any CLI command (such as `mint dev`) in your docs repository — the CLI automatically detects `mint.json` and creates a `docs.json` file
 
-  ```bash
-  mint upgrade
-  ```
-
-  1. Delete your old `mint.json` file and push your changes
+  3. Delete your old `mint.json` file and push your changes
 
   ## CI Checks
 
diff --git a/installation.mdx b/installation.mdx
index 68eca503e..7ac837ae7 100644
--- a/installation.mdx
+++ b/installation.mdx
@@ -332,16 +332,6 @@ mint scrape openapi <openApiFilename or URL>
 | `--overwrite` | Overwrite existing files. |
 | `--no-writeFiles` | Preview output without writing files. |
 
-### Upgrade configuration
-
-Convert a `mint.json` configuration file to the current `docs.json` format:
-
-```bash
-mint upgrade
-```
-
-See [Global settings](/organize/settings) for more information about `docs.json`.
-
 ### Check version
 
 Display the current CLI and client version:
diff --git a/organize/settings.mdx b/organize/settings.mdx
index 1a7e84e15..844cba41f 100644
--- a/organize/settings.mdx
+++ b/organize/settings.mdx
@@ -116,7 +116,7 @@ If a `$ref` resolves to an object, Mintlify merges any sibling keys in the same
 
 ## Upgrading from `mint.json`
 
-If your project uses the deprecated `mint.json` file, follow these steps to upgrade to `docs.json`.
+If your project uses the deprecated `mint.json` file, the CLI automatically upgrades it to `docs.json` when you run commands like `mint dev`, `mint broken-links`, or `mint rename`.
 
 <Steps>
   <Step title="Install or update the CLI">
@@ -144,14 +144,14 @@ If your project uses the deprecated `mint.json` file, follow these steps to upgr
     mint update
     ```
   </Step>
-  <Step title="Create your docs.json file">
-    In your docs repository, run:
+  <Step title="Run any CLI command">
+    In your docs repository, run any CLI command such as:
 
     ```bash
-    mint upgrade
+    mint dev
     ```
 
-    This command creates a `docs.json` file from your existing `mint.json`. Review the generated file to ensure all settings are correct.
+    If a `mint.json` file is detected without a corresponding `docs.json`, the CLI automatically creates a `docs.json` file from your existing configuration. Review the generated file to ensure all settings are correct.
   </Step>
   <Step title="Delete your mint.json file">
     After verifying your `docs.json` is configured correctly, you can safely delete your old `mint.json` file.