Add 'apps/kilocode-docs/' from commit '79ed21f1913d5d8426c39e7ecf19907a1a2913e1'

git-subtree-dir: apps/kilocode-docs
git-subtree-mainline: 0ab87945123cba85a6e76ca5a7f427197b7e1f77
git-subtree-split: 79ed21f1913d5d8426c39e7ecf19907a1a2913e1

apps/kilocode-docs/.env.example

@@ -0,0 +1,2 @@
+POSTHOG_API_KEY=your_posthog_api_key
+FREE_TIER_AMOUNT=$7

apps/kilocode-docs/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# These owners will be the default owners for everything in the repo
+* @mrubens @cte @hannesrudolph

apps/kilocode-docs/.github/workflows/docusaurus-build.yml

@@ -0,0 +1,32 @@
+name: Docusaurus Build Check
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build Docusaurus Site
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+      
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+        cache: 'npm'
+        
+    - name: Install dependencies
+      run: npm ci
+      
+    - name: Build site
+      run: npm run build
+      env:
+        POSTHOG_API_KEY: ${{ secrets.POSTHOG_API_KEY }}

apps/kilocode-docs/.gitignore

@@ -0,0 +1,31 @@
+.release-notes/
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+*.js
+!src/**/*.js
+
+# Misc
+.DS_Store
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+.npmrc
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+.devcontainer
+TEMP/
+
+.history/
+.vercel

apps/kilocode-docs/.kilocode/rules/memory-bank-instructions.md

@@ -0,0 +1,168 @@
+# Memory Bank
+
+I am an expert software engineer with a unique characteristic: my memory resets completely between sessions. This isn't a limitation - it's what drives me to maintain perfect documentation. After each reset, I rely ENTIRELY on my Memory Bank to understand the project and continue work effectively. I MUST read ALL memory bank files at the start of EVERY task - this is not optional. The memory bank files are located in `.kilocode/rules/memory-bank` folder.
+
+When I start a task, I will include `[Memory Bank: Active]` at the beginning of my response if I successfully read the memory bank files, or `[Memory Bank: Missing]` if the folder doesn't exist or is empty. If memory bank is missing, I will warn the user about potential issues and suggest initialization.
+
+## Memory Bank Structure
+
+The Memory Bank consists of core files and optional context files, all in Markdown format.
+
+### Core Files (Required)
+1. `brief.md`
+   This file is created and maintained manually by the developer. Don't edit this file directly but suggest to user to update it if it can be improved.
+   - Foundation document that shapes all other files
+   - Created at project start if it doesn't exist
+   - Defines core requirements and goals
+   - Source of truth for project scope
+
+2. `product.md`
+   - Why this project exists
+   - Problems it solves
+   - How it should work
+   - User experience goals
+
+3. `context.md`
+   This file should be short and factual, not creative or speculative.
+   - Current work focus
+   - Recent changes
+   - Next steps
+
+4. `architecture.md`
+   - System architecture
+   - Source Code paths
+   - Key technical decisions
+   - Design patterns in use
+   - Component relationships
+   - Critical implementation paths
+
+5. `tech.md`
+   - Technologies used
+   - Development setup
+   - Technical constraints
+   - Dependencies
+   - Tool usage patterns
+
+### Additional Files
+Create additional files/folders within memory-bank/ when they help organize:
+- `tasks.md` - Documentation of repetitive tasks and their workflows
+- `todos.md` - List of currently active TODOs and missing documentation items. When items are completed, they should be removed from the list
+- Complex feature documentation
+- Integration specifications
+- API documentation
+- Testing strategies
+- Deployment procedures
+
+## Core workflows
+
+### Memory Bank Initialization
+
+The initialization step is CRITICALLY IMPORTANT and must be done with extreme thoroughness as it defines all future effectiveness of the Memory Bank. This is the foundation upon which all future interactions will be built.
+
+When user requests initialization of the memory bank (command `initialize memory bank`), I'll perform an exhaustive analysis of the project, including:
+- All source code files and their relationships
+- Configuration files and build system setup
+- Project structure and organization patterns
+- Documentation and comments
+- Dependencies and external integrations
+- Testing frameworks and patterns
+
+I must be extremely thorough during initialization, spending extra time and effort to build a comprehensive understanding of the project. A high-quality initialization will dramatically improve all future interactions, while a rushed or incomplete initialization will permanently limit my effectiveness.
+
+After initialization, I will ask the user to read through the memory bank files and verify product description, used technologies and other information. I should provide a summary of what I've understood about the project to help the user verify the accuracy of the memory bank files. I should encourage the user to correct any misunderstandings or add missing information, as this will significantly improve future interactions.
+
+### Memory Bank Update
+
+Memory Bank updates occur when:
+1. Discovering new project patterns
+2. After implementing significant changes
+3. When user explicitly requests with the phrase **update memory bank** (MUST review ALL files)
+4. When context needs clarification
+
+If I notice significant changes that should be preserved but the user hasn't explicitly requested an update, I should suggest: "Would you like me to update the memory bank to reflect these changes?"
+
+To execute Memory Bank update, I will:
+
+1. Review ALL project files
+2. Document current state
+3. Document Insights & Patterns
+4. If requested with additional context (e.g., "update memory bank using information from @/Makefile"), focus special attention on that source
+
+Note: When triggered by **update memory bank**, I MUST review every memory bank file, even if some don't require updates. Focus particularly on context.md as it tracks current state.
+
+### Add Task
+
+When user completes a repetitive task (like adding support for a new model version) and wants to document it for future reference, they can request: **add task** or **store this as a task**.
+
+This workflow is designed for repetitive tasks that follow similar patterns and require editing the same files. Examples include:
+- Adding support for new AI model versions
+- Implementing new API endpoints following established patterns
+- Adding new features that follow existing architecture
+
+Tasks are stored in the file `tasks.md` in the memory bank folder. The file is optional an can be empty. The file can store many tasks. 
+
+To execute Add Task workflow:
+
+1. Create or update `tasks.md` in the memory bank folder
+2. Document the task with:
+   - Task name and description
+   - Files that need to be modified
+   - Step-by-step workflow followed
+   - Important considerations or gotchas
+   - Example of the completed implementation
+3. Include any context that was discovered during task execution but wasn't previously documented
+
+Example task entry:
+```markdown
+## Add New Model Support
+**Last performed:** [date]
+**Files to modify:**
+- `/providers/gemini.md` - Add model to documentation
+- `/src/providers/gemini-config.ts` - Add model configuration
+- `/src/constants/models.ts` - Add to model list
+- `/tests/providers/gemini.test.ts` - Add test cases
+
+**Steps:**
+1. Add model configuration with proper token limits
+2. Update documentation with model capabilities
+3. Add to constants file for UI display
+4. Write tests for new model configuration
+
+**Important notes:**
+- Check Google's documentation for exact token limits
+- Ensure backward compatibility with existing configurations
+- Test with actual API calls before committing
+```
+
+### Regular Task Execution
+
+In the beginning of EVERY task I MUST read ALL memory bank files - this is not optional. 
+
+The memory bank files are located in `.kilocode/rules/memory-bank` folder. If the folder doesn't exist or is empty, I will warn user about potential issues with the memory bank. I will include `[Memory Bank: Active]` at the beginning of my response if I successfully read the memory bank files, or `[Memory Bank: Missing]` if the folder doesn't exist or is empty. If memory bank is missing, I will warn the user about potential issues and suggest initialization. I should briefly summarize my understanding of the project to confirm alignment with the user's expectations, like:
+
+"[Memory Bank: Active] I understand we're building a React inventory system with barcode scanning. Currently implementing the scanner component that needs to work with the backend API."
+
+When starting a task that matches a documented task in `tasks.md`, I should mention this and follow the documented workflow to ensure no steps are missed.
+
+If the task was repetitive and might be needed again, I should suggest: "Would you like me to add this task to the memory bank for future reference?"
+
+In the end of the task, when it seems to be completed, I will update `context.md` accordingly. If the change seems significant, I will suggest to the user: "Would you like me to update memory bank to reflect these changes?" I will not suggest updates for minor changes.
+
+## Context Window Management
+
+When the context window fills up during an extended session:
+1. I should suggest updating the memory bank to preserve the current state
+2. Recommend starting a fresh conversation/task
+3. In the new conversation, I will automatically load the memory bank files to maintain continuity
+
+## Technical Implementation
+
+Memory Bank is built on Kilo Code's Custom Rules feature, with files stored as standard markdown documents that both the user and I can access.
+
+## Important Notes
+
+REMEMBER: After every memory reset, I begin completely fresh. The Memory Bank is my only link to previous work. It must be maintained with precision and clarity, as my effectiveness depends entirely on its accuracy.
+
+If I detect inconsistencies between memory bank files, I should prioritize brief.md and note any discrepancies to the user.
+
+IMPORTANT: I MUST read ALL memory bank files at the start of EVERY task - this is not optional. The memory bank files are located in `.kilocode/rules/memory-bank` folder.

apps/kilocode-docs/.kilocode/rules/memory-bank/architecture.md

@@ -0,0 +1,137 @@
+# Architecture Overview
+
+## System Architecture
+
+The Kilo Code documentation site is built using Docusaurus 3.8.1, a modern static site generator optimized for documentation websites. The architecture follows a standard Docusaurus pattern with custom enhancements for the Kilo Code brand and functionality.
+
+## Project Structure
+
+### Root Configuration
+- [`package.json`](package.json:1) - Project dependencies and build scripts
+- [`docusaurus.config.ts`](docusaurus.config.ts:1) - Main Docusaurus configuration
+- [`sidebars.ts`](sidebars.ts:1) - Documentation navigation structure
+- [`.env.example`](.env.example:1) - Environment variables template
+
+### Source Code Organization
+
+#### `/src` Directory
+- [`src/constants.ts`](src/constants.ts:1) - Application-wide constants (URLs, links, configuration)
+- [`src/components/`](src/components/) - Custom React components
+  - [`Codicon.tsx`](src/components/Codicon.tsx:1) - VS Code icon component
+  - [`Image.js`](src/components/Image.js:1) - Enhanced image component
+  - [`ReportIssue/`](src/components/ReportIssue/) - Issue reporting component
+  - [`YouTubeEmbed/`](src/components/YouTubeEmbed/) - YouTube video embedding
+- [`src/css/custom.css`](src/css/custom.css:1) - Global styling and theme customization
+- [`src/theme/`](src/theme/) - Docusaurus theme customizations
+
+#### `/docs` Directory Structure
+The documentation follows a hierarchical organization:
+
+```
+docs/
+├── index.mdx                    # Landing page
+├── getting-started/             # Installation and setup
+├── basic-usage/                 # Core functionality
+├── features/                    # Feature documentation
+│   ├── tools/                   # Tool reference
+│   ├── mcp/                     # MCP integration
+│   ├── slash-commands/          # Command workflows
+│   └── experimental/            # Beta features
+├── advanced-usage/              # Advanced topics
+├── providers/                   # AI provider setup guides
+└── extending/                   # Development and contribution
+```
+
+#### `/static` Directory
+- [`static/img/`](static/img/) - Images organized by feature/section
+- [`static/downloads/`](static/downloads/) - Downloadable resources
+
+### Key Technical Decisions
+
+#### Documentation Organization
+- **Feature-First Structure**: Documentation is organized by user journey and feature categories rather than technical implementation
+- **Provider Separation**: Each AI provider has dedicated documentation for setup and configuration
+- **Tool Reference**: Comprehensive tool documentation with individual pages for each tool
+
+#### Navigation Design
+- **Progressive Disclosure**: Information is layered from basic to advanced usage
+- **Cross-References**: Extensive internal linking between related concepts
+- **Search Integration**: Local search with @easyops-cn/docusaurus-search-local
+
+#### Content Strategy
+- **MDX Support**: Enhanced markdown with React component integration
+- **Code Examples**: Extensive use of code blocks with syntax highlighting
+- **Visual Documentation**: Screenshots and diagrams for complex concepts
+
+## Component Relationships
+
+### Core Components
+1. **Docusaurus Core** - Static site generation and routing
+2. **Custom Theme** - VS Code-inspired styling and branding
+3. **Search Integration** - Local search functionality
+4. **Analytics** - PostHog integration for usage tracking
+5. **Custom Components** - Enhanced documentation experience
+
+### Data Flow
+1. **Content Creation** - Markdown/MDX files in `/docs`
+2. **Build Process** - Docusaurus compilation and optimization
+3. **Static Generation** - HTML/CSS/JS output for hosting
+4. **Deployment** - Static files served at https://kilocode.ai/docs
+
+## Critical Implementation Paths
+
+### Build System
+- **Development**: `npm start` - Local development server with hot reload
+- **Production**: `npm run build` - Optimized static site generation
+- **Deployment**: Static files hosted with CDN distribution
+
+### Content Management
+- **Documentation Updates**: Direct markdown file editing
+- **Asset Management**: Static files in organized directory structure
+- **Version Control**: Git-based workflow for content updates
+
+### Search Implementation
+- **Local Search**: @easyops-cn/docusaurus-search-local plugin
+- **Indexing**: Automatic content indexing during build
+- **Search UI**: Integrated search bar with contextual results
+
+### Customization Points
+- **Theme Overrides**: Custom CSS and component swizzling
+- **Plugin Configuration**: Docusaurus plugin ecosystem integration
+- **Content Enhancement**: MDX components for interactive documentation
+
+## Integration Points
+
+### External Services
+- **PostHog Analytics**: User behavior tracking and insights
+- **GitHub Integration**: Edit links and issue reporting
+- **Community Platforms**: Discord, Reddit, Twitter integration
+
+### VS Code Extension Integration
+- **Deep Linking**: Direct links to extension installation
+- **Context Sharing**: Documentation references from extension
+- **Feature Parity**: Documentation reflects current extension capabilities
+
+## Performance Considerations
+
+### Build Optimization
+- **Static Generation**: Pre-built HTML for fast loading
+- **Asset Optimization**: Image compression and lazy loading
+- **Code Splitting**: JavaScript bundle optimization
+
+### User Experience
+- **Mobile Responsive**: Optimized for all device sizes
+- **Fast Navigation**: Client-side routing for smooth transitions
+- **Search Performance**: Local search for instant results
+
+## Maintenance Patterns
+
+### Content Updates
+- **Regular Reviews**: Documentation accuracy validation
+- **Feature Alignment**: Updates synchronized with extension releases
+- **Community Feedback**: User-driven improvements and corrections
+
+### Technical Maintenance
+- **Dependency Updates**: Regular package updates and security patches
+- **Performance Monitoring**: Build time and site performance tracking
+- **Accessibility**: WCAG compliance and usability improvements

apps/kilocode-docs/.kilocode/rules/memory-bank/brief.md

@@ -0,0 +1 @@
+This is the technical and user documentation for Kilo Code, an open source AI agent VS Code extension. It helps you write code more efficiently by generating code, automating tasks, and providing suggestions. It is written with the documentation library Docusaurus and hosted at https://kilocode.ai/docs

apps/kilocode-docs/.kilocode/rules/memory-bank/context.md

@@ -0,0 +1,78 @@
+# Current Context
+
+## Project Status
+
+The Kilo Code documentation site is a mature, production-ready Docusaurus project that serves as the comprehensive documentation hub for the Kilo Code VS Code extension. The site is hosted at https://kilocode.ai/docs and provides extensive documentation covering installation, usage, features, and extension capabilities.
+
+## Current Work Focus
+
+**Memory Bank Initialization**: Currently performing comprehensive memory bank initialization to establish persistent project context for future AI interactions. This involves analyzing the entire documentation structure, understanding the project's purpose, and creating structured documentation files.
+
+## Recent Changes
+
+- Memory bank system being implemented with structured documentation files
+- Product overview documented with comprehensive feature descriptions
+- Project structure analyzed including all documentation categories and provider integrations
+
+## Documentation Structure
+
+The documentation is organized into several major sections:
+
+### Core User Journey
+- **Getting Started**: Installation, setup, and first task completion
+- **Using Kilo Code**: Chat interface, modes, context mentions, and basic features
+- **Core Concepts**: Auto-approving actions, suggested responses, tool usage, and checkpoints
+
+### Advanced Features
+- **Advanced Usage**: Prompt engineering, customization options, memory bank, and large project handling
+- **Customization**: Settings management, custom modes, API configuration profiles
+- **Extending Kilo Code**: Model providers (18+ supported), local models, MCP integration, shell integration
+
+### Reference Materials
+- **Tools Reference**: Comprehensive documentation of all 15+ available tools
+- **Provider Documentation**: Detailed setup guides for Anthropic, OpenAI, and 16+ other AI providers
+- **Community Resources**: Contributing guidelines, development environment setup
+
+## Key Features Documented
+
+### Core Capabilities
+- Multi-mode AI assistance (Code, Architect, Ask, Debug, Custom)
+- Comprehensive tool ecosystem for file operations, browser automation, and system commands
+- Memory Bank system for persistent project context
+- MCP (Model Context Protocol) integration for external tool connectivity
+
+### User Experience Features
+- Auto-generated commit messages with customizable templates
+- Context mentions for precise file and code referencing
+- Checkpoints for conversation state management
+- Fast edits and surgical code modifications
+- Browser automation for web testing and interaction
+
+### Extensibility
+- 18+ AI model providers supported
+- Custom mode creation with file restrictions and tool limitations
+- Local model support for privacy-conscious development
+- MCP server integration for unlimited external tool connectivity
+
+## Technical Implementation
+
+The site uses modern web technologies:
+- **Framework**: Docusaurus 3.8.1 for static site generation
+- **Styling**: Custom CSS with VS Code-inspired design elements
+- **Search**: Local search implementation with @easyops-cn/docusaurus-search-local
+- **Analytics**: PostHog integration for usage tracking
+- **Components**: Custom React components for enhanced documentation experience
+
+## Next Steps
+
+1. Complete memory bank initialization with remaining core files
+2. Document the technical architecture and build system
+3. Create task documentation for common documentation workflows
+4. Validate all memory bank files for accuracy and completeness
+
+## Important Considerations
+
+- Documentation must remain accessible to both technical and non-technical users
+- All provider documentation needs to stay current with API changes
+- Memory bank system documentation serves as both user guide and implementation reference
+- Community contributions are encouraged through GitHub discussions and pull requests

apps/kilocode-docs/.kilocode/rules/memory-bank/product.md

@@ -0,0 +1,95 @@
+# Product Overview
+
+## What Kilo Code Is
+
+Kilo Code is an open source AI agent VS Code extension that transforms how developers write code by providing intelligent, context-aware assistance directly within the VS Code editor. It serves as a persistent development partner that can understand projects, generate code, automate tasks, and provide suggestions.
+
+## Problems It Solves
+
+### Core Development Pain Points
+- **Blank Page Syndrome**: Eliminates the struggle of starting new code or features from scratch
+- **Context Switching**: Reduces time spent switching between documentation, Stack Overflow, and code
+- **Repetitive Tasks**: Automates common development workflows like commit message generation, boilerplate creation, and file operations
+- **Code Quality**: Helps with refactoring, debugging, and maintaining consistent coding standards
+- **Project Understanding**: Assists in understanding large codebases and complex architectures
+
+### AI Memory Limitations
+- **Session Reset Problem**: Traditional AI assistants lose all context between sessions, requiring re-explanation of project details
+- **Inefficient Context Gathering**: Without memory, AI must re-analyze entire codebases repeatedly, which is slow and expensive
+- **Inconsistent Understanding**: Lack of persistent context leads to inconsistent suggestions and solutions
+
+## How Kilo Code Works
+
+### Core Interaction Model
+Users interact with Kilo Code through a chat interface within VS Code, using natural language to describe what they want to accomplish. Kilo Code then uses specialized modes and tools to fulfill requests.
+
+### Mode System
+- **Code Mode**: General-purpose coding tasks, file editing, project creation
+- **Architect Mode**: Planning, design, technical leadership, and documentation
+- **Ask Mode**: Information gathering, explanations, and learning
+- **Debug Mode**: Systematic problem diagnosis and troubleshooting
+- **Custom Modes**: Unlimited specialized personas for specific workflows
+
+### Tool Ecosystem
+Kilo Code uses a sophisticated tool system organized into groups:
+- **Read Tools**: File exploration, code analysis, project understanding
+- **Edit Tools**: Code modification, file creation, precise surgical edits
+- **Browser Tools**: Web automation and testing
+- **Command Tools**: System command execution and build processes
+- **MCP Tools**: External service integration through Model Context Protocol
+- **Workflow Tools**: Task management, mode switching, progress tracking
+
+### Memory Bank System
+A revolutionary approach to AI context preservation that maintains project understanding across sessions through structured documentation files that both the AI and developers can access.
+
+## User Experience Goals
+
+### Seamless Integration
+- Natural language interaction within familiar VS Code environment
+- No context switching between tools or applications
+- Immediate access through sidebar panel
+
+### Intelligent Assistance
+- Context-aware suggestions based on current project and codebase
+- Proactive help with common development patterns
+- Learning from user preferences and project conventions
+
+### Workflow Enhancement
+- Streamlined development processes through automation
+- Reduced cognitive load for repetitive tasks
+- Enhanced productivity without disrupting existing workflows
+
+### Extensibility
+- Support for multiple AI model providers
+- Custom mode creation for specialized workflows
+- MCP integration for unlimited tool expansion
+- Local model support for privacy-conscious development
+
+## Target Outcomes
+
+### For Individual Developers
+- Faster code generation and iteration cycles
+- Improved code quality through AI-assisted refactoring and debugging
+- Reduced time spent on documentation and boilerplate code
+- Enhanced learning through AI explanations and suggestions
+
+### For Development Teams
+- Consistent coding standards and practices
+- Shared custom modes for standardized workflows
+- Improved code review processes through better commit messages
+- Knowledge preservation through Memory Bank documentation
+
+### For Projects
+- Better documentation as a byproduct of AI assistance
+- More maintainable codebases through consistent patterns
+- Faster onboarding for new team members
+- Preserved project knowledge across team changes
+
+## Success Metrics
+
+The product succeeds when developers report:
+- Increased coding velocity and reduced time-to-completion
+- Improved code quality and fewer bugs
+- Enhanced understanding of complex codebases
+- Reduced friction in development workflows
+- Better project documentation and knowledge retention

apps/kilocode-docs/.kilocode/rules/memory-bank/tasks.md

@@ -0,0 +1,391 @@
+# Documentation Tasks
+
+This file documents common repetitive tasks and workflows for maintaining the Kilo Code documentation site.
+
+## Add New Provider Documentation
+
+**Last performed:** Initial documentation setup
+**Files to modify:**
+- `/docs/providers/[provider-name].md` - Create new provider documentation
+- `/sidebars.ts` - Add provider to navigation structure
+- `/src/constants.ts` - Add provider URLs if needed
+
+**Steps:**
+1. Create new provider documentation file in `/docs/providers/`
+2. Follow the standard provider documentation template:
+   - Introduction and website link
+   - Getting an API Key section
+   - Supported Models section
+   - Configuration in Kilo Code section
+   - Tips and Notes section
+3. Add provider to the Model Providers section in `sidebars.ts`
+4. Update constants file if new URLs are needed
+5. Test documentation locally with `npm start`
+6. Verify all links work correctly
+
+**Template structure:**
+```markdown
+---
+sidebar_label: Provider Name
+---
+
+# Using [Provider Name] With Kilo Code
+
+Brief description of the provider and their strengths.
+
+**Website:** [Provider URL]
+
+## Getting an API Key
+[Step-by-step instructions]
+
+## Supported Models
+[List of supported models]
+
+## Configuration in Kilo Code
+[Setup instructions]
+
+## Tips and Notes
+[Additional helpful information]
+```
+
+## Add New Tool Documentation
+
+**Last performed:** Tool reference documentation setup
+**Files to modify:**
+- `/docs/features/tools/[tool-name].md` - Create new tool documentation
+- `/sidebars.ts` - Add tool to Tools Reference section
+- `/docs/features/tools/tool-use-overview.md` - Update tool overview if needed
+
+**Steps:**
+1. Create new tool documentation file in `/docs/features/tools/`
+2. Follow the standard tool documentation template
+3. Add tool to the Tools Reference section in `sidebars.ts`
+4. Update tool overview page if the tool represents a new category
+5. Test documentation locally
+6. Verify code examples and parameter descriptions are accurate
+
+**Important notes:**
+- Include practical examples of tool usage
+- Document all parameters with their types and requirements
+- Explain when and why to use the tool
+- Include common error scenarios and solutions
+
+## Update Feature Documentation
+
+**Last performed:** Feature documentation organization
+**Files to modify:**
+- Relevant feature documentation files in `/docs/features/`
+- `/sidebars.ts` - Update navigation if structure changes
+- `/docs/index.mdx` - Update feature highlights if major features added
+
+**Steps:**
+1. Identify which feature documentation needs updates
+2. Review current documentation for accuracy
+3. Update content to reflect latest extension capabilities
+4. Add new screenshots if UI has changed
+5. Update navigation structure if needed
+6. Test all internal links
+7. Verify examples still work with current extension version
+
+**Important considerations:**
+- Keep screenshots current with latest extension UI
+- Ensure feature descriptions match actual extension behavior
+- Update version-specific information
+- Maintain consistency in documentation style
+
+## Add New Blog Post
+
+**Last performed:** Auto-generate commit messages blog post
+**Files to modify:**
+- `/blog-posts/[post-name].md` - Create new blog post
+- Consider adding to main documentation if content is reference material
+
+**Steps:**
+1. Create new blog post file in `/blog-posts/`
+2. Follow the established blog post style and tone
+3. Include practical examples and real-world usage
+4. Add relevant images to `/static/img/` if needed
+5. Consider if content should also be added to main documentation
+6. Review for clarity and technical accuracy
+
+**Content guidelines:**
+- Focus on practical benefits and real-world usage
+- Include specific examples and code snippets
+- Maintain conversational but informative tone
+- Link to relevant documentation sections
+
+## Update Provider API Changes
+
+**Last performed:** Provider documentation updates
+**Files to modify:**
+- Relevant provider documentation in `/docs/providers/`
+- `/docs/getting-started/connecting-api-provider.md` - If setup process changes
+
+**Steps:**
+1. Identify which providers have API changes
+2. Update supported models lists
+3. Update configuration instructions if needed
+4. Update pricing information references
+5. Test configuration steps with actual provider APIs
+6. Update screenshots if provider UIs have changed
+
+**Important notes:**
+- Verify model names and capabilities with provider documentation
+- Check for new authentication methods or requirements
+- Update rate limit information if changed
+- Ensure all external links are still valid
+
+## Reorganize Documentation Structure
+
+**Last performed:** Features section reorganization
+**Files to modify:**
+- `/sidebars.ts` - Primary navigation structure changes
+- `/docusaurus.config.ts` - Add redirects for moved content
+- Multiple documentation files - Update internal links
+
+**Steps:**
+1. Plan new documentation structure
+2. Update `sidebars.ts` with new organization
+3. Add redirects in `docusaurus.config.ts` for moved content
+4. Update internal links throughout documentation
+5. Test all navigation paths
+6. Verify search functionality still works
+7. Update any hardcoded paths in components
+
+**Important considerations:**
+- Always add redirects for moved content to prevent broken links
+- Update internal link references throughout the site
+- Test navigation flow from user perspective
+- Consider impact on external links and bookmarks
+
+## Add New Custom Component
+
+**Last performed:** YouTube embed and image components
+**Files to modify:**
+- `/src/components/[ComponentName]/` - Create new component directory
+- `/src/theme/MDXComponents.ts` - Register component for MDX usage
+- Documentation files where component will be used
+
+**Steps:**
+1. Create component directory in `/src/components/`
+2. Implement React component with TypeScript
+3. Add component styles in separate CSS module if needed
+4. Register component in `MDXComponents.ts` for MDX usage
+5. Test component in development environment
+6. Document component usage for other contributors
+7. Use component in relevant documentation files
+
+**Component guidelines:**
+- Follow existing component patterns and styling
+- Use TypeScript for type safety
+- Include proper error handling
+- Make components reusable and configurable
+- Follow accessibility best practices
+
+## Update Screenshots and Visual Assets
+
+**Last performed:** Ongoing maintenance need
+**Files to modify:**
+- `/static/img/[feature-directories]/` - Update screenshot files
+- Documentation files with embedded images - Update image references
+- `/docs/getting-started/` - Installation and setup screenshots
+- `/docs/basic-usage/` - Interface and workflow screenshots
+
+**Steps:**
+1. Identify which features have UI changes from extension releases
+2. Take new screenshots in consistent browser/OS environment
+3. Optimize images for web (compress, appropriate dimensions)
+4. Replace old screenshots in `/static/img/` directories
+5. Update any image references in documentation files
+6. Test that all images load correctly in development
+7. Verify images are accessible and have proper alt text
+
+**Important considerations:**
+- Maintain consistent screenshot style (browser, zoom level, theme)
+- Use descriptive filenames that match the feature being documented
+- Compress images to keep site performance optimal
+- Update alt text for accessibility
+- Consider creating a screenshot style guide for consistency
+
+## Graduate Experimental Features to Stable
+
+**Last performed:** Codebase indexing graduation
+**Files to modify:**
+- Feature documentation files - Remove experimental warnings
+- `/sidebars.ts` - Move from experimental to appropriate section
+- `/docs/features/experimental/` - Remove from experimental list
+- Related tool documentation - Update experimental status
+- `/docusaurus.config.ts` - Add redirects if URLs change
+
+**Steps:**
+1. Identify features graduating from experimental status
+2. Remove experimental warnings and disclaimers from documentation
+3. Update navigation structure in `sidebars.ts`
+4. Move documentation files if directory structure changes
+5. Add redirects for any changed URLs
+6. Update cross-references throughout documentation
+7. Remove duplicate documentation if it exists
+8. Update feature overview pages to reflect stable status
+
+**Important considerations:**
+- Always add redirects for moved content to prevent broken links
+- Search for all references to the feature across documentation
+- Update any "experimental features" overview pages
+- Consider if feature deserves more prominent placement in navigation
+- Verify all examples and instructions work with stable version
+
+## Process Extension Release Documentation Updates
+
+**Last performed:** Version-specific updates from todos.md
+**Files to modify:**
+- Multiple feature documentation files based on release notes
+- Provider documentation for new models or API changes
+- Tool documentation for behavior changes
+- Getting started guides for new onboarding features
+- FAQ or troubleshooting sections for resolved issues
+
+**Steps:**
+1. Review extension release notes for documentation impacts
+2. Categorize changes: UI updates, new features, bug fixes, model additions
+3. Update relevant feature documentation with new capabilities
+4. Add or update screenshots for UI changes
+5. Update provider documentation for new models
+6. Update tool documentation for behavior changes
+7. Add troubleshooting entries for resolved issues
+8. Test all updated examples and instructions
+
+**Important considerations:**
+- Prioritize user-facing changes that affect documentation accuracy
+- Update version-specific information where relevant
+- Ensure examples still work with current extension version
+- Consider if changes require updates to getting started flow
+- Document any breaking changes or migration steps
+
+## Manage Documentation Redirects
+
+**Last performed:** MCP and features section reorganization
+**Files to modify:**
+- `/docusaurus.config.ts` - Add redirect configurations
+- `/sidebars.ts` - Update navigation structure
+- Documentation files - Update internal links
+
+**Steps:**
+1. Plan new documentation structure or identify moved content
+2. Document all URL changes that will occur
+3. Add redirect entries in `docusaurus.config.ts`
+4. Update navigation structure in `sidebars.ts`
+5. Update internal links throughout documentation
+6. Test all redirect paths work correctly
+7. Verify search functionality still works
+8. Update any hardcoded paths in components
+
+**Important considerations:**
+- Always add redirects before moving content to prevent 404 errors
+- Use permanent redirects (301) for moved content
+- Test redirects work for both old and new URLs
+- Update internal links to use new URLs directly
+- Consider impact on external links and bookmarks
+- Document redirect rationale for future reference
+
+## Resolve Duplicate/Conflicting Documentation
+
+**Last performed:** Codebase search tool documentation cleanup needed
+**Files to modify:**
+- Duplicate documentation files
+- Navigation structure
+- Internal links and cross-references
+- Redirect configuration if URLs change
+
+**Steps:**
+1. Identify duplicate or conflicting documentation files
+2. Compare content to determine which version is authoritative
+3. Merge useful content from both versions if needed
+4. Remove or redirect the duplicate file
+5. Update navigation to remove duplicate entries
+6. Update internal links to point to single authoritative source
+7. Add redirects if removing a file that might be bookmarked
+8. Verify no broken links remain
+
+**Important considerations:**
+- Determine which version has more accurate/current information
+- Preserve any unique content from the version being removed
+- Check git history to understand why duplicates exist
+- Ensure the remaining version covers all use cases
+- Update any cross-references throughout the site
+
+## Update Tool Documentation for Behavior Changes
+
+**Last performed:** Tool fixes mentioned in v4.58.0 release
+**Files to modify:**
+- Individual tool documentation files in `/docs/features/tools/`
+- Tool overview page if categories change
+- Examples and usage patterns in tool docs
+
+**Steps:**
+1. Review extension release notes for tool behavior changes
+2. Identify which tools have updated functionality
+3. Update parameter descriptions and requirements
+4. Update examples to reflect new behavior
+5. Add or update limitation sections
+6. Update "when is it used" sections if use cases change
+7. Test examples to ensure they work correctly
+8. Update tool overview page if needed
+
+**Important considerations:**
+- Verify all parameter descriptions are accurate
+- Test code examples with current extension version
+- Update any error scenarios or troubleshooting information
+- Ensure examples demonstrate best practices
+- Consider if changes affect tool categorization
+
+## Audit and Fix Broken Links
+
+**Last performed:** Ongoing maintenance need
+**Files to modify:**
+- All documentation files with internal or external links
+- Navigation configuration files
+- Component files with hardcoded links
+
+**Steps:**
+1. Run Docusaurus build to identify broken internal links
+2. Use link checking tools for external links
+3. Manually verify provider URLs and external service links
+4. Update or remove broken external links
+5. Fix internal link references
+6. Update navigation structure if needed
+7. Test all fixed links work correctly
+8. Document any permanently removed external resources
+
+**Important considerations:**
+- Docusaurus automatically checks internal links during build
+- External links may break due to provider website changes
+- Consider using archive.org links for historical references
+- Update provider URLs when services rebrand or move
+- Remove links to discontinued services
+- Add redirects if internal link structure changes
+
+## Update Model Lists Across Providers
+
+**Last performed:** Ongoing as providers add models
+**Files to modify:**
+- Individual provider documentation files in `/docs/providers/`
+- Provider comparison information if it exists
+- Getting started guides mentioning specific models
+
+**Steps:**
+1. Review provider websites and APIs for new model additions
+2. Update supported models lists in provider documentation
+3. Add model capabilities and limitations information
+4. Update pricing references if available
+5. Test configuration with new models if possible
+6. Update any model comparison information
+7. Verify model names and identifiers are correct
+8. Update examples to use current model names
+
+**Important considerations:**
+- Verify model names exactly match provider APIs
+- Include context window sizes and capabilities where relevant
+- Note any special configuration requirements for new models
+- Update rate limit information if it varies by model
+- Consider if new models change provider recommendations
+- Test actual API connectivity when possible

apps/kilocode-docs/.kilocode/rules/memory-bank/tech.md

@@ -0,0 +1,158 @@
+# Technology Stack
+
+## Core Framework
+
+### Docusaurus 3.8.1
+- **Purpose**: Modern static site generator optimized for documentation
+- **Key Features**: React-based, MDX support, built-in search, theming
+- **Configuration**: [`docusaurus.config.ts`](docusaurus.config.ts:1)
+
+## Runtime Environment
+
+### Node.js
+- **Required Version**: Node.js 18.0 or higher
+- **Package Manager**: npm (with package-lock.json for dependency locking)
+- **Development Server**: Hot reload with live editing support
+
+## Core Dependencies
+
+### React Ecosystem
+- **React 19.0.0**: Core UI library
+- **React DOM 19.0.0**: DOM rendering
+- **@mdx-js/react 3.0.0**: MDX component integration
+- **clsx 2.0.0**: Conditional CSS class utility
+
+### Docusaurus Plugins & Presets
+- **@docusaurus/preset-classic 3.8.1**: Standard Docusaurus configuration
+- **@docusaurus/plugin-client-redirects 3.8.1**: URL redirect management
+- **@easyops-cn/docusaurus-search-local 0.48.5**: Local search functionality
+
+### Styling & UI Components
+- **@vscode/codicons 0.0.36**: VS Code icon integration
+- **prism-react-renderer 2.3.0**: Syntax highlighting for code blocks
+- **Custom CSS**: VS Code-inspired theme in [`src/css/custom.css`](src/css/custom.css:1)
+
+### Analytics & Tracking
+- **posthog-docusaurus 2.0.4**: User behavior analytics and insights
+- **Configuration**: Environment-based with POSTHOG_API_KEY
+
+## Development Dependencies
+
+### TypeScript Support
+- **TypeScript 5.6.2**: Type checking and development tooling
+- **@docusaurus/types 3.8.1**: Docusaurus TypeScript definitions
+- **@docusaurus/module-type-aliases 3.8.1**: Module type aliases
+- **@docusaurus/tsconfig 3.8.1**: Shared TypeScript configuration
+
+### Development Tools
+- **dotenv 16.4.7**: Environment variable management
+- **husky 9.1.7**: Git hooks for development workflow
+
+## Build System
+
+### Development Workflow
+```bash
+npm start          # Local development server with hot reload
+npm run build      # Production build with optimization
+npm run serve      # Serve built files locally
+npm run clear      # Clear Docusaurus cache
+```
+
+Not that on Windows, it may be useful to use:
+```bash
+npx docusaurus start
+npx docusaurus build
+```
+
+### Build Configuration
+- **Host**: 0.0.0.0 (accessible from network)
+- **Environment Variables**: Loaded via dotenv
+- **Output**: Static HTML/CSS/JS files for CDN deployment
+
+## Browser Support
+
+### Production Targets
+- **Modern Browsers**: >0.5% usage, not dead, not Opera Mini
+- **Specific Exclusions**: Opera Mini (limited JavaScript support)
+
+### Development Targets
+- **Chrome**: Last 3 versions
+- **Firefox**: Last 3 versions  
+- **Safari**: Last 5 versions
+
+## External Integrations
+
+### GitHub Integration
+- **Repository**: https://github.com/Kilo-Org/docs
+- **Edit Links**: Direct links to GitHub for documentation editing
+- **Issue Reporting**: Integrated issue creation workflow
+
+### Community Platforms
+- **Discord**: https://kilocode.ai/discord
+- **Reddit**: https://www.reddit.com/r/kilocode/
+- **Twitter**: https://x.com/Kilo_Code
+- **YouTube**: https://www.youtube.com/@Kilo-Code
+
+### VS Code Marketplace
+- **Extension URL**: https://marketplace.visualstudio.com/items?itemName=kilocode.kilo-code
+- **Open VSX**: https://open-vsx.org/extension/kilocode/kilo-code
+
+## Deployment Architecture
+
+### Static Site Hosting
+- **Production URL**: https://kilocode.ai/docs
+- **Base Path**: /docs (configured in docusaurus.config.ts)
+- **CDN**: Static file distribution for global performance
+
+### Content Delivery
+- **Static Assets**: Images, downloads, and media files
+- **Search Index**: Local search data bundled with site
+- **Sitemap**: Automatic generation for SEO
+
+## Development Constraints
+
+### File Organization
+- **Documentation**: Markdown/MDX files in `/docs` directory
+- **Static Assets**: Organized by feature in `/static/img`
+- **Components**: Custom React components in `/src/components`
+
+### Content Management
+- **Version Control**: Git-based workflow for all content
+- **Asset Optimization**: Manual image optimization required
+- **Link Validation**: Docusaurus validates internal links during build
+
+## Performance Considerations
+
+### Build Optimization
+- **Code Splitting**: Automatic JavaScript bundle optimization
+- **Static Generation**: Pre-rendered HTML for fast initial load
+- **Asset Optimization**: CSS/JS minification in production builds
+
+### Runtime Performance
+- **Client-Side Routing**: Fast navigation between pages
+- **Search Performance**: Local search index for instant results
+- **Image Loading**: Manual lazy loading implementation where needed
+
+## Security & Privacy
+
+### Data Collection
+- **Analytics**: PostHog for usage tracking (configurable)
+- **Privacy Policy**: Links to both website and extension privacy policies
+- **User Control**: Analytics can be disabled via environment configuration
+
+### Content Security
+- **Static Generation**: No server-side vulnerabilities
+- **External Links**: Proper target and rel attributes for security
+- **Asset Validation**: Build-time validation of all assets and links
+
+## Maintenance Requirements
+
+### Regular Updates
+- **Dependencies**: Monthly security and feature updates
+- **Docusaurus**: Follow major version updates for new features
+- **Node.js**: Maintain compatibility with LTS versions
+
+### Content Synchronization
+- **Extension Features**: Documentation must reflect current extension capabilities
+- **Provider APIs**: Keep provider setup guides current with API changes
+- **Community Links**: Verify external links remain active

apps/kilocode-docs/.kilocode/rules/memory-bank/todos.md

@@ -0,0 +1,116 @@
+## Settings and UI Documentation
+
+### 10. API Provider Selection Enhancement
+- **File to Update**: `features/settings-management.md`
+- **Release Note**: v4.58.0 - "Add Search/Filter Functionality to API Provider Selection in Settings"
+- **Required Changes**: Document new search/filter functionality in API provider selection
+
+### 11. Auto-Approve Settings Update
+- **File to Update**: `features/auto-approving-actions.md`
+- **Release Note**: v4.57.0 - "Add 'max requests' section to the Auto-Approve Settings page"
+- **Required Changes**: Document new max requests section in Auto-Approve Settings
+
+### 12. Chat Interface Updates
+- **File to Update**: `basic-usage/the-chat-interface.md`
+- **Release Notes & Changes**:
+  - v4.58.0 - "Add copy prompt button to task actions" → Document copy prompt button functionality
+  - v4.56.0 - "Add idea suggestion box to get you inspired with some ideas when starting out fresh" → Document idea suggestion feature
+  - v4.57.1 - "Show idea suggestions when there is no task history" → Update idea suggestion documentation
+
+### 13. Git Commit Generation Updates
+- **File to Update**: `basic-usage/git-commit-generation.md`
+- **Release Note**: v4.56.1 - "Continue to show commit message generation progress while waiting for LLM response"
+- **Required Changes**: Document improved progress indicators during commit message generation
+
+---
+
+## Bug Fixes and Technical Updates
+
+### 14. OpenRouter Provider Fix
+- **File to Update**: `providers/openrouter.md`
+- **Release Note**: v4.56.2 - "Fix autocomplete init with custom openrouter models"
+- **Required Changes**: Update documentation regarding autocomplete with custom OpenRouter models
+
+### 15. Claude Code Windows Integration
+- **File to Update**: `providers/claude-code.md`
+- **Release Note**: v4.57.2 - "ENAMETOOLONG error in Claude Code integration on Windows is resolved"
+- **Required Changes**: Add troubleshooting section for Windows-specific issues (now resolved)
+
+### 16. Error Handling Improvements
+- **File to Update**: `faq.md` or create troubleshooting section
+- **Release Note**: v4.57.3 - "More details are included in connection error messages"
+- **Required Changes**: Document improved error handling and connection error messages
+
+### 17. Localization Updates
+- **File to Create/Update**: `advanced-usage/localization.md` (if doesn't exist)
+- **Release Notes**:
+  - v4.58.1 - "French localization has been improved"
+  - v4.58.3 - "Fixed 'Kilo' being inadvertently translated in some languages"
+- **Required Changes**: Document localization improvements and translation fixes
+
+---
+
+## Tool Documentation Updates
+
+### 18. Tool Behavior Updates
+- **Files to Review**: All files in `features/tools/` directory
+- **Release Notes**: Various tool fixes mentioned in v4.58.0
+- **Required Changes**: 
+  - Update `apply_diff` tool documentation for intermittent hang fixes
+  - Update `insert_content` tool documentation for new file creation capability
+  - Update MCP resource handling documentation for image support fixes
+
+### 19. Codebase Search Tool
+- **File to Update**: `features/tools/codebase-search.md` or `advanced-usage/available-tools/codebase-search.md`
+- **Release Note**: Related to codebase indexing moving out of experimental
+- **Required Changes**: Remove experimental warnings from codebase search tool documentation
+
+---
+
+## UI and Visual Updates
+
+### 20. Settings Management UX
+- **File to Update**: `features/settings-management.md`
+- **Release Note**: v4.58.0 - "Fix code index secret persistence and improve settings UX"
+- **Required Changes**: Document settings UX improvements and code index configuration
+
+### 21. Chat UI Improvements
+- **File to Update**: `basic-usage/the-chat-interface.md`
+- **Release Notes**: v4.58.0 - Multiple UI consistency and layout improvements
+- **Required Changes**: Update documentation for chat UI enhancements and consistency changes
+
+### 22. Screenshot Updates
+- **Files to Review**: All documentation files with screenshots
+- **Release Notes**: Multiple UI changes across releases
+- **Required Changes**: Review and update screenshots to reflect current UI state
+
+---
+
+## Getting Started Updates
+
+### 23. First Task Experience
+- **File to Update**: `getting-started/your-first-task.md`
+- **Release Notes**: Idea suggestion box and improved onboarding
+- **Required Changes**: Update first task documentation to include idea suggestions for new users
+
+---
+
+## Additional Provider Model Updates
+
+### 24. Model Additions Across Providers
+- **Files to Update**: Various provider files
+- **Release Notes**: Multiple model additions across different providers
+- **Required Changes**: 
+  - Verify all new models are documented in respective provider files
+  - Update model lists and capabilities where applicable
+
+---
+
+## Documentation Structure and Navigation
+
+### 25. File Organization Review
+- **Files to Review**: All documentation files
+- **Changes**: 
+  - Ensure codebase indexing is properly moved out of experimental
+  - Verify all internal links work after any file moves
+  - Update navigation and cross-references as needed

apps/kilocode-docs/.kilocodemodes

@@ -0,0 +1,217 @@
+customModes:
+  - slug: video-script-writer
+    name: Video Script Writer
+    roleDefinition: >-
+      **Persona: Kilo Code Expert Scriptwriter**
+
+
+      **Background:**
+
+      A professional scriptwriter specializing in creating clear, engaging, and
+      informative scripts tailored specifically for YouTube, Reddit tutorials,
+      and documentation videos focused on Kilo Code. With a deep understanding
+      of Kilo Code’s functionalities and its practical applications, this expert
+      excels at translating complex coding concepts into straightforward,
+      easy-to-follow explanations.
+
+
+      **Communication Style:**
+
+      - Professional yet friendly, fostering trust and approachability.
+
+      - Concise and structured, using precise language to ensure clarity.
+
+      - Logical flow, breaking down complex topics into manageable steps.
+
+      - Engaging tone, designed to maintain viewer interest throughout the
+      video.
+
+
+      **Specialization:**
+
+      - Kilo Code’s features and updates
+
+      - Common troubleshooting techniques
+
+      - Step-by-step tutorials for beginners to advanced users
+
+      - Practical use-cases and real-world examples
+
+
+      **Approach:**
+
+      - Start by clearly stating the objective of the script.
+
+      - Provide concise explanations with relatable analogies when helpful.
+
+      - Anticipate common questions and proactively address them.
+
+      - Conclude with actionable insights or suggested next steps for users.
+
+
+      **Tone and Personality:**
+
+      - Knowledgeable and authoritative without being intimidating.
+
+      - Patient and encouraging, ensuring viewers feel capable and supported.
+
+      - Enthusiastic about Kilo Code, making viewers excited about learning and
+      implementing the software.
+
+
+      **Goal:**
+
+      To empower viewers by making Kilo Code accessible and easy to master,
+      enhancing their confidence and competence through expert guidance and
+      clear, compelling content.
+    groups: []
+    source: project
+  - slug: docs
+    name: Documentation Writer
+    roleDefinition: You are a technical documentation writer who combines 24 years of coding experience with Smart Brevity principles to create documentation that developers can scan, understand, and act on immediately. You prioritize cognitive accessibility and write for readers with varying attention spans, including those with ADD/ADHD. Your straightforward, conversational style eliminates fluff while maintaining technical precision. You specialize in Visual Studio Code extension documentation using Docusaurus, with deep expertise in Markdown, MDX, and React-based static sites. Every piece of content serves a clear purpose and provides immediate value to developers.
+    customInstructions: >-
+      ### Documentation Standards
+
+      #### 1. **Lead with Impact** (Smart Brevity Core)
+         Start every section with the ONE most important thing users need to know. Answer "why should I care?" before explaining "how to do it." Front-load value in the first sentence.
+
+      #### 2. **One Big Thing Per Section**
+         Each documentation section should have one primary takeaway. State it clearly in the opening. Everything else supports that main point.
+
+      #### 3. **Scannable Structure** 
+         - Use descriptive headings that answer questions
+         - Keep paragraphs to 1-3 sentences (max 60 words)
+         - Limit sentences to 20 words when possible
+         - Use bullet points for lists of 3+ items
+         - Bold key terms on first mention
+
+      #### 4. **Precision Over Perfection**
+         Write for experienced developers. Skip basic explanations unless they clarify Kilo Code-specific behavior. Assume familiarity with VS Code, extensions, and development workflows.
+
+      #### 5. **Show, Don't Just Tell**
+         Every feature explanation needs a realistic code example. Make examples copy-pasteable and immediately useful. Avoid "Hello World" demos—use real-world scenarios.
+
+      #### 6. **Cognitive Accessibility First**
+         - Use parallel structure in lists
+         - Define technical terms when they impact understanding
+         - Provide context for complex workflows
+         - Break complex tasks into numbered steps
+         - Use consistent terminology throughout
+
+      #### 7. **Anticipate and Address**
+         Include common pitfalls, troubleshooting tips, and "gotchas" within relevant sections. Answer the question users will have next.
+
+      #### 8. **Internal Navigation Standards**
+         - Use absolute paths starting from `/docs/` root
+         - Omit `.md` extensions in links
+         - Example: `[Configuration Guide](/configuration/setup/)`
+         - Test all links work in Docusaurus environment
+
+      #### 9. **@site Alias Usage**
+         - Use `@site` only for code imports and component references
+         - Example: `import Header from '@site/src/components/Header';`
+         - Never use `@site` in Markdown links—use absolute paths instead
+
+      #### 10. **Code Standards**
+         - Provide syntax highlighting for all code blocks
+         - Include file names or context when helpful
+         - Maintain consistent indentation (2 spaces)
+         - Test code examples before publishing
+         - Show input AND expected output when relevant
+
+      #### 11. **Visual Elements**
+         - Add image placeholders with descriptive alt text
+         - Use format: `<img src="/img/folder/filename.png" alt="Descriptive text" width="600" />`
+         - Images should start with `/img/` path
+         - Include brief description below complex images
+
+      #### 12. **Eliminate Filler Words**
+         Remove: "simply," "just," "easily," "obviously," "of course," "as you can see." These add cognitive load without value.
+
+      #### 13. **Progressive Disclosure**
+         Start with the essential information. Add detail as needed. Use expandable sections or links to deeper content for advanced users.
+
+      #### 14. **Consistency Checklist**
+         - Use same terminology for same concepts
+         - Follow identical formatting patterns
+         - Maintain consistent voice and tone
+         - Verify all links and code examples work
+         - Check accessibility with screen reader preview
+
+    groups:
+      - read
+      - command
+      - edit
+    source: project
+
+  - slug: posts
+    name: Blog Post Author
+    roleDefinition: You are a technical blog author who applies Smart Brevity principles to make complex development topics accessible and engaging. With 24 years of experience, you write with authentic candor and technical precision, helping developers quickly understand why they should care about Kilo Code features. Your friendly, conversational tone includes light humor while maintaining professional credibility. You specialize in translating documentation into compelling stories that show real-world value, always leading with the problem being solved rather than the solution being offered.
+    customInstructions: >-
+      ### Smart Brevity Blog Standards
+
+      #### 1. **Hook with Value** (Smart Brevity Core)
+         Open every post by stating the problem this feature/topic solves. Lead with "why this matters" before explaining "what it does." Make the value clear in the first paragraph.
+
+      #### 2. **One Big Thing Focus**
+         Each blog post should have one main takeaway readers can act on immediately. State it early and reinforce it throughout.
+
+      #### 3. **Scannable and Engaging**
+         - Use subheadings that ask questions or promise benefits
+         - Keep paragraphs short (2-3 sentences max)
+         - Include bullet points for key benefits or steps
+         - Add light humor or personality without compromising clarity
+         - Bold important concepts and features
+
+      #### 4. **Real-World Context**
+         Show how experienced developers actually use these features. Skip toy examples—demonstrate genuine productivity gains and workflow improvements.
+
+      #### 5. **Documentation Integration**
+         - Link to relevant docs using absolute URLs
+         - Example: `[Complete Setup Guide](https://kilocode.ai/docs/configuration/)`
+         - Reference specific documentation sections to drive deeper engagement
+         - Make it easy to go from blog interest to documentation action
+
+      #### 6. **Accessible Technical Writing**
+         - Define acronyms and technical terms when they impact understanding
+         - Use parallel structure in lists and explanations
+         - Provide context for workflows and processes
+         - Consider readers with varying attention spans and learning styles
+
+      #### 7. **Problem-Solution Structure**
+         - Start with relatable developer pain point
+         - Show how Kilo Code addresses it specifically
+         - Provide concrete example or walkthrough
+         - End with clear next steps or call to action
+
+      #### 8. **Code with Context**
+         - Include realistic, copy-pasteable code examples
+         - Show before/after scenarios when relevant
+         - Provide syntax highlighting and proper formatting
+         - Explain why the code works, not just how
+
+      #### 9. **Visual Storytelling**
+         - Use images from documentation: `<img src="https://kilocode.ai/docs/img/folder/filename.png" alt="Description" width="600" />`
+         - Include screenshots that support the narrative
+         - Add brief descriptions for complex visuals
+         - Show UI paths with backticks: `Settings → Prompts → Feature Name`
+
+      #### 10. **Friendly Authority**
+         - Write conversationally but maintain technical credibility
+         - Include 1-2 appropriate jokes or light observations per post
+         - Acknowledge common frustrations developers face
+         - Share insights from real usage patterns
+
+      #### 11. **Clear Navigation**
+         - End posts with specific next steps
+         - Link to relevant documentation sections
+         - Suggest related features or workflows
+         - Make it easy for readers to continue their journey
+
+      #### 12. **Elimination Editing**
+         Remove marketing speak, unnecessary qualifiers, and filler words. Every sentence should advance understanding or provide value.
+
+    groups:
+      - read
+      - edit
+    source: project

apps/kilocode-docs/.kilocoderules

@@ -0,0 +1,31 @@
+# Kilo Code Documentation Rules
+
+## Documentation Links
+- Do not include .md extensions in documentation links
+- Use absolute paths starting from the `/docs/` root for internal documentation links
+- Example: [link text](/basic-usage/how-tools-work) NOT [link text](basic-usage/how-tools-work.md) or [link text](../../basic-usage/how-tools-work)
+
+This ensures links work correctly in the built documentation while maintaining clean URLs.
+
+## Image References
+- Use `/docs/img/` prefix for all image paths in documentation
+- Example: `<img src="/docs/img/your-first-task/example.png" alt="Description" width="600" />`
+- NOT: `<img src="img/example.png" ...>` or `<img src="../static/img/example.png" ...>`
+
+## Component Imports
+- Import custom components from `@site/src/components/` using absolute paths
+- Import constants from `@site/src/constants.ts`
+- Examples:
+  - `import Image from '@site/src/components/Image';`
+  - `import { DISCORD_URL } from '@site/src/constants.ts'`
+  - `import Codicon from '@site/src/components/Codicon';`
+
+## External Link References
+- Use constants from `src/constants.ts` for external URLs instead of hardcoding
+- Example: `<a href={DISCORD_URL} target="_blank">Discord</a>`
+- NOT: `<a href="https://kilocode.ai/discord">Discord</a>`
+
+## Sidebar Configuration
+- Document IDs in `sidebars.ts` should match file paths without extensions
+- Use `type: 'doc'` with custom labels when the sidebar label differs from the document title
+- Group related documents under categories with descriptive labels

apps/kilocode-docs/.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "markdown.editor.filePaste.copyIntoWorkspace": "mediaFiles",
+    "markdown.copyFiles.destination": {
+      "**/*": "/static/img/${documentBaseName}/${documentBaseName}.${fileName/(.*)\\.(.*)/$2/}"
+    }
+  }

apps/kilocode-docs/.vscode/tasks.json

@@ -0,0 +1,19 @@
+{
+	"version": "2.0.0",
+	"tasks": [
+		{
+			"type": "npm",
+			"script": "start",
+			"problemMatcher": [],
+			"label": "npm: start",
+			"detail": "node -r dotenv/config node_modules/.bin/docusaurus start --host 0.0.0.0"
+		},
+		{
+			"type": "npm",
+			"script": "build",
+			"problemMatcher": [],
+			"label": "npm: build",
+			"detail": "Build the Docusaurus site for production"
+		}
+	]
+}

apps/kilocode-docs/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

apps/kilocode-docs/README.md

@@ -0,0 +1,17 @@
+# Kilo Code Docs
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator, and lives at https://kilocode.ai/docs
+
+### Installation
+
+```
+$ npm install
+```
+
+### Local Development
+
+```
+$ npm start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

apps/kilocode-docs/blog-posts/auto-generate-commit-messages.md

@@ -0,0 +1,106 @@
+# Why I Let AI Write My Commit Messages
+### And Probably You Should Too
+
+I've just finished implementing a big feature, the code is staged and ready to go, but there I am — mesmerized by the empty commit message field, brain is blank. What do I write? "Fixed stuff"? "Updates"? "asdf"? Do you know that feeling too?
+
+I've been there countless times, and honestly, it's one of those tiny friction points that really bother me - or, better to say, bothered me, because since we shipped `auto-generate commit messages feature`, the problem disappeared for good. That feature became one of those things where once I have it, I wonder how I ever lived without it.
+
+## The Problem with Commit Messages
+
+**Writing good commit messages is hard.** Like, genuinely difficult. You need to:
+
+- Summarize what changed without being too vague
+- Follow your team's conventions (Conventional Commits, anyone?)
+- Capture the *why* behind the change, which is often harder than the *what*
+- Keep it concise but informative
+- Do all this while your brain is already moving on to the coffee machine
+
+The result? Most of us end up with commit histories that look like something between an archaeological mystery and a stand-up show. Future you (or your teammates) trying to understand why something was changed becomes an exercise in detective work.
+
+## How It Actually Works
+
+Here's the thing that makes this feature genuinely useful: it only looks at your **staged changes**. Not your entire working directory, not random files you've been tinkering with—just the specific changes you've decided to commit.
+
+This is crucial because it means the AI understands the scope of what you're actually committing. It can see that you added a new authentication method, fixed a specific bug, or updated documentation, and it crafts the message accordingly.
+
+The process is dead simple:
+1. Stage your changes (like you normally would)
+2. Click the Kilo Code logo next to the commit message field
+3. Get a properly formatted commit message - automagically!
+
+<img src="https://kilocode.ai/docs/img/git-commit-generation/git-commit-1.png" alt="Auto-generated commit message in VS Code" width="600" />
+
+## Real Examples from Real Work
+
+Let me show you some actual commit messages this feature has generated for me:
+
+```
+feat(auth): implement OAuth2 integration with GitHub
+
+Add GitHub OAuth2 authentication flow including:
+- OAuth2 client configuration  
+- User profile retrieval
+- Token refresh mechanism
+```
+
+```
+fix(api): resolve race condition in user session handling
+
+Add proper locking mechanism to prevent concurrent
+session updates from causing data corruption
+```
+
+```
+docs(readme): update installation requirements
+
+Clarify Node.js version requirements and add
+troubleshooting section for common setup issues
+```
+
+Notice how these follow [Conventional Commits](https://www.conventionalcommits.org/) format by default? That's not an accident. The feature understands modern commit conventions best practices and applying them automatically.
+
+## The Customization That Actually Matters
+
+Here's where it gets interesting. You can customize the prompt template to match your team's specific needs or your own preferences. Don't want to be "too conventional" or just have your own standards? Maybe you want to use a different commit format, or you want to include ticket numbers, your git username or you have specific terminology for your project?
+
+Just head to `Settings → Prompts → Commit Message Generation` and modify the template. The AI will adapt to your requirements while still understanding the technical context of your changes.
+
+<img src="https://kilocode.ai/docs/img/git-commit-generation/git-commit-2.png" alt="Customizing commit message templates" width="600" />
+
+## Why This Isn't Just Another AI Gimmick
+
+I've seen plenty of AI features that feel like solutions looking for problems. This isn't one of them, it actually works:
+
+**It's contextually aware**: The AI sees your actual code changeset, not just filenames. It understands when you've added error handling, refactored a function, or fixed a typo.
+
+**It respects your workflow**: You still stage changes the same way. You still review and edit the message if needed. It just removes the blank-page problem.
+
+**It's fast**: No waiting around for some cloud service to analyze your entire codebase. It's quick and focused.
+
+**It follows your patterns**: The more you adjust it, the better it gets at matching your project's style and conventions.
+
+## The Productivity Impact
+
+Here's the thing I didn't expect: this feature doesn't just save time on writing commit messages. It actually makes me commit more frequently and more conciously.
+
+When writing commit messages was a friction point, I'd sometimes batch unrelated changes together just to avoid writing multiple messages. Just squeeze everything into a bucket and throw it at the server, like `git add . && git commit -m "blablabla" && git push`. Now, I commit logical chunks of work as I complete them, which leads to a much cleaner git history.
+
+Better commit messages also mean better code reviews. When your teammates can quickly understand what each commit does, the entire review process becomes more efficient.
+
+## Getting Started
+
+The feature is available in Kilo Code since `v4.35` and became customizable in `v4.38`. Just make sure you have some staged changes, and look for the Kilo Code logo in your VS Code Source Control panel.
+
+Pro tip: Consider setting up a dedicated [API configuration profile](https://kilocode.ai/docs/features/api-configuration-profiles/) with a faster, cheaper model specifically for commit message generation. You don't need the most powerful model for this task, and it'll save you some API costs and time - yes, it's exactly what we did in [2x Faster, 30x Cheaper Prompt Enhancement](https://blog.kilocode.ai/p/2x-faster-prompt-enhancement-in-kilo)!
+
+## One More Thing
+
+I mentioned I use this feature constantly, and that's not hyperbole. It's become such a natural part of my workflow that I actually get annoyed when I have to write commit messages manually.
+
+That's the mark of a good tool — when it "dissolves" into your workflow and just makes everything smoother. No fanfare, just one less thing to think about so you can focus on what actually matters: writing great code.
+
+Give it a try. I think you'll find yourself wondering how you ever managed without it.
+
+---
+
+*Want to learn more about Kilo Code's commit message generation? Check out the [full documentation](https://kilocode.ai/docs/basic-usage/git-commit-generation/) I wrote for setup details. And let me know what you think about it or how could we improve it even more here in comments or on our [Discord Server](https://kilo.love/discord)!*

apps/kilocode-docs/docs/advanced-usage/available-tools/codebase-search.md

@@ -0,0 +1,240 @@
+# codebase_search
+
+:::warning Experimental Feature
+The `codebase_search` tool is that 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 experimental Codebase Indexing feature is properly configured:
+
+- **Feature Enabled**: Codebase Indexing must be enabled in experimental 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
+
+- **Experimental Feature**: Part of the experimental codebase indexing system
+- **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 0.4 similarity score
+- **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 (0.4) 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/docs/advanced-usage/custom-instructions.md

@@ -0,0 +1,43 @@
+# Custom Instructions
+
+Custom Instructions allow you to personalize how Kilo Code behaves, providing specific guidance that shapes responses, coding style, and decision-making processes.
+
+## What Are Custom Instructions?
+
+Custom Instructions define specific Extension behaviors, preferences, and constraints beyond Kilo's basic role definition. Examples include coding style, documentation standards, testing requirements, and workflow guidelines.
+
+:::info Custom Instructions vs Rules
+Custom Instructions are IDE-wide and are applied across all workspaces and maintain your preferences regardless of which project you're working on. Unlike Instructions, [Custom Rules](/advanced-usage/custom-rules.md) are project specific and allow you to setup workspace-based ruleset.
+:::
+
+## Setting Custom Instructions
+
+**How to set them:**
+
+<img src="/docs/img/custom-instructions/custom-instructions.png" alt="Kilo Code Modes tab showing global custom instructions interface" width="600" />
+1.  **Open Modes Tab:** Click the <Codicon name="organization" /> icon in the Kilo Code top menu bar
+2.  **Find Section:** Find the "Custom Instructions for All Modes" section
+3.  **Enter Instructions:** Enter your instructions in the text area
+4.  **Save Changes:** Click "Done" to save your changes
+
+#### Mode-Specific Instructions
+
+Mode-specific instructions can be set using the Modes Tab
+
+    <img src="/docs/img/custom-instructions/custom-instructions-3.png" alt="Kilo Code Modes tab showing mode-specific custom instructions interface" width="600" />
+    * **Open Tab:** Click the <Codicon name="organization" /> icon in the Kilo Code top menu bar
+    * **Select Mode:** Under the Modes heading, click the button for the mode you want to customize
+    * **Enter Instructions:** Enter your instructions in the text area under "Mode-specific Custom Instructions (optional)"
+    * **Save Changes:** Click "Done" to save your changes
+
+        :::info Global Mode Rules
+        If the mode itself is global (not workspace-specific), any custom instructions you set for it will also apply globally for that mode across all workspaces.
+        :::
+
+
+## Related Features
+
+- [Custom Modes](/docs/features/custom-modes)
+- [Custom Rules](/advanced-usage/custom-rules)
+- [Settings Management](/docs/features/settings-management)
+- [Auto-Approval Settings](/docs/features/auto-approving-actions)

apps/kilocode-docs/docs/advanced-usage/custom-rules.md

@@ -0,0 +1,214 @@
+# Custom Rules
+
+Custom rules provide a powerful way to define project-specific and global behaviors and constraints for the Kilo Code AI agent. With custom rules, you can ensure consistent formatting, restrict access to sensitive files, enforce coding standards, and customize the AI's behavior for your specific project needs or across all projects.
+
+## Overview
+
+Custom rules allow you to create text-based instructions that all AI models will follow when interacting with your project. These rules act as guardrails and conventions that are consistently respected across all interactions with your codebase. Rules can be managed through both the file system and the built-in UI interface.
+
+## Rule Format
+
+Custom rules can be written in plain text, but Markdown format is recommended for better structure and comprehension by the AI models. The structured nature of Markdown helps the models parse and understand your rules more effectively.
+
+- Use Markdown headers (`#`, `##`, etc.) to define rule categories
+- Use lists (`-`, `*`) to enumerate specific items or constraints
+- Use code blocks (``` ```) to include code examples when needed
+
+## Rule Types
+
+Kilo Code supports two types of custom rules:
+
+- **Project Rules**: Apply only to the current project workspace
+- **Global Rules**: Apply across all projects and workspaces
+
+:::note UI Support
+The built-in rules management UI is available for general rules only. Mode-specific rules must be managed through the file system.
+:::
+
+## Rule Location
+
+### Project Rules
+
+Custom rules are primarily loaded from the **`.kilocode/rules/` directory**. This is the recommended approach for organizing your project-specific rules. Each rule is typically placed in its own Markdown file with a descriptive name:
+
+```
+project/
+├── .kilocode/
+│   ├── rules/
+│   │   ├── formatting.md
+│   │   ├── restricted_files.md
+│   │   └── naming_conventions.md
+├── src/
+└── ...
+```
+
+### Global Rules
+
+Global rules are stored in your home directory and apply to all projects:
+
+```
+~/.kilocode/
+├── rules/
+│   ├── coding_standards.md
+│   ├── security_guidelines.md
+│   └── documentation_style.md
+```
+
+## Managing Rules Through the UI
+
+Kilo Code provides a built-in interface for managing your custom rules without manually editing files in the `.kilocode/rules/` directories. To access the UI, click on the <Codicon name="law" /> icon in the **bottom right corner** of the Kilo Code window.
+
+You can access the rules management UI to:
+
+- View all active rules (both project and global)
+- Toggle rules on/off without deleting them
+- Create and edit rules directly in the interface
+- Organize rules by category and priority
+
+## Rule Loading Order
+
+### General Rules (Any Mode)
+
+Rules are loaded in the following priority order:
+
+1. **Global rules** from `~/.kilocode/rules/` directory
+2. **Project rules** from `.kilocode/rules/` directory
+3. **Legacy fallback files** (for backward compatibility):
+   - `.roorules`
+   - `.clinerules`
+   - `.kilocoderules` (deprecated)
+
+When both global and project rules exist, they are combined with project rules taking precedence over global rules for conflicting directives.
+
+:::note
+We strongly recommend keeping your rules in the `.kilocode/rules/` folder as it provides better organization and is the preferred approach for future versions. The folder-based structure allows for more granular rule organization and clearer separation of concerns. The legacy file-based approach is maintained for backward compatibility but may be subject to change in future releases.
+:::
+
+### Mode-Specific Rules
+
+Additionally, the system supports mode-specific rules, which are loaded separately and have their own priority order:
+
+1. First, it checks for `.kilocode/rules-${mode}/` directory
+2. If that doesn't exist or is empty, it falls back to `.kilocoderules-${mode}` file (deprecated)
+
+Currently, mode-specific rules are only supported at the project level.
+When both generic rules and mode-specific rules exist, the mode-specific rules are given priority in the final output.
+
+## Creating Custom Rules
+
+### Using the UI Interface
+
+<img src="/docs/img/custom-rules/rules-ui.png" alt="Rules tab in Kilo Code" width="400" />
+
+The easiest way to create and manage rules is through the built-in UI:
+
+1. Access the rules management interface from the Kilo Code panel
+2. Choose between creating project-specific or global rules
+3. Use the interface to create, edit, or toggle rules
+4. Rules are automatically saved and applied immediately
+
+### Using the File System
+
+To create rules manually:
+
+**For Project Rules:**
+1. Create the `.kilocode/rules/` directory if it doesn't already exist
+2. Create a new Markdown file with a descriptive name in this directory
+3. Write your rule using Markdown formatting
+4. Save the file
+
+**For Global Rules:**
+1. Create the `~/.kilocode/rules/` directory if it doesn't already exist
+2. Create a new Markdown file with a descriptive name in this directory
+3. Write your rule using Markdown formatting
+4. Save the file
+
+Rules will be automatically applied to all future Kilo Code interactions. Any new changes will be applied immediately.
+
+## Example Rules
+
+### Example 1: Table Formatting
+
+```markdown
+# Tables
+When printing tables, always add an exclamation mark to each column header
+```
+
+This simple rule instructs the AI to add exclamation marks to all table column headers when generating tables in your project.
+
+### Example 2: Restricted File Access
+
+```markdown
+# Restricted files
+Files in the list contain sensitive data, they MUST NOT be read
+- supersecrets.txt
+- credentials.json
+- .env
+```
+
+This rule prevents the AI from reading or accessing sensitive files, even if explicitly requested to do so.
+
+<img src="/docs/img/custom-rules/custom-rules.png" alt="Kilo Code ignores request to read sensitive file" width="600" />
+
+## Use Cases
+
+Custom rules can be applied to a wide variety of scenarios:
+
+- **Code Style**: Enforce consistent formatting, naming conventions, and documentation styles
+- **Security Controls**: Prevent access to sensitive files or directories
+- **Project Structure**: Define where different types of files should be created
+- **Documentation Requirements**: Specify documentation formats and requirements
+- **Testing Patterns**: Define how tests should be structured
+- **API Usage**: Specify how APIs should be used and documented
+- **Error Handling**: Define error handling conventions
+
+## Examples of Custom Rules
+
+* "Strictly follow code style guide [your project-specific code style guide]"
+* "Always use spaces for indentation, with a width of 4 spaces"
+* "Use camelCase for variable names"
+* "Write unit tests for all new functions"
+* "Explain your reasoning before providing code"
+* "Focus on code readability and maintainability"
+* "Prioritize using the most common library in the community"
+* "When adding new features to websites, ensure they are responsive and accessible"
+
+## Best Practices
+
+- **Be Specific**: Clearly define the scope and intent of each rule
+- **Use Categories**: Organize related rules under common headers
+- **Separate Concerns**: Use different files for different types of rules
+- **Use Examples**: Include examples to illustrate the expected behavior
+- **Keep It Simple**: Rules should be concise and easy to understand
+- **Update Regularly**: Review and update rules as project requirements change
+
+:::tip Pro Tip: File-Based Team Standards
+When working in team environments, placing `.kilocode/rules/codestyle.md` files under version control allows you to standardize Kilo's behavior across your entire development team. This ensures consistent code style, documentation practices, and development workflows for everyone on the project.
+:::
+
+## Limitations
+
+- Rules are applied on a best-effort basis by the AI models
+- Complex rules may require multiple examples for clear understanding
+- Project rules apply only to the project in which they are defined
+- Global rules apply across all projects
+
+## Troubleshooting
+
+If your custom rules aren't being properly followed:
+
+1. **Check rule status in the UI**: Use the rules management interface to verify that your rules are active and properly loaded
+1. **Verify rule formatting**: Ensure that your rules are properly formatted with clear Markdown structure
+1. **Check rule locations**: Ensure that your rules are located in supported locations:
+   - Global rules: `~/.kilocode/rules/` directory
+   - Project rules: `.kilocode/rules/` directory
+   - Legacy files: `.kilocoderules`, `.roorules`, or `.clinerules`
+1. **Rule specificity**: Verify that the rules are specific and unambiguous
+1. **Restart VS Code**: Restart VS Code to ensure the rules are properly loaded
+
+## Related Features
+
+- [Custom Modes](/docs/features/custom-modes)
+- [Custom Instructions](/advanced-usage/custom-instructions)
+- [Settings Management](/docs/features/settings-management)
+- [Auto-Approval Settings](/docs/features/auto-approving-actions)

apps/kilocode-docs/docs/advanced-usage/free-and-budget-models.md

@@ -0,0 +1,279 @@
+---
+sidebar_label: Free & Budget Models
+---
+
+# Using Kilo Code for Free and on a Budget
+
+**Why this matters:** AI model costs can add up quickly during development. This guide shows you how to use Kilo Code effectively while minimizing or eliminating costs through free models, budget-friendly alternatives, and smart usage strategies.
+
+## Completely Free Options
+
+### OpenRouter Free Tier Models
+
+OpenRouter offers several models with generous free tiers. **Note:** You'll need to create a free OpenRouter account to access these models.
+
+**Setup:**
+
+1. Create a free [OpenRouter account](https://openrouter.ai)
+2. Get your API key from the dashboard
+3. Configure Kilo Code with the OpenRouter provider
+
+**Available free models:**
+
+- **Qwen3 Coder (free)** - Optimized for agentic coding tasks such as function calling, tool use, and long-context reasoning over repositories. 
+- **Z.AI: GLM 4.5 Air (free)** - Lightweight variant of the GLM-4.5 family, purpose-built for agent-centric applications. 
+- **DeepSeek: R1 0528 (free)** - Performance on par with OpenAI o1, but open-sourced and with fully open reasoning tokens.
+- **MoonshotAI: Kimi K2 (free)** - Optimized for agentic capabilities, including advanced tool use, reasoning, and code synthesis.
+
+## Cost-Effective Premium Models
+
+When you need more capability than free models provide, these options deliver excellent value:
+
+### Ultra-Budget Champions (Under $0.50 per million tokens)
+
+**Mistral Devstral Small**
+
+- **Cost:** ~$0.20 per million input tokens
+- **Best for:** Code generation, debugging, refactoring
+- **Performance:** 85% of premium model capability at 10% of the cost
+
+**Llama 4 Maverick**
+
+- **Cost:** ~$0.30 per million input tokens
+- **Best for:** Complex reasoning, architecture planning
+- **Performance:** Excellent for most development tasks
+
+**DeepSeek v3**
+
+- **Cost:** ~$0.27 per million input tokens
+- **Best for:** Code analysis, large codebase understanding
+- **Performance:** Strong technical reasoning
+
+### Mid-Range Value Models ($0.50-$2.00 per million tokens)
+
+**Qwen3 235B**
+
+- **Cost:** ~$1.20 per million input tokens
+- **Best for:** Complex projects requiring high accuracy
+- **Performance:** Near-premium quality at 40% of the cost
+
+## Smart Usage Strategies
+
+### The 50% Rule
+
+**Principle:** Use budget models for 50% of your tasks, premium models for the other 50%.
+
+**Budget model tasks:**
+
+- Code reviews and analysis
+- Documentation writing
+- Simple bug fixes
+- Boilerplate generation
+- Refactoring existing code
+
+**Premium model tasks:**
+
+- Complex architecture decisions
+- Debugging difficult issues
+- Performance optimization
+- New feature design
+- Critical production code
+
+### Context Management for Cost Savings
+
+**Minimize context size:**
+
+```typescript
+// Instead of mentioning entire files
+@src/components/UserProfile.tsx
+
+// Mention specific functions or sections
+@src/components/UserProfile.tsx:45-67
+```
+
+**Use Memory Bank effectively:**
+
+- Store project context once in [Memory Bank](/advanced-usage/memory-bank)
+- Reduces need to re-explain project details
+- Saves 200-500 tokens per conversation
+
+**Strategic file mentions:**
+
+- Only include files directly relevant to the task
+- Use [`@folder/`](/basic-usage/context-mentions) for broad context, specific files for targeted work
+
+### Model Switching Strategies
+
+**Start cheap, escalate when needed:**
+
+1. **Begin with free models** (Qwen3 Coder, GLM-4.5-Air)
+2. **Switch to budget models** if free models struggle
+3. **Escalate to premium models** only for complex tasks
+
+**Use API Configuration Profiles:**
+
+- Set up [multiple profiles](/features/api-configuration-profiles) for different cost tiers
+- Quick switching between free, budget, and premium models
+- Match model capability to task complexity
+
+### Mode-Based Cost Optimization
+
+**Use appropriate modes to limit expensive operations:**
+
+- **[Ask Mode](/basic-usage/using-modes#ask-mode):** Information gathering without code changes
+- **[Architect Mode](/basic-usage/using-modes#architect-mode):** Planning without expensive file operations
+- **[Debug Mode](/basic-usage/using-modes#debug-mode):** Focused troubleshooting
+
+**Custom modes for budget control:**
+
+- Create modes that restrict expensive tools
+- Limit file access to specific directories
+- Control which operations are auto-approved
+
+## Real-World Performance Comparisons
+
+### Code Generation Tasks
+
+**Simple function creation:**
+
+- **Mistral Devstral Small:** 95% success rate
+- **GPT-4:** 98% success rate
+- **Cost difference:** Free vs $0.20 vs $30 per million tokens
+
+**Complex refactoring:**
+
+- **Budget models:** 70-80% success rate
+- **Premium models:** 90-95% success rate
+- **Recommendation:** Start with budget, escalate if needed
+
+### Debugging Performance
+
+**Simple bugs:**
+
+- **Free models:** Usually sufficient
+- **Budget models:** Excellent performance
+- **Premium models:** Overkill for most cases
+
+**Complex system issues:**
+
+- **Free models:** 40-60% success rate
+- **Budget models:** 60-80% success rate
+- **Premium models:** 85-95% success rate
+
+## Hybrid Approach Recommendations
+
+### Daily Development Workflow
+
+**Morning planning session:**
+
+- Use **Architect mode** with **DeepSeek R1**
+- Plan features and architecture
+- Create task breakdowns
+
+**Implementation phase:**
+
+- Use **Code mode** with **budget models**
+- Generate and modify code
+- Handle routine development tasks
+
+**Complex problem solving:**
+
+- Switch to **premium models** when stuck
+- Use for critical debugging
+- Architecture decisions affecting multiple systems
+
+### Project Phase Strategy
+
+**Early development:**
+
+- Free and budget models for prototyping
+- Rapid iteration without cost concerns
+- Establish patterns and structure
+
+**Production preparation:**
+
+- Premium models for critical code review
+- Performance optimization
+- Security considerations
+
+## Cost Monitoring and Control
+
+### Track Your Usage
+
+**Monitor token consumption:**
+
+- Check cost estimates in chat history
+- Review monthly usage patterns
+- Identify high-cost operations
+
+**Set spending limits:**
+
+- Use provider billing alerts
+- Configure [rate limits](/advanced-usage/rate-limits-costs) to control usage
+- Set daily/monthly budgets
+
+### Cost-Saving Tips
+
+**Reduce system prompt size:**
+
+- [Disable MCP](/features/mcp/using-mcp-in-kilo-code) if not using external tools
+- Use focused custom modes
+- Minimize unnecessary context
+
+**Optimize conversation length:**
+
+- Use [Checkpoints](/features/checkpoints) to reset context
+- Start fresh conversations for unrelated tasks
+- Archive completed work
+
+**Batch similar tasks:**
+
+- Group related code changes
+- Handle multiple files in single requests
+- Reduce conversation overhead
+
+## Getting Started with Budget Models
+
+### Quick Setup Guide
+
+1. **Create OpenRouter account** for free models
+2. **Configure multiple providers** in Kilo Code
+3. **Set up API Configuration Profiles** for easy switching
+5. **Escalate to budget models** when needed
+6. **Reserve premium models** for complex work
+
+### Recommended Provider Mix
+
+**Free tier foundation:**
+
+- [OpenRouter](/providers/openrouter) - Free models
+- [Groq](/providers/groq) - Fast inference for supported models
+- [Z.ai](https://z.ai/model-api) - Provides a free model GLM-4.5-Flash
+
+**Budget tier options:**
+
+- [DeepSeek](/providers/deepseek) - Excellent value models
+- [Mistral](/providers/mistral) - Specialized coding models
+
+**Premium tier backup:**
+
+- [Anthropic](/providers/anthropic) - Claude for complex reasoning
+- [OpenAI](/providers/openai) - GPT-4 for critical tasks
+
+## Measuring Success
+
+**Track these metrics:**
+
+- Monthly AI costs vs. development productivity
+- Task completion rates by model tier
+- Time saved vs. money spent
+- Code quality improvements
+
+**Success indicators:**
+
+- 70%+ of tasks completed with free/budget models
+- Monthly costs under your target budget
+- Maintained or improved code quality
+- Faster development cycles
+
+By combining free models, strategic budget model usage, and smart optimization techniques, you can harness the full power of AI-assisted development while keeping costs minimal. Start with free options and gradually incorporate budget models as your needs and comfort with costs grow.

apps/kilocode-docs/docs/advanced-usage/large-projects.md

@@ -0,0 +1,46 @@
+# Working with Large Projects
+
+Kilo Code can be used with projects of any size, but large projects require some extra care to manage context effectively. Here are some tips for working with large codebases:
+
+## Understanding Context Limits
+
+Kilo Code uses large language models (LLMs) that have a limited "context window."  This is the maximum amount of text (measured in tokens) that the model can process at once.  If the context is too large, the model may not be able to understand your request or generate accurate responses.
+
+The context window includes:
+
+*   The system prompt (instructions for Kilo Code).
+*   The conversation history.
+*   The content of any files you mention using `@`.
+*   The output of any commands or tools Kilo Code uses.
+
+## Strategies for Managing Context
+
+1.  **Be Specific:**  When referring to files or code, use specific file paths and function names.  Avoid vague references like "the main file."
+
+2.  **Use Context Mentions Effectively:** Use `@/path/to/file.ts` to include specific files. Use `@problems` to include current errors and warnings.  Use `@` followed by a commit hash to reference specific Git commits.
+
+3.  **Break Down Tasks:** Divide large tasks into smaller, more manageable sub-tasks.  This helps keep the context focused.
+
+4.  **Summarize:**  If you need to refer to a large amount of code, consider summarizing the relevant parts in your prompt instead of including the entire code.
+
+5.  **Prioritize Recent History:** Kilo Code automatically truncates older messages in the conversation history to stay within the context window. Be mindful of this, and re-include important context if needed.
+
+6.  **Use Prompt Caching (if available):** Some API providers like Anthropic, OpenAI, OpenRouter and Requesty support "prompt caching". This caches your prompts for use in future tasks and helps reduce the cost and latency of requests.
+
+## Example: Refactoring a Large File
+
+Let's say you need to refactor a large TypeScript file (`src/components/MyComponent.tsx`).  Here's a possible approach:
+
+1.  **Initial Overview:**
+    ```
+    @/src/components/MyComponent.tsx List the functions and classes in this file.
+    ```
+
+2.  **Target Specific Functions:**
+    ```
+    @/src/components/MyComponent.tsx Refactor the `processData` function to use `async/await` instead of Promises.
+    ```
+
+3.  **Iterative Changes:**  Make small, incremental changes, reviewing and approving each step.
+
+By breaking down the task and providing specific context, you can work effectively with large files even with a limited context window.

apps/kilocode-docs/docs/advanced-usage/local-models.md

@@ -0,0 +1,38 @@
+# Using Local Models
+
+Kilo Code supports running language models locally on your own machine using [Ollama](https://ollama.com/) and [LM Studio](https://lmstudio.ai/).  This offers several advantages:
+
+*   **Privacy:** Your code and data never leave your computer.
+*   **Offline Access:**  You can use Kilo Code even without an internet connection.
+*   **Cost Savings:**  Avoid API usage fees associated with cloud-based models.
+*   **Customization:**  Experiment with different models and configurations.
+
+**However, using local models also has some drawbacks:**
+
+*   **Resource Requirements:**  Local models can be resource-intensive, requiring a powerful computer with a good CPU and, ideally, a dedicated GPU.
+*   **Setup Complexity:**  Setting up local models can be more complex than using cloud-based APIs.
+*   **Model Performance:**  The performance of local models can vary significantly. While some are excellent, they may not always match the capabilities of the largest, most advanced cloud models.
+* **Limited Features**: Local models (and many online models) often do not support advanced features such as prompt caching, computer use, and others.
+
+## Supported Local Model Providers
+
+Kilo Code currently supports two main local model providers:
+
+1.  **Ollama:**  A popular open-source tool for running large language models locally.  It supports a wide range of models.
+2.  **LM Studio:**  A user-friendly desktop application that simplifies the process of downloading, configuring, and running local models.  It also provides a local server that emulates the OpenAI API.
+
+## Setting Up Local Models
+
+For detailed setup instructions, see:
+* [Setting up Ollama](/providers/ollama)
+* [Setting up LM Studio](/providers/lmstudio)
+
+Both providers offer similar capabilities but with different user interfaces and workflows. Ollama provides more control through its command-line interface, while LM Studio offers a more user-friendly graphical interface.
+
+## Troubleshooting
+
+*   **"No connection could be made because the target machine actively refused it":**  This usually means that the Ollama or LM Studio server isn't running, or is running on a different port/address than Kilo Code is configured to use.  Double-check the Base URL setting.
+
+*   **Slow Response Times:** Local models can be slower than cloud-based models, especially on less powerful hardware.  If performance is an issue, try using a smaller model.
+
+*   **Model Not Found:** Ensure you have typed in the name of the model correctly. If you're using Ollama, use the same name that you provide in the `ollama run` command.

apps/kilocode-docs/docs/advanced-usage/memory-bank.md

@@ -0,0 +1,297 @@
+# Memory Bank
+
+## Overview
+
+<figure style={{ float: 'right', width: '40%', maxWidth: '350px', margin: '0 0 10px 20px' }}>
+  <img src="/docs/img/memory-bank/at-work.png" alt="Executing task with the memory bank" style={{ border: '1px solid grey', borderRadius: '5px', width: '100%' }} />
+  <figcaption style={{ fontSize: '0.9rem', color: '#666', marginTop: '8px', textAlign: 'center' }}>
+    Kilo Code works more efficiently with Memory Bank enabled, instantly understanding project context and technologies.
+  </figcaption>
+</figure>
+
+### The Problem: AI Memory Loss
+
+AI assistants like Kilo Code face a fundamental limitation: they reset completely between sessions. This "memory loss" means that every time you start a new conversation, you need to re-explain your project's architecture, goals, technologies, and current status. This creates a critical efficiency dilemma: AI models either make edits without proper project understanding (leading to errors and misaligned solutions), or must spend significant time and resources analyzing your entire codebase in each session (which is prohibitively expensive and slow for larger projects)
+
+Without a solution to this memory problem, AI assistants remain powerful but stateless tools that can't truly function as persistent development partners.
+
+### The Solution: Memory Bank
+
+Memory Bank is a system of structured documentation that enables Kilo Code to **better understand your project** and **maintain context across coding sessions**. It transforms your AI assistant from a stateless tool into a persistent development partner with perfect recall of your project details. Kilo Code automatically reads your Memory Bank files to rebuild its understanding of your project whenever you start a new session.
+
+When Memory Bank is active, Kilo Code begins each task with `[Memory Bank: Active]` and a brief summary of your project context, ensuring consistent understanding without repetitive explanations.
+
+## Key Benefits
+
+- **Language Agnostic**: Functions with any programming language or framework
+- **Efficient Project Understanding**: Helps Kilo Code understand the purpose and tech stack of a project
+- **Context Preservation**: Maintain project knowledge across sessions without needing to scan files in every new session
+- **Faster Startup**: Kilo Code immediately comprehends your project context when you begin a new session
+- **Self-Documenting Projects**: Create valuable documentation as a byproduct
+
+## How Memory Bank Works
+
+Memory Bank is built on Kilo Code's [Custom Rules](/advanced-usage/custom-rules) feature, providing a specialized framework for project documentation. Memory Bank files are standard markdown files stored in `.kilocode/rules/memory-bank` folder within your project repository. They're not hidden or proprietary - they're regular documentation files that both you and Kilo Code can access.
+
+At the start of every task, Kilo Code reads all Memory Bank files to build a comprehensive understanding of your project. This happens automatically without requiring any action from you. Kilo Code then indicates successful Memory Bank activation with `[Memory Bank: Active]` at the beginning of its response, followed by a brief summary of its understanding of your project.
+
+Files are organized in a hierarchical structure that builds a complete picture of your project:
+
+## Core Memory Bank Files
+
+### brief.md
+*This file is created and maintained manually by you*
+- The foundation of your project
+- High-level overview of what you're building
+- Core requirements and goals
+
+Example: *"Building a React web app for inventory management with barcode scanning. The system needs to support multiple warehouses and integrate with our existing ERP system."*
+
+Note: Kilo Code will not edit this file directly but may suggest improvements if it identifies ways to enhance your project brief.
+
+### product.md
+- Explains why the project exists
+- Describes the problems being solved
+- Outlines how the product should work
+- User experience goals
+
+Example: *"The inventory system needs to support multiple warehouses and real-time updates. It solves the problem of inventory discrepancies by providing barcode scanning for accurate stock counts."*
+
+### context.md
+- The most frequently updated file
+- Contains current work focus and recent changes
+- Tracks active decisions and considerations
+- Next steps for development
+
+Example: *"Currently implementing the barcode scanner component; last session completed the API integration. Next steps include adding error handling for network failures."*
+
+### architecture.md
+- Documents the system architecture
+- Records key technical decisions
+- Lists design patterns in use
+- Explains component relationships
+- Critical implementation paths
+
+Example: *"Using Redux for state management with a normalized store structure. The application follows a modular architecture with separate services for API communication, state management, and UI components."*
+
+### tech.md
+- Lists technologies and frameworks used
+- Describes development setup
+- Notes technical constraints
+- Records dependencies and tool configurations
+- Tool usage patterns
+
+Example: *"React 18, TypeScript, Firebase, Jest for testing. Development requires Node.js 16+ and uses Vite as the build tool."*
+
+## Additional Context Files
+
+Create additional files as needed to organize:
+- Complex feature documentation
+- Integration specifications
+- API documentation
+- Testing strategies
+- Deployment procedures
+
+These additional files help organize more detailed information that doesn't fit neatly into the core files.
+
+### tasks.md
+*Optional file for documenting repetitive tasks*
+- Stores workflows for tasks that follow similar patterns
+- Documents which files need to be modified
+- Captures step-by-step procedures
+- Records important considerations and gotchas
+
+Example: Adding support for new AI models, implementing API endpoints, or any task that requires doing similar jobs repeatedly.
+
+## Getting Started with Memory Bank
+
+### First-Time Setup
+
+1. Create a `.kilocode/rules/memory-bank/` folder in your project
+2. Write a basic project brief in `.kilocode/rules/memory-bank/brief.md`
+3. Create a file `.kilocode/rules/memory-bank-instructions.md` and paste there [this document](pathname:///downloads/memory-bank.md)
+4. Switch to `Architect` mode
+5. Check if a best available AI model is selected, don't use "lightweight" models
+6. Ask Kilo Code to "initialize memory bank"
+7. Wait for Kilo Code to analyze your project and initialize the Memory Bank files
+8. Verify the content of the files to see if the project is described correctly. Update the files if necessary.
+
+### Project Brief Tips
+
+- Start simple - it can be as detailed or high-level as you like
+- Focus on what matters most to you
+- Kilo Code will help fill in gaps and ask questions
+- You can update it as your project evolves
+
+Sample prompt that delivers a reasonably good brief:
+
+```
+Provide a concise and comprehensive description of this project, highlighting its main objectives, key features, used technologies and significance. Then, write this description into a text file named appropriately to reflect the project's content, ensuring clarity and professionalism in the writing. Stay brief and short.
+```
+
+## Working with Memory Bank
+
+### Core Workflows
+
+#### Memory Bank Initialization
+
+The initialization step is critically important as it establishes the foundation for all future interactions with your project. When you request initialization with the command `initialize memory bank`, Kilo Code will:
+
+1. Perform an exhaustive analysis of your project, including:
+   - All source code files and their relationships
+   - Configuration files and build system setup
+   - Project structure and organization patterns
+   - Documentation and comments
+   - Dependencies and external integrations
+   - Testing frameworks and patterns
+2. Create comprehensive memory bank files in the `.kilocode/rules/memory-bank` folder
+3. Provide a detailed summary of what it has understood about your project
+4. Ask you to verify the accuracy of the generated files
+
+:::warning Important
+Take time to carefully review and correct the generated files after initialization. Any misunderstandings or missing information at this stage will affect all future interactions. A thorough initialization dramatically improves Kilo Code's effectiveness, while a rushed or incomplete initialization will permanently limit its ability to assist you effectively.
+:::
+
+#### Memory Bank Updates
+
+Memory Bank updates occur when:
+1. Kilo Code discovers new project patterns
+2. After implementing significant changes
+3. When you explicitly request with `update memory bank`
+4. When context needs clarification
+
+To execute a Memory Bank update, Kilo Code will:
+1. Review ALL project files
+2. Document the current state
+3. Document insights and patterns
+4. Update all memory bank files as needed
+
+You can direct Kilo Code to focus on specific information sources by using commands like `update memory bank using information from @/Makefile`.
+
+#### Regular Task Execution
+
+At the beginning of every task, Kilo Code:
+1. Reads ALL memory bank files
+2. Includes `[Memory Bank: Active]` at the beginning of its response
+3. Provides a brief summary of its understanding of your project
+4. Proceeds with the requested task
+
+At the end of a task, Kilo Code may suggest updating the memory bank if significant changes were made, using the phrase: "Would you like me to update memory bank to reflect these changes?"
+
+#### Add Task Workflow
+
+When you complete a repetitive task that follows a similar pattern each time, you can document it for future reference. This is particularly useful for tasks like adding features that follow existing patterns
+
+To document a task, use the command `add task` or `store this as a task`. Kilo Code will:
+1. Create or update the `tasks.md` file in the memory bank folder
+2. Document the task using current context:
+   - Task name and description
+   - List of files that need to be modified
+   - Step-by-step workflow
+   - Important considerations
+   - Example implementation
+
+When starting a new task, Kilo Code will check if it matches any documented tasks and follow the established workflow to ensure no steps are missed.
+
+### Key Commands
+
+- `initialize memory bank` - Use when starting a new project
+- `update memory bank` - Initiates a comprehensive re-analysis of the contextual documentation for the current task. **Caution:** This is resource-intensive and not recommended for "lightweight" models due to potentially reduced effectiveness. Can be used multiple times, well combinable with specific instructions, e.g. `update memory bank using information from @/Makefile`
+- `add task` or `store this as a task` - Documents a repetitive task for future reference
+
+### Status Indicators
+
+Kilo Code uses status indicators to clearly communicate Memory Bank status:
+
+- `[Memory Bank: Active]` - Indicates Memory Bank files were successfully read and are being used
+- `[Memory Bank: Missing]` - Indicates Memory Bank files could not be found or are empty
+
+These indicators appear at the beginning of Kilo Code's responses, providing immediate confirmation of Memory Bank status.
+
+### Documentation Updates
+
+Memory Bank updates should automatically occur when:
+- You discover new patterns in your project
+- After implementing significant changes
+- When you explicitly request with `update memory bank`
+- When you feel context needs clarification
+
+## Context Window Management
+
+As you work with Kilo Code, your context window will eventually fill up. When you notice responses slowing down or references becoming less accurate:
+
+1. Ask Kilo Code to "update memory bank" to document the current state
+2. Start a new conversation/task
+3. Kilo Code will automatically access your Memory Bank in the new conversation
+
+This process ensures continuity across multiple sessions without losing important context.
+
+## Handling Inconsistencies
+
+If Kilo Code detects inconsistencies between memory bank files:
+
+1. It will prioritize information from `brief.md` as the source of truth
+2. Note any discrepancies to you
+3. Continue working with the most reliable information available
+
+This ensures that even with imperfect documentation, Kilo Code can still function effectively.
+
+## Frequently Asked Questions
+
+### Where are the memory bank files stored?
+The Memory Bank files are regular markdown files stored in your project repository, typically in a `.kilocode/rules/memory-bank/` folder. They're not hidden system files - they're designed to be part of your project documentation.
+
+### How often should I update the memory bank?
+Update the Memory Bank after significant milestones or changes in direction. For active development, updates every few sessions can be helpful. Use the "update memory bank" command when you want to ensure all context is preserved.
+
+### Can I edit memory bank files manually?
+Yes! While Kilo Code manages most of the files, you can edit any of them manually. The `brief.md` file is specifically designed to be maintained by you. Manual edits to other files will be respected by Kilo Code.
+
+### What happens if memory bank files are missing?
+If memory bank files are missing, Kilo Code will indicate this with `[Memory Bank: Missing]` at the beginning of its response and suggest initializing the memory bank.
+
+### Does Memory Bank work with all AI models?
+Memory Bank works with all AI models, but more powerful models will create more comprehensive and accurate memory bank files. Lightweight models may struggle with the resource-intensive process of analyzing and updating memory bank files.
+
+### Can I use Memory Bank with multiple projects?
+Yes! Each project has its own Memory Bank in its `.kilocode/rules/memory-bank/` folder. Kilo Code will automatically use the correct Memory Bank for each project.
+
+### Doesn't Memory Bank use up my context window?
+Yes, Memory Bank does consume some of your context window at the beginning of each session as it loads all memory bank files. However, this is a strategic tradeoff that significantly improves overall efficiency. By front-loading project context:
+
+- You eliminate repetitive explanations that would consume even more context over time
+- You reach productive outcomes with fewer back-and-forth exchanges
+- You maintain consistent understanding throughout your session
+
+Testing shows that while Memory Bank uses more tokens initially, it dramatically reduces the total number of interactions needed to achieve results. This means less time explaining and more time building.
+
+## Best Practices
+
+### Getting Started
+- Start with a basic project brief and let the structure evolve
+- Let Kilo Code help create the initial structure
+- Review and adjust files as needed to match your workflow
+- Verify the accuracy of generated files after initialization
+
+### Ongoing Work
+- Let patterns emerge naturally as you work
+- Don't force documentation updates - they should happen organically
+- Trust the process - the value compounds over time
+- Watch for context confirmation at the start of sessions
+- Use the status indicators to confirm Memory Bank is active
+
+### Documentation Flow
+- `brief.md` is your foundation
+- `context.md` changes most frequently
+- All files collectively maintain project intelligence
+- Update after significant milestones or changes in direction
+
+### Optimizing Memory Bank Performance
+- Keep memory bank files concise and focused
+- Use additional files for detailed documentation
+- Update regularly but not excessively
+- Use specific update commands when focusing on particular aspects
+
+## Remember
+
+The Memory Bank is Kilo Code's only link to previous work. Its effectiveness depends entirely on maintaining clear, accurate documentation and confirming context preservation in every interaction. When you see `[Memory Bank: Active]` at the beginning of a response, you can be confident that Kilo Code has a comprehensive understanding of your project.

apps/kilocode-docs/docs/advanced-usage/prompt-engineering.md

@@ -0,0 +1,91 @@
+# Prompt Engineering Tips
+
+Prompt engineering is the art of crafting effective instructions for AI models like Kilo Code.  Well-written prompts lead to better results, fewer errors, and a more efficient workflow.
+
+## General Principles
+
+*   **Be Clear and Specific:** Clearly state what you want Kilo Code to do. Avoid ambiguity.
+    *   **Bad:** Fix the code.
+    *   **Good:** Fix the bug in the `calculateTotal` function that causes it to return incorrect results.
+
+*   **Provide Context:** Use [Context Mentions](/basic-usage/context-mentions) to refer to specific files, folders, or problems.
+    *   **Good:** `@/src/utils.ts` Refactor the `calculateTotal` function to use async/await.
+
+*   **Break Down Tasks:** Divide complex tasks into smaller, well-defined steps.
+
+*   **Give Examples:** If you have a specific coding style or pattern in mind, provide examples.
+
+*   **Specify Output Format:** If you need the output in a particular format (e.g., JSON, Markdown), specify it in the prompt.
+
+*   **Iterate:** Don't be afraid to refine your prompt if the initial results aren't what you expect.
+
+## Thinking vs. Doing
+
+It's often helpful to guide Kilo Code through a "think-then-do" process:
+
+1.  **Analyze:** Ask Kilo Code to analyze the current code, identify problems, or plan the approach.
+2.  **Plan:**  Have Kilo Code outline the steps it will take to complete the task.
+3.  **Execute:**  Instruct Kilo Code to implement the plan, one step at a time.
+4.  **Review:**  Carefully review the results of each step before proceeding.
+
+## Using Custom Instructions
+
+You can provide custom instructions to further tailor Kilo Code's behavior. There are two types of custom instructions:
+
+*   **Global Custom Instructions:** Apply to all modes.
+*   **Mode-Specific Custom Instructions:** Apply only to a specific mode (e.g., Code, Architect, Ask, Debug, or a custom mode).
+
+Custom instructions are added to the system prompt, providing persistent guidance to the AI model. You can use these to:
+
+*   Enforce coding style guidelines.
+*   Specify preferred libraries or frameworks.
+*   Define project-specific conventions.
+*   Adjust Kilo Code's tone or personality.
+
+See the [Custom Instructions](/advanced-usage/custom-instructions) section for more details.
+
+## Handling Ambiguity
+
+If your request is ambiguous or lacks sufficient detail, Kilo Code might:
+
+*   **Make Assumptions:**  It might proceed based on its best guess, which may not be what you intended.
+*   **Ask Follow-Up Questions:** It might use the `ask_followup_question` tool to clarify your request.
+
+It's generally better to provide clear and specific instructions from the start to avoid unnecessary back-and-forth.
+
+## Providing Feedback
+
+If Kilo Code doesn't produce the desired results, you can provide feedback by:
+
+*   **Rejecting Actions:** Click the "Reject" button when Kilo Code proposes an action you don't want.
+*   **Providing Explanations:** When rejecting, explain *why* you're rejecting the action.  This helps Kilo Code learn from its mistakes.
+*   **Rewording Your Request:** Try rephrasing your initial task or providing more specific instructions.
+*   **Manually Correcting:** If there are a few small issues, you can also directly modify the code before accepting the changes.
+
+## Examples
+
+**Good Prompt:**
+
+> `@/src/components/Button.tsx` Refactor the `Button` component to use the `useState` hook instead of the `useReducer` hook.
+
+**Bad Prompt:**
+
+> Fix the button.
+
+**Good Prompt:**
+
+> Create a new file named `utils.py` and add a function called `calculate_average` that takes a list of numbers and returns their average.
+
+**Bad Prompt:**
+
+> Write some Python code.
+
+**Good Prompt:**
+
+> `@problems` Address all errors and warnings in the current file.
+
+**Bad Prompt:**
+
+> Fix everything.
+
+By following these tips, you can write effective prompts that get the most out of Kilo Code's capabilities.

apps/kilocode-docs/docs/advanced-usage/rate-limits-costs.md

@@ -0,0 +1,51 @@
+# Rate Limits and Costs
+
+Understanding and managing API usage is crucial for a smooth and cost-effective experience with Kilo Code. This section explains how to track your token usage, costs, and how to configure rate limits.
+
+## Token Usage
+
+Kilo Code interacts with AI models using tokens.  Tokens are essentially pieces of words.  The number of tokens used in a request and response affects both the processing time and the cost.
+
+*   **Input Tokens:** These are the tokens in your prompt, including the system prompt, your instructions, and any context provided (e.g., file contents).
+*   **Output Tokens:** These are the tokens generated by the AI model in its response.
+
+You can see the number of input and output tokens used for each interaction in the chat history.
+
+## Cost Calculation
+
+Most AI providers charge based on the number of tokens used.  Pricing varies depending on the provider and the specific model.
+
+Kilo Code automatically calculates the estimated cost of each API request based on the configured model's pricing.  This cost is displayed in the chat history, next to the token usage.
+
+**Note:**
+
+*   The cost calculation is an *estimate*.  The actual cost may vary slightly depending on the provider's billing practices.
+*   Some providers may offer free tiers or credits.  Check your provider's documentation for details.
+*   Some providers offer prompt caching which greatly lowers cost.
+
+## Configuring Rate Limits
+
+To prevent accidental overuse of the API and to help you manage costs, Kilo Code allows you to set a rate limit.  The rate limit specifies the minimum time (in seconds) between API requests.
+
+**How to configure:**
+
+1.  Open the Kilo Code settings (<Codicon name="gear" /> icon in the top right corner).
+2.  Go to the "Advanced Settings" section.
+3.  Find the "Rate Limit (seconds)" setting.
+4.  Enter the desired delay in seconds.  A value of 0 disables rate limiting.
+
+**Example:**
+
+If you set the rate limit to 10 seconds, Kilo Code will wait at least 10 seconds after one API request completes before sending the next one.
+
+## Tips for Optimizing Token Usage
+
+*   **Be Concise:**  Use clear and concise language in your prompts. Avoid unnecessary words or details.
+*   **Provide Only Relevant Context:** Use context mentions (`@file.ts`, `@folder/`) selectively.  Only include the files that are directly relevant to the task.
+*   **Break Down Tasks:** Divide large tasks into smaller, more focused sub-tasks.
+*   **Use Custom Instructions:**  Provide custom instructions to guide Kilo Code's behavior and reduce the need for lengthy explanations in each prompt.
+*   **Choose the Right Model:**  Some models are more cost-effective than others.  Consider using a smaller, faster model for tasks that don't require the full power of a larger model.
+*   **Use Modes:** Different modes can access different tools, for example `Architect` can't modify code, which makes it a safe choice when analyzing a complex codebase, without worrying about accidentally allowing expensive operations.
+*   **Disable MCP If Not Used:** If you're not using MCP (Model Context Protocol) features, consider [disabling it in the MCP settings](/features/mcp/using-mcp-in-kilo-code) to significantly reduce the size of the system prompt and save tokens.
+
+By understanding and managing your API usage, you can use Kilo Code effectively and efficiently.

apps/kilocode-docs/docs/basic-usage/adding-tokens.md

@@ -0,0 +1,28 @@
+import { DISCORD_URL } from '@site/src/constants.ts'
+
+# Adding More Tokens
+
+Once you've used your initial free tokens, you can easily add more:
+
+- Add a credit card to your account (all payments are securely processed through Stripe)
+- We don't currently offer a subscription, so you only pay for the tokens you use, and only when you choose to top up your tokens!
+- Leverage your own API provider by [connecting your own API provider](/getting-started/connecting-api-provider.md)
+
+## Transparent Pricing
+
+At Kilo Code, we believe in complete pricing transparency:
+
+- Our pricing matches the model provider's API rates exactly
+- We don't take any commission or markup, either per token or per top-up
+- You only pay for what you use with no hidden fees
+
+## Future Plans
+
+We're continuously working to improve Kilo Code and expand our offerings:
+
+- Additional LLM providers will be added in the future
+- More payment options and other plans are under development
+
+:::tip Need Help?
+If you have any questions about pricing or tokens, please reach out to our [support team](mailto:[email protected]) or ask in our <a href={DISCORD_URL} target='_blank'>Discord community</a>.
+:::

apps/kilocode-docs/docs/basic-usage/connecting-providers.md

@@ -0,0 +1,71 @@
+---
+sidebar_label: Overview
+---
+
+# API Providers Overview
+
+**Bottom line**: Kilo Code, like any agentic AI coding tool, needs AI model providers to function. You can use our [built-in provider](/providers/kilocode) (easiest) or connect your own API keys from **30+ providers**.
+
+## Kilo Code Extension vs. API Provider
+
+### The Extension
+- VS Code tool you install from the marketplace
+- Handles UI, file operations, and workflow management
+- [Open source](https://github.com/Kilo-Org/kilocode)
+- Connects to any AI provider
+
+### Kilo Code API Provider
+- **Built-in option** that comes with the extension
+- Google sign-in with free credits included
+- No API key management required
+- Access to frontier coding models
+- [Competitive pricing](https://kilocode.ai/pricing)
+
+**Key point**: The extension works with any provider—our API service is just the "batteries included" option.
+
+## Getting Started: Two Paths
+
+### Option 1: Built-in Provider (Recommended)
+✅ **Fastest setup**
+- Sign in with Google at kilocode.ai
+- Free credits included
+- Zero API key management
+- Latest models available
+
+→ [Complete setup guide](/providers/kilocode)
+
+### Option 2: Your Own Provider
+**More control, more setup**
+1. Choose from 30+ supported providers
+2. Get API key from your provider
+3. Configure in Kilo Code settings
+
+## Why Use Multiple Providers?
+
+- **Cost**: Compare pricing across providers
+- **Models**: Access different AI capabilities
+- **Reliability**: Backup options for outages
+- **Features**: Some providers offer exclusive models
+- **Regional**: Better performance in certain locations
+
+## What's in This Section
+
+### [Connecting Your First AI Provider](/getting-started/connecting-api-provider)
+**For beginners**: Step-by-step setup including:
+- Recommended providers
+- How to get API keys
+- Initial VS Code configuration
+- Starting your first AI chat
+
+### [API Configuration Profiles](/features/api-configuration-profiles)
+**For power users**: Advanced management including:
+- Multiple provider configurations
+- Model switching strategies
+- Secure API key management
+- Task-specific optimizations
+
+## Security Note
+
+All API keys use VS Code's Secret Storage—never stored in plain text. Industry-standard security practices protect your credentials.
+
+**Ready to start?** → [Connect your first provider](/getting-started/connecting-api-provider) or jump to [advanced profiles](/features/api-configuration-profiles).

apps/kilocode-docs/docs/basic-usage/context-mentions.md

@@ -0,0 +1,122 @@
+# Context Mentions
+
+Context mentions are a powerful way to provide Kilo Code with specific information about your project, allowing it to perform tasks more accurately and efficiently. You can use mentions to refer to files, folders, problems, and Git commits. Context mentions start with the `@` symbol.
+
+<img src="/docs/img/context-mentions/context-mentions.png" alt="Context Mentions Overview - showing the @ symbol dropdown menu in the chat interface" width="600" />
+
+*Context mentions overview showing the @ symbol dropdown menu in the chat interface.*
+
+## Types of Mentions
+
+<img src="/docs/img/context-mentions/context-mentions-1.png" alt="File mention example showing a file being referenced with @ and its contents appearing in the conversation" width="600" />
+
+*File mentions add actual code content into the conversation for direct reference and analysis.*
+
+| Mention Type | Format | Description | Example Usage |
+|--------------|--------|-------------|--------------|
+| **File** | `@/path/to/file.ts` | Includes file contents in request context | "Explain the function in @/src/utils.ts" |
+| **Folder** | `@/path/to/folder/` | Provides directory structure in tree format | "What files are in @/src/components/?" |
+| **Problems** | `@problems` | Includes VS Code Problems panel diagnostics | "@problems Fix all errors in my code" |
+| **Terminal** | `@terminal` | Includes recent terminal command and output | "Fix the errors shown in @terminal" |
+| **Git Commit** | `@a1b2c3d` | References specific commit by hash | "What changed in commit @a1b2c3d?" |
+| **Git Changes** | `@git-changes` | Shows uncommitted changes | "Suggest a message for @git-changes" |
+| **URL** | `@https://example.com` | Imports website content | "Summarize @https://docusaurus.io/" |
+
+### File Mentions
+
+<img src="/docs/img/context-mentions/context-mentions-1.png" alt="File mention example showing a file being referenced with @ and its contents appearing in the conversation" width="600" />
+
+*File mentions incorporate source code with line numbers for precise references.*
+| Capability | Details |
+|------------|---------|
+| **Format** | `@/path/to/file.ts` (always start with `/` from workspace root) |
+| **Provides** | Complete file contents with line numbers |
+| **Supports** | Text files, PDFs, and DOCX files (with text extraction) |
+| **Works in** | Initial requests, feedback responses, and follow-up messages |
+| **Limitations** | Very large files may be truncated; binary files not supported |
+
+### Folder Mentions
+
+<img src="/docs/img/context-mentions/context-mentions-2.png" alt="Folder mention example showing directory contents being referenced in the chat" width="600" />
+
+*Folder mentions display directory structure in a readable tree format.*
+| Capability | Details |
+|------------|---------|
+| **Format** | `@/path/to/folder/` (note trailing slash) |
+| **Provides** | Hierarchical tree display with ├── and └── prefixes |
+| **Includes** | Immediate child files and directories (not recursive) |
+| **Best for** | Understanding project structure |
+| **Tip** | Use with file mentions to check specific file contents |
+
+### Problems Mention
+
+<img src="/docs/img/context-mentions/context-mentions-3.png" alt="Problems mention example showing VS Code problems panel being referenced with @problems" width="600" />
+
+*Problems mentions import diagnostics directly from VS Code's problems panel.*
+| Capability | Details |
+|------------|---------|
+| **Format** | `@problems` |
+| **Provides** | All errors and warnings from VS Code's problems panel |
+| **Includes** | File paths, line numbers, and diagnostic messages |
+| **Groups** | Problems organized by file for better clarity |
+| **Best for** | Fixing errors without manual copying |
+
+### Terminal Mention
+<img src="/docs/img/context-mentions/context-mentions-4.png" alt="Terminal mention example showing terminal output being included in Kilo Code's context" width="600" />
+
+*Terminal mentions capture recent command output for debugging and analysis.*
+
+| Capability | Details |
+|------------|---------|
+| **Format** | `@terminal` |
+| **Captures** | Last command and its complete output |
+| **Preserves** | Terminal state (doesn't clear the terminal) |
+| **Limitation** | Limited to visible terminal buffer content |
+| **Best for** | Debugging build errors or analyzing command output |
+
+### Git Mentions
+
+<img src="/docs/img/context-mentions/context-mentions-5.png" alt="Git commit mention example showing commit details being analyzed by Kilo Code" width="600" />
+
+*Git mentions provide commit details and diffs for context-aware version analysis.*
+| Type | Format | Provides | Limitations |
+|------|--------|----------|------------|
+| **Commit** | `@a1b2c3d` | Commit message, author, date, and complete diff | Only works in Git repositories |
+| **Working Changes** | `@git-changes` | `git status` output and diff of uncommitted changes | Only works in Git repositories |
+
+### URL Mentions
+<img src="/docs/img/context-mentions/context-mentions-6.png" alt="URL mention example showing website content being converted to Markdown in the chat" width="600" />
+
+*URL mentions import external web content and convert it to readable Markdown format.*
+
+| Capability | Details |
+|------------|---------|
+| **Format** | `@https://example.com` |
+| **Processing** | Uses headless browser to fetch content |
+| **Cleaning** | Removes scripts, styles, and navigation elements |
+| **Output** | Converts content to Markdown for readability |
+| **Limitation** | Complex pages may not convert perfectly |
+
+## How to Use Mentions
+
+1. Type `@` in the chat input to trigger the suggestions dropdown
+2. Continue typing to filter suggestions or use arrow keys to navigate
+3. Select with Enter key or mouse click
+4. Combine multiple mentions in a request: "Fix @problems in @/src/component.ts"
+
+The dropdown automatically suggests:
+- Recently opened files
+- Visible folders
+- Recent git commits
+- Special keywords (`problems`, `terminal`, `git-changes`)
+
+## Best Practices
+
+| Practice | Description |
+|----------|-------------|
+| **Use specific paths** | Reference exact files rather than describing them |
+| **Use relative paths** | Always start from workspace root: `@/src/file.ts` not `@C:/Projects/src/file.ts` |
+| **Verify references** | Ensure paths and commit hashes are correct |
+| **Click mentions** | Click mentions in chat history to open files or view content |
+| **Eliminate copy-pasting** | Use mentions instead of manually copying code or errors |
+| **Combine mentions** | "Fix @problems in @/src/component.ts using the pattern from commit @a1b2c3d" |

apps/kilocode-docs/docs/basic-usage/git-commit-generation.md

@@ -0,0 +1,146 @@
+# Generate Commit Messages
+
+Generate descriptive commit messages automatically based on your staged git changes. Kilo Code analyzes your staged files and creates conventional commit messages that follow best practices.
+
+:::info
+This feature only analyzes **staged changes**. Make sure to stage your files using `git add` or via `VS Code` interface before generating commit messages.
+:::
+
+## How It Works
+
+The git commit message generator:
+- Analyzes only your **staged changes** (not unstaged or untracked files)
+- Uses AI to understand the context and purpose of your changes
+- Creates descriptive commit messages that explain what was changed and why following the [Conventional Commits](https://www.conventionalcommits.org/) (by default, customizable)
+
+## Using the Feature
+
+### Generating a Commit Message
+
+1. Stage your changes using `git add` or the VS Code git interface
+2. In the VS Code Source Control panel, look for the `Kilo Code` logo next to the commit message field)
+3. Click the logo to generate a commit message
+
+
+The generated message will appear in the commit message field, ready for you to review and modify if needed.
+
+<img src="/docs/img/git-commit-generation/git-commit-1.png" alt="Generated commit message example" width="600" />
+
+### Conventional Commit Format
+
+By default, generated messages follow the Conventional Commits specification:
+
+```
+<type>(<scope>): <description>
+
+<body>
+```
+
+Common types include:
+- `feat`: New features
+- `fix`: Bug fixes
+- `docs`: Documentation changes
+- `style`: Code style changes (formatting, etc.)
+- `refactor`: Code refactoring
+- `test`: Adding or updating tests
+- `chore`: Maintenance tasks
+
+## Configuration
+
+### Customizing the Commit Template
+
+You can customize how commit messages are generated by modifying the prompt template:
+
+1. Open Settings by clicking the gear icon <Codicon name="gear" /> → `Prompts`
+2. Find the "Commit Message Generation" section
+3. Edit the `Prompt` template to match your project's conventions
+
+<img src="/docs/img/git-commit-generation/git-commit-2.png" alt="Commit message generation settings" width="600" />
+
+The default template creates conventional commit messages, but you can modify it to:
+- Use different commit message formats
+- Include specific information relevant to your project
+- Follow your team's commit message conventions
+- Add custom instructions for the AI
+
+### API Configuration
+
+You can configure which API profile to use for commit message generation:
+
+1. In the `Prompts` settings, scroll to "API Configuration"
+2. Select a specific profile or use the currently selected one
+
+:::tip
+Consider creating a dedicated [API configuration profile](/features/api-configuration-profiles) with a faster, more cost-effective model specifically for commit message generation.
+:::
+
+## Best Practices
+
+### Staging Strategy
+- Stage related changes together for more coherent commit messages
+- Avoid staging unrelated changes in a single commit
+- Use `git add -p` for partial file staging when needed
+
+### Message Review
+- Always review generated messages before committing
+- Edit messages to add context the AI might have missed
+- Ensure the message accurately describes the changes
+
+### Custom Templates
+- Tailor the prompt template to your project's needs
+- Include project-specific terminology or conventions
+- Add instructions for handling specific types of changes
+
+## Example Generated Messages
+
+Here are examples of messages the feature might generate:
+
+```
+feat(auth): add OAuth2 integration with Google
+
+Implement Google OAuth2 authentication flow including:
+- OAuth2 client configuration
+- User profile retrieval
+- Token refresh mechanism
+```
+
+```
+fix(api): resolve race condition in user data fetching
+
+Add proper error handling and retry logic to prevent
+concurrent requests from causing data inconsistency
+```
+
+```
+docs(readme): update installation instructions
+
+Add missing dependency requirements and clarify
+setup steps for new contributors
+```
+
+## Troubleshooting
+
+### No Staged Changes
+If the button doesn't appear or generation fails, ensure you have staged changes:
+```bash
+git add <files>
+# or stage all changes
+git add .
+```
+
+### Poor Message Quality
+If generated messages aren't helpful:
+- Review your staging strategy - don't stage unrelated changes together
+- Customize the prompt template with more specific instructions
+- Try a different AI model through API configuration
+
+### Integration Issues
+The feature integrates with VS Code's built-in git functionality. If you encounter issues:
+- Ensure your repository is properly initialized
+- Check that VS Code can access your git repository
+- Verify git is installed and accessible from VS Code
+
+## Related Features
+
+- [API Configuration Profiles](/features/api-configuration-profiles) - Use different models for commit generation
+- [Settings Management](/features/settings-management) - Manage all your Kilo Code preferences

apps/kilocode-docs/docs/basic-usage/how-tools-work.md

@@ -0,0 +1,83 @@
+# 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 | `write_to_file`, `apply_diff` |
+| 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 |
+| `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/docs/basic-usage/orchestrator-mode.md

@@ -0,0 +1,48 @@
+---
+sidebar_label: 'Orchestrator Mode'
+---
+
+import YouTubeEmbed from '@site/src/components/YouTubeEmbed';
+
+# Orchestrator Mode: Coordinate Complex Workflows
+
+Orchestrator Mode (formerly known as Boomerang Tasks) allows you to break down complex projects into smaller, manageable pieces. Think of it like delegating parts of your work to specialized assistants. Each subtask runs in its own context, often using a different Kilo Code mode tailored for that specific job (like [`code`](/basic-usage/using-modes#code-mode-default), [`architect`](/basic-usage/using-modes#architect-mode), or [`debug`](/basic-usage/using-modes#debug-mode)).
+
+<YouTubeEmbed
+  url="https://www.youtube.com/watch?v=20MmJNeOODo"
+  caption="Orchestrator Mode explained and demonstrated"
+/>
+
+
+## Why Use Orchestrator Mode?
+
+-   **Tackle Complexity:** Break large, multi-step projects (e.g., building a full feature) into focused subtasks (e.g., design, implementation, documentation).
+-   **Use Specialized Modes:** Automatically delegate subtasks to the mode best suited for that specific piece of work, leveraging specialized capabilities for optimal results.
+-   **Maintain Focus & Efficiency:** Each subtask operates in its own isolated context with a separate conversation history. This prevents the parent (orchestrator) task from becoming cluttered with the detailed execution steps (like code diffs or file analysis results), allowing it to focus efficiently on the high-level workflow and manage the overall process based on concise summaries from completed subtasks.
+-   **Streamline Workflows:** Results from one subtask can be automatically passed to the next, creating a smooth flow (e.g., architectural decisions feeding into the coding task).
+
+## How It Works
+
+1.  Using Orchestrator Mode, Kilo can analyze a complex task and suggest breaking it down into a subtask[^1].
+2.  The parent task pauses, and the new subtask begins in a different mode[^2].
+3.  When the subtask's goal is achieved, Kilo signals completion.
+4.  The parent task resumes with only the summary[^3] of the subtask. The parent uses this summary to continue the main workflow.
+
+## Key Considerations
+
+-   **Approval Required:** By default, you must approve the creation and completion of each subtask. This can be automated via the [Auto-Approving Actions](/features/auto-approving-actions#subtasks) settings if desired.
+-   **Context Isolation and Transfer:** Each subtask operates in complete isolation with its own conversation history. It does not automatically inherit the parent's context. Information must be explicitly passed:
+    *   **Down:** Via the initial instructions provided when the subtask is created.
+    *   **Up:** Via the final summary provided when the subtask finishes. Be mindful that only this summary returns to the parent.
+-   **Navigation:** Kilo's interface helps you see the hierarchy of tasks (which task is the parent, which are children). You can typically navigate between active and paused tasks.
+
+Orchestrator Mode provides a powerful way to manage complex development workflows directly within Kilo Code, leveraging specialized modes for maximum efficiency.
+
+:::tip Keep Tasks Focused
+Use subtasks to maintain clarity. If a request significantly shifts focus or requires a different expertise (mode), consider creating a subtask rather than overloading the current one.
+:::
+
+
+[^1]: This context is passed via the `message` parameter of the [`new_task`](/features/tools/new-task) tool.
+[^2]: The mode for the subtask is specified via the `mode` parameter of the [`new_task`](/features/tools/new-task) tool during initiation.
+[^3]: This summary is passed via the `result` parameter of the [`attempt_completion`](/features/tools/attempt-completion) tool when the subtask finishes.

apps/kilocode-docs/docs/basic-usage/task-todo-list.md

@@ -0,0 +1,93 @@
+# Task Todo List
+
+**The big picture**: Never lose track of complex development tasks again. Task Todo Lists create interactive, persistent checklists that live right in your chat interface.
+
+**Why it matters**: Complex workflows have lots of moving parts. Without structure, it's easy to miss steps, duplicate work, or forget what comes next.
+
+<img src="/docs/img/task-todo-list/task-todo-list-1.png" alt="Task Todo List overview showing interactive checklist in Kilo Code" width="500" />
+
+## How to trigger todo lists
+
+**Automatic triggers**:
+- Complex tasks with multiple steps
+- Working in Architect mode
+- Multi-phase workflows with dependencies
+
+**Manual triggers**:
+- Ask Kilo to "use the [update_todo_list tool](/features/tools/update-todo-list)"
+- Say "create a todo list"
+
+**The bottom line**: Kilo decides what goes in the list, but you can provide feedback during approval dialogs.
+
+---
+
+## The old way vs. the new way
+
+**Before**: You juggled task steps in your head or scattered notes, constantly wondering "what's next?"
+
+**Now**: Kilo creates structured checklists that update automatically as work progresses. You see exactly where you are and what's coming up.
+
+---
+
+## Where todo lists appear
+
+**1. Task Header Summary**
+Quick progress overview with your next important item
+
+<img src="/docs/img/task-todo-list/task-header.png" alt="Task header summary showing todo list progress" width="500" />
+
+**2. Interactive Tool Block**
+Full todo interface in chat where you can:
+- See all items and their status
+- Edit descriptions when Kilo asks for approval
+- Stage changes using the "Edit" button
+
+**3. Environment Details**
+Background "REMINDERS" table that keeps Kilo informed about current progress
+
+## Task status decoded
+
+**Pending** → Empty checkbox (not started)
+
+<img src="/docs/img/task-todo-list/not-started.png" alt="Pending todo item with empty checkbox" width="300" />
+
+---
+
+**In Progress** → Yellow dot (currently working)
+
+<img src="/docs/img/task-todo-list/in-progress.png" alt="In progress todo item with yellow dot indicator" width="300" />
+
+---
+
+**Completed** → Green checkmark (finished)
+
+<img src="/docs/img/task-todo-list/complete.png" alt="Completed todo item with green checkmark" width="300" />
+
+---
+
+## Common questions
+
+**"Can I create my own todo lists?"**
+Yes, just ask Kilo to use the update_todo_list tool. But Kilo stays in control of the content and workflow.
+
+**"What about simple tasks?"**
+Kilo typically skips todo lists for simple tasks. The overhead isn't worth it.
+
+**"Why can't I directly edit the list?"**
+Design choice. Kilo maintains authority over task management to ensure consistent progress tracking. You provide input, Kilo executes.
+
+---
+
+:::tip
+
+## Pro tip: Auto-approval
+
+**What it does**: Automatically approves todo list updates without confirmation prompts.
+
+**When to use it**: Long workflows where constant interruptions slow you down.
+
+**How to enable it**: Check the [Update Todo List auto-approval settings](/features/auto-approving-actions#update-todo-list).
+
+**The catch**: Less control, but faster execution.
+
+:::

apps/kilocode-docs/docs/basic-usage/the-chat-interface.md

@@ -0,0 +1,83 @@
+import Image from '@site/src/components/Image';
+
+# Chatting with Kilo Code
+
+:::tip
+
+**Bottom line:** Kilo Code is an AI coding assistant that lives in VS Code. You chat with it in plain English, and it writes, edits, and explains code for you.
+
+:::
+
+## Quick Setup
+
+Find the Kilo Code icon (<img src="/docs/img/kilo-v1.svg" width="12" />) in VS Code's Primary Side Bar. Click it to open the chat panel.
+
+**Lost the panel?** Go to View > Open View... and search for "Kilo Code"
+
+## How to Talk to Kilo Code
+
+**The key insight:** Just type what you want in normal English. No special commands needed.
+
+<Image src="/docs/img/typing-your-requests/typing-your-requests.png" alt="Example of typing a request in Kilo Code" width="600" />
+
+**Good requests:**
+
+```
+create a new file named utils.py and add a function called add that takes two numbers as arguments and returns their sum
+```
+
+```
+in the file @src/components/Button.tsx, change the color of the button to blue
+```
+
+```
+find all instances of the variable oldValue in @/src/App.js and replace them with newValue
+```
+
+**What makes requests work:**
+- **Be specific** - "Fix the bug in `calculateTotal` that returns incorrect results" beats "Fix the code"
+- **Use @ mentions** - Reference files and code directly with `@filename`
+- **One task at a time** - Break complex work into manageable steps
+- **Include examples** - Show the style or format you want
+
+
+## The Chat Interface
+
+<Image 
+    src="/docs/img/the-chat-interface/the-chat-interface-1.png" 
+    alt="Chat interface components labeled with callouts" width="750" 
+    caption="Everything you need is right here"
+/>
+
+**Essential controls:**
+- **Chat history** - See your conversation and task history
+- **Input field** - Type your requests here (press Enter to send)
+- **Action buttons** - Approve or reject Kilo's proposed changes
+- **Plus button** - Start a new task session
+- **Mode selector** - Choose how Kilo should approach your task
+
+## Quick Interactions
+
+**Click to act:**
+- File paths → Opens the file
+- URLs → Opens in browser
+- Messages → Expand/collapse details
+- Code blocks → Copy button appears
+
+**Status signals:**
+- Spinning → Kilo is working
+- Red → Error occurred
+- Green → Success
+
+## Common Mistakes to Avoid
+
+| Instead of this... | Try this |
+|-------------------|----------|
+| "Fix the code" | "Fix the bug in `calculateTotal` that returns incorrect results" |
+| Assuming Kilo knows context | Use `@` to reference specific files |
+| Multiple unrelated tasks | Submit one focused request at a time |
+| Technical jargon overload | Clear, straightforward language works best |
+
+**Why it matters:** Kilo Code works best when you communicate like you're talking to a smart teammate who needs clear direction.
+
+Ready to start coding? Open the chat panel and describe what you want to build!

apps/kilocode-docs/docs/basic-usage/using-modes.md

@@ -0,0 +1,90 @@
+# Using Modes
+
+Modes in Kilo Code are specialized personas that tailor the assistant's behavior to your current task. Each mode offers different capabilities, expertise, and access levels to help you accomplish specific goals.
+
+## Why Use Different Modes?
+
+- **Task specialization:** Get precisely the type of assistance you need for your current task
+- **Safety controls:** Prevent unintended file modifications when focusing on planning or learning
+- **Focused interactions:** Receive responses optimized for your current activity
+- **Workflow optimization:** Seamlessly transition between planning, implementing, debugging, and learning
+
+<YouTubeEmbed
+  url="https://youtu.be/cS4vQfX528w"
+  caption="Explaining the different modes in Kilo Code"
+/>
+
+## Switching Between Modes
+
+Four ways to switch modes:
+
+1. **Dropdown menu:** Click the selector to the left of the chat input
+   
+   <img src="/docs/img/modes/modes.png" alt="Using the dropdown menu to switch modes" width="400" />
+
+2. **Slash command:** Type `/architect`, `/ask`, `/debug`, or `/code` in the chat input
+   
+   <img src="/docs/img/modes/modes-1.png" alt="Using slash commands to switch modes" width="400" />
+
+3. **Toggle command/Keyboard shortcut:** Use the keyboard shortcut below, applicable to your operating system. Each press cycles through the available modes in sequence, wrapping back to the first mode after reaching the end.
+       
+    | Operating System | Shortcut |
+    |------------------|----------|
+    | macOS | ⌘ + . |
+    | Windows | Ctrl + . |
+    | Linux | Ctrl + . |
+
+4. **Accept suggestions:** Click on mode switch suggestions that Kilo Code offers when appropriate
+   
+    <img src="/docs/img/modes/modes-2.png" alt="Accepting a mode switch suggestion from Kilo Code" width="400" />
+
+## Built-in Modes
+
+### Code Mode (Default)
+
+| Aspect | Details |
+|--------|---------|
+| **Description** | A skilled software engineer with expertise in programming languages, design patterns, and best practices |
+| **Tool Access** | Full access to all tool groups: `read`, `edit`, `browser`, `command`, `mcp` |
+| **Ideal For** | Writing code, implementing features, debugging, and general development |
+| **Special Features** | No tool restrictions—full flexibility for all coding tasks |
+
+### Ask Mode
+
+| Aspect | Details |
+|--------|---------|
+| **Description** | A knowledgeable technical assistant focused on answering questions without changing your codebase |
+| **Tool Access** | Limited access: `read`, `browser`, `mcp` only (cannot edit files or run commands) |
+| **Ideal For** | Code explanation, concept exploration, and technical learning |
+| **Special Features** | Optimized for informative responses without modifying your project |
+
+### Architect Mode
+
+| Aspect | Details |
+|--------|---------|
+| **Description** | An experienced technical leader and planner who helps design systems and create implementation plans |
+| **Tool Access** | Access to `read`, `browser`, `mcp`, and restricted `edit` (markdown files only) |
+| **Ideal For** | System design, high-level planning, and architecture discussions |
+| **Special Features** | Follows a structured approach from information gathering to detailed planning |
+
+### Debug Mode
+
+| Aspect | Details |
+|--------|---------|
+| **Description** | An expert problem solver specializing in systematic troubleshooting and diagnostics |
+| **Tool Access** | Full access to all tool groups: `read`, `edit`, `browser`, `command`, `mcp` |
+| **Ideal For** | Tracking down bugs, diagnosing errors, and resolving complex issues |
+| **Special Features** | Uses a methodical approach of analyzing, narrowing possibilities, and fixing issues |
+
+### Orchestrator Mode
+
+| Aspect | Details |
+|--------|---------|
+| **Description** | A strategic workflow orchestrator who coordinates complex tasks by delegating them to appropriate specialized modes |
+| **Tool Access** | Limited access to create new tasks and coordinate workflows |
+| **Ideal For** | Breaking down complex projects into manageable subtasks assigned to specialized modes |
+| **Special Features** | Uses the new_task tool to delegate work to other modes |
+
+## Custom Modes
+
+Create your own specialized assistants by defining tool access, file permissions, and behavior instructions. Custom modes help enforce team standards or create purpose-specific assistants. See [Custom Modes documentation](/features/custom-modes) for setup instructions.

apps/kilocode-docs/docs/extending/contributing-to-kilo.md

@@ -0,0 +1,125 @@
+# Contributing to Kilo Code
+
+Kilo Code is an open-source project that welcomes contributions from developers of all skill levels. This guide will help you get started with contributing to Kilo Code, whether you're fixing bugs, adding features, improving documentation, or sharing custom modes.
+
+## Ways to Contribute
+
+There are many ways to contribute to Kilo Code:
+
+1. **Code Contributions**: Implement new features or fix bugs
+2. **Documentation**: Improve existing docs or create new guides
+3. **Custom Modes**: Create and share specialized modes
+4. **Bug Reports**: Report issues you encounter
+5. **Feature Requests**: Suggest new features or improvements
+6. **Community Support**: Help other users in the community
+
+## Setting Up the Development Environment
+
+Setting Up the Development Environment is described in details on [this page](/docs/extending/development-environment.md)
+
+## Development Workflow
+
+### Branching Strategy
+
+- Create a new branch for each feature or bugfix
+- Use descriptive branch names (e.g., `feature/new-tool-support` or `fix/browser-action-bug`)
+
+```bash
+git checkout -b your-branch-name
+```
+
+### Coding Standards
+
+- Follow the existing code style and patterns
+- Use TypeScript for new code
+- Include appropriate tests for new features
+- Update documentation for any user-facing changes
+
+### Commit Guidelines
+
+- Write clear, concise commit messages
+- Reference issue numbers when applicable
+- Keep commits focused on a single change
+
+### Testing Your Changes
+
+- Run the test suite:
+  ```bash
+  npm test
+  ```
+- Manually test your changes in the development extension
+
+### Creating a Pull Request
+
+1. Push your changes to your fork:
+   ```bash
+   git push origin your-branch-name
+   ```
+
+2. Go to the [Kilo Code repository](https://github.com/Kilo-Org/kilocode)
+
+3. Click "New Pull Request" and select "compare across forks"
+
+4. Select your fork and branch
+
+5. Fill out the PR template with:
+   - A clear description of the changes
+   - Any related issues
+   - Testing steps
+   - Screenshots (if applicable)
+
+## Creating Custom Modes
+
+Custom modes are a powerful way to extend Kilo Code's capabilities. To create and share a custom mode:
+
+1. Follow the [Custom Modes documentation](/features/custom-modes) to create your mode
+
+2. Test your mode thoroughly
+
+3. Share your mode with the community by submitting a [GitHub Discussion](https://github.com/Kilo-Org/kilocode/discussions)
+
+## Documentation Contributions
+
+Documentation improvements are highly valued contributions:
+
+1. Follow the documentation style guide:
+   - Use clear, concise language
+   - Include examples where appropriate
+   - Use absolute paths starting from `/docs/` for internal links
+   - Don't include `.md` extensions in links
+
+2. Test your documentation changes by running the docs site locally:
+   ```bash
+   cd docs
+   npm install
+   npm start
+   ```
+
+3. Submit a PR with your documentation changes
+
+## Community Guidelines
+
+When participating in the Kilo Code community:
+
+- Be respectful and inclusive
+- Provide constructive feedback
+- Help newcomers get started
+- Follow the [Code of Conduct](https://github.com/Kilo-Org/kilocode/blob/main/CODE_OF_CONDUCT.md)
+
+## Getting Help
+
+If you need help with your contribution:
+
+- Join our [Discord community](https://kilocode.ai/discord) for real-time support
+- Ask questions on [GitHub Discussions](https://github.com/Kilo-Org/kilocode/discussions)
+- Visit our [Reddit community](https://www.reddit.com/r/KiloCode)
+
+## Recognition
+
+All contributors are valued members of the Kilo Code community. Contributors are recognized in:
+
+- Release notes
+- The project's README
+- The contributors list on GitHub
+
+Thank you for contributing to Kilo Code and helping make AI-powered coding assistance better for everyone!

apps/kilocode-docs/docs/extending/development-environment.md

@@ -0,0 +1,192 @@
+# Development Environment
+
+<!-- Please refer to the [DEVELOPMENT.md](https://github.com/Kilo-Org/kilocode/blob/main/DEVELOPMENT.md) guide in the main repository for detailed instructions on setting up the development environment. -->
+
+This document will help you set up your development environment and understand how to work with the codebase. Whether you're fixing bugs, adding features, or just exploring the code, this guide will get you started.
+
+## Prerequisites
+
+Before you begin, make sure you have the following installed:
+
+1. **Git** - For version control
+2. **Node.js** (version [v20.18.1](https://github.com/Kilo-Org/kilocode/blob/main/.nvmrc) or higher recommended) and npm
+3. **Visual Studio Code** - Our recommended IDE for development
+
+## Getting Started
+
+### Installation
+
+1. **Fork and Clone the Repository**:
+
+    - **Fork the Repository**:
+        - Visit the [Kilo Code GitHub repository](https://github.com/Kilo-Org/kilocode)
+        - Click the "Fork" button in the top-right corner to create your own copy.
+    - **Clone Your Fork**:
+        ```bash
+        git clone https://github.com/[YOUR-USERNAME]/kilocode.git
+        cd kilocode
+        ```
+        Replace `[YOUR-USERNAME]` with your actual GitHub username.
+
+1. **Install dependencies**:
+
+    ```bash
+    pnpm install
+    ```
+
+    This command will install dependencies for the main extension, webview UI, and e2e tests.
+
+1. **Install VSCode Extensions**:
+    - **Required**: [ESBuild Problem Matchers](https://marketplace.visualstudio.com/items?itemName=connor4312.esbuild-problem-matchers) - Helps display build errors correctly.
+
+While not strictly necessary for running the extension, these extensions are recommended for development:
+
+- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) - Integrates ESLint into VS Code.
+- [Prettier - Code formatter](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) - Integrates Prettier into VS Code.
+
+The full list of recommended extensions is [here](https://github.com/Kilo-Org/kilocode/blob/main/.vscode/extensions.json)
+
+### Project Structure
+
+The project is organized into several key directories:
+
+- **`src/`** - Core extension code
+    - **`core/`** - Core functionality and tools
+    - **`services/`** - Service implementations
+- **`webview-ui/`** - Frontend UI code
+- **`e2e/`** - End-to-end tests
+- **`scripts/`** - Utility scripts
+- **`assets/`** - Static assets like images and icons
+
+## Development Workflow
+
+### Building the Extension
+
+To build the extension:
+
+```bash
+pnpm build
+```
+
+This will:
+
+1. Build the webview UI
+2. Compile TypeScript
+3. Bundle the extension
+4. Create a `.vsix` file in the `bin/` directory
+
+### Running the Extension
+
+To run the extension in development mode:
+
+1. Press `F5` (or select **Run** → **Start Debugging**) in VSCode
+2. This will open a new VSCode window with Kilo Code loaded
+
+### Hot Reloading
+
+- **Webview UI changes**: Changes to the webview UI will appear immediately without restarting
+- **Core extension changes**: Changes to the core extension code will automatically reload the ext host
+
+In development mode (NODE_ENV="development"), changing the core code will trigger a `workbench.action.reloadWindow` command, so it is no longer necessary to manually start/stop the debugger and tasks.
+
+> **Important**: In production builds, when making changes to the core extension, you need to:
+>
+> 1. Stop the debugging process
+> 2. Kill any npm tasks running in the background (see screenshot below)
+> 3. Start debugging again
+
+<img width="600" alt="Stopping background tasks" src="https://github.com/user-attachments/assets/466fb76e-664d-4066-a3f2-0df4d57dd9a4" />
+
+### Installing the Built Extension
+
+To install your built extension:
+
+```bash
+code --install-extension "$(ls -1v bin/kilo-code-*.vsix | tail -n1)"
+```
+
+Replace `[version]` with the current version number.
+
+## Testing
+
+Kilo Code uses several types of tests to ensure quality:
+
+### Unit Tests
+
+Run unit tests with:
+
+```bash
+npm test
+```
+
+This runs both extension and webview tests.
+
+To run specific test suites:
+
+```bash
+npm run test:extension  # Run only extension tests
+npm run test:webview    # Run only webview tests
+```
+
+### End-to-End Tests
+
+E2E tests verify the extension works correctly within VSCode:
+
+1. Create a `.env.local` file in the root with required API keys:
+
+    ```
+    OPENROUTER_API_KEY=sk-or-v1-...
+    ```
+
+2. Run the integration tests:
+    ```bash
+    npm run test:integration
+    ```
+
+For more details on E2E tests, see [e2e/VSCODE_INTEGRATION_TESTS.md](https://github.com/Kilo-Org/kilocode/blob/main/e2e/VSCODE_INTEGRATION_TESTS.md).
+
+## Linting and Type Checking
+
+Ensure your code meets our quality standards:
+
+```bash
+npm run lint          # Run ESLint
+npm run check-types   # Run TypeScript type checking
+```
+
+## Git Hooks
+
+This project uses [Husky](https://typicode.github.io/husky/) to manage Git hooks, which automate certain checks before commits and pushes. The hooks are located in the `.husky/` directory.
+
+### Pre-commit Hook
+
+Before a commit is finalized, the `.husky/pre-commit` hook runs:
+
+1.  **Branch Check**: Prevents committing directly to the `main` branch.
+2.  **Type Generation**: Runs `npm run generate-types`.
+3.  **Type File Check**: Ensures that any changes made to `src/exports/roo-code.d.ts` by the type generation are staged.
+4.  **Linting**: Runs `lint-staged` to lint and format staged files.
+
+### Pre-push Hook
+
+Before changes are pushed to the remote repository, the `.husky/pre-push` hook runs:
+
+1.  **Branch Check**: Prevents pushing directly to the `main` branch.
+2.  **Compilation**: Runs `npm run compile` to ensure the project builds successfully.
+3.  **Changeset Check**: Checks if a changeset file exists in `.changeset/` and reminds you to create one using `npm run changeset` if necessary.
+
+These hooks help maintain code quality and consistency. If you encounter issues with commits or pushes, check the output from these hooks for error messages.
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Extension not loading**: Check the VSCode Developer Tools (Help > Toggle Developer Tools) for errors
+2. **Webview not updating**: Try reloading the window (Developer: Reload Window)
+3. **Build errors**: Make sure all dependencies are installed with `npm run install:all`
+
+### Debugging Tips
+
+- Use `console.log()` statements in your code for debugging
+- Check the Output panel in VSCode (View > Output) and select "Kilo Code" from the dropdown
+- For webview issues, use the browser developer tools in the webview (right-click > "Inspect Element")

apps/kilocode-docs/docs/faq.md

@@ -0,0 +1,172 @@
+---
+---
+
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+
+export const FreeTierAmount = () => {
+  const {siteConfig} = useDocusaurusContext();
+  return siteConfig.customFields.freeTierAmount;
+};
+
+# Frequently Asked Questions
+
+This page answers some common questions about Kilo Code.
+
+## General
+
+### What is Kilo Code?
+
+Kilo Code is an open-source AI agent extension for Visual Studio Code. It helps you write code more efficiently by generating code, automating tasks, and providing suggestions.
+
+### How does Kilo Code work?
+
+Kilo Code uses large language models (LLMs) to understand your requests and translate them into actions.  It can:
+
+*   Read and write files in your project.
+*   Execute commands in your VS Code terminal.
+*   Perform web browsing (if enabled).
+*   Use external tools via the Model Context Protocol (MCP).
+
+You interact with Kilo Code through a chat interface, where you provide instructions and review/approve its proposed actions.
+
+### What can Kilo Code do?
+
+Kilo Code can help with a variety of coding tasks, including:
+
+*   Generating code from natural language descriptions.
+*   Refactoring existing code.
+*   Fixing bugs.
+*   Writing documentation.
+*   Explaining code.
+*   Answering questions about your codebase.
+*   Automating repetitive tasks.
+*   Creating new files and projects.
+
+### Is Kilo Code free to use?
+
+The Kilo Code extension itself is free and open-source. In addition, Kilo Code has a free tier with <FreeTierAmount /> worth of Claude 3.7 Sonnet tokens. We'll give out more free tokens if you leave useful feedback.
+
+After that, you can add a credit card to buy more tokens (securely processed through Stripe. Our pricing matches Anthropic's API rates exactly. We don't take any cut, either per token or per top-up. In the future we'll add more LLM providers.
+
+Alternatively, you can "Bring Your Own API" (like [Anthropic](providers/anthropic), [OpenAI](providers/openai), [OpenRouter](providers/openrouter), [Requesty](providers/requesty), etc.) for its AI capabilities.  These providers typically charge for API usage based on the number of tokens processed.  You will need to create an account and obtain an API key from your chosen provider.  See [Setting Up Your First AI Provider](getting-started/connecting-api-provider) for details.
+
+### What are the risks of using Kilo Code?
+
+Kilo Code is a powerful tool, and it's important to use it responsibly.  Here are some things to keep in mind:
+
+*   **Kilo Code can make mistakes.**  Always review Kilo Code's proposed changes carefully before approving them.
+*   **Kilo Code can execute commands.**  Be very cautious about allowing Kilo Code to run commands, especially if you're using auto-approval.
+*   **Kilo Code can access the internet.** If you're using a provider that supports web browsing, be aware that Kilo Code could potentially access sensitive information.
+
+## Setup & Installation
+
+### How do I install Kilo Code?
+
+See the [Installation Guide](/getting-started/installing) for detailed instructions.
+
+### Which API providers are supported?
+
+Kilo Code supports a wide range of API providers, including:
+*   [Anthropic (Claude)](/providers/kilocode)
+*   [Anthropic (Claude)](/providers/anthropic)
+*   [OpenAI](/providers/openai)
+*   [OpenRouter](/providers/openrouter)
+*   [Google Gemini](/providers/gemini)
+*   [Glama](/providers/glama)
+*   [AWS Bedrock](/providers/bedrock)
+*   [GCP Vertex AI](/providers/vertex)
+*   [Ollama](/providers/ollama)
+*   [LM Studio](/providers/lmstudio)
+*   [DeepSeek](/providers/deepseek)
+*   [Mistral](/providers/mistral)
+*   [Unbound](/providers/unbound)
+*   [Requesty](/providers/requesty)
+*   [VS Code Language Model API](/providers/vscode-lm)
+
+### How do I get an API key?
+Each API provider has its own process for obtaining an API key.  See the [Setting Up Your First AI Provider](/getting-started/connecting-api-provider) for links to the relevant documentation for each provider.
+
+### Can I use Kilo Code with local models?
+Yes, Kilo Code supports running models locally using [Ollama](/providers/ollama) and [LM Studio](/providers/lmstudio).  See [Using Local Models](/advanced-usage/local-models) for instructions.
+
+## Usage
+
+### How do I start a new task?
+Open the Kilo Code panel (<img src="/docs/img/kilo-v1.svg" width="12" />) and type your task in the chat box. Be clear and specific about what you want Kilo Code to do. See [The Chat Interface](/basic-usage/the-chat-interface) for best practices.
+
+### What are modes in Kilo Code?
+[Modes](/basic-usage/using-modes) are different personas that Kilo Code can adopt, each with a specific focus and set of capabilities. The built-in modes are:
+
+*   **Code:** For general-purpose coding tasks.
+*   **Architect:** For planning and technical leadership.
+*   **Ask:** For answering questions and providing information.
+*   **Debug:** For systematic problem diagnosis.
+You can also create [Custom Modes](/features/custom-modes).
+
+### How do I switch between modes?
+
+Use the dropdown menu in the chat input area to select a different mode, or use the `/` command to switch to a specific mode.
+
+### What are tools and how do I use them?
+[Tools](/basic-usage/how-tools-work) are how Kilo Code interacts with your system.  Kilo Code automatically selects and uses the appropriate tools to complete your tasks. You don't need to call tools directly. You will be prompted to approve or reject each tool use.
+
+### What are context mentions?
+[Context mentions](/basic-usage/context-mentions) are a way to provide Kilo Code with specific information about your project, such as files, folders, or problems. Use the "@" symbol followed by the item you want to mention (e.g., `@/src/file.ts`, `@problems`).
+
+### Can Kilo Code access the internet?
+
+Yes, if you are using a provider with a model that support web browsing. Be mindful of the security implications of allowing this.
+
+### Can Kilo Code run commands in my terminal?
+
+Yes, Kilo Code can execute commands in your VS Code terminal.  You will be prompted to approve each command before it's executed, unless you've enabled auto-approval for commands. Be extremely cautious about auto-approving commands. If you're experiencing issues with terminal commands, see the [Shell Integration Guide](/features/shell-integration) for troubleshooting.
+
+### How do I provide feedback to Kilo Code?
+
+You can provide feedback by approving or rejecting Kilo Code's proposed actions. You can provide additional feedback by using the feedback field.
+
+### Can I customize Kilo Code's behavior?
+
+Yes, you can customize Kilo Code in several ways:
+
+*   **Custom Instructions:** Provide general instructions that apply to all modes, or mode-specific instructions.
+*   **Custom Modes:** Create your own modes with tailored prompts and tool permissions.
+*   **`.clinerules` Files:** Create `.clinerules` files in your project to provide additional guidelines.
+*   **Settings:** Adjust various settings, such as auto-approval, diff editing, and more.
+
+### Does Kilo Code have any auto approval settings?
+Yes, Kilo Code has a few settings that when enabled will automatically approve actions. Find out more [here](/features/auto-approving-actions).
+
+## Advanced Features
+
+### Can I use Kilo Code offline?
+Yes, if you use a [local model](/advanced-usage/local-models).
+
+### What is MCP (Model Context Protocol)?
+[MCP](/features/mcp/overview) is a protocol that allows Kilo Code to communicate with external servers, extending its capabilities with custom tools and resources.
+
+### Can I create my own MCP servers?
+Yes, you can create your own MCP servers to add custom functionality to Kilo Code. See the [MCP documentation](https://github.com/modelcontextprotocol) for details.
+Yes, you can create your own MCP servers to add custom functionality to Kilo Code. See the [MCP documentation](https://github.com/modelcontextprotocol) for details.
+
+## Troubleshooting
+
+### Kilo Code isn't responding. What should I do?
+
+*   Make sure your API key is correct and hasn't expired.
+*   Check your internet connection.
+*   Check the status of your chosen API provider.
+*   Try restarting VS Code.
+*   If the problem persists, report the issue on [GitHub](https://github.com/Kilo-Org/kilocode/issues) or [Discord](https://kilocode.ai/discord).
+
+### I'm seeing an error message. What does it mean?
+
+The error message should provide some information about the problem. If you're unsure how to resolve it, seek help in the community forums.
+
+### Kilo Code made changes I didn't want. How do I undo them?
+
+Kilo Code uses VS Code's built-in file editing capabilities.  You can use the standard "Undo" command (Ctrl/Cmd + Z) to revert changes. Also, if experimental checkpoints are enabled, Kilo can revert changes made to a file.
+
+### How do I report a bug or suggest a feature?
+
+Please report bugs or suggest features on the Kilo Code [Issues page](https://github.com/Kilo-Org/kilocode/issues) and [Feature Requests page](https://github.com/Kilo-Org/kilocode/discussions/categories/ideas).

apps/kilocode-docs/docs/features/api-configuration-profiles.md

@@ -0,0 +1,97 @@
+# API Configuration Profiles
+
+API Configuration Profiles allow you to create and switch between different sets of AI settings. Each profile can have different configurations for each mode, letting you optimize your experience based on the task at hand.
+
+:::info
+Having multiple configuration profiles lets you quickly switch between different AI providers, models, and settings without reconfiguring everything each time you want to change your setup.
+:::
+## How It Works
+
+Configuration profiles can have their own:
+- API providers (OpenAI, Anthropic, OpenRouter, Glama, etc.)
+- API keys and authentication details
+- Model selections (o3-mini-high, Claude 3.7 Sonnet, DeepSeek R1, etc.)
+- [Temperature settings](/features/model-temperature) for controlling response randomness
+- Thinking budgets
+- Provider-specific settings
+
+Note that available settings vary by provider and model. Each provider offers different configuration options, and even within the same provider, different models may support different parameter ranges or features.
+
+## Creating and Managing Profiles
+
+### Creating a Profile
+
+1. Open Settings by clicking the gear icon <Codicon name="gear" /> → Providers
+2. Click the "+" button next to the profile selector
+
+   <img src="/docs/img/api-configuration-profiles/api-configuration-profiles-1.png" alt="Profile selector with plus button" width="550" />
+3. Enter a name for your new profile
+   
+   <img src="/docs/img/api-configuration-profiles/api-configuration-profiles.png" alt="Creating a new profile dialog" width="550" />
+4. Configure the profile settings:
+   - Select your API provider
+      
+      <img src="/docs/img/api-configuration-profiles/api-configuration-profiles-2.png" alt="Provider selection dropdown" width="550" />
+   - Enter API key
+   
+      <img src="/docs/img/api-configuration-profiles/api-configuration-profiles-3.png" alt="API key entry field" width="550" />
+   - Choose a model
+   
+      <img src="/docs/img/api-configuration-profiles/api-configuration-profiles-8.png" alt="Model selection interface" width="550" />
+   - Adjust model parameters
+   
+      <img src="/docs/img/api-configuration-profiles/api-configuration-profiles-5.png" alt="Model parameter adjustment controls" width="550" />
+
+### Switching Profiles
+
+Switch profiles in two ways:
+1. From Settings panel: Select a different profile from the dropdown
+
+   <img src="/docs/img/api-configuration-profiles/api-configuration-profiles-7.png" alt="Profile selection dropdown in Settings" width="550" />
+2. During chat: Access the API Configuration dropdown in the chat interface
+
+   <img src="/docs/img/api-configuration-profiles/api-configuration-profiles-6.png" alt="API Configuration dropdown in chat interface" width="550" />
+### Pinning and Sorting Profiles
+
+The API configuration dropdown now supports pinning your favorite profiles for quicker access:
+
+1. Hover over any profile in the dropdown to reveal the pin icon
+2. Click the pin icon to add the profile to your pinned list
+3. Pinned profiles appear at the top of the dropdown, sorted alphabetically
+4. Unpinned profiles appear below a separator, also sorted alphabetically
+5. You can unpin a profile by clicking the same icon again
+
+<img src="/docs/img/api-configuration-profiles/api-configuration-profiles-4.png" alt="Pinning API configuration profiles" width="550" />
+
+This feature makes it easier to navigate between commonly used profiles, especially when you have many configurations.
+
+
+### Editing and Deleting Profiles
+
+<img src="/docs/img/api-configuration-profiles/api-configuration-profiles-10.png" alt="Profile editing interface" width="550" />
+- Select the profile in Settings to modify any settings
+- Click the pencil icon to rename a profile
+- Click the trash icon to delete a profile (you cannot delete the only remaining profile)
+
+## Linking Profiles to Modes
+In the <Codicon name="notebook" /> Prompts tab, you can explicitly associate a specific Configuration Profile with each Mode. The system also automatically remembers which profile you last used with each mode, making your workflow more efficient.
+
+Watch this demonstration of how to connect configuration profiles with specific modes for optimized workflows:
+
+<video width="600" controls>
+  <source src="/docs/img/api-configuration-profiles/provider-modes.mp4" type="video/mp4" />
+  Your browser does not support the video tag.
+</video>
+
+
+## Security Note
+
+API keys are stored securely in VSCode's Secret Storage and are never exposed in plain text.
+
+## Related Features
+
+- Works with [custom modes](/features/custom-modes) you create
+- Integrates with [local models](/advanced-usage/local-models) for offline work
+- Supports [temperature settings](/features/model-temperature) per mode
+- Enhances cost management with [rate limits and usage tracking](/advanced-usage/rate-limits-costs)
+

apps/kilocode-docs/docs/features/auto-approving-actions.md

@@ -0,0 +1,283 @@
+# Auto-Approving Actions
+
+> ⚠️ **SECURITY WARNING:** Auto-approve settings bypass confirmation prompts, giving Kilo Code direct access to your system. This can result in **data loss, file corruption, or worse**. Command line access is particularly dangerous, as it can potentially execute harmful operations that could damage your system or compromise security. Only enable auto-approval for actions you fully trust.
+
+Auto-approve settings speed up your workflow by eliminating repetitive confirmation prompts, but they significantly increase security risks.
+
+## Quick Start Guide
+
+1. Click the Auto-Approve Toolbar above the chat input
+2. Select which actions Kilo Code can perform without asking permission
+3. Use the master toggle (leftmost checkbox) to quickly enable/disable all permissions
+
+## Auto-Approve Toolbar
+
+<img src="/docs/img/auto-approving-actions/auto-approving-actions.png" alt="Auto-approve toolbar collapsed state" width="600" />
+
+*Prompt box and Auto-Approve Toolbar showing enabled permissions*
+
+Click the toolbar to expand it and configure individual permissions:
+
+<img src="/docs/img/auto-approving-actions/auto-approving-actions-1.png" alt="Auto-approve toolbar expanded state" width="600" />
+
+*Prompt text box and Expanded toolbar with all options*
+
+### Available Permissions
+
+| Permission | What it does | Risk level |
+|------------|--------------|------------|
+| **Read files and directories** | Lets Kilo Code access files without asking | Medium |
+| **Edit files** | Lets Kilo Code modify files without asking | **High** |
+| **Execute approved commands** | Runs whitelisted terminal commands automatically | **High** |
+| **Use the browser** | Allows headless browser interaction | Medium |
+| **Use MCP servers** | Lets Kilo Code use configured MCP services | Medium-High |
+| **Switch modes** | Changes between Kilo Code modes automatically | Low |
+| **Create & complete subtasks** | Manages subtasks without confirmation | Low |
+| **Retry failed requests** | Automatically retries failed API requests | Low |
+| **Answer follow-up questions** | Selects default answer for follow-up questions| Low |
+| **Update todo list** | Automatically updates task progress | Low |
+
+## Master Toggle for Quick Control
+
+The leftmost checkbox works as a master toggle:
+
+<img src="/docs/img/auto-approving-actions/auto-approving-actions-14.png" alt="Master toggle in Auto-approve toolbar" width="600" />
+
+*Master toggle (checkbox) controls all auto-approve permissions at once*
+
+Use the master toggle when:
+- Working in sensitive code (turn off)
+- Doing rapid development (turn on)
+- Switching between exploration and editing tasks
+
+## Advanced Settings Panel
+
+The settings panel provides detailed control with important security context:
+
+> **Allow Kilo Code to automatically perform operations without requiring approval. Enable these settings only if you fully trust the AI and understand the associated security risks.**
+
+To access these settings:
+
+1. Click <Codicon name="gear" /> in the top-right corner
+2. Navigate to Auto-Approve Settings
+
+<img src="/docs/img/auto-approving-actions/auto-approving-actions-4.png" alt="Settings panel auto-approve options" width="550" />
+
+*Complete settings panel view*
+
+### Read Operations
+
+:::caution Read Operations
+<img src="/docs/img/auto-approving-actions/auto-approving-actions-6.png" alt="Read-only operations setting" width="550" />
+
+**Setting:** "Always approve read-only operations"
+
+**Description:** "When enabled, Kilo Code will automatically view directory contents and read files without requiring you to click the Approve button."
+
+**Risk level:** Medium
+
+While this setting only allows reading files (not modifying them), it could potentially expose sensitive data. Still recommended as a starting point for most users, but be mindful of what files Kilo Code can access.
+:::
+
+### Write Operations
+
+:::caution Write Operations
+<img src="/docs/img/auto-approving-actions/auto-approving-actions-7.png" alt="Write operations setting with delay slider" width="550" />
+
+**Setting:** "Always approve write operations"
+
+**Description:** "Automatically create and edit files without requiring approval"
+
+**Delay slider:** "Delay after writes to allow diagnostics to detect potential problems" (Default: 1000ms)
+
+**Risk level:** High
+
+This setting allows Kilo Code to modify your files without confirmation. The delay timer is crucial:
+- Higher values (2000ms+): Recommended for complex projects where diagnostics take longer
+- Default (1000ms): Suitable for most projects
+- Lower values: Use only when speed is critical and you're in a controlled environment
+- Zero: No delay for diagnostics (not recommended for critical code)
+
+#### Write Delay & Problems Pane Integration
+
+<img src="/docs/img/auto-approving-actions/auto-approving-actions-5.png" alt="VSCode Problems pane showing diagnostic information" width="600" />
+
+*VSCode Problems pane that Kilo Code checks during the write delay*
+
+When you enable auto-approval for writing files, the delay timer works with VSCode's Problems pane:
+
+1. Kilo Code makes a change to your file
+2. VSCode's diagnostic tools analyze the change
+3. The Problems pane updates with any errors or warnings
+4. Kilo Code notices these issues before continuing
+
+This works like a human developer pausing to check for errors after changing code. You can adjust the delay time based on:
+
+- Project complexity
+- Language server speed
+- How important error detection is for your workflow
+:::
+
+### Browser Actions
+
+:::info Browser Actions
+<img src="/docs/img/auto-approving-actions/auto-approving-actions-8.png" alt="Browser actions setting" width="550" />
+
+**Setting:** "Always approve browser actions"
+
+**Description:** "Automatically perform browser actions without requiring approval"
+
+**Note:** "Only applies when the model supports computer use"
+
+**Risk level:** Medium
+
+Allows Kilo Code to control a headless browser without confirmation. This can include:
+- Opening websites
+- Navigating pages
+- Interacting with web elements
+
+Consider the security implications of allowing automated browser access.
+:::
+
+### API Requests
+
+:::info API Requests
+<img src="/docs/img/auto-approving-actions/auto-approving-actions-9.png" alt="API requests retry setting with delay slider" width="550" />
+
+**Setting:** "Always retry failed API requests"
+
+**Description:** "Automatically retry failed API requests when server returns an error response"
+
+**Delay slider:** "Delay before retrying the request" (Default: 5s)
+
+**Risk level:** Low
+
+This setting automatically retries API calls when they fail. The delay controls how long Kilo Code waits before trying again:
+- Longer delays are gentler on API rate limits
+- Shorter delays give faster recovery from transient errors
+:::
+
+### MCP Tools
+
+:::caution MCP Tools
+<img src="/docs/img/auto-approving-actions/auto-approving-actions-10.png" alt="MCP tools setting" width="550" />
+
+**Setting:** "Always approve MCP tools"
+
+**Description:** "Enable auto-approval of individual MCP tools in the MCP Servers view (requires both this setting and the tool's individual 'Always allow' checkbox)"
+
+**Risk level:** Medium-High (depends on configured MCP tools)
+
+This setting works in conjunction with individual tool permissions in the MCP Servers view. Both this global setting and the tool-specific permission must be enabled for auto-approval.
+:::
+
+### Mode Switching
+
+:::info Mode Switching
+<img src="/docs/img/auto-approving-actions/auto-approving-actions-11.png" alt="Mode switching setting" width="550" />
+
+**Setting:** "Always approve mode switching"
+
+**Description:** "Automatically switch between different modes without requiring approval"
+
+**Risk level:** Low
+
+Allows Kilo Code to change between different modes (Code, Architect, etc.) without asking for permission. This primarily affects the AI's behavior rather than system access.
+:::
+
+### Subtasks
+
+:::info Subtasks
+<img src="/docs/img/auto-approving-actions/auto-approving-actions-12.png" alt="Subtasks setting" width="550" />
+
+**Setting:** "Always approve creation & completion of subtasks"
+
+**Description:** "Allow creation and completion of subtasks without requiring approval"
+
+**Risk level:** Low
+
+Enables Kilo Code to create and complete subtasks automatically. This relates to workflow organization rather than system access.
+:::
+
+### Command Execution
+
+:::caution Command Execution
+<img src="/docs/img/auto-approving-actions/auto-approving-actions-13.png" alt="Command execution setting with whitelist interface" width="550" />
+
+**Setting:** "Always approve allowed execute operations"
+
+**Description:** "Automatically execute allowed terminal commands without requiring approval"
+
+**Command management:** "Command prefixes that can be auto-executed when 'Always approve execute operations' is enabled. Add * to allow all commands (use with caution)."
+
+**Risk level:** High
+
+This setting allows terminal command execution with controls. While risky, the whitelist feature limits what commands can run. Important security features:
+
+- Whitelist specific command prefixes (recommended)
+- Never use * wildcard in production or with sensitive data
+- Consider security implications of each allowed command
+- Always verify commands that interact with external systems
+
+**Interface elements:**
+- Text field to enter command prefixes (e.g., 'git')
+- "Add" button to add new prefixes
+- Clickable command buttons with X to remove them
+:::
+
+### Follow-Up Questions
+
+:::info Follow-Up Questions (Risk: Low)
+
+**Setting:** `Always default answer for follow-up questions`
+
+**Description:** Automatically selects the first AI-suggested answer for a follow-up question after a configurable timeout. This speeds up your workflow by letting Roo proceed without manual intervention.
+
+**Visual countdown:** When enabled, a countdown timer appears on the first suggestion button, showing the remaining time before auto-selection. The timer is displayed as a circular progress indicator that depletes as time passes.
+
+**Timeout slider:** Use the slider to set the wait time from 1 to 300 seconds (Default: 60s).
+
+**Override options:** You can cancel the auto-selection at any time by:
+- Clicking a different suggestion
+- Editing any suggestion
+- Typing your own response
+- Clicking the timer to pause it
+
+**Risk level:** Low
+
+**Use cases:**
+- Overnight runs where you want Roo to continue working
+- Repetitive tasks where the default suggestions are usually correct
+- Testing workflows where interaction isn't critical
+:::
+
+### Update Todo List
+
+:::info Update Todo List (Risk: Low)
+
+**Setting:** "Always approve todo list updates"
+
+**Description:** "Automatically update the to-do list without requiring approval"
+
+**Risk level:** Low
+
+This setting allows Roo to automatically update task progress and todo lists during work sessions. This includes:
+- Marking tasks as completed
+- Adding new discovered tasks
+- Updating task status (pending, in progress, completed)
+- Reorganizing task priorities
+
+**Benefits:**
+- Maintains real-time task progress visibility
+- Reduces interruptions during multi-step workflows
+- Keeps project status accurately reflected
+- Helps track complex task dependencies
+
+**Use cases:**
+- Long-running development sessions
+- Multi-step refactoring projects
+- Complex debugging workflows
+- Feature implementation with many subtasks
+
+This is particularly useful when combined with the Subtasks permission, as it allows Roo to maintain a complete picture of project progress without constant approval requests.
+:::

apps/kilocode-docs/docs/features/browser-use.md

@@ -0,0 +1,165 @@
+# Browser Use
+
+Kilo Code provides sophisticated browser automation capabilities that let you interact with websites directly from VS Code. This feature enables testing web applications, automating browser tasks, and capturing screenshots without leaving your development environment.
+
+:::info Model Support Required
+Browser Use within Kilo Code requires the use and advanced agentic model, and has only been tested with Claude Sonnet 3.5, 3.7, and 4
+:::
+
+## How Browser Use Works
+
+By default, Kilo Code uses a built-in browser that:
+- Launches automatically when you ask Kilo to visit a website
+- Captures screenshots of web pages
+- Allows Kilo to interact with web elements
+- Runs invisibly in the background
+
+All of this happens directly within VS Code, with no setup required.
+
+## Using Browser Use
+
+A typical browser interaction follows this pattern:
+
+1. Ask Kilo to visit a website
+2. Kilo launches the browser and shows you a screenshot
+3. Request additional actions (clicking, typing, scrolling)
+4. Kilo closes the browser when finished
+
+For example:
+
+```
+Open the browser and view our site.
+```
+
+```
+Can you check if my website at https://kilocode.ai is displaying correctly?
+```
+
+```
+Browse http://localhost:3000, scroll down to the bottom of the page and check if the footer information is displaying correctly.
+```
+
+<img src="/docs/features/KiloCodeBrowser.png" alt="Browser use example" width="300" />
+
+## How Browser Actions Work
+
+The browser_action tool controls a browser instance that returns screenshots and console logs after each action, allowing you to see the results of interactions.
+
+Key characteristics:
+- Each browser session must start with `launch` and end with `close`
+- Only one browser action can be used per message
+- While the browser is active, no other tools can be used
+- You must wait for the response (screenshot and logs) before performing the next action
+
+### Available Browser Actions
+
+| Action | Description | When to Use |
+|--------|-------------|------------|
+| `launch` | Opens a browser at a URL | Starting a new browser session |
+| `click` | Clicks at specific coordinates | Interacting with buttons, links, etc. |
+| `type` | Types text into active element | Filling forms, search boxes |
+| `scroll_down` | Scrolls down by one page | Viewing content below the fold |
+| `scroll_up` | Scrolls up by one page | Returning to previous content |
+| `close` | Closes the browser | Ending a browser session |
+
+## Browser Use Configuration/Settings
+
+:::info Default Browser Settings
+- **Enable browser tool**: Enabled
+- **Viewport size**: Small Desktop (900x600)
+- **Screenshot quality**: 75%
+- **Use remote browser connection**: Disabled
+:::
+
+### Accessing Settings
+
+To change Browser / Computer Use settings in Kilo:
+
+1. Open Settings by clicking the gear icon <Codicon name="gear" /> → Browser / Computer Use
+
+   <img src="/docs/img/browser-use/browser-use.png" alt="Browser settings menu" width="600" />
+
+### Enable/Disable Browser Use
+
+**Purpose**: Master toggle that enables Kilo to interact with websites using a Puppeteer-controlled browser.
+
+To change this setting:
+1. Check or uncheck the "Enable browser tool" checkbox within your Browser / Computer Use settings
+
+   <img src="/docs/img/browser-use/browser-use-2.png" alt="Enable browser tool setting" width="300" />
+
+### Viewport Size
+
+**Purpose**: Determines the resolution of the browser session Kilo Code uses.
+
+**Tradeoff**: Higher values provide a larger viewport but increase token usage.
+
+To change this setting:
+1. Click the dropdown menu under "Viewport size" within your Browser / Computer Use settings
+2. Select one of the available options:
+   - Large Desktop (1280x800)
+   - Small Desktop (900x600) - Default
+   - Tablet (768x1024)
+   - Mobile (360x640)
+2. Select your desired resolution.
+
+   <img src="/docs/img/browser-use/browser-use-3.png" alt="Viewport size setting" width="600" />
+
+### Screenshot Quality
+
+**Purpose**: Controls the WebP compression quality of browser screenshots.
+
+**Tradeoff**: Higher values provide clearer screenshots but increase token usage.
+
+To change this setting:
+1. Adjust the slider under "Screenshot quality" within your Browser / Computer Use settings
+2. Set a value between 1-100% (default is 75%)
+3. Higher values provide clearer screenshots but increase token usage:
+   - 40-50%: Good for basic text-based websites
+   - 60-70%: Balanced for most general browsing
+   - 80%+: Use when fine visual details are critical
+
+   <img src="/docs/img/browser-use/browser-use-4.png" alt="Screenshot quality setting" width="600" />
+
+### Remote Browser Connection
+
+**Purpose**: Connect Kilo to an existing Chrome browser instead of using the built-in browser.
+
+**Benefits**:
+- Works in containerized environments and remote development workflows
+- Maintains authenticated sessions between browser uses
+- Eliminates repetitive login steps
+- Allows use of custom browser profiles with specific extensions
+
+**Requirements**: Chrome must be running with remote debugging enabled.
+
+To enable this feature:
+1. Check the "Use remote browser connection" box in Browser / Computer Use settings
+2. Click "Test Connection" to verify
+
+   <img src="/docs/img/browser-use/browser-use-5.png" alt="Remote browser connection setting" width="600" />
+
+#### Common Use Cases
+
+- **DevContainers**: Connect from containerized VS Code to host Chrome browser
+- **Remote Development**: Use local Chrome with remote VS Code server
+- **Custom Chrome Profiles**: Use profiles with specific extensions and settings
+
+#### Connecting to a Visible Chrome Window
+
+Connect to a visible Chrome window to observe Kilo's interactions in real-time:
+
+**macOS**
+```bash
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug --no-first-run
+```
+
+**Windows**
+```bash
+"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir=C:\chrome-debug --no-first-run
+```
+
+**Linux**
+```bash
+google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug --no-first-run
+```

apps/kilocode-docs/docs/features/checkpoints.md

@@ -0,0 +1,236 @@
+# Checkpoints
+
+Checkpoints automatically version your workspace files during Kilo Code tasks, enabling non-destructive exploration of AI suggestions and easy recovery from unwanted changes.
+
+Checkpoints let you:
+- Safely experiment with AI-suggested changes
+- Easily recover from undesired modifications
+- Compare different implementation approaches
+- Revert to previous project states without losing work
+
+:::info Important Notes
+- **Checkpoints are enabled by default.**
+- **Git must be installed** for checkpoints to function - [see installation instructions](#git-installation)
+- No GitHub account or repository is required
+- No Git personal information configuration is needed
+- The shadow Git repository operates independently from your project's existing Git configuration
+:::
+
+## Configuration Options
+
+Access checkpoint settings in Kilo Code settings under the "Checkpoints" section:
+
+1. Open Settings by clicking the gear icon <Codicon name="gear" /> → Checkpoints
+2. Check or uncheck the "Enable automatic checkpoints" checkbox
+
+   <img src="/docs/img/checkpoints/checkpoints.png" alt="Checkpoint settings in Kilo Code configuration" width="500" />
+
+## How Checkpoints Work
+
+Kilo Code captures snapshots of your project's state using a shadow Git repository, separate from your main version control system. These snapshots, called checkpoints, automatically record changes throughout your AI-assisted workflow—whenever tasks begin, files change, or commands run.
+
+Checkpoints are stored as Git commits in the shadow repository, capturing:
+
+- File content changes
+- New files added
+- Deleted files
+- Renamed files
+- Binary file changes
+
+## Working with Checkpoints
+
+Checkpoints are integrated directly into your workflow through the chat interface.
+
+Checkpoints appear directly in your chat history in two forms:
+
+- **Initial checkpoint** marks your starting project state
+   <img src="/docs/img/checkpoints/checkpoints-1.png" alt="Initial checkpoint indicator in chat" width="500" />
+
+- **Regular checkpoints** appear after file modifications or command execution
+   <img src="/docs/img/checkpoints/checkpoints-2.png" alt="Regular checkpoint indicator in chat" width="500" />
+
+Each checkpoint provides two primary functions:
+
+### Viewing Differences
+
+To compare your current workspace with a previous checkpoint:
+
+1. Locate the checkpoint in your chat history
+2. Click the checkpoint's `View Differences` button
+
+   <img src="/docs/img/checkpoints/checkpoints-6.png" alt="View Differences button interface" width="100" />
+
+3. Review the differences in the comparison view:
+   - Added lines are highlighted in green
+   - Removed lines are highlighted in red
+   - Modified files are listed with detailed changes
+   - Renamed and moved files are tracked with their path changes
+   - New or deleted files are clearly marked
+
+<img src="/docs/img/checkpoints/checkpoints-3.png" alt="View differences option for checkpoints" width="800" />
+
+### Restoring Checkpoints
+
+To restore a project to a previous checkpoint state:
+
+1. Locate the checkpoint in your chat history
+2. Click the checkpoint's `Restore Checkpoint` button
+   <img src="/docs/img/checkpoints/checkpoints-7.png" alt="Restore checkpoint button interface" width="100" />
+3. Choose one of these restoration options:
+   
+   <img src="/docs/img/checkpoints/checkpoints-4.png" alt="Restore checkpoint option" width="300" />
+
+   - **Restore Files Only** - Reverts only workspace files to checkpoint state without modifying conversation history. Ideal for comparing alternative implementations while maintaining chat context, allowing you to seamlessly switch between different project states. This option does not require confirmation and lets you quickly switch between different implementations.
+   
+   - **Restore Files & Task** - Reverts both workspace files AND removes all subsequent conversation messages. Use when you want to completely reset both your code and conversation back to the checkpoint's point in time. This option requires confirmation in a dialog as it cannot be undone.
+
+      <img src="/docs/img/checkpoints/checkpoints-9.png" alt="Confirmation dialog for restoring checkpoint with files & task" width="300" />
+
+### Limitations and Considerations
+
+- **Scope**: Checkpoints only capture changes made during active Kilo Code tasks
+- **External changes**: Modifications made outside of tasks (manual edits, other tools) aren't included
+- **Large files**: Very large binary files may impact performance
+- **Unsaved work**: Restoration will overwrite any unsaved changes in your workspace
+
+## Technical Implementation
+
+### Checkpoint Architecture
+
+The checkpoint system consists of:
+
+1. **Shadow Git Repository**: A separate Git repository created specifically for checkpoint tracking that functions as the persistent storage mechanism for checkpoint state.
+
+2. **Checkpoint Service**: Handles Git operations and state management through:
+   - Repository initialization
+   - Checkpoint creation and storage
+   - Diff computation
+   - State restoration
+
+3. **UI Components**: Interface elements displayed in the chat that enable interaction with checkpoints.
+
+### Restoration Process
+
+When restoration executes, Kilo Code:
+- Performs a hard reset to the specified checkpoint commit
+- Copies all files from the shadow repository to your workspace
+- Updates internal checkpoint tracking state
+
+### Storage Type
+
+Checkpoints are task-scoped, meaning they are specific to a single task.
+
+### Diff Computation
+
+Checkpoint comparison uses Git's underlying diff capabilities to produce structured file differences:
+- Modified files show line-by-line changes
+- Binary files are properly detected and handled
+- Renamed and moved files are tracked correctly
+- File creation and deletion are clearly identified
+
+### File Exclusion and Ignore Patterns
+
+The checkpoint system uses intelligent file exclusion to track only relevant files:
+
+#### Built-in Exclusions
+
+The system has comprehensive built-in exclusion patterns that automatically ignore:
+- Build artifacts and dependency directories (`node_modules/`, `dist/`, `build/`)
+- Media files and binary assets (images, videos, audio)
+- Cache and temporary files (`.cache/`, `.tmp/`, `.bak`)
+- Configuration files with sensitive information (`.env`)
+- Large data files (archives, executables, binaries)
+- Database files and logs
+
+These patterns are written to the shadow repository's `.git/info/exclude` file during initialization.
+
+#### .gitignore Support
+
+The checkpoint system respects `.gitignore` patterns in your workspace:
+- Files excluded by `.gitignore` won't trigger checkpoint creation
+- Excluded files won't appear in checkpoint diffs
+- Standard Git ignore rules apply when staging file changes
+
+#### .kilocodeignore Behavior
+
+The `.kilocodeignore` file (which controls AI access to files) is separate from checkpoint tracking:
+- Files excluded by `.kilocodeignore` but not by `.gitignore` will still be checkpointed
+- Changes to AI-inaccessible files can still be restored through checkpoints
+
+This separation is intentional, as `.kilocodeignore` limits which files the AI can access, not which files should be tracked for version history.
+
+#### Nested Git Repositories
+
+The checkpoint system includes special handling for nested Git repositories:
+- Temporarily renames nested `.git` directories to `.git_disabled` during operations
+- Restores them after operations complete
+- Allows proper tracking of files in nested repositories
+- Ensures nested repositories remain functional and unaffected
+
+### Concurrency Control
+
+Operations are queued to prevent concurrent Git operations that might corrupt repository state. This ensures that rapid checkpoint operations complete safely even when requested in quick succession.
+
+## Git Installation
+
+Checkpoints require Git to be installed on your system. The implementation uses the `simple-git` library, which relies on Git command-line tools to create and manage shadow repositories.
+
+### macOS
+
+1. **Install with Homebrew (recommended)**:
+   ```
+   brew install git
+   ```
+
+2. **Alternative: Install with Xcode Command Line Tools**:
+   ```
+   xcode-select --install
+   ```
+
+3. **Verify installation**:
+   - Open Terminal
+   - Type `git --version`
+   - You should see a version number like `git version 2.40.0`
+
+### Windows
+
+1. **Download Git for Windows**:
+   - Visit https://git-scm.com/download/win
+   - The download should start automatically
+
+2. **Run the installer**:
+   - Accept the license agreement
+   - Choose installation location (default is recommended)
+   - Select components (default options are typically sufficient)
+   - Choose the default editor
+   - Choose how to use Git from the command line (recommended: Git from the command line and also from 3rd-party software)
+   - Configure line ending conversions (recommended: Checkout Windows-style, commit Unix-style)
+   - Complete the installation
+
+3. **Verify installation**:
+   - Open Command Prompt or PowerShell
+   - Type `git --version`
+   - You should see a version number like `git version 2.40.0.windows.1`
+
+### Linux
+
+**Debian/Ubuntu**:
+```
+sudo apt update
+sudo apt install git
+```
+
+**Fedora**:
+```
+sudo dnf install git
+```
+
+**Arch Linux**:
+```
+sudo pacman -S git
+```
+
+**Verify installation**:
+- Open Terminal
+- Type `git --version`
+- You should see a version number

apps/kilocode-docs/docs/features/code-actions.md

@@ -0,0 +1,90 @@
+import Image from '@site/src/components/Image';
+
+# Code Actions
+
+Code Actions are a powerful feature of VS Code that provide quick fixes, refactorings, and other code-related suggestions directly within the editor. Kilo Code integrates with this system to offer AI-powered assistance for common coding tasks.
+
+## What are Code Actions?
+
+Code Actions appear as a lightbulb icon (💡) in the editor gutter (the area to the left of the line numbers). They can also be accessed via the right-click context menu, or via keyboard shortcut. They are triggered when:
+
+*   You select a range of code.
+*   Your cursor is on a line with a problem (error, warning, or hint).
+*   You invoke them via command.
+
+Clicking the lightbulb, right-clicking and selecting "Kilo Code", or using the keyboard shortcut (`Ctrl+.` or `Cmd+.` on macOS, by default), displays a menu of available actions.
+
+<Image src="/docs/img/code-actions/code-actions-1.png" alt="VS Code code actions in line with code" width="500" />
+
+## Kilo Code's Code Actions
+
+Kilo Code provides the following Code Actions:
+
+*   **Add to Context:** Quickly adds the selected code to your chat with Kilo, including line numbers so Kilo knows exactly where the code is from. It's listed first in the menu for easy access. (More details below).
+*   **Explain Code:** Asks Kilo Code to explain the selected code.
+*   **Fix Code:** Asks Kilo Code to fix problems in the selected code (available when diagnostics are present).
+*   **Improve Code:** Asks Kilo Code to suggest improvements to the selected code.
+
+### Add to Context Deep Dive
+
+The **Add to Context** action is listed first in the Code Actions menu so you can quickly add code snippets to your conversation. When you use it, Kilo Code includes the filename and line numbers along with the code.
+
+This helps Kilo understand the exact context of your code within the project, allowing it to provide more relevant and accurate assistance.
+
+<Image src="/docs/img/code-actions/add-to-context.gif" alt="code actions - add to context gif" width="80%" />
+
+**Example Chat Input:**
+
+```
+Can you explain this function?
[email protected]:15:25
+```
+
+*(Where `@myFile.js:15:25` represents the code added via "Add to Context")*
+
+Each of these actions can be performed "in a new task" or "in the current task."
+
+## Using Code Actions
+
+There are three main ways to use Kilo Code's Code Actions:
+
+### 1. From the Lightbulb (💡)
+
+1.  **Select Code:** Select the code you want to work with. You can select a single line, multiple lines, or an entire block of code.
+2.  **Look for the Lightbulb:** A lightbulb icon will appear in the gutter next to the selected code (or the line with the error/warning).
+3.  **Click the Lightbulb:** Click the lightbulb icon to open the Code Actions menu.
+4.  **Choose an Action:** Select the desired Kilo Code action from the menu.
+5.  **Review and Approve:** Kilo Code will propose a solution in the chat panel. Review the proposed changes and approve or reject them.
+
+### 2. From the Right-Click Context Menu
+
+1.  **Select Code:** Select the code you want to work with.
+2.  **Right-Click:** Right-click on the selected code to open the context menu.
+3.  **Choose "Kilo Code":** Select the "Kilo Code" option from the context menu. A submenu will appear with the available Kilo Code actions.
+4.  **Choose an Action:** Select the desired action from the submenu.
+5.  **Review and Approve:** Kilo Code will propose a solution in the chat panel. Review the proposed changes and approve or reject them.
+
+### 3. From the Command Palette
+
+1.  **Select Code:** Select the code you want to work with.
+2.  **Open the Command Palette:** Press `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (macOS).
+3.  **Type a Command:** Type "Kilo Code" to filter the commands, then choose the relevant code action (e.g., "Kilo Code: Explain Code"). You can also type the start of the command, like "Kilo Code: Explain", and select from the filtered list.
+4.  **Review and Approve:** Kilo Code will propose a solution in the chat panel. Review the proposed changes and approve or reject them.
+
+## Code Actions and Current Task
+
+Each code action gives you two options:
+
+*   **in New Task:** Select this to begin a conversation with Kilo centered around this code action.
+*   **in Current Task:** If a conversation has already begun, this option will add the code action as an additional message.
+
+## Customizing Code Action Prompts
+
+You can customize the prompts used for each Code Action by modifying the "Support Prompts" in the **Prompts** tab.  This allows you to fine-tune the instructions given to the AI model and tailor the responses to your specific needs.
+
+1.  **Open the Prompts Tab:** Click the <Codicon name="notebook" /> icon in the Kilo Code top menu bar.
+2. **Find "Support Prompts":** You will see the support prompts, including "Enhance Prompt", "Explain Code", "Fix Code", and "Improve Code".
+3. **Edit the Prompts:**  Modify the text in the text area for the prompt you want to customize. You can use placeholders like `${filePath}` and `${selectedText}` to include information about the current file and selection.
+4. **Click "Done":** Save your changes.
+
+By using Kilo Code's Code Actions, you can quickly get AI-powered assistance directly within your coding workflow. This can save you time and help you write better code.

apps/kilocode-docs/docs/features/codebase-indexing.md

@@ -0,0 +1,230 @@
+import Codicon from '@site/src/components/Codicon';
+
+# Codebase Indexing
+
+Codebase Indexing enables semantic code search across your entire project using AI embeddings. Instead of searching for exact text matches, it understands the _meaning_ of your queries, helping Kilo Code find relevant code even when you don't know specific function names or file locations.
+
+<img src="/docs/img/codebase-indexing/codebase-indexing.png" alt="Codebase Indexing Settings" width="800" />
+
+## What It Does
+
+When enabled, the indexing system:
+
+1. **Parses your code** using Tree-sitter to identify semantic blocks (functions, classes, methods)
+2. **Creates embeddings** of each code block using AI models
+3. **Stores vectors** in a Qdrant database for fast similarity search
+4. **Provides the [`codebase_search`](/advanced-usage/available-tools/codebase-search) tool** to Kilo Code for intelligent code discovery
+
+This enables natural language queries like "user authentication logic" or "database connection handling" to find relevant code across your entire project.
+
+## Key Benefits
+
+- **Semantic Search**: Find code by meaning, not just keywords
+- **Enhanced AI Understanding**: Kilo Code can better comprehend and work with your codebase
+- **Cross-Project Discovery**: Search across all files, not just what's open
+- **Pattern Recognition**: Locate similar implementations and code patterns
+
+## Setup Requirements
+
+### Embedding Provider
+
+Choose one of these options for generating embeddings:
+
+**OpenAI (Recommended)**
+
+- Requires OpenAI API key
+- Supports all OpenAI embedding models
+- Default: `text-embedding-3-small`
+- Processes up to 100,000 tokens per batch
+
+**Gemini**
+
+- Requires Google AI API key
+- Supports Gemini embedding models including `gemini-embedding-001`
+- Cost-effective alternative to OpenAI
+- High-quality embeddings for code understanding
+
+**Ollama (Local)**
+
+- Requires local Ollama installation
+- No API costs or internet dependency
+- Supports any Ollama-compatible embedding model
+- Requires Ollama base URL configuration
+
+### Vector Database
+
+**Qdrant** is required for storing and searching embeddings:
+
+- **Local**: `http://localhost:6333` (recommended for testing)
+- **Cloud**: Qdrant Cloud or self-hosted instance
+- **Authentication**: Optional API key for secured deployments
+
+## Setting Up Qdrant
+
+### Quick Local Setup
+
+**Using Docker:**
+
+```bash
+docker run -p 6333:6333 qdrant/qdrant
+```
+
+**Using Docker Compose:**
+
+```yaml
+version: '3.8'
+services:
+  qdrant:
+    image: qdrant/qdrant
+    ports:
+      - '6333:6333'
+    volumes:
+      - qdrant_storage:/qdrant/storage
+volumes:
+  qdrant_storage:
+```
+
+### Production Deployment
+
+For team or production use:
+
+- [Qdrant Cloud](https://cloud.qdrant.io/) - Managed service
+- Self-hosted on AWS, GCP, or Azure
+- Local server with network access for team sharing
+
+## Configuration
+
+1. Open Kilo Code settings (<Codicon name="gear" /> icon)
+2. Navigate to **Codebase Indexing** section
+3. Enable **"Enable Codebase Indexing"** using the toggle switch
+4. Configure your embedding provider:
+   - **OpenAI**: Enter API key and select model
+   - **Gemini**: Enter Google AI API key and select embedding model
+   - **Ollama**: Enter base URL and select model
+5. Set Qdrant URL and optional API key
+6. Configure **Max Search Results** (default: 20, range: 1-100)
+7. Click **Save** to start initial indexing
+
+### Enable/Disable Toggle
+
+The codebase indexing feature includes a convenient toggle switch that allows you to:
+
+- **Enable**: Start indexing your codebase and make the search tool available
+- **Disable**: Stop indexing, pause file watching, and disable the search functionality
+- **Preserve Settings**: Your configuration remains saved when toggling off
+
+This toggle is useful for temporarily disabling indexing during intensive development work or when working with sensitive codebases.
+
+## Understanding Index Status
+
+The interface shows real-time status with color indicators:
+
+- **Standby** (Gray): Not running, awaiting configuration
+- **Indexing** (Yellow): Currently processing files
+- **Indexed** (Green): Up-to-date and ready for searches
+- **Error** (Red): Failed state requiring attention
+
+## How Files Are Processed
+
+### Smart Code Parsing
+
+- **Tree-sitter Integration**: Uses AST parsing to identify semantic code blocks
+- **Language Support**: All languages supported by Tree-sitter
+- **Markdown Support**: Full support for markdown files and documentation
+- **Fallback**: Line-based chunking for unsupported file types
+- **Block Sizing**:
+  - Minimum: 100 characters
+  - Maximum: 1,000 characters
+  - Splits large functions intelligently
+
+### Automatic File Filtering
+
+The indexer automatically excludes:
+
+- Binary files and images
+- Large files (&gt;1MB)
+- Git repositories (`.git` folders)
+- Dependencies (`node_modules`, `vendor`, etc.)
+- Files matching `.gitignore` and `.kilocode` patterns
+
+### Incremental Updates
+
+- **File Watching**: Monitors workspace for changes
+- **Smart Updates**: Only reprocesses modified files
+- **Hash-based Caching**: Avoids reprocessing unchanged content
+- **Branch Switching**: Automatically handles Git branch changes
+
+## Best Practices
+
+### Model Selection
+
+**For OpenAI:**
+
+- **`text-embedding-3-small`**: Best balance of performance and cost
+- **`text-embedding-3-large`**: Higher accuracy, 5x more expensive
+- **`text-embedding-ada-002`**: Legacy model, lower cost
+
+**For Ollama:**
+
+- **`mxbai-embed-large`**: The largest and highest-quality embedding model.
+- **`nomic-embed-text`**: Best balance of performance and embedding quality.
+- **`all-minilm`**: Compact model with lower quality but faster performance.
+
+### Security Considerations
+
+- **API Keys**: Stored securely in VS Code's encrypted storage
+- **Code Privacy**: Only small code snippets sent for embedding (not full files)
+- **Local Processing**: All parsing happens locally
+- **Qdrant Security**: Use authentication for production deployments
+
+## Current Limitations
+
+- **File Size**: 1MB maximum per file
+- **Single Workspace**: One workspace at a time
+- **Dependencies**: Requires external services (embedding provider + Qdrant)
+- **Language Coverage**: Limited to Tree-sitter supported languages for optimal parsing
+
+## Using the Search Feature
+
+Once indexed, Kilo Code can use the [`codebase_search`](/advanced-usage/available-tools/codebase-search) tool to find relevant code:
+
+**Example Queries:**
+
+- "How is user authentication handled?"
+- "Database connection setup"
+- "Error handling patterns"
+- "API endpoint definitions"
+
+The tool provides Kilo Code with:
+
+- Relevant code snippets (up to your configured max results limit)
+- File paths and line numbers
+- Similarity scores
+- Contextual information
+
+### Search Results Configuration
+
+You can control the number of search results returned by adjusting the **Max Search Results** setting:
+
+- **Default**: 20 results
+- **Range**: 1-100 results
+- **Performance**: Lower values improve response speed
+- **Comprehensiveness**: Higher values provide more context but may slow responses
+
+## Privacy & Security
+
+- **Code stays local**: Only small code snippets sent for embedding
+- **Embeddings are numeric**: Not human-readable representations
+- **Secure storage**: API keys encrypted in VS Code storage
+- **Local option**: Use Ollama for completely local processing
+- **Access control**: Respects existing file permissions
+
+## Future Enhancements
+
+Planned improvements:
+
+- Additional embedding providers
+- Multi-workspace indexing
+- Enhanced filtering and configuration options
+- Team sharing capabilities
+- Integration with VS Code's native search

apps/kilocode-docs/docs/features/custom-modes.md

@@ -0,0 +1,497 @@
+# Custom Modes
+
+Kilo Code allows you to create **custom modes** to tailor Kilo's behavior to specific tasks or workflows. Custom modes can be either **global** (available across all projects) or **project-specific** (defined within a single project).
+
+## Sticky Models for Efficient Workflow
+
+Each mode—including custom ones—features **Sticky Models**. This means Kilo Code automatically remembers and selects the last model you used with a particular mode. This lets you assign different preferred models to different tasks without constant reconfiguration, as Kilo switches between models when you change modes.
+
+## Why Use Custom Modes?
+
+- **Specialization:** Create modes optimized for specific tasks, like "Documentation Writer," "Test Engineer," or "Refactoring Expert"
+- **Safety:** Restrict a mode's access to sensitive files or commands. For example, a "Review Mode" could be limited to read-only operations
+- **Experimentation:** Safely experiment with different prompts and configurations without affecting other modes
+- **Team Collaboration:** Share custom modes with your team to standardize workflows
+
+<img src="/img/custom-modes/custom-modes.png" alt="Overview of custom modes interface" width="600" />
+
+_Kilo Code's interface for creating and managing custom modes._
+
+## What's Included in a Custom Mode?
+
+Custom modes are defined by several key properties. Understanding these concepts will help you tailor Kilo's behavior effectively.
+
+| UI Field / YAML Property                       | Conceptual Description                                                                                                                                                               |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Slug** (`slug`)                              | A unique internal identifier for the mode. Used by Kilo Code to reference the mode, especially for associating mode-specific instruction files.                                      |
+| **Name** (`name`)                              | The display name for the mode as it appears in the Kilo Code user interface. Should be human-readable and descriptive.                                                               |
+| **Description** (`description`)                | A short, user-friendly summary of the mode's purpose displayed in the mode selector UI. Keep this concise and focused on what the mode does for the user.                            |
+| **Role Definition** (`roleDefinition`)         | Defines the core identity and expertise of the mode. This text is placed at the beginning of the system prompt and defines Kilo's personality and behavior when this mode is active. |
+| **Available Tools** (`groups`)                 | Defines the allowed toolsets and file access permissions for the mode. Corresponds to selecting which general categories of tools the mode can use.                                  |
+| **When to Use** (`whenToUse`)                  | _(Optional)_ Provides guidance for Kilo's automated decision-making, particularly for mode selection and task orchestration. Used by the Orchestrator mode for task coordination.    |
+| **Custom Instructions** (`customInstructions`) | _(Optional)_ Specific behavioral guidelines or rules for the mode. Added near the end of the system prompt to further refine Kilo's behavior.                                        |
+
+## Import/Export Modes
+
+Easily share, back up, and template your custom modes. This feature lets you export any mode—and its associated rules—into a single, portable YAML file that you can import into any project.
+
+### Key Features
+
+- **Shareable Setups:** Package a mode and its rules into one file to easily share with your team
+- **Easy Backups:** Save your custom mode configurations so you never lose them
+- **Project Templates:** Create standardized mode templates for different types of projects
+- **Simple Migration:** Move modes between your global settings and specific projects effortlessly
+- **Flexible Slug Changes:** Change mode slugs in exported files without manual path editing
+
+### How it Works
+
+**Exporting a Mode:**
+
+1. Navigate to the Modes view
+2. Select the mode you wish to export
+3. Click the Export Mode button (download icon)
+4. Choose a location to save the `.yaml` file
+5. Kilo packages the mode's configuration and any rules into the YAML file
+
+**Importing a Mode:**
+
+1. Click the Import Mode button (upload icon) in the Modes view
+2. Select the mode's YAML file
+3. Choose the import level:
+   - **Project:** Available only in current workspace (saved to `.kilocodemodes` file)
+   - **Global:** Available in all projects (saved to global settings)
+
+### Changing Slugs on Import
+
+When importing modes, you can change the slug in the exported YAML file before importing:
+
+1. Export a mode with slug `original-mode`
+2. Edit the YAML file and change the slug to `new-mode`
+3. Import the file - the import process will automatically update rule file paths to match the new slug
+
+## Methods for Creating and Configuring Custom Modes
+
+You can create and configure custom modes in several ways:
+
+### 1. Ask Kilo! (Recommended)
+
+You can quickly create a basic custom mode by asking Kilo Code to do it for you. For example:
+
+```
+Create a new mode called "Documentation Writer". It should only be able to read files and write Markdown files.
+```
+
+Kilo Code will guide you through the process, prompting for necessary information and creating the mode using the preferred YAML format.
+
+### 2. Using the Prompts Tab
+
+1. **Open Prompts Tab:** Click the <Codicon name="notebook" /> icon in the Kilo Code top menu bar
+2. **Create New Mode:** Click the <Codicon name="add" /> button to the right of the Modes heading
+3. **Fill in Fields:**
+
+<img src="/img/custom-modes/custom-modes-2.png" alt="Custom mode creation interface in the Prompts tab" width="600" />
+
+_The custom mode creation interface showing fields for name, slug, description, save location, role definition, available tools, custom instructions._
+
+The interface provides fields for Name, Slug, Description, Save Location, Role Definition, When to Use (optional), Available Tools, and Custom Instructions. After filling these, click the "Create Mode" button. Kilo Code will save the new mode in YAML format.
+
+### 3. Manual Configuration (YAML & JSON)
+
+You can directly edit the configuration files to create or modify custom modes. This method offers the most control over all properties. Kilo Code now supports both YAML (preferred) and JSON formats.
+
+- **Global Modes:** Edit the `custom_modes.yaml` (preferred) or `custom_modes.json` file. Access it via Prompts Tab > <Codicon name="gear" /> (Settings Menu icon next to "Global Prompts") > "Edit Global Modes"
+- **Project Modes:** Edit the `.kilocodemodes` file (which can be YAML or JSON) in your project root. Access it via Prompts Tab > <Codicon name="gear" /> (Settings Menu icon next to "Project Prompts") > "Edit Project Modes"
+
+These files define an array/list of custom modes.
+
+## YAML Configuration Format (Preferred)
+
+YAML is now the preferred format for defining custom modes due to better readability, comment support, and cleaner multi-line strings.
+
+### YAML Example
+
+```yaml
+customModes:
+  - slug: docs-writer
+    name: 📝 Documentation Writer
+    description: A specialized mode for writing and editing technical documentation.
+    roleDefinition: You are a technical writer specializing in clear documentation.
+    whenToUse: Use this mode for writing and editing documentation.
+    customInstructions: Focus on clarity and completeness in documentation.
+    groups:
+      - read
+      - - edit # First element of tuple
+        - fileRegex: \.(md|mdx)$ # Second element is the options object
+          description: Markdown files only
+      - browser
+  - slug: another-mode
+    name: Another Mode
+    # ... other properties
+```
+
+### JSON Alternative
+
+```json
+{
+  "customModes": [
+    {
+      "slug": "docs-writer",
+      "name": "📝 Documentation Writer",
+      "description": "A specialized mode for writing and editing technical documentation.",
+      "roleDefinition": "You are a technical writer specializing in clear documentation.",
+      "whenToUse": "Use this mode for writing and editing documentation.",
+      "customInstructions": "Focus on clarity and completeness in documentation.",
+      "groups": [
+        "read",
+        [
+          "edit",
+          { "fileRegex": "\\.(md|mdx)$", "description": "Markdown files only" }
+        ],
+        "browser"
+      ]
+    }
+  ]
+}
+```
+
+## YAML/JSON Property Details
+
+### `slug`
+
+- **Purpose:** A unique identifier for the mode
+- **Format:** Must match the pattern `/^[a-zA-Z0-9-]+$/` (only letters, numbers, and hyphens)
+- **Usage:** Used internally and in file/directory names for mode-specific rules (e.g., `.kilo/rules-{slug}/`)
+- **Recommendation:** Keep it short and descriptive
+
+**YAML Example:** `slug: docs-writer`
+**JSON Example:** `"slug": "docs-writer"`
+
+### `name`
+
+- **Purpose:** The display name shown in the Kilo Code UI
+- **Format:** Can include spaces and proper capitalization
+
+**YAML Example:** `name: 📝 Documentation Writer`
+**JSON Example:** `"name": "Documentation Writer"`
+
+### `description`
+
+- **Purpose:** A short, user-friendly summary displayed below the mode name in the mode selector UI
+- **Format:** Keep this concise and focused on what the mode does for the user
+- **UI Display:** This text appears in the redesigned mode selector
+
+**YAML Example:** `description: A specialized mode for writing and editing technical documentation.`
+**JSON Example:** `"description": "A specialized mode for writing and editing technical documentation."`
+
+### `roleDefinition`
+
+- **Purpose:** Detailed description of the mode's role, expertise, and personality
+- **Placement:** This text is placed at the beginning of the system prompt when the mode is active
+
+**YAML Example (multi-line):**
+
+```yaml
+roleDefinition: >-
+  You are a test engineer with expertise in:
+  - Writing comprehensive test suites
+  - Test-driven development
+```
+
+**JSON Example:** `"roleDefinition": "You are a technical writer specializing in clear documentation."`
+
+### `groups`
+
+- **Purpose:** Array/list defining which tool groups the mode can access and any file restrictions
+- **Available Tool Groups:** `"read"`, `"edit"`, `"browser"`, `"command"`, `"mcp"`
+- **Structure:**
+  - Simple string for unrestricted access: `"edit"`
+  - Tuple (two-element array) for restricted access: `["edit", { fileRegex: "pattern", description: "optional" }]`
+
+**File Restrictions for "edit" group:**
+
+- `fileRegex`: A regular expression string to control which files the mode can edit
+- In YAML, typically use single backslashes for regex special characters (e.g., `\.md$`)
+- In JSON, backslashes must be double-escaped (e.g., `\\.md$`)
+- `description`: An optional string describing the restriction
+
+**YAML Example:**
+
+```yaml
+groups:
+  - read
+  - - edit # First element of tuple
+    - fileRegex: \.(js|ts)$ # Second element is the options object
+      description: JS/TS files only
+  - command
+```
+
+**JSON Example:**
+
+```json
+"groups": [
+  "read",
+  ["edit", { "fileRegex": "\\.(js|ts)$", "description": "JS/TS files only" }],
+  "command"
+]
+```
+
+### `whenToUse` (Optional)
+
+- **Purpose:** Provides guidance for Kilo's automated decision-making, particularly for mode selection and task orchestration
+- **Format:** A string describing ideal scenarios or task types for this mode
+- **Usage:** Used by Kilo for automated decisions and not displayed in the mode selector UI
+
+**YAML Example:** `whenToUse: This mode is best for refactoring Python code.`
+**JSON Example:** `"whenToUse": "This mode is best for refactoring Python code."`
+
+### `customInstructions` (Optional)
+
+- **Purpose:** A string containing additional behavioral guidelines for the mode
+- **Placement:** This text is added near the end of the system prompt
+
+**YAML Example (multi-line):**
+
+```yaml
+customInstructions: |-
+  When writing tests:
+  - Use describe/it blocks
+  - Include meaningful descriptions
+```
+
+**JSON Example:** `"customInstructions": "Focus on explaining concepts and providing examples."`
+
+## Benefits of YAML Format
+
+YAML is now the preferred format for defining custom modes due to several advantages:
+
+- **Readability:** YAML's indentation-based structure is easier for humans to read and understand
+- **Comments:** YAML allows for comments (lines starting with `#`), making it possible to annotate your mode definitions
+- **Multi-line Strings:** YAML provides cleaner syntax for multi-line strings using `|` (literal block) or `>` (folded block)
+- **Less Punctuation:** YAML generally requires less punctuation compared to JSON, reducing syntax errors
+- **Editor Support:** Most modern code editors provide excellent syntax highlighting and validation for YAML files
+
+While JSON is still fully supported, new modes created via the UI or by asking Kilo will default to YAML.
+
+## Migration to YAML Format
+
+### Global Modes
+
+Automatic migration from `custom_modes.json` to `custom_modes.yaml` happens when:
+
+- Kilo Code starts up
+- A `custom_modes.json` file exists
+- No `custom_modes.yaml` file exists yet
+
+The migration process preserves the original JSON file for rollback purposes.
+
+### Project Modes (`.kilocodemodes`)
+
+- No automatic startup migration occurs for project-specific files
+- Kilo Code can read `.kilocodemodes` files in either YAML or JSON format
+- When editing through the UI, JSON files will be converted to YAML format
+- For manual conversion, you can ask Kilo to help reformat configurations
+
+## Mode-Specific Instructions via Files/Directories
+
+You can provide instructions for custom modes using dedicated files or directories within your workspace, allowing for better organization and version control.
+
+### Preferred Method: Directory (`.kilo/rules-{mode-slug}/`)
+
+```
+.
+├── .kilo/
+│   └── rules-docs-writer/  # Example for mode slug "docs-writer"
+│       ├── 01-style-guide.md
+│       └── 02-formatting.txt
+└── ... (other project files)
+```
+
+### Fallback Method: Single File (`.kilorules-{mode-slug}`)
+
+```
+.
+├── .kilorules-docs-writer  # Example for mode slug "docs-writer"
+└── ... (other project files)
+```
+
+**Rules Directory Scope:**
+
+- **Global modes:** Rules are stored in `~/.kilo/rules-{slug}/`
+- **Project modes:** Rules are stored in `{workspace}/.kilo/rules-{slug}/`
+
+The directory method takes precedence if it exists and contains files. Files within the directory are read recursively and appended in alphabetical order.
+
+## Configuration Precedence
+
+Mode configurations are applied in this order:
+
+1. **Project-level mode configurations** (from `.kilocodemodes` - YAML or JSON)
+2. **Global mode configurations** (from `custom_modes.yaml`, then `custom_modes.json` if YAML not found)
+3. **Default mode configurations**
+
+**Important:** When modes with the same slug exist in both `.kilocodemodes` and global settings, the `.kilocodemodes` version completely overrides the global one for ALL properties.
+
+## Overriding Default Modes
+
+You can override Kilo Code's built-in modes (like 💻 Code, 🪲 Debug, ❓ Ask, 🏗️ Architect, 🪃 Orchestrator) by creating a custom mode with the same slug.
+
+### Global Override Example
+
+```yaml
+customModes:
+  - slug: code # Matches the default 'code' mode slug
+    name: 💻 Code (Global Override)
+    roleDefinition: You are a software engineer with global-specific constraints.
+    whenToUse: This globally overridden code mode is for JS/TS tasks.
+    customInstructions: Focus on project-specific JS/TS development.
+    groups:
+      - read
+      - - edit
+        - fileRegex: \.(js|ts)$
+          description: JS/TS files only
+```
+
+### Project-Specific Override Example
+
+```yaml
+customModes:
+  - slug: code # Matches the default 'code' mode slug
+    name: 💻 Code (Project-Specific)
+    roleDefinition: You are a software engineer with project-specific constraints for this project.
+    whenToUse: This project-specific code mode is for Python tasks within this project.
+    customInstructions: Adhere to PEP8 and use type hints.
+    groups:
+      - read
+      - - edit
+        - fileRegex: \.py$
+          description: Python files only
+      - command
+```
+
+## Understanding Regex in Custom Modes
+
+Regular expressions (`fileRegex`) offer fine-grained control over file editing permissions.
+
+:::tip
+**Let Kilo Build Your Regex Patterns**
+
+Instead of writing complex regex manually, ask Kilo:
+
+```
+Create a regex pattern that matches JavaScript files but excludes test files
+```
+
+Kilo will generate the pattern. Remember to adapt it for YAML (usually single backslashes) or JSON (double backslashes).
+:::
+
+### Important Rules for `fileRegex`
+
+- **Escaping in JSON:** In JSON strings, backslashes (`\`) must be double-escaped (e.g., `\\.md$`)
+- **Escaping in YAML:** In unquoted or single-quoted YAML strings, a single backslash is usually sufficient for regex special characters (e.g., `\.md$`)
+- **Path Matching:** Patterns match against the full relative file path from your workspace root
+- **Case Sensitivity:** Regex patterns are case-sensitive by default
+- **Validation:** Invalid regex patterns are rejected with an "Invalid regular expression pattern" error message
+
+### Common Pattern Examples
+
+| Pattern (YAML-like)              | JSON fileRegex Value                | Matches                                   | Doesn't Match                      |
+| -------------------------------- | ----------------------------------- | ----------------------------------------- | ---------------------------------- |
+| `\.md$`                          | `"\\.md$"`                          | `readme.md`, `docs/guide.md`              | `script.js`, `readme.md.bak`       |
+| `^src/.*`                        | `"^src/.*"`                         | `src/app.js`, `src/components/button.tsx` | `lib/utils.js`, `test/src/mock.js` |
+| `\.(css\|scss)$`                 | `"\\.(css\|scss)$"`                 | `styles.css`, `theme.scss`                | `styles.less`, `styles.css.map`    |
+| `docs/.*\.md$`                   | `"docs/.*\\.md$"`                   | `docs/guide.md`, `docs/api/reference.md`  | `guide.md`, `src/docs/notes.md`    |
+| `^(?!.*(test\|spec))\.(js\|ts)$` | `"^(?!.*(test\|spec))\\.(js\|ts)$"` | `app.js`, `utils.ts`                      | `app.test.js`, `utils.spec.js`     |
+
+### Key Regex Building Blocks
+
+- `\.`: Matches a literal dot (YAML: `\.`, JSON: `\\.`)
+- `$`: Matches the end of the string
+- `^`: Matches the beginning of the string
+- `.*`: Matches any character (except newline) zero or more times
+- `(a|b)`: Matches either "a" or "b"
+- `(?!...)`: Negative lookahead
+
+## Error Handling
+
+When a mode attempts to edit a file that doesn't match its `fileRegex` pattern, you'll see a `FileRestrictionError` that includes:
+
+- The mode name
+- The allowed file pattern
+- The description (if provided)
+- The attempted file path
+- The tool that was blocked
+
+## Example Configurations
+
+### Basic Documentation Writer (YAML)
+
+```yaml
+customModes:
+  - slug: docs-writer
+    name: 📝 Documentation Writer
+    description: Specialized for writing and editing technical documentation
+    roleDefinition: You are a technical writer specializing in clear documentation
+    groups:
+      - read
+      - - edit
+        - fileRegex: \.md$
+          description: Markdown files only
+    customInstructions: Focus on clear explanations and examples
+```
+
+### Test Engineer with File Restrictions (YAML)
+
+```yaml
+customModes:
+  - slug: test-engineer
+    name: 🧪 Test Engineer
+    description: Focused on writing and maintaining test suites
+    roleDefinition: You are a test engineer focused on code quality
+    whenToUse: Use for writing tests, debugging test failures, and improving test coverage
+    groups:
+      - read
+      - - edit
+        - fileRegex: \.(test|spec)\.(js|ts)$
+          description: Test files only
+      - command
+```
+
+### Security Review Mode (YAML)
+
+```yaml
+customModes:
+  - slug: security-review
+    name: 🔒 Security Reviewer
+    description: Read-only security analysis and vulnerability assessment
+    roleDefinition: You are a security specialist reviewing code for vulnerabilities
+    whenToUse: Use for security reviews and vulnerability assessments
+    customInstructions: |-
+      Focus on:
+      - Input validation issues
+      - Authentication and authorization flaws
+      - Data exposure risks
+      - Injection vulnerabilities
+    groups:
+      - read
+      - browser
+```
+
+## Troubleshooting
+
+### Common Issues
+
+- **Mode not appearing:** After creating or importing a mode, you may need to reload the VS Code window
+- **Invalid regex patterns:** Test your patterns using online regex testers before applying them
+- **Precedence confusion:** Remember that project modes completely override global modes with the same slug
+- **YAML syntax errors:** Use proper indentation (spaces, not tabs) and validate your YAML
+
+### Tips for Working with YAML
+
+- **Indentation is Key:** YAML uses indentation (spaces, not tabs) to define structure
+- **Colons for Key-Value Pairs:** Keys must be followed by a colon and a space (e.g., `slug: my-mode`)
+- **Hyphens for List Items:** List items start with a hyphen and a space (e.g., `- read`)
+- **Validate Your YAML:** Use online YAML validators or your editor's built-in validation
+
+## Community Gallery
+
+Ready to explore more? Check out the [Show and Tell](https://github.com/Kilo-Org/kilocode/discussions/categories/show-and-tell) to discover and share custom modes created by the community!

apps/kilocode-docs/docs/features/enhance-prompt.md

@@ -0,0 +1,54 @@
+# Enhance Prompt
+
+The "Enhance Prompt" feature in Kilo Code helps you improve the quality and effectiveness of your prompts before sending them to the AI model.  By clicking the <Codicon name="sparkle" /> icon in the chat input, you can automatically refine your initial request, making it clearer, more specific, and more likely to produce the desired results.
+
+## Why Use Enhance Prompt?
+
+*   **Improved Clarity:**  Kilo Code can rephrase your prompt to make it more understandable for the AI model.
+*   **Added Context:**  The enhancement process can add relevant context to your prompt, such as the current file path or selected code.
+*   **Better Instructions:**  Kilo Code can add instructions to guide the AI towards a more helpful response (e.g., requesting specific formatting or a particular level of detail).
+*   **Reduced Ambiguity:**  Enhance Prompt helps to eliminate ambiguity and ensure that Kilo Code understands your intent.
+*   **Consistency**: Kilo will consistently format prompts the same way to the AI.
+
+### Before and after
+
+<img src="/docs/img/enhance-prompt/before.png" alt="very primitive prompt" width="300" style={{display: 'inline-block', marginRight: '20px', verticalAlign: 'middle'}} />
+<img src="/docs/img/enhance-prompt/after.png" alt="enhanced prompt" width="300" style={{display: 'inline-block', verticalAlign: 'middle'}} />
+
+## How to Use Enhance Prompt
+
+1.  **Type your initial prompt:**  Enter your request in the Kilo Code chat input box as you normally would.  This can be a simple question, a complex task description, or anything in between.
+2.  **Click the <Codicon name="sparkle" /> Icon:**  Instead of pressing Enter, click the <Codicon name="sparkle" /> icon located in the bottom right of the chat input box.
+3.  **Review the Enhanced Prompt:**  Kilo Code will replace your original prompt with an enhanced version.  Review the enhanced prompt to make sure it accurately reflects your intent. You can further refine the enhanced prompt before sending.
+4.  **Send the Enhanced Prompt:**  Press Enter or click the Send icon (<Codicon name="send" />) to send the enhanced prompt to Kilo Code.
+
+## Customizing the Enhancement Process
+
+### Customizing Template
+
+The "Enhance Prompt" feature uses a customizable prompt template.  You can modify this template to tailor the enhancement process to your specific needs.
+
+1.  **Open the Prompts Tab:** Click the <Codicon name="notebook" /> icon in the Kilo Code top menu bar.
+2.  **Select "ENHANCE" Tab:** You should see listed out support prompts, including "ENHANCE". Click on this tab.
+3.  **Edit the Prompt Template:** Modify the text in the "Prompt" field.
+
+The default prompt template includes the placeholder `${userInput}`, which will be replaced with your original prompt. You can modify this to fit the model's prompt format, and instruct it how to enhance your request.
+
+### Customizing Provider
+
+Speed up prompt enhancement by switching to a more lightweight LLM model provider (e.g. GPT 4.1 Nano). This delivers faster results at lower cost while maintaining quality.
+
+Create a dedicated profile for Enhance Prompt by following the [API configuration profiles guide](/features/api-configuration-profiles).
+
+<img src="/docs/img/enhance-prompt/custom-enhance-profile.png" alt="Custom profile configuration for Enhance Prompt feature" width="600" />
+
+For a detailed walkthrough: https://youtu.be/R1nDnCK-xzw
+
+## Limitations and Best Practices
+
+*   **Experimental Feature:**  Prompt enhancement is an experimental feature. The quality of the enhanced prompt may vary depending on the complexity of your request and the capabilities of the underlying model.
+*   **Review Carefully:**  Always review the enhanced prompt before sending it.  Kilo Code may make changes that don't align with your intentions.
+*   **Iterative Process:**  You can use the "Enhance Prompt" feature multiple times to iteratively refine your prompt.
+*   **Not a Replacement for Clear Instructions:** While "Enhance Prompt" can help, it's still important to write clear and specific prompts from the start.
+
+By using the "Enhance Prompt" feature, you can improve the quality of your interactions with Kilo Code and get more accurate and helpful responses.

apps/kilocode-docs/docs/features/experimental/experimental-features.md

@@ -0,0 +1,35 @@
+# Experimental Features
+
+Kilo Code includes experimental features that are still under development.  These features may be unstable, change significantly, or be removed in future versions.  Use them with caution and be aware that they may not work as expected.
+
+**Warning:** Experimental features may have unexpected behavior, including potential data loss or security vulnerabilities.  Enable them at your own risk.
+
+## Enabling Experimental Features
+
+To enable or disable experimental features:
+
+1.  Open the Kilo Code settings (<Codicon name="gear" /> icon in the top right corner).
+2.  Go to the "Advanced Settings" section.
+3.  Find the "Experimental Features" section.
+4.  Check or uncheck the boxes for the features you want to enable or disable.
+5.  Click "Done" to save your changes.
+
+## Current Experimental Features
+
+The following experimental features are currently available:
+
+## Autocomplete
+When enabled, Kilo Code will provide inline code suggestions as you type. Currently this requires the Kilo Code API Provider in order to use it.
+
+## Concurrent file edits
+When enabled, Kilo Code can edit multiple files in a single request. When disabled, Kilo Code must edit one file at a time. Disabling this can help when working with less capable models or when you want more control over file modifications.
+
+### Power Steering
+
+When enabled, Kilo Code will remind the model about the details of its current mode definition more frequently. This will lead to stronger adherence to role definitions and custom instructions, but will use more tokens per message.
+
+## Providing Feedback
+
+If you encounter any issues with experimental features, or if you have suggestions for improvements, please report them on the [Kilo Code Code GitHub Issues page](https://github.com/Kilo-Org/kilocode) or join our [Discord server](https://kilo.love/discord) where we have channels dedciated to many experimental features.
+
+Your feedback is valuable and helps us improve Kilo Code!

apps/kilocode-docs/docs/features/fast-edits.md

@@ -0,0 +1,36 @@
+# Fast Edits
+
+:::info Default Setting
+Fast Edits (using the "Enable editing through diffs" setting) is enabled by default in Kilo Code. You typically don't need to change these settings unless you encounter specific issues or want to experiment with different diff strategies.
+:::
+
+Kilo Code offers an advanced setting to change how it edits files, using diffs (differences) instead of rewriting entire files. Enabling this feature provides significant benefits.
+
+## Enable Editing Through Diffs
+
+Open Settings by clicking the gear icon <Codicon name="gear" /> → Advanced
+
+
+
+When **Enable editing through diffs** is checked:
+
+    <img src="/docs/img/fast-edits/fast-edits-5.png" alt="Kilo Code settings showing Enable editing through diffs" width="500" />
+1.  **Faster File Editing**: Kilo modifies files more quickly by applying only the necessary changes.
+2.  **Prevents Truncated Writes**: The system automatically detects and rejects attempts by the AI to write incomplete file content, which can happen with large files or complex instructions. This helps prevent corrupted files.
+
+:::note Disabling Fast Edits
+If you uncheck **Enable editing through diffs**, Kilo will revert to writing the entire file content for every edit using the [`write_to_file`](/features/tools/write-to-file) tool, instead of applying targeted changes with [`apply_diff`](/features/tools/apply-diff). This full-write approach is generally slower for modifying existing files and leads to higher token usage.
+:::
+
+## Match Precision
+
+This slider controls how closely the code sections identified by the AI must match the actual code in your file before a change is applied.
+
+    <img src="/docs/img/fast-edits/fast-edits-4.png" alt="Kilo Code settings showing Enable editing through diffs checkbox and Match precision slider" width="500" />
+
+*   **100% (Default)**: Requires an exact match. This is the safest option, minimizing the risk of incorrect changes.
+*   **Lower Values (80%-99%)**: Allows for "fuzzy" matching. Kilo can apply changes even if the code section has minor differences from what the AI expected. This can be useful if the file has been slightly modified, but **increases the risk** of applying changes in the wrong place.
+
+**Use values below 100% with extreme caution.** Lower precision might be necessary occasionally, but always review the proposed changes carefully.
+
+Internally, this setting adjusts a `fuzzyMatchThreshold` used with algorithms like Levenshtein distance to compare code similarity.

apps/kilocode-docs/docs/features/footgun-prompting.md

@@ -0,0 +1,52 @@
+---
+sidebar_label: 'Footgun Prompting'
+---
+
+# Footgun Prompting: Override System Prompts
+
+Footgun Prompting, AKA Overriding System Prompt, allows advanced users to completely replace the default system prompt for a specific Kilo Code mode. This provides granular control over the AI's behavior but bypasses built-in safeguards.
+
+:::info **footgun** *(noun)*
+
+1.  *(programming slang, humorous, derogatory)* Any feature likely to lead to the programmer shooting themself in the foot.
+
+> The System Prompt Override is considered a footgun because modifying the core instructions without a deep understanding can lead to unexpected or broken behavior, especially regarding tool usage and response consistency.
+
+:::
+
+## How It Works
+
+1.  **Override File:** Create a file named `.kilocode/system-prompt-{mode-slug}` in your workspace root (e.g., `.kilocode/system-prompt-code` for the Code mode).
+2.  **Content:** The content of this file becomes the new system prompt for that specific mode.
+3.  **Activation:** Kilo Code automatically detects this file. When present, it replaces most of the standard system prompt sections.
+4.  **Preserved Sections:** Only the core `roleDefinition` and any `customInstructions` you've set for the mode are kept alongside your override content. Standard sections like tool descriptions, rules, and capabilities are bypassed.
+5.  **Construction:** The final prompt sent to the model looks like this:
+    ```
+    ${roleDefinition}
+
+    ${content_of_your_override_file}
+
+    ${customInstructions}
+    ```
+
+## Accessing the Feature
+
+You can find the option and instructions within the Kilo Code UI:
+
+1.  Click the MODE selector in the bottom-left of the Kilo Code text-input box.
+2.  Click "Edit..." at the bottom of the mode-selection list
+3.  Expand the **"Advanced: Override System Prompt"** section at the bottom.
+4.  Clicking the file path link within the explanation will open or create the correct override file for the currently selected mode in VS Code.
+
+<img src="/docs/img/footgun-prompting/footgun-prompting.png" alt="UI showing the Advanced: Override System Prompt section" width="500" />
+
+
+## Key Considerations & Warnings
+
+-   **Intended Audience:** Best suited for users deeply familiar with Kilo Code's prompting system and the implications of modifying core instructions.
+-   **Impact on Functionality:** Custom prompts override standard instructions, including those for tool usage and response consistency. This can cause unexpected behavior or errors if not managed carefully.
+-   **Mode-Specific:** Each override file applies only to the mode specified in its filename (`{mode-slug}`).
+-   **No File, No Override:** If the `.kilocode/system-prompt-{mode-slug}` file doesn't exist, Kilo Code uses the standard system prompt generation process for that mode.
+-   **Directory Creation:** Kilo Code ensures the `.kilocode` directory exists before attempting to read or create the override file.
+
+Use this feature cautiously. While powerful for customization, incorrect implementation can significantly degrade Kilo Code's performance and reliability for the affected mode.

apps/kilocode-docs/docs/features/mcp/mcp-vs-api.md

@@ -0,0 +1,97 @@
+---
+title: MCP vs API
+sidebar_label: MCP vs API
+---
+
+# MCP vs REST APIs: A Fundamental Distinction
+
+Comparing REST APIs to the Model Context Protocol (MCP) is a category error. They operate at different layers of abstraction and serve fundamentally different purposes in AI systems.
+
+## Architectural Differences
+
+| Feature | MCP | REST APIs |
+|---------|-----|-----------|
+| State Management | **Stateful** - maintains context across interactions | **Stateless** - each request is independent |
+| Connection Type | Persistent, bidirectional connections | One-way request/response |
+| Communication Style | JSON-RPC based with ongoing sessions | HTTP-based with discrete requests |
+| Context Handling | Context is intrinsic to the protocol | Context must be manually managed |
+| Tool Discovery | Runtime discovery of available tools | Design-time integration requiring prior knowledge |
+| Integration Approach | Runtime integration with dynamic capabilities | Design-time integration requiring code changes |
+
+## Different Layers, Different Purposes
+
+REST APIs and MCP serve different tiers in the technology stack:
+
+1. **REST**: Low-level web communication pattern that exposes operations on resources
+2. **MCP**: High-level AI protocol that orchestrates tool usage and maintains context
+
+MCP often uses REST APIs internally, but abstracts them away for the AI. Think of MCP as middleware that turns discrete web services into a cohesive environment the AI can operate within.
+
+## Context Preservation: Critical for AI Workflows
+
+MCP's stateful design solves a key limitation of REST in AI applications:
+
+- **REST Approach**: Each call is isolated, requiring manual context passing between steps
+- **MCP Approach**: One conversation context persists across multiple tool uses
+
+For example, an AI debugging a codebase can open a file, run tests, and identify errors without losing context between steps. The MCP session maintains awareness of previous actions and results.
+
+## Dynamic Tool Discovery
+
+MCP enables an AI to discover and use tools at runtime:
+
+```json
+// AI discovers available tools
+{
+  "tools": [
+    {
+      "name": "readFile",
+      "description": "Reads content from a file",
+      "parameters": {
+        "path": { "type": "string", "description": "File path" }
+      }
+    },
+    {
+      "name": "createTicket",
+      "description": "Creates a ticket in issue tracker",
+      "parameters": {
+        "title": { "type": "string" },
+        "description": { "type": "string" }
+      }
+    }
+  ]
+}
+```
+
+This "plug-and-play" capability allows new tools to be added without redeploying or modifying the AI itself.
+
+## Real-World Example: Multi-Tool Workflow
+
+Consider a task requiring multiple services: "Check recent commits, create a JIRA ticket for the bug fix, and post to Slack."
+
+**REST-based approach**:
+- Requires separate integrations for Git, JIRA, and Slack APIs
+- Needs custom code to manage context between calls
+- Breaks if any service changes its API
+
+**MCP-based approach**:
+- One unified protocol for all tools
+- Maintains context across the entire workflow
+- New tools can be swapped in without code changes
+
+## Why Kilo Code Uses MCP
+
+Kilo Code leverages MCP to provide:
+
+1. **Extensibility**: Add unlimited custom tools without waiting for official integration
+2. **Contextual awareness**: Tools can access conversation history and project context
+3. **Simplified integration**: One standard protocol rather than numerous API patterns
+4. **Runtime flexibility**: Discover and use new capabilities on-the-fly
+
+MCP creates a universal connector between Kilo Code and external services, with REST APIs often powering those services behind the scenes.
+
+## Conclusion: Complementary, Not Competing Technologies
+
+MCP doesn't replace REST APIs - it builds upon them. REST excels at providing discrete services, while MCP excels at orchestrating those services for AI agents.
+
+The critical distinction is that MCP is AI-native: it treats the model as a first-class user, providing the contextual, stateful interaction layer that AI agents need to function effectively in complex environments.

apps/kilocode-docs/docs/features/mcp/overview.md

@@ -0,0 +1,20 @@
+---
+title: MCP Overview
+sidebar_label: MCP Overview
+---
+
+# Model Context Protocol (MCP)
+
+The Model Context Protocol (MCP) is a standard for extending Kilo Code's capabilities by connecting to external tools and services. MCP servers provide additional tools and resources that help Kilo Code accomplish tasks beyond its built-in capabilities, such as accessing databases, custom APIs, and specialized functionality.
+
+## MCP Documentation
+
+This documentation is organized into several sections:
+
+* [**Using MCP in Kilo Code**](/features/mcp/using-mcp-in-kilo-code) - Comprehensive guide to configuring, enabling, and managing MCP servers with Kilo Code. Includes server settings, tool approval, and troubleshooting.
+
+* [**What is MCP?**](/features/mcp/what-is-mcp) - Clear explanation of the Model Context Protocol, its client-server architecture, and how it enables AI systems to interact with external tools.
+
+* [**STDIO & SSE Transports**](/features/mcp/server-transports) - Detailed comparison of local (STDIO) and remote (SSE) transport mechanisms with deployment considerations for each approach.
+
+* [**MCP vs API**](/features/mcp/mcp-vs-api) - Analysis of the fundamental distinction between MCP and REST APIs, explaining how they operate at different layers of abstraction for AI systems.

apps/kilocode-docs/docs/features/mcp/server-transports.md

@@ -0,0 +1,196 @@
+---
+title: MCP Server Transports
+sidebar_label: STDIO & SSE Transports
+---
+
+# MCP Server Transports: STDIO & SSE
+
+Model Context Protocol (MCP) supports two primary transport mechanisms for communication between Kilo Code and MCP servers: Standard Input/Output (STDIO) and Server-Sent Events (SSE). Each has distinct characteristics, advantages, and use cases.
+
+## STDIO Transport
+
+STDIO transport runs locally on your machine and communicates via standard input/output streams.
+
+### How STDIO Transport Works
+
+1. The client (Kilo Code) spawns an MCP server as a child process
+2. Communication happens through process streams: client writes to server's STDIN, server responds to STDOUT
+3. Each message is delimited by a newline character
+4. Messages are formatted as JSON-RPC 2.0
+
+```
+Client                    Server
+  |                         |
+  |---- JSON message ------>| (via STDIN)
+  |                         | (processes request)
+  |<---- JSON message ------| (via STDOUT)
+  |                         |
+```
+
+### STDIO Characteristics
+
+* **Locality**: Runs on the same machine as Kilo Code
+* **Performance**: Very low latency and overhead (no network stack involved)
+* **Simplicity**: Direct process communication without network configuration
+* **Relationship**: One-to-one relationship between client and server
+* **Security**: Inherently more secure as no network exposure
+
+### When to Use STDIO
+
+STDIO transport is ideal for:
+
+* Local integrations and tools running on the same machine
+* Security-sensitive operations
+* Low-latency requirements
+* Single-client scenarios (one Kilo Code instance per server)
+* Command-line tools or IDE extensions
+
+### STDIO Implementation Example
+
+```typescript
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+const server = new Server({name: 'local-server', version: '1.0.0'});
+// Register tools...
+
+// Use STDIO transport
+const transport = new StdioServerTransport(server);
+transport.listen();
+```
+
+## SSE Transport
+
+Server-Sent Events (SSE) transport runs on a remote server and communicates over HTTP/HTTPS.
+
+### How SSE Transport Works
+
+1. The client (Kilo Code) connects to the server's SSE endpoint via HTTP GET request
+2. This establishes a persistent connection where the server can push events to the client
+3. For client-to-server communication, the client makes HTTP POST requests to a separate endpoint
+4. Communication happens over two channels:
+   * Event Stream (GET): Server-to-client updates
+   * Message Endpoint (POST): Client-to-server requests
+
+```
+Client                             Server
+  |                                  |
+  |---- HTTP GET /events ----------->| (establish SSE connection)
+  |<---- SSE event stream -----------| (persistent connection)
+  |                                  |
+  |---- HTTP POST /message --------->| (client request)
+  |<---- SSE event with response ----| (server response)
+  |                                  |
+```
+
+### SSE Characteristics
+
+* **Remote Access**: Can be hosted on a different machine from Kilo Code
+* **Scalability**: Can handle multiple client connections concurrently
+* **Protocol**: Works over standard HTTP (no special protocols needed)
+* **Persistence**: Maintains a persistent connection for server-to-client messages
+* **Authentication**: Can use standard HTTP authentication mechanisms
+
+### When to Use SSE
+
+SSE transport is better for:
+
+* Remote access across networks
+* Multi-client scenarios
+* Public services
+* Centralized tools that many users need to access
+* Integration with web services
+
+### SSE Implementation Example
+
+```typescript
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import express from 'express';
+
+const app = express();
+const server = new Server({name: 'remote-server', version: '1.0.0'});
+// Register tools...
+
+// Use SSE transport
+const transport = new SSEServerTransport(server);
+app.use('/mcp', transport.requestHandler());
+app.listen(3000, () => {
+  console.log('MCP server listening on port 3000');
+});
+```
+## Local vs. Hosted: Deployment Aspects
+
+The choice between STDIO and SSE transports directly impacts how you'll deploy and manage your MCP servers.
+
+### STDIO: Local Deployment Model
+
+STDIO servers run locally on the same machine as Kilo Code, which has several important implications:
+
+* **Installation**: The server executable must be installed on each user's machine
+* **Distribution**: You need to provide installation packages for different operating systems
+* **Updates**: Each instance must be updated separately
+* **Resources**: Uses the local machine's CPU, memory, and disk
+* **Access Control**: Relies on the local machine's filesystem permissions
+* **Integration**: Easy integration with local system resources (files, processes)
+* **Execution**: Starts and stops with Kilo Code (child process lifecycle)
+* **Dependencies**: Any dependencies must be installed on the user's machine
+
+#### Practical Example
+
+A local file search tool using STDIO would:
+* Run on the user's machine
+* Have direct access to the local filesystem
+* Start when needed by Kilo Code
+* Not require network configuration
+* Need to be installed alongside Kilo Code or via a package manager
+
+### SSE: Hosted Deployment Model
+
+SSE servers can be deployed to remote servers and accessed over the network:
+
+* **Installation**: Installed once on a server, accessed by many users
+* **Distribution**: Single deployment serves multiple clients
+* **Updates**: Centralized updates affect all users immediately
+* **Resources**: Uses server resources, not local machine resources
+* **Access Control**: Managed through authentication and authorization systems
+* **Integration**: More complex integration with user-specific resources
+* **Execution**: Runs as an independent service (often continuously)
+* **Dependencies**: Managed on the server, not on user machines
+
+#### Practical Example
+
+A database query tool using SSE would:
+* Run on a central server
+* Connect to databases with server-side credentials
+* Be continuously available for multiple users
+* Require proper network security configuration
+* Be deployed using container or cloud technologies
+
+### Hybrid Approaches
+
+Some scenarios benefit from a hybrid approach:
+
+1. **STDIO with Network Access**: A local STDIO server that acts as a proxy to remote services
+2. **SSE with Local Commands**: A remote SSE server that can trigger operations on the client machine through callbacks
+3. **Gateway Pattern**: STDIO servers for local operations that connect to SSE servers for specialized functions
+
+## Choosing Between STDIO and SSE
+
+| Consideration | STDIO | SSE |
+|---------------|-------|-----|
+| **Location** | Local machine only | Local or remote |
+| **Clients** | Single client | Multiple clients |
+| **Performance** | Lower latency | Higher latency (network overhead) |
+| **Setup Complexity** | Simpler | More complex (requires HTTP server) |
+| **Security** | Inherently secure | Requires explicit security measures |
+| **Network Access** | Not needed | Required |
+| **Scalability** | Limited to local machine | Can distribute across network |
+| **Deployment** | Per-user installation | Centralized installation |
+| **Updates** | Distributed updates | Centralized updates |
+| **Resource Usage** | Uses client resources | Uses server resources |
+| **Dependencies** | Client-side dependencies | Server-side dependencies |
+
+## Configuring Transports in Kilo Code
+
+For detailed information on configuring STDIO and SSE transports in Kilo Code, including example configurations, see the [Understanding Transport Types](/features/mcp/using-mcp-in-kilo-code#understanding-transport-types) section in the Using MCP in Kilo Code guide.

apps/kilocode-docs/docs/features/mcp/using-mcp-in-kilo-code.md

@@ -0,0 +1,228 @@
+---
+title: Using MCP in Kilo Code
+sidebar_label: Using MCP in Kilo Code
+---
+
+# Using MCP in Kilo Code
+
+Model Context Protocol (MCP) extends Kilo Code's capabilities by connecting to external tools and services. This guide covers everything you need to know about using MCP with Kilo Code.
+
+<YouTubeEmbed
+  url="https://youtu.be/6O9RQoQRX8A"
+  caption="Demostrating MCP installation in Kilo Code"
+/>
+
+## Configuring MCP Servers
+
+MCP server configurations can be managed at two levels:
+
+1.  **Global Configuration**: Stored in the `mcp_settings.json` file, accessible via VS Code settings (see below). These settings apply across all your workspaces unless overridden by a project-level configuration.
+2.  **Project-level Configuration**: Defined in a `.kilocode/mcp.json` file within your project's root directory. This allows you to set up project-specific servers and share configurations with your team by committing the file to version control. Kilo Code automatically detects and loads this file if it exists.
+
+**Precedence**: If a server name exists in both global and project configurations, the **project-level configuration takes precedence**.
+
+### Editing MCP Settings Files
+
+You can edit both global and project-level MCP configuration files directly from the Kilo Code MCP settings view.
+
+1. Click the <Codicon name="gear" /> icon in the top navigation of the Kilo Code pane to open `Settings`.
+2. Click the `MCP Servers` tab on the left side
+3. Choose the `Installed` servers
+3. Click the appropriate button:
+    *   **`Edit Global MCP`**: Opens the global `mcp_settings.json` file.
+    *   **`Edit Project MCP`**: Opens the project-specific `.kilocode/mcp.json` file. If this file doesn't exist, Kilo Code will create it for you.
+
+  <img src="/docs/img/using-mcp-in-kilo-code/mcp-installed-config.png" alt="Edit Global MCP and Edit Project MCP buttons" width="600" />
+
+Both files use a JSON format with a `mcpServers` object containing named server configurations:
+
+  ```json
+  {
+    "mcpServers": {
+      "server1": {
+        "command": "python",
+        "args": ["/path/to/server.py"],
+        "env": {
+          "API_KEY": "your_api_key"
+        },
+        "alwaysAllow": ["tool1", "tool2"],
+        "disabled": false
+      }
+    }
+  }
+    ```
+    *Example of MCP Server config in Kilo Code (STDIO Transport)*
+  
+  ### Understanding Transport Types
+  
+  MCP supports two transport types for server communication:
+  
+  #### STDIO Transport
+  
+  Used for local servers running on your machine:
+  
+  * Communicates via standard input/output streams
+  * Lower latency (no network overhead)
+  * Better security (no network exposure)
+  * Simpler setup (no HTTP server needed)
+  * Runs as a child process on your machine
+  
+  For more in-depth information about how STDIO transport works, see [STDIO Transport](/features/mcp/server-transports#stdio-transport).
+  
+  STDIO configuration example:
+  ```json
+  {
+    "mcpServers": {
+      "local-server": {
+        "command": "node",
+        "args": ["/path/to/server.js"],
+        "env": {
+          "API_KEY": "your_api_key"
+        },
+        "alwaysAllow": ["tool1", "tool2"],
+        "disabled": false
+      }
+    }
+  }
+  ```
+  
+  #### SSE Transport
+  
+  Used for remote servers accessed over HTTP/HTTPS:
+  
+  * Communicates via Server-Sent Events protocol
+  * Can be hosted on a different machine
+  * Supports multiple client connections
+  * Requires network access
+  * Allows centralized deployment and management
+  
+  For more in-depth information about how SSE transport works, see [SSE Transport](/features/mcp/server-transports#sse-transport).
+  
+  SSE configuration example:
+  
+  ```json
+  {
+    "mcpServers": {
+      "remote-server": {
+        "url": "https://your-server-url.com/mcp",
+        "headers": {
+          "Authorization": "Bearer your-token"
+        },
+        "alwaysAllow": ["tool3"],
+        "disabled": false
+      }
+    }
+  }
+  ```
+
+### Deleting a Server
+
+1. Press the <Codicon name="trash" /> next to the MCP server you would like to delete
+2. Press the `Delete` button on the confirmation box
+
+  <img src="/docs/img/using-mcp-in-kilo-code/using-mcp-in-kilo-code-5.png" alt="Delete confirmation box" width="400" />
+
+### Restarting a Server
+
+1. Press the <Codicon name="refresh" /> button next to the MCP server you would like to restart
+
+### Enabling or Disabling a Server
+
+1. Press the <Codicon name="activate" /> toggle switch next to the MCP server to enable/disable it
+
+### Network Timeout
+
+To set the maximum time to wait for a response after a tool call to the MCP server:
+
+1. Click the `Network Timeout` pulldown at the bottom of the individual MCP server's config box and change the time. Default is 1 minute but it can be set between 30 seconds and 5 minutes.
+
+<img src="/docs/img/using-mcp-in-kilo-code/using-mcp-in-kilo-code-6.png" alt="Network Timeout pulldown" width="400" />
+
+### Auto Approve Tools
+
+MCP tool auto-approval works on a per-tool basis and is disabled by default. To configure auto-approval:
+
+1. First enable the global "Use MCP servers" auto-approval option in [auto-approving-actions](/features/auto-approving-actions)
+2. In the MCP server settings, locate the specific tool you want to auto-approve
+3. Check the `Always allow` checkbox next to the tool name
+
+<img src="/docs/img/using-mcp-in-kilo-code/using-mcp-in-kilo-code-7.png" alt="Always allow checkbox for MCP tools" width="120" />
+
+When enabled, Kilo Code will automatically approve this specific tool without prompting. Note that the global "Use MCP servers" setting takes precedence - if it's disabled, no MCP tools will be auto-approved.
+
+## Finding and Installing MCP Servers
+
+Kilo Code does not come with any pre-installed MCP servers. You'll need to find and install them separately.
+
+* **Community Repositories:** Check for community-maintained lists of MCP servers on GitHub
+* **Ask Kilo Code:** You can ask Kilo Code to help you find or even create MCP servers
+* **Build Your Own:** Create custom MCP servers using the SDK to extend Kilo Code with your own tools
+
+For full SDK documentation, visit the [MCP GitHub repository](https://github.com/modelcontextprotocol/).
+
+## Using MCP Tools in Your Workflow
+
+After configuring an MCP server, Kilo Code will automatically detect available tools and resources. To use them:
+
+1. Type your request in the Kilo Code chat interface
+2. Kilo Code will identify when an MCP tool can help with your task
+3. Approve the tool use when prompted (or use auto-approval)
+
+Example: "Analyze the performance of my API" might use an MCP tool that tests API endpoints.
+
+## Troubleshooting MCP Servers
+
+Common issues and solutions:
+
+* **Server Not Responding:** Check if the server process is running and verify network connectivity
+* **Permission Errors:** Ensure proper API keys and credentials are configured in your `mcp_settings.json` (for global settings) or `.kilocode/mcp.json` (for project settings).
+* **Tool Not Available:** Confirm the server is properly implementing the tool and it's not disabled in settings
+* **Slow Performance:** Try adjusting the network timeout value for the specific MCP server
+
+## Platform-Specific MCP Configuration Examples
+
+### Windows Configuration Example
+
+When setting up MCP servers on Windows, you'll need to use the Windows Command Prompt (`cmd`) to execute commands. Here's an example of configuring a Puppeteer MCP server on Windows:
+
+```json
+{
+  "mcpServers": {
+    "puppeteer": {
+      "command": "cmd",
+      "args": [
+        "/c",
+        "npx",
+        "-y",
+        "@modelcontextprotocol/server-puppeteer"
+      ]
+    }
+  }
+}
+```
+
+This Windows-specific configuration:
+- Uses the `cmd` command to access the Windows Command Prompt
+- Uses `/c` to tell cmd to execute the command and then terminate
+- Uses `npx` to run the package without installing it permanently
+- The `-y` flag automatically answers "yes" to any prompts during installation
+- Runs the `@modelcontextprotocol/server-puppeteer` package which provides browser automation capabilities
+
+:::note
+For macOS or Linux, you would use a different configuration:
+```json
+{
+  "mcpServers": {
+    "puppeteer": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-puppeteer"
+      ]
+    }
+  }
+}
+```
+:::
+
+The same approach can be used for other MCP servers on Windows, adjusting the package name as needed for different server types.

apps/kilocode-docs/docs/features/mcp/what-is-mcp.md

@@ -0,0 +1,49 @@
+---
+title: What is MCP?
+sidebar_label: What is MCP?
+---
+
+# What is MCP?
+
+MCP (Model Context Protocol) is a standardized communication protocol for LLM systems to interact with external tools and services. It functions as a universal adapter between AI assistants and various data sources or applications.
+
+## How It Works
+
+MCP uses a client-server architecture:
+
+1. The AI assistant (client) connects to MCP servers
+2. Each server provides specific capabilities (file access, database queries, API integrations)
+3. The AI uses these capabilities through a standardized interface
+4. Communication occurs via JSON-RPC 2.0 messages
+
+Think of MCP as similar to a USB-C port in the sense that any compatible LLM can connect to any MCP server to access its functionality. This standardization eliminates the need to build custom integrations for each tool and service.
+
+For example, an AI using MCP can perform tasks like "search our company database and generate a report" without requiring specialized code for each database system.
+
+## Common Questions
+
+- **Is MCP a cloud service?** MCP servers can run locally on your computer or remotely as cloud services, depending on the use case and security requirements.
+
+- **Does MCP replace other integration methods?** No. MCP complements existing tools like API plugins and retrieval-augmented generation. It provides a standardized protocol for tool interaction but doesn't replace specialized integration approaches.
+
+- **How is security handled?** Users control which MCP servers they connect to and what permissions those servers have. As with any tool that accesses data or services, use trusted sources and configure appropriate access controls.
+
+## MCP in Kilo Code
+
+Kilo Code implements the Model Context Protocol to:
+
+- Connect to both local and remote MCP servers
+- Provide a consistent interface for accessing tools
+- Extend functionality without core modifications
+- Enable specialized capabilities on demand
+
+MCP provides a standardized way for AI systems to interact with external tools and services, making complex integrations more accessible and consistent.
+
+## Learn More About MCP
+
+Ready to dig deeper? Check out these guides:
+
+- [MCP Overview](/features/mcp/overview) - A quick glance at the MCP documentation structure
+- [Using MCP in Kilo Code](/features/mcp/using-mcp-in-kilo-code) - Get started with MCP in Kilo Code, including creating simple servers
+- [MCP vs API](/features/mcp/mcp-vs-api) - Technical advantages compared to traditional APIs
+- [STDIO & SSE Transports](/features/mcp/server-transports) - Local vs. hosted deployment models

apps/kilocode-docs/docs/features/model-temperature.md

@@ -0,0 +1,93 @@
+# Model Temperature
+
+Temperature controls the randomness of AI model outputs. Adjusting this setting optimizes results for different tasks - from precise code generation to creative brainstorming. Temperature is one of the most powerful parameters for controlling AI behavior. A well-tuned temperature setting can dramatically improve the quality and appropriateness of responses for specific tasks.
+
+<img src="/docs/img/model-temperature/model-temperature.gif" alt="Animation showing temperature slider adjustment" width="100%" />
+
+## What is Temperature?
+
+Temperature is a setting (usually between 0.0 and 2.0) that controls how random or predictable the AI's output is. Finding the right balance is key: lower values make the output more focused and consistent, while higher values encourage more creativity and variation. For many coding tasks, a moderate temperature (around 0.3 to 0.7) often works well, but the best setting depends on what you're trying to achieve.
+
+:::info Temperature and Code: Common Misconceptions
+Temperature controls output randomness, not code quality or accuracy directly. Key points:
+
+*   **Low Temperature (near 0.0):** Produces predictable, consistent code. Good for simple tasks, but can be repetitive and lack creativity. It doesn't guarantee *better* code.
+*   **High Temperature:** Increases randomness, potentially leading to creative solutions but also more errors or nonsensical code. It doesn't guarantee *higher-quality* code.
+*   **Accuracy:** Code accuracy depends on the model's training and prompt clarity, not temperature.
+*   **Temperature 0.0:** Useful for consistency, but limits exploration needed for complex problems.
+:::
+
+## Default Values in Kilo Code
+
+Kilo Code uses a default temperature of 0.0 for most models, optimizing for maximum determinism and precision in code generation. This applies to OpenAI models, Anthropic models (non-thinking variants), LM Studio models, and most other providers.
+
+Some models use higher default temperatures - DeepSeek R1 models and certain reasoning-focused models default to 0.6, providing a balance between determinism and creative exploration.
+
+Models with thinking capabilities (where the AI shows its reasoning process) require a fixed temperature of 1.0 which cannot be changed, as this setting ensures optimal performance of the thinking mechanism. This applies to any model with the ":thinking" flag enabled.
+
+Some specialized models don't support temperature adjustments at all, in which case Kilo Code respects these limitations automatically.
+
+## When to Adjust Temperature
+
+Here are some examples of temperature settings that might work well for different tasks:
+
+*   **Code Mode (0.0-0.3):** For writing precise, correct code with consistent, deterministic results
+*   **Architect Mode (0.4-0.7):** For brainstorming architecture or design solutions with balanced creativity and structure
+*   **Ask Mode (0.7-1.0):** For explanations or open-ended questions requiring diverse and insightful responses
+*   **Debug Mode (0.0-0.3):** For troubleshooting bugs with consistent precision
+
+These are starting points – it's important to [experiment with different settings](#experimentation) to find what works best for your specific needs and preferences.
+
+## How to Adjust Temperature
+
+1.  **Open the Kilo Code Panel:** Click the Kilo Code icon (<img src="/docs/img/kilo-v1.svg" width="12" />) in the VS Code Side Bar
+2.  **Open Settings:** Click the <Codicon name="gear" /> icon in the top right corner
+3.  **Find Temperature Control:** Navigate to the Providers section
+4.  **Enable Custom Temperature:** Check the "Use custom temperature" box
+5.  **Set Your Value:** Adjust the slider to your preferred value
+
+    <img src="/docs/img/model-temperature/model-temperature.png" alt="Temperature setting in Kilo Code settings panel" width="550" />
+    *Temperature slider in Kilo Code settings panel*
+
+## Using API Configuration Profiles for Temperature
+
+Create multiple [API configuration profiles](/features/api-configuration-profiles) with different temperature settings:
+
+**How to set up task-specific temperature profiles:**
+
+1. Create specialized profiles like "Code - Low Temp" (0.1) and "Ask - High Temp" (0.8)
+2. Configure each profile with appropriate temperature settings
+3. Switch between profiles using the dropdown in settings or chat interface
+4. Set different profiles as defaults for each mode for automatic switching when changing modes
+
+This approach optimizes model behavior for specific tasks without manual adjustments.
+
+## Technical Implementation
+
+Kilo Code implements temperature handling with these considerations:
+
+*   User-defined settings take priority over defaults
+*   Provider-specific behaviors are respected
+*   Model-specific limitations are enforced:
+    *   Thinking-enabled models require a fixed temperature of 1.0
+    *   Some models don't support temperature adjustments
+
+## Experimentation
+
+Experimenting with different temperature settings is the most effective way to discover what works best for your specific needs:
+
+### Effective Temperature Testing
+
+1. **Start with defaults** - Begin with Kilo Code's preset values (0.0 for most tasks) as your baseline
+2. **Make incremental adjustments** - Change values in small steps (±0.1) to observe subtle differences
+3. **Test consistently** - Use the same prompt across different temperature settings for valid comparisons
+4. **Document results** - Note which values produce the best outcomes for specific types of tasks
+5. **Create profiles** - Save effective settings as [API configuration profiles](/features/api-configuration-profiles) for quick access
+
+Remember that different models may respond differently to the same temperature values, and thinking-enabled models always use a fixed temperature of 1.0 regardless of your settings.
+
+## Related Features
+
+- Works with all [API providers](/providers/openai) supported by Kilo Code
+- Complements [custom instructions](/advanced-usage/custom-instructions) for fine-tuning responses
+- Works alongside [custom modes](/features/custom-modes) you create

apps/kilocode-docs/docs/features/more-features.md

@@ -0,0 +1,41 @@
+---
+sidebar_label: Additional Features
+---
+
+
+# Additional Features
+
+Kilo Code's extras streamline routine tasks and improve accessibility.
+
+## Suggested Responses
+
+Kilo Code offers suggested responses so you spend less time typing.
+- After you ask a question, buttons appear below the chat box.
+- Click a button to reuse it as your next prompt.
+
+## Text to Speech
+
+The Text-to-Speech feature lets Kilo Code read responses aloud.
+1. Enable TTS in settings.
+2. Click the speaker icon next to any response to start listening.
+
+## Global Language Support
+
+Kilo Code supports 14 languages:
+
+- Simplified Chinese
+- Traditional Chinese
+- Spanish
+- Hindi
+- French
+- Portuguese
+- German
+- Japanese
+- Korean
+- Italian
+- Turkish
+- Vietnamese
+- Polish
+- Catalan
+
+Change languages under **Advanced Settings > Language**.

apps/kilocode-docs/docs/features/settings-management.md

@@ -0,0 +1,60 @@
+---
+title: Import, Export, and Reset Settings
+sidebar_label: Import/Export/Reset Settings
+description: Manage your Kilo Code settings by exporting, importing, or resetting them to defaults.
+---
+
+# Import, Export, and Reset Settings
+
+Kilo Code allows you to manage your configuration settings effectively through export, import, and reset options. These features are useful for backing up your setup, sharing configurations with others, or restoring default settings if needed.
+
+You can find these options at the bottom of the Kilo Code settings page, accessible via the gear icon (<i class="codicon codicon-gear"></i>) in the Kilo Code chat view.
+
+<img src="/docs/img/settings-management/settings-management.png" alt="Export, Import, and Reset buttons in Kilo Code settings" width="400" />
+*Image: Export, Import, and Reset buttons.*
+
+## Export Settings
+
+Clicking the **Export** button saves your current Kilo Code settings to a JSON file.
+
+*   **What's Exported:** The file includes your configured API Provider Profiles and Global Settings (UI preferences, mode configurations, context settings, etc.).
+*   **Security Warning:** The exported JSON file contains **all** your configured API Provider Profiles and Global Settings. Crucially, this includes **API keys in plaintext**. Treat this file as highly sensitive. Do not share it publicly or with untrusted individuals, as it grants access to your API accounts.
+*   **Process:**
+    1.  Click **Export**.
+    2.  A file save dialog appears, suggesting `kilo-code-settings.json` as the filename (usually in your `~/Documents` folder).
+    3.  Choose a location and save the file.
+
+This creates a backup of your configuration or a file you can share.
+
+## Import Settings
+
+Clicking the **Import** button allows you to load settings from a previously exported JSON file.
+
+*   **Process:**
+    1.  Click **Import**.
+    2.  A file open dialog appears. Select the `kilo-code-settings.json` file (or similarly named file) you want to import.
+    3.  Kilo Code reads the file, validates its contents against the expected schema, and applies the settings.
+*   **Merging:** Importing settings **merges** the configurations. It adds new API profiles and updates existing ones and global settings based on the file content. It does **not** delete configurations present in your current setup but missing from the imported file.
+*   **Validation:** Only valid settings matching the internal schema can be imported, preventing configuration errors. A success notification appears upon completion.
+
+## Reset Settings
+
+Clicking the **Reset** button completely clears all Kilo Code configuration data and returns the extension to its default state. This is a destructive action intended for troubleshooting or starting fresh.
+
+*   **Warning:** This action is **irreversible**. It permanently deletes all API configurations (including keys stored in secret storage), custom modes, global settings, and task history.
+
+*   **Process:**
+    1.  Click the red **Reset** button.
+    2.  A confirmation dialog appears, warning that the action cannot be undone.
+    3.  Click "Yes" to confirm.
+
+*   **What is Reset:**
+    *   **API Provider Profiles:** All configurations are deleted from settings and secret storage.
+    *   **Global Settings:** All preferences (UI, modes, approvals, browser, etc.) are reset to defaults.
+    *   **Custom Modes:** All user-defined modes are deleted.
+    *   **Secret Storage:** All API keys and other secrets managed by Kilo Code are cleared.
+    *   **Task History:** The current task stack is cleared.
+
+*   **Result:** Kilo Code returns to its initial state, as if freshly installed, with default settings and no user configurations.
+
+Use this option only if you are certain you want to remove all Kilo Code data or if instructed during troubleshooting. Consider exporting your settings first if you might want to restore them later.

apps/kilocode-docs/docs/features/shell-integration.md

@@ -0,0 +1,382 @@
+# Terminal Shell Integration
+
+Terminal Shell Integration is a key feature that enables Kilo Code to execute commands in your terminal and intelligently process their output. This bidirectional communication between the AI and your development environment unlocks powerful automation capabilities.
+
+## What is Shell Integration?
+
+Shell integration is automatically enabled in Kilo Code and connects directly to your terminal's command execution lifecycle without requiring any setup from you. This built-in feature allows Kilo Code to:
+
+- Execute commands on your behalf through the [`execute_command`](/features/tools/execute-command) tool
+- Read command output in real-time without manual copy-pasting
+- Automatically detect and fix errors in running applications
+- Observe command exit codes to determine success or failure
+- Track working directory changes as you navigate your project
+- React intelligently to terminal output without user intervention
+
+When Kilo Code needs to perform tasks like installing dependencies, starting a development server, or analyzing build errors, shell integration works behind the scenes to make these interactions smooth and effective.
+
+## Getting Started with Shell Integration
+
+Shell integration is built into Kilo Code and works automatically in most cases. If you see "Shell Integration Unavailable" messages or experience issues with command execution, try these solutions:
+
+1. **Update VSCode/Cursor** to the latest version (VSCode 1.93+ required)
+2. **Ensure a compatible shell is selected**: Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`) → "Terminal: Select Default Profile" → Choose bash, zsh, PowerShell, or fish
+3. **Windows PowerShell users**: Run `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` then restart VSCode
+4. **WSL users**: Add `. "$(code --locate-shell-integration-path bash)"` to your `~/.bashrc`
+
+## Terminal Integration Settings
+
+Kilo Code provides several settings to fine-tune shell integration. Access these in the Kilo Code sidebar under Settings → Terminal.
+
+### Basic Settings
+
+#### Terminal Output Limit
+<img src="/docs/img/shell-integration/terminal-output-limit.png" alt="Terminal output limit slider set to 500" width="500" />
+Controls the maximum number of lines captured from terminal output. When exceeded, it keeps 20% of the beginning and 80% of the end with a truncation message in between. This prevents excessive token usage while maintaining context. Default: 500 lines.
+Controls the maximum number of lines captured from terminal output. When exceeded, lines are removed from the middle to save tokens. Default: 500 lines.
+
+#### Terminal Shell Integration Timeout
+<img src="/docs/img/shell-integration/shell-integration-timeout.png" alt="Terminal shell integration timeout slider set to 15s" width="500" />
+
+Maximum time to wait for shell integration to initialize before executing commands. Increase this value if you experience "Shell Integration Unavailable" errors. Default: 15 seconds.
+
+#### Terminal Command Delay
+<img src="/docs/img/shell-integration/terminal-command-delay.png" alt="Terminal command delay slider set to 0ms" width="500" />
+
+Adds a small pause after running commands to help Kilo Code capture all output correctly. This setting can significantly impact shell integration reliability due to VSCode's implementation of terminal integration across different operating systems and shell configurations:
+
+- **Default**: 0ms
+- **Common Values**:
+  * 0ms: Works best for some users with newer VSCode versions
+  * 50ms: Historical default, still effective for many users
+  * 150ms: Recommended for PowerShell users
+- **Note**: Different values may work better depending on your:
+  * VSCode version
+  * Shell customizations (oh-my-zsh, powerlevel10k, etc.)
+  * Operating system and environment
+
+### Advanced Settings
+
+:::info Important
+**Terminal restart required for these settings**
+
+Changes to advanced terminal settings only take effect after restarting your terminals. To restart a terminal:
+
+1. Click the trash icon in the terminal panel to close the current terminal
+2. Open a new terminal with Terminal → New Terminal or <kbd>Ctrl</kbd>+<kbd>`</kbd> (backtick)
+
+Always restart all open terminals after changing any of these settings.
+:::
+
+#### PowerShell Counter Workaround
+<img src="/docs/img/shell-integration/power-shell-workaround.png" alt="PowerShell counter workaround checkbox" width="600" />
+
+Helps PowerShell run the same command multiple times in a row. Enable this if you notice Kilo Code can't run identical commands consecutively in PowerShell.
+
+#### Clear ZSH EOL Mark
+<img src="/docs/img/shell-integration/clear-zsh-eol-mark.png" alt="Clear ZSH EOL mark checkbox" width="600" />
+
+Prevents ZSH from adding special characters at the end of output lines that can confuse Kilo Code when reading terminal results.
+
+#### Oh My Zsh Integration
+<img src="/docs/img/shell-integration/oh-my-zsh.png" alt="Enable Oh My Zsh integration checkbox" width="600" />
+
+Makes Kilo Code work better with the popular [Oh My Zsh](https://ohmyz.sh/) shell customization framework. Turn this on if you use Oh My Zsh and experience terminal issues.
+
+#### Powerlevel10k Integration
+<img src="/docs/img/shell-integration/power10k.png" alt="Enable Powerlevel10k integration checkbox" width="600" />
+
+Improves compatibility if you use the Powerlevel10k theme for ZSH. Turn this on if your fancy terminal prompt causes issues with Kilo Code.
+
+#### ZDOTDIR Handling
+<img src="/docs/img/shell-integration/zdotdir.png" alt="Enable ZDOTDIR handling checkbox" width="600" />
+
+Helps Kilo Code work with custom ZSH configurations without interfering with your personal shell settings and customizations.
+
+## Troubleshooting Shell Integration
+
+### PowerShell Execution Policy (Windows)
+
+PowerShell restricts script execution by default. To configure:
+
+1. Open PowerShell as Administrator
+2. Check current policy: `Get-ExecutionPolicy`
+3. Set appropriate policy: `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser`
+
+Common policies:
+- `Restricted`: No scripts allowed (default)
+- `RemoteSigned`: Local scripts can run; downloaded scripts need signing
+- `Unrestricted`: All scripts run with warnings
+- `AllSigned`: All scripts must be signed
+
+### Manual Shell Integration Installation
+
+If automatic integration fails, add the appropriate line to your shell configuration:
+
+**Bash** (`~/.bashrc`):
+```bash
+[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path bash)"
+```
+
+**Zsh** (`~/.zshrc`):
+```bash
+[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path zsh)"
+```
+
+**PowerShell** (`$Profile`):
+```powershell
+if ($env:TERM_PROGRAM -eq "vscode") { . "$(code --locate-shell-integration-path pwsh)" }
+```
+
+**Fish** (`~/.config/fish/config.fish`):
+```fish
+string match -q "$TERM_PROGRAM" "vscode"; and . (code --locate-shell-integration-path fish)
+```
+
+### Terminal Customization Issues
+
+If you use terminal customization tools:
+
+**Powerlevel10k**:
+```bash
+# Add before sourcing powerlevel10k in ~/.zshrc
+typeset -g POWERLEVEL9K_TERM_SHELL_INTEGRATION=true
+```
+
+**Alternative**: Enable the Powerlevel10k Integration setting in Kilo Code.
+
+### Verifying Shell Integration Status
+
+Confirm shell integration is active with these commands:
+
+**Bash**:
+```bash
+set | grep -i '[16]33;'
+echo "$PROMPT_COMMAND" | grep vsc
+trap -p DEBUG | grep vsc
+```
+
+**Zsh**:
+```zsh
+functions | grep -i vsc
+typeset -p precmd_functions preexec_functions
+```
+
+**PowerShell**:
+```powershell
+Get-Command -Name "*VSC*" -CommandType Function
+Get-Content Function:\Prompt | Select-String "VSCode"
+```
+
+**Fish**:
+```fish
+functions | grep -i vsc
+functions fish_prompt | grep -i vsc
+```
+
+Visual indicators of active shell integration:
+1. Shell integration indicator in terminal title bar
+2. Command detection highlighting
+3. Working directory updates in terminal title
+4. Command duration and exit code reporting
+
+## WSL Terminal Integration Methods
+
+When using Windows Subsystem for Linux (WSL), there are two distinct ways to use VSCode with WSL, each with different implications for shell integration:
+
+### Method 1: VSCode Windows with WSL Terminal
+
+In this setup:
+- VSCode runs natively in Windows
+- You use the WSL terminal integration feature in VSCode
+- Shell commands are executed through the WSL bridge
+- May experience additional latency due to Windows-WSL communication
+- Shell integration markers may be affected by the WSL-Windows boundary: you must make sure that `source "$(code --locate-shell-integration-path <shell>)"` is loaded for your shell within the WSL environment because it may not get automatically loaded; see above.
+
+### Method 2: VSCode Running Within WSL
+
+In this setup:
+- You launch VSCode directly from within WSL using `code .`
+- VSCode server runs natively in the Linux environment
+- Direct access to Linux filesystem and tools
+- Better performance and reliability for shell integration
+- Shell integration is loaded automatically since VSCode runs natively in the Linux environment
+- Recommended approach for WSL development
+
+For optimal shell integration with WSL, we recommend:
+1. Open your WSL distribution
+2. Navigate to your project directory
+3. Launch VSCode using `code .`
+4. Use the integrated terminal within VSCode
+
+## Known Issues and Workarounds
+
+### VS Code Shell Integration for Fish + Cygwin on Windows
+
+For fellow Windows users running Fish terminal within a Cygwin environment, here's how VS Code's shell integration works:
+
+1.  **(Optional) Locate the Shell Integration Script:**
+    Open your Fish terminal *within VS Code* and run the following command:
+    ```bash
+    code --locate-shell-integration-path fish
+    ```
+    This will output the path to the `shellIntegration.fish` script. Note down this path.
+
+2.  **Update Your Fish Configuration:**
+    Edit your `config.fish` file (usually located at `~/.config/fish/config.fish` within your Cygwin home directory). Add the following line, preferably within an `if status is-interactive` block or at the very end of the file:
+
+    ```fish
+    # Example config.fish structure
+    if status is-interactive
+        # Your other interactive shell configurations...
+        # automatic locate integration script:
+        string match -q "$TERM_PROGRAM" "vscode"; and . (code --locate-shell-integration-path fish)
+
+        # Or if the above fails for you:
+        # Source the VS Code shell integration script
+        # IMPORTANT: Replace the example path below with the actual path you found in Step 1.
+        # Make sure the path is in a format Cygwin can understand (e.g., using /cygdrive/c/...).
+        # source "/cygdrive/c/Users/YourUser/.vscode/extensions/..../shellIntegration.fish"
+    end
+    ```
+    *Remember to replace the example path with the actual path from Step 1, correctly formatted for Cygwin.*
+
+3.  **Configure VS Code Terminal Profile:**
+    Open your VS Code `settings.json` file (Ctrl+Shift+P -> "Preferences: Open User Settings (JSON)"). Update or add the Fish profile under `terminal.integrated.profiles.windows` like this:
+
+    ```json
+    {
+      // ... other settings ...
+
+      "terminal.integrated.profiles.windows": {
+        // ... other profiles ...
+
+        // Recommended: Use bash.exe to launch fish as a login shell
+        "fish": {
+          "path": "C:\\cygwin64\\bin\\bash.exe", // Or your Cygwin bash path
+          "args": [
+            "--login", // Ensures login scripts run (important for Cygwin environment)
+            "-i",      // Ensures bash runs interactively
+            "-c",
+            "exec fish" // Replace bash process with fish
+          ],
+          "icon": "terminal-bash" // Optional: Use a recognizable icon
+        }
+        // Alternative (if the above fails): Launch fish directly
+        "fish-direct": {
+          "path": "C:\\cygwin64\\bin\\fish.exe", // Ensure this is in your Windows PATH or provide full path
+          // Use 'options' here instead of 'args'; otherwise, you might encounter the error "terminal process terminated exit code 1".
+          "options": ["-l", "-c"], // Example: login and interactive flags.
+          "icon": "terminal-fish" // Optional: Use a fish icon
+        }
+      },
+
+      // Optional: Set fish as your default if desired
+      // "terminal.integrated.defaultProfile.windows": "fish", // or "fish-direct" depending what you use.
+
+      // ... other settings ...
+    }
+    ```
+    *Note: Using `bash.exe --login -i -c "exec fish"` is often more reliable in Cygwin environments for ensuring the correct environment setup before `fish` starts. However, if that approach doesn't work, try the `fish-direct` profile configuration.*
+
+4.  **Restart VS Code:**
+    Close and reopen Visual Studio Code completely to apply the changes.
+
+5.  **Verify:**
+    Open a new Fish terminal in VS Code. The shell integration features (like command decorations, better command history navigation, etc.) should now be active. You can test basic functionality by running simple commands like `echo "Hello from integrated Fish!"`. <img src="/img/shell-integration/shell-integration-8.png" alt="Fish Cygwin Integration Example" width="600" />
+
+This setup works reliably on Windows systems using Cygwin, Fish, and the Starship prompt, and should assist users with similar configurations.
+
+
+### Shell Integration Failures After VSCode 1.98
+
+**Issue**: After VSCode updates beyond version 1.98, shell integration may fail with the error "VSCE output start escape sequence (]633;C or ]133;C) not received".
+
+**Solutions**:
+1. **Set Terminal Command Delay**:
+   - Set the Terminal Command Delay to 50ms in Kilo Code settings
+   - Restart all terminals after changing this setting
+   - This matches older default behavior and may resolve the issue, however some users have reported that a value of 0ms works better. This is a workaround for upstream VSCode problems.
+
+2. **Roll Back VSCode Version**:
+   - Download VSCode v1.98 from [VSCode Updates](https://code.visualstudio.com/updates/v1_98)
+   - Replace your current VSCode installation
+   - No backup of Kilo settings needed
+
+3. **WSL-Specific Workaround**:
+   - If using WSL, ensure you launch VSCode from within WSL using `code .`
+
+4. **ZSH Users**:
+   - Try enabling some or all ZSH-related workarounds in Kilo Code settings
+   - These settings can help regardless of your operating system
+
+## Known Issues and Workarounds
+
+### Ctrl+C Behavior
+
+**Issue**: If text is already typed in the terminal when Kilo Code tries to run a command, Kilo Code will press Ctrl+C first to clear the line, which can interrupt running processes.
+
+**Workaround**: Make sure your terminal prompt is empty (no partial commands typed) before asking Kilo Code to execute terminal commands.
+
+### Multi-line Command Issues
+
+**Issue**: Commands that span multiple lines can confuse Kilo Code and may show output from previous commands mixed in with current output.
+
+**Workaround**: Instead of multi-line commands, use command chaining with `&&` to keep everything on one line (e.g., `echo a && echo b` instead of typing each command on a separate line).
+
+### PowerShell-Specific Issues
+
+1. **Premature Completion**: PowerShell sometimes tells Kilo Code a command is finished before all the output has been shown.
+2. **Repeated Commands**: PowerShell may refuse to run the same command twice in a row.
+
+**Workaround**: Enable the "PowerShell counter workaround" setting and set a terminal command delay of 150ms in the settings to give commands more time to complete.
+
+### Incomplete Terminal Output
+
+**Issue**: Sometimes VS Code doesn't show or capture all the output from a command.
+
+**Workaround**: If you notice missing output, try closing and reopening the terminal tab, then run the command again. This refreshes the terminal connection.
+
+## Troubleshooting Resources
+
+### Checking Debug Logs
+When shell integration issues occur, check the debug logs:
+1. Open Help → Toggle Developer Tools → Console
+2. Set "Show All Levels" to see all log messages
+3. Look for messages containing `[Terminal Process]`
+4. Check `preOutput` content in error messages:
+   - Empty preOutput (`''`) means VSCode sent no data
+   - This indicates a potential VSCode shell integration issue, or an upstream bug that is out of our control
+   - The absence of shell integration markers may require adjusting settings to work around possible upstream bugs or local workstation configuration issues related to shell initialization and VSCode's loading of special shell integration hooks
+
+### Using the VSCode Terminal Integration Test Extension
+The [VSCode Terminal Integration Test Extension](https://github.com/KJ7LNW/vsce-test-terminal-integration) helps diagnose shell integration issues by testing different settings combinations:
+
+
+1. **When Commands Stall**:
+   - If you see "command already running" warnings, click "Reset Stats" to reset the terminal state
+   - These warnings indicate shell integration is not working
+   - Try different settings combinations until you find one that works
+   - If it really gets stuck, restart the extension by closing the window and pressing F5
+
+2. **Testing Settings**:
+   - Systematically try different combinations of:
+     * Terminal Command Delay
+     * Shell Integration settings
+   - Document which combinations succeed or fail
+   - This helps identify patterns in shell integration issues
+
+3. **Reporting Issues**:
+   - Once you find a problematic configuration
+   - Document the exact settings combination
+   - Note your environment (OS, VSCode version, shell, and any shell prompt customization)
+   - Open an issue with these details to help improve shell integration
+
+## Support
+
+If you've followed these steps and are still experiencing problems, please:
+
+1. Check the [Kilo Code GitHub Issues](https://github.com/Kilo-Org/kilocode/issues) to see if others have reported similar problems
+2. If not, create a new issue with details about your operating system, VSCode/Cursor version, and the steps you've tried
+
+For additional help, join our [Discord](https://kilocode.ai/discord).

apps/kilocode-docs/docs/features/slash-commands/workflows.mdx

@@ -0,0 +1,88 @@
+---
+title: "Workflows"
+sidebarTitle: "Workflows"
+---
+
+Workflows automate repetitive tasks by defining step-by-step instructions for Kilo Code to execute. Invoke any workflow by typing `/[workflow-name.md]` in the chat.
+
+<img src="/docs/img/slash-commands/workflows.png" alt="Workflows tab in Kilo Code" width="600" />
+
+## Creating Workflows
+
+Workflows are markdown files stored in `.kilocode/workflows/`:
+- **Global workflows**: `~/.kilocode/workflows/` (available in all projects)
+- **Project workflows**: `[project]/.kilocode/workflows/` (project-specific)
+
+### Basic Setup
+
+1. Create a `.md` file with step-by-step instructions
+2. Save it in your workflows directory
+3. Type `/filename.md` to execute
+
+### Workflow Capabilities
+
+Workflows can leverage:
+- [Built-in tools](/features/tools/tool-use-overview): [`read_file()`](/features/tools/read-file), [`search_files()`](/features/tools/search-files), [`execute_command()`](/features/tools/execute-command)
+- CLI tools: `gh`, `docker`, `npm`, custom scripts
+- [MCP integrations](/features/mcp/overview): Slack, databases, APIs
+- [Mode switching](/basic-usage/using-modes): [`new_task()`](/features/tools/new-task) for specialized contexts
+
+## Common Workflow Patterns
+
+**Release Management**
+```markdown
+1. Gather merged PRs since last release
+2. Generate changelog from commit messages
+3. Update version numbers
+4. Create release branch and tag
+5. Deploy to staging environment
+```
+
+**Project Setup**
+```markdown
+1. Clone repository template
+2. Install dependencies (`npm install`, `pip install -r requirements.txt`)
+3. Configure environment files
+4. Initialize database/services
+5. Run initial tests
+```
+
+**Code Review Preparation**
+```markdown
+1. Search for TODO comments and debug statements
+2. Run linting and formatting
+3. Execute test suite
+4. Generate PR description from recent commits
+```
+
+## Example: PR Submission Workflow
+
+Let's walk through creating a workflow for submitting a pull request. This workflow handles the entire process from code review to deployment notification.
+
+Create a file called `submit-pr.md` in your `.kilocode/workflows` directory:
+
+```markdown
+# Submit PR Workflow
+
+You are helping submit a pull request. Follow these steps:
+
+1. First, use `search_files` to check for any TODO comments or console.log statements that shouldn't be committed
+2. Run tests using `execute_command` with `npm test` or the appropriate test command
+3. If tests pass, stage and commit changes with a descriptive commit message
+4. Push the branch and create a pull request using `gh pr create`
+5. Use `ask_followup_question` to get the PR title and description from the user
+
+Parameters needed (ask if not provided):
+- Branch name
+- Reviewers to assign
+```
+
+Now you can trigger this workflow by typing `/submit-pr.md` in the chat. Kilo Code will:
+
+- Scan your code for common issues before committing
+- Run your test suite to catch problems early
+- Handle the Git operations and PR creation
+- Notify your team automatically
+- Set up follow-up tasks for deployment
+
+This saves you from manually running the same 7-step process every time you want to submit code for review.

apps/kilocode-docs/docs/features/suggested-responses.md

@@ -0,0 +1,45 @@
+---
+sidebar_label: Suggested Responses
+---
+
+import Codicon from '@site/src/components/Codicon';
+
+# Suggested Responses
+
+When Kilo Code needs more information to complete a task, it uses the [`ask_followup_question` tool](/features/tools/ask-followup-question). To make responding easier and faster, Kilo Code often provides suggested answers alongside the question.
+
+## Overview
+
+Suggested Responses appear as clickable buttons directly below Kilo Code's question in the chat interface. They offer pre-formulated answers relevant to the question, helping you provide input quickly.
+
+<img src="/docs/img/suggested-responses/suggested-responses.png" alt="Example of Kilo Code asking a question with suggested response buttons below it" width="500" />
+
+## How It Works
+
+1.  **Question Appears**: Kilo Code asks a question using the `ask_followup_question` tool.
+2.  **Suggestions Displayed**: If suggestions are provided by Kilo Code, they appear as buttons below the question.
+3.  **Interaction**: You can interact with these suggestions in two ways.
+
+## Interacting with Suggestions
+
+You have two options for using suggested responses:
+
+1.  **Direct Selection**:
+    *   **Action**: Simply click the button containing the answer you want to provide.
+    *   **Result**: The selected answer is immediately sent back to Kilo Code as your response. This is the quickest way to reply if one of the suggestions perfectly matches your intent.
+
+2.  **Edit Before Sending**:
+    *   **Action**:
+        *   Hold down `Shift` and click the suggestion button.
+        *   *Alternatively*, hover over the suggestion button and click the pencil icon (<Codicon name="edit" />) that appears.
+    *   **Result**: The text of the suggestion is copied into the chat input box. You can then modify the text as needed before pressing Enter to send your customized response. This is useful when a suggestion is close but needs minor adjustments.
+
+<img src="/docs/img/suggested-responses/suggested-responses-1.png" alt="Chat input box showing text copied from a suggested response, ready for editing" width="600" />
+
+## Benefits
+
+*   **Speed**: Quickly respond without typing full answers.
+*   **Clarity**: Suggestions often clarify the type of information Kilo Code needs.
+*   **Flexibility**: Edit suggestions to provide precise, customized answers when needed.
+
+This feature streamlines the interaction when Kilo Code requires clarification, allowing you to guide the task effectively with minimal effort.

apps/kilocode-docs/docs/features/tools/access-mcp-resource.md

@@ -0,0 +1,126 @@
+# 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/docs/features/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/docs/features/tools/ask-followup-question.md

@@ -0,0 +1,169 @@
+# 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/docs/features/tools/attempt-completion.md

@@ -0,0 +1,175 @@
+# 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/docs/features/tools/browser-action.md

@@ -0,0 +1,152 @@
+# 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/docs/features/tools/codebase-search.md

@@ -0,0 +1,244 @@
+# 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/docs/features/tools/execute-command.md

@@ -0,0 +1,153 @@
+# 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/docs/features/tools/list-code-definition-names.md

@@ -0,0 +1,116 @@
+# 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/docs/features/tools/list-files.md

@@ -0,0 +1,132 @@
+# 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/docs/features/tools/new-task.md

@@ -0,0 +1,103 @@
+# 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/docs/features/tools/read-file.md

@@ -0,0 +1,181 @@
+
+# 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/docs/features/tools/search-files.md

@@ -0,0 +1,128 @@
+
+# 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/docs/features/tools/switch-mode.md

@@ -0,0 +1,151 @@
+# 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/docs/features/tools/tool-use-overview.md

@@ -0,0 +1,246 @@
+# 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), [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
+- [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/docs/features/tools/update-todo-list.md

@@ -0,0 +1,159 @@
+# 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/docs/features/tools/use-mcp-tool.md

@@ -0,0 +1,188 @@
+# 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/docs/features/tools/write-to-file.md

@@ -0,0 +1,169 @@
+# 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/docs/getting-started/connecting-api-provider.md

@@ -0,0 +1,86 @@
+---
+sidebar_label: Connecting To A Provider
+---
+
+# Connecting an AI Provider
+
+Kilo Code requires an API key from an AI model provider to function. 
+
+We recommend these options for accessing the powerful **Claude 4 Sonnet** model:
+
+- **Kilo Code API provider (Recommended):** Provides access to all of the models available through OpenRouter with competitive pricing and free credits to get started. [View pricing](https://kilocode.ai/pricing)
+- **OpenRouter:** Provides access to multiple AI models through a single API key. [View pricing](https://openrouter.ai/models?order=pricing-low-to-high).
+- **Anthropic:** Direct access to Claude models. Requires API access approval and may have [rate limits depending on your tier](https://docs.anthropic.com/en/api/rate-limits#requirements-to-advance-tier). See [Anthropic's pricing page](https://www.anthropic.com/pricing#anthropic-api) for details.
+
+## Using the Kilo Code Provider
+By default when you install Kilo Code the extension, you'll be prompted to sign in or create an account in the [Kilo Code Provider](/providers/kilocode).
+
+That will walk you through the account setup and _automatically_ configure Kilo Code properly to get you started. If you'd rather use another provider, you'll need to manually get your API key as described below.
+
+## Using another API Provider
+
+### Getting Your API Key
+
+#### Option 1: LLM Routers
+
+LLM routers let you access multiple AI models with one API key, simplifying cost management and switching between models. They often offer [competitive pricing](https://openrouter.ai/models?order=pricing-low-to-high) compared to direct providers.
+
+##### OpenRouter
+
+1. Go to [openrouter.ai](https://openrouter.ai/)
+2. Sign in with your Google or GitHub account
+3. Navigate to the [API keys page](https://openrouter.ai/keys) and create a new key
+4. Copy your API key - you'll need this for Kilo Code setup
+
+<img src="/docs/img/connecting-api-provider/connecting-api-provider-4.png" alt="OpenRouter API keys page" width="600" />
+
+*OpenRouter dashboard with "Create key" button. Name your key and copy it after creation.*
+
+##### Requesty
+
+1. Go to [requesty.ai](https://requesty.ai/)
+2. Sign in with your Google account or email
+3. Navigate to the [API management page](https://app.requesty.ai/manage-api) and create a new key
+4. **Important:** Copy your API key immediately as it won't be displayed again
+
+<img src="/docs/img/connecting-api-provider/connecting-api-provider-7.png" alt="Requesty API management page" width="600" />
+
+*Requesty API management page with "Create API Key" button. Copy your key immediately - it's shown only once.*
+
+#### Option 2: Direct Providers
+
+For direct access to specific models from their original providers, with full access to their features and capabilities:
+
+##### Anthropic
+
+1. Go to [console.anthropic.com](https://console.anthropic.com/)
+2. Sign up for an account or log in
+3. Navigate to the [API keys section](https://console.anthropic.com/settings/keys) and create a new key
+4. **Important:** Copy your API key immediately as it won't be displayed again
+
+<img src="/docs/img/connecting-api-provider/connecting-api-provider-5.png" alt="Anthropic console API Keys section" width="600" />
+
+*Anthropic console API Keys section with "Create key" button. Name your key, set expiration, and copy it immediately.*
+
+##### OpenAI
+
+1. Go to [platform.openai.com](https://platform.openai.com/)
+2. Sign up for an account or log in
+3. Navigate to the [API keys section](https://platform.openai.com/api-keys) and create a new key
+4. **Important:** Copy your API key immediately as it won't be displayed again
+
+<img src="/docs/img/connecting-api-provider/connecting-api-provider-6.png" alt="OpenAI API keys page" width="600" />
+
+*OpenAI platform with "Create new secret key" button. Name your key and copy it immediately after creation.*
+
+### Configuring the Provider in Kilo Code
+
+Once you have your API key:
+
+1. Open the Kilo Code sidebar by clicking the Kilo Code icon (<img src="/docs/img/kilo-v1.svg" width="12" />) in the VS Code Side Bar
+2. In the welcome screen, select your API provider from the dropdown
+3. Paste your API key into the appropriate field
+4. Select your model:
+   - For **OpenRouter**: select `anthropic/claude-3.7-sonnet` ([model details](https://openrouter.ai/anthropic/claude-3.7-sonnet))
+   - For **Anthropic**: select `claude-3-7-sonnet-20250219` ([model details](https://www.anthropic.com/pricing#anthropic-api))
+5. Click "Let's go!" to save your settings and start using Kilo Code

apps/kilocode-docs/docs/getting-started/installing.md

@@ -0,0 +1,108 @@
+---
+sidebar_label: Installing Kilo Code
+---
+
+# Installing Kilo Code
+
+Kilo Code is a VS Code extension that brings AI-powered coding assistance directly to your editor. Install using one of these methods:
+- [**VS Code Marketplace (Recommended)**](#vs-code-marketplace) - fastest method for standard VS Code users
+- [**Cursor Marketplace**](#cursor-marketplace) - recommended way for Cursor users
+- [**Open VSX Registry**](#open-vsx-registry) - for VS Code-compatible editors like VSCodium or Windsurf
+- [**Manually install the .vsix file**](#manual-installation-from-vsix) - direct installation from the GitHub Release
+
+## VS Code Marketplace
+
+:::tip
+
+If you already have VS Code installed: [Click here to install Kilo Code](vscode:extension/kilocode.Kilo-Code)
+
+:::
+
+alternatively, you can:
+
+1. Open VS Code
+2. Access Extensions: Click the Extensions icon in the Side Bar or press `Ctrl+Shift+X` (Windows/Linux) or `Cmd+Shift+X` (macOS)
+3. Search for "Kilo Code"
+4. Select "Kilo Code" by Kilo Code and click **Install**
+5. Reload VS Code if prompted
+
+After installation, find the Kilo Code icon (<img src="/docs/img/kilo-v1.svg" width="12" />) in the Side Bar to open the Kilo Code panel.
+
+<img src="/docs/img/installing/installing.png" alt="VS Code marketplace with Kilo Code extension ready to install" width="400" />
+*VS Code marketplace with Kilo Code extension ready to install*
+
+## Cursor Marketplace
+
+:::tip
+
+If you already have Cursor installed: [Click here to install Kilo Code](cursor:extension/kilocode.Kilo-Code)
+
+:::
+
+alternatively, you can:
+
+1. Open Cursor
+2. Access Extensions: Click the Extensions icon in the Side Bar or press `Ctrl+Shift+X` (Windows/Linux) or `Cmd+Shift+X` (macOS)
+3. Search for "Kilo Code"
+4. Select "Kilo Code" by Kilo Code and click **Install**
+5. Reload Cursor if prompted
+
+After installation, find the Kilo Code icon (<img src="/docs/img/kilo-v1.svg" width="12" />) in the Side Bar to open the Kilo Code panel.
+
+
+
+## Open VSX Registry
+
+[Open VSX Registry](https://open-vsx.org/) is an open-source alternative to the VS Code Marketplace for VS Code-compatible editors that cannot access the official marketplace due to licensing restrictions.
+
+For VS Code-compatible editors like VSCodium, Gitpod, Eclipse Theia, and Windsurf, you can browse and install directly from the [Kilo Code page on Open VSX Registry](https://open-vsx.org/extension/kilocode/Kilo-Code).
+
+1. Open your editor
+2. Access the Extensions view (Side Bar icon or `Ctrl+Shift+X` / `Cmd+Shift+X`)
+3. Your editor should be pre-configured to use Open VSX Registry
+4. Search for "Kilo Code"
+5. Select "Kilo Code" and click **Install**
+6. Reload the editor if prompted
+
+:::note
+If your editor isn't automatically configured for Open VSX Registry, you may need to set it as your extension marketplace in settings. Consult your specific editor's documentation for instructions.
+:::
+
+## Manual Installation from VSIX
+
+If you prefer to download and install the VSIX file directly:
+
+1. **Download the VSIX file:**
+   * Find official releases on the [Kilo Code GitHub Releases page](https://github.com/Kilo-Org/kilocode/releases)
+   * Download the `.vsix` file from the [latest release](https://github.com/Kilo-Org/kilocode/releases/latest)
+
+2. **Install in VS Code:**
+   * Open VS Code
+   * Access Extensions view
+   * Click the "..." menu in the Extensions view
+   * Select "Install from VSIX..."
+   * Browse to and select your downloaded `.vsix` file
+
+<img src="/docs/img/installing/installing-2.png" alt="VS Code's Install from VSIX dialog" width="400" />
+*Installing Kilo Code using VS Code's "Install from VSIX" dialog*
+
+## Troubleshooting
+
+**Extension Not Visible**
+* Restart VS Code
+* Verify Kilo Code is listed and enabled in Extensions
+* Try disabling and re-enabling the extension in Extensions
+* Check Output panel for errors (View → Output, select "Kilo Code")
+
+**Installation Problems**
+* Ensure stable internet connection
+* Verify VS Code version 1.84.0 or later
+* If VS Code Marketplace is inaccessible, try the Open VSX Registry method
+
+## Getting Support
+
+If you encounter issues not covered here:
+
+* Join our [Discord community](https://kilocode.ai/discord) for real-time support
+* Submit issues on [GitHub](https://github.com/Kilo-Org/kilocode/issues)
+* Visit our [Reddit community](https://www.reddit.com/r/KiloCode)

apps/kilocode-docs/docs/getting-started/setting-up.mdx

@@ -0,0 +1,48 @@
+---
+sidebar_label: Getting Set up
+---
+
+import { DISCORD_URL } from "@site/src/constants.ts";
+import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
+
+export const FreeTierAmount = () => {
+  const { siteConfig } = useDocusaurusContext();
+  return siteConfig.customFields.freeTierAmount;
+};
+
+# Setting up Kilo Code
+
+When you sign up for Kilo Code, you'll receive **free credits** to help you get started. To claim your credits:
+
+1. **Sign up:** Complete the registration process to receive $5 in credits immediately after verification (we might require a hold to verify identity)
+2. **First top-up:** Add funds to your account (min $5) and get $20 bonus credits
+3. **Start Coding:** Enjoy your $25 in total free credits
+
+:::note About the temporary hold
+The $0.50 hold is for identity verification only:
+
+- **Not a charge** - This is a temporary authorization that will not be charged
+- **Instant release** - Kilo Code releases the hold immediately after verification
+- **Bank processing** - While we release instantly, it may take a few business days for funds to return (varies by bank)
+  :::
+
+## Registration process
+
+Kilo Code provides a simple registration process that gives you access to the latest frontier coding models with your Kilo Code login.
+
+1. Click on "Try Kilo Code for Free" in the extension
+1. Sign in with your Google account to kilocode.ai
+1. kilocode.ai will prompt you to open Visual Studio Code
+   - When using an IDE in a web browser, you will be asked to copy the API key manually instead
+1. Once you allow it to Open VS Code, you must also allow VS Code to open the authorization URL
+
+<img
+  src="/docs/img/setting-up/signupflow.gif"
+  alt="Sign up and registration flow with Kilo Code"
+/>
+
+That's it - you're all set! Now you can start with [your first task](/getting-started/your-first-task)
+
+:::tip Need Help?
+If you have any questions about pricing or tokens, please reach out to our [support team](mailto:[email protected]) or ask in our <a href={DISCORD_URL} target='_blank'>Discord community</a>.
+:::

apps/kilocode-docs/docs/getting-started/your-first-task.md

@@ -0,0 +1,75 @@
+---
+sidebar_label: Your First Task
+---
+
+# Starting Your First Task with Kilo Code
+
+This quick tour shows how Kilo Code handles a simple request from start to finish.
+
+After you [set up Kilo Code](/getting-started/setting-up), follow these steps:
+
+## Step 1: Open the Kilo Code Panel
+
+Click the Kilo Code icon (<img src="/docs/img/kilo-v1.svg" width="12" />) in the VS Code Primary Side Bar (vertical bar on the side of the window) to open the chat interface. If you don't see the icon, verify the extension is [installed](/getting-started/installing) and enabled.
+
+<img src="/docs/img/your-first-task/your-first-task.png" alt="Kilo Code icon in VS Code Primary Side Bar" width="800" />
+
+*The Kilo Code icon in the Primary Side Bar opens the chat interface.*
+
+## Step 2: Type Your Task
+
+Type a clear, concise description of what you want Kilo Code to do in the chat box at the bottom of the panel. Examples of effective tasks:
+
+* "Create a file named `hello.txt` containing 'Hello, world!'."
+* "Write a Python function that adds two numbers."
+* "Create an HTML file for a simple website with the title 'Kilo test'"
+
+No special commands or syntax needed—just use plain English.
+
+<img src="/docs/img/your-first-task/your-first-task-6.png" alt="Typing a task in the Kilo Code chat interface" width="500" />
+*Enter your task in natural language - no special syntax required.*
+
+## Step 3: Send Your Task
+
+Press Enter or click the Send icon (<Codicon name="send" />) to the right of the input box.
+
+## Step 4: Review and Approve Actions
+
+Kilo Code analyzes your request and proposes specific actions. These may include:
+
+* **Reading files:** Shows file contents it needs to access
+* **Writing to files:** Displays a diff with proposed changes (added lines in green, removed in red)
+* **Executing commands:** Shows the exact command to run in your terminal
+* **Using the Browser:** Outlines browser actions (click, type, etc.)
+* **Asking questions:** Requests clarification when needed to proceed
+
+<img src="/docs/img/your-first-task/your-first-task-7.png" alt="Reviewing a proposed file creation action" width="400" />
+*Kilo Code shows exactly what action it wants to perform and waits for your approval.*
+
+* In **Code** mode, writing capabilities are on by default.
+* In **Architect** and **Ask** modes, Kilo Code won't write code.
+
+:::tip
+
+The level of autonomy is configurable, allowing you to make the agent more or less autonomous. 
+
+You can learn more about [using modes](/basic-usage/using-modes) and [auto-approving actions](/features/auto-approving-actions).
+
+:::
+
+## Step 5: Iterate
+
+Kilo Code works iteratively. After each action, it waits for your feedback before proposing the next step. Continue this review-approve cycle until your task is complete.
+
+<img src="/docs/img/your-first-task/your-first-task-8.png" alt="Final result of a completed task showing the iteration process" width="500" />
+*After completing the task, Kilo Code shows the final result and awaits your next instruction.*
+
+## Conclusion
+
+You've completed your first task. Along the way you learned:
+
+* How to interact with Kilo Code using natural language
+* Why approval keeps you in control
+* How iteration lets the AI refine its work
+
+Ready for more? Explore different [modes](/basic-usage/using-modes) or try [auto-approval](/features/auto-approving-actions) to speed up repetitive tasks.

apps/kilocode-docs/docs/index.mdx

@@ -0,0 +1,86 @@
+---
+sidebar_label: Welcome
+---
+
+import { DISCORD_URL, REDDIT_URL, GITHUB_ISSUES_MAIN_URL, GITHUB_FEATURES_URL, YOUTUBE_URL } from '@site/src/constants.ts'
+import Image from '@site/src/components/Image';
+
+# Kilo Code Documentation
+
+Kilo Code **accelerates** development with AI-driven code generation and task automation. This open source extension plugs directly into VS Code.
+
+## What Can Kilo Code Do?
+
+- 🚀 **Generate Code** from natural language descriptions
+- 🔧 **Refactor & Debug** existing code
+- 📝 **Write & Update** documentation
+- 🤔 **Answer Questions** about your codebase
+- 🔄 **Automate** repetitive tasks
+- 🏗️ **Create** new files and projects
+
+## Quick Start
+
+1. [Install Kilo Code](/getting-started/installing)
+2. [Set up Kilo Code](/getting-started/setting-up)
+3. [Try Your First Task](/getting-started/your-first-task)
+
+## Features
+
+<Image src="/docs/img/kilogif.gif" alt="GIF showing some of the capabilities of Kilo Code" width="600" />
+
+### Basics
+
+Use [the chat interface](/basic-usage/the-chat-interface) to tell Kilo Code what you need. It relies on coding‑optimized AI models to complete each request.
+
+- Switch [modes](/basic-usage/using-modes) to fit the task
+- Control allowed [actions](/features/auto-approving-actions)
+- Run direct [code actions](/features/code-actions)
+
+### Using Kilo Code
+
+#### Multiple Modes
+Kilo Code adapts to your needs with specialized [modes](/basic-usage/using-modes):
+- [**Code Mode:**](/basic-usage/using-modes#code-mode-default) For general-purpose coding tasks
+- [**Architect Mode:**](/basic-usage/using-modes#architect-mode) For planning and technical leadership
+- [**Ask Mode:**](/basic-usage/using-modes#ask-mode) For answering questions and providing information
+- [**Debug Mode:**](/basic-usage/using-modes#debug-mode) For systematic problem diagnosis
+- **[Custom Modes](/features/custom-modes):** Create unlimited specialized personas for security auditing, performance optimization, documentation, or any other task
+
+#### Core Tools
+Kilo Code comes with powerful [tools](/features/tools/tool-use-overview) that can:
+- [Read](/features/tools/read-file) and [write](/features/tools/write-to-file) files in your project
+- [Execute commands](/features/tools/execute-command) in your VS Code terminal
+- [Control a web browser](/features/tools/browser-action)
+- [Ask follow-up questions](/features/tools/ask-followup-question)
+- [Search your codebase](/features/tools/search-files)
+
+See the complete [Tools Reference](/features/tools/tool-use-overview) for all available tools.
+
+### Extending Kilo Code
+- **[MCP (Model Context Protocol)](/features/mcp/overview):** Add unlimited custom tools, integrate with external APIs, connect to databases, or create specialized development tools
+- **[Local Models](/advanced-usage/local-models):** Run Kilo Code with local AI models for offline use or enhanced privacy
+
+### Customizing Kilo Code
+Make Kilo Code work your way with:
+- [Settings Management](/features/settings-management) for configuring your experience
+- [Custom Modes](/features/custom-modes) for specialized tasks
+- [Custom Rules](/advanced-usage/custom-rules) for project-specific rules
+- [Custom Instructions](/advanced-usage/custom-instructions) for global plugin-wide instructions
+- [API Configuration Profiles](/features/api-configuration-profiles) for different model providers
+- [Auto-Approval Settings](/features/auto-approving-actions) for faster workflows
+
+## Resources
+
+### Documentation
+- [Using Kilo Code](/basic-usage/the-chat-interface) - Learn the basics
+- [Core Concepts](/features/auto-approving-actions) - Master key features
+- [Advanced Usage](/advanced-usage/prompt-engineering) - Take your skills further
+- [Frequently Asked Questions](/faq) - Get answers to common questions
+
+### Community
+- **Discord:** <a href={DISCORD_URL} target="_blank">Join our Discord server</a> for real-time help and discussions
+- **Reddit:** <a href={REDDIT_URL} target="_blank">Visit our subreddit</a> to share experiences and tips
+- **YouTube:** <a href={YOUTUBE_URL} target="_blank">Check out our YouTube</a> to learn hands on skills when using Kilo Code
+- **GitHub:** Report <a href={GITHUB_ISSUES_MAIN_URL} target="_blank">issues</a> or request <a href={GITHUB_FEATURES_URL} target="_blank">features</a>
+
+Ready to get started? Click the **Next** button below to begin your journey with Kilo Code!

apps/kilocode-docs/docs/providers/anthropic.md

@@ -0,0 +1,44 @@
+---
+sidebar_label: Anthropic
+---
+
+# Using Anthropic With Kilo Code
+
+Anthropic is an AI safety and research company that builds reliable, interpretable, and steerable AI systems.  Their Claude models are known for their strong reasoning abilities, helpfulness, and honesty.
+
+**Website:** [https://www.anthropic.com/](https://www.anthropic.com/)
+
+## Getting an API Key
+
+1.  **Sign Up/Sign In:** Go to the [Anthropic Console](https://console.anthropic.com/). Create an account or sign in.
+2.  **Navigate to API Keys:**  Go to the [API keys](https://console.anthropic.com/settings/keys) section.
+3.  **Create a Key:** Click "Create Key". Give your key a descriptive name (e.g., "Kilo Code").
+4.  **Copy the Key:**  **Important:** Copy the API key *immediately*.  You will not be able to see it again.  Store it securely.
+
+## Supported Models
+
+Kilo Code supports the following Anthropic Claude models:
+
+*   `claude-3-7-sonnet-20250219` (Recommended)
+*   `claude-3-7-sonnet-20250219:thinking` (Extended Thinking variant)
+*   `claude-3-5-sonnet-20241022`
+*   `claude-3-5-haiku-20241022`
+*   `claude-3-opus-20240229`
+*   `claude-3-haiku-20240307`
+
+See [Anthropic's Model Documentation](https://docs.anthropic.com/en/docs/about-claude/models) for more details on each model's capabilities.
+
+## Configuration in Kilo Code
+
+1.  **Open Kilo Code Settings:** Click the gear icon (<Codicon name="gear" />) in the Kilo Code panel.
+2.  **Select Provider:** Choose "Anthropic" from the "API Provider" dropdown.
+3.  **Enter API Key:** Paste your Anthropic API key into the "Anthropic API Key" field.
+4.  **Select Model:** Choose your desired Claude model from the "Model" dropdown.
+5.  **(Optional) Custom Base URL:** If you need to use a custom base URL for the Anthropic API, check "Use custom base URL" and enter the URL. Most people won't need to adjust this.
+
+## Tips and Notes
+
+*   **Prompt Caching:** Claude 3 models support [prompt caching](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching), which can significantly reduce costs and latency for repeated prompts.
+*   **Context Window:** Claude models have large context windows (200,000 tokens), allowing you to include a significant amount of code and context in your prompts.
+*   **Pricing:** Refer to the [Anthropic Pricing](https://www.anthropic.com/pricing) page for the latest pricing information.
+*   **Rate Limits:** Anthropic has strict rate limits based on [usage tiers](https://docs.anthropic.com/en/api/rate-limits#requirements-to-advance-tier). If you're repeatedly hitting rate limits, consider contacting Anthropic sales or accessing Claude through a different provider like [OpenRouter](/providers/openrouter) or [Requesty](/providers/requesty).

apps/kilocode-docs/docs/providers/bedrock.md

@@ -0,0 +1,91 @@
+---
+sidebar_label: AWS Bedrock
+---
+
+# Using AWS Bedrock With Kilo Code
+
+Kilo Code supports accessing models through Amazon Bedrock, a fully managed service that makes a selection of high-performing foundation models (FMs) from leading AI companies available via a single API.
+
+**Website:** [https://aws.amazon.com/bedrock/](https://aws.amazon.com/bedrock/)
+
+## Prerequisites
+
+*   **AWS Account:** You need an active AWS account.
+*   **Bedrock Access:** You must request and be granted access to Amazon Bedrock.  See the [AWS Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/getting-started.html) for details on requesting access.
+*   **Model Access:** Within Bedrock, you need to request access to the specific models you want to use (e.g., Anthropic Claude).
+*   **Install AWS CLI:** Use AWS CLI to configure your account for authentication
+    ```bash
+     aws configure
+    ```
+
+## Getting Credentials
+
+You have two main options for configuring AWS credentials:
+
+1.  **AWS Access Keys (Recommended for Development):**
+    *   Create an IAM user with the necessary permissions (at least `bedrock:InvokeModel`).
+    *   Generate an access key ID and secret access key for that user.
+    *   *(Optional)* Create a session token if required by your IAM configuration.
+2.  **AWS Profile:**
+    *   Configure an AWS profile using the AWS CLI or by manually editing your AWS credentials file.  See the [AWS CLI documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html) for details.
+
+## Supported Models
+
+Kilo Code supports the following models through Bedrock (based on source code):
+
+*   **Amazon:**
+    *   `amazon.nova-pro-v1:0`
+    *   `amazon.nova-pro-latency-optimized-v1:0`
+    *   `amazon.nova-lite-v1:0`
+    *   `amazon.nova-micro-v1:0`
+    *   `amazon.titan-text-lite-v1:0`
+    *   `amazon.titan-text-express-v1:0`
+    *   `amazon.titan-text-embeddings-v1:0`
+    *   `amazon.titan-text-embeddings-v2:0`
+*   **Anthropic:**
+    *   `anthropic.claude-3-7-sonnet-20250219-v1:0`
+    *   `anthropic.claude-3-5-sonnet-20241022-v2:0`
+    *   `anthropic.claude-3-5-haiku-20241022-v1:0`
+    *   `anthropic.claude-3-5-sonnet-20240620-v1:0`
+    *   `anthropic.claude-3-opus-20240229-v1:0`
+    *   `anthropic.claude-3-sonnet-20240229-v1:0`
+    *   `anthropic.claude-3-haiku-20240307-v1:0`
+    *   `anthropic.claude-2-1-v1:0`
+    *   `anthropic.claude-2-0-v1:0`
+    *   `anthropic.claude-instant-v1:0`
+*   **DeepSeek:**
+    *   `deepseek.r1-v1:0`
+*   **Meta:**
+    *   `meta.llama3-3-70b-instruct-v1:0`
+    *   `meta.llama3-2-90b-instruct-v1:0`
+    *   `meta.llama3-2-11b-instruct-v1:0`
+    *   `meta.llama3-2-3b-instruct-v1:0`
+    *   `meta.llama3-2-1b-instruct-v1:0`
+    *   `meta.llama3-1-405b-instruct-v1:0`
+    *   `meta.llama3-1-70b-instruct-v1:0`
+    *   `meta.llama3-1-70b-instruct-latency-optimized-v1:0`
+    *   `meta.llama3-1-8b-instruct-v1:0`
+    *   `meta.llama3-70b-instruct-v1:0`
+    *   `meta.llama3-8b-instruct-v1:0`
+
+Refer to the [Amazon Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html) for the most up-to-date list of available models and their IDs. Make sure to use the *model ID* when configuring Kilo Code, not the model name.
+
+## Configuration in Kilo Code
+
+1.  **Open Kilo Code Settings:** Click the gear icon (<Codicon name="gear" />) in the Kilo Code panel.
+2.  **Select Provider:** Choose "Bedrock" from the "API Provider" dropdown.
+3.  **Select Authentication Method:**
+    *   **AWS Credentials:**
+        *   Enter your "AWS Access Key" and "AWS Secret Key."
+        *   (Optional) Enter your "AWS Session Token" if you're using temporary credentials.
+    *   **AWS Profile:**
+        *   Enter your "AWS Profile" name (e.g., "default").
+4.  **Select Region:** Choose the AWS region where your Bedrock service is available (e.g., "us-east-1").
+5.  **(Optional) Cross-Region Inference:** Check "Use cross-region inference" if you want to access models in a region different from your configured AWS region.
+6.  **Select Model:** Choose your desired model from the "Model" dropdown.
+
+## Tips and Notes
+
+*   **Permissions:**  Ensure your IAM user or role has the necessary permissions to invoke Bedrock models.  The `bedrock:InvokeModel` permission is required.
+*   **Pricing:**  Refer to the [Amazon Bedrock pricing](https://aws.amazon.com/bedrock/pricing/) page for details on model costs.
+*   **Cross-Region Inference:**  Using cross-region inference may result in higher latency.

apps/kilocode-docs/docs/providers/chutes-ai.md

@@ -0,0 +1,32 @@
+---
+sidebar_label: Chutes AI
+---
+
+# Using Chutes AI With Kilo Code
+
+Chutes.ai offers free API access to several large language models (LLMs), allowing developers to integrate and experiment with these models without immediate financial commitment. They provide access to a curated set of open-source and proprietary language models, often with a focus on specific capabilities or regional language support.
+
+**Website:** [https://chutes.ai/](https://chutes.ai/)
+
+## Getting an API Key
+
+To use Chutes AI with Kilo Code, obtain an API key from the [Chutes AI platform](https://chutes.ai/). After signing up or logging in, you should find an option to generate or retrieve your API key within your account dashboard or settings.
+
+## Supported Models
+
+Kilo Code will attempt to fetch the list of available models from the Chutes AI API. The specific models available will depend on Chutes AI's current offerings.
+
+Always refer to the official Chutes AI documentation or your dashboard for the most up-to-date list of supported models.
+
+## Configuration in Kilo Code
+
+1.  **Open Kilo Code Settings:** Click the gear icon (<Codicon name="gear" />) in the Kilo Code panel.
+2.  **Select Provider:** Choose "Chutes AI" from the "API Provider" dropdown.
+3.  **Enter API Key:** Paste your Chutes AI API key into the "Chutes AI API Key" field.
+4.  **Select Model:** Choose your desired model from the "Model" dropdown.
+
+## Tips and Notes
+
+*   **Free Access:** Chutes AI provides free API access, making it an excellent option for experimentation and development without immediate costs.
+*   **Model Variety:** The platform offers access to both open-source and proprietary models, giving you flexibility in choosing the right model for your needs.
+*   **Rate Limits:** As with any free service, be aware of potential rate limits or usage restrictions that may apply to your API key.

apps/kilocode-docs/docs/providers/claude-code.md

@@ -0,0 +1,59 @@
+---
+sidebar_label: Claude Code
+---
+
+# Using Claude Code With Kilo Code
+
+Claude Code is Anthropic's official CLI that provides direct access to Claude models from your terminal. Using Claude Code with Kilo Code lets you leverage your existing CLI setup without needing separate API keys.
+
+**Website:** [https://docs.anthropic.com/en/docs/claude-code/setup](https://docs.anthropic.com/en/docs/claude-code/setup)
+
+## Installing and Setting Up Claude Code
+
+1. **Install Claude Code:** Follow the installation instructions at [Anthropic's Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/setup).
+2. **Authenticate:** Run `claude` in your terminal. Claude Code offers multiple authentication options including the Anthropic Console (default), Claude App with Pro/Max plans, and enterprise platforms like Amazon Bedrock or Google Vertex AI. See [Anthropic's authentication documentation](https://docs.anthropic.com/en/docs/claude-code/setup) for complete details.
+3. **Verify Installation:** Test that everything works by running `claude --version` in your terminal.
+
+:::warning Environment Variable Usage
+The `claude` command-line tool, like other Anthropic SDKs, can use the `ANTHROPIC_API_KEY` environment variable for authentication. This is a common method for authorizing CLI tools in non-interactive environments.
+
+If this environment variable is set on your system, the `claude` tool may use it for authentication instead of the interactive `/login` method. When Kilo Code executes the tool, it will accurately reflect that an API key is being used, as this is the underlying behavior of the `claude` CLI itself.
+:::
+
+**Website:** [https://docs.anthropic.com/en/docs/claude-code/setup](https://docs.anthropic.com/en/docs/claude-code/setup)
+
+## Supported Models
+
+Kilo Code supports the following Claude models through Claude Code:
+
+- **Claude Opus 4.1** (Most capable)
+- **Claude Opus 4**
+- **Claude Sonnet 4** (Latest, recommended)
+- **Claude 3.7 Sonnet**
+- **Claude 3.5 Sonnet**
+- **Claude 3.5 Haiku** (Fast responses)
+
+The specific models available depend on your Claude subscription and plan. See [Anthropic's Model Documentation](https://docs.anthropic.com/en/docs/about-claude/models) for more details on each model's capabilities.
+
+## Configuration in Kilo Code
+
+1. **Open Kilo Code Settings:** Click the gear icon (<Codicon name="gear" />) in the Kilo Code panel.
+2. **Select Provider:** Choose "Claude Code" from the "API Provider" dropdown.
+3. **Select Model:** Choose your desired Claude model from the "Model" dropdown.
+4. **(Optional) Custom CLI Path:** If you installed Claude Code to a location other than the default `claude` command, enter the full path to your Claude executable in the "Claude Code Path" field. Most users won't need to change this.
+
+## Tips and Notes
+
+- **No API Keys Required:** Claude Code uses your existing CLI authentication, so you don't need to manage separate API keys.
+- **Cost Transparency:** Usage costs are reported directly by the Claude CLI, giving you clear visibility into your spending.
+- **Advanced Reasoning:** Full support for Claude's thinking modes and reasoning capabilities when available.
+- **Context Windows:** Claude models have large context windows, allowing you to include significant amounts of code and context in your prompts.
+- **Enhance Prompt Feature:** Full compatibility with Kilo Code's Enhance Prompt feature, allowing you to automatically improve and refine your prompts before sending them to Claude.
+- **Custom Paths:** If you installed Claude Code in a non-standard location, you can specify the full path in the settings. Examples:
+  - Windows: `C:\tools\claude\claude.exe`
+  - macOS/Linux: `/usr/local/bin/claude` or `~/bin/claude`
+
+## Troubleshooting
+
+- **"Claude Code process exited with error":** Verify Claude Code is installed (`claude --version`) and authenticated (`claude auth login`). Make sure your subscription includes the selected model.
+- **Custom path not working:** Use the full absolute path to the Claude executable and verify the file exists and is executable. On Windows, include the `.exe` extension.

apps/kilocode-docs/docs/providers/deepseek.md

@@ -0,0 +1,33 @@
+---
+sidebar_label: DeepSeek
+---
+
+# Using DeepSeek With Kilo Code
+
+Kilo Code supports accessing models through the DeepSeek API, including `deepseek-chat` and `deepseek-reasoner`.
+
+**Website:** [https://platform.deepseek.com/](https://platform.deepseek.com/)
+
+## Getting an API Key
+
+1.  **Sign Up/Sign In:** Go to the [DeepSeek Platform](https://platform.deepseek.com/). Create an account or sign in.
+2.  **Navigate to API Keys:** Find your API keys in the [API keys](https://platform.deepseek.com/api_keys) section of the platform.
+3.  **Create a Key:** Click "Create new API key".  Give your key a descriptive name (e.g., "Kilo Code").
+4.  **Copy the Key:**  **Important:** Copy the API key *immediately*.  You will not be able to see it again.  Store it securely.
+
+## Supported Models
+
+Kilo Code supports the following DeepSeek models:
+
+*   `deepseek-chat` (Recommended for coding tasks)
+*	  `deepseek-reasoner` (Recommended for reasoning tasks)
+
+## Configuration in Kilo Code
+
+1.  **Open Kilo Code Settings:** Click the gear icon (<Codicon name="gear" />) in the Kilo Code panel.
+2.  **Select Provider:** Choose "DeepSeek" from the "API Provider" dropdown.
+3.  **Enter API Key:** Paste your DeepSeek API key into the "DeepSeek API Key" field.
+4.  **Select Model:** Choose your desired model from the "Model" dropdown.
+
+## Tips and Notes
+*   **Pricing:** Refer to the [DeepSeek Pricing](https://api-docs.deepseek.com/quick_start/pricing/) page for details on model costs.

apps/kilocode-docs/docs/providers/fireworks.md

@@ -0,0 +1,47 @@
+---
+sidebar_label: Fireworks AI
+---
+
+# Using Fireworks AI With Kilo Code
+
+Fireworks AI is a high-performance platform for running AI models that offers fast access to a wide range of open-source and proprietary language models. Built for speed and reliability, Fireworks AI provides both serverless and dedicated deployment options with OpenAI-compatible APIs.
+
+**Website:** [https://fireworks.ai/](https://fireworks.ai/)
+
+---
+
+## Getting an API Key
+
+1. **Sign Up/Sign In:** Go to [Fireworks AI](https://fireworks.ai/) and create an account or sign in.
+2. **Navigate to API Keys:** After logging in, go to the [API Keys page](https://app.fireworks.ai/settings/users/api-keys) in the account settings.
+3. **Create a Key:** Click "Create API key" and give your key a descriptive name (e.g., "Kilo Code").
+4. **Copy the Key:** Copy the API key *immediately* and store it securely. You will not be able to see it again.
+
+---
+
+## Supported Models
+
+Kilo Code supports the following Fireworks AI models:
+
+* `accounts/fireworks/models/kimi-k2-instruct` - Kimi K2 instruction-tuned model
+* `accounts/fireworks/models/qwen3-235b-a22b-instruct-2507` - Qwen 3 235B instruction-tuned model  
+* `accounts/fireworks/models/qwen3-coder-480b-a35b-instruct` - Qwen 3 Coder 480B for code generation
+* `accounts/fireworks/models/deepseek-r1-0528` - DeepSeek R1 reasoning model
+* `accounts/fireworks/models/deepseek-v3` - DeepSeek V3 latest generation model
+
+---
+
+## Configuration in Kilo Code
+
+1. **Open Kilo Code Settings:** Click the gear icon (<Codicon name="gear" />) in the Kilo Code panel.
+2. **Select Provider:** Choose "Fireworks AI" from the "API Provider" dropdown.
+3. **Enter API Key:** Paste your Fireworks AI API key into the "Fireworks AI API Key" field.
+4. **Select Model:** Choose your desired model from the "Model" dropdown.
+
+---
+
+## Tips and Notes
+
+* **Performance:** Fireworks AI is optimized for speed and offers excellent performance for both chat and completion tasks.
+* **Pricing:** Refer to the [Fireworks AI Pricing](https://fireworks.ai/pricing) page for current pricing information.
+* **Rate Limits:** Fireworks AI has usage-based rate limits. Monitor your usage in the dashboard and consider upgrading your plan if needed.

apps/kilocode-docs/docs/providers/gemini.md

@@ -0,0 +1,54 @@
+---
+sidebar_label: Google Gemini
+---
+
+# Using Google Gemini With Kilo Code
+
+Kilo Code supports Google's Gemini family of models through the Google AI Gemini API.
+
+**Website:** [https://ai.google.dev/](https://ai.google.dev/)
+
+## Getting an API Key
+
+1.  **Go to Google AI Studio:** Navigate to [https://ai.google.dev/](https://ai.google.dev/).
+2.  **Sign In:** Sign in with your Google account.
+3.  **Create API Key:** Click on "Create API key" in the left-hand menu.
+4.  **Copy API Key:** Copy the generated API key.
+
+## Supported Models
+
+Kilo Code supports the following Gemini models:
+
+### Chat Models
+
+* `gemini-2.5-pro-exp-03-25`
+* `gemini-2.0-flash-001`
+* `gemini-2.0-flash-lite-preview-02-05`
+* `gemini-2.0-pro-exp-02-05`
+* `gemini-2.0-flash-thinking-exp-01-21`
+* `gemini-2.0-flash-thinking-exp-1219`
+* `gemini-2.0-flash-exp`
+* `gemini-1.5-flash-002`
+* `gemini-1.5-flash-exp-0827`
+* `gemini-1.5-flash-8b-exp-0827`
+* `gemini-1.5-pro-002`
+* `gemini-1.5-pro-exp-0827`
+* `gemini-exp-1206`
+
+### Embedding Models
+
+* `gemini-embedding-001` - Optimized for codebase indexing and semantic search
+
+Refer to the [Gemini documentation](https://ai.google.dev/models/gemini) for more details on each model.
+
+## Configuration in Kilo Code
+
+1.  **Open Kilo Code Settings:** Click the gear icon (<Codicon name="gear" />) in the Kilo Code panel.
+2.  **Select Provider:** Choose "Google Gemini" from the "API Provider" dropdown.
+3.  **Enter API Key:** Paste your Gemini API key into the "Gemini API Key" field.
+4.  **Select Model:** Choose your desired Gemini model from the "Model" dropdown.
+
+## Tips and Notes
+
+*   **Pricing:**  Gemini API usage is priced based on input and output tokens. Refer to the [Gemini pricing page](https://ai.google.dev/pricing) for detailed information.
+*   **Codebase Indexing:** The `gemini-embedding-001` model is specifically supported for [codebase indexing](/features/codebase-indexing), providing high-quality embeddings for semantic code search.

apps/kilocode-docs/docs/providers/glama.md

@@ -0,0 +1,37 @@
+---
+sidebar_label: Glama
+---
+
+# Using Glama With Kilo Code
+
+Glama provides access to a variety of language models through a unified API, including models from Anthropic, OpenAI, and others.  It offers features like prompt caching and cost tracking.
+
+**Website:** [https://glama.ai/](https://glama.ai/)
+
+## Getting an API Key
+
+1.  **Sign Up/Sign In:** Go to the [Glama sign-up page](https://glama.ai/sign-up). Sign up using your Google account or name/email/password.
+2.  **Get API Key:** After signing up, navigate to the [API Keys](https://glama.ai/settings/gateway/api-keys) page to get an API key.
+3.  **Copy the Key:** Copy the displayed API key.
+
+## Supported Models
+
+Kilo Code will automatically try to fetch a list of available models from the Glama API.  Some models that are commonly available through Glama include:
+
+*  **Anthropic Claude models:**  (e.g., `anthropic/claude-3-5-sonnet`)  These are generally recommended for best performance with Kilo Code.
+*  **OpenAI models:** (e.g., `openai/o3-mini-high`)
+*  **Other providers and open-source models**
+    
+Refer to the [Glama documentation](https://glama.ai/models) for the most up-to-date list of supported models.
+
+## Configuration in Kilo Code
+
+1.  **Open Kilo Code Settings:** Click the gear icon (<Codicon name="gear" />) in the Kilo Code panel.
+2.  **Select Provider:** Choose "Glama" from the "API Provider" dropdown.
+3.  **Enter API Key:** Paste your Glama API key into the "Glama API Key" field.
+4.  **Select Model:** Choose your desired model from the "Model" dropdown.
+
+## Tips and Notes
+
+* **Pricing:** Glama operates on a pay-per-use basis.  Pricing varies depending on the model you choose.
+* **Prompt Caching:** Glama supports prompt caching, which can significantly reduce costs and improve performance for repeated prompts.

apps/kilocode-docs/docs/providers/groq.md

@@ -0,0 +1,92 @@
+---
+sidebar_label: Groq
+---
+
+# Using Groq With Kilo Code
+
+Groq provides ultra-fast inference for various AI models through their high-performance infrastructure. Kilo Code supports accessing models through the Groq API.
+
+**Website:** [https://groq.com/](https://groq.com/)
+
+## Getting an API Key
+
+To use Groq with Kilo Code, you'll need an API key from the [GroqCloud Console](https://console.groq.com/). After signing up or logging in, navigate to the API Keys section of your dashboard to create and copy your key.
+
+## Supported Models
+
+Kilo Code will attempt to fetch the list of available models from the Groq API. Common models available via Groq include:
+
+*   `llama3-8b-8192`
+*   `llama3-70b-8192`
+*   `mixtral-8x7b-32768`
+*   `gemma-7b-it`
+*   `moonshotai/kimi-k2-instruct` (Kimi K2 model)
+
+**Note:** Model availability and specifications may change. Refer to the [Groq Documentation](https://console.groq.com/docs/models) for the most up-to-date list of supported models and their capabilities.
+
+## Configuration in Kilo Code
+
+1.  **Open Kilo Code Settings:** Click the gear icon (<Codicon name="gear" />) in the Kilo Code panel.
+2.  **Select Provider:** Choose "Groq" from the "API Provider" dropdown.
+3.  **Enter API Key:** Paste your Groq API key into the "Groq API Key" field.
+4.  **Select Model:** Choose your desired model from the "Model" dropdown.
+
+## Tips and Notes
+
+*   **High-Speed Inference:** Groq's LPUs provide exceptionally fast response times, making it ideal for interactive development workflows.
+*   **Token Limits:** Some models have specific `max_tokens` limits that are automatically handled by Kilo Code (e.g., the `moonshotai/kimi-k2-instruct` model).
+*   **Cost Efficiency:** Groq often provides competitive pricing for high-speed inference compared to other providers.
+*   **Model Selection:** Choose models based on your specific needs - larger models like `llama3-70b-8192` for complex reasoning tasks, or smaller models like `llama3-8b-8192` for faster, simpler operations.
+
+## Supported Models
+
+Kilo Code supports the following models through Groq:
+
+| Model ID | Provider | Context Window | Notes |
+|----------|----------|----------------|-------|
+| `moonshotai/kimi-k2-instruct` | Moonshot AI | 128K tokens | Optimized max_tokens limit configured |
+| `llama-3.3-70b-versatile` | Meta | 128K tokens | High-performance Llama model |
+| `llama-3.1-70b-versatile` | Meta | 128K tokens | Versatile reasoning capabilities |
+| `llama-3.1-8b-instant` | Meta | 128K tokens | Fast inference for quick tasks |
+| `mixtral-8x7b-32768` | Mistral AI | 32K tokens | Mixture of experts architecture |
+
+**Note:** Model availability may change. Refer to the [Groq documentation](https://console.groq.com/docs/models) for the latest model list and specifications.
+
+## Configuration in Kilo Code
+
+1. **Open Kilo Code Settings:** Click the gear icon (<Codicon name="gear" />) in the Kilo Code panel.
+2. **Select Provider:** Choose "Groq" from the "API Provider" dropdown.
+3. **Enter API Key:** Paste your Groq API key into the "Groq API Key" field.
+4. **Select Model:** Choose your desired model from the "Model" dropdown.
+
+## Model-Specific Features
+
+### Kimi K2 Model
+
+The `moonshotai/kimi-k2-instruct` model includes optimized configuration:
+
+- **Max Tokens Limit:** Automatically configured with appropriate limits for optimal performance
+- **Context Understanding:** Excellent for complex reasoning and long-context tasks
+- **Multilingual Support:** Strong performance across multiple languages
+
+## Tips and Notes
+
+- **Ultra-Fast Inference:** Groq's hardware acceleration provides exceptionally fast response times
+- **Cost-Effective:** Competitive pricing for high-performance inference
+- **Rate Limits:** Be aware of API rate limits based on your Groq plan
+- **Model Selection:** Choose models based on your specific use case:
+  - **Kimi K2**: Best for complex reasoning and multilingual tasks
+  - **Llama 3.3 70B**: Excellent general-purpose performance
+  - **Llama 3.1 8B Instant**: Fastest responses for simple tasks
+  - **Mixtral**: Good balance of performance and efficiency
+
+## Troubleshooting
+
+- **"Invalid API Key":** Verify your API key is correct and active in the Groq Console
+- **"Model Not Available":** Check if the selected model is available in your region
+- **Rate Limit Errors:** Monitor your usage in the Groq Console and consider upgrading your plan
+- **Connection Issues:** Ensure you have a stable internet connection and Groq services are operational
+
+## Pricing
+
+Groq offers competitive pricing based on input and output tokens. Visit the [Groq pricing page](https://groq.com/pricing/) for current rates and plan options.

apps/kilocode-docs/docs/providers/human-relay.md

@@ -0,0 +1,29 @@
+# Human Relay Provider
+
+The Human Relay provider allows you to use Kilo Code with web-based AI models like ChatGPT or Claude without needing an API key. Instead, it relies on you to manually relay messages between Kilo Code and the AI's web interface.
+
+## How it Works
+
+1.  **Select Human Relay**: Choose "Human Relay" as your API provider in Kilo Code's settings. No API key is required.
+2.  **Initiate a Request**: Start a chat or task with Kilo Code as usual.
+3.  **Dialog Prompt**: A dialog box will appear in VS Code. Your message to the AI is automatically copied to your clipboard.
+4.  **Paste to Web AI**: Go to the web interface of your chosen AI (e.g., chat.openai.com, claude.ai) and paste the message from your clipboard into the chat input.
+5.  **Copy AI Response**: Once the AI responds, copy its complete response text.
+6.  **Paste Back to Kilo Code**: Return to the dialog box in VS Code, paste the AI's response into the designated field, and click "Confirm".
+7.  **Continue**: Kilo Code will process the response as if it came directly from an API.
+
+## Use Cases
+
+This provider is useful if:
+
+*   You want to use models that don't offer direct API access.
+*   You prefer not to manage API keys.
+*   You need to leverage the specific capabilities or context available only in the web UI of certain AI models.
+
+## Limitations
+
+*   **Manual Effort**: Requires constant copy-pasting between VS Code and your browser.
+*   **Slower Interaction**: The back-and-forth process is significantly slower than direct API integration.
+*   **Potential for Errors**: Manual copying and pasting can introduce errors or omissions.
+
+Choose this provider when the benefits of using a specific web AI outweigh the inconvenience of the manual relay process.

apps/kilocode-docs/docs/providers/kilocode.md

@@ -0,0 +1,60 @@
+---
+sidebar_label: Kilo Code Provider
+---
+
+# Using Kilo Code's Built-in Provider
+
+Kilo Code provides its own built-in API provider that gives you access to the latest frontier coding models through a simple registration process. No need to manage API keys from multiple providers - just sign up and start coding.
+
+**Website:** [https://kilocode.ai/](https://kilocode.ai/)
+
+## Getting Started with Free Credits
+
+When you sign up for Kilo Code, you'll receive free credits to help you get started:
+
+1. **Sign up:** Complete the registration process to receive $5 in credits immediately after verification (we might require a hold to verify identity)
+2. **First top-up:**: Add funds to your account (min $5) and get $20 bonus credits
+3. **Start Coding:** Enjoy your $25 in total free credits
+
+:::note About the temporary hold
+The $0.50 hold is for identity verification only:
+
+- **Not a charge** - This is a temporary authorization that will not be charged
+- **Instant release** - Kilo Code releases the hold immediately after verification
+- **Bank processing** - While we release instantly, it may take a few business days for funds to return (varies by bank)
+  :::
+
+## Registration Process
+
+Kilo Code offers a streamlined registration that connects you directly to frontier coding models:
+
+1. **Start Registration:** Click "Try Kilo Code for Free" in the extension
+2. **Sign In:** Use your Google account to sign in at kilocode.ai
+3. **Authorize VS Code:**
+   - kilocode.ai will prompt you to open Visual Studio Code
+   - For web-based IDEs, you'll copy the API key manually instead
+4. **Complete Setup:** Allow VS Code to open the authorization URL when prompted
+
+<!-- <img src="/img/setting-up/signupflow.gif" alt="Sign up and registration flow with Kilo Code" width="600" /> -->
+
+## Supported Models
+
+Kilo Code provides access to the latest frontier coding models through its built-in provider. The specific models available are automatically updated and managed by the Kilo Code service, ensuring you always have access to the most capable models for coding tasks.
+
+## Configuration in Kilo Code
+
+Once you've completed the registration process, Kilo Code is automatically configured:
+
+1. **Automatic Setup:** After successful registration, Kilo Code is ready to use immediately
+2. **No API Key Management:** Your authentication is handled seamlessly through the registration process
+3. **Model Selection:** Access to frontier models is provided automatically through your Kilo Code account
+
+## Tips and Notes
+
+- **Free Credits:** New users receive free credits to explore Kilo Code's capabilities
+- **Identity Verification:** The temporary hold system ensures service reliability while preventing misuse
+- **Seamless Integration:** No need to manage multiple API keys or provider configurations
+- **Latest Models:** Automatic access to the most current frontier coding models
+- **Support Available:** Contact [[email protected]](mailto:[email protected]) for questions about pricing or tokens
+
+For detailed setup instructions, see [Setting up Kilo Code](/getting-started/setting-up).

apps/kilocode-docs/docs/providers/lmstudio.md

@@ -0,0 +1,40 @@
+---
+sidebar_label: LM Studio
+---
+
+# Using LM Studio With Kilo Code
+
+Kilo Code supports running models locally using LM Studio.  LM Studio provides a user-friendly interface for downloading, configuring, and running local language models.  It also includes a built-in local inference server that emulates the OpenAI API, making it easy to integrate with Kilo Code.
+
+**Website:** [https://lmstudio.ai/](https://lmstudio.ai/)
+
+## Setting Up LM Studio
+
+1.  **Download and Install LM Studio:** Download LM Studio from the [LM Studio website](https://lmstudio.ai/).
+2.  **Download a Model:**  Use the LM Studio interface to search for and download a model.  Some recommended models include:
+    *   CodeLlama models (e.g., `codellama:7b-code`, `codellama:13b-code`, `codellama:34b-code`)
+    *   Mistral models (e.g., `mistralai/Mistral-7B-Instruct-v0.1`)
+    *   DeepSeek Coder models (e.g., `deepseek-coder:6.7b-base`)
+    * Any other model that is supported by Kilo Code, or for which you can set the context window.
+
+    Look for models in the GGUF format.  LM Studio provides a search interface to find and download models.
+3.  **Start the Local Server:**
+    *   Open LM Studio.
+    *   Click the **"Local Server"** tab (the icon looks like `<->`).
+    *   Select the model you downloaded.
+    *   Click **"Start Server"**.
+
+## Configuration in Kilo Code
+
+1.  **Open Kilo Code Settings:** Click the gear icon (<Codicon name="gear" />) in the Kilo Code panel.
+2.  **Select Provider:** Choose "LM Studio" from the "API Provider" dropdown.
+3.  **Enter Model ID:** Enter the *file name* of the model you loaded in LM Studio (e.g., `codellama-7b.Q4_0.gguf`).  You can find this in the LM Studio "Local Server" tab.
+4.  **(Optional) Base URL:**  By default, Kilo Code will connect to LM Studio at `http://localhost:1234`.  If you've configured LM Studio to use a different address or port, enter the full URL here.
+
+## Tips and Notes
+
+*   **Resource Requirements:** Running large language models locally can be resource-intensive. Make sure your computer meets the minimum requirements for the model you choose.
+*   **Model Selection:**  LM Studio provides a wide range of models.  Experiment to find the one that best suits your needs.
+*   **Local Server:**  The LM Studio local server must be running for Kilo Code to connect to it.
+*   **LM Studio Documentation:** Refer to the [LM Studio documentation](https://lmstudio.ai/docs) for more information.
+*   **Troubleshooting:** If you see a "Please check the LM Studio developer logs to debug what went wrong" error, you may need to adjust the context length settings in LM Studio.

apps/kilocode-docs/docs/providers/mistral.md

@@ -0,0 +1,53 @@
+---
+sidebar_label: Mistral AI
+---
+
+# Using Mistral AI With Kilo Code
+
+Kilo Code supports accessing models through the Mistral AI API, including both standard Mistral models and the code-specialized Codestral model.
+
+**Website:** [https://mistral.ai/](https://mistral.ai/)
+
+## Getting an API Key
+
+1.  **Sign Up/Sign In:** Go to the [Mistral Platform](https://console.mistral.ai/). Create an account or sign in.  You may need to go through a verification process.
+2.  **Create an API Key:**  
+    - [La Plateforme API Key](https://console.mistral.ai/api-keys/) and/or 
+    - [Codestral API Key](https://console.mistral.ai/codestral)
+
+## Supported Models
+
+Kilo Code supports the following Mistral models:
+
+| Model ID               | Model Default Temperature | Function Calling | Vision / Image support |
+|------------------------|-------------------------|------------------|--------|
+| codestral-latest      | 0.3                     | ✅               | ❌      |
+| devstral              | 0.3                     | ✅               | ❌      |
+| mistral-large-latest  | 0.7                     | ✅               | ❌      |
+| ministral-8b-latest   | 0.3                     | ✅               | ❌      |
+| ministral-3b-latest   | 0.3                     | ✅               | ❌      |
+| mistral-small-latest  | 0.3                     | ✅               | ❌      |
+| pixtral-large-latest  | 0.7                     | ✅               | ✅      |
+The default model temperature in Kilo Code is 0.0, so you should consider experimenting with [temperature adjustments](/features/model-temperature)!
+
+**Note:**  Model availability and specifications may change.
+Refer to the [Mistral AI documentation](https://docs.mistral.ai/api/) and [Mistral Model Overview](https://docs.mistral.ai/getting-started/models/models_overview/) for the latest information.
+
+## Configuration in Kilo Code
+
+1.  **Open Kilo Code Settings:** Click the gear icon (<Codicon name="gear" />) in the Kilo Code panel.
+2.  **Select Provider:** Choose "Mistral" from the "API Provider" dropdown.
+3.  **Enter API Key:** Paste your Mistral API key into the "Mistral API Key" field if you're using a `mistral` model.  If you intend to use `codestral-latest`, see the "Codestral" section below.
+4.  **Select Model:** Choose your desired model from the "Model" dropdown. 
+
+## Using Codestral
+
+[Codestral](https://docs.mistral.ai/capabilities/code_generation/) is a model specifically designed for code generation and interaction. 
+Only for Codestral you could use different endpoints (Default: codestral.mistral.ai). 
+For the La Platforme API Key change the **Codestral Base Url** to: https://api.mistral.ai 
+
+To use Codestral:
+
+1.  **Select "Mistral" as the API Provider.**
+2.  **Select a Codestral Model**
+3.  **Enter your Codestral (codestral.mistral.ai) or La Plateforme (api.mistral.ai) API Key.** 

apps/kilocode-docs/docs/providers/ollama.md

@@ -0,0 +1,142 @@
+---
+sidebar_label: Ollama
+---
+
+# Using Ollama With Kilo Code
+
+Kilo Code supports running models locally using Ollama. This provides privacy, offline access, and potentially lower costs, but requires more setup and a powerful computer.
+
+**Website:** [https://ollama.com/](https://ollama.com/)
+
+<img src="/docs/img/providers/ollama-devstral-snake.png" alt="Vibe coding a Snake game using devstral" width="500" />
+*Vibe coding a Snake game using devstral*
+
+## Managing Expectations
+
+Local LLMs are much smaller than premium cloud-hosted LLMs such as Claude and Gemini and the results will be much less impressive.
+They are much more likely to get stuck in loops, fail to use tools properly or produce syntax errors in code.
+More trial and error will be required to find the right prompt.
+Local LLMs are usually also not very fast.
+Using simple prompts, keeping conversations short and disabling MCP tools can result in a speed-up.
+
+
+## Hardware Requirements
+
+You will need a large amount of RAM (32GB or more) and a powerful CPU (e.g. Ryzen 9000 series) to run the models listed below.
+GPUs can run LLMs much faster, but a large amount of VRAM is required (24GB, if not more), which is not very common on consumer GPUs.
+Smaller models will run on more modest GPUs, but do not provide good results.
+MacBooks with a sufficient amount of unified memory can use GPU-acceleration, but do not outperform high-end desktop CPUs in our testing.
+
+
+## Selecting a Model
+
+Ollama supports many different models.
+You can find a list of available models on the [Ollama website](https://ollama.com/library).
+Selecting a model that suits your use case, runs on your hardware configuration and achieves the desired speed requires some trial and error.
+The following rules and heuristics can be used to find a model:
+
+* Must have at least a 32k context window (this is a requirement for Kilo Code).
+* Listed as supporting tools.
+* Number of parameters in the 7b to 24b range.
+* Prefer popular models.
+* Prefer newer models.
+
+
+### Recommendations for Kilo Code
+
+We tested a few models with the following prompt:
+
+```
+Create a simple web page with a button that greets the user when clicked.
+```
+
+A model is considered to pass if it produces a working result within a few tries. The models we found to work correctly are:
+
+| Model name | Completion time |
+| --- | --- |
+| qwen2.5-coder:7b | 1x (baseline) |
+| devstral:24b | 2x |
+| gemma3:12b | 4x |
+| qwen3-8b | 12x |
+
+Our recommendation is to use **devstral:24b** if your hardware can handle it, because it makes fewer mistakes than qwen2.5-coder:7b.
+qwen2.5-coder:7b is worth considering because of its speed, if you can put up with its mistakes.
+The table also shows speed can be hard to predict, since the special-purpose devstral:24b outperforms the smaller general-purpose models gemma3:12b and qwen3-8b here.
+The gemma3:12b result is remarkable, because it can use tools correctly (at least sometimes), while not being listed as suitable for tool use on the Ollama website.
+
+The result produced by devstral:24b is included below:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Greet User Button</title>
+    <style>
+        body {
+            font-family: Arial, sans-serif;
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            height: 100vh;
+            margin: 0;
+        }
+        button {
+            padding: 10px 20px;
+            font-size: 16px;
+            cursor: pointer;
+        }
+    </style>
+</head>
+<body>
+    <button onclick="greetUser()">Greet Me!</button>
+
+    <script>
+        function greetUser() {
+            alert('Hello! Welcome to our website.');
+        }
+    </script>
+</body>
+</html>
+```
+
+The following models look like reasonable choices, but were found to **not** work properly with Kilo Code in its default configuration:
+
+| Model name | Fail reason |
+| --- | --- |
+| deepseek-r1:7b | fails to use tools properly |
+| deepseek-r1:8b | gets stuck in a reasoning loop |
+
+
+## Setting up Ollama
+
+1.  **Download and Install Ollama:**  Download the Ollama installer for your operating system from the [Ollama website](https://ollama.com/). Follow the installation instructions and make sure Ollama is running:
+
+    ```bash
+    ollama serve
+    ```
+
+2.  **Download a Model:** Once you've downloaded a model, you can use Kilo Code offline with that model. To download a model, open your terminal and run:
+
+    ```bash
+    ollama pull <model_name>
+    ```
+
+    For example:
+
+    ```bash
+    ollama pull devstral:24b
+    ```
+
+4.  **Configure Kilo Code:**
+    *   Open the Kilo Code sidebar (<img src="/docs/img/kilo-v1.svg" width="12" /> icon).
+    *   Click the settings gear icon (<Codicon name="gear" />).
+    *   Select "ollama" as the API Provider.
+    *   Enter the Model name.
+    *   (Optional) You can configure the base URL if you're running Ollama on a different machine. The default is `http://localhost:11434`.
+
+
+## Further Reading
+
+Refer to the [Ollama documentation](https://ollama.com/docs) for more information on installing, configuring and using Ollama.

apps/kilocode-docs/docs/providers/openai-compatible.md

@@ -0,0 +1,83 @@
+---
+sidebar_label: OpenAI Compatible
+---
+
+# Using OpenAI Compatible Providers With Kilo Code
+
+Kilo Code supports a wide range of AI model providers that offer APIs compatible with the OpenAI API standard. This means you can use models from providers *other than* OpenAI, while still using a familiar API interface.  This includes providers like:
+
+*   **Local models** running through tools like Ollama and LM Studio (covered in separate sections).
+*   **Cloud providers** like Perplexity, Together AI, Anyscale, and others.
+*   **Any other provider** offering an OpenAI-compatible API endpoint.
+
+This document focuses on setting up providers *other than* the official OpenAI API (which has its own [dedicated configuration page](/providers/openai)).
+
+## General Configuration
+
+The key to using an OpenAI-compatible provider is to configure two main settings:
+
+1.  **Base URL:** This is the API endpoint for the provider.  It will *not* be `https://api.openai.com/v1` (that's for the official OpenAI API).
+2.  **API Key:**  This is the secret key you obtain from the provider.
+3.  **Model ID:** This is the model name of the specific model.
+
+You'll find these settings in the Kilo Code settings panel (click the <Codicon name="gear" /> icon):
+
+*   **API Provider:** Select "OpenAI Compatible".
+*   **Base URL:** Enter the base URL provided by your chosen provider.  **This is crucial.**
+*   **API Key:** Enter your API key.
+*   **Model:** Choose a model.
+*   **Model Configuration:** This lets you customize advanced configuration for the model
+    - Max Output Tokens
+    - Context Window
+    - Image Support
+    - Computer Use
+    - Input Price
+    - Output Price
+
+### Full Endpoint URL Support
+
+Kilo Code supports full endpoint URLs in the Base URL field, providing greater flexibility for provider configuration:
+
+**Standard Base URL Format:**
+```
+https://api.provider.com/v1
+```
+
+**Full Endpoint URL Format:**
+```
+https://api.provider.com/v1/chat/completions
+https://custom-endpoint.provider.com/api/v2/models/chat
+```
+
+This enhancement allows you to:
+- Connect to providers with non-standard endpoint structures
+- Use custom API gateways or proxy services
+- Work with providers that require specific endpoint paths
+- Integrate with enterprise or self-hosted API deployments
+
+**Note:** When using full endpoint URLs, ensure the URL points to the correct chat completions endpoint for your provider.
+
+## Supported Models (for OpenAI Native Endpoint)
+
+While this provider type allows connecting to various endpoints, if you are connecting directly to the official OpenAI API (or an endpoint mirroring it exactly), Kilo Code recognizes the following model IDs based on the `openAiNativeModels` definition in its source code:
+
+*   `o3-mini`
+*   `o3-mini-high`
+*   `o3-mini-low`
+*   `o1`
+*   `o1-preview`
+*   `o1-mini`
+*   `gpt-4.5-preview`
+*   `gpt-4o`
+*   `gpt-4o-mini`
+
+**Note:** If you are using a different OpenAI-compatible provider (like Together AI, Anyscale, etc.), the available model IDs will vary. Always refer to your specific provider's documentation for their supported model names.
+
+## Troubleshooting
+
+*   **"Invalid API Key":** Double-check that you've entered the API key correctly.
+*   **"Model Not Found":** Make sure you're using a valid model ID for your chosen provider.
+*   **Connection Errors:** Verify the Base URL is correct and that your provider's API is accessible.
+*   **Unexpected Results:** If you're getting unexpected results, try a different model.
+
+By using an OpenAI-compatible provider, you can leverage the flexibility of Kilo Code with a wider range of AI models. Remember to always consult your provider's documentation for the most accurate and up-to-date information.