docs: port clickhousectl local use + restructure Install IA

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

@@ -27,9 +27,32 @@ required.
   <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>
+  <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>
+
+## Local development
+
+For trying ClickHouse locally on your laptop.
+
+<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.
+    One-line install via 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="code" href="/core/get-started/setup/self-managed/advanced">
+    Compile from source or use a CI-generated binary.
   </Card>
+</CardGroup>
+
+## Production server
+
+For running ClickHouse Server on production hardware.
+
+<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 +62,7 @@ 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>
-  <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/overview.mdx

@@ -3,15 +3,32 @@ 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
+
+For trying ClickHouse locally on your laptop.
+
 <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.
+    One-line install via the ClickHouse CLI (`clickhousectl`) 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="code">
+    Compile from source or use a CI-generated binary.
+  </Card>
+</CardGroup>
+
+## Production server
+
+For running ClickHouse Server on production hardware.
+
+<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 +38,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,27 +16,52 @@ 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
 ```
 
 A `chctl` alias is also created automatically for convenience.
+
+<Accordion title="Advanced: install ClickHouse without clickhousectl">
+
+If you only need the `clickhouse` binary and don't want `clickhousectl`, use the
+universal installer with `CLICKHOUSE_ONLY=1`:
+
+```bash
+curl https://clickhouse.com/ | CLICKHOUSE_ONLY=1 sh
+```
+
+This downloads a single `clickhouse` binary into the current directory. You can
+then run `clickhouse-server`, `clickhouse-client`, and `clickhouse-local`
+directly from that binary, and the rest of this guide's `clickhousectl`-based
+steps won't apply.
+
+</Accordion>
 </Step>
 <Step>
 ## Install ClickHouse {#install-clickhouse}
 
 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,31 @@ 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}