@office-ai/aioncli-core 0.26.0 → 0.30.1

package/dist/docs/tools/file-system.md

@@ -1,99 +1,49 @@
-# Gemini CLI file system tools
+# File system tools reference
 
-The Gemini CLI provides a comprehensive suite of tools for interacting with the
-local file system. These tools allow the Gemini model to read from, write to,
-list, search, and modify files and directories, all under your control and
-typically with confirmation for sensitive operations.
+The Gemini CLI core provides a suite of tools for interacting with the local
+file system. These tools allow the model to explore and modify your codebase.
 
-**Note:** All file system tools operate within a `rootDirectory` (usually the
-current working directory where you launched the CLI) for security. Paths that
-you provide to these tools are generally expected to be absolute or are resolved
-relative to this root directory.
+## Technical reference
 
-## 1. `list_directory` (ReadFolder)
+All file system tools operate within a `rootDirectory` (the current working
+directory or workspace root) for security.
 
-`list_directory` lists the names of files and subdirectories directly within a
-specified directory path. It can optionally ignore entries matching provided
-glob patterns.
+### `list_directory` (ReadFolder)
+
+Lists the names of files and subdirectories directly within a specified path.
 
 - **Tool name:** `list_directory`
-- **Display name:** ReadFolder
-- **File:** `ls.ts`
-- **Parameters:**
-  - `path` (string, required): The absolute path to the directory to list.
-  - `ignore` (array of strings, optional): A list of glob patterns to exclude
-    from the listing (e.g., `["*.log", ".git"]`).
-  - `respect_git_ignore` (boolean, optional): Whether to respect `.gitignore`
-    patterns when listing files. Defaults to `true`.
-- **Behavior:**
-  - Returns a list of file and directory names.
-  - Indicates whether each entry is a directory.
-  - Sorts entries with directories first, then alphabetically.
-- **Output (`llmContent`):** A string like:
-  `Directory listing for /path/to/your/folder:\n[DIR] subfolder1\nfile1.txt\nfile2.png`
-- **Confirmation:** No.
+- **Arguments:**
+  - `dir_path` (string, required): Absolute or relative path to the directory.
+  - `ignore` (array, optional): Glob patterns to exclude.
+  - `file_filtering_options` (object, optional): Configuration for `.gitignore`
+    and `.geminiignore` compliance.
 
-## 2. `read_file` (ReadFile)
+### `read_file` (ReadFile)
 
-`read_file` reads and returns the content of a specified file. This tool handles
-text, images (PNG, JPG, GIF, WEBP, SVG, BMP), audio files (MP3, WAV, AIFF, AAC,
-OGG, FLAC), and PDF files. For text files, it can read specific line ranges.
-Other binary file types are generally skipped.
+Reads and returns the content of a specific file. Supports text, images, audio,
+and PDF.
 
 - **Tool name:** `read_file`
-- **Display name:** ReadFile
-- **File:** `read-file.ts`
-- **Parameters:**
-  - `path` (string, required): The absolute path to the file to read.
-  - `offset` (number, optional): For text files, the 0-based line number to
-    start reading from. Requires `limit` to be set.
-  - `limit` (number, optional): For text files, the maximum number of lines to
-    read. If omitted, reads a default maximum (e.g., 2000 lines) or the entire
-    file if feasible.
-- **Behavior:**
-  - For text files: Returns the content. If `offset` and `limit` are used,
-    returns only that slice of lines. Indicates if content was truncated due to
-    line limits or line length limits.
-  - For image, audio, and PDF files: Returns the file content as a
-    base64-encoded data structure suitable for model consumption.
-  - For other binary files: Attempts to identify and skip them, returning a
-    message indicating it's a generic binary file.
-- **Output:** (`llmContent`):
-  - For text files: The file content, potentially prefixed with a truncation
-    message (e.g.,
-    `[File content truncated: showing lines 1-100 of 500 total lines...]\nActual file content...`).
-  - For image/audio/PDF files: An object containing `inlineData` with `mimeType`
-    and base64 `data` (e.g.,
-    `{ inlineData: { mimeType: 'image/png', data: 'base64encodedstring' } }`).
-  - For other binary files: A message like
-    `Cannot display content of binary file: /path/to/data.bin`.
-- **Confirmation:** No.
+- **Arguments:**
+  - `file_path` (string, required): Path to the file.
+  - `offset` (number, optional): Start line for text files (0-based).
+  - `limit` (number, optional): Maximum lines to read.
 
-## 3. `write_file` (WriteFile)
+### `write_file` (WriteFile)
 
-`write_file` writes content to a specified file. If the file exists, it will be
-overwritten. If the file doesn't exist, it (and any necessary parent
-directories) will be created.
+Writes content to a specified file, overwriting it if it exists or creating it
+if not.
 
 - **Tool name:** `write_file`
-- **Display name:** WriteFile
-- **File:** `write-file.ts`
-- **Parameters:**
-  - `file_path` (string, required): The absolute path to the file to write to.
-  - `content` (string, required): The content to write into the file.
-- **Behavior:**
-  - Writes the provided `content` to the `file_path`.
-  - Creates parent directories if they don't exist.
-- **Output (`llmContent`):** A success message, e.g.,
-  `Successfully overwrote file: /path/to/your/file.txt` or
-  `Successfully created and wrote to new file: /path/to/new/file.txt`.
-- **Confirmation:** Yes. Shows a diff of changes and asks for user approval
-  before writing.
+- **Arguments:**
+  - `file_path` (string, required): Path to the file.
+  - `content` (string, required): Data to write.
+- **Confirmation:** Requires manual user approval.
 
-## 4. `glob` (FindFiles)
+### `glob` (FindFiles)
 
-`glob` finds files matching specific glob patterns (e.g., `src/**/*.ts`,
-`*.md`), returning absolute paths sorted by modification time (newest first).
+Finds files matching specific glob patterns across the workspace.
 
 - **Tool name:** `glob`
 - **Display name:** FindFiles
@@ -117,14 +67,13 @@ directories) will be created.
   `Found 5 file(s) matching "*.ts" within src, sorted by modification time (newest first):\nsrc/file1.ts\nsrc/subdir/file2.ts...`
 - **Confirmation:** No.
 
-## 5. `search_file_content` (SearchText)
+## 5. `grep_search` (SearchText)
 
-`search_file_content` searches for a regular expression pattern within the
-content of files in a specified directory. Can filter files by a glob pattern.
-Returns the lines containing matches, along with their file paths and line
-numbers.
+`grep_search` searches for a regular expression pattern within the content of
+files in a specified directory. Can filter files by a glob pattern. Returns the
+lines containing matches, along with their file paths and line numbers.
 
-- **Tool name:** `search_file_content`
+- **Tool name:** `grep_search`
 - **Display name:** SearchText
 - **File:** `grep.ts`
 - **Parameters:**
@@ -162,56 +111,16 @@ This tool is designed for precise, targeted changes and requires significant
 context around the `old_string` to ensure it modifies the correct location.
 
 - **Tool name:** `replace`
-- **Display name:** Edit
-- **File:** `edit.ts`
-- **Parameters:**
-  - `file_path` (string, required): The absolute path to the file to modify.
-  - `old_string` (string, required): The exact literal text to replace.
-
-    **CRITICAL:** This string must uniquely identify the single instance to
-    change. It should include at least 3 lines of context _before_ and _after_
-    the target text, matching whitespace and indentation precisely. If
-    `old_string` is empty, the tool attempts to create a new file at `file_path`
-    with `new_string` as content.
-
-  - `new_string` (string, required): The exact literal text to replace
-    `old_string` with.
-  - `expected_replacements` (number, optional): The number of occurrences to
-    replace. Defaults to `1`.
-
-- **Behavior:**
-  - If `old_string` is empty and `file_path` does not exist, creates a new file
-    with `new_string` as content.
-  - If `old_string` is provided, it reads the `file_path` and attempts to find
-    exactly one occurrence of `old_string`.
-  - If one occurrence is found, it replaces it with `new_string`.
-  - **Enhanced reliability (multi-stage edit correction):** To significantly
-    improve the success rate of edits, especially when the model-provided
-    `old_string` might not be perfectly precise, the tool incorporates a
-    multi-stage edit correction mechanism.
-    - If the initial `old_string` isn't found or matches multiple locations, the
-      tool can leverage the Gemini model to iteratively refine `old_string` (and
-      potentially `new_string`).
-    - This self-correction process attempts to identify the unique segment the
-      model intended to modify, making the `replace` operation more robust even
-      with slightly imperfect initial context.
-- **Failure conditions:** Despite the correction mechanism, the tool will fail
-  if:
-  - `file_path` is not absolute or is outside the root directory.
-  - `old_string` is not empty, but the `file_path` does not exist.
-  - `old_string` is empty, but the `file_path` already exists.
-  - `old_string` is not found in the file after attempts to correct it.
-  - `old_string` is found multiple times, and the self-correction mechanism
-    cannot resolve it to a single, unambiguous match.
-- **Output (`llmContent`):**
-  - On success:
-    `Successfully modified file: /path/to/file.txt (1 replacements).` or
-    `Created new file: /path/to/new_file.txt with provided content.`
-  - On failure: An error message explaining the reason (e.g.,
-    `Failed to edit, 0 occurrences found...`,
-    `Failed to edit, expected 1 occurrences but found 2...`).
-- **Confirmation:** Yes. Shows a diff of the proposed changes and asks for user
-  approval before writing to the file.
-
-These file system tools provide a foundation for the Gemini CLI to understand
-and interact with your local project context.
+- **Arguments:**
+  - `file_path` (string, required): Path to the file.
+  - `instruction` (string, required): Semantic description of the change.
+  - `old_string` (string, required): Exact literal text to find.
+  - `new_string` (string, required): Exact literal text to replace with.
+- **Confirmation:** Requires manual user approval.
+
+## Next steps
+
+- Follow the [File management tutorial](../cli/tutorials/file-management.md) for
+  practical examples.
+- Learn about [Trusted folders](../cli/trusted-folders.md) to manage access
+  permissions.

package/dist/docs/tools/index.md

@@ -1,95 +1,102 @@
 # Gemini CLI tools
 
-The Gemini CLI includes built-in tools that the Gemini model uses to interact
-with your local environment, access information, and perform actions. These
-tools enhance the CLI's capabilities, enabling it to go beyond text generation
-and assist with a wide range of tasks.
-
-## Overview of Gemini CLI tools
-
-In the context of the Gemini CLI, tools are specific functions or modules that
-the Gemini model can request to be executed. For example, if you ask Gemini to
-"Summarize the contents of `my_document.txt`," the model will likely identify
-the need to read that file and will request the execution of the `read_file`
-tool.
-
-The core component (`packages/core`) manages these tools, presents their
-definitions (schemas) to the Gemini model, executes them when requested, and
-returns the results to the model for further processing into a user-facing
-response.
-
-These tools provide the following capabilities:
-
-- **Access local information:** Tools allow Gemini to access your local file
-  system, read file contents, list directories, etc.
-- **Execute commands:** With tools like `run_shell_command`, Gemini can run
-  shell commands (with appropriate safety measures and user confirmation).
-- **Interact with the web:** Tools can fetch content from URLs.
-- **Take actions:** Tools can modify files, write new files, or perform other
-  actions on your system (again, typically with safeguards).
-- **Ground responses:** By using tools to fetch real-time or specific local
-  data, Gemini's responses can be more accurate, relevant, and grounded in your
-  actual context.
-
-## How to use Gemini CLI tools
-
-To use Gemini CLI tools, provide a prompt to the Gemini CLI. The process works
-as follows:
-
-1.  You provide a prompt to the Gemini CLI.
-2.  The CLI sends the prompt to the core.
-3.  The core, along with your prompt and conversation history, sends a list of
-    available tools and their descriptions/schemas to the Gemini API.
-4.  The Gemini model analyzes your request. If it determines that a tool is
-    needed, its response will include a request to execute a specific tool with
-    certain parameters.
-5.  The core receives this tool request, validates it, and (often after user
-    confirmation for sensitive operations) executes the tool.
-6.  The output from the tool is sent back to the Gemini model.
-7.  The Gemini model uses the tool's output to formulate its final answer, which
-    is then sent back through the core to the CLI and displayed to you.
-
-You will typically see messages in the CLI indicating when a tool is being
-called and whether it succeeded or failed.
+Gemini CLI uses tools to interact with your local environment, access
+information, and perform actions on your behalf. These tools extend the model's
+capabilities beyond text generation, letting it read files, execute commands,
+and search the web.
+
+## User-triggered tools
+
+You can directly trigger these tools using special syntax in your prompts.
+
+- **[File access](./file-system.md#read_many_files) (`@`):** Use the `@` symbol
+  followed by a file or directory path to include its content in your prompt.
+  This triggers the `read_many_files` tool.
+- **[Shell commands](./shell.md) (`!`):** Use the `!` symbol followed by a
+  system command to execute it directly. This triggers the `run_shell_command`
+  tool.
+
+## Model-triggered tools
+
+The Gemini model automatically requests these tools when it needs to perform
+specific actions or gather information to fulfill your requests. You do not call
+these tools manually.
+
+### File management
+
+These tools let the model explore and modify your local codebase.
+
+- **[Directory listing](./file-system.md#list_directory) (`list_directory`):**
+  Lists files and subdirectories.
+- **[File reading](./file-system.md#read_file) (`read_file`):** Reads the
+  content of a specific file.
+- **[File writing](./file-system.md#write_file) (`write_file`):** Creates or
+  overwrites a file with new content.
+- **[File search](./file-system.md#glob) (`glob`):** Finds files matching a glob
+  pattern.
+- **[Text search](./file-system.md#search_file_content)
+  (`search_file_content`):** Searches for text within files using grep or
+  ripgrep.
+- **[Text replacement](./file-system.md#replace) (`replace`):** Performs precise
+  edits within a file.
+
+### Agent coordination
+
+These tools help the model manage its plan and interact with you.
+
+- **Ask user (`ask_user`):** Requests clarification or missing information from
+  you via an interactive dialog.
+- **[Memory](./memory.md) (`save_memory`):** Saves important facts to your
+  long-term memory (`GEMINI.md`).
+- **[Todos](./todos.md) (`write_todos`):** Manages a list of subtasks for
+  complex plans.
+- **[Agent Skills](../cli/skills.md) (`activate_skill`):** Loads specialized
+  procedural expertise when needed.
+- **Internal docs (`get_internal_docs`):** Accesses Gemini CLI's own
+  documentation to help answer your questions.
+
+### Information gathering
+
+These tools provide the model with access to external data.
+
+- **[Web fetch](./web-fetch.md) (`web_fetch`):** Retrieves and processes content
+  from specific URLs.
+- **[Web search](./web-search.md) (`google_web_search`):** Performs a Google
+  Search to find up-to-date information.
+
+## How to use tools
+
+You use tools indirectly by providing natural language prompts to Gemini CLI.
+
+1.  **Prompt:** You enter a request or use syntax like `@` or `!`.
+2.  **Request:** The model analyzes your request and identifies if a tool is
+    required.
+3.  **Validation:** If a tool is needed, the CLI validates the parameters and
+    checks your security settings.
+4.  **Confirmation:** For sensitive operations (like writing files), the CLI
+    prompts you for approval.
+5.  **Execution:** The tool runs, and its output is sent back to the model.
+6.  **Response:** The model uses the results to generate a final, grounded
+    answer.
 
 ## Security and confirmation
 
-Many tools, especially those that can modify your file system or execute
-commands (`write_file`, `edit`, `run_shell_command`), are designed with safety
-in mind. The Gemini CLI will typically:
+Safety is a core part of the tool system. To protect your system, Gemini CLI
+implements several safeguards.
 
-- **Require confirmation:** Prompt you before executing potentially sensitive
-  operations, showing you what action is about to be taken.
-- **Utilize sandboxing:** All tools are subject to restrictions enforced by
-  sandboxing (see [Sandboxing in the Gemini CLI](../cli/sandbox.md)). This means
-  that when operating in a sandbox, any tools (including MCP servers) you wish
-  to use must be available _inside_ the sandbox environment. For example, to run
-  an MCP server through `npx`, the `npx` executable must be installed within the
-  sandbox's Docker image or be available in the `sandbox-exec` environment.
+- **User confirmation:** You must manually approve tools that modify files or
+  execute shell commands. The CLI shows you a diff or the exact command before
+  you confirm.
+- **Sandboxing:** You can run tool executions in secure, containerized
+  environments to isolate changes from your host system. For more details, see
+  the [Sandboxing](../cli/sandbox.md) guide.
+- **Trusted folders:** You can configure which directories allow the model to
+  use system tools.
 
-It's important to always review confirmation prompts carefully before allowing a
-tool to proceed.
+Always review confirmation prompts carefully before allowing a tool to execute.
 
-## Learn more about Gemini CLI's tools
+## Next steps
 
-Gemini CLI's built-in tools can be broadly categorized as follows:
-
-- **[File System Tools](./file-system.md):** For interacting with files and
-  directories (reading, writing, listing, searching, etc.).
-- **[Shell Tool](./shell.md) (`run_shell_command`):** For executing shell
+- Learn how to [Provide context](../cli/gemini-md.md) to guide tool use.
+- Explore the [Command reference](../cli/commands.md) for tool-related slash
   commands.
-- **[Web Fetch Tool](./web-fetch.md) (`web_fetch`):** For retrieving content
-  from URLs.
-- **[Web Search Tool](./web-search.md) (`google_web_search`):** For searching
-  the web.
-- **[Memory Tool](./memory.md) (`save_memory`):** For saving and recalling
-  information across sessions.
-- **[Todo Tool](./todos.md) (`write_todos`):** For managing subtasks of complex
-  requests.
-
-Additionally, these tools incorporate:
-
-- **[MCP servers](./mcp-server.md)**: MCP servers act as a bridge between the
-  Gemini model and your local environment or other services like APIs.
-- **[Sandboxing](../cli/sandbox.md)**: Sandboxing isolates the model and its
-  changes from your environment to reduce potential risk.

package/dist/docs/tools/internal-docs.md

@@ -0,0 +1,46 @@
+# Internal documentation tool (`get_internal_docs`)
+
+The `get_internal_docs` tool lets Gemini CLI access its own technical
+documentation to provide more accurate answers about its capabilities and usage.
+
+## Description
+
+This tool is used when Gemini CLI needs to verify specific details about Gemini
+CLI's internal features, built-in commands, or configuration options. It
+provides direct access to the Markdown files in the `docs/` directory.
+
+### Arguments
+
+`get_internal_docs` takes one optional argument:
+
+- `path` (string, optional): The relative path to a specific documentation file
+  (for example, `cli/commands.md`). If omitted, the tool returns a list of all
+  available documentation paths.
+
+## Usage
+
+The `get_internal_docs` tool is used exclusively by Gemini CLI. You cannot
+invoke this tool manually.
+
+When Gemini CLI uses this tool, it retrieves the content of the requested
+documentation file and processes it to answer your question. This ensures that
+the information provided by the AI is grounded in the latest project
+documentation.
+
+## Behavior
+
+Gemini CLI uses this tool to ensure technical accuracy:
+
+- **Capability discovery:** If Gemini CLI is unsure how a feature works, it can
+  lookup the corresponding documentation.
+- **Reference lookup:** Gemini CLI can verify slash command sub-commands or
+  specific setting names.
+- **Self-correction:** Gemini CLI can use the documentation to correct its
+  understanding of Gemini CLI's system logic.
+
+## Next steps
+
+- Explore the [Command reference](../cli/commands.md) for a detailed guide to
+  slash commands.
+- See the [Configuration guide](../get-started/configuration.md) for settings
+  reference.

package/dist/docs/tools/mcp-server.md

@@ -101,8 +101,8 @@ execution.
 
 #### Global MCP settings (`mcp`)
 
-The `mcp` object in your `settings.json` allows you to define global rules for
-all MCP servers.
+The `mcp` object in your `settings.json` lets you define global rules for all
+MCP servers.
 
 - **`mcp.serverCommand`** (string): A global command to start an MCP server.
 - **`mcp.allowed`** (array of strings): A list of MCP server names to allow. If
@@ -722,7 +722,8 @@ The MCP integration tracks several states:
 
 ### Debugging tips
 
-1. **Enable debug mode:** Run the CLI with `--debug` for verbose output
+1. **Enable debug mode:** Run the CLI with `--debug` for verbose output (use F12
+   to open debug console in interactive mode)
 2. **Check stderr:** MCP server stderr is captured and logged (INFO messages
    filtered)
 3. **Test isolation:** Test your MCP server independently before integrating
@@ -732,7 +733,7 @@ The MCP integration tracks several states:
 
 ## Important notes
 
-### Security sonsiderations
+### Security considerations
 
 - **Trust settings:** The `trust` option bypasses all confirmation dialogs. Use
   cautiously and only for servers you completely control
@@ -741,7 +742,7 @@ The MCP integration tracks several states:
 - **Sandbox compatibility:** When using sandboxing, ensure MCP servers are
   available within the sandbox environment
 - **Private data:** Using broadly scoped personal access tokens can lead to
-  information leakage between repositories
+  information leakage between repositories.
 
 ### Performance and resource management
 
@@ -1037,6 +1038,29 @@ gemini mcp remove my-server
 This will find and delete the "my-server" entry from the `mcpServers` object in
 the appropriate `settings.json` file based on the scope (`-s, --scope`).
 
+### Enabling/disabling a server (`gemini mcp enable`, `gemini mcp disable`)
+
+Temporarily disable an MCP server without removing its configuration, or
+re-enable a previously disabled server.
+
+**Commands:**
+
+```bash
+gemini mcp enable <name> [--session]
+gemini mcp disable <name> [--session]
+```
+
+**Options (flags):**
+
+- `--session`: Apply change only for this session (not persisted to file).
+
+Disabled servers appear in `/mcp` status as "Disabled" but won't connect or
+provide tools. Enablement state is stored in
+`~/.gemini/mcp-server-enablement.json`.
+
+The same commands are available as slash commands during an active session:
+`/mcp enable <name>` and `/mcp disable <name>`.
+
 ## Instructions
 
 Gemini CLI supports

package/dist/docs/tools/memory.md

@@ -1,54 +1,35 @@
 # Memory tool (`save_memory`)
 
-This document describes the `save_memory` tool for the Gemini CLI.
+The `save_memory` tool allows the Gemini agent to persist specific facts, user
+preferences, and project details across sessions.
 
-## Description
+## Technical reference
 
-Use `save_memory` to save and recall information across your Gemini CLI
-sessions. With `save_memory`, you can direct the CLI to remember key details
-across sessions, providing personalized and directed assistance.
+This tool appends information to the `## Gemini Added Memories` section of your
+global `GEMINI.md` file (typically located at `~/.gemini/GEMINI.md`).
 
 ### Arguments
 
-`save_memory` takes one argument:
-
-- `fact` (string, required): The specific fact or piece of information to
-  remember. This should be a clear, self-contained statement written in natural
+- `fact` (string, required): A clear, self-contained statement in natural
   language.
 
-## How to use `save_memory` with the Gemini CLI
-
-The tool appends the provided `fact` to a special `GEMINI.md` file located in
-the user's home directory (`~/.gemini/GEMINI.md`). This file can be configured
-to have a different name.
-
-Once added, the facts are stored under a `## Gemini Added Memories` section.
-This file is loaded as context in subsequent sessions, allowing the CLI to
-recall the saved information.
-
-Usage:
-
-```
-save_memory(fact="Your fact here.")
-```
-
-### `save_memory` examples
-
-Remember a user preference:
+## Technical behavior
 
-```
-save_memory(fact="My preferred programming language is Python.")
-```
+- **Storage:** Appends to the global context file in the user's home directory.
+- **Loading:** The stored facts are automatically included in the hierarchical
+  context system for all future sessions.
+- **Format:** Saves data as a bulleted list item within a dedicated Markdown
+  section.
 
-Store a project-specific detail:
+## Use cases
 
-```
-save_memory(fact="The project I'm currently working on is called 'gemini-cli'.")
-```
+- Persisting user preferences (for example, "I prefer functional programming").
+- Saving project-wide architectural decisions.
+- Storing frequently used aliases or system configurations.
 
-## Important notes
+## Next steps
 
-- **General usage:** This tool should be used for concise, important facts. It
-  is not intended for storing large amounts of data or conversational history.
-- **Memory file:** The memory file is a plain text Markdown file, so you can
-  view and edit it manually if needed.
+- Follow the [Memory management guide](../cli/tutorials/memory-management.md)
+  for practical examples.
+- Learn how the [Project context (GEMINI.md)](../cli/gemini-md.md) system loads
+  this information.