@office-ai/aioncli-core 0.26.0 → 0.30.0

package/dist/docs/cli/plan-mode.md

@@ -0,0 +1,190 @@
+# Plan Mode (experimental)
+
+Plan Mode is a safe, read-only mode for researching and designing complex
+changes. It prevents modifications while you research, design and plan an
+implementation strategy.
+
+> **Note: Plan Mode is currently an experimental feature.**
+>
+> Experimental features are subject to change. To use Plan Mode, enable it via
+> `/settings` (search for `Plan`) or add the following to your `settings.json`:
+>
+> ```json
+> {
+>   "experimental": {
+>     "plan": true
+>   }
+> }
+> ```
+>
+> Your feedback is invaluable as we refine this feature. If you have ideas,
+> suggestions, or encounter issues:
+>
+> - Use the `/bug` command within the CLI to file an issue.
+> - [Open an issue](https://github.com/google-gemini/gemini-cli/issues) on
+>   GitHub.
+
+- [Starting in Plan Mode](#starting-in-plan-mode)
+- [How to use Plan Mode](#how-to-use-plan-mode)
+  - [Entering Plan Mode](#entering-plan-mode)
+  - [The Planning Workflow](#the-planning-workflow)
+  - [Exiting Plan Mode](#exiting-plan-mode)
+- [Tool Restrictions](#tool-restrictions)
+  - [Customizing Planning with Skills](#customizing-planning-with-skills)
+  - [Customizing Policies](#customizing-policies)
+
+## Starting in Plan Mode
+
+You can configure Gemini CLI to start directly in Plan Mode by default:
+
+1.  Type `/settings` in the CLI.
+2.  Search for `Default Approval Mode`.
+3.  Set the value to `Plan`.
+
+Other ways to start in Plan Mode:
+
+- **CLI Flag:** `gemini --approval-mode=plan`
+- **Manual Settings:** Manually update your `settings.json`:
+
+  ```json
+  {
+    "general": {
+      "defaultApprovalMode": "plan"
+    }
+  }
+  ```
+
+## How to use Plan Mode
+
+### Entering Plan Mode
+
+You can enter Plan Mode in three ways:
+
+1.  **Keyboard Shortcut:** Press `Shift+Tab` to cycle through approval modes
+    (`Default` -> `Auto-Edit` -> `Plan`).
+
+    > **Note:** Plan Mode is automatically removed from the rotation when the
+    > agent is actively processing or showing confirmation dialogs.
+
+2.  **Command:** Type `/plan` in the input box.
+3.  **Natural Language:** Ask the agent to "start a plan for...". The agent will
+    then call the [`enter_plan_mode`] tool to switch modes.
+
+### The Planning Workflow
+
+1.  **Requirements:** The agent clarifies goals using [`ask_user`].
+2.  **Exploration:** The agent uses read-only tools (like [`read_file`]) to map
+    the codebase and validate assumptions.
+3.  **Design:** The agent proposes alternative approaches with a recommended
+    solution for you to choose from.
+4.  **Planning:** A detailed plan is written to a temporary Markdown file.
+5.  **Review:** You review the plan.
+    - **Approve:** Exit Plan Mode and start implementation (switching to
+      Auto-Edit or Default approval mode).
+    - **Iterate:** Provide feedback to refine the plan.
+
+### Exiting Plan Mode
+
+To exit Plan Mode:
+
+1. **Keyboard Shortcut:** Press `Shift+Tab` to cycle to the desired mode.
+2. **Tool:** The agent calls the [`exit_plan_mode`] tool to present the
+   finalized plan for your approval.
+
+## Tool Restrictions
+
+Plan Mode enforces strict safety policies to prevent accidental changes.
+
+These are the only allowed tools:
+
+- **FileSystem (Read):** [`read_file`], [`list_directory`], [`glob`]
+- **Search:** [`grep_search`], [`google_web_search`]
+- **Interaction:** [`ask_user`]
+- **MCP Tools (Read):** Read-only [MCP tools] (e.g., `github_read_issue`,
+  `postgres_read_schema`) are allowed.
+- **Planning (Write):** [`write_file`] and [`replace`] ONLY allowed for `.md`
+  files in the `~/.gemini/tmp/<project>/<session-id>/plans/` directory.
+- **Skills:** [`activate_skill`] (allows loading specialized instructions and
+  resources in a read-only manner)
+
+### Customizing Planning with Skills
+
+You can leverage [Agent Skills](./skills.md) to customize how Gemini CLI
+approaches planning for specific types of tasks. When a skill is activated
+during Plan Mode, its specialized instructions and procedural workflows will
+guide the research and design phases.
+
+For example:
+
+- A **"Database Migration"** skill could ensure the plan includes data safety
+  checks and rollback strategies.
+- A **"Security Audit"** skill could prompt the agent to look for specific
+  vulnerabilities during codebase exploration.
+- A **"Frontend Design"** skill could guide the agent to use specific UI
+  components and accessibility standards in its proposal.
+
+To use a skill in Plan Mode, you can explicitly ask the agent to "use the
+[skill-name] skill to plan..." or the agent may autonomously activate it based
+on the task description.
+
+### Customizing Policies
+
+Plan Mode is designed to be read-only by default to ensure safety during the
+research phase. However, you may occasionally need to allow specific tools to
+assist in your planning.
+
+Because user policies (Tier 2) have a higher base priority than built-in
+policies (Tier 1), you can override Plan Mode's default restrictions by creating
+a rule in your `~/.gemini/policies/` directory.
+
+#### Example: Allow `git status` and `git diff` in Plan Mode
+
+This rule allows you to check the repository status and see changes while in
+Plan Mode.
+
+`~/.gemini/policies/git-research.toml`
+
+```toml
+[[rule]]
+toolName = "run_shell_command"
+commandPrefix = ["git status", "git diff"]
+decision = "allow"
+priority = 100
+modes = ["plan"]
+```
+
+#### Example: Enable research sub-agents in Plan Mode
+
+You can enable [experimental research sub-agents] like `codebase_investigator`
+to help gather architecture details during the planning phase.
+
+`~/.gemini/policies/research-subagents.toml`
+
+```toml
+[[rule]]
+toolName = "codebase_investigator"
+decision = "allow"
+priority = 100
+modes = ["plan"]
+```
+
+Tell the agent it can use these tools in your prompt, for example: _"You can
+check ongoing changes in git."_
+
+For more information on how the policy engine works, see the [Policy Engine
+Guide].
+
+[`list_directory`]: /docs/tools/file-system.md#1-list_directory-readfolder
+[`read_file`]: /docs/tools/file-system.md#2-read_file-readfile
+[`grep_search`]: /docs/tools/file-system.md#5-grep_search-searchtext
+[`write_file`]: /docs/tools/file-system.md#3-write_file-writefile
+[`glob`]: /docs/tools/file-system.md#4-glob-findfiles
+[`google_web_search`]: /docs/tools/web-search.md
+[`replace`]: /docs/tools/file-system.md#6-replace-edit
+[MCP tools]: /docs/tools/mcp-server.md
+[`activate_skill`]: /docs/cli/skills.md
+[experimental research sub-agents]: /docs/core/subagents.md
+[Policy Engine Guide]: /docs/core/policy-engine.md
+[`enter_plan_mode`]: /docs/tools/planning.md#1-enter_plan_mode-enterplanmode
+[`exit_plan_mode`]: /docs/tools/planning.md#2-exit_plan_mode-exitplanmode
+[`ask_user`]: /docs/tools/ask-user.md

package/dist/docs/cli/rewind.md

@@ -0,0 +1,51 @@
+# Rewind
+
+The `/rewind` command lets you go back to a previous state in your conversation
+and, optionally, revert any file changes made by the AI during those
+interactions. This is a powerful tool for undoing mistakes, exploring different
+approaches, or simply cleaning up your session history.
+
+## Usage
+
+To use the rewind feature, simply type `/rewind` into the input prompt and press
+**Enter**.
+
+Alternatively, you can use the keyboard shortcut: **Press `Esc` twice**.
+
+## Interface
+
+When you trigger a rewind, an interactive list of your previous interactions
+appears.
+
+1.  **Select interaction:** Use the **Up/Down arrow keys** to navigate through
+    the list. The most recent interactions are at the bottom.
+2.  **Preview:** As you select an interaction, you'll see a preview of the user
+    prompt and, if applicable, the number of files changed during that step.
+3.  **Confirm selection:** Press **Enter** on the interaction you want to rewind
+    back to.
+4.  **Action selection:** After selecting an interaction, you'll be presented
+    with a confirmation dialog with up to three options:
+    - **Rewind conversation and revert code changes:** Reverts both the chat
+      history and the file modifications to the state before the selected
+      interaction.
+    - **Rewind conversation:** Only reverts the chat history. File changes are
+      kept.
+    - **Revert code changes:** Only reverts the file modifications. The chat
+      history is kept.
+    - **Do nothing (esc):** Cancels the rewind operation.
+
+If no code changes were made since the selected point, the options related to
+reverting code changes will be hidden.
+
+## Key considerations
+
+- **Destructive action:** Rewinding is a destructive action for your current
+  session history and potentially your files. Use it with care.
+- **Agent awareness:** When you rewind the conversation, the AI model loses all
+  memory of the interactions that were removed. If you only revert code changes,
+  you may need to inform the model that the files have changed.
+- **Manual edits:** Rewinding only affects file changes made by the AI's edit
+  tools. It does **not** undo manual edits you've made or changes triggered by
+  the shell tool (`!`).
+- **Compression:** Rewind works across chat compression points by reconstructing
+  the history from stored session data.

package/dist/docs/cli/sandbox.md

@@ -11,7 +11,7 @@ Before using sandboxing, you need to install and set up the Gemini CLI:
 npm install -g @google/gemini-cli
 ```
 
-To verify the installation
+To verify the installation:
 
 ```bash
 gemini --version
@@ -82,10 +82,11 @@ gemini -p "run the test suite"
 Built-in profiles (set via `SEATBELT_PROFILE` env var):
 
 - `permissive-open` (default): Write restrictions, network allowed
-- `permissive-closed`: Write restrictions, no network
 - `permissive-proxied`: Write restrictions, network via proxy
 - `restrictive-open`: Strict restrictions, network allowed
-- `restrictive-closed`: Maximum restrictions
+- `restrictive-proxied`: Strict restrictions, network via proxy
+- `strict-open`: Read and write restrictions, network allowed
+- `strict-proxied`: Read and write restrictions, network via proxy
 
 ### Custom sandbox flags
 

package/dist/docs/cli/session-management.md

@@ -1,32 +1,36 @@
-# Session Management
+# Session management
 
-Gemini CLI includes robust session management features that automatically save
-your conversation history. This allows you to interrupt your work and resume
-exactly where you left off, review past interactions, and manage your
-conversation history effectively.
+Session management saves your conversation history so you can resume your work
+where you left off. Use these features to review past interactions, manage
+history across different projects, and configure how long data is retained.
 
-## Automatic Saving
+## Automatic saving
 
-Every time you interact with Gemini CLI, your session is automatically saved.
-This happens in the background without any manual intervention.
+Your session history is recorded automatically as you interact with the model.
+This background process ensures your work is preserved even if you interrupt a
+session.
 
 - **What is saved:** The complete conversation history, including:
   - Your prompts and the model's responses.
   - All tool executions (inputs and outputs).
-  - Token usage statistics (input/output/cached, etc.).
-  - Assistant thoughts/reasoning summaries (when available).
-- **Location:** Sessions are stored in `~/.gemini/tmp/<project_hash>/chats/`.
+  - Token usage statistics (input, output, cached, etc.).
+  - Assistant thoughts and reasoning summaries (when available).
+- **Location:** Sessions are stored in `~/.gemini/tmp/<project_hash>/chats/`,
+  where `<project_hash>` is a unique identifier based on your project's root
+  directory.
 - **Scope:** Sessions are project-specific. Switching directories to a different
-  project will switch to that project's session history.
+  project switches to that project's session history.
 
-## Resuming Sessions
+## Resuming sessions
 
 You can resume a previous session to continue the conversation with all prior
-context restored.
+context restored. Resuming is supported both through command-line flags and an
+interactive browser.
 
-### From the Command Line
+### From the command line
 
-When starting the CLI, you can use the `--resume` (or `-r`) flag:
+When starting Gemini CLI, use the `--resume` (or `-r`) flag to load existing
+sessions.
 
 - **Resume latest:**
 
@@ -36,8 +40,8 @@ When starting the CLI, you can use the `--resume` (or `-r`) flag:
 
   This immediately loads the most recent session.
 
-- **Resume by index:** First, list available sessions (see
-  [Listing Sessions](#listing-sessions)), then use the index number:
+- **Resume by index:** List available sessions first (see
+  [Listing sessions](#listing-sessions)), then use the index number:
 
   ```bash
   gemini --resume 1
@@ -48,30 +52,35 @@ When starting the CLI, you can use the `--resume` (or `-r`) flag:
   gemini --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890
   ```
 
-### From the Interactive Interface
+### From the interactive interface
 
-While the CLI is running, you can use the `/resume` slash command to open the
-**Session Browser**:
+While the CLI is running, use the `/resume` slash command to open the **Session
+Browser**:
 
 ```text
 /resume
 ```
 
-This opens an interactive interface where you can:
+The Session Browser provides an interactive interface where you can perform the
+following actions:
 
 - **Browse:** Scroll through a list of your past sessions.
 - **Preview:** See details like the session date, message count, and the first
   user prompt.
 - **Search:** Press `/` to enter search mode, then type to filter sessions by ID
   or content.
-- **Select:** Press `Enter` to resume the selected session.
+- **Select:** Press **Enter** to resume the selected session.
+- **Esc:** Press **Esc** to exit the Session Browser.
 
-## Managing Sessions
+## Managing sessions
 
-### Listing Sessions
+You can list and delete sessions to keep your history organized and manage disk
+space.
+
+### Listing sessions
 
 To see a list of all available sessions for the current project from the command
-line:
+line, use the `--list-sessions` flag:
 
 ```bash
 gemini --list-sessions
@@ -87,12 +96,12 @@ Available sessions for this project (3):
   3. Update documentation (Just now) [abcd1234]
 ```
 
-### Deleting Sessions
+### Deleting sessions
 
 You can remove old or unwanted sessions to free up space or declutter your
 history.
 
-**From the Command Line:** Use the `--delete-session` flag with an index or ID:
+**From the command line:** Use the `--delete-session` flag with an index or ID:
 
 ```bash
 gemini --delete-session 2
@@ -102,17 +111,18 @@ gemini --delete-session 2
 
 1.  Open the browser with `/resume`.
 2.  Navigate to the session you want to remove.
-3.  Press `x`.
+3.  Press **x**.
 
 ## Configuration
 
 You can configure how Gemini CLI manages your session history in your
-`settings.json` file.
+`settings.json` file. These settings let you control retention policies and
+session lengths.
 
-### Session Retention
+### Session retention
 
-To prevent your history from growing indefinitely, you can enable automatic
-cleanup policies.
+To prevent your history from growing indefinitely, enable automatic cleanup
+policies in your settings.
 
 ```json
 {
@@ -126,20 +136,20 @@ cleanup policies.
 }
 ```
 
-- **`enabled`**: (boolean) Master switch for session cleanup. Default is
+- **`enabled`**: (boolean) Master switch for session cleanup. Defaults to
   `false`.
-- **`maxAge`**: (string) Duration to keep sessions (e.g., "24h", "7d", "4w").
-  Sessions older than this will be deleted.
+- **`maxAge`**: (string) Duration to keep sessions (for example, "24h", "7d",
+  "4w"). Sessions older than this are deleted.
 - **`maxCount`**: (number) Maximum number of sessions to retain. The oldest
-  sessions exceeding this count will be deleted.
+  sessions exceeding this count are deleted.
 - **`minRetention`**: (string) Minimum retention period (safety limit). Defaults
-  to `"1d"`; sessions newer than this period are never deleted by automatic
+  to `"1d"`. Sessions newer than this period are never deleted by automatic
   cleanup.
 
-### Session Limits
+### Session limits
 
-You can also limit the length of individual sessions to prevent context windows
-from becoming too large and expensive.
+You can limit the length of individual sessions to prevent context windows from
+becoming too large and expensive.
 
 ```json
 {
@@ -149,10 +159,17 @@ from becoming too large and expensive.
 }
 ```
 
-- **`maxSessionTurns`**: (number) The maximum number of turns (user + model
+- **`maxSessionTurns`**: (number) The maximum number of turns (user and model
   exchanges) allowed in a single session. Set to `-1` for unlimited (default).
 
   **Behavior when limit is reached:**
-  - **Interactive Mode:** The CLI shows an informational message and stops
+  - **Interactive mode:** The CLI shows an informational message and stops
     sending requests to the model. You must manually start a new session.
-  - **Non-Interactive Mode:** The CLI exits with an error.
+  - **Non-interactive mode:** The CLI exits with an error.
+
+## Next steps
+
+- Explore the [Memory tool](../tools/memory.md) to save persistent information
+  across sessions.
+- Learn how to [Checkpoint](./checkpointing.md) your session state.
+- Check out the [CLI reference](./cli-reference.md) for all command-line flags.