Update installation guide (#18823)

docs/get-started/installation.md

@@ -1,43 +1,98 @@
-# Gemini CLI installation, execution, and deployment
+# Gemini CLI installation, execution, and releases
 
-Install and run Gemini CLI. This document provides an overview of Gemini CLI's
-installation methods and deployment architecture.
+This document provides an overview of Gemini CLI's sytem requriements,
+installation methods, and release types.
 
-## How to install and/or run Gemini CLI
+## Recommended system specifications
 
-There are several ways to run Gemini CLI. The recommended option depends on how
-you intend to use Gemini CLI.
+- **Operating System:**
+  - macOS 15+
+  - Windows 11 24H2+
+  - Ubuntu 20.04+
+- **Hardware:**
+  - "Casual" usage: 4GB+ RAM (short sessions, common tasks and edits)
+  - "Power" usage: 16GB+ RAM (long sessions, large codebases, deep context)
+- **Runtime:** Node.js 20.0.0+
+- **Shell:** Bash or Zsh
+- **Location:**
+  [Gemini Code Assist supported locations](https://developers.google.com/gemini-code-assist/resources/available-locations#americas)
+- **Internet connection required**
 
-- As a standard installation. This is the most straightforward method of using
-  Gemini CLI.
+## Install Gemini CLI
+
+We recommend most users install Gemini CLI using one of the following
+installation methods:
+
+- npm
+- Homebrew
+- MacPorts
+- Anaconda
+
+Note that Gemini CLI comes pre-installed on
+[**Cloud Shell**](https://docs.cloud.google.com/shell/docs) and
+[**Cloud Workstations**](https://cloud.google.com/workstations).
+
+### Install globally with npm
+
+```bash
+npm install -g @google/gemini-cli
+```
+
+### Install globally with Homebrew (macOS/Linux)
+
+```bash
+brew install gemini-cli
+```
+
+### Install globally with MacPorts (macOS)
+
+```bash
+sudo port install gemini-cli
+```
+
+### Install with Anaconda (for restricted environments)
+
+```bash
+# Create and activate a new environment
+conda create -y -n gemini_env -c conda-forge nodejs
+conda activate gemini_env
+
+# Install Gemini CLI globally via npm (inside the environment)
+npm install -g @google/gemini-cli
+```
+
+## Run Gemini CLI
+
+For most users, we recommend running Gemini CLI with the `gemini` command:
+
+```bash
+gemini
+```
+
+For a list of options and additional commands, see the
+[CLI cheatsheet](/docs/cli/cli-reference.md).
+
+You can also run Gemini CLI using one of the following advanced methods:
+
+- Run instantly with npx. You can run Gemini CLI without permanent installation.
 - In a sandbox. This method offers increased security and isolation.
 - From the source. This is recommended for contributors to the project.
 
-### 1. Standard installation (recommended for standard users)
+### Run instantly with npx
 
-This is the recommended way for end-users to install Gemini CLI. It involves
-downloading the Gemini CLI package from the NPM registry.
+```bash
+# Using npx (no installation required)
+npx @google/gemini-cli
+```
 
-- **Global install:**
+You can also execute the CLI directly from the main branch on GitHub, which is
+helpful for testing features still in development:
 
-  ```bash
-  npm install -g @google/gemini-cli
-  ```
+```bash
+npx https://github.com/google-gemini/gemini-cli
+```
 
-  Then, run the CLI from anywhere:
-
-  ```bash
-  gemini
-  ```
-
-- **NPX execution:**
-
-  ```bash
-  # Execute the latest version from NPM without a global install
-  npx @google/gemini-cli
-  ```
-
-### 2. Run in a sandbox (Docker/Podman)
+### Run in a sandbox (Docker/Podman)
 
 For security and isolation, Gemini CLI can be run inside a container. This is
 the default way that the CLI executes tools that might have side effects.
@@ -56,7 +111,7 @@ the default way that the CLI executes tools that might have side effects.
   gemini --sandbox -y -p "your prompt here"
   ```
 
-### 3. Run from source (recommended for Gemini CLI contributors)
+### Run from source (recommended for Gemini CLI contributors)
 
 Contributors to the project will want to run the CLI directly from the source
 code.
@@ -79,63 +134,41 @@ code.
   gemini
   ```
 
----
+## Releases
 
-### 4. Running the latest Gemini CLI commit from GitHub
+Gemini CLI has three release channels: nightly, preview, and stable. For most
+users, we recommend the stable release, which is the default installation.
 
-You can run the most recently committed version of Gemini CLI directly from the
-GitHub repository. This is useful for testing features still in development.
+### Stable
+
+New stable releases are published each week. The stable release is the promotion
+of last week's `preview` release along with any bug fixes. The stable release
+uses `latest` tag, but omitting the tag also installs the latest stable release
+by default:
 
 ```bash
-# Execute the CLI directly from the main branch on GitHub
-npx https://github.com/google-gemini/gemini-cli
+# Both commands install the latest stable release.
+npm install -g @google/gemini-cli
+npm install -g @google/gemini-cli@latest
 ```
 
-## Deployment architecture
+### Preview
 
-The execution methods described above are made possible by the following
-architectural components and processes:
+New preview releases will be published each week. These releases are not fully
+vetted and may contain regressions or other outstanding issues. Try out the
+preview release by using the `preview` tag:
 
-**NPM packages**
+```bash
+npm install -g @google/gemini-cli@preview
+```
 
-Gemini CLI project is a monorepo that publishes two core packages to the NPM
-registry:
+### Nightly
 
-- `@google/gemini-cli-core`: The backend, handling logic and tool execution.
-- `@google/gemini-cli`: The user-facing frontend.
+Nightly releases are published every day. The nightly release includes all
+changes from the main branch at time of release. It should be assumed there are
+pending validations and issues. You can help test the latest changes by
+installing with the `nightly` tag:
 
-These packages are used when performing the standard installation and when
-running Gemini CLI from the source.
-
-**Build and packaging processes**
-
-There are two distinct build processes used, depending on the distribution
-channel:
-
-- **NPM publication:** For publishing to the NPM registry, the TypeScript source
-  code in `@google/gemini-cli-core` and `@google/gemini-cli` is transpiled into
-  standard JavaScript using the TypeScript Compiler (`tsc`). The resulting
-  `dist/` directory is what gets published in the NPM package. This is a
-  standard approach for TypeScript libraries.
-
-- **GitHub `npx` execution:** When running the latest version of Gemini CLI
-  directly from GitHub, a different process is triggered by the `prepare` script
-  in `package.json`. This script uses `esbuild` to bundle the entire application
-  and its dependencies into a single, self-contained JavaScript file. This
-  bundle is created on-the-fly on the user's machine and is not checked into the
-  repository.
-
-**Docker sandbox image**
-
-The Docker-based execution method is supported by the `gemini-cli-sandbox`
-container image. This image is published to a container registry and contains a
-pre-installed, global version of Gemini CLI.
-
-## Release process
-
-The release process is automated through GitHub Actions. The release workflow
-performs the following actions:
-
-1.  Build the NPM packages using `tsc`.
-2.  Publish the NPM packages to the artifact registry.
-3.  Create GitHub releases with bundled assets.
+```bash
+npm install -g @google/gemini-cli@nightly
+```