Update CLI docs for mint update (#810)

* Update CLI docs

* update changelog

* add troubleshooting info

* add reviewer feedback

Author: ethanpalm

changelog.mdx

@@ -13,8 +13,8 @@ mode: "center"
 
   Learn more at [API playground docs.](/api-playground/)
 
-  ## npm i mint 
-  Can now use `npm i mint@latest -g` to upgrade your CLI.
+  ## `mint update`
+  Can now use `mint update` to update your CLI.
 </Update>
 
 <Update label="April 2025">

installation.mdx

@@ -1,5 +1,6 @@
 ---
-title: "Installation"
+title: "CLI"
+sidebarTitle: "Installation"
 description: "Install the CLI to preview and develop your docs locally"
 icon: "terminal"
 ---
@@ -13,37 +14,45 @@ icon: "terminal"
   src="/images/installation/local-development-dark.png"
 />
 
+## Installing the CLI
+
 <Info>
   **Prerequisite**: Please install [Node.js](https://nodejs.org/en) (version 19 or higher) before proceeding.
 </Info>
 
-**Step 1**: Install the [CLI](https://www.npmjs.com/package/mint):
+<Steps>
+  <Step title="Install the CLI.">
+    Run the following command to install the [CLI](https://www.npmjs.com/package/mint):
+    <CodeGroup>
 
-<CodeGroup>
+    ```bash npm
+    npm i -g mint
+    ```
 
-```bash npm
-npm i -g mint
-```
 
+    ```bash yarn
+    yarn global add mint
+    ```
 
-```bash yarn
-yarn global add mint
-```
 
+    ```bash pnpm
+    pnpm add -g mint
+    ```
 
-```bash pnpm
-pnpm add -g mint
-```
+    </CodeGroup>
+  </Step>
+  <Step title="Preview locally.">
+    Navigate to your docs directory (where your `docs.json` file is located) and execute the following command:
 
-</CodeGroup>
+    ```bash
+    mint dev
+    ```
 
-**Step 2**: Navigate to the docs directory (where the `docs.json` file is located) and execute the following command:
-
-```bash
-mint dev
-```
+    A local preview of your documentation will be available at `http://localhost:3000`.
+  </Step>
+</Steps>
 
-Alternatively, if you do not want to install the CLI globally, you can use a run a one-time script:
+Alternatively, if you do not want to install the CLI globally, you can run a one-time script:
 
 <CodeGroup>
 
@@ -63,11 +72,21 @@ pnpm dlx mint dev
 
 </CodeGroup>
 
-A local preview of your documentation will be available at `http://localhost:3000`.
-
 ## Updates
 
-Each CLI release is associated with a specific version of the Mintlify platform. If your local preview doesn't align with the production version, please update the CLI:
+You can update the client and CLI versions independently.
+
+### Client version
+
+If your local preview is out of sync with the production version, update your client version:
+
+```bash
+mint update
+```
+
+### CLI version
+
+Update the CLI to the latest version:
 
 <CodeGroup>
 
@@ -87,33 +106,33 @@ pnpm up --global mint
 
 </CodeGroup>
 
-## Custom Ports
+## Custom ports
 
 By default, the CLI uses port 3000. You can customize the port using the `--port` flag. To run the CLI on port 3333, for instance, use this command:
 
 ```bash
 mint dev --port 3333
 ```
 
-If you attempt to run on a port that's already in use, it will use the next available port:
+If you attempt to run on a port that is already in use, it will use the next available port:
 
 ```mdx
 Port 3000 is already in use. Trying 3001 instead.
 ```
 
-## Additional Commands
+## Additional commands
 
 While `mint dev` is the most commonly used command, there are other commands you can use to manage your documentation.
 
-### Find Broken Links
+### Finding broken links
 
 The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:
 
 ```bash
 mint broken-links
 ```
 
-### Check OpenAPI Spec
+### Checking OpenAPI spec
 
 You can use the CLI to check your OpenAPI file for errors using the following command:
 
@@ -123,19 +142,17 @@ mint openapi-check <openapiFilenameOrUrl>
 
 You can pass in a filename (e.g. `./openapi.yaml`) or a URL (e.g. `https://petstore3.swagger.io/api/v3/openapi.json`).
 
-### Renaming Files
+### Renaming files
 
-You can rename files using the following command:
+You can rename and update all references to files using the following command:
 
 ```bash
 mint rename <oldFilename> <newFilename>
 ```
 
-This is an improvement over updating the filename normally as it will also update all references to the file, ensuring no broken links.
-
 ## Formatting
 
-While developing locally, we recommend using extensions on your IDE to recognize and format MDX.
+While developing locally, we recommend using extensions in your IDE to recognize and format `MDX` files.
 
 If you use Cursor, Windsurf, or VSCode, we recommend the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting.
 
@@ -152,6 +169,11 @@ If you use JetBrains, we recommend the [MDX IntelliJ IDEA plugin](https://plugin
     3. Reinstall the mint CLI: `npm install -g mint`
   </Accordion>
   <Accordion title="Issue: Encountering an unknown error">
-    Solution: Go to the root of your device and delete the ~/.mintlify folder. Afterwards, run `mint dev` again.
+    Solution: Go to the root of your device and delete the `~/.mintlify` folder. Afterwards, run `mint dev` again.
+  </Accordion>
+  <Accordion title="Issue: The update command is not available">
+    If running `mint update` returns the command menu, your current version of the CLI does not include the `update` command.
+    
+    Use `npm i -g mint@latest` to update the CLI.
   </Accordion>
 </AccordionGroup>