@google/gemini-cli-core 0.30.0-preview.6 → 0.31.0-preview.0

package/dist/docs/{get-started → reference}/configuration.md

@@ -1,16 +1,5 @@
 # Gemini CLI configuration
 
-> **Note on configuration format, 9/17/25:** The format of the `settings.json`
-> file has been updated to a new, more organized structure.
->
-> - The new format will be supported in the stable release starting
->   **[09/10/25]**.
-> - Automatic migration from the old format to the new format will begin on
->   **[09/17/25]**.
->
-> For details on the previous format, please see the
-> [v1 Configuration documentation](./configuration-v1.md).
-
 Gemini CLI offers several ways to configure its behavior, including environment
 variables, command-line arguments, and settings files. This document outlines
 the different configuration methods and available settings.
@@ -132,22 +121,38 @@ their corresponding top-level category object in your `settings.json` file.
   - **Description:** Enable update notification prompts.
   - **Default:** `true`
 
+- **`general.enableNotifications`** (boolean):
+  - **Description:** Enable run-event notifications for action-required prompts
+    and session completion. Currently macOS only.
+  - **Default:** `false`
+
 - **`general.checkpointing.enabled`** (boolean):
   - **Description:** Enable session checkpointing for recovery
   - **Default:** `false`
   - **Requires restart:** Yes
 
-- **`general.enablePromptCompletion`** (boolean):
-  - **Description:** Enable AI-powered prompt completion suggestions while
-    typing.
-  - **Default:** `false`
+- **`general.plan.directory`** (string):
+  - **Description:** The directory where planning artifacts are stored. If not
+    specified, defaults to the system temporary directory.
+  - **Default:** `undefined`
   - **Requires restart:** Yes
 
+- **`general.plan.modelRouting`** (boolean):
+  - **Description:** Automatically switch between Pro and Flash models based on
+    Plan Mode status. Uses Pro for the planning phase and Flash for the
+    implementation phase.
+  - **Default:** `true`
+
 - **`general.retryFetchErrors`** (boolean):
   - **Description:** Retry on "exception TypeError: fetch failed sending
     request" errors.
   - **Default:** `false`
 
+- **`general.maxAttempts`** (number):
+  - **Description:** Maximum number of attempts for requests to the main chat
+    model. Cannot exceed 10.
+  - **Default:** `10`
+
 - **`general.debugKeystrokeLogging`** (boolean):
   - **Description:** Enable debug logging of keystrokes to the console.
   - **Default:** `false`
@@ -228,6 +233,11 @@ their corresponding top-level category object in your `settings.json` file.
   - **Default:** `true`
   - **Requires restart:** Yes
 
+- **`ui.showCompatibilityWarnings`** (boolean):
+  - **Description:** Show warnings about terminal or OS compatibility issues.
+  - **Default:** `true`
+  - **Requires restart:** Yes
+
 - **`ui.hideTips`** (boolean):
   - **Description:** Hide helpful tips in the UI
   - **Default:** `false`
@@ -306,13 +316,20 @@ their corresponding top-level category object in your `settings.json` file.
   - **Description:** Show the spinner during operations.
   - **Default:** `true`
 
+- **`ui.loadingPhrases`** (enum):
+  - **Description:** What to show while the model is working: tips, witty
+    comments, both, or nothing.
+  - **Default:** `"tips"`
+  - **Values:** `"tips"`, `"witty"`, `"all"`, `"off"`
+
 - **`ui.customWittyPhrases`** (array):
   - **Description:** Custom witty phrases to display during loading. When
     provided, the CLI cycles through these instead of the defaults.
   - **Default:** `[]`
 
 - **`ui.accessibility.enableLoadingPhrases`** (boolean):
-  - **Description:** Enable loading phrases during operations.
+  - **Description:** @deprecated Use ui.loadingPhrases instead. Enable loading
+    phrases during operations.
   - **Default:** `true`
   - **Requires restart:** Yes
 
@@ -635,6 +652,27 @@ their corresponding top-level category object in your `settings.json` file.
   - **Default:** `{}`
   - **Requires restart:** Yes
 
+- **`agents.browser.sessionMode`** (enum):
+  - **Description:** Session mode: 'persistent', 'isolated', or 'existing'.
+  - **Default:** `"persistent"`
+  - **Values:** `"persistent"`, `"isolated"`, `"existing"`
+  - **Requires restart:** Yes
+
+- **`agents.browser.headless`** (boolean):
+  - **Description:** Run browser in headless mode.
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
+- **`agents.browser.profilePath`** (string):
+  - **Description:** Path to browser profile directory for session persistence.
+  - **Default:** `undefined`
+  - **Requires restart:** Yes
+
+- **`agents.browser.visualModel`** (string):
+  - **Description:** Model override for the visual agent.
+  - **Default:** `undefined`
+  - **Requires restart:** Yes
+
 #### `context`
 
 - **`context.fileName`** (string | string[]):
@@ -862,6 +900,14 @@ their corresponding top-level category object in your `settings.json` file.
   - **Default:** `undefined`
   - **Requires restart:** Yes
 
+- **`security.enableConseca`** (boolean):
+  - **Description:** Enable the context-aware security checker. This feature
+    uses an LLM to dynamically generate and enforce security policies for tool
+    use based on your prompt, providing an additional layer of protection
+    against unintended actions.
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
 #### `advanced`
 
 - **`advanced.autoConfigureMemory`** (boolean):
@@ -942,8 +988,15 @@ their corresponding top-level category object in your `settings.json` file.
   - **Requires restart:** Yes
 
 - **`experimental.useOSC52Paste`** (boolean):
-  - **Description:** Use OSC 52 sequence for pasting instead of clipboardy
-    (useful for remote sessions).
+  - **Description:** Use OSC 52 for pasting. This may be more robust than the
+    default system when using remote terminal sessions (if your terminal is
+    configured to allow it).
+  - **Default:** `false`
+
+- **`experimental.useOSC52Copy`** (boolean):
+  - **Description:** Use OSC 52 for copying. This may be more robust than the
+    default system when using remote terminal sessions (if your terminal is
+    configured to allow it).
   - **Default:** `false`
 
 - **`experimental.plan`** (boolean):
@@ -951,6 +1004,16 @@ their corresponding top-level category object in your `settings.json` file.
   - **Default:** `false`
   - **Requires restart:** Yes
 
+- **`experimental.modelSteering`** (boolean):
+  - **Description:** Enable model steering (user hints) to guide the model
+    during tool execution.
+  - **Default:** `false`
+
+- **`experimental.directWebFetch`** (boolean):
+  - **Description:** Enable web fetch behavior that bypasses LLM summarization.
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
 #### `skills`
 
 - **`skills.enabled`** (boolean):
@@ -1210,8 +1273,8 @@ within your user's home folder.
 Environment variables are a common way to configure applications, especially for
 sensitive information like API keys or for settings that might change between
 environments. For authentication setup, see the
-[Authentication documentation](./authentication.md) which covers all available
-authentication methods.
+[Authentication documentation](../get-started/authentication.md) which covers
+all available authentication methods.
 
 The CLI automatically loads environment variables from an `.env` file. The
 loading order is:
@@ -1230,13 +1293,19 @@ the `advanced.excludedEnvVars` setting in your `settings.json` file.
 
 - **`GEMINI_API_KEY`**:
   - Your API key for the Gemini API.
-  - One of several available [authentication methods](./authentication.md).
+  - One of several available
+    [authentication methods](../get-started/authentication.md).
   - Set this in your shell profile (e.g., `~/.bashrc`, `~/.zshrc`) or an `.env`
     file.
 - **`GEMINI_MODEL`**:
   - Specifies the default Gemini model to use.
   - Overrides the hardcoded default
   - Example: `export GEMINI_MODEL="gemini-3-flash-preview"`
+- **`GEMINI_CLI_IDE_PID`**:
+  - Manually specifies the PID of the IDE process to use for integration. This
+    is useful when running Gemini CLI in a standalone terminal while still
+    wanting to associate it with a specific IDE instance.
+  - Overrides the automatic IDE detection logic.
 - **`GEMINI_CLI_HOME`**:
   - Specifies the root directory for Gemini CLI's user-level configuration and
     storage.
@@ -1576,15 +1645,15 @@ conventions and context.
   about the active instructional context.
 - **Importing content:** You can modularize your context files by importing
   other Markdown files using the `@path/to/file.md` syntax. For more details,
-  see the [Memory Import Processor documentation](../core/memport.md).
+  see the [Memory Import Processor documentation](./memport.md).
 - **Commands for memory management:**
   - Use `/memory refresh` to force a re-scan and reload of all context files
     from all configured locations. This updates the AI's instructional context.
   - Use `/memory show` to display the combined instructional context currently
     loaded, allowing you to verify the hierarchy and content being used by the
     AI.
-  - See the [Commands documentation](../cli/commands.md#memory) for full details
-    on the `/memory` command and its sub-commands (`show` and `refresh`).
+  - See the [Commands documentation](./commands.md#memory) for full details on
+    the `/memory` command and its sub-commands (`show` and `refresh`).
 
 By understanding and utilizing these configuration layers and the hierarchical
 nature of context files, you can effectively manage the AI's memory and tailor

package/dist/docs/{cli → reference}/keyboard-shortcuts.md

@@ -36,7 +36,7 @@ available combinations.
 | Delete from the cursor to the start of the line. | `Ctrl + U`                                                       |
 | Clear all text in the input field.               | `Ctrl + C`                                                       |
 | Delete the previous word.                        | `Ctrl + Backspace`<br />`Alt + Backspace`<br />`Ctrl + W`        |
-| Delete the next word.                            | `Ctrl + Delete`<br />`Alt + Delete`                              |
+| Delete the next word.                            | `Ctrl + Delete`<br />`Alt + Delete`<br />`Alt + D`               |
 | Delete the character to the left.                | `Backspace`<br />`Ctrl + H`                                      |
 | Delete the character to the right.               | `Delete`<br />`Ctrl + D`                                         |
 | Undo the most recent text edit.                  | `Cmd + Z (no Shift)`<br />`Alt + Z (no Shift)`                   |
@@ -61,7 +61,7 @@ available combinations.
 | Show the next entry in history.              | `Ctrl + N (no Shift)` |
 | Start reverse search through history.        | `Ctrl + R`            |
 | Submit the selected reverse-search match.    | `Enter (no Ctrl)`     |
-| Accept a suggestion while reverse searching. | `Tab`                 |
+| Accept a suggestion while reverse searching. | `Tab (no Shift)`      |
 | Browse and rewind previous interactions.     | `Double Esc`          |
 
 #### Navigation
@@ -79,7 +79,7 @@ available combinations.
 
 | Action                                  | Keys                                               |
 | --------------------------------------- | -------------------------------------------------- |
-| Accept the inline suggestion.           | `Tab`<br />`Enter (no Ctrl)`                       |
+| Accept the inline suggestion.           | `Tab (no Shift)`<br />`Enter (no Ctrl)`            |
 | Move to the previous completion option. | `Up Arrow (no Shift)`<br />`Ctrl + P (no Shift)`   |
 | Move to the next completion option.     | `Down Arrow (no Shift)`<br />`Ctrl + N (no Shift)` |
 | Expand an inline suggestion.            | `Right Arrow`                                      |

package/dist/docs/{core → reference}/policy-engine.md

@@ -64,9 +64,11 @@ primary conditions are the tool's name and its arguments.
 
 The `toolName` in the rule must match the name of the tool being called.
 
-- **Wildcards**: For Model-hosting-protocol (MCP) servers, you can use a
-  wildcard. A `toolName` of `my-server__*` will match any tool from the
-  `my-server` MCP.
+- **Wildcards**: You can use wildcards to match multiple tools.
+  - `*`: Matches **any tool** (built-in or MCP).
+  - `server__*`: Matches any tool from a specific MCP server.
+  - `*__toolName`: Matches a specific tool name across **all** MCP servers.
+  - `*__*`: Matches **any tool from any MCP server**.
 
 #### Arguments pattern
 
@@ -92,11 +94,12 @@ rule with the highest priority wins**.
 To provide a clear hierarchy, policies are organized into three tiers. Each tier
 has a designated number that forms the base of the final priority calculation.
 
-| Tier    | Base | Description                                                                |
-| :------ | :--- | :------------------------------------------------------------------------- |
-| Default | 1    | Built-in policies that ship with the Gemini CLI.                           |
-| User    | 2    | Custom policies defined by the user.                                       |
-| Admin   | 3    | Policies managed by an administrator (e.g., in an enterprise environment). |
+| Tier      | Base | Description                                                                |
+| :-------- | :--- | :------------------------------------------------------------------------- |
+| Default   | 1    | Built-in policies that ship with the Gemini CLI.                           |
+| Workspace | 2    | Policies defined in the current workspace's configuration directory.       |
+| User      | 3    | Custom policies defined by the user.                                       |
+| Admin     | 4    | Policies managed by an administrator (e.g., in an enterprise environment). |
 
 Within a TOML policy file, you assign a priority value from **0 to 999**. The
 engine transforms this into a final priority using the following formula:
@@ -105,15 +108,17 @@ engine transforms this into a final priority using the following formula:
 
 This system guarantees that:
 
-- Admin policies always override User and Default policies.
-- User policies always override Default policies.
+- Admin policies always override User, Workspace, and Default policies.
+- User policies override Workspace and Default policies.
+- Workspace policies override Default policies.
 - You can still order rules within a single tier with fine-grained control.
 
 For example:
 
 - A `priority: 50` rule in a Default policy file becomes `1.050`.
-- A `priority: 100` rule in a User policy file becomes `2.100`.
-- A `priority: 20` rule in an Admin policy file becomes `3.020`.
+- A `priority: 10` rule in a Workspace policy policy file becomes `2.010`.
+- A `priority: 100` rule in a User policy file becomes `3.100`.
+- A `priority: 20` rule in an Admin policy file becomes `4.020`.
 
 ### Approval modes
 
@@ -141,9 +146,9 @@ A rule matches a tool call if all of its conditions are met:
 
 1.  **Tool name**: The `toolName` in the rule must match the name of the tool
     being called.
-    - **Wildcards**: For Model-hosting-protocol (MCP) servers, you can use a
-      wildcard. A `toolName` of `my-server__*` will match any tool from the
-      `my-server` MCP.
+    - **Wildcards**: You can use wildcards like `*`, `server__*`, or
+      `*__toolName` to match multiple tools. See [Tool Name](#tool-name) for
+      details.
 2.  **Arguments pattern**: If `argsPattern` is specified, the tool's arguments
     are converted to a stable JSON string, which is then tested against the
     provided regular expression. If the arguments don't match the pattern, the
@@ -156,10 +161,11 @@ User, and (if configured) Admin directories.
 
 ### Policy locations
 
-| Tier      | Type   | Location                    |
-| :-------- | :----- | :-------------------------- |
-| **User**  | Custom | `~/.gemini/policies/*.toml` |
-| **Admin** | System | _See below (OS specific)_   |
+| Tier          | Type   | Location                                  |
+| :------------ | :----- | :---------------------------------------- |
+| **User**      | Custom | `~/.gemini/policies/*.toml`               |
+| **Workspace** | Custom | `$WORKSPACE_ROOT/.gemini/policies/*.toml` |
+| **Admin**     | System | _See below (OS specific)_                 |
 
 #### System-wide policies (Admin)
 
@@ -199,6 +205,10 @@ toolName = "run_shell_command"
 # to form a composite name like "mcpName__toolName".
 mcpName = "my-custom-server"
 
+# (Optional) Metadata hints provided by the tool. A rule matches if all
+# key-value pairs provided here are present in the tool's annotations.
+toolAnnotations = { readOnlyHint = true }
+
 # (Optional) A regex to match against the tool's arguments.
 argsPattern = '"command":"(git|npm)'
 
@@ -268,13 +278,12 @@ priority = 100
 
 ### Special syntax for MCP tools
 
-You can create rules that target tools from Model-hosting-protocol (MCP) servers
-using the `mcpName` field or a wildcard pattern.
+You can create rules that target tools from Model Context Protocol (MCP) servers
+using the `mcpName` field or composite wildcard patterns.
 
-**1. Using `mcpName`**
+**1. Targeting a specific tool on a server**
 
-To target a specific tool from a specific server, combine `mcpName` and
-`toolName`.
+Combine `mcpName` and `toolName` to target a single operation.
 
 ```toml
 # Allows the `search` tool on the `my-jira-server` MCP
@@ -285,10 +294,10 @@ decision = "allow"
 priority = 200
 ```
 
-**2. Using a wildcard**
+**2. Targeting all tools on a specific server**
 
-To create a rule that applies to _all_ tools on a specific MCP server, specify
-only the `mcpName`.
+Specify only the `mcpName` to apply a rule to every tool provided by that
+server.
 
 ```toml
 # Denies all tools from the `untrusted-server` MCP
@@ -299,6 +308,33 @@ priority = 500
 deny_message = "This server is not trusted by the admin."
 ```
 
+**3. Targeting all MCP servers**
+
+Use `mcpName = "*"` to create a rule that applies to **all** tools from **any**
+registered MCP server. This is useful for setting category-wide defaults.
+
+```toml
+# Ask user for any tool call from any MCP server
+[[rule]]
+mcpName = "*"
+decision = "ask_user"
+priority = 10
+```
+
+**4. Targeting a tool name across all servers**
+
+Use `mcpName = "*"` with a specific `toolName` to target that operation
+regardless of which server provides it.
+
+```toml
+# Allow the `search` tool across all connected MCP servers
+[[rule]]
+mcpName = "*"
+toolName = "search"
+decision = "allow"
+priority = 50
+```
+
 ## Default policies
 
 The Gemini CLI ships with a set of default policies to provide a safe

package/dist/docs/{faq.md → resources/faq.md}

@@ -104,7 +104,7 @@ The Gemini CLI configuration is stored in two `settings.json` files:
 1.  In your home directory: `~/.gemini/settings.json`.
 2.  In your project's root directory: `./.gemini/settings.json`.
 
-Refer to [Gemini CLI Configuration](./get-started/configuration.md) for more
+Refer to [Gemini CLI Configuration](../reference/configuration.md) for more
 details.
 
 ## Google AI Pro/Ultra and subscription FAQs

package/dist/docs/{quota-and-pricing.md → resources/quota-and-pricing.md}

@@ -135,6 +135,18 @@ Flow video editor). These plans do not apply to the API usage which powers the
 Gemini CLI. Supporting these plans is under active consideration for future
 support.
 
+## Check usage and quota
+
+You can check your current token usage and quota information using the
+`/stats model` command. This command provides a snapshot of your current
+session's token usage, as well as your overall quota and usage for the supported
+models.
+
+For more information on the `/stats` command and its subcommands, see the
+[Command Reference](../../reference/commands.md#stats).
+
+A summary of model usage is also presented on exit at the end of a session.
+
 ## Tips to avoid high costs
 
 When using a Pay as you Go API key, be mindful of your usage to avoid unexpected
@@ -151,8 +163,3 @@ costs.
   models directly.
 - Vertex AI: This is the enterprise-grade platform for building, deploying, and
   managing Gemini models with specific security and control requirements.
-
-## Understanding your usage
-
-A summary of model usage is available through the `/stats` command and presented
-on exit at the end of a session.

package/dist/docs/{tos-privacy.md → resources/tos-privacy.md}

@@ -10,8 +10,8 @@ and Privacy Notices applicable to those services apply to such access and use.
 Your Gemini CLI Usage Statistics are handled in accordance with Google's Privacy
 Policy.
 
-**Note:** See [quotas and pricing](/docs/quota-and-pricing.md) for the quota and
-pricing details that apply to your usage of the Gemini CLI.
+**Note:** See [quotas and pricing](/docs/resources/quota-and-pricing.md) for the
+quota and pricing details that apply to your usage of the Gemini CLI.
 
 ## Supported authentication methods
 

package/dist/docs/{troubleshooting.md → resources/troubleshooting.md}

@@ -93,7 +93,7 @@ topics on:
   - **Cause:** When sandboxing is enabled, Gemini CLI may attempt operations
     that are restricted by your sandbox configuration, such as writing outside
     the project directory or system temp directory.
-  - **Solution:** Refer to the [Configuration: Sandboxing](./cli/sandbox.md)
+  - **Solution:** Refer to the [Configuration: Sandboxing](../cli/sandbox.md)
     documentation for more information, including how to customize your sandbox
     configuration.