@office-ai/aioncli-core 0.26.0 → 0.30.1

package/dist/docs/cli/index.md

@@ -1,63 +1,123 @@
-# Gemini CLI
-
-Within Gemini CLI, `packages/cli` is the frontend for users to send and receive
-prompts with the Gemini AI model and its associated tools. For a general
-overview of Gemini CLI, see the [main documentation page](../index.md).
-
-## Basic features
-
-- **[Commands](./commands.md):** A reference for all built-in slash commands
-- **[Custom commands](./custom-commands.md):** Create your own commands and
-  shortcuts for frequently used prompts.
-- **[Headless mode](./headless.md):** Use Gemini CLI programmatically for
-  scripting and automation.
-- **[Model selection](./model.md):** Configure the Gemini AI model used by the
-  CLI.
-- **[Settings](./settings.md):** Configure various aspects of the CLI's behavior
-  and appearance.
-- **[Themes](./themes.md):** Customizing the CLI's appearance with different
-  themes.
-- **[Keyboard shortcuts](./keyboard-shortcuts.md):** A reference for all
-  keyboard shortcuts to improve your workflow.
-- **[Tutorials](./tutorials.md):** Step-by-step guides for common tasks.
-
-## Advanced features
-
-- **[Checkpointing](./checkpointing.md):** Automatically save and restore
-  snapshots of your session and files.
-- **[Enterprise configuration](./enterprise.md):** Deploying and manage Gemini
-  CLI in an enterprise environment.
-- **[Sandboxing](./sandbox.md):** Isolate tool execution in a secure,
-  containerized environment.
-- **[Telemetry](./telemetry.md):** Configure observability to monitor usage and
-  performance.
-- **[Token caching](./token-caching.md):** Optimize API costs by caching tokens.
-- **[Trusted folders](./trusted-folders.md):** A security feature to control
-  which projects can use the full capabilities of the CLI.
-- **[Ignoring files (.geminiignore)](./gemini-ignore.md):** Exclude specific
-  files and directories from being accessed by tools.
-- **[Context files (GEMINI.md)](./gemini-md.md):** Provide persistent,
-  hierarchical context to the model.
-- **[System prompt override](./system-prompt.md):** Replace the built‑in system
-  instructions using `GEMINI_SYSTEM_MD`.
-
-## Non-interactive mode
-
-Gemini CLI can be run in a non-interactive mode, which is useful for scripting
-and automation. In this mode, you pipe input to the CLI, it executes the
-command, and then it exits.
-
-The following example pipes a command to Gemini CLI from your terminal:
-
-```bash
-echo "What is fine tuning?" | gemini
-```
-
-You can also use the `--prompt` or `-p` flag:
-
-```bash
-gemini -p "What is fine tuning?"
-```
-
-For comprehensive documentation on headless usage, scripting, automation, and
-advanced examples, see the **[Headless mode](./headless.md)** guide.
+# Using Gemini CLI
+
+Gemini CLI is a terminal-first interface that brings the power of Gemini AI
+models directly into your development workflow. It lets you interact with AI
+using your local files, shell environment, and project context, creating a
+bridge between generative AI and your system tools.
+
+## User guides
+
+These guides provide step-by-step instructions and practical examples for using
+Gemini CLI in your daily development workflow.
+
+- **[Quickstart](../get-started/index.md):** Get up and running with Gemini CLI
+  in minutes.
+- **[Examples](../get-started/examples.md):** See practical examples of Gemini
+  CLI in action.
+- **[Get started with skills](./tutorials/skills-getting-started.md):** Learn
+  how to use and manage specialized expertise.
+- **[File management](./tutorials/file-management.md):** How to include, search,
+  and modify local files.
+- **[Set up an MCP server](./tutorials/mcp-setup.md):** Configure Model Context
+  Protocol servers for custom tools.
+- **[Manage context and memory](./tutorials/memory-management.md):** Manage
+  persistent instructions and individual facts.
+- **[Manage sessions and history](./tutorials/session-management.md):** Resume,
+  manage, and rewind your conversations.
+- **[Execute shell commands](./tutorials/shell-commands.md):** Execute system
+  commands safely directly from your prompt.
+- **[Plan tasks with todos](./tutorials/task-planning.md):** Using todos for
+  complex, multi-step agent requests.
+- **[Web search and fetch](./tutorials/web-tools.md):** Searching and fetching
+  content from the web.
+
+## Features
+
+Technical reference documentation for each capability of Gemini CLI.
+
+- **[/about](../cli/commands.md#about):** Show version info.
+- **[/auth](../cli/commands.md#auth):** Change authentication method.
+- **[/bug](../cli/commands.md#bug):** File an issue about Gemini CLI.
+- **[/chat](../cli/commands.md#chat):** Save and resume conversation history.
+- **[/clear](../cli/commands.md#clear):** Clear the terminal screen.
+- **[/compress](../cli/commands.md#compress):** Replace context with a summary.
+- **[/copy](../cli/commands.md#copy):** Copy output to clipboard.
+- **[/directory](../cli/commands.md#directory-or-dir):** Manage workspace
+  directories.
+- **[/docs](../cli/commands.md#docs):** Open documentation in browser.
+- **[/editor](../cli/commands.md#editor):** Select preferred editor.
+- **[/extensions](../cli/commands.md#extensions):** List active extensions.
+- **[/help](../cli/commands.md#help-or):** Display help information.
+- **[/hooks](../hooks/index.md):** Manage hooks for lifecycle events.
+- **[/ide](../ide-integration/index.md):** Manage IDE integration.
+- **[/init](../cli/commands.md#init):** Create a GEMINI.md context file.
+- **[/mcp](../tools/mcp-server.md):** Manage Model Context Protocol servers.
+- **[/memory](../cli/commands.md#memory):** Manage instructional context.
+- **[/model](./model.md):** Choose Gemini model.
+- **[/policies](../cli/commands.md#policies):** Manage security policies.
+- **[/privacy](../cli/commands.md#privacy):** Display privacy notice.
+- **[/quit](../cli/commands.md#quit-or-exit):** Exit Gemini CLI.
+- **[/restore](../cli/commands.md#restore):** Restore file state.
+- **[/resume](../cli/commands.md#resume):** Browse and resume sessions.
+- **[/rewind](./rewind.md):** Navigate backward through history.
+- **[/settings](./settings.md):** Open settings editor.
+- **[/setup-github](../cli/commands.md#setup-github):** Set up GitHub Actions.
+- **[/shells](../cli/commands.md#shells-or-bashes):** Toggle background shells
+  view.
+- **[/skills](./skills.md):** Manage Agent Skills.
+- **[/stats](../cli/commands.md#stats):** Display session statistics.
+- **[/terminal-setup](../cli/commands.md#terminal-setup):** Configure
+  keybindings.
+- **[/theme](./themes.md):** Change visual theme.
+- **[/tools](../cli/commands.md#tools):** Display list of available tools.
+- **[/vim](../cli/commands.md#vim):** Toggle vim mode.
+- **[Activate skill (tool)](../tools/activate-skill.md):** Internal mechanism
+  for loading expert procedures.
+- **[Ask user (tool)](../tools/ask-user.md):** Internal dialog system for
+  clarification.
+- **[Checkpointing](./checkpointing.md):** Automatic session snapshots.
+- **[File system (tool)](../tools/file-system.md):** Technical details for local
+  file operations.
+- **[Headless mode](./headless.md):** Programmatic and scripting interface.
+- **[Internal documentation (tool)](../tools/internal-docs.md):** Technical
+  lookup for CLI features.
+- **[Memory (tool)](../tools/memory.md):** Storage details for persistent facts.
+- **[Model routing](./model-routing.md):** Automatic fallback resilience.
+- **[Plan mode (experimental)](./plan-mode.md):** Use a safe, read-only mode for
+  planning complex changes.
+- **[Sandboxing](./sandbox.md):** Isolate tool execution.
+- **[Shell (tool)](../tools/shell.md):** Detailed system execution parameters.
+- **[Telemetry](./telemetry.md):** Usage and performance metric details.
+- **[Todo (tool)](../tools/todos.md):** Progress tracking specification.
+- **[Token caching](./token-caching.md):** Performance optimization.
+- **[Web fetch (tool)](../tools/web-fetch.md):** URL retrieval and extraction
+  details.
+- **[Web search (tool)](../tools/web-search.md):** Google Search integration
+  technicals.
+
+## Configuration
+
+Settings and customization options for Gemini CLI.
+
+- **[Custom commands](./custom-commands.md):** Personalized shortcuts.
+- **[Enterprise configuration](./enterprise.md):** Professional environment
+  controls.
+- **[Ignore files (.geminiignore)](./gemini-ignore.md):** Exclusion pattern
+  reference.
+- **[Model configuration](./generation-settings.md):** Fine-tune generation
+  parameters like temperature and thinking budget.
+- **[Project context (GEMINI.md)](./gemini-md.md):** Technical hierarchy of
+  context files.
+- **[Settings](./settings.md):** Full `settings.json` schema.
+- **[System prompt override](./system-prompt.md):** Instruction replacement
+  logic.
+- **[Themes](./themes.md):** UI personalization technical guide.
+- **[Trusted folders](./trusted-folders.md):** Security permission logic.
+
+## Next steps
+
+- Explore the [Command reference](./commands.md) to learn about all available
+  slash commands.
+- Read about [Project context](./gemini-md.md) to understand how to provide
+  persistent instructions to the model.
+- See the [CLI reference](./cli-reference.md) for a quick cheatsheet of flags.

package/dist/docs/cli/keyboard-shortcuts.md

@@ -8,43 +8,50 @@ available combinations.
 
 #### Basic Controls
 
-| Action                                       | Keys    |
-| -------------------------------------------- | ------- |
-| Confirm the current selection or choice.     | `Enter` |
-| Dismiss dialogs or cancel the current focus. | `Esc`   |
+| Action                                                          | Keys                  |
+| --------------------------------------------------------------- | --------------------- |
+| Confirm the current selection or choice.                        | `Enter`               |
+| Dismiss dialogs or cancel the current focus.                    | `Esc`<br />`Ctrl + [` |
+| Cancel the current request or quit the CLI when input is empty. | `Ctrl + C`            |
+| Exit the CLI when the input buffer is empty.                    | `Ctrl + D`            |
 
 #### Cursor Movement
 
-| Action                                    | Keys                   |
-| ----------------------------------------- | ---------------------- |
-| Move the cursor to the start of the line. | `Ctrl + A`<br />`Home` |
-| Move the cursor to the end of the line.   | `Ctrl + E`<br />`End`  |
+| Action                                      | Keys                                                         |
+| ------------------------------------------- | ------------------------------------------------------------ |
+| Move the cursor to the start of the line.   | `Ctrl + A`<br />`Home (no Shift, Ctrl)`                      |
+| Move the cursor to the end of the line.     | `Ctrl + E`<br />`End (no Shift, Ctrl)`                       |
+| Move the cursor up one line.                | `Up Arrow (no Shift, Alt, Ctrl, Cmd)`                        |
+| Move the cursor down one line.              | `Down Arrow (no Shift, Alt, Ctrl, Cmd)`                      |
+| Move the cursor one character to the left.  | `Left Arrow (no Shift, Alt, Ctrl, Cmd)`                      |
+| Move the cursor one character to the right. | `Right Arrow (no Shift, Alt, Ctrl, Cmd)`<br />`Ctrl + F`     |
+| Move the cursor one word to the left.       | `Ctrl + Left Arrow`<br />`Alt + Left Arrow`<br />`Alt + B`   |
+| Move the cursor one word to the right.      | `Ctrl + Right Arrow`<br />`Alt + Right Arrow`<br />`Alt + F` |
 
 #### Editing
 
-| Action                                           | Keys                                      |
-| ------------------------------------------------ | ----------------------------------------- |
-| Delete from the cursor to the end of the line.   | `Ctrl + K`                                |
-| 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 />`Cmd + Backspace` |
-
-#### Screen Control
-
-| Action                                       | Keys       |
-| -------------------------------------------- | ---------- |
-| Clear the terminal screen and redraw the UI. | `Ctrl + L` |
+| Action                                           | Keys                                                             |
+| ------------------------------------------------ | ---------------------------------------------------------------- |
+| Delete from the cursor to the end of the line.   | `Ctrl + K`                                                       |
+| 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 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)`                   |
+| Redo the most recent undone text edit.           | `Shift + Ctrl + Z`<br />`Shift + Cmd + Z`<br />`Shift + Alt + Z` |
 
 #### Scrolling
 
-| Action                   | Keys                 |
-| ------------------------ | -------------------- |
-| Scroll content up.       | `Shift + Up Arrow`   |
-| Scroll content down.     | `Shift + Down Arrow` |
-| Scroll to the top.       | `Home`               |
-| Scroll to the bottom.    | `End`                |
-| Scroll up by one page.   | `Page Up`            |
-| Scroll down by one page. | `Page Down`          |
+| Action                   | Keys                              |
+| ------------------------ | --------------------------------- |
+| Scroll content up.       | `Shift + Up Arrow`                |
+| Scroll content down.     | `Shift + Down Arrow`              |
+| Scroll to the top.       | `Ctrl + Home`<br />`Shift + Home` |
+| Scroll to the bottom.    | `Ctrl + End`<br />`Shift + End`   |
+| Scroll up by one page.   | `Page Up`                         |
+| Scroll down by one page. | `Page Down`                       |
 
 #### History & Search
 
@@ -53,17 +60,20 @@ available combinations.
 | Show the previous entry in history.          | `Ctrl + P (no Shift)` |
 | Show the next entry in history.              | `Ctrl + N (no Shift)` |
 | Start reverse search through history.        | `Ctrl + R`            |
-| Insert the selected reverse-search match.    | `Enter (no Ctrl)`     |
+| Submit the selected reverse-search match.    | `Enter (no Ctrl)`     |
 | Accept a suggestion while reverse searching. | `Tab`                 |
+| Browse and rewind previous interactions.     | `Double Esc`          |
 
 #### Navigation
 
-| Action                           | Keys                                        |
-| -------------------------------- | ------------------------------------------- |
-| Move selection up in lists.      | `Up Arrow (no Shift)`                       |
-| Move selection down in lists.    | `Down Arrow (no Shift)`                     |
-| Move up within dialog options.   | `Up Arrow (no Shift)`<br />`K (no Shift)`   |
-| Move down within dialog options. | `Down Arrow (no Shift)`<br />`J (no Shift)` |
+| Action                                             | Keys                                        |
+| -------------------------------------------------- | ------------------------------------------- |
+| Move selection up in lists.                        | `Up Arrow (no Shift)`                       |
+| Move selection down in lists.                      | `Down Arrow (no Shift)`                     |
+| Move up within dialog options.                     | `Up Arrow (no Shift)`<br />`K (no Shift)`   |
+| Move down within dialog options.                   | `Down Arrow (no Shift)`<br />`J (no Shift)` |
+| Move to the next item or question in a dialog.     | `Tab (no Shift)`                            |
+| Move to the previous item or question in a dialog. | `Shift + Tab`                               |
 
 #### Suggestions & Completions
 
@@ -77,67 +87,68 @@ available combinations.
 
 #### Text Input
 
-| Action                               | Keys                                                                                        |
-| ------------------------------------ | ------------------------------------------------------------------------------------------- |
-| Submit the current prompt.           | `Enter (no Ctrl, no Shift, no Cmd, not Paste)`                                              |
-| Insert a newline without submitting. | `Ctrl + Enter`<br />`Cmd + Enter`<br />`Paste + Enter`<br />`Shift + Enter`<br />`Ctrl + J` |
-
-#### External Tools
-
-| Action                                         | Keys                      |
-| ---------------------------------------------- | ------------------------- |
-| Open the current prompt in an external editor. | `Ctrl + X`                |
-| Paste from the clipboard.                      | `Ctrl + V`<br />`Cmd + V` |
+| Action                                         | Keys                                                                                      |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| Submit the current prompt.                     | `Enter (no Shift, Alt, Ctrl, Cmd)`                                                        |
+| Insert a newline without submitting.           | `Ctrl + Enter`<br />`Cmd + Enter`<br />`Alt + Enter`<br />`Shift + Enter`<br />`Ctrl + J` |
+| Open the current prompt in an external editor. | `Ctrl + X`                                                                                |
+| Paste from the clipboard.                      | `Ctrl + V`<br />`Cmd + V`<br />`Alt + V`                                                  |
 
 #### App Controls
 
-| Action                                                            | Keys       |
-| ----------------------------------------------------------------- | ---------- |
-| Toggle detailed error information.                                | `F12`      |
-| Toggle the full TODO list.                                        | `Ctrl + T` |
-| Toggle IDE context details.                                       | `Ctrl + G` |
-| Toggle Markdown rendering.                                        | `Cmd + M`  |
-| Toggle copy mode when the terminal is using the alternate buffer. | `Ctrl + S` |
-| Expand a height-constrained response to show additional lines.    | `Ctrl + S` |
-| Toggle focus between the shell and Gemini input.                  | `Ctrl + F` |
-
-#### Session Control
-
-| Action                                       | Keys       |
-| -------------------------------------------- | ---------- |
-| Cancel the current request or quit the CLI.  | `Ctrl + C` |
-| Exit the CLI when the input buffer is empty. | `Ctrl + D` |
+| Action                                                                                                                                             | Keys             |
+| -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
+| Toggle detailed error information.                                                                                                                 | `F12`            |
+| Toggle the full TODO list.                                                                                                                         | `Ctrl + T`       |
+| Show IDE context details.                                                                                                                          | `Ctrl + G`       |
+| Toggle Markdown rendering.                                                                                                                         | `Alt + M`        |
+| Toggle copy mode when in alternate buffer mode.                                                                                                    | `Ctrl + S`       |
+| Toggle YOLO (auto-approval) mode for tool calls.                                                                                                   | `Ctrl + Y`       |
+| Cycle through approval modes: default (prompt), auto_edit (auto-approve edits), and plan (read-only). Plan mode is skipped when the agent is busy. | `Shift + Tab`    |
+| Expand and collapse blocks of content when not in alternate buffer mode.                                                                           | `Ctrl + O`       |
+| Expand or collapse a paste placeholder when cursor is over placeholder.                                                                            | `Ctrl + O`       |
+| Toggle current background shell visibility.                                                                                                        | `Ctrl + B`       |
+| Toggle background shell list.                                                                                                                      | `Ctrl + L`       |
+| Kill the active background shell.                                                                                                                  | `Ctrl + K`       |
+| Confirm selection in background shell list.                                                                                                        | `Enter`          |
+| Dismiss background shell list.                                                                                                                     | `Esc`            |
+| Move focus from background shell to Gemini.                                                                                                        | `Shift + Tab`    |
+| Move focus from background shell list to Gemini.                                                                                                   | `Tab (no Shift)` |
+| Show warning when trying to move focus away from background shell.                                                                                 | `Tab (no Shift)` |
+| Show warning when trying to move focus away from shell input.                                                                                      | `Tab (no Shift)` |
+| Move focus from Gemini to the active shell.                                                                                                        | `Tab (no Shift)` |
+| Move focus from the shell back to Gemini.                                                                                                          | `Shift + Tab`    |
+| Clear the terminal screen and redraw the UI.                                                                                                       | `Ctrl + L`       |
+| Restart the application.                                                                                                                           | `R`              |
+| Suspend the CLI and move it to the background.                                                                                                     | `Ctrl + Z`       |
 
 <!-- KEYBINDINGS-AUTOGEN:END -->
 
 ## Additional context-specific shortcuts
 
-- `Ctrl+Y`: Toggle YOLO (auto-approval) mode for tool calls.
-- `Shift+Tab`: Toggle Auto Edit (auto-accept edits) mode.
-- `Option+M` (macOS): Entering `µ` with Option+M also toggles Markdown
-  rendering, matching `Cmd+M`.
+- `Option+B/F/M` (macOS only): Are interpreted as `Cmd+B/F/M` even if your
+  terminal isn't configured to send Meta with Option.
 - `!` on an empty prompt: Enter or exit shell mode.
+- `?` on an empty prompt: Toggle the shortcuts panel above the input. Press
+  `Esc`, `Backspace`, any printable key, or a registered app hotkey to close it.
+  The panel also auto-hides while the agent is running/streaming or when
+  action-required dialogs are shown. Press `?` again to close the panel and
+  insert a `?` into the prompt.
+- `Tab` + `Tab` (while typing in the prompt): Toggle between minimal and full UI
+  details when no completion/search interaction is active. The selected mode is
+  remembered for future sessions. Full UI remains the default on first run, and
+  single `Tab` keeps its existing completion/focus behavior.
+- `Shift + Tab` (while typing in the prompt): Cycle approval modes: default,
+  auto-edit, and plan (skipped when agent is busy).
 - `\` (at end of a line) + `Enter`: Insert a newline without leaving single-line
   mode.
-- `Ctrl+Delete` / `Meta+Delete`: Delete the word to the right of the cursor.
-- `Ctrl+B` or `Left Arrow`: Move the cursor one character to the left while
-  editing text.
-- `Ctrl+F` or `Right Arrow`: Move the cursor one character to the right; with an
-  embedded shell attached, `Ctrl+F` still toggles focus.
-- `Ctrl+D` or `Delete`: Remove the character immediately to the right of the
-  cursor.
-- `Ctrl+H` or `Backspace`: Remove the character immediately to the left of the
-  cursor.
-- `Ctrl+Left Arrow` / `Meta+Left Arrow` / `Meta+B`: Move one word to the left.
-- `Ctrl+Right Arrow` / `Meta+Right Arrow` / `Meta+F`: Move one word to the
-  right.
-- `Ctrl+W`: Delete the word to the left of the cursor (in addition to
-  `Ctrl+Backspace` / `Cmd+Backspace`).
-- `Ctrl+Z` / `Ctrl+Shift+Z`: Undo or redo the most recent text edit.
-- `Meta+Enter`: Open the current input in an external editor (alias for
-  `Ctrl+X`).
-- `Esc` pressed twice quickly: Clear the current input buffer.
+- `Esc` pressed twice quickly: Clear the input prompt if it is not empty,
+  otherwise browse and rewind previous interactions.
 - `Up Arrow` / `Down Arrow`: When the cursor is at the top or bottom of a
   single-line input, navigate backward or forward through prompt history.
 - `Number keys (1-9, multi-digit)` inside selection dialogs: Jump directly to
   the numbered radio option and confirm when the full number is entered.
+- `Ctrl + O`: Expand or collapse paste placeholders (`[Pasted Text: X lines]`)
+  inline when the cursor is over the placeholder.
+- `Double-click` on a paste placeholder (alternate buffer mode only): Expand to
+  view full content inline. Double-click again to collapse.

package/dist/docs/cli/model-routing.md

@@ -1,4 +1,4 @@
-## Model routing
+# Model routing
 
 Gemini CLI includes a model routing feature that automatically switches to a
 fallback model in case of a model failure. This feature is enabled by default
@@ -11,12 +11,17 @@ health and automatically routes requests to available models based on defined
 policies.
 
 1.  **Model failure:** If the currently selected model fails (e.g., due to quota
-    or server errors), the CLI will iniate the fallback process.
+    or server errors), the CLI will initiate the fallback process.
 
 2.  **User consent:** Depending on the failure and the model's policy, the CLI
     may prompt you to switch to a fallback model (by default always prompts
     you).
 
+    Some internal utility calls (such as prompt completion and classification)
+    use a silent fallback chain for `gemini-2.5-flash-lite` and will fall back
+    to `gemini-2.5-flash` and `gemini-2.5-pro` without prompting or changing the
+    configured model.
+
 3.  **Model switch:** If approved, or if the policy allows for silent fallback,
     the CLI will use an available fallback model for the current turn or the
     remainder of the session.

package/dist/docs/cli/model.md

@@ -39,7 +39,7 @@ To enable Gemini 3 Pro and Gemini 3 Flash (if available), enable
 
 You can also use the `--model` flag to specify a particular Gemini model on
 startup. For more details, refer to the
-[configuration documentation](./configuration.md).
+[configuration documentation](../get-started/configuration.md).
 
 Changes to these settings will be applied to all subsequent interactions with
 Gemini CLI.

package/dist/docs/cli/notifications.md

@@ -0,0 +1,58 @@
+# Notifications (experimental)
+
+Gemini CLI can send system notifications to alert you when a session completes
+or when it needs your attention, such as when it's waiting for you to approve a
+tool call.
+
+> **Note:** This is a preview feature currently under active development.
+> Preview features may be available on the **Preview** channel or may need to be
+> enabled under `/settings`.
+
+Notifications are particularly useful when running long-running tasks or using
+[Plan Mode](./plan-mode.md), letting you switch to other windows while Gemini
+CLI works in the background.
+
+## Requirements
+
+Currently, system notifications are only supported on macOS.
+
+### Terminal support
+
+The CLI uses the OSC 9 terminal escape sequence to trigger system notifications.
+This is supported by several modern terminal emulators. If your terminal does
+not support OSC 9 notifications, Gemini CLI falls back to a system alert sound
+to get your attention.
+
+## Enable notifications
+
+Notifications are disabled by default. You can enable them using the `/settings`
+command or by updating your `settings.json` file.
+
+1.  Open the settings dialog by typing `/settings` in an interactive session.
+2.  Navigate to the **General** category.
+3.  Toggle the **Enable Notifications** setting to **On**.
+
+Alternatively, add the following to your `settings.json`:
+
+```json
+{
+  "general": {
+    "enableNotifications": true
+  }
+}
+```
+
+## Types of notifications
+
+Gemini CLI sends notifications for the following events:
+
+- **Action required:** Triggered when the model is waiting for user input or
+  tool approval. This helps you know when the CLI has paused and needs you to
+  intervene.
+- **Session complete:** Triggered when a session finishes successfully. This is
+  useful for tracking the completion of automated tasks.
+
+## Next steps
+
+- Start planning with [Plan Mode](./plan-mode.md).
+- Configure your experience with other [settings](./settings.md).