docs: plan mode doumentation

docs/docs.json

@@ -65,6 +65,7 @@
                 "pages": [
                   "features/agent/quick-start",
                   "features/agent/how-it-works",
+                  "features/agent/plan-mode",
                   "features/agent/model-setup",
                   "features/agent/how-to-customize",
                   "features/agent/context-selection"

docs/features/agent/how-it-works.mdx

@@ -17,22 +17,37 @@ The following handshake describes how Agent uses tools:
 6. The model responds, potentially with another tool call and step 2 begins again
 
 <Info>
-  In [Chat mode](/features/chat/quick-start), tools are **not** included in the
-  request to the model.
+  Tool availability varies by mode:
+  - **Chat mode**: No tools included
+  - **Plan mode**: Only read-only tools included
+  - **Agent mode**: All tools included
 </Info>
 
 ## Built-in tools
 
-Continue includes several built-in tools which provide the model access to IDE functionality:
+Continue includes several built-in tools which provide the model access to IDE functionality.
 
-- **Read file** (`read_file`): read the contents of a file within the project
-- **Read currently open file** (`read_currently_open_file`): read the contents of the currently open file
-- **Create new file** (`create_new_file`): Create a new file within the project, with path and contents specified by the model
-- **Exact search** (`exact_search`): perform a `ripgrep` search within the project
-- **Glob search** (`file_glob_search`): perform a glob search on files in the project. Currently limits to 100 output and warns the Agent if limit reached.
-- **Run terminal command** (`run_terminal_command`): run a terminal command from the workspace root
-- **Search web** (`search_web`): Perform a web search to get top results
-- **View diff** (`view_diff`): View the current working git diff
-- **View repo map** (`view_repo_map`): request a copy of the repository map—same as the [Repo Map Context Provider](/customize/custom-providers#repository-map)
-- **View subdirectory** (`view_subdirectory`): request a copy of a repo map for a specific directory within the project
-- **Create Rule Block** (`create_rule_block`): creates a new rule block in `.continue/rules` based on the contents of the conversation
+### Plan mode tools (read-only)
+
+In Plan mode, only these read-only tools are available:
+- **Read file** (`readFile`)
+- **Read currently open file** (`readCurrentlyOpenFile`)
+- **List directory** (`ls`)
+- **Glob search** (`globSearch`)
+- **Grep search** (`grepSearch`)
+- **Fetch URL content** (`fetchUrlContent`)
+- **Search web** (`searchWeb`)
+- **View diff** (`viewDiff`)
+- **View repo map** (`viewRepoMap`)
+- **View subdirectory** (`viewSubdirectory`)
+- **Codebase tool** (`codebaseTool`)
+
+### Agent mode tools (all tools)
+
+In Agent mode, all tools are available including the read-only tools above plus:
+
+- **Create new file** (`create_new_file`): Create a new file within the project
+- **Edit file** (`editFile`): Make changes to existing files
+- **Run terminal command** (`run_terminal_command`): Run commands from the workspace root
+- **Create Rule Block** (`create_rule_block`): Create a new rule block in `.continue/rules`
+- All other write/execute tools for modifying the codebase

docs/features/agent/plan-mode.mdx

@@ -0,0 +1,49 @@
+---
+title: "Plan Mode"
+description: "Explore and understand code safely with read-only tools"
+---
+
+## What is Plan mode?
+
+Plan mode is a restricted environment that provides read-only access to your codebase. It's designed for safe exploration, understanding code, and planning changes without making any modifications.
+
+![Plan mode in action](/images/plan-mode.gif)
+
+### Key features
+
+- **Read-only tools**: Access files, search, and analyze without risk
+- **Safe exploration**: Perfect for understanding unfamiliar codebases
+- **Planning focus**: Develop implementation strategies before execution
+- **MCP support**: Works with all MCP tools alongside built-in read-only tools
+
+### How it works
+
+Plan mode filters the available tools to only include read-only operations. This means you can:
+- Read any file in your project
+- Search through code with grep and glob patterns
+- View repository structure and diffs
+- Fetch web content for additional context
+- Use all MCP tools
+
+But you cannot:
+- Create, edit, or delete files
+- Run terminal commands
+- Make any system changes
+
+### Getting started
+
+Select "Plan" from the mode selector below the chat input, or use `Cmd/Ctrl + .` to cycle through modes.
+
+![Plan mode selector](/images/plan-mode-selector.png)
+
+For detailed information about tools and usage, see the [Agent documentation](/features/agent/how-it-works), which covers both Agent and Plan modes.
+
+### Common workflow
+
+1. **Start in Plan mode** to explore and understand
+2. **Develop your approach** with the model's help
+3. **Switch to Agent mode** when ready to implement
+
+<Tip>
+  Plan mode shares the same interface and context features as Chat and Agent modes. You can use `@` context providers and highlight code just like in other modes.
+</Tip>

docs/features/agent/quick-start.mdx

@@ -6,18 +6,39 @@ title: "Quick Start"
 
 Agent equips the Chat model with the tools needed to handle a wide range of coding tasks, allowing the model to make decisions and save you the work of manually finding context and performing actions.
 
+### When to use each mode
+
+- **Plan mode**: Use when you want to explore code, understand systems, or plan changes without making modifications. Perfect for:
+  - Understanding unfamiliar codebases
+  - Planning complex refactors
+  - Debugging and investigation
+  - Creating implementation strategies
+  
+- **Agent mode**: Use when you're ready to make changes. Ideal for:
+  - Implementing features
+  - Fixing bugs
+  - Running tests and commands
+  - Executing plans developed in Plan mode
+
 ### Use Agent
 
-You can switch to `Agent` in the mode selector below the chat input box.
+You can switch to `Agent` in the mode selector below the chat input box. The mode selector offers three options:
+- **Chat**: No tools available, pure conversation
+- **Plan**: Read-only tools for safe exploration and planning
+- **Agent**: All tools available for making changes
 
 ![How to select agent mode](/images/mode-select-agent.png)
 
 <Info>
-  If Agent is disabled with a `Not Supported` message, the selected model or
+  If Agent or Plan is disabled with a `Not Supported` message, the selected model or
   provider doesn't support tools, or Continue doesn't yet support tools with it.
   See [Model Blocks](/customization/models) for more information.
 </Info>
 
+<Tip>
+  Use the keyboard shortcut `Cmd/Ctrl + .` to quickly cycle between modes.
+</Tip>
+
 ### Chat with Agent
 
 Agent lives within the same interface as [Chat](/features/chat/how-it-works), so the same [input](/features/chat/quick-start#1-start-a-conversation) is used to send messages and you can still use the same manual methods of providing context, such as [`@` context providers](/features/chat/quick-start#3-use--for-additional-context) or adding [highlighted code from the editor](/features/chat/quick-start#2-include-code-context).

docs/features/plan/how-it-works.mdx

@@ -0,0 +1,102 @@
+---
+title: "How Plan Works"
+description: "Plan mode provides a restricted environment with read-only tools, enabling safe exploration and planning without making changes to your codebase."
+---
+
+## Understanding Plan mode
+
+Plan mode is designed to help you understand code and construct plans before making changes. It sits between Chat mode (no tools) and Agent mode (all tools), providing a middle ground where you can explore and analyze without risk.
+
+### The key difference: Read-only tools
+
+While Agent mode has access to all tools including those that modify files, Plan mode restricts access to only read-only tools. This ensures that:
+
+- No files are created, modified, or deleted
+- No commands are executed that could change system state
+- All exploration is safe and non-destructive
+- You can confidently investigate without unintended consequences
+
+## How Plan mode works
+
+When you select Plan mode:
+
+1. Continue sends a special system message instructing the model to focus on understanding and planning
+2. The tool list is filtered to include only read-only tools
+3. The model can use these tools to explore and analyze your codebase
+4. When you're ready to implement changes, you switch to Agent mode
+
+### Available tools in Plan mode
+
+Plan mode includes these read-only built-in tools:
+
+- **Read file** (`readFile`): Read the contents of any file in the project
+- **Read currently open file** (`readCurrentlyOpenFile`): Read the contents of the currently open file
+- **List directory** (`ls`): List files and directories
+- **Glob search** (`globSearch`): Search for files matching a pattern
+- **Grep search** (`grepSearch`): Search file contents using regex patterns
+- **Fetch URL content** (`fetchUrlContent`): Retrieve content from web URLs
+- **Search web** (`searchWeb`): Perform web searches for additional context
+- **View diff** (`viewDiff`): View the current git diff
+- **View repo map** (`viewRepoMap`): Get an overview of the repository structure
+- **View subdirectory** (`viewSubdirectory`): Get a detailed view of a specific directory
+- **Codebase tool** (`codebaseTool`): Advanced codebase analysis capabilities
+
+### MCP tools support
+
+In addition to built-in read-only tools, Plan mode also supports all MCP (Model Context Protocol) tools. This allows integration with external services that provide additional context or analysis capabilities without modifying your local environment.
+
+## The planning workflow
+
+A typical Plan mode workflow follows these steps:
+
+1. **Exploration**: Use read-only tools to understand the current state
+2. **Analysis**: Identify what needs to change and potential impacts
+3. **Planning**: Develop a detailed plan for implementation
+4. **Verification**: Review the plan and ensure it addresses all requirements
+5. **Execution**: Switch to Agent mode to implement the plan
+
+### Example: Planning a refactor
+
+```
+User: Help me plan a refactor to extract the authentication logic into a separate module
+
+Plan mode:
+1. Reads relevant files to understand current structure
+2. Analyzes dependencies and usage patterns
+3. Identifies all places that need updates
+4. Creates a step-by-step refactoring plan
+5. Suggests: "Switch to Agent mode to implement this plan"
+```
+
+## System message and behavior
+
+Plan mode uses a dedicated system message that:
+
+- Instructs the model to focus on understanding and planning
+- Emphasizes using only read-only tools
+- Reminds the model to suggest switching to Agent mode for implementation
+- Encourages thorough analysis before suggesting changes
+
+<Info>
+  The system message can be customized per model. See [How to Customize](/features/plan/how-to-customize) for details.
+</Info>
+
+## When to use Plan mode vs other modes
+
+### Use Plan mode when:
+- Exploring unfamiliar codebases
+- Planning complex refactors or features
+- Debugging and understanding issues
+- Reviewing code architecture
+- Creating implementation strategies
+
+### Use Chat mode when:
+- Having discussions without needing file access
+- Asking general programming questions
+- Getting explanations without exploring code
+
+### Use Agent mode when:
+- Ready to implement changes
+- Need to create or modify files
+- Want to run commands or tests
+- Implementing a plan developed in Plan mode

docs/features/plan/quick-start.mdx

@@ -0,0 +1,60 @@
+---
+title: "Quick Start"
+---
+
+## How to use it
+
+Plan mode provides a safe environment for understanding and constructing plans without making changes. It equips the Chat model with read-only tools, allowing you to explore, analyze, and plan modifications before executing them.
+
+### Use Plan
+
+You can switch to `Plan` in the mode selector below the chat input box.
+
+![How to select plan mode](/images/mode-select-plan.png)
+
+<Info>
+  If Plan is disabled with a `Not Supported` message, the selected model or
+  provider doesn't support tools. See [Model Setup](/features/plan/model-setup) 
+  for more information.
+</Info>
+
+### Chat with Plan
+
+Plan mode lives within the same interface as [Chat](/features/chat/how-it-works) and [Agent](/features/agent/how-it-works), so the same [input](/features/chat/quick-start#1-start-a-conversation) is used to send messages and you can still use the same manual methods of providing context, such as [`@` context providers](/features/chat/quick-start#3-use--for-additional-context) or adding [highlighted code from the editor](/features/chat/quick-start#2-include-code-context).
+
+#### What makes Plan different
+
+Unlike Agent mode, Plan mode:
+- Only uses read-only tools (file reading, searching, analysis)
+- Cannot modify, create, or delete files
+- Focuses on understanding and planning rather than execution
+- Provides a safe environment for exploration
+
+### Common use cases
+
+Plan mode is ideal for:
+- **Code exploration**: Understanding how a codebase works
+- **Planning refactors**: Analyzing impact before making changes
+- **Debugging**: Investigating issues without modifying code
+- **Architecture review**: Understanding system design and dependencies
+- **Pre-implementation planning**: Thinking through changes before executing
+
+### Example workflow
+
+1. **Start in Plan mode** to explore and understand the task
+2. **Develop a plan** with the model's help
+3. **Switch to Agent mode** when ready to implement changes
+
+For example, you might say:
+
+> Help me understand how the authentication system works and plan improvements to add OAuth support
+
+Plan mode will analyze the existing code, understand the current implementation, and help you create a detailed plan—all without making any changes.
+
+## Switching to execution
+
+When you're ready to implement your plan, simply switch to Agent mode using the mode selector or keyboard shortcut (`Cmd/Ctrl + .`). The conversation context carries over, so Agent mode can immediately start implementing the plan you developed.
+
+<Tip>
+  Use the keyboard shortcut `Cmd/Ctrl + .` to quickly cycle between Chat, Plan, and Agent modes.
+</Tip>

docs/getting-started/overview.mdx

@@ -43,4 +43,14 @@ description: "To quickly understand what you can do with Continue, check out eac
   Learn more about [Agent](/features/agent/quick-start)
 </Info>
 </Tab>
+
+<Tab title="Plan">
+[Plan](/features/agent/plan-mode) provides a safe environment with read-only tools for exploring code and planning changes
+
+![plan](/images/plan-mode.gif)
+
+<Info>
+  Learn more about [Plan](/features/agent/plan-mode)
+</Info>
+</Tab>
 </Tabs>