diff --git a/docs/resources/authentication.md b/docs/resources/authentication.md
new file mode 100644
index 0000000000..6d8758b958
--- /dev/null
+++ b/docs/resources/authentication.md
@@ -0,0 +1,416 @@
+# Gemini CLI authentication setup
+
+To use Gemini CLI, you'll need to authenticate with Google. This guide helps you
+quickly find the best way to sign in based on your account type and how you're
+using the CLI.
+
+<!-- prettier-ignore -->
+> [!TIP]
+> Looking for a high-level comparison of all available subscriptions?
+> To compare features and find the right quota for your needs, see our
+> [Plans page](https://geminicli.com/plans/).
+
+For most users, we recommend starting Gemini CLI and logging in with your
+personal Google account.
+
+## Choose your authentication method <a id="auth-methods"></a>
+
+Select the authentication method that matches your situation in the table below:
+
+| User Type / Scenario                                                   | Recommended Authentication Method                                | Google Cloud Project Required                               |
+| :--------------------------------------------------------------------- | :--------------------------------------------------------------- | :---------------------------------------------------------- |
+| Individual Google accounts                                             | [Sign in with Google](#login-google)                             | No, with exceptions                                         |
+| Organization users with a company, school, or Google Workspace account | [Sign in with Google](#login-google)                             | [Yes](#set-gcp)                                             |
+| AI Studio user with a Gemini API key                                   | [Use Gemini API Key](#gemini-api)                                | No                                                          |
+| Google Cloud Vertex AI user                                            | [Vertex AI](#vertex-ai)                                          | [Yes](#set-gcp)                                             |
+| [Headless mode](#headless)                                             | [Use Gemini API Key](#gemini-api) or<br> [Vertex AI](#vertex-ai) | No (for Gemini API Key)<br> [Yes](#set-gcp) (for Vertex AI) |
+
+### What is my Google account type?
+
+- **Individual Google accounts:** Includes all
+  [free tier accounts](../resources/quota-and-pricing.md#free-usage) such as
+  Gemini Code Assist for individuals, as well as paid subscriptions for
+  [Google AI Pro and Ultra](https://gemini.google/subscriptions/).
+
+- **Organization accounts:** Accounts using paid licenses through an
+  organization such as a company, school, or
+  [Google Workspace](https://workspace.google.com/). Includes
+  [Google AI Ultra for Business](https://support.google.com/a/answer/16345165)
+  subscriptions.
+
+## (Recommended) Sign in with Google <a id="login-google"></a>
+
+If you run Gemini CLI on your local machine, the simplest authentication method
+is logging in with your Google account. This method requires a web browser on a
+machine that can communicate with the terminal running Gemini CLI (for example,
+your local machine).
+
+If you are a **Google AI Pro** or **Google AI Ultra** subscriber, use the Google
+account associated with your subscription.
+
+To authenticate and use Gemini CLI:
+
+1. Start the CLI:
+
+   ```bash
+   gemini
+   ```
+
+2. Select **Sign in with Google**. Gemini CLI opens a sign in prompt using your
+   web browser. Follow the on-screen instructions. Your credentials will be
+   cached locally for future sessions.
+
+### Do I need to set my Google Cloud project?
+
+Most individual Google accounts (free and paid) don't require a Google Cloud
+project for authentication. However, you'll need to set a Google Cloud project
+when you meet at least one of the following conditions:
+
+- You are using a company, school, or Google Workspace account.
+- You are using a Gemini Code Assist license from the Google Developer Program.
+- You are using a license from a Gemini Code Assist subscription.
+
+For instructions, see [Set your Google Cloud Project](#set-gcp).
+
+## Use Gemini API key <a id="gemini-api"></a>
+
+If you don't want to authenticate using your Google account, you can use an API
+key from Google AI Studio.
+
+To authenticate and use Gemini CLI with a Gemini API key:
+
+1. Obtain your API key from
+   [Google AI Studio](https://aistudio.google.com/app/apikey).
+
+2. Set the `GEMINI_API_KEY` environment variable to your key. For example:
+
+   **macOS/Linux**
+
+   ```bash
+   # Replace YOUR_GEMINI_API_KEY with the key from AI Studio
+   export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
+   ```
+
+   **Windows (PowerShell)**
+
+   ```powershell
+   # Replace YOUR_GEMINI_API_KEY with the key from AI Studio
+   $env:GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
+   ```
+
+   To make this setting persistent, see
+   [Persisting Environment Variables](#persisting-vars).
+
+3. Start the CLI:
+
+   ```bash
+   gemini
+   ```
+
+4. Select **Use Gemini API key**.
+
+<!-- prettier-ignore -->
+> [!WARNING]
+> Treat API keys, especially for services like Gemini, as sensitive
+> credentials. Protect them to prevent unauthorized access and potential misuse
+> of the service under your account.
+
+## Use Vertex AI <a id="vertex-ai"></a>
+
+To use Gemini CLI with Google Cloud's Vertex AI platform, choose from the
+following authentication options:
+
+- A. Application Default Credentials (ADC) using `gcloud`.
+- B. Service account JSON key.
+- C. Google Cloud API key.
+
+Regardless of your authentication method for Vertex AI, you'll need to set
+`GOOGLE_CLOUD_PROJECT` to your Google Cloud project ID with the Vertex AI API
+enabled, and `GOOGLE_CLOUD_LOCATION` to the location of your Vertex AI resources
+or the location where you want to run your jobs.
+
+For example:
+
+**macOS/Linux**
+
+```bash
+# Replace with your project ID and desired location (for example, us-central1)
+export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
+export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"
+```
+
+**Windows (PowerShell)**
+
+```powershell
+# Replace with your project ID and desired location (for example, us-central1)
+$env:GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
+$env:GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"
+```
+
+To make any Vertex AI environment variable settings persistent, see
+[Persisting Environment Variables](#persisting-vars).
+
+#### A. Vertex AI - application default credentials (ADC) using `gcloud`
+
+Consider this authentication method if you have Google Cloud CLI installed.
+
+If you have previously set `GOOGLE_API_KEY` or `GEMINI_API_KEY`, you must unset
+them to use ADC.
+
+**macOS/Linux**
+
+```bash
+unset GOOGLE_API_KEY GEMINI_API_KEY
+```
+
+**Windows (PowerShell)**
+
+```powershell
+Remove-Item Env:\GOOGLE_API_KEY, Env:\GEMINI_API_KEY -ErrorAction Ignore
+```
+
+1. Verify you have a Google Cloud project and Vertex AI API is enabled.
+
+2. Log in to Google Cloud:
+
+   ```bash
+   gcloud auth application-default login
+   ```
+
+3. [Configure your Google Cloud Project](#set-gcp).
+
+4. Start the CLI:
+
+   ```bash
+   gemini
+   ```
+
+5. Select **Vertex AI**.
+
+#### B. Vertex AI - service account JSON key
+
+Consider this method of authentication in non-interactive environments, CI/CD
+pipelines, or if your organization restricts user-based ADC or API key creation.
+
+If you have previously set `GOOGLE_API_KEY` or `GEMINI_API_KEY`, you must unset
+them:
+
+**macOS/Linux**
+
+```bash
+unset GOOGLE_API_KEY GEMINI_API_KEY
+```
+
+**Windows (PowerShell)**
+
+```powershell
+Remove-Item Env:\GOOGLE_API_KEY, Env:\GEMINI_API_KEY -ErrorAction Ignore
+```
+
+1.  [Create a service account and key](https://cloud.google.com/iam/docs/keys-create-delete)
+    and download the provided JSON file. Assign the "Vertex AI User" role to the
+    service account.
+
+2.  Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the JSON
+    file's absolute path. For example:
+
+    **macOS/Linux**
+
+    ```bash
+    # Replace /path/to/your/keyfile.json with the actual path
+    export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"
+    ```
+
+    **Windows (PowerShell)**
+
+    ```powershell
+    # Replace C:\path\to\your\keyfile.json with the actual path
+    $env:GOOGLE_APPLICATION_CREDENTIALS="C:\path\to\your\keyfile.json"
+    ```
+
+3.  [Configure your Google Cloud Project](#set-gcp).
+
+4.  Start the CLI:
+
+    ```bash
+    gemini
+    ```
+
+5.  Select **Vertex AI**.
+
+<!-- prettier-ignore -->
+> [!WARNING]
+> Protect your service account key file as it gives access to
+> your resources.
+
+#### C. Vertex AI - Google Cloud API key
+
+1.  Obtain a Google Cloud API key:
+    [Get an API Key](https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys?usertype=newuser).
+
+2.  Set the `GOOGLE_API_KEY` environment variable:
+
+    **macOS/Linux**
+
+    ```bash
+    # Replace YOUR_GOOGLE_API_KEY with your Vertex AI API key
+    export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"
+    ```
+
+    **Windows (PowerShell)**
+
+    ```powershell
+    # Replace YOUR_GOOGLE_API_KEY with your Vertex AI API key
+    $env:GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"
+    ```
+
+    If you see errors like `"API keys are not supported by this API..."`, your
+    organization might restrict API key usage for this service. Try the other
+    Vertex AI authentication methods instead.
+
+3.  [Configure your Google Cloud Project](#set-gcp).
+
+4.  Start the CLI:
+
+    ```bash
+    gemini
+    ```
+
+5.  Select **Vertex AI**.
+
+## Set your Google Cloud project <a id="set-gcp"></a>
+
+<!-- prettier-ignore -->
+> [!IMPORTANT]
+> Most individual Google accounts (free and paid) don't require a
+> Google Cloud project for authentication.
+
+When you sign in using your Google account, you may need to configure a Google
+Cloud project for Gemini CLI to use. This applies when you meet at least one of
+the following conditions:
+
+- You are using a Company, School, or Google Workspace account.
+- You are using a Gemini Code Assist license from the Google Developer Program.
+- You are using a license from a Gemini Code Assist subscription.
+
+To configure Gemini CLI to use a Google Cloud project, do the following:
+
+1.  [Find your Google Cloud Project ID](https://support.google.com/googleapi/answer/7014113).
+
+2.  [Enable the Gemini for Cloud API](https://cloud.google.com/gemini/docs/discover/set-up-gemini#enable-api).
+
+3.  [Configure necessary IAM access permissions](https://cloud.google.com/gemini/docs/discover/set-up-gemini#grant-iam).
+
+4.  Configure your environment variables. Set either the `GOOGLE_CLOUD_PROJECT`
+    or `GOOGLE_CLOUD_PROJECT_ID` variable to the project ID to use with Gemini
+    CLI. Gemini CLI checks for `GOOGLE_CLOUD_PROJECT` first, then falls back to
+    `GOOGLE_CLOUD_PROJECT_ID`.
+
+    For example, to set the `GOOGLE_CLOUD_PROJECT_ID` variable:
+
+    **macOS/Linux**
+
+    ```bash
+    # Replace YOUR_PROJECT_ID with your actual Google Cloud project ID
+    export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
+    ```
+
+    **Windows (PowerShell)**
+
+    ```powershell
+    # Replace YOUR_PROJECT_ID with your actual Google Cloud project ID
+    $env:GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
+    ```
+
+    To make this setting persistent, see
+    [Persisting Environment Variables](#persisting-vars).
+
+## Persisting environment variables <a id="persisting-vars"></a>
+
+To avoid setting environment variables for every terminal session, you can
+persist them with the following methods:
+
+1.  **Add your environment variables to your shell configuration file:** Append
+    the environment variable commands to your shell's startup file.
+
+    **macOS/Linux** (for example, `~/.bashrc`, `~/.zshrc`, or `~/.profile`):
+
+    ```bash
+    echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc
+    source ~/.bashrc
+    ```
+
+    **Windows (PowerShell)** (for example, `$PROFILE`):
+
+    ```powershell
+    Add-Content -Path $PROFILE -Value '$env:GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"'
+    . $PROFILE
+    ```
+
+<!-- prettier-ignore -->
+> [!WARNING]
+> Be aware that when you export API keys or service account
+> paths in your shell configuration file, any process launched from that
+> shell can read them.
+
+2.  **Use a `.env` file:** Create a `.gemini/.env` file in your project
+    directory or home directory. Gemini CLI automatically loads variables from
+    the first `.env` file it finds, searching up from the current directory,
+    then in your home directory's `.gemini/.env` (for example, `~/.gemini/.env`
+    or `%USERPROFILE%\.gemini\.env`).
+
+    Example for user-wide settings:
+
+    **macOS/Linux**
+
+    ```bash
+    mkdir -p ~/.gemini
+    cat >> ~/.gemini/.env <<'EOF'
+    GOOGLE_CLOUD_PROJECT="your-project-id"
+    # Add other variables like GEMINI_API_KEY as needed
+    EOF
+    ```
+
+    **Windows (PowerShell)**
+
+    ```powershell
+    New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.gemini"
+    @"
+    GOOGLE_CLOUD_PROJECT="your-project-id"
+    # Add other variables like GEMINI_API_KEY as needed
+    "@ | Out-File -FilePath "$env:USERPROFILE\.gemini\.env" -Encoding utf8 -Append
+    ```
+
+Variables are loaded from the first file found, not merged.
+
+## Running in Google Cloud environments <a id="cloud-env"></a>
+
+When running Gemini CLI within certain Google Cloud environments, authentication
+is automatic.
+
+In a Google Cloud Shell environment, Gemini CLI typically authenticates
+automatically using your Cloud Shell credentials. In Compute Engine
+environments, Gemini CLI automatically uses Application Default Credentials
+(ADC) from the environment's metadata server.
+
+If automatic authentication fails, use one of the interactive methods described
+on this page.
+
+## Running in headless mode <a id="headless"></a>
+
+[Headless mode](../cli/headless) will use your existing authentication method,
+if an existing authentication credential is cached.
+
+If you have not already signed in with an authentication credential, you must
+configure authentication using environment variables:
+
+- [Use Gemini API Key](#gemini-api)
+- [Vertex AI](#vertex-ai)
+
+## What's next?
+
+Your authentication method affects your quotas, pricing, Terms of Service, and
+privacy notices. Review the following pages to learn more:
+
+- [Gemini CLI: Quotas and Pricing](../resources/quota-and-pricing.md).
+- [Gemini CLI: Terms of Service and Privacy Notice](../resources/tos-privacy.md).
diff --git a/docs/resources/installation.md b/docs/resources/installation.md
new file mode 100644
index 0000000000..e56d98d889
--- /dev/null
+++ b/docs/resources/installation.md
@@ -0,0 +1,174 @@
+# Gemini CLI installation, execution, and releases
+
+This document provides an overview of Gemini CLI's system requirements,
+installation methods, and release types.
+
+## Recommended system specifications
+
+- **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, Zsh, or PowerShell
+- **Location:**
+  [Gemini Code Assist supported locations](https://developers.google.com/gemini-code-assist/resources/available-locations#americas)
+- **Internet connection required**
+
+## 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](../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.
+
+### Run instantly with npx
+
+```bash
+# Using npx (no installation required)
+npx @google/gemini-cli
+```
+
+You can also execute the CLI directly from the main branch on GitHub, which is
+helpful for testing features still in development:
+
+```bash
+npx https://github.com/google-gemini/gemini-cli
+```
+
+### 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.
+
+- **Directly from the registry:** You can run the published sandbox image
+  directly. This is useful for environments where you only have Docker and want
+  to run the CLI.
+  ```bash
+  # Run the published sandbox image
+  docker run --rm -it us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.1.1
+  ```
+- **Using the `--sandbox` flag:** If you have Gemini CLI installed locally
+  (using the standard installation described above), you can instruct it to run
+  inside the sandbox container.
+  ```bash
+  gemini --sandbox -y -p "your prompt here"
+  ```
+
+### Run from source (recommended for Gemini CLI contributors)
+
+Contributors to the project will want to run the CLI directly from the source
+code.
+
+- **Development mode:** This method provides hot-reloading and is useful for
+  active development.
+  ```bash
+  # From the root of the repository
+  npm run start
+  ```
+- **Production-like mode (linked package):** This method simulates a global
+  installation by linking your local package. It's useful for testing a local
+  build in a production workflow.
+
+  ```bash
+  # Link the local cli package to your global node_modules
+  npm link packages/cli
+
+  # Now you can run your local version using the `gemini` command
+  gemini
+  ```
+
+## Releases
+
+Gemini CLI has three release channels: nightly, preview, and stable. For most
+users, we recommend the stable release, which is the default installation.
+
+### 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
+# Both commands install the latest stable release.
+npm install -g @google/gemini-cli
+npm install -g @google/gemini-cli@latest
+```
+
+### Preview
+
+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:
+
+```bash
+npm install -g @google/gemini-cli@preview
+```
+
+### Nightly
+
+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:
+
+```bash
+npm install -g @google/gemini-cli@nightly
+```