Update deployment.md -> installation.md and sidebar links. (#10662)

Co-authored-by: Tommaso Sciortino <sciortino@gmail.com>

docs/get-started/deployment.md

@@ -1,10 +1,13 @@
-# Gemini CLI Execution and Deployment
+Note: This page will be replaced by [installation.md](installation.md).
 
-This document describes how to run Gemini CLI and its deployment architecture.
+# Gemini CLI Installation, Execution, and Deployment
 
-## Running Gemini CLI
+Install and run Gemini CLI. This document provides an overview of Gemini CLI's
+installation methods and deployment architecture.
 
-There are several ways to run Gemini CLI. The option you choose depends on how
+## How to install and/or run Gemini CLI
+
+There are several ways to run Gemini CLI. The recommended option depends on how
 you intend to use Gemini CLI.
 
 - As a standard installation. This is the most straightforward method of using

docs/get-started/index.md

@@ -24,8 +24,7 @@ Once Gemini CLI is installed, run Gemini CLI from your command line:
 gemini
 ```
 
-For more deployment options, see
-[Gemini CLI Execution and Deployment](./deployment.md).
+For more installation options, see [Gemini CLI Installation](./installation.md).
 
 ## Authenticate
 

docs/get-started/installation.md

@@ -0,0 +1,141 @@
+# Gemini CLI Installation, Execution, and Deployment
+
+Install and run Gemini CLI. This document provides an overview of Gemini CLI's
+installation methods and deployment architecture.
+
+## How to install and/or run Gemini CLI
+
+There are several ways to run Gemini CLI. The recommended option depends on how
+you intend to use Gemini CLI.
+
+- As a standard installation. This is the most straightforward method of using
+  Gemini CLI.
+- 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)
+
+This is the recommended way for end-users to install Gemini CLI. It involves
+downloading the Gemini CLI package from the NPM registry.
+
+- **Global install:**
+
+  ```bash
+  npm install -g @google/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)
+
+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"
+  ```
+
+### 3. 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
+  ```
+
+---
+
+### 4. Running the latest Gemini CLI commit from GitHub
+
+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.
+
+```bash
+# Execute the CLI directly from the main branch on GitHub
+npx https://github.com/google-gemini/gemini-cli
+```
+
+## Deployment architecture
+
+The execution methods described above are made possible by the following
+architectural components and processes:
+
+**NPM packages**
+
+Gemini CLI project is a monorepo that publishes two core packages to the NPM
+registry:
+
+- `@google/gemini-cli-core`: The backend, handling logic and tool execution.
+- `@google/gemini-cli`: The user-facing frontend.
+
+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.

docs/index.md

@@ -22,7 +22,7 @@ This documentation is organized into the following sections:
 
 - **[Gemini CLI Quickstart](./get-started/index.md):** Let's get started with
   Gemini CLI.
-- **[Deployment](./get-started/deployment.md):** Install and run Gemini CLI.
+- **[Installation](./get-started/installation.md):** Install and run Gemini CLI.
 - **[Authentication](./get-started/authentication.md):** Authenticate Gemini
   CLI.
 - **[Configuration](./get-started/configuration.md):** Information on
@@ -73,6 +73,8 @@ This documentation is organized into the following sections:
 
 - **[Extensions](./extensions/index.md):** How to extend the CLI with new
   functionality.
+- **[Get Started with Extensions](./extensions/getting-started-extensions.md):**
+  Learn how to build your own extension.
 - **[Extension Releasing](./extensions/extension-releasing.md):** How to release
   Gemini CLI extensions.
 

docs/sidebar.json

@@ -28,8 +28,8 @@
         "slug": "docs/get-started/configuration"
       },
       {
-        "label": "Deployment",
-        "slug": "docs/get-started/deployment"
+        "label": "Installation",
+        "slug": "docs/get-started/installation"
       },
       {
         "label": "Examples",
@@ -159,6 +159,10 @@
         "label": "Introduction",
         "slug": "docs/extensions"
       },
+      {
+        "label": "Get Started with Extensions",
+        "slug": "docs/extensions/getting-started-extensions.md"
+      },
       {
         "label": "Extension Releasing",
         "slug": "docs/extensions/extension-releasing"
@@ -189,6 +193,10 @@
         "label": "Releases",
         "slug": "docs/releases"
       },
+      {
+        "label": "Changelog",
+        "slug": "docs/changelogs"
+      },
       {
         "label": "Integration Tests",
         "slug": "docs/integration-tests"