Add back tool reference

apps/kilocode-docs/components/SideNav.tsx

@@ -9,6 +9,7 @@ const sectionNavItems: SectionNav = {
 	"getting-started": Nav.GettingStartedNav,
 	"code-with-ai": Nav.CodeWithAiNav,
 	collaborate: Nav.CollaborateNav,
+	"automate/tools": Nav.ToolsNav,
 	automate: Nav.AutomateNav,
 	"deploy-secure": Nav.DeploySecureNav,
 	contributing: Nav.ContributingNav,

apps/kilocode-docs/lib/nav/automate.ts

@@ -41,4 +41,11 @@ export const AutomateNav: NavSection[] = [
 			{ href: "/automate/mcp/mcp-vs-api", children: "MCP vs API" },
 		],
 	},
+	{
+		title: "Tools",
+		links: [
+			{ href: "/automate/how-tools-work", children: "How Tools Work" },
+			{ href: "/automate/tools", children: "Tools Details" },
+		],
+	},
 ]

apps/kilocode-docs/lib/nav/getting-started.ts

@@ -27,7 +27,7 @@ export const GettingStartedNav: NavSection[] = [
 			{ href: "/getting-started/faq", children: "FAQ" },
 			{
 				href: "/getting-started/migrating",
-				children: "Migrating from Cursor/Windsurf",
+				children: "Migrating from Cursor",
 			},
 		],
 	},

apps/kilocode-docs/lib/nav/index.ts

@@ -5,6 +5,7 @@ import { CollaborateNav } from "./collaborate"
 import { ContributingNav } from "./contributing"
 import { DeploySecureNav } from "./deploy-secure"
 import { GettingStartedNav } from "./getting-started"
+import { ToolsNav } from "./tools"
 
 export const Nav = {
 	GettingStartedNav,
@@ -14,4 +15,5 @@ export const Nav = {
 	DeploySecureNav,
 	ContributingNav,
 	AiProvidersNav,
+	ToolsNav,
 }

apps/kilocode-docs/lib/nav/tools.ts

@@ -0,0 +1,51 @@
+import { NavSection } from "../types"
+
+export const ToolsNav: NavSection[] = [
+	{
+		title: "Tools",
+		links: [{ href: "/automate/tools", children: "Overview" }],
+	},
+	{
+		title: "Read Tools",
+		links: [
+			{ href: "/automate/tools/read-file", children: "read_file" },
+			{ href: "/automate/tools/search-files", children: "search_files" },
+			{ href: "/automate/tools/list-files", children: "list_files" },
+			{ href: "/automate/tools/list-code-definition-names", children: "list_code_definition_names" },
+			{ href: "/automate/tools/codebase-search", children: "codebase_search" },
+		],
+	},
+	{
+		title: "Edit Tools",
+		links: [
+			{ href: "/automate/tools/apply-diff", children: "apply_diff" },
+			{ href: "/automate/tools/delete-file", children: "delete_file" },
+			{ href: "/automate/tools/write-to-file", children: "write_to_file" },
+		],
+	},
+	{
+		title: "Browser Tools",
+		links: [{ href: "/automate/tools/browser-action", children: "browser_action" }],
+	},
+	{
+		title: "Command Tools",
+		links: [{ href: "/automate/tools/execute-command", children: "execute_command" }],
+	},
+	{
+		title: "MCP Tools",
+		links: [
+			{ href: "/automate/tools/use-mcp-tool", children: "use_mcp_tool" },
+			{ href: "/automate/tools/access-mcp-resource", children: "access_mcp_resource" },
+		],
+	},
+	{
+		title: "Workflow Tools",
+		links: [
+			{ href: "/automate/tools/switch-mode", children: "switch_mode" },
+			{ href: "/automate/tools/new-task", children: "new_task" },
+			{ href: "/automate/tools/ask-followup-question", children: "ask_followup_question" },
+			{ href: "/automate/tools/attempt-completion", children: "attempt_completion" },
+			{ href: "/automate/tools/update-todo-list", children: "update_todo_list" },
+		],
+	},
+]

apps/kilocode-docs/pages/automate/how-tools-work.md

@@ -0,0 +1,89 @@
+---
+title: How Tools Work
+description: Learn how Kilo Code's tools automate your development workflow
+---
+
+# How Tools Work
+
+Kilo Code uses tools to interact with your code and environment. These specialized helpers perform specific actions like reading files, making edits, running commands, or searching your codebase. Tools provide automation for common development tasks without requiring manual execution.
+
+## Tool Workflow
+
+Describe what you want to accomplish in natural language, and Kilo Code will:
+
+1. Select the appropriate tool based on your request
+2. Present the tool with its parameters for your review
+3. Execute the approved tool and show you the results
+4. Continue this process until your task is complete
+
+## Tool Categories
+
+| Category | Purpose                                    | Tool Names                                                               |
+| :------- | :----------------------------------------- | :----------------------------------------------------------------------- |
+| Read     | Access file content and code structure     | `read_file`, `search_files`, `list_files`, `list_code_definition_names`  |
+| Edit     | Create or modify files and code            | `apply_diff`, `delete_file`, `write_to_file`                             |
+| Execute  | Run commands and perform system operations | `execute_command`                                                        |
+| Browser  | Interact with web content                  | `browser_action`                                                         |
+| Workflow | Manage task flow and context               | `ask_followup_question`, `attempt_completion`, `switch_mode`, `new_task` |
+
+## Example: Using Tools
+
+Here's how a typical tool interaction works:
+
+<img src="/docs/img/how-tools-work/how-tools-work.png" alt="Tool approval interface showing Save and Reject buttons along with Auto-approve checkbox" width="600" />
+
+_The tool approval interface shows Save/Reject buttons and Auto-approve options._
+
+**User:** Create a file named `greeting.js` that logs a greeting message
+
+**Kilo Code:** (Proposes the `write_to_file` tool as shown in the image above)
+
+```xml
+<write_to_file>
+<path>greeting.js</path>
+<content>
+function greet(name) {
+  console.log(`Hello, ${name}!`);
+}
+
+greet('World');
+</content>
+<line_count>5</line_count>
+</write_to_file>
+```
+
+**User:** (Clicks "Save" in the interface)
+
+**Kilo Code:** (Confirms file creation)
+
+## Tool Safety and Approval
+
+Every tool use requires your explicit approval. When Kilo proposes a tool, you'll see:
+
+- A "Save" button to approve and execute the tool
+- A "Reject" button to decline the proposed tool
+- An optional "Auto-approve" setting for trusted operations
+
+This safety mechanism ensures you maintain control over which files are modified, what commands are executed, and how your codebase is changed. Always review tool proposals carefully before saving them.
+
+## Core Tools Reference
+
+| Tool Name                    | Description                                         | Category |
+| :--------------------------- | :-------------------------------------------------- | :------- |
+| `read_file`                  | Reads the content of a file with line numbers       | Read     |
+| `search_files`               | Searches for text or regex patterns across files    | Read     |
+| `list_files`                 | Lists files and directories in a specified location | Read     |
+| `list_code_definition_names` | Lists code definitions like classes and functions   | Read     |
+| `write_to_file`              | Creates new files or overwrites existing ones       | Edit     |
+| `apply_diff`                 | Makes precise changes to specific parts of a file   | Edit     |
+| `delete_file`                | Removes files from the workspace                    | Edit     |
+| `execute_command`            | Runs commands in the VS Code terminal               | Execute  |
+| `browser_action`             | Performs actions in a headless browser              | Browser  |
+| `ask_followup_question`      | Asks you a clarifying question                      | Workflow |
+| `attempt_completion`         | Indicates the task is complete                      | Workflow |
+| `switch_mode`                | Changes to a different operational mode             | Workflow |
+| `new_task`                   | Creates a new subtask with a specific starting mode | Workflow |
+
+## Learn More About Tools
+
+For more detailed information about each tool, including complete parameter references and advanced usage patterns, see the [Tool Use Overview](/features/tools/tool-use-overview) documentation.

apps/kilocode-docs/pages/automate/tools/access-mcp-resource.md

@@ -0,0 +1,134 @@
+# access_mcp_resource
+
+The `access_mcp_resource` tool retrieves data from resources exposed by connected Model Context Protocol (MCP) servers. It allows Kilo Code to access files, API responses, documentation, or system information that provides additional context for tasks.
+
+## Parameters
+
+The tool accepts these parameters:
+
+- `server_name` (required): The name of the MCP server providing the resource
+- `uri` (required): The URI identifying the specific resource to access
+
+## What It Does
+
+This tool connects to MCP servers and fetches data from their exposed resources. Unlike `use_mcp_tool` which executes actions, this tool specifically retrieves information that serves as context for tasks.
+
+## When is it used?
+
+- When Kilo Code needs additional context from external systems
+- When Kilo Code needs to access domain-specific data from specialized MCP servers
+- When Kilo Code needs to retrieve reference documentation hosted by MCP servers
+- When Kilo Code needs to integrate real-time data from external APIs via MCP
+
+## Key Features
+
+- Retrieves both text and image data from MCP resources
+- Requires user approval before executing resource access
+- Uses URI-based addressing to precisely identify resources
+- Integrates with the Model Context Protocol SDK
+- Displays resource content appropriately based on content type
+- Supports timeouts for reliable network operations
+- Handles server connection states (connected, connecting, disconnected)
+- Discovers available resources from connected servers
+- Processes structured response data with metadata
+- Handles image content special rendering
+
+## Limitations
+
+- Depends on external MCP servers being available and connected
+- Limited to the resources provided by connected servers
+- Cannot access resources from disabled servers
+- Network issues can affect reliability and performance
+- Resource access subject to configured timeouts
+- URI formats are determined by the specific MCP server implementation
+- No offline or cached resource access capabilities
+
+## How It Works
+
+When the `access_mcp_resource` tool is invoked, it follows this process:
+
+1. **Connection Validation**:
+
+    - Verifies that an MCP hub is available and initialized
+    - Confirms the specified server exists in the connection list
+    - Checks if the server is disabled (returns an error if it is)
+
+2. **User Approval**:
+
+    - Presents the resource access request to the user for approval
+    - Provides server name and resource URI for user verification
+    - Proceeds only if the user approves the resource access
+
+3. **Resource Request**:
+
+    - Uses the Model Context Protocol SDK to communicate with servers
+    - Makes a `resources/read` request to the server through the MCP hub
+    - Applies configured timeouts to prevent hanging on unresponsive servers
+
+4. **Response Processing**:
+    - Receives a structured response with metadata and content arrays
+    - Processes text content for display to the user
+    - Handles image data specially for appropriate display
+    - Returns the processed resource data to Kilo Code for use in the current task
+
+## Resource Types
+
+MCP servers can provide two main types of resources:
+
+1. **Standard Resources**:
+
+    - Fixed resources with specific URIs
+    - Defined name, description, and MIME type
+    - Direct access without parameters
+    - Typically represent static data or real-time information
+
+2. **Resource Templates**:
+    - Parameterized resources with placeholder values in URIs
+    - Allow dynamic resource generation based on provided parameters
+    - Can represent queries or filtered views of data
+    - More flexible but require additional URI formatting
+
+## Examples When Used
+
+- When helping with API development, Kilo Code retrieves endpoint specifications from MCP resources to ensure correct implementation.
+- When assisting with data visualization, Kilo Code accesses current data samples from connected MCP servers.
+- When working in specialized domains, Kilo Code retrieves technical documentation to provide accurate guidance.
+- When generating industry-specific code, Kilo Code references compliance requirements from documentation resources.
+
+## Usage Examples
+
+Accessing current weather data:
+
+```
+<access_mcp_resource>
+<server_name>weather-server</server_name>
+<uri>weather://san-francisco/current</uri>
+</access_mcp_resource>
+```
+
+Retrieving API documentation:
+
+```
+<access_mcp_resource>
+<server_name>api-docs</server_name>
+<uri>docs://payment-service/endpoints</uri>
+</access_mcp_resource>
+```
+
+Accessing domain-specific knowledge:
+
+```
+<access_mcp_resource>
+<server_name>knowledge-base</server_name>
+<uri>kb://medical/terminology/common</uri>
+</access_mcp_resource>
+```
+
+Fetching system configuration:
+
+```
+<access_mcp_resource>
+<server_name>infra-monitor</server_name>
+<uri>config://production/database</uri>
+</access_mcp_resource>
+```

apps/kilocode-docs/pages/automate/tools/apply-diff.md

@@ -0,0 +1,98 @@
+# apply_diff
+
+The `apply_diff` tool makes precise, surgical changes to files by specifying exactly what content to replace. It uses multiple sophisticated strategies for finding and applying changes while maintaining proper code formatting and structure.
+
+## Parameters
+
+The tool accepts these parameters:
+
+- `path` (required): The path of the file to modify relative to the current working directory.
+- `diff` (required): The search/replace block defining the changes. **Line numbers are mandatory within the diff content format** for all currently implemented strategies.
+
+**Note**: While the system is designed to be extensible with different diff strategies, all currently implemented strategies require line numbers to be specified within the diff content itself using the `:start_line:` marker.
+
+## What It Does
+
+This tool applies targeted changes to existing files using sophisticated strategies to locate and replace content precisely. Unlike simple search and replace, it uses intelligent matching algorithms (including fuzzy matching) that adapt to different content types and file sizes, with fallback mechanisms for complex edits.
+
+## When is it used?
+
+- When Kilo Code needs to make precise changes to existing code without rewriting entire files.
+- When refactoring specific sections of code while maintaining surrounding context.
+- When fixing bugs in existing code with surgical precision.
+- When implementing feature enhancements that modify only certain parts of a file.
+
+## Key Features
+
+- Uses intelligent fuzzy matching with configurable confidence thresholds (typically 0.8-1.0).
+- Provides context around matches using `BUFFER_LINES` (default 40).
+- Employs an overlapping window approach for searching large files.
+- Preserves code formatting and indentation automatically.
+- Combines overlapping matches for improved confidence scoring.
+- Shows changes in a diff view for user review and editing before applying.
+- Tracks consecutive errors per file (`consecutiveMistakeCountForApplyDiff`) to prevent repeated failures.
+- Validates file access against `.kilocodeignore` rules.
+- Handles multi-line edits effectively.
+
+## Limitations
+
+- Works best with unique, distinctive code sections for reliable identification.
+- Performance can vary with very large files or highly repetitive code patterns.
+- Fuzzy matching might occasionally select incorrect locations if content is ambiguous.
+- Each diff strategy has specific format requirements.
+- Complex edits might require careful strategy selection or manual review.
+
+## How It Works
+
+When the `apply_diff` tool is invoked, it follows this process:
+
+1.  **Parameter Validation**: Validates required `path` and `diff` parameters.
+2.  **KiloCodeIgnore Check**: Validates if the target file path is allowed by `.kilocodeignore` rules.
+3.  **File Analysis**: Loads the target file content.
+4.  **Match Finding**: Uses the selected strategy's algorithms (exact, fuzzy, overlapping windows) to locate the target content, considering confidence thresholds and context (`BUFFER_LINES`).
+5.  **Change Preparation**: Generates the proposed changes, preserving indentation.
+6.  **User Interaction**:
+    - Displays the changes in a diff view.
+    - Allows the user to review and potentially edit the proposed changes.
+    - Waits for user approval or rejection.
+7.  **Change Application**: If approved, applies the changes (potentially including user edits) to the file.
+8.  **Error Handling**: If errors occur (e.g., match failure, partial application), increments the `consecutiveMistakeCountForApplyDiff` for the file and reports the failure type.
+9.  **Feedback**: Returns the result, including any user feedback or error details.
+
+## Diff Strategy
+
+Kilo Code uses this strategy for applying diffs:
+
+### MultiSearchReplaceDiffStrategy
+
+An enhanced search/replace format supporting multiple changes in one request. **Line numbers are mandatory for each search block.**
+
+- **Best for**: Multiple, distinct changes where line numbers are known or can be estimated.
+- **Requires**: Exact match for the `SEARCH` block content, including whitespace and indentation. The `:start_line:` marker is **required** within each SEARCH block. Markers within content must be escaped (`\`).
+
+Example format for the `<diff>` block:
+
+```diff
+<<<<<<< SEARCH
+:start_line:10
+:end_line:12
+-------
+    // Old calculation logic
+    const result = value * 0.9;
+    return result;
+=======
+    // Updated calculation logic with logging
+    console.log(`Calculating for value: ${value}`);
+    const result = value * 0.95; // Adjusted factor
+    return result;
+>>>>>>> REPLACE
+
+<<<<<<< SEARCH
+:start_line:25
+:end_line:25
+-------
+    const defaultTimeout = 5000;
+=======
+    const defaultTimeout = 10000; // Increased timeout
+>>>>>>> REPLACE
+```

apps/kilocode-docs/pages/automate/tools/ask-followup-question.md

@@ -0,0 +1,177 @@
+# ask_followup_question
+
+The `ask_followup_question` tool enables interactive communication by asking specific questions to gather additional information needed to complete tasks effectively.
+
+## Parameters
+
+The tool accepts these parameters:
+
+- `question` (required): The specific question to ask the user
+- `follow_up` (optional): A list of 2-4 suggested answers that help guide user responses, each within `<suggest>` tags
+
+## What It Does
+
+This tool creates a conversational interface between Kilo Code and the user, allowing for gathering clarification, additional details, or user preferences when facing ambiguities or decision points. Each question can include suggested responses to streamline the interaction.
+
+## When is it used?
+
+- When critical information is missing from the original request
+- When Kilo Code needs to choose between multiple valid implementation approaches
+- When technical details or preferences are required to proceed
+- When Kilo Code encounters ambiguities that need resolution
+- When additional context would significantly improve the solution quality
+
+## Key Features
+
+- Provides a structured way to gather specific information without breaking workflow
+- Includes suggested answers to reduce user typing and guide responses
+- Maintains conversation history and context across interactions
+- Supports responses containing images and code snippets
+- Available in all modes as part of the "always available" tool set
+- Enables direct user guidance on implementation decisions
+- Formats responses with `<answer>` tags to distinguish them from regular conversation
+- Resets consecutive error counter when used successfully
+
+## Limitations
+
+- Limited to asking one specific question per tool use
+- Presents suggestions as selectable options in the UI
+- Cannot force structured responses – users can still respond freely
+- Excessive use can slow down task completion and create a fragmented experience
+- Suggested answers must be complete, with no placeholders requiring user edits
+- No built-in validation for user responses
+- Contains no mechanism to enforce specific answer formats
+
+## How It Works
+
+When the `ask_followup_question` tool is invoked, it follows this process:
+
+1. **Parameter Validation**: Validates the required `question` parameter and checks for optional suggestions
+
+    - Ensures question text is provided
+    - Parses any suggested answers from the `follow_up` parameter using the `fast-xml-parser` library
+    - Normalizes suggestions into an array format even if there's only one suggestion
+
+2. **JSON Transformation**: Converts the XML structure into a standardized JSON format for UI display
+
+    ```typescript
+    {
+      question: "User's question here",
+      suggest: [
+        { answer: "Suggestion 1" },
+        { answer: "Suggestion 2" }
+      ]
+    }
+    ```
+
+3. **UI Integration**:
+
+    - Passes the JSON structure to the UI layer via the `ask("followup", ...)` method
+    - Displays selectable suggestion buttons to the user in the interface
+    - Creates an interactive experience for selecting or typing a response
+
+4. **Response Collection and Processing**:
+
+    - Captures user text input and any images included in the response
+    - Wraps user responses in `<answer>` tags when returning to the assistant
+    - Preserves any images included in the user's response
+    - Maintains the conversational context by adding the response to the history
+    - Resets the consecutive error counter when the tool is used successfully
+
+5. **Error Handling**:
+    - Tracks consecutive mistakes using a counter
+    - Resets the counter when the tool is used successfully
+    - Provides specific error messages:
+        - For missing parameters: "Missing required parameter 'question'"
+        - For XML parsing: "Failed to parse operations: [error message]"
+        - For invalid format: "Invalid operations xml format"
+    - Contains safeguards to prevent tool execution when required parameters are missing
+    - Increments consecutive mistake count when errors occur
+
+## Workflow Sequence
+
+The question-answer cycle follows this sequence:
+
+1. **Information Gap Recognition**: Kilo Code identifies missing information needed to proceed
+2. **Specific Question Creation**: Kilo Code formulates a clear, targeted question
+3. **Suggestion Development**: Kilo Code creates relevant suggested answers (optional but recommended)
+4. **Tool Invocation**: Assistant invokes the tool with question and optional suggestions
+5. **UI Presentation**: Question and suggestions are displayed to the user as interactive elements
+6. **User Response**: The user selects a suggestion or provides a custom answer
+7. **Message Handling**: System handles both partial and complete messages
+    - For streaming responses, processes chunks as they arrive
+    - For complete messages, processes the entire response at once
+    - Maintains state consistency regardless of message chunking
+8. **Response Processing**: System wraps the response in `<answer>` tags and preserves images
+9. **Context Integration**: Response is added to the conversation history
+10. **Task Continuation**: Kilo Code proceeds with the task using the new information
+
+## Examples When Used
+
+- When developing a web application, Kilo Code might ask about preferred styling frameworks (Bootstrap, Tailwind, custom CSS)
+- When creating an API, Kilo Code might ask about authentication methods (JWT, OAuth, API keys)
+- When refactoring code, Kilo Code might ask about prioritizing performance vs. readability
+- When setting up a database, Kilo Code might ask about specific schema design preferences
+- When creating a custom feature, Kilo Code might ask about specific behavior expectations
+- When troubleshooting errors, Kilo Code might ask about specific environment details
+
+## Response Format
+
+When a user responds to a question, the response is formatted with `<answer>` tags for clarity and consistency. This format helps clearly separate the user's answer from other conversation elements.
+
+Example response format:
+
+```
+<answer>
+Use Tailwind CSS for utility-first styling with maximum flexibility
+</answer>
+```
+
+Key characteristics of the response format:
+
+- Surrounded by `<answer>` tags
+- Preserves formatting of the original response
+- Maintains images if included in the response
+- Returns the complete text, even for long responses
+
+## Usage Examples
+
+Asking about implementation preferences:
+
+```
+<ask_followup_question>
+<question>Which styling approach would you prefer for this web application?</question>
+<follow_up>
+<suggest>Use Bootstrap for rapid development with consistent components</suggest>
+<suggest>Use Tailwind CSS for utility-first styling with maximum flexibility</suggest>
+<suggest>Use vanilla CSS with custom styling for complete control and minimal dependencies</suggest>
+</follow_up>
+</ask_followup_question>
+```
+
+Requesting technical clarification:
+
+```
+<ask_followup_question>
+<question>What database should this application use for storing user data?</question>
+<follow_up>
+<suggest>MongoDB for flexible schema and document-based storage</suggest>
+<suggest>PostgreSQL for relational data with strong consistency guarantees</suggest>
+<suggest>Firebase for real-time updates and simplified backend management</suggest>
+<suggest>SQLite for lightweight local storage without external dependencies</suggest>
+</follow_up>
+</ask_followup_question>
+```
+
+Addressing ambiguity in requirements:
+
+```
+<ask_followup_question>
+<question>How should the application handle user authentication?</question>
+<follow_up>
+<suggest>Implement email/password authentication with account verification</suggest>
+<suggest>Use social login providers (Google, GitHub, etc.) for quick signup</suggest>
+<suggest>Implement both email/password and social login options</suggest>
+</follow_up>
+</ask_followup_question>
+```

apps/kilocode-docs/pages/automate/tools/attempt-completion.md

@@ -0,0 +1,183 @@
+# attempt_completion
+
+The `attempt_completion` tool signals that Kilo Code believes a task is complete and presents results to the user. It provides a summary of what was accomplished, optionally includes a command to demonstrate the result, and supports continued refinement through user feedback.
+
+## Parameters
+
+The tool accepts these parameters:
+
+- `result` (required): The final result description summarizing what was accomplished
+- `command` (optional): A CLI command to execute to demonstrate the result
+
+## What It Does
+
+This tool marks the end of a task by presenting a final summary of what was accomplished. It signals to both the user and the system that the current task is complete. When a command is provided, it can also demonstrate the result through a live execution.
+
+## When is it used?
+
+- When Kilo Code believes the user's task has been completed
+- When summarizing what changes or improvements were made
+- When demonstrating the current result with a command execution
+- When providing a checkpoint for user feedback on the solution
+- When transitioning from one phase of work to potential refinements
+
+## Key Features
+
+- Provides a clear signal that Kilo Code believes the task is complete
+- Summarizes accomplishments in a concise message
+- Optionally demonstrates results through command execution
+- Enables user feedback for further refinements
+- Displays results in a special UI format distinct from regular messages
+- Captures task completion telemetry for system analytics
+- Maintains a structured conversation flow by providing checkpoints
+- Supports subtask completion within larger workflows
+- Ensures users receive a clear summary of what was done
+- Available in all modes as part of the "always available" tool group
+
+## Limitations
+
+- Should not be used until previous tool uses are confirmed successful (guideline, not enforced)
+- Limited to a single command for result demonstration
+- Cannot present multiple command options
+- Commands require user approval before execution
+- Limited to demonstrating results that can be shown via CLI commands
+- Cannot be used for partial task completion or progress updates
+- Result formatting strips XML closing tags through internal processing
+
+## How It Works
+
+When the `attempt_completion` tool is invoked, it follows this process:
+
+1. **Safety Consideration** (guideline, not enforced):
+
+    - The AI is instructed to confirm previous tool uses were successful
+    - This is a best practice rather than a programmatically enforced mechanism
+
+2. **Result Presentation**:
+
+    - Displays the completion message to the user in a special "completion_result" UI format
+    - Removes XML closing tags from the result text using the `removeClosingTag` function
+    - Presents the result differently than regular messages for visual distinction
+
+3. **Command Execution** (if provided):
+
+    - Requests user approval before executing the command
+    - Only executes if the user approves
+    - Executes the command using the system's command execution functionality
+    - Shows the result of the command to the user
+
+4. **Feedback Collection**:
+
+    - Waits for user feedback on the completion result
+    - Processes this feedback and returns it to the AI
+    - Enables continued refinement based on user input
+
+5. **Task Completion and Continuation**:
+
+    - Signals the task as completed in the system
+    - Captures telemetry data for the completed task
+    - For subtasks, offers to finish the subtask and resume the parent task
+    - Supports continued conversation through the feedback mechanism
+
+6. **Implementation Integration**:
+    - Tool results are parsed through the system's parsing mechanism in `parse-assistant-message.ts`
+    - The tool is part of the "ALWAYS_AVAILABLE_TOOLS" constant, making it available in all modes
+
+## Result Formatting Guidelines
+
+The result message should follow these guidelines:
+
+- Clearly communicate what was accomplished
+- Be concise but complete
+- Focus on the value delivered to the user
+- Avoid unnecessary pleasantries or filler text
+- Maintain a professional, straightforward tone
+- Present information in a way that's easy to scan and understand
+- Acknowledge that the user may provide feedback for further refinements
+
+Note: The system automatically strips XML closing tags from the result text through the `removeClosingTag` function.
+
+## Command Selection Guidelines
+
+When including a command, follow these guidelines:
+
+- Choose commands that visually demonstrate the result
+- Prefer commands that show the user what was created or modified
+- Examples include:
+    - `open index.html` to display a created website
+    - `npm start` to launch a development server
+    - `python app.py` to run a created application
+- Avoid commands that merely print text (like `echo` or `cat`)
+- Remember that commands require user approval before execution
+- Ensure the command is valid for the user's operating system
+
+## Feedback and UI Representation
+
+The `attempt_completion` tool has a unique feedback mechanism:
+
+- Results appear in a special "completion_result" UI format distinct from regular messages
+- The system waits for user feedback after presenting the result
+- Feedback is processed and returned to Kilo Code for further refinements
+- This creates an iterative improvement cycle rather than ending the conversation
+- The UI includes special elements for providing feedback
+- Results serve as clear checkpoints in the conversation flow
+
+When used within subtasks:
+
+- The system offers to finish the subtask and resume the parent task
+- If approved, the subtask is completed with a summary
+- The parent task resumes with context from the completed subtask
+- This enables complex, nested workflows while maintaining context
+
+## Examples When Used
+
+- When creating a website, Kilo Code presents the solution and uses `open index.html` to show the result. The user provides feedback, and Kilo Code refines the design.
+- When implementing a feature, Kilo Code summarizes the changes and their impact. The user requests additional test coverage, and Kilo Code continues the task.
+- When fixing bugs, Kilo Code explains what was fixed and how the solution addresses the Kilo Codet cause. The user confirms the fix works.
+- When setting up a development environment, Kilo Code confirms all components are installed. The user requests additional configuration, and Kilo Code continues.
+- When creating a data processing script, Kilo Code summarizes the functionality. The user suggests performance improvements, and Kilo Code optimizes the code.
+
+## Usage Examples
+
+Completing a task with just a result summary:
+
+```
+<attempt_completion>
+<result>
+I've updated the CSS for the navigation bar to match the design mockup. The changes include:
+1. Updated color scheme to use the new brand colors
+2. Added responsive behavior for mobile devices
+3. Fixed the alignment issues in the dropdown menus
+</result>
+</attempt_completion>
+```
+
+Completing a task with a result and demonstration command:
+
+```
+<attempt_completion>
+<result>
+I've created a simple React application with the following features:
+1. A responsive landing page with the requested hero section
+2. A working contact form with validation
+3. Navigation between all three requested pages
+4. Styling that matches the provided design mockup
+</result>
+<command>npm start</command>
+</attempt_completion>
+```
+
+Completing a Python script task with execution:
+
+```
+<attempt_completion>
+<result>
+I've created a data processing script that:
+1. Reads the CSV files from the data directory
+2. Cleans and normalizes the data as requested
+3. Generates the summary statistics in JSON format
+4. Outputs the processed data to the output directory
+</result>
+<command>python process_data.py</command>
+</attempt_completion>
+```

apps/kilocode-docs/pages/automate/tools/browser-action.md

@@ -0,0 +1,162 @@
+# browser_action
+
+The `browser_action` tool enables web automation and interaction via a Puppeteer-controlled browser. It allows Kilo Code to launch browsers, navigate to websites, click elements, type text, and scroll pages with visual feedback through screenshots.
+
+## Parameters
+
+The tool accepts these parameters:
+
+- `action` (required): The action to perform:
+    - `launch`: Start a new browser session at a URL
+    - `click`: Click at specific x,y coordinates
+    - `type`: Type text via the keyboard
+    - `scroll_down`: Scroll down one page height
+    - `scroll_up`: Scroll up one page height
+    - `close`: End the browser session
+- `url` (optional): The URL to navigate to when using the `launch` action
+- `coordinate` (optional): The x,y coordinates for the `click` action (e.g., "450,300")
+- `text` (optional): The text to type when using the `type` action
+
+## What It Does
+
+This tool creates an automated browser session that Kilo Code can control to navigate websites, interact with elements, and perform tasks that require browser automation. Each action provides a screenshot of the current state, enabling visual verification of the process.
+
+## When is it used?
+
+- When Kilo Code needs to interact with web applications or websites
+- When testing user interfaces or web functionality
+- When capturing screenshots of web pages
+- When demonstrating web workflows visually
+
+## Key Features
+
+- Provides visual feedback with screenshots after each action and captures console logs
+- Supports complete workflows from launching to page interaction to closing
+- Enables precise interactions via coordinates, keyboard input, and scrolling
+- Maintains consistent browser sessions with intelligent page loading detection
+- Operates in two modes: local (isolated Puppeteer instance) or remote (connects to existing Chrome)
+- Handles errors gracefully with automatic session cleanup and detailed messages
+- Optimizes visual output with support for various formats and quality settings
+- Tracks interaction state with position indicators and action history
+
+## Browser Modes
+
+The tool operates in two distinct modes:
+
+### Local Browser Mode (Default)
+
+- Downloads and manages a local Chromium instance through Puppeteer
+- Creates a fresh browser environment with each launch
+- No access to existing user profiles, cookies, or extensions
+- Consistent, predictable behavior in a sandboxed environment
+- Completely closes the browser when the session ends
+
+### Remote Browser Mode
+
+- Connects to an existing Chrome/Chromium instance running with remote debugging enabled
+- Can access existing browser state, cookies, and potentially extensions
+- Faster startup as it reuses an existing browser process
+- Supports connecting to browsers in Docker containers or on remote machines
+- Only disconnects (doesn't close) from the browser when session ends
+- Requires Chrome to be running with remote debugging port open (typically port 9222)
+
+## Limitations
+
+- While the browser is active, only `browser_action` tool can be used
+- Browser coordinates are viewport-relative, not page-relative
+- Click actions must target visible elements within the viewport
+- Browser sessions must be explicitly closed before using other tools
+- Browser window has configurable dimensions (default 900x600)
+- Cannot directly interact with browser DevTools
+- Browser sessions are temporary and not persistent across Kilo Code restarts
+- Works only with Chrome/Chromium browsers, not Firefox or Safari
+- Local mode has no access to existing cookies; remote mode requires Chrome with debugging enabled
+
+## How It Works
+
+When the `browser_action` tool is invoked, it follows this process:
+
+1. **Action Validation and Browser Management**:
+
+    - Validates the required parameters for the requested action
+    - For `launch`: Initializes a browser session (either local Puppeteer instance or remote Chrome)
+    - For interaction actions: Uses the existing browser session
+    - For `close`: Terminates or disconnects from the browser appropriately
+
+2. **Page Interaction and Stability**:
+
+    - Ensures pages are fully loaded using DOM stability detection via `waitTillHTMLStable` algorithm
+    - Executes requested actions (navigation, clicking, typing, scrolling) with proper timing
+    - Monitors network activity after clicks and waits for navigation when necessary
+
+3. **Visual Feedback**:
+
+    - Captures optimized screenshots using WebP format (with PNG fallback)
+    - Records browser console logs for debugging purposes
+    - Tracks mouse position and maintains paginated history of actions
+
+4. **Session Management**:
+    - Maintains browser state across multiple actions
+    - Handles errors and automatically cleans up resources
+    - Enforces proper workflow sequence (launch → interactions → close)
+
+## Workflow Sequence
+
+Browser interactions must follow this specific sequence:
+
+1. **Session Initialization**: All browser workflows must start with a `launch` action
+2. **Interaction Phase**: Multiple `click`, `type`, and scroll actions can be performed
+3. **Session Termination**: All browser workflows must end with a `close` action
+4. **Tool Switching**: After closing the browser, other tools can be used
+
+## Examples When Used
+
+- When creating a web form submission process, Kilo Code launches a browser, navigates to the form, fills out fields with the `type` action, and clicks submit.
+- When testing a responsive website, Kilo Code navigates to the site and uses scroll actions to examine different sections.
+- When capturing screenshots of a web application, Kilo Code navigates through different pages and takes screenshots at each step.
+- When demonstrating an e-commerce checkout flow, Kilo Code simulates the entire process from product selection to payment confirmation.
+
+## Usage Examples
+
+Launching a browser and navigating to a website:
+
+```
+<browser_action>
+<action>launch</action>
+<url>https://example.com</url>
+</browser_action>
+```
+
+Clicking at specific coordinates (e.g., a button):
+
+```
+<browser_action>
+<action>click</action>
+<coordinate>450,300</coordinate>
+</browser_action>
+```
+
+Typing text into a focused input field:
+
+```
+<browser_action>
+<action>type</action>
+<text>Hello, World!</text>
+</browser_action>
+```
+
+Scrolling down to see more content:
+
+```
+<browser_action>
+<action>scroll_down</action>
+</browser_action>
+```
+
+Closing the browser session:
+
+```
+<browser_action>
+<action>close</action>
+</browser_action>
+```

apps/kilocode-docs/pages/automate/tools/codebase-search.md

@@ -0,0 +1,263 @@
+# codebase_search
+
+:::info Setup Required
+The `codebase_search` tool is part of the [Codebase Indexing](/features/codebase-indexing) feature. It requires additional setup including an embedding provider and vector database.
+:::
+
+The `codebase_search` tool performs semantic searches across your entire codebase using AI embeddings. Unlike traditional text-based search, it understands the meaning of your queries and finds relevant code even when exact keywords don't match.
+
+---
+
+## Parameters
+
+The tool accepts these parameters:
+
+- `query` (required): Natural language search query describing what you're looking for
+- `path` (optional): Directory path to limit search scope to a specific part of your codebase
+
+---
+
+## What It Does
+
+This tool searches through your indexed codebase using semantic similarity rather than exact text matching. It finds code blocks that are conceptually related to your query, even if they don't contain the exact words you searched for. Results include relevant code snippets with file paths, line numbers, and similarity scores.
+
+---
+
+## When is it used?
+
+- When Kilo Code needs to find code related to specific functionality across your project
+- When looking for implementation patterns or similar code structures
+- When searching for error handling, authentication, or other conceptual code patterns
+- When exploring unfamiliar codebases to understand how features are implemented
+- When finding related code that might be affected by changes or refactoring
+
+---
+
+## Key Features
+
+- **Semantic Understanding**: Finds code by meaning rather than exact keyword matches
+- **Cross-Project Search**: Searches across your entire indexed codebase, not just open files
+- **Contextual Results**: Returns code snippets with file paths and line numbers for easy navigation
+- **Similarity Scoring**: Results ranked by relevance with similarity scores (0-1 scale)
+- **Scope Filtering**: Optional path parameter to limit searches to specific directories
+- **Intelligent Ranking**: Results sorted by semantic relevance to your query
+- **UI Integration**: Results displayed with syntax highlighting and navigation links
+- **Performance Optimized**: Fast vector-based search with configurable result limits
+
+---
+
+## Requirements
+
+This tool is only available when the Codebase Indexing feature is properly configured:
+
+- **Feature Configured**: Codebase Indexing must be configured in settings
+- **Embedding Provider**: OpenAI API key or Ollama configuration required
+- **Vector Database**: Qdrant instance running and accessible
+- **Index Status**: Codebase must be indexed (status: "Indexed" or "Indexing")
+
+---
+
+## Limitations
+
+- **Requires Configuration**: Depends on external services (embedding provider + Qdrant)
+- **Index Dependency**: Only searches through indexed code blocks
+- **Result Limits**: Maximum of 50 results per search to maintain performance
+- **Similarity Threshold**: Only returns results above similarity threshold (default: 0.4, configurable)
+- **File Size Limits**: Limited to files under 1MB that were successfully indexed
+- **Language Support**: Effectiveness depends on Tree-sitter language support
+
+---
+
+## How It Works
+
+When the `codebase_search` tool is invoked, it follows this process:
+
+1. **Availability Validation**:
+
+    - Verifies that the CodeIndexManager is available and initialized
+    - Confirms codebase indexing is enabled in settings
+    - Checks that indexing is properly configured (API keys, Qdrant URL)
+    - Validates the current index state allows searching
+
+2. **Query Processing**:
+
+    - Takes your natural language query and generates an embedding vector
+    - Uses the same embedding provider configured for indexing (OpenAI or Ollama)
+    - Converts the semantic meaning of your query into a mathematical representation
+
+3. **Vector Search Execution**:
+
+    - Searches the Qdrant vector database for similar code embeddings
+    - Uses cosine similarity to find the most relevant code blocks
+    - Applies the minimum similarity threshold (default: 0.4, configurable) to filter results
+    - Limits results to 50 matches for optimal performance
+
+4. **Path Filtering** (if specified):
+
+    - Filters results to only include files within the specified directory path
+    - Uses normalized path comparison for accurate filtering
+    - Maintains relevance ranking within the filtered scope
+
+5. **Result Processing and Formatting**:
+
+    - Converts absolute file paths to workspace-relative paths
+    - Structures results with file paths, line ranges, similarity scores, and code content
+    - Formats for both AI consumption and UI display with syntax highlighting
+
+6. **Dual Output Format**:
+    - **AI Output**: Structured text format with query, file paths, scores, and code chunks
+    - **UI Output**: JSON format with syntax highlighting and navigation capabilities
+
+---
+
+## Search Query Best Practices
+
+### Effective Query Patterns
+
+**Good: Conceptual and specific**
+
+```xml
+<codebase_search>
+<query>user authentication and password validation</query>
+</codebase_search>
+```
+
+**Good: Feature-focused**
+
+```xml
+<codebase_search>
+<query>database connection pool setup</query>
+</codebase_search>
+```
+
+**Good: Problem-oriented**
+
+```xml
+<codebase_search>
+<query>error handling for API requests</query>
+</codebase_search>
+```
+
+**Less effective: Too generic**
+
+```xml
+<codebase_search>
+<query>function</query>
+</codebase_search>
+```
+
+### Query Types That Work Well
+
+- **Functional Descriptions**: "file upload processing", "email validation logic"
+- **Technical Patterns**: "singleton pattern implementation", "factory method usage"
+- **Domain Concepts**: "user profile management", "payment processing workflow"
+- **Architecture Components**: "middleware configuration", "database migration scripts"
+
+---
+
+## Directory Scoping
+
+Use the optional `path` parameter to focus searches on specific parts of your codebase:
+
+**Search within API modules:**
+
+```xml
+<codebase_search>
+<query>endpoint validation middleware</query>
+<path>src/api</path>
+</codebase_search>
+```
+
+**Search in test files:**
+
+```xml
+<codebase_search>
+<query>mock data setup patterns</query>
+<path>tests</path>
+</codebase_search>
+```
+
+**Search specific feature directories:**
+
+```xml
+<codebase_search>
+<query>component state management</query>
+<path>src/components/auth</path>
+</codebase_search>
+```
+
+---
+
+## Result Interpretation
+
+### Similarity Scores
+
+- **0.8-1.0**: Highly relevant matches, likely exactly what you're looking for
+- **0.6-0.8**: Good matches with strong conceptual similarity
+- **0.4-0.6**: Potentially relevant but may require review
+- **Below 0.4**: Filtered out as too dissimilar
+
+### Result Structure
+
+Each search result includes:
+
+- **File Path**: Workspace-relative path to the file containing the match
+- **Score**: Similarity score indicating relevance (0.4-1.0)
+- **Line Range**: Start and end line numbers for the code block
+- **Code Chunk**: The actual code content that matched your query
+
+---
+
+## Examples When Used
+
+- When implementing a new feature, Kilo Code searches for "authentication middleware" to understand existing patterns before writing new code.
+- When debugging an issue, Kilo Code searches for "error handling in API calls" to find related error patterns across the codebase.
+- When refactoring code, Kilo Code searches for "database transaction patterns" to ensure consistency across all database operations.
+- When onboarding to a new codebase, Kilo Code searches for "configuration loading" to understand how the application bootstraps.
+
+---
+
+## Usage Examples
+
+Searching for authentication-related code across the entire project:
+
+```xml
+<codebase_search>
+<query>user login and authentication logic</query>
+</codebase_search>
+```
+
+Finding database-related code in a specific directory:
+
+```xml
+<codebase_search>
+<query>database connection and query execution</query>
+<path>src/data</path>
+</codebase_search>
+```
+
+Looking for error handling patterns in API code:
+
+```xml
+<codebase_search>
+<query>HTTP error responses and exception handling</query>
+<path>src/api</path>
+</codebase_search>
+```
+
+Searching for testing utilities and mock setups:
+
+```xml
+<codebase_search>
+<query>test setup and mock data creation</query>
+<path>tests</path>
+</codebase_search>
+```
+
+Finding configuration and environment setup code:
+
+```xml
+<codebase_search>
+<query>environment variables and application configuration</query>
+</codebase_search>
+```

apps/kilocode-docs/pages/automate/tools/delete-file.md

@@ -0,0 +1,55 @@
+# delete_file
+
+Delete a file or directory from the workspace. This tool provides a safe alternative to rm commands and works across all platforms.
+
+## Parameters
+
+- `path` (required): Relative path to the file or directory to delete
+
+## Description
+
+This tool safely deletes files and directories with user confirmation. For directories, it validates all contained files and shows statistics before deletion.
+
+## Safety Features
+
+- Only deletes files/directories within the workspace
+- Requires user confirmation before deletion
+- Prevents deletion of write-protected files
+- Validates all files against `.kilocodeignore` rules
+- For directories: scans recursively and shows statistics (file count, directory count, total size) before deletion
+- Blocks directory deletion if any contained file is protected or ignored
+
+## Usage
+
+### Delete a single file
+
+```xml
+<delete_file>
+<path>temp/old_file.txt</path>
+</delete_file>
+```
+
+### Delete a directory
+
+```xml
+<delete_file>
+<path>old_project/</path>
+</delete_file>
+```
+
+When deleting a directory, the tool:
+
+1. Scans the directory recursively
+2. Validates all files can be deleted
+3. Shows summary with file count, subdirectory count, and total size
+4. Requires user approval before deletion
+
+## Error Handling
+
+The tool provides clear error messages for:
+
+- File or directory does not exist
+- File is write-protected
+- File is blocked by `.kilocodeignore` rules
+- Directory contains protected or ignored files
+- Path is outside the workspace

apps/kilocode-docs/pages/automate/tools/execute-command.md

@@ -0,0 +1,164 @@
+# execute_command
+
+The `execute_command` tool runs CLI commands on the user's system. It allows Kilo Code to perform system operations, install dependencies, build projects, start servers, and execute other terminal-based tasks needed to accomplish user objectives.
+
+## Parameters
+
+The tool accepts these parameters:
+
+- `command` (required): The CLI command to execute. Must be valid for the user's operating system.
+- `cwd` (optional): The working directory to execute the command in. If not provided, the current working directory is used.
+
+## What It Does
+
+This tool executes terminal commands directly on the user's system, enabling a wide range of operations from file manipulations to running development servers. Commands run in managed terminal instances with real-time output capture, integrated with VS Code's terminal system for optimal performance and security.
+
+## When is it used?
+
+- When installing project dependencies (npm install, pip install, etc.)
+- When building or compiling code (make, npm run build, etc.)
+- When starting development servers or running applications
+- When initializing new projects (git init, npm init, etc.)
+- When performing file operations beyond what other tools provide
+- When running tests or linting operations
+- When needing to execute specialized commands for specific technologies
+
+## Key Features
+
+- Integrates with VS Code shell API for reliable terminal execution
+- Reuses terminal instances when possible through a registry system
+- Captures command output line by line with real-time feedback
+- Supports long-running commands that continue in the background
+- Allows specification of custom working directories
+- Maintains terminal history and state across command executions
+- Handles complex command chains appropriate for the user's shell
+- Provides detailed command completion status and exit code interpretation
+- Supports interactive terminal applications with user feedback loop
+- Shows terminals during execution for transparency
+- Validates commands for security using shell-quote parsing
+- Blocks potentially dangerous subshell execution patterns
+- Integrates with KiloCodeIgnore system for file access control
+- Handles terminal escape sequences for clean output
+
+## Limitations
+
+- Command access may be restricted by KiloCodeIgnore rules and security validations
+- Commands with elevated permission requirements may need user configuration
+- Behavior may vary across operating systems for certain commands
+- Very long-running commands may require specific handling
+- File paths should be properly escaped according to the OS shell rules
+- Not all terminal features may work with remote development scenarios
+
+## How It Works
+
+When the `execute_command` tool is invoked, it follows this process:
+
+1. **Command Validation and Security Checks**:
+
+    - Parses the command using shell-quote to identify components
+    - Validates against security restrictions (subshell usage, restricted files)
+    - Checks against KiloCodeIgnore rules for file access permissions
+    - Ensures the command meets system security requirements
+
+2. **Terminal Management**:
+
+    - Gets or creates a terminal through TerminalRegistry
+    - Sets up the working directory context
+    - Prepares event listeners for output capture
+    - Shows the terminal for user visibility
+
+3. **Command Execution and Monitoring**:
+
+    - Executes via VS Code's shellIntegration API
+    - Captures output with escape sequence processing
+    - Throttles output handling (100ms intervals)
+    - Monitors for command completion or errors
+    - Detects "hot" processes like compilers for special handling
+
+4. **Result Processing**:
+    - Strips ANSI/VS Code escape sequences for clean output
+    - Interprets exit codes with detailed signal information
+    - Updates working directory tracking if changed by command
+    - Provides command status with appropriate context
+
+## Terminal Implementation Details
+
+The tool uses a sophisticated terminal management system:
+
+1. **First Priority: Terminal Reuse**
+
+    - The TerminalRegistry tries to reuse existing terminals when possible
+    - This reduces proliferation of terminal instances and improves performance
+    - Terminal state (working directory, history) is preserved across commands
+
+2. **Second Priority: Security Validation**
+
+    - Commands are parsed using shell-quote for component analysis
+    - Dangerous patterns like `$(...)` and backticks are blocked
+    - Commands are checked against KiloCodeIgnore rules for file access control
+    - A prefix-based allowlist system validates command patterns
+
+3. **Performance Optimizations**
+
+    - Output is processed in 100ms throttled intervals to prevent UI overload
+    - Zero-copy buffer management uses index-based tracking for efficiency
+    - Special handling for compilation and "hot" processes
+    - Platform-specific optimizations for Windows PowerShell
+
+4. **Error and Signal Handling**
+    - Exit codes are mapped to detailed signal information (SIGTERM, SIGKILL, etc.)
+    - Core dump detection for critical failures
+    - Working directory changes are tracked and handled automatically
+    - Clean recovery from terminal disconnection scenarios
+
+## Examples When Used
+
+- When setting up a new project, Kilo Code runs initialization commands like `npm init -y` followed by installing dependencies.
+- When building a web application, Kilo Code executes build commands like `npm run build` to compile assets.
+- When deploying code, Kilo Code runs git commands to commit and push changes to a repository.
+- When troubleshooting, Kilo Code executes diagnostic commands to gather system information.
+- When starting a development server, Kilo Code launches the appropriate server command (e.g., `npm start`).
+- When running tests, Kilo Code executes the test runner command for the project's testing framework.
+
+## Usage Examples
+
+Running a simple command in the current directory:
+
+```
+<execute_command>
+<command>npm run dev</command>
+</execute_command>
+```
+
+Installing dependencies for a project:
+
+```
+<execute_command>
+<command>npm install express mongodb mongoose dotenv</command>
+</execute_command>
+```
+
+Running multiple commands in sequence:
+
+```
+<execute_command>
+<command>mkdir -p src/components && touch src/components/App.js</command>
+</execute_command>
+```
+
+Executing a command in a specific directory:
+
+```
+<execute_command>
+<command>git status</command>
+<cwd>./my-project</cwd>
+</execute_command>
+```
+
+Building and then starting a project:
+
+```
+<execute_command>
+<command>npm run build && npm start</command>
+</execute_command>
+```

apps/kilocode-docs/pages/automate/tools/index.md

@@ -0,0 +1,274 @@
+---
+title: Tool Use Details
+description: Learn how Kilo Code's tools automate your development workflow
+---
+
+# Tool Use Overview
+
+Kilo Code implements a sophisticated tool system that allows AI models to interact with your development environment in a controlled and secure manner. This document explains how tools work, when they're called, and how they're managed.
+
+## Core Concepts
+
+### Tool Groups
+
+Tools are organized into logical groups based on their functionality:
+
+| Category           | Purpose                           | Tools                                                                                                                                                                                                                                                            | Common Use                                         |
+| ------------------ | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| **Read Group**     | File system reading and searching | [read_file](/features/tools/read-file), [search_files](/features/tools/search-files), [list_files](/features/tools/list-files), [list_code_definition_names](/features/tools/list-code-definition-names)                                                         | Code exploration and analysis                      |
+| **Edit Group**     | File system modifications         | [apply_diff](/features/tools/apply-diff), [delete_file](/features/tools/delete-file), [write_to_file](/features/tools/write-to-file)                                                                                                                             | Code changes and file manipulation                 |
+| **Browser Group**  | Web automation                    | [browser_action](/features/tools/browser-action)                                                                                                                                                                                                                 | Web testing and interaction                        |
+| **Command Group**  | System command execution          | [execute_command](/features/tools/execute-command)                                                                                                                                                                                                               | Running scripts, building projects                 |
+| **MCP Group**      | External tool integration         | [use_mcp_tool](/features/tools/use-mcp-tool), [access_mcp_resource](/features/tools/access-mcp-resource)                                                                                                                                                         | Specialized functionality through external servers |
+| **Workflow Group** | Mode and task management          | [switch_mode](/features/tools/switch-mode), [new_task](/features/tools/new-task), [ask_followup_question](/features/tools/ask-followup-question), [attempt_completion](/features/tools/attempt-completion), [update_todo_list](/features/tools/update-todo-list) | Context switching and task organization            |
+
+### Always Available Tools
+
+Certain tools are accessible regardless of the current mode:
+
+- [ask_followup_question](/features/tools/ask-followup-question): Gather additional information from users
+- [attempt_completion](/features/tools/attempt-completion): Signal task completion
+- [switch_mode](/features/tools/switch-mode): Change operational modes
+- [new_task](/features/tools/new-task): Create subtasks
+- [update_todo_list](/features/tools/update-todo-list): Manage step-by-step task tracking
+
+## Available Tools
+
+### Read Tools
+
+These tools help Kilo Code understand your code and project:
+
+- [read_file](/features/tools/read-file) - Examines the contents of files
+- [search_files](/features/tools/search-files) - Finds patterns across multiple files
+- [list_files](/features/tools/list-files) - Maps your project's file structure
+- [list_code_definition_names](/features/tools/list-code-definition-names) - Creates a structural map of your code
+
+### Edit Tools
+
+These tools help Kilo Code make changes to your code:
+
+- [apply_diff](/features/tools/apply-diff) - Makes precise, surgical changes to your code
+- [delete_file](/features/tools/delete-file) - Removes files from your workspace
+- [write_to_file](/features/tools/write-to-file) - Creates new files or completely rewrites existing ones
+
+### Browser Tools
+
+These tools help Kilo Code interact with web applications:
+
+- [browser_action](/features/tools/browser-action) - Automates browser interactions
+
+### Command Tools
+
+These tools help Kilo Code execute commands:
+
+- [execute_command](/features/tools/execute-command) - Runs system commands and programs
+
+### MCP Tools
+
+These tools help Kilo Code connect with external services:
+
+- [use_mcp_tool](/features/tools/use-mcp-tool) - Uses specialized external tools
+- [access_mcp_resource](/features/tools/access-mcp-resource) - Accesses external data sources
+
+### Workflow Tools
+
+These tools help manage the conversation and task flow:
+
+- [ask_followup_question](/features/tools/ask-followup-question) - Gets additional information from you
+- [attempt_completion](/features/tools/attempt-completion) - Presents final results
+- [switch_mode](/features/tools/switch-mode) - Changes to a different mode for specialized tasks
+- [new_task](/features/tools/new-task) - Creates a new subtask
+- [update_todo_list](/features/tools/update-todo-list) - Tracks task progress with step-by-step checklists
+
+## Tool Calling Mechanism
+
+### When Tools Are Called
+
+Tools are invoked under specific conditions:
+
+1. **Direct Task Requirements**
+
+    - When specific actions are needed to complete a task as decided by the LLM
+    - In response to user requests
+    - During automated workflows
+
+2. **Mode-Based Availability**
+
+    - Different modes enable different tool sets
+    - Mode switches can trigger tool availability changes
+    - Some tools are restricted to specific modes
+
+3. **Context-Dependent Calls**
+    - Based on the current state of the workspace
+    - In response to system events
+    - During error handling and recovery
+
+### Decision Process
+
+The system uses a multi-step process to determine tool availability:
+
+1. **Mode Validation**
+
+    ```typescript
+    isToolAllowedForMode(
+        tool: string,
+        modeSlug: string,
+        customModes: ModeConfig[],
+        toolRequirements?: Record<string, boolean>,
+        toolParams?: Record<string, any>
+    )
+    ```
+
+2. **Requirement Checking**
+
+    - System capability verification
+    - Resource availability
+    - Permission validation
+
+3. **Parameter Validation**
+    - Required parameter presence
+    - Parameter type checking
+    - Value validation
+
+## Technical Implementation
+
+### Tool Call Processing
+
+1. **Initialization**
+
+    - Tool name and parameters are validated
+    - Mode compatibility is checked
+    - Requirements are verified
+
+2. **Execution**
+
+    ```typescript
+    const toolCall = {
+    	type: "tool_call",
+    	name: chunk.name,
+    	arguments: chunk.input,
+    	callId: chunk.callId,
+    }
+    ```
+
+3. **Result Handling**
+    - Success/failure determination
+    - Result formatting
+    - Error handling
+
+### Security and Permissions
+
+1. **Access Control**
+
+    - File system restrictions
+    - Command execution limitations
+    - Network access controls
+
+2. **Validation Layers**
+    - Tool-specific validation
+    - Mode-based restrictions
+    - System-level checks
+
+## Mode Integration
+
+### Mode-Based Tool Access
+
+Tools are made available based on the current mode:
+
+- **Code Mode**: Full access to file system tools, code editing capabilities, command execution
+- **Ask Mode**: Limited to reading tools, information gathering capabilities, no file system modifications
+- **Architect Mode**: Design-focused tools, documentation capabilities, limited execution rights
+- **Custom Modes**: Can be configured with specific tool access for specialized workflows
+
+### Mode Switching
+
+1. **Process**
+
+    - Current mode state preservation
+    - Tool availability updates
+    - Context switching
+
+2. **Impact on Tools**
+    - Tool set changes
+    - Permission adjustments
+    - Context preservation
+
+## Best Practices
+
+### Tool Usage Guidelines
+
+1. **Efficiency**
+
+    - Use the most specific tool for the task
+    - Avoid redundant tool calls
+    - Batch operations when possible
+
+2. **Security**
+
+    - Validate inputs before tool calls
+    - Use minimum required permissions
+    - Follow security best practices
+
+3. **Error Handling**
+    - Implement proper error checking
+    - Provide meaningful error messages
+    - Handle failures gracefully
+
+### Common Patterns
+
+1. **Information Gathering**
+
+    ```
+    [ask_followup_question](/features/tools/ask-followup-question) → [read_file](/features/tools/read-file) → [search_files](/features/tools/search-files)
+    ```
+
+2. **Code Modification**
+
+    ```
+    [read_file](/features/tools/read-file) → [apply_diff](/features/tools/apply-diff) → [attempt_completion](/features/tools/attempt-completion)
+    ```
+
+3. **Task Management**
+
+    ```
+    [new_task](/features/tools/new-task) → [switch_mode](/features/tools/switch-mode) → [execute_command](/features/tools/execute-command)
+    ```
+
+4. **Progress Tracking**
+    ```
+    [update_todo_list](/features/tools/update-todo-list) → [execute_command](/features/tools/execute-command) → [update_todo_list](/features/tools/update-todo-list)
+    ```
+
+## Error Handling and Recovery
+
+### Error Types
+
+1. **Tool-Specific Errors**
+
+    - Parameter validation failures
+    - Execution errors
+    - Resource access issues
+
+2. **System Errors**
+
+    - Permission denied
+    - Resource unavailable
+    - Network failures
+
+3. **Context Errors**
+    - Invalid mode for tool
+    - Missing requirements
+    - State inconsistencies
+
+### Recovery Strategies
+
+1. **Automatic Recovery**
+
+    - Retry mechanisms
+    - Fallback options
+    - State restoration
+
+2. **User Intervention**
+    - Error notifications
+    - Recovery suggestions
+    - Manual intervention options

apps/kilocode-docs/pages/automate/tools/list-code-definition-names.md

@@ -0,0 +1,120 @@
+# list_code_definition_names
+
+The `list_code_definition_names` tool provides a structural overview of your codebase by listing code definitions from source files at the top level of a specified directory. It helps Kilo Code understand code architecture by displaying line numbers and definition snippets.
+
+## Parameters
+
+The tool accepts these parameters:
+
+- `path` (required): The path of the directory to list top level source code definitions for, relative to the current working directory
+
+## What It Does
+
+This tool scans source code files at the top level of a specified directory and extracts code definitions like classes, functions, and interfaces. It displays the line numbers and actual code for each definition, providing a quick way to map the important components of your codebase.
+
+## When is it used?
+
+- When Kilo Code needs to understand your codebase architecture quickly
+- When Kilo Code needs to locate important code constructs across multiple files
+- When planning refactoring or extensions to existing code
+- Before diving into implementation details with other tools
+- When identifying relationships between different parts of your codebase
+
+## Key Features
+
+- Extracts classes, functions, methods, interfaces, and other definitions from source files
+- Displays line numbers and actual source code for each definition
+- Supports multiple programming languages including JavaScript, TypeScript, Python, Rust, Go, C++, C, C#, Ruby, Java, PHP, Swift, and Kotlin
+- Processes only files at the top level of the specified directory (not subdirectories)
+- Limits processing to a maximum of 50 files for performance
+- Focuses on top-level definitions to avoid overwhelming detail
+- Helps identify code organization patterns across the project
+- Creates a mental map of your codebase's architecture
+- Works in conjunction with other tools like `read_file` for deeper analysis
+
+## Limitations
+
+- Only identifies top-level definitions, not nested ones
+- Only processes files at the top level of the specified directory, not subdirectories
+- Limited to processing a maximum of 50 files per request
+- Dependent on language-specific parsers, with varying detection quality
+- May not recognize all definitions in languages with complex syntax
+- Not a substitute for reading code to understand implementation details
+- Cannot detect runtime patterns or dynamic code relationships
+- Does not provide information about how definitions are used
+- May have reduced accuracy with highly dynamic or metaprogrammed code
+- Limited to specific languages supported by the implemented Tree-sitter parsers
+
+## How It Works
+
+When the `list_code_definition_names` tool is invoked, it follows this process:
+
+1. **Parameter Validation**: Validates the required `path` parameter
+2. **Path Resolution**: Resolves the relative path to an absolute path
+3. **Directory Scanning**: Scans only the top level of the specified directory for source code files (not recursive)
+4. **File Filtering**: Limits processing to a maximum of 50 files
+5. **Language Detection**: Identifies file types based on extensions (.js, .jsx, .ts, .tsx, .py, .rs, .go, .cpp, .hpp, .c, .h, .cs, .rb, .java, .php, .swift, .kt, .kts)
+6. **Code Parsing**: Uses Tree-sitter to parse code and extract definitions through these steps:
+    - Parsing file content into an Abstract Syntax Tree (AST)
+    - Creating a query using a language-specific query string
+    - Sorting the captures by their position in the file
+7. **Result Formatting**: Outputs definitions with line numbers and actual source code
+
+## Output Format
+
+The output shows file paths followed by line numbers and the actual source code of each definition. For example:
+
+```
+src/utils.js:
+0--0 | export class HttpClient {
+5--5 | formatDate() {
+10--10 | function parseConfig(data) {
+
+src/models/User.js:
+0--0 | interface UserProfile {
+10--10 | export class User {
+20--20 | function createUser(data) {
+```
+
+Each line displays:
+
+- The start and end line numbers of the definition
+- The pipe symbol (|) as a separator
+- The actual source code of the definition
+
+This output format helps you quickly see both where definitions are located in the file and their implementation details.
+
+## Examples When Used
+
+- When starting a new task, Kilo Code first lists key code definitions to understand the overall structure of your project.
+- When planning refactoring work, Kilo Code uses this tool to identify classes and functions that might be affected.
+- When exploring unfamiliar codebases, Kilo Code maps the important code constructs before diving into implementation details.
+- When adding new features, Kilo Code identifies existing patterns and relevant code definitions to maintain consistency.
+- When troubleshooting bugs, Kilo Code maps the codebase structure to locate potential sources of the issue.
+- When planning architecture changes, Kilo Code identifies all affected components across files.
+
+## Usage Examples
+
+Listing code definitions in the current directory:
+
+```
+<list_code_definition_names>
+<path>.</path>
+</list_code_definition_names>
+```
+
+Examining a specific module's structure:
+
+```
+<list_code_definition_names>
+<path>src/components</path>
+</list_code_definition_names>
+```
+
+Exploring a utility library:
+
+```
+<list_code_definition_names>
+<path>lib/utils</path>
+</list_code_definition_names>
+```

apps/kilocode-docs/pages/automate/tools/list-files.md

@@ -0,0 +1,137 @@
+# list_files
+
+The `list_files` tool displays the files and directories within a specified location. It helps Kilo Code understand your project structure and navigate your codebase effectively.
+
+## Parameters
+
+The tool accepts these parameters:
+
+- `path` (required): The path of the directory to list contents for, relative to the current working directory
+- `recursive` (optional): Whether to list files recursively. Use `true` for recursive listing, `false` or omit for top-level only.
+
+## What It Does
+
+This tool lists all files and directories in a specified location, providing a clear overview of your project structure. It can either show just the top-level contents or recursively explore subdirectories.
+
+## When is it used?
+
+- When Kilo Code needs to understand your project structure
+- When Kilo Code explores what files are available before reading specific ones
+- When Kilo Code maps a codebase to better understand its organization
+- Before using more targeted tools like `read_file` or `search_files`
+- When Kilo Code needs to check for specific file types (like configuration files) across a project
+
+## Key Features
+
+- Lists both files and directories with directories clearly marked
+- Offers both recursive and non-recursive listing modes
+- Intelligently ignores common large directories like `node_modules` and `.git` in recursive mode
+- Respects `.gitignore` rules when in recursive mode
+- Marks files ignored by `.kilocodeignore` with a lock symbol (🔒) when `showKiloCodeIgnoredFiles` is enabled
+- Optimizes performance with level-by-level directory traversal
+- Sorts results to show directories before their contents, maintaining a logical hierarchy
+- Presents results in a clean, organized format
+- Automatically creates a mental map of your project structure
+
+## Limitations
+
+- File listing is capped at about 200 files by default to prevent performance issues
+- Has a 10-second timeout for directory traversal to prevent hanging on complex directory structures
+- When the file limit is hit, it adds a note suggesting to use `list_files` on specific subdirectories
+- Not designed for confirming the existence of files you've just created
+- May have reduced performance in very large directory structures
+- Cannot list files in root or home directories for security reasons
+
+## How It Works
+
+When the `list_files` tool is invoked, it follows this process:
+
+1. **Parameter Validation**: Validates the required `path` parameter and optional `recursive` parameter
+2. **Path Resolution**: Resolves the relative path to an absolute path
+3. **Security Checks**: Prevents listing files in sensitive locations like root or home directories
+4. **Directory Scanning**:
+    - For non-recursive mode: Lists only the top-level contents
+    - For recursive mode: Traverses the directory structure level by level with a 10-second timeout
+    - If timeout occurs, returns partial results collected up to that point
+5. **Result Filtering**:
+    - In recursive mode, skips common large directories like `node_modules`, `.git`, etc.
+    - Respects `.gitignore` rules when in recursive mode
+    - Handles `.kilocodeignore` patterns, either hiding files or marking them with a lock symbol
+6. **Formatting**:
+    - Marks directories with a trailing slash (`/`)
+    - Sorts results to show directories before their contents for logical hierarchy
+    - Marks ignored files with a lock symbol (🔒) when `showKiloCodeIgnored` is enabled
+    - Caps results at 200 files by default with a note about using subdirectories
+    - Organizes results for readability
+
+## File Listing Format
+
+The file listing results include:
+
+- Each file path is displayed on its own line
+- Directories are marked with a trailing slash (`/`)
+- Files ignored by `.kilocodeignore` are marked with a lock symbol (🔒) when `showKiloCodeIgnored` is enabled
+- Results are sorted logically with directories appearing before their contents
+- When the file limit is reached, a message appears suggesting to use `list_files` on specific subdirectories
+
+Example output format:
+
+```
+src/
+src/components/
+src/components/Button.tsx
+src/components/Header.tsx
+src/utils/
+src/utils/helpers.ts
+src/index.ts
+...
+File listing truncated (showing 200 of 543 files). Use list_files on specific subdirectories for more details.
+```
+
+When `.kilocodeignore` files are used and `showKiloCodeIgnored` is enabled:
+
+```
+src/
+src/components/
+src/components/Button.tsx
+src/components/Header.tsx
+🔒 src/secrets.json
+src/utils/
+src/utils/helpers.ts
+src/index.ts
+```
+
+## Examples When Used
+
+- When starting a new task, Kilo Code may list the project files to understand its structure before diving into specific code.
+- When asked to find specific types of files (like all JavaScript files), Kilo Code first lists directories to know where to look.
+- When providing recommendations for code organization, Kilo Code examines the current project structure first.
+- When setting up a new feature, Kilo Code lists related directories to understand the project conventions.
+
+## Usage Examples
+
+Listing top-level files in the current directory:
+
+```
+<list_files>
+<path>.</path>
+</list_files>
+```
+
+Recursively listing all files in a source directory:
+
+```
+<list_files>
+<path>src</path>
+<recursive>true</recursive>
+</list_files>
+```
+
+Examining a specific project subdirectory:
+
+```
+<list_files>
+<path>src/components</path>
+<recursive>false</recursive>
+</list_files>
+```

apps/kilocode-docs/pages/automate/tools/new-task.md

@@ -0,0 +1,110 @@
+# new_task
+
+The `new_task` tool creates subtasks with specialized modes while maintaining a parent-child relationship. It breaks down complex projects into manageable pieces, each operating in the mode best suited for specific work.
+
+## Parameters
+
+The tool accepts these parameters:
+
+- `mode` (required): The slug of the mode to start the new task in (e.g., "code", "ask", "architect")
+- `message` (required): The initial user message or instructions for this new task
+
+## What It Does
+
+This tool creates a new task instance with a specified starting mode and initial message. It allows complex workflows to be divided into subtasks with their own conversation history. Parent tasks are paused during subtask execution and resumed when the subtask completes, with results transferred back to the parent.
+
+## When is it used?
+
+- When breaking down complex projects into separate, focused subtasks
+- When different aspects of a task require different specialized modes
+- When different phases of work benefit from context separation
+- When organizing multi-phase development workflows
+
+## Key Features
+
+- Creates subtasks with their own conversation history and specialized mode
+- Pauses parent tasks for later resumption
+- Maintains hierarchical task relationships for navigation
+- Transfers results back to parent tasks upon completion
+- Supports workflow segregation for complex projects
+- Allows different parts of a project to use modes optimized for specific work
+- Requires explicit user approval for task creation
+- Provides clear task transition in the UI
+
+## Limitations
+
+- Cannot create tasks with modes that don't exist
+- Requires user approval before creating each new task
+- Task interface may become complex with deeply nested subtasks
+- Subtasks inherit certain workspace and extension configurations from parents
+- May require re-establishing context when switching between deeply nested tasks
+- Task completion needs explicit signaling to properly return to parent tasks
+
+## How It Works
+
+When the `new_task` tool is invoked, it follows this process:
+
+1. **Parameter Validation**:
+
+    - Validates the required `mode` and `message` parameters
+    - Verifies that the requested mode exists in the system
+
+2. **Task Stack Management**:
+
+    - Maintains a task stack that tracks all active and paused tasks
+    - Preserves the current mode for later resumption
+    - Sets the parent task to paused state
+
+3. **Task Context Management**:
+
+    - Creates a new task context with the provided message
+    - Assigns unique taskId and instanceId identifiers for state management
+    - Captures telemetry data on tool usage and task lifecycles
+
+4. **Mode Switching and Integration**:
+
+    - Switches to the specified mode with appropriate role and capabilities
+    - Initializes the new task with the provided message
+    - Integrates with VS Code's command palette and code actions
+
+5. **Task Completion and Result Transfer**:
+    - When subtask completes, result is passed back to parent task via `finishSubTask()`
+    - Parent task resumes in its original mode
+    - Task history and token usage metrics are updated
+    - The `taskCompleted` event is emitted with performance data
+
+## Examples When Used
+
+- When a front-end developer needs to architect a new feature, implement the code, and document it, they can create separate tasks for each phase with results flowing from one phase to the next.
+- When debugging an issue before implementing a fix, the debugging task can document findings that are passed to the implementation task.
+- When developing a full-stack application, database schema designs from an architect-mode task inform implementation details in a subsequent code-mode task.
+- When documenting a system after implementation, the documentation task can reference the completed implementation while using documentation-specific features.
+
+## Usage Examples
+
+Creating a new task in code mode:
+
+```
+<new_task>
+<mode>code</mode>
+<message>Implement a user authentication service with login, registration, and password reset functionality.</message>
+</new_task>
+```
+
+Creating a documentation task after completing implementation:
+
+```
+<new_task>
+<mode>docs</mode>
+<message>Create comprehensive API documentation for the authentication service we just built.</message>
+</new_task>
+```
+
+Breaking down a complex feature into architectural planning and implementation:
+
+```
+<new_task>
+<mode>architect</mode>
+<message>Design the database schema and system architecture for our new e-commerce platform.</message>
+</new_task>
+```

apps/kilocode-docs/pages/automate/tools/read-file.md

@@ -0,0 +1,195 @@
+# read_file
+
+The `read_file` tool examines the contents of files in a project. It allows Kilo Code to understand code, configuration files, and documentation to provide better assistance.
+
+## Parameters
+
+The tool accepts these parameters:
+
+- `path` (required): The path of the file to read relative to the current working directory
+- `start_line` (optional): The starting line number to read from (1-based indexing)
+- `end_line` (optional): The ending line number to read to (1-based, inclusive)
+- `auto_truncate` (optional): Whether to automatically truncate large files when line range isn't specified (true/false)
+
+## What It Does
+
+This tool reads the content of a specified file and returns it with line numbers for easy reference. It can read entire files or specific sections, and even extract text from PDFs and Word documents.
+
+## When is it used?
+
+- When Kilo Code needs to understand existing code structure
+- When Kilo Code needs to analyze configuration files
+- When Kilo Code needs to extract information from text files
+- When Kilo Code needs to see code before suggesting changes
+- When specific line numbers need to be referenced in discussions
+
+## Key Features
+
+- Displays file content with line numbers for easy reference
+- Can read specific portions of files by specifying line ranges
+- Extracts readable text from PDF and DOCX files
+- Intelligently truncates large files to focus on the most relevant sections
+- Provides method summaries with line ranges for large code files
+- Efficiently streams only requested line ranges for better performance
+- Makes it easy to discuss specific parts of code with line numbering
+
+## Limitations
+
+- May not handle extremely large files efficiently without using line range parameters
+- For binary files (except PDF and DOCX), may return content that isn't human-readable
+
+## How It Works
+
+When the `read_file` tool is invoked, it follows this process:
+
+1. **Parameter Validation**: Validates the required `path` parameter and optional parameters
+2. **Path Resolution**: Resolves the relative path to an absolute path
+3. **Reading Strategy Selection**:
+    - The tool uses a strict priority hierarchy (explained in detail below)
+    - It chooses between range reading, auto-truncation, or full file reading
+4. **Content Processing**:
+    - Adds line numbers to the content (e.g., "1 | const x = 13") where `1 |` is the line number.
+    - For truncated files, adds truncation notice and method definitions
+    - For special formats (PDF, DOCX, IPYNB), extracts readable text
+
+## Reading Strategy Priority
+
+The tool uses a clear decision hierarchy to determine how to read a file:
+
+1. **First Priority: Explicit Line Range**
+
+    - If either `start_line` or `end_line` is provided, the tool always performs a range read
+    - The implementation efficiently streams only the requested lines, making it suitable for processing large files
+    - This takes precedence over all other options
+
+2. **Second Priority: Auto-Truncation for Large Files**
+
+    - This only applies when ALL of these conditions are met:
+        - Neither `start_line` nor `end_line` is specified
+        - The `auto_truncate` parameter is set to `true`
+        - The file is not a binary file
+        - The file exceeds the configured line threshold (typically 500-1000 lines)
+    - When auto-truncation activates, the tool:
+        - Reads only the first portion of the file (determined by the maxReadFileLine setting)
+        - Adds a truncation notice showing the number of lines displayed vs. total
+        - Provides a summary of method definitions with their line ranges
+
+3. **Default Behavior: Read Entire File**
+    - If neither of the above conditions are met, it reads the entire file content
+    - For special formats like PDF, DOCX, and IPYNB, it uses specialized extractors
+
+## Examples When Used
+
+- When asked to explain or improve code, Kilo Code first reads the relevant files to understand the current implementation.
+- When troubleshooting configuration issues, Kilo Code reads config files to identify potential problems.
+- When working with documentation, Kilo Code reads existing docs to understand the current content before suggesting improvements.
+
+## Usage Examples
+
+Here are several scenarios demonstrating how the `read_file` tool is used and the typical output you might receive.
+
+### Reading an Entire File
+
+To read the complete content of a file:
+
+**Input:**
+
+```xml
+<read_file>
+<path>src/app.js</path>
+</read_file>
+```
+
+**Simulated Output (for a small file like `example_small.txt`):**
+
+```
+1 | This is the first line.
+2 | This is the second line.
+3 | This is the third line.
+```
+
+_(Output will vary based on the actual file content)_
+
+### Reading Specific Lines
+
+To read only a specific range of lines (e.g., 46-68):
+
+**Input:**
+
+```xml
+<read_file>
+<path>src/app.js</path>
+<start_line>46</start_line>
+<end_line>68</end_line>
+</read_file>
+```
+
+**Simulated Output (for lines 2-3 of `example_five_lines.txt`):**
+
+```
+2 | Content of line two.
+3 | Content of line three.
+```
+
+_(Output shows only the requested lines with their original line numbers)_
+
+### Reading a Large File (Auto-Truncation)
+
+When reading a large file without specifying lines and `auto_truncate` is enabled (or defaults to true based on settings):
+
+**Input:**
+
+```xml
+<read_file>
+<path>src/large-module.js</path>
+<auto_truncate>true</auto_truncate> <!-- Optional if default is true -->
+</read_file>
+```
+
+**Simulated Output (for `large_file.log` with 1500 lines, limit 1000):**
+
+```
+1 | Log entry 1...
+2 | Log entry 2...
+...
+1000 | Log entry 1000...
+[... truncated 500 lines ...]
+```
+
+_(Output is limited to the configured maximum lines, with a truncation notice)_
+
+### Attempting to Read a Non-Existent File
+
+If the specified file does not exist:
+
+**Input:**
+
+```xml
+<read_file>
+<path>non_existent_file.txt</path>
+</read_file>
+```
+
+**Simulated Output (Error):**
+
+```
+Error: File not found at path 'non_existent_file.txt'.
+```
+
+### Attempting to Read a Blocked File
+
+If the file is excluded by rules in a `.kilocodeignore` file:
+
+**Input:**
+
+```xml
+<read_file>
+<path>.env</path>
+</read_file>
+```
+
+**Simulated Output (Error):**
+
+```
+Error: Access denied to file '.env' due to .kilocodeignore rules.
+```

apps/kilocode-docs/pages/automate/tools/search-files.md

@@ -0,0 +1,131 @@
+# search_files
+
+The `search_files` tool performs regex searches across multiple files in your project. It helps Kilo Code locate specific code patterns, text, or other content throughout your codebase with contextual results.
+
+## Parameters
+
+The tool accepts these parameters:
+
+- `path` (required): The path of the directory to search in, relative to the current working directory
+- `regex` (required): The regular expression pattern to search for (uses Rust regex syntax)
+- `file_pattern` (optional): Glob pattern to filter files (e.g., '\*.ts' for TypeScript files)
+
+## What It Does
+
+This tool searches across files in a specified directory using regular expressions, showing each match with surrounding context. It's like having a powerful "Find in Files" feature that works across the entire project structure.
+
+## When is it used?
+
+- When Kilo Code needs to find where specific functions or variables are used
+- When Kilo Code helps with refactoring and needs to understand usage patterns
+- When Kilo Code needs to locate all instances of a particular code pattern
+- When Kilo Code searches for text across multiple files with filtering capabilities
+
+## Key Features
+
+- Searches across multiple files in a single operation using high-performance Ripgrep
+- Shows context around each match (1 line before and after)
+- Filters files by type using glob patterns (e.g., only TypeScript files)
+- Provides line numbers for easy reference
+- Uses powerful regex patterns for precise searches
+- Automatically limits output to 300 results with notification
+- Truncates lines longer than 500 characters with "[truncated...]" marker
+- Intelligently combines nearby matches into single blocks for readability
+
+## Limitations
+
+- Works best with text-based files (not effective for binary files like images)
+- Performance may slow with extremely large codebases
+- Uses Rust regex syntax, which may differ slightly from other regex implementations
+- Cannot search within compressed files or archives
+- Default context size is fixed (1 line before and after)
+- May display varying context sizes when matches are close together due to result grouping
+
+## How It Works
+
+When the `search_files` tool is invoked, it follows this process:
+
+1. **Parameter Validation**: Validates the required `path` and `regex` parameters
+2. **Path Resolution**: Resolves the relative path to an absolute path
+3. **Search Execution**:
+    - Uses Ripgrep (rg) for high-performance text searching
+    - Applies file pattern filtering if specified
+    - Collects matches with surrounding context
+4. **Result Formatting**:
+    - Formats results with file paths, line numbers, and context
+    - Displays 1 line of context before and after each match
+    - Structures output for easy readability
+    - Limits results to a maximum of 300 matches with notification
+    - Truncates lines longer than 500 characters
+    - Merges nearby matches into contiguous blocks
+
+## Search Results Format
+
+The search results include:
+
+- Relative file paths for each matching file (prefixed with #)
+- Context lines before and after each match (1 line by default)
+- Line numbers padded to 3 spaces followed by `|` and the line content
+- A separator line (----) after each match group
+
+Example output format:
+
+```
+# rel/path/to/app.ts
+ 11 |   // Some processing logic here
+ 12 |   // TODO: Implement error handling
+ 13 |   return processedData;
+----
+
+# Showing first 300 of 300+ results. Use a more specific search if necessary.
+```
+
+When matches occur close to each other, they're merged into a single block rather than shown as separate results:
+
+```
+# rel/path/to/auth.ts
+ 13 | // Some code here
+ 14 | // TODO: Add proper validation
+ 15 | function validateUser(credentials) {
+ 16 |   // TODO: Implement rate limiting
+ 17 |   return checkDatabase(credentials);
+----
+```
+
+## Examples When Used
+
+- When asked to refactor a function, Kilo Code first searches for all places the function is used to ensure comprehensive changes.
+- When investigating bugs, Kilo Code searches for similar patterns to identify related issues across the codebase.
+- When addressing technical debt, Kilo Code locates all TODO comments across the project.
+- When analyzing dependencies, Kilo Code finds all imports of a particular module.
+
+## Usage Examples
+
+Searching for TODO comments in all JavaScript files:
+
+```
+<search_files>
+<path>src</path>
+<regex>TODO|FIXME</regex>
+<file_pattern>*.js</file_pattern>
+</search_files>
+```
+
+Finding all usages of a specific function:
+
+```
+<search_files>
+<path>.</path>
+<regex>function\s+calculateTotal</regex>
+<file_pattern>*.{js,ts}</file_pattern>
+</search_files>
+```
+
+Searching for a specific import pattern across the entire project:
+
+```
+<search_files>
+<path>.</path>
+<regex>import\s+.*\s+from\s+['"]@components/</regex>
+</search_files>
+```

apps/kilocode-docs/pages/automate/tools/switch-mode.md

@@ -0,0 +1,158 @@
+# switch_mode
+
+The `switch_mode` tool enables Kilo Code to change between different operational modes, each with specialized capabilities for specific types of tasks. This allows seamless transitions between modes like Code, Architect, Ask, or Debug when the current task requires different expertise.
+
+## Parameters
+
+The tool accepts these parameters:
+
+- `mode_slug` (required): The slug of the mode to switch to (e.g., "code", "ask", "architect")
+- `reason` (optional): The reason for switching modes, providing context for the user
+
+## What It Does
+
+This tool requests a mode change when the current task would be better handled by another mode's capabilities. It maintains context while shifting Kilo Code's focus and available toolsets to match the requirements of the new task phase.
+
+## When is it used?
+
+- When transitioning from information gathering to code implementation
+- When shifting from coding to architecture or design
+- When the current task requires capabilities only available in a different mode
+- When specialized expertise is needed for a particular phase of a complex project
+
+## Key Features
+
+- Maintains context continuity across mode transitions
+- Provides clear reasoning for mode switch recommendations
+- Requires user approval for all mode changes
+- Enforces tool group restrictions specific to each mode
+- Seamlessly adapts tool availability based on the selected mode
+- Works with both standard and custom modes
+- Displays the mode switch and reasoning in the UI
+- Uses XML-style formatting for parameter specification
+- Handles file type restrictions specific to certain modes
+
+## Limitations
+
+- Cannot switch to modes that don't exist in the system
+- Requires explicit user approval for each mode transition
+- Cannot use tools specific to a mode until the switch is complete
+- Applies a 500ms delay after mode switching to allow the change to take effect
+- Some modes have file type restrictions (e.g., Architect mode can only edit markdown files)
+- Mode preservation for resumption applies only to the `new_task` functionality, not general mode switching
+
+## How It Works
+
+When the `switch_mode` tool is invoked, it follows this process:
+
+1. **Request Validation**:
+
+    - Validates that the requested mode exists in the system
+    - Checks that the `mode_slug` parameter is provided and valid
+    - Verifies the user isn't already in the requested mode
+    - Ensures the `reason` parameter (if provided) is properly formatted
+
+2. **Mode Transition Preparation**:
+
+    - Packages the mode change request with the provided reason
+    - Presents the change request to the user for approval
+
+3. **Mode Activation (Upon User Approval)**:
+
+    - Updates the UI to reflect the new mode
+    - Adjusts available tools based on the mode's tool group configuration
+    - Applies the mode-specific prompt and behavior
+    - Applies a 500ms delay to allow the change to take effect before executing next tool
+    - Enforces any file restrictions specific to the mode
+
+4. **Continuation**:
+    - Proceeds with the task using the capabilities of the new mode
+    - Retains relevant context from the previous interaction
+
+## Tool Group Association
+
+The `switch_mode` tool belongs to the "modes" tool group but is also included in the "always available" tools list. This means:
+
+- It can be used in any mode regardless of the mode's configured tool groups
+- It's available alongside other core tools like `ask_followup_question` and `attempt_completion`
+- It allows mode transitions at any point in a workflow when task requirements change
+
+## Mode Structure
+
+Each mode in the system has a specific structure:
+
+- `slug`: Unique identifier for the mode (e.g., "code", "ask")
+- `name`: Display name for the mode (e.g., "Code", "Ask")
+- `roleDefinition`: The specialized role and capabilities of the mode
+- `customInstructions`: Optional mode-specific instructions that guide behavior
+- `groups`: Tool groups available to the mode with optional restrictions
+
+## Mode Capabilities
+
+The core modes provide these specialized capabilities:
+
+- **Code Mode**: Focused on coding tasks with full access to code editing tools
+- **Architect Mode**: Specialized for system design and architecture planning, limited to editing markdown files only
+- **Ask Mode**: Optimized for answering questions and providing information
+- **Debug Mode**: Equipped for systematic problem diagnosis and resolution
+
+## Custom Modes
+
+Beyond the core modes, the system supports custom project-specific modes:
+
+- Custom modes can be defined with specific tool groups enabled
+- They can specify custom role definitions and instructions
+- The system checks custom modes first before falling back to core modes
+- Custom mode definitions take precedence over core modes with the same slug
+
+## File Restrictions
+
+Different modes may have specific file type restrictions:
+
+- **Architect Mode**: Can only edit files matching the `.md` extension
+- Attempting to edit restricted file types results in a `FileRestrictionError`
+- These restrictions help enforce proper separation of concerns between modes
+
+## Examples When Used
+
+- When discussing a new feature, Kilo Code switches from Ask mode to Architect mode to help design the system structure.
+- After completing architecture planning in Architect mode, Kilo Code switches to Code mode to implement the designed features.
+- When encountering bugs during development, Kilo Code switches from Code mode to Debug mode for systematic troubleshooting.
+
+## Usage Examples
+
+Switching to Code mode for implementation:
+
+```
+<switch_mode>
+<mode_slug>code</mode_slug>
+<reason>Need to implement the login functionality based on the architecture we've discussed</reason>
+</switch_mode>
+```
+
+Switching to Architect mode for design:
+
+```
+<switch_mode>
+<mode_slug>architect</mode_slug>
+<reason>Need to design the system architecture before implementation</reason>
+</switch_mode>
+```
+
+Switching to Debug mode for troubleshooting:
+
+```
+<switch_mode>
+<mode_slug>debug</mode_slug>
+<reason>Need to systematically diagnose the authentication error</reason>
+</switch_mode>
+```
+
+Switching to Ask mode for information:
+
+```
+<switch_mode>
+<mode_slug>ask</mode_slug>
+<reason>Need to answer questions about the implemented feature</reason>
+</switch_mode>
+```

apps/kilocode-docs/pages/automate/tools/update-todo-list.md

@@ -0,0 +1,168 @@
+# update_todo_list
+
+The `update_todo_list` tool replaces the entire TODO list with an updated checklist reflecting the current state. It provides step-by-step task tracking, allowing confirmation of completion before updating and dynamic addition of new todos discovered during complex tasks.
+
+## Parameters
+
+The tool accepts these parameters:
+
+- `todos` (required): A markdown checklist with task descriptions and status indicators
+
+## What It Does
+
+This tool manages a comprehensive TODO list that tracks task progress through different status states. It replaces the entire list with each update, ensuring the current state accurately reflects all pending, in-progress, and completed tasks. The system displays the TODO list as reminders in subsequent messages.
+
+## When is it used?
+
+- When tasks involve multiple steps requiring systematic tracking
+- When new actionable items are discovered during task execution
+- When updating the status of several todos simultaneously
+- When complex projects benefit from clear, stepwise progress tracking
+- When organizing multi-phase workflows with dependencies
+
+## Key Features
+
+- Maintains a single-level markdown checklist with three status states
+- Updates multiple task statuses in a single operation
+- Dynamically adds new todos as they're discovered during execution
+- Provides visual progress tracking through status indicators
+- Integrates with the reminder system for persistent task visibility
+- Supports task reordering based on execution priority
+- Preserves all unfinished tasks unless explicitly removed
+- Enables efficient batch status updates
+
+## Limitations
+
+- Limited to single-level checklists (no nesting or subtasks)
+- Cannot remove tasks unless they're completed or no longer relevant
+- Requires complete list replacement rather than incremental updates
+- Status changes must be explicitly managed through tool calls
+- No built-in task dependency tracking
+- Cannot schedule tasks for future execution
+- Limited to three status states (pending, in-progress, completed)
+
+## Status Indicators
+
+The tool uses three distinct status indicators:
+
+- `[ ]` **Pending**: Task not yet started
+- `[-]` **In Progress**: Task currently being worked on
+- `[x]` **Completed**: Task fully finished with no unresolved issues
+
+## How It Works
+
+When the `update_todo_list` tool is invoked, it follows this process:
+
+1. **Status Validation**:
+
+    - Parses the markdown checklist format
+    - Validates status indicators are properly formatted
+    - Ensures task descriptions are clear and actionable
+
+2. **List Replacement**:
+
+    - Completely replaces the existing TODO list
+    - Preserves task order as specified in the update
+    - Maintains task descriptions and status states
+
+3. **Reminder Integration**:
+
+    - Integrates updated list with the reminder system
+    - Displays current tasks in subsequent message headers
+    - Provides persistent visibility of task progress
+
+4. **Progress Tracking**:
+    - Tracks completion status across multiple updates
+    - Maintains task history for reference
+    - Supports workflow continuation across sessions
+
+## Best Practices
+
+### Task Management Guidelines
+
+- Mark tasks as completed immediately after all work is finished
+- Start the next task by marking it as in-progress
+- Add new todos as soon as they are identified during execution
+- Use clear, descriptive task names that indicate specific actions
+- Order tasks by logical execution sequence or priority
+
+### Status Update Patterns
+
+- Update multiple statuses simultaneously when transitioning between tasks
+- Confirm task completion before marking as finished
+- Keep in-progress tasks focused on current work
+- Add blocking tasks when dependencies are discovered
+
+### When to Use
+
+Use this tool when:
+
+- The task involves multiple steps or requires ongoing tracking
+- New actionable items are discovered during task execution
+- Multiple todos need status updates simultaneously
+- Complex tasks benefit from clear progress visualization
+
+Avoid using when:
+
+- There is only a single, trivial task
+- The task can be completed in one or two simple steps
+- The request is purely conversational or informational
+
+## Examples When Used
+
+- When implementing a multi-component feature requiring frontend, backend, and database changes
+- When debugging issues that reveal multiple related problems requiring fixes
+- When setting up development environments with multiple configuration steps
+- When documenting systems that require research, writing, and review phases
+- When refactoring code that affects multiple files and requires testing
+
+## Usage Examples
+
+Initial task breakdown:
+
+```
+<update_todo_list>
+<todos>
+[-] Analyze requirements and create technical specification
+[ ] Design database schema and API endpoints
+[ ] Implement backend authentication service
+[ ] Create frontend login components
+[ ] Write comprehensive tests
+[ ] Update documentation
+</todos>
+</update_todo_list>
+```
+
+Updating progress and adding discovered tasks:
+
+```
+<update_todo_list>
+<todos>
+[x] Analyze requirements and create technical specification
+[x] Design database schema and API endpoints
+[-] Implement backend authentication service
+[ ] Create frontend login components
+[ ] Write comprehensive tests
+[ ] Update documentation
+[ ] Add password reset functionality
+[ ] Implement rate limiting for login attempts
+</todos>
+</update_todo_list>
+```
+
+Completing multiple tasks and transitioning focus:
+
+```
+<update_todo_list>
+<todos>
+[x] Analyze requirements and create technical specification
+[x] Design database schema and API endpoints
+[x] Implement backend authentication service
+[x] Create frontend login components
+[-] Write comprehensive tests
+[ ] Update documentation
+[ ] Add password reset functionality
+[ ] Implement rate limiting for login attempts
+</todos>
+</update_todo_list>
+```

apps/kilocode-docs/pages/automate/tools/use-mcp-tool.md

@@ -0,0 +1,196 @@
+# use_mcp_tool
+
+The `use_mcp_tool` tool enables interaction with external tools provided by connected Model Context Protocol (MCP) servers. It extends Kilo Code's capabilities with domain-specific functionality through a standardized protocol.
+
+## Parameters
+
+The tool accepts these parameters:
+
+- `server_name` (required): The name of the MCP server providing the tool
+- `tool_name` (required): The name of the tool to execute
+- `arguments` (required/optional): A JSON object containing the tool's input parameters, following the tool's input schema. May be optional for tools that require no input.
+
+## What It Does
+
+This tool allows Kilo Code to access specialized functionality provided by external MCP servers. Each MCP server can offer multiple tools with unique capabilities, extending Kilo Code beyond its built-in functionality. The system validates arguments against schemas, manages server connections, and processes responses of various content types (text, image, resource).
+
+## When is it used?
+
+- When specialized functionality not available in core tools is needed
+- When domain-specific operations are required
+- When integration with external systems or services is needed
+- When working with data that requires specific processing or analysis
+- When accessing proprietary tools through a standardized interface
+
+## Key Features
+
+- Uses the standardized MCP protocol via the `@modelcontextprotocol/sdk` library
+- Supports multiple transport mechanisms (StdioClientTransport and SSEClientTransport)
+- Validates arguments using Zod schema validation on both client and server sides
+- Processes multiple response content types: text, image, and resource references
+- Manages server lifecycle with automatic restarts when server code changes
+- Provides an "always allow" mechanism to bypass approval for trusted tools
+- Works with the companion `access_mcp_resource` tool for resource retrieval
+- Maintains proper error tracking and handling for failed operations
+- Supports configurable timeouts (1-3600 seconds, default: 60 seconds)
+- Allows file watchers to automatically detect and reload server changes
+
+## Limitations
+
+- Depends on external MCP servers being available and connected
+- Limited to the tools provided by connected servers
+- Tool capabilities vary between different MCP servers
+- Network issues can affect reliability and performance
+- Requires user approval before execution (unless in the "always allow" list)
+- Cannot execute multiple MCP tool operations simultaneously
+
+## Server Configuration
+
+MCP servers can be configured globally or at the project level:
+
+- **Global Configuration**: Managed through the Kilo Code extension settings in VS Code. These apply across all projects unless overridden.
+- **Project-level Configuration**: Defined in a `.kilocode/mcp.json` file within your project's root directory.
+- This allows project-specific server setups.
+- Project-level servers take precedence over global servers if they share the same name.
+- Since `.kilocode/mcp.json` can be committed to version control, it simplifies sharing configurations with your team.
+
+## How It Works
+
+When the `use_mcp_tool` tool is invoked, it follows this process:
+
+1. **Initialization and Validation**:
+
+    - The system verifies that the MCP hub is available
+    - Confirms the specified server exists and is connected
+    - Validates the requested tool exists on the server
+    - Arguments are validated against the tool's schema definition
+    - Timeout settings are extracted from server configuration (default: 60 seconds)
+
+2. **Execution and Communication**:
+
+    - The system selects the appropriate transport mechanism:
+        - `StdioClientTransport`: For communicating with local processes via standard I/O
+        - `SSEClientTransport`: For communicating with HTTP servers via Server-Sent Events
+    - A request is sent with validated server name, tool name, and arguments
+    - Communication uses the `@modelcontextprotocol/sdk` library for standardized interactions
+    - Request execution is tracked with timeout handling to prevent hanging operations
+
+3. **Response Processing**:
+
+    - Responses can include multiple content types:
+        - Text content: Plain text responses
+        - Image content: Binary image data with MIME type information
+        - Resource references: URIs to access server resources (works with `access_mcp_resource`)
+    - The system checks the `isError` flag to determine if error handling is needed
+    - Results are formatted for display in the Kilo Code interface
+
+4. **Resource and Error Handling**:
+    - The system uses WeakRef patterns to prevent memory leaks
+    - A consecutive mistake counter tracks and manages errors
+    - File watchers monitor for server code changes and trigger automatic restarts
+    - The security model requires approval for tool execution unless in the "always allow" list
+
+## Security and Permissions
+
+The MCP architecture provides several security features:
+
+- Users must approve tool usage before execution (by default)
+- Specific tools can be marked for automatic approval in the "always allow" list
+- Server configurations are validated with Zod schemas for integrity
+- Configurable timeouts prevent hanging operations (1-3600 seconds)
+- Server connections can be enabled or disabled through the UI
+
+## Examples When Used
+
+- Analyzing specialized data formats using server-side processing tools
+- Generating images or other media through AI models hosted on external servers
+- Executing complex domain-specific calculations without local implementation
+- Accessing proprietary APIs or services through a controlled interface
+- Retrieving data from specialized databases or data sources
+
+## Usage Examples
+
+Requesting weather forecast data with text response:
+
+```
+<use_mcp_tool>
+<server_name>weather-server</server_name>
+<tool_name>get_forecast</tool_name>
+<arguments>
+{
+  "city": "San Francisco",
+  "days": 5,
+  "format": "text"
+}
+</arguments>
+</use_mcp_tool>
+```
+
+Analyzing source code with a specialized tool that returns JSON:
+
+```
+<use_mcp_tool>
+<server_name>code-analysis</server_name>
+<tool_name>complexity_metrics</tool_name>
+<arguments>
+{
+  "language": "typescript",
+  "file_path": "src/app.ts",
+  "include_functions": true,
+  "metrics": ["cyclomatic", "cognitive"]
+}
+</arguments>
+</use_mcp_tool>
+```
+
+Generating an image with specific parameters:
+
+```
+<use_mcp_tool>
+<server_name>image-generation</server_name>
+<tool_name>create_image</tool_name>
+<arguments>
+{
+  "prompt": "A futuristic city with flying cars",
+  "style": "photorealistic",
+  "dimensions": {
+    "width": 1024,
+    "height": 768
+  },
+  "format": "webp"
+}
+</arguments>
+</use_mcp_tool>
+```
+
+Accessing a resource through a tool that returns a resource reference:
+
+```
+<use_mcp_tool>
+<server_name>database-connector</server_name>
+<tool_name>query_and_store</tool_name>
+<arguments>
+{
+  "database": "users",
+  "type": "select",
+  "fields": ["name", "email", "last_login"],
+  "where": {
+    "status": "active"
+  },
+  "store_as": "active_users"
+}
+</arguments>
+</use_mcp_tool>
+```
+
+Tool with no required arguments:
+
+```
+<use_mcp_tool>
+<server_name>system-monitor</server_name>
+<tool_name>get_current_status</tool_name>
+<arguments>
+{}
+</arguments>
+</use_mcp_tool>
+```

apps/kilocode-docs/pages/automate/tools/write-to-file.md

@@ -0,0 +1,177 @@
+# write_to_file
+
+The `write_to_file` tool creates new files or completely replaces existing file content with an interactive approval process. It provides a diff view for reviewing changes before they're applied.
+
+## Parameters
+
+The tool accepts these parameters:
+
+- `path` (required): The path of the file to write to, relative to the current working directory
+- `content` (required): The complete content to write to the file
+- `line_count` (required): The number of lines in the file, including empty lines
+
+## What It Does
+
+This tool writes content to a specified file, either creating a new file if it doesn't exist or completely overwriting an existing file. All changes require explicit user approval through a diff view interface, where users can review and even edit the proposed changes before they're applied.
+
+## When is it used?
+
+- When Kilo Code needs to create a new file from scratch
+- When Kilo Code needs to completely rewrite an existing file
+- When creating multiple files for a new project
+- When generating configuration files, documentation, or source code
+- When you need to review changes before they're applied
+
+## Key Features
+
+- Interactive Approval: Shows changes in a diff view requiring explicit approval before applying
+- User Edit Support: Allows editing the proposed content before final approval
+- Safety Measures: Detects code omission, validates paths, and prevents truncated content
+- Editor Integration: Opens a diff view that scrolls to the first difference automatically
+- Content Preprocessing: Handles artifacts from different AI models to ensure clean content
+- Access Control: Validates against `.kilocodeignore` restrictions before making changes
+- Parent Directories: May handle directory creation through system dependencies
+- Complete Replacement: Provides a fully transformed file in a single operation
+
+## Limitations
+
+- Not suitable for existing files: Much slower and less efficient than `apply_diff` for modifying existing files
+- Performance with large files: Operation becomes significantly slower with larger files
+- Complete overwrite: Replaces entire file content, cannot preserve original content
+- Line count required: Needs accurate line count to detect potential content truncation
+- Review overhead: The approval process adds extra steps compared to direct edits
+- Interactive only: Cannot be used in automated workflows that require non-interactive execution
+
+## How It Works
+
+When the `write_to_file` tool is invoked, it follows this process:
+
+1. **Parameter Validation**: Validates the required parameters and permissions
+
+    - Checks that `path`, `content`, and `line_count` are provided
+    - Validates the file is allowed (not restricted by `.kilocodeignore`)
+    - Ensures the path is within the workspace boundaries
+    - Tracks consecutive mistake counts for missing parameters
+    - Shows specific error messages for each validation failure
+
+2. **Content Preprocessing**:
+
+    - Removes code block markers that might be added by AI models
+    - Handles escaped HTML entities (specifically for non-Claude models)
+    - Strips line numbers if accidentally included in content
+    - Performs model-specific processing for different AI providers
+
+3. **Diff View Generation**:
+
+    - Opens a diff view in the editor showing the proposed changes
+    - Adds a 300ms delay to ensure UI responsiveness
+    - Scrolls automatically to the first difference
+    - Highlights changes for easy review
+
+4. **User Approval Process**:
+
+    - Waits for explicit user approval to proceed
+    - Allows users to edit the content in the diff view
+    - Captures any user edits for the final content
+    - Provides option to reject changes entirely
+    - Detects and incorporates user modifications into the final result
+
+5. **Safety Validation**:
+
+    - Detects potential content truncation by comparing with provided line count
+    - Shows warnings if content appears incomplete
+    - Validates file path and access permissions
+    - Specifically checks if files are outside the workspace with `isOutsideWorkspace` flag
+
+6. **File Writing**:
+    - Writes the approved content (with any user edits) to the file
+    - Provides confirmation of successful write
+    - Resets the consecutive mistakes counter on success
+
+## Examples When Used
+
+- When creating a new project, Kilo Code generates multiple files but lets you review each before committing changes.
+- When setting up configuration files, Kilo Code shows the proposed configuration in a diff view for approval.
+- When generating documentation, Kilo Code creates markdown files but lets you make final adjustments in the diff view.
+- When developing a prototype, Kilo Code shows complete source files in a diff view where you can fine-tune before saving.
+
+## Usage Examples
+
+Creating a new JSON configuration file:
+
+```
+<write_to_file>
+<path>config/settings.json</path>
+<content>
+{
+  "apiEndpoint": "https://api.example.com",
+  "theme": {
+    "primaryColor": "#007bff",
+    "secondaryColor": "#6c757d",
+    "fontFamily": "Arial, sans-serif"
+  },
+  "features": {
+    "darkMode": true,
+    "notifications": true,
+    "analytics": false
+  },
+  "version": "1.0.0"
+}
+</content>
+<line_count>14</line_count>
+</write_to_file>
+```
+
+Creating a simple HTML file:
+
+```
+<write_to_file>
+<path>src/index.html</path>
+<content>
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>My Application</title>
+  <link rel="stylesheet" href="styles.css">
+</head>
+<body>
+  <div id="app"></div>
+  <script src="app.js"></script>
+</body>
+</html>
+</content>
+<line_count>13</line_count>
+</write_to_file>
+```
+
+Creating a JavaScript module:
+
+```
+<write_to_file>
+<path>src/utils/helpers.js</path>
+<content>
+/**
+ * Utility functions for the application
+ */
+
+export function formatDate(date) {
+  return new Date(date).toLocaleDateString();
+}
+
+export function calculateTotal(items) {
+  return items.reduce((sum, item) => sum + item.price, 0);
+}
+
+export function debounce(func, delay) {
+  let timeout;
+  return function(...args) {
+    clearTimeout(timeout);
+    timeout = setTimeout(() => func.apply(this, args), delay);
+  };
+}
+</content>
+<line_count>18</line_count>
+</write_to_file>
+```

apps/kilocode-docs/previous-docs-redirects.js

@@ -586,7 +586,7 @@ module.exports = [
 	},
 	{
 		source: "/basic-usage/how-tools-work",
-		destination: "/docs/code-with-ai",
+		destination: "/docs/automate/how-tools-work",
 		basePath: false,
 		permanent: true,
 	},
@@ -620,4 +620,110 @@ module.exports = [
 		basePath: false,
 		permanent: true,
 	},
+
+	// ============================================
+	// AUTOMATE - Tools Reference
+	// ============================================
+	{
+		source: "/features/tools/tool-use-overview",
+		destination: "/docs/automate/tools",
+		basePath: false,
+		permanent: true,
+	},
+	{
+		source: "/features/tools/access-mcp-resource",
+		destination: "/docs/automate/tools/access-mcp-resource",
+		basePath: false,
+		permanent: true,
+	},
+	{
+		source: "/features/tools/apply-diff",
+		destination: "/docs/automate/tools/apply-diff",
+		basePath: false,
+		permanent: true,
+	},
+	{
+		source: "/features/tools/ask-followup-question",
+		destination: "/docs/automate/tools/ask-followup-question",
+		basePath: false,
+		permanent: true,
+	},
+	{
+		source: "/features/tools/attempt-completion",
+		destination: "/docs/automate/tools/attempt-completion",
+		basePath: false,
+		permanent: true,
+	},
+	{
+		source: "/features/tools/browser-action",
+		destination: "/docs/automate/tools/browser-action",
+		basePath: false,
+		permanent: true,
+	},
+	{
+		source: "/features/tools/delete-file",
+		destination: "/docs/automate/tools/delete-file",
+		basePath: false,
+		permanent: true,
+	},
+	{
+		source: "/features/tools/execute-command",
+		destination: "/docs/automate/tools/execute-command",
+		basePath: false,
+		permanent: true,
+	},
+	{
+		source: "/features/tools/list-code-definition-names",
+		destination: "/docs/automate/tools/list-code-definition-names",
+		basePath: false,
+		permanent: true,
+	},
+	{
+		source: "/features/tools/list-files",
+		destination: "/docs/automate/tools/list-files",
+		basePath: false,
+		permanent: true,
+	},
+	{
+		source: "/features/tools/new-task",
+		destination: "/docs/automate/tools/new-task",
+		basePath: false,
+		permanent: true,
+	},
+	{
+		source: "/features/tools/read-file",
+		destination: "/docs/automate/tools/read-file",
+		basePath: false,
+		permanent: true,
+	},
+	{
+		source: "/features/tools/search-files",
+		destination: "/docs/automate/tools/search-files",
+		basePath: false,
+		permanent: true,
+	},
+	{
+		source: "/features/tools/switch-mode",
+		destination: "/docs/automate/tools/switch-mode",
+		basePath: false,
+		permanent: true,
+	},
+	{
+		source: "/features/tools/update-todo-list",
+		destination: "/docs/automate/tools/update-todo-list",
+		basePath: false,
+		permanent: true,
+	},
+	{
+		source: "/features/tools/use-mcp-tool",
+		destination: "/docs/automate/tools/use-mcp-tool",
+		basePath: false,
+		permanent: true,
+	},
+	{
+		source: "/features/tools/write-to-file",
+		destination: "/docs/automate/tools/write-to-file",
+		basePath: false,
+		permanent: true,
+	},
 ]

apps/kilocode-docs/public/globals.css

@@ -270,10 +270,6 @@ a:hover {
 
 /* Mobile Responsive Styles */
 @media (max-width: 1024px) {
-	:root {
-		--top-nav-height: 60px;
-	}
-
 	/* Hide table of contents on tablet and below */
 	.toc-container {
 		display: none;