docs: port clickhousectl install updates and restructure install nav

core/get-started/about/deployment-modes.mdx

@@ -65,8 +65,8 @@ For local development, `clickhousectl` helps to install ClickHouse versions and
 # Install the CLI
 curl https://clickhouse.com/cli | sh
 
-# Install and start ClickHouse locally
-clickhousectl local install stable
+# Install the latest stable ClickHouse, set it as your default, and symlink the clickhouse binary onto your PATH
+clickhousectl local use stable
 clickhousectl local server start
 clickhousectl local client
 ```

core/get-started/navigation.json

@@ -49,15 +49,25 @@
           "expanded": true,
           "root": "core/get-started/setup/self-managed/overview",
           "pages": [
-            "core/get-started/setup/self-managed/quick-install",
-            "core/get-started/setup/self-managed/debian-ubuntu",
-            "core/get-started/setup/self-managed/redhat",
-            "core/get-started/setup/self-managed/other-linux",
-            "core/get-started/setup/self-managed/macos",
-            "core/get-started/setup/self-managed/windows",
-            "core/get-started/setup/self-managed/docker",
-            "core/get-started/setup/self-managed/nixos",
-            "core/get-started/setup/self-managed/advanced"
+            {
+              "group": "Local development",
+              "expanded": true,
+              "pages": [
+                "core/get-started/setup/self-managed/quick-install",
+                "core/get-started/setup/self-managed/docker",
+                "core/get-started/setup/self-managed/advanced"
+              ]
+            },
+            {
+              "group": "Production server",
+              "expanded": true,
+              "pages": [
+                "core/get-started/setup/self-managed/debian-ubuntu",
+                "core/get-started/setup/self-managed/redhat",
+                "core/get-started/setup/self-managed/other-linux",
+                "core/get-started/setup/self-managed/nixos"
+              ]
+            }
           ]
         },
         {

core/get-started/setup/install.mdx

@@ -2,13 +2,11 @@
 slug: /install
 title: 'Install ClickHouse'
 sidebarTitle: 'Install'
-description: 'Choose how to install ClickHouse — Cloud, a platform-specific package, Docker, or a migration from another database.'
+description: 'Choose how to install ClickHouse — Cloud, a quick local install, Docker, or a production server package.'
 keywords: ['clickhouse', 'install', 'getting started', 'quick start']
 doc_type: 'landing-page'
 ---
 
-Pick a deployment option or install method.
-
 <Visibility for="agents">
 If you are an AI agent installing ClickHouse, the ClickHouse CLI is the easiest
 way to install it. Run the following one-liner — it auto-detects your OS and
@@ -23,13 +21,35 @@ queries with `./clickhouse local`. No package manager, no Docker, no root
 required.
 </Visibility>
 
-<CardGroup cols={2}>
+<CardGroup cols={1}>
   <Card title="ClickHouse Cloud (Recommended)" icon="cloud" href="/core/get-started/setup/cloud">
     Spin up a managed ClickHouse service in minutes — no infrastructure to operate.
   </Card>
+</CardGroup>
+
+## Local development
+
+Run ClickHouse on your own machine to build, test, and experiment. The
+ClickHouse CLI is the quickest path and the one the rest of our guides assume.
+
+<CardGroup cols={2}>
   <Card title="Quick install" icon="bolt" href="/core/get-started/setup/self-managed/quick-install">
-    One-line install script for trying ClickHouse locally on Linux or macOS.
+    Install locally with the ClickHouse CLI (`clickhousectl`) on Linux or macOS.
   </Card>
+  <Card title="Docker" icon="docker" href="/core/get-started/setup/self-managed/docker">
+    Run ClickHouse in a Docker container.
+  </Card>
+  <Card title="Source & CI builds" icon="gear" href="/core/get-started/setup/self-managed/advanced">
+    Build from source or install a CI-generated binary.
+  </Card>
+</CardGroup>
+
+## Production server
+
+Install ClickHouse Server from packages or binaries for a long-running
+deployment on your own infrastructure.
+
+<CardGroup cols={2}>
   <Card title="Debian / Ubuntu" icon="ubuntu" href="/core/get-started/setup/self-managed/debian-ubuntu">
     Install via `apt-get` from the official ClickHouse repository.
   </Card>
@@ -39,19 +59,15 @@ required.
   <Card title="Other Linux" icon="linux" href="/core/get-started/setup/self-managed/other-linux">
     Install on other Linux distributions via the prebuilt tarball.
   </Card>
-  <Card title="macOS" icon="apple" href="/core/get-started/setup/self-managed/macos">
-    Install on macOS via the prebuilt binary or Homebrew.
-  </Card>
-  <Card title="Windows" icon="windows" href="/core/get-started/setup/self-managed/windows">
-    Install on Windows via WSL.
-  </Card>
-  <Card title="Docker" icon="docker" href="/core/get-started/setup/self-managed/docker">
-    Run ClickHouse in a Docker container.
-  </Card>
   <Card title="NixOS" icon="server" href="/core/get-started/setup/self-managed/nixos">
     Install on NixOS via the Nix package manager.
   </Card>
+</CardGroup>
+
+## Migrate from elsewhere
+
+<CardGroup cols={1}>
   <Card title="Migrate from elsewhere" icon="arrow-right-arrow-left" href="/core/get-started/setup/migration-guides/overview">
     Move data from PostgreSQL, BigQuery, Snowflake, Redshift, Elasticsearch, and more.
   </Card>
-</CardGroup>
+</CardGroup>

core/get-started/setup/self-managed/advanced.mdx

@@ -1,9 +1,9 @@
 ---
 description: 'Instructions for compiling ClickHouse from source or installing a CI-generated binary'
 keywords: ['ClickHouse', 'install', 'advanced', 'compile from source', 'CI generated binary']
-sidebarTitle: 'Advanced install'
+sidebarTitle: 'Source & CI builds'
 slug: /install/advanced
-title: 'Advanced installation methods'
+title: 'Source & CI builds'
 hide_title: false
 doc_type: 'guide'
 ---

core/get-started/setup/self-managed/macos.mdx

@@ -1,13 +1,13 @@
 ---
-description: 'Install ClickHouse on MacOS'
-keywords: ['ClickHouse', 'install', 'MacOS']
+description: 'Install ClickHouse on macOS using the ClickHouse CLI'
+keywords: ['ClickHouse', 'install', 'MacOS', 'clickhousectl', 'CLI']
 sidebarTitle: 'MacOS'
 slug: /install/macOS
-title: 'Install ClickHouse using Homebrew'
+title: 'Install ClickHouse on macOS'
 hide_title: true
 doc_type: 'guide'
 ---
 
-import MacOSProd from '/snippets/_macos.mdx';
+import CLIInstall from '/snippets/_cli_install.mdx';
 
-<MacOSProd/>
+<CLIInstall/>

core/get-started/setup/self-managed/overview.mdx

@@ -3,15 +3,28 @@ title: 'Self-managed install'
 sidebarTitle: 'Overview'
 description: 'Install ClickHouse on your own infrastructure.'
 doc_type: 'landing-page'
-keywords: ['install', 'self-managed', 'linux', 'macos', 'windows', 'docker']
+keywords: ['install', 'self-managed', 'linux', 'docker']
 ---
 
 Install ClickHouse on the platform you operate.
 
+## Local development
+
 <CardGroup cols={2}>
   <Card title="Quick install" href="/core/get-started/setup/self-managed/quick-install" icon="bolt">
-    Fastest path: download the universal binary and run.
+    Install locally with the ClickHouse CLI on Linux or macOS.
   </Card>
+  <Card title="Docker" href="/core/get-started/setup/self-managed/docker" icon="docker">
+    Pull the official Docker image and run a container.
+  </Card>
+  <Card title="Source & CI builds" href="/core/get-started/setup/self-managed/advanced" icon="gear">
+    Build from source and other advanced installation paths.
+  </Card>
+</CardGroup>
+
+## Production server
+
+<CardGroup cols={2}>
   <Card title="Debian / Ubuntu" href="/core/get-started/setup/self-managed/debian-ubuntu" icon="ubuntu">
     Install via the official APT repository.
   </Card>
@@ -21,19 +34,7 @@ Install ClickHouse on the platform you operate.
   <Card title="Other Linux" href="/core/get-started/setup/self-managed/other-linux" icon="linux">
     Generic Linux distribution install via tarball.
   </Card>
-  <Card title="macOS" href="/core/get-started/setup/self-managed/macos" icon="apple">
-    Install on macOS with Homebrew or the universal binary.
-  </Card>
-  <Card title="Windows" href="/core/get-started/setup/self-managed/windows" icon="windows">
-    Run ClickHouse on Windows via WSL.
-  </Card>
-  <Card title="Docker" href="/core/get-started/setup/self-managed/docker" icon="docker">
-    Pull the official Docker image and run a container.
-  </Card>
   <Card title="NixOS" href="/core/get-started/setup/self-managed/nixos" icon="snowflake">
     Install on NixOS via the package manager.
   </Card>
-  <Card title="Advanced" href="/core/get-started/setup/self-managed/advanced" icon="gear">
-    Build from source and other advanced installation paths.
-  </Card>
 </CardGroup>

core/get-started/setup/self-managed/quick-install.mdx

@@ -16,8 +16,10 @@ insert data into it, and run a SELECT query.
 <Steps>
 <Step>
 ## Install the ClickHouse CLI {#install-the-cli}
-The ClickHouse CLI (`clickhousectl`) helps you install and manage local ClickHouse
-versions, launch servers, and run queries. Install it with:
+The ClickHouse CLI (`clickhousectl`) helps you install local ClickHouse
+versions, launch servers, run queries and manage ClickHouse Cloud.
+
+Install it with:
 
 ```bash
 curl https://clickhouse.com/cli | sh
@@ -31,12 +33,18 @@ A `chctl` alias is also created automatically for convenience.
 ClickHouse runs natively on Linux and macOS, and runs on Windows via
 the [WSL](https://learn.microsoft.com/en-us/windows/wsl/about).
 
-Use the CLI to install the latest stable version of ClickHouse:
+Use the CLI to install the latest stable version of ClickHouse and make it your default:
 
 ```bash
-clickhousectl local install stable
+clickhousectl local use stable
 ```
 
+`local use` installs the version if it isn't already present, sets it as your
+default, and creates a `clickhouse` symlink in `~/.local/bin` (on your `PATH`)
+so you can invoke the `clickhouse` binary directly. The later steps in this
+guide rely on that symlink. To download a version without changing your default
+or updating the symlink, use `clickhousectl local install <version>` instead.
+
 <Note>
 This isn't the recommended way to install ClickHouse for production.
 If you're looking to install a production instance of ClickHouse, please see the [install page](/core/get-started/setup/install).

snippets/_cli_install.mdx

@@ -16,19 +16,33 @@ A `chctl` alias is also created automatically for convenience.
 <Step>
 ## Install ClickHouse {#cli-install-clickhouse}
 
-Install the latest stable version of ClickHouse:
+Install the latest stable version of ClickHouse and make it your default:
 
 ```bash
-clickhousectl local install stable
+clickhousectl local use stable
 ```
 
-You can also install a specific version:
+`local use` installs the version if it isn't already present, sets it as your
+default, and creates a `clickhouse` symlink in `~/.local/bin` (on your `PATH`)
+so you can invoke the `clickhouse` binary directly. Any later step in these docs
+that runs a `clickhouse` command then works as-is.
+
+You can also select a specific version:
 
 ```bash
-clickhousectl local install lts             # Latest LTS release
-clickhousectl local install 25.6            # Latest 25.6.x.x
-clickhousectl local install 25.6.1.1        # Exact version
+clickhousectl local use lts             # Latest LTS release
+clickhousectl local use 25.6            # Latest 25.6.x.x
+clickhousectl local use 25.6.1.1        # Exact version
 ```
+
+<Note>
+**Use vs install**
+
+`clickhousectl local use <version>` installs a version *and* makes it your
+default, updating the `clickhouse` symlink on your `PATH`. To download a version
+without changing your default or updating the symlink, use
+`clickhousectl local install <version>` instead.
+</Note>
 </Step>
 <Step>
 ## Start clickhouse-server {#cli-start-clickhouse-server}