Update macOS Homebrew install docs for formula-to-cask migration

docs-ref-conceptual/Latest-version/index.yml

@@ -57,8 +57,6 @@ landingContent:
           url: release-notes-azure-cli.md
         - text: Upcoming breaking changes
           url: upcoming-breaking-changes.md
-        - text: Install - macOS (preview)
-          url: install-azure-cli-macos-preview.md
         - text: Impact of MFA in automation
           url: authenticate-azure-cli-mfa.md
   - title: Azure CLI reference

docs-ref-conceptual/Latest-version/install-azure-cli-macos.md

@@ -24,9 +24,19 @@ Homebrew is the easiest way to manage your Azure CLI install. It provides conven
 install, update, and uninstall. If you don't have homebrew available on your system,
 [install homebrew][04] before continuing.
 
+> [!NOTE]
+> Azure CLI has migrated from a Homebrew Core formula to a Homebrew Cask. Both commands below
+> install the same CLI. No action is required if you already have Azure CLI installed.
+
 You can install the Azure CLI on macOS by updating your brew repository information, and then
 running the `install` command:
 
+```bash
+brew update && brew install --cask azure-cli
+```
+
+or
+
 ```bash
 brew update && brew install azure-cli
 ```
@@ -50,6 +60,23 @@ autoload bashcompinit && bashcompinit
 source $(brew --prefix)/etc/bash_completion.d/az
 ```
 
+### Issues after the Homebrew Core to Cask migration
+
+If you experience unexpected behavior after the migration from the Homebrew Core formula to the
+Homebrew Cask, perform a one-time clean reinstall:
+
+```bash
+brew uninstall azure-cli
+brew cleanup azure-cli
+brew update
+brew install azure-cli
+az version
+```
+
+> [!IMPORTANT]
+> Running `brew update` is required. It refreshes local metadata so Homebrew knows the formula has
+> moved to the cask. Your `~/.azure` configuration is preserved during uninstall.
+
 ### Unable to find Python or installed packages
 
 There might be a minor version mismatch or other issue during homebrew installation. The Azure CLI

docs-ref-conceptual/Latest-version/install-azure-cli.md

@@ -29,7 +29,6 @@ in a Docker container and Azure Cloud Shell.
   - [Install on Azure Linux with tdnf][07]
 
 - [Install on macOS][18]
-- [Install on macOS (preview)][21]
 
 - [Run in Docker container][20]
 
@@ -95,4 +94,3 @@ information on managing extensions, see [Use and manage extensions with the Azur
 [18]: install-azure-cli-macos.md
 [19]: install-azure-cli-windows.md
 [20]: run-azure-cli-docker.md
-[21]: install-azure-cli-macos-preview.md

docs-ref-conceptual/Latest-version/toc.yml

@@ -44,8 +44,6 @@ items:
       - name: Install - macOS
         href: install-azure-cli-macos.md
         displayName: install, macos, brew, homebrew, osx, os x, mac
-      - name: Install - macOS (preview)
-        href: install-azure-cli-macos-preview.md
       - name: Run in Azure Cloud Shell
         href: /azure/cloud-shell/quickstart?toc=%2fcli%2fazure%2ftoc.json&bc=%2fcli%2fazure%2fbreadcrumb%2ftoc.json
         displayName: bash, Powershell

openpublishing-redirection-config/.openpublishing.redirection.json

@@ -229,6 +229,11 @@
          "source_path_from_root": "/docs-ref-conceptual/Latest-version/query-azure-cli.md",
          "redirect_url": "/cli/azure/use-azure-cli-successfully-query",
          "redirect_document_id": false
+      },
+      {
+         "source_path_from_root": "/docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md",
+         "redirect_url": "/cli/azure/install-azure-cli-macos",
+         "redirect_document_id": true
       }
    ]
 }