Merge branch 'main' into mark/removememorybank

2026-08-30 17:14:40 +08:00 · 2026-02-04 10:46:50 +01:00
parent 4ddccbc18f b895abd493
commit 22c045d8be
39 changed files with 1267 additions and 29 deletions
@@ -6,6 +6,16 @@ This is the Kilo Code documentation site. Kilo Code is the leading open source a

 The dev server is run with `bun dev` and runs on `http://localhost:3002`. Typically the user will be running it themselves, so always check if it is running FIRST before deciding to run it yourself to test something.

+## Branch Naming Convention
+
+When making changes _only_ to the documentation, create branches with the `docs/` prefix:
+
+```bash
+git checkout -b docs/description-of-change
+```
+
+This convention helps identify documentation-only PRs and keeps them organized.
+
 ## Markdoc Custom Tags

 This project uses [Markdoc](https://markdoc.dev/) for rendering markdown with custom components. Custom tags allow you to embed React components directly in markdown files.
@@ -37,3 +37,19 @@ The quickest way to deploy your own version of this boilerplate is by deploying
 ### Deploy to Netlify

 [![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/markdoc/next.js-starter)
+
+## Contributing
+
+When making documentation _only_ changes, use branch names prefixed with `docs/`:
+
+```bash
+git checkout -b docs/your-change-description
+```
+
+Examples:
+
+- `docs/add-mcp-tutorial`
+- `docs/fix-installation-steps`
+- `docs/update-api-reference`
+
+For full contribution guidelines, see the [Contributing Guide](https://kilo.ai/docs/contributing).
@@ -17,18 +17,29 @@ export function Image({ src, alt, width, height, caption }: ImageProps) {
 	if (width) imgStyle.width = width
 	if (height) imgStyle.height = height

+	const figureStyle: React.CSSProperties = {
+		margin: "1.5rem 0",
+		maxWidth: "100%",
+		overflow: "hidden",
+	}
+
+	// If width is specified, apply it to the figure to constrain caption width
+	if (width) {
+		figureStyle.width = width
+		figureStyle.maxWidth = "100%"
+	}
+
 	return (
-		<figure style={{ margin: "1.5rem 0", maxWidth: "100%", overflow: "hidden" }}>
+		<figure style={figureStyle}>
 			<img src={src} alt={alt} style={imgStyle} />
 			{caption && (
 				<figcaption
 					style={{
-						display: "table-caption",
-						captionSide: "bottom",
 						fontStyle: "italic",
 						textAlign: "center",
 						marginTop: "0.5rem",
 						color: "var(--gray-600, #6b7280)",
+						width: "100%",
 					}}>
 					{caption}
 				</figcaption>
@@ -33,6 +33,10 @@ export const CustomizeNav: NavSection[] = [
 				href: "/customize/context/codebase-indexing",
 				children: "Codebase Indexing",
 			},
+			{
+				href: "/customize/context/kilocodeignore",
+				children: ".kilocodeignore",
+			},
 			{
 				href: "/customize/context/large-projects",
 				children: "Large Projects",
@@ -16,9 +16,22 @@ export const GettingStartedNav: NavSection[] = [
 				href: "/getting-started/setup-authentication",
 				children: "Setup & Authentication",
 			},
+			{
+				href: "/getting-started/byok",
+				children: "Bring Your Own Key (BYOK)",
+			},
 			{ href: "/ai-providers", children: "AI Providers" },
-			{ href: "/getting-started/settings", children: "Settings" },
+			{
+				href: "/getting-started/settings",
+				children: "Settings",
+				subLinks: [
+					{ href: "/getting-started/settings/auto-approving-actions", children: "Auto-Approving Actions" },
+					{ href: "/getting-started/settings/auto-cleanup", children: "Auto Cleanup" },
+					{ href: "/getting-started/settings/system-notifications", children: "System Notifications" },
+				],
+			},
 			{ href: "/getting-started/adding-credits", children: "Adding Credits" },
+			{ href: "/getting-started/rate-limits-and-costs", children: "Rate Limits and Costs" },
 		],
 	},
 	{
@@ -162,17 +162,17 @@

 ## Pages to Remove from Nav / Condense

-| Page                               | Recommendation                                           |
-| ---------------------------------- | -------------------------------------------------------- |
-| `features/system-notifications`    | Fold into Settings or remove                             |
-| `features/more-features`           | This is a red flag - break out or remove                 |
-| `features/suggested-responses`     | Fold into Chat Interface                                 |
-| `features/auto-approving-actions`  | Fold into Settings                                       |
-| `advanced-usage/auto-cleanup`      | Fold into Settings                                       |
-| `features/model-temperature`       | Fold into Model Selection                                |
-| `advanced-usage/rate-limits-costs` | Fold into Adding Credits or AI Providers                 |
-| `features/footgun-prompting`       | Remove                                                   |
-| `tips-and-tricks`                  | Could become a blog post or fold relevant bits elsewhere |
+| Page                                  | Recommendation                                           |
+| ------------------------------------- | -------------------------------------------------------- |
+| ☑️ `features/system-notifications`    | Fold into Settings or remove                             |
+| ❎ `features/more-features`           | Remove                                                   |
+| ☑️ `features/suggested-responses`     | Fold into Chat Interface                                 |
+| ☑️ `features/auto-approving-actions`  | Fold into Settings                                       |
+| ☑️ `advanced-usage/auto-cleanup`      | Fold into Settings                                       |
+| ❎ `features/model-temperature`       | Remove                                                   |
+| ☑️ `advanced-usage/rate-limits-costs` | Fold into Adding Credits or AI Providers                 |
+| ❎ `features/footgun-prompting`       | Remove                                                   |
+| ☑️ `tips-and-tricks`                  | Could become a blog post or fold relevant bits elsewhere |

 ---

@@ -30,9 +30,9 @@ Describe what you want to accomplish in natural language, and Kilo Code will:

 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._
+{% callout type="info" title="Tool Approval UI" %}
+When a tool is proposed, you'll see Save and Reject buttons along with an optional Auto-approve checkbox for trusted operations.
+{% /callout %}

 **User:** Create a file named `greeting.js` that logs a greeting message

@@ -207,6 +207,10 @@ Common issues and solutions:
 - **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

+{% callout type="tip" %}
+**Reduce system prompt size:** If you're not using MCP, turn it off in Settings > Agent Behaviour > MCP Servers to significantly cut down the size of the system prompt and improve performance.
+{% /callout %}
+
 ## Platform-Specific MCP Configuration Examples

 ### Windows Configuration Example
@@ -91,4 +91,51 @@ find all instances of the variable oldValue in @/src/App.js and replace them wit

 **Why it matters:** Kilo Code works best when you communicate like you're talking to a smart teammate who needs clear direction.

+## Suggested Responses
+
+When Kilo Code needs more information to complete a task, it uses the [`ask_followup_question`](/docs/features/tools/ask-followup-question) tool. To make responding easier and faster, Kilo Code often provides suggested answers alongside the question.
+
+{% image src="/docs/img/suggested-responses/suggested-responses.png" alt="Example of Kilo Code asking a question with suggested response buttons below it" width="800" caption="Suggested responses appear as clickable buttons below questions" /%}
+
+**How it works:**
+
+1. **Question Appears** - Kilo Code asks a question using the `ask_followup_question` tool
+2. **Suggestions Displayed** - If suggestions are provided, 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.
+
+**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.
+
+## Tips for Better Workflow
+
+{% callout type="tip" %}
+**Move Kilo Code to the Secondary Side Bar** for a better layout. Right-click on the Kilo Code icon in the Activity Bar and select **Move To → Secondary Side Bar**. This lets you see the Explorer, Search, Source Control, etc. alongside Kilo Code.
+
+{% image src="/docs/img/move-to-secondary.png" alt="Move to Secondary Side Bar" width="600" caption="Move Kilo Code to the Secondary Side Bar for better workspace organization" /%}
+{% /callout %}
+
+{% callout type="tip" %}
+**Drag files directly into chat.** Once you have Kilo Code in a separate sidebar from the file explorer, you can drag files from the explorer into the chat window (even multiple at once). Just hold down the Shift key after you start dragging the files.
+{% /callout %}
+
 Ready to start coding? Open the chat panel and describe what you want to build!
@@ -38,6 +38,14 @@ One thing that doesn't change: context window size matters for your workflow.

 Check [our provider docs](/docs/basic-usage/connecting-providers) for specific context limits on each model.

+{% callout type="tip" %}
+**Be thoughtful about Max Tokens settings for thinking models.** Every token you allocate to output takes away from space available to store conversation history. Consider only using high `Max Tokens` / `Max Thinking Tokens` settings with modes like Architect and Debug, and keeping Code mode at 16k max tokens or less.
+{% /callout %}
+
+{% callout type="tip" %}
+**Recover from context limit errors:** If you hit the `input length and max tokens exceed context limit` error, you can recover by deleting a message, rolling back to a previous checkpoint, or switching over to a model with a long context window like Gemini for a message.
+{% /callout %}
+
 ## Stay Current

 The AI model space moves fast. Bookmark [kilo.ai/models](https://kilo.ai/models) and check back when you're evaluating options. What's best today might not be best next month — and that's actually exciting.
@@ -78,6 +78,10 @@ Four ways to switch modes:
 | **Ideal For**        | Tracking down bugs, diagnosing errors, and resolving complex issues                 |
 | **Special Features** | Uses a methodical approach of analyzing, narrowing possibilities, and fixing issues |

+{% callout type="tip" %}
+**Keep debugging separate from main tasks:** When using Debug mode, ask Kilo to "start a new task in Debug mode with all of the necessary context needed to figure out X" so that the debugging process uses its own context window and doesn't pollute the main task.
+{% /callout %}
+
 ### Orchestrator Mode

 | Aspect               | Details                                                                                                             |
@@ -96,6 +96,18 @@ If using Cursor, go to **Settings** > **Cursor Settings** > **Tab**, and toggle

 ## Tips

+{% callout type="tip" %}
+**When to use chat vs autocomplete:** Use chat for multi-file changes, refactoring, or when you need to explain intent. Use autocomplete for quick, localized edits where the context is already clear from surrounding code.
+{% /callout %}
+
+{% callout type="tip" %}
+**Steer autocomplete with comments:** Write a comment describing what you want before triggering autocomplete, or type a function signature—autocomplete will fill in the implementation.
+{% /callout %}
+
+{% callout type="tip" %}
+**Treat suggestions as drafts:** Accept autocomplete suggestions quickly, then refine. It's often faster to fix a 90% correct suggestion than to craft the perfect prompt.
+{% /callout %}
+
 - Autocomplete works best with clear, well-structured code
 - Comments above functions help autocomplete understand intent
 - Variable and function names matter - descriptive names lead to better suggestions
@@ -32,9 +32,13 @@ Before diving into the code, we recommend reviewing the [Architecture Overview](

 - Create a new branch for each feature or bugfix
 - Use descriptive branch names (e.g., `feature/new-tool-support` or `fix/browser-action-bug`)
+- **For documentation only changes**: Use the `docs/` prefix (e.g., `docs/improve-mcp-guide`)

 ```bash
 git checkout -b your-branch-name
+
+# For documentation changes:
+git checkout -b docs/your-change-description
 ```

 ### Coding Standards
@@ -97,16 +97,22 @@ For team or production use:

 ## 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:
+### Open Codebase Indexing Settings
+
+1. In the chat header, click the database icon (indexing status)
+2. The Codebase Indexing settings panel opens
+3. If you don't see the icon, open Kilo Code settings (<Codicon name="gear" />) and search for **Codebase Indexing**
+
+### Configure Settings
+
+1. Enable **"Enable Codebase Indexing"** using the toggle switch
+2. 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
+3. Set Qdrant URL and optional API key
+4. Configure **Max Search Results** (default: 20, range: 1-100)
+5. Click **Save** to start initial indexing

 ### Enable/Disable Toggle

@@ -148,7 +154,7 @@ The indexer automatically excludes:
 - Large files (&gt;1MB)
 - Git repositories (`.git` folders)
 - Dependencies (`node_modules`, `vendor`, etc.)
- Files matching `.gitignore` and `.kilocodeignore` patterns
+- Files matching `.gitignore` and [`.kilocodeignore`](/docs/customize/context/kilocodeignore) patterns

 ### Incremental Updates

@@ -0,0 +1,74 @@
+---
+title: ".kilocodeignore"
+description: "Control which files Kilo Code can access"
+---
+
+# .kilocodeignore
+
+## Overview
+
+`.kilocodeignore` is a root-level file that tells Kilo Code which files and folders it should not access. It uses standard `.gitignore` pattern syntax, but it only affects Kilo Code's file access, not Git.
+
+If no `.kilocodeignore` file exists, Kilo Code can access all files in the workspace.
+
+## Quick Start
+
+1. Create a `.kilocodeignore` file at the root of your project.
+2. Add patterns for files or folders you want Kilo Code to avoid.
+3. Save the file. Kilo Code will pick up the changes automatically.
+
+Example:
+
+```txt
+# Secrets
+.env
+secrets/
+**/*.pem
+**/*.key
+
+# Build output
+dist/
+coverage/
+
+# Allow a specific file inside a blocked folder
+!secrets/README.md
+```
+
+## Pattern Rules
+
+`.kilocodeignore` follows the same rules as `.gitignore`:
+
+- `#` starts a comment
+- `*` and `**` match wildcards
+- Trailing `/` matches directories only
+- `!` negates a previous rule
+
+Patterns are evaluated relative to the workspace root.
+
+## What It Affects
+
+Kilo Code checks `.kilocodeignore` before accessing files in tools like:
+
+- [`read_file`](/docs/automate/tools/read-file)
+- [`write_to_file`](/docs/automate/tools/write-to-file)
+- [`apply_diff`](/docs/automate/tools/apply-diff)
+- [`delete_file`](/docs/automate/tools/delete-file)
+- [`execute_command`](/docs/automate/tools/execute-command)
+- [`list_files`](/docs/automate/tools/list-files)
+
+If a file is blocked, Kilo Code will return an "access denied" message and suggest updating your `.kilocodeignore` rules.
+
+## Visibility in Lists
+
+By default, ignored files are hidden from file lists. You can show them with a lock icon by enabling:
+
+Settings -> Context -> **Show .kilocodeignore'd files in lists and searches**
+
+## Checkpoints vs .kilocodeignore
+
+Checkpoint tracking is separate from file access rules. Files blocked by `.kilocodeignore` can still be checkpointed if they are not excluded by `.gitignore`. See the [Checkpoints](/docs/code-with-ai/features/checkpoints) documentation for details.
+
+## Troubleshooting
+
+- **Kilo can't access a file you want:** Remove or narrow the matching rule in `.kilocodeignore`.
+- **A file still appears in lists:** Check the setting that shows ignored files in lists and searches.
@@ -18,6 +18,10 @@ Each mode—including custom ones—features **Sticky Models**. This means Kilo
 - **Experimentation:** Safely experiment with different prompts and configurations without affecting other modes
 - **Team Collaboration:** Share custom modes with your team to standardize workflows

+{% callout type="tip" %}
+**Keep custom modes on track:** Limit the types of files that they're allowed to edit using the `fileRegex` option in the `groups` configuration. This prevents modes from accidentally modifying files outside their intended scope.
+{% /callout %}
+
 {% image src="/docs/img/custom-modes/custom-modes.png" alt="Overview of custom modes interface" width="600" caption="Overview of custom modes interface" /%}

 _Kilo Code's interface for creating and managing custom modes._
@@ -94,6 +98,10 @@ Create a new mode called "Documentation Writer". It should only be able to read

 Kilo Code will guide you through the process, prompting for necessary information and creating the mode using the preferred YAML format.

+{% callout type="tip" %}
+**Create modes from job postings:** If there's a real world job posting for something you want a custom mode to do, try asking Code mode to `Create a custom mode based on the job posting at @[url]`. This can help you quickly create specialized modes with realistic role definitions.
+{% /callout %}
+
 ### 2. Using the Prompts Tab

 1. **Open Prompts Tab:** Click the <Codicon name="notebook" /> icon in the Kilo Code top menu bar
@@ -0,0 +1,50 @@
+---
+title: "Bring Your Own Key (BYOK)"
+description: "Use your own API keys with Kilo Gateway while retaining platform features"
+---
+
+# Bring Your Own Key (BYOK)
+
+Bring Your Own Key (BYOK) lets you use your own API keys when using the Kilo Gateway, while retaining Kilo platform features like Code Reviews and Cloud Agents.
+
+A user or organization may want to use BYOK to:
+
+- Utilize new models quickly, Kilo Gateway supports most new models in minutes
+- Use subscriptions with third-party AI providers, for example [Z.AI](https://z.ai/subscribe) or [Minimax](https://platform.minimax.io/subscribe/coding-plan)
+- Attribute usage against existing provider commitments or agreements
+- Use existing credits with a provider
+
+## Supported BYOK providers
+
+Kilo Gateway currently supports BYOK keys for these providers:
+
+- Anthropic
+- OpenAI
+- Google AI Studio
+- Minimax
+- Mistral AI
+- xAI
+- Z.AI
+
+## Add a BYOK key
+
+1. Log into the Kilo platform and select the account or organization you want to add the BYOK key to.
+2. Navigate to the [Bring Your Own Key (BYOK) page](https://app.kilo.ai/byok), available in the sidebar under `Account`.
+3. Click `Add Your First Key`, select the provider, and paste your API key.
+4. Save.
+
+## How Bring Your Own Key works
+
+- When you use the **Kilo Gateway** provider, Kilo checks if there's a BYOK key for the selected model's provider.
+- If a matching BYOK key exists, the request is routed using your key.
+- If the key is invalid, the request fails. It does not fall back to using Kilo's keys.
+
+## Using BYOK in the Extensions and CLI
+
+- BYOK works with the Kilo Gateway provider. Users should ensure that is set as the active [provider](/docs/ai-providers).
+- Select a model from a provider configured for BYOK, for example Claude Sonnet 4.5 if you configured BYOK for Anthropic.
+- (Optional) Validate with the provider that traffic is being served by that key.
+
+## Limitations
+
+- BYOK is not fully supported by Agent Manager. See [Agent Manager](/docs/automate/agent-manager) for details.
@@ -79,3 +79,7 @@ Ready for more? Here are some next steps:
 - **[Autocomplete](/docs/code-with-ai/features/autocomplete)** — Get inline code suggestions as you type
 - **[Modes](/docs/code-with-ai/agents/using-modes)** — Explore different modes for different tasks
 - **[Git commit generation](/docs/code-with-ai/features/git-commit-generation)** — Automatically generate commit messages
+
+{% callout type="tip" %}
+**Accelerate development:** Check out multiple copies of your repository and run Kilo Code on all of them in parallel (using git to resolve any conflicts, same as with human devs). This can dramatically speed up development on large projects.
+{% /callout %}
@@ -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 Settings > Agent Behaviour > MCP Servers](/automate/mcp/overview) 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.
@@ -0,0 +1,345 @@
+---
+title: "Auto-Approving Actions"
+description: "Configure automatic approval settings for Kilo Code operations"
+---
+
+# Auto-Approving Actions
+
+{% callout type="danger" %}
+**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.
+{% /callout %}
+
+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
+
+[![KiloCode Task Timeline](https://img.youtube.com/vi/NBccFnYDQ-k/maxresdefault.jpg)](https://youtube.com/shorts/NBccFnYDQ-k?feature=shared)
+
+## Auto-Approve Toolbar
+
+{% image src="/docs/img/auto-approving-actions/auto-approving-actions.png" alt="Auto-approve toolbar collapsed state" width="800" caption="Prompt box and Auto-Approve Toolbar showing enabled permissions" /%}
+
+Click the toolbar to expand it and configure individual permissions:
+
+{% image src="/docs/img/auto-approving-actions/auto-approving-actions-1.png" alt="Auto-approve toolbar expanded state" width="800" caption="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:
+
+{% image src="/docs/img/auto-approving-actions/auto-approving-actions-14.png" alt="Master toggle in Auto-approve toolbar" width="800" caption="Master toggle 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. To access these settings:
+
+1. Click {% codicon name="gear" /%} in the top-right corner
+2. Navigate to Auto-Approve Settings
+
+{% image src="/docs/img/auto-approving-actions/auto-approving-actions-4.png" alt="Settings panel auto-approve options" width="800" caption="Complete settings panel view" /%}
+
+{% callout type="info" %}
+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.
+{% /callout %}
+
+### Read Operations
+
+{% image src="/docs/img/auto-approving-actions/auto-approving-actions-6.png" alt="Read-only operations setting" width="800" caption="Read operations settings" /%}
+
+**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.
+
+#### Read Outside Workspace
+
+**Setting:** "Allow reading files outside the workspace"
+
+**Description:** When enabled, Kilo Code can read files outside the current workspace directory without asking for approval.
+
+**Risk level:** Medium-High
+
+This setting extends read permissions beyond your project folder. Consider the security implications:
+
+- Kilo Code could access sensitive files in your home directory
+- Configuration files, SSH keys, or credentials could be read
+- Only enable if you trust the AI and need it to access external files
+
+**Recommendation:** Keep disabled unless you specifically need Kilo Code to read files outside your project.
+
+### Write Operations
+
+{% image src="/docs/img/auto-approving-actions/auto-approving-actions-7.png" alt="Write operations setting with delay slider" width="800" caption="Write operations settings with diagnostic delay slider" /%}
+
+**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 Outside Workspace
+
+**Setting:** "Allow writing files outside the workspace"
+
+**Description:** When enabled, Kilo Code can create or modify files outside the current workspace directory without asking for approval.
+
+**Risk level:** Very High
+
+Use with caution and in controlled environments. It allows Kilo Code to:
+
+- Modify your shell configuration files
+- Change system configurations
+- Write to any location your user has access to
+
+**Recommendation:** Keep disabled unless absolutely necessary. Even experienced users should avoid this setting.
+
+#### Write to Protected Files
+
+**Setting:** "Allow writing to protected files"
+
+**Description:** When enabled, Kilo Code can overwrite or modify files that are normally protected by the [`.kilocodeignore`](/docs/customize/custom-rules) file.
+
+**Risk level:** Very High
+
+Protected files are intentionally shielded from modification. Enable only if you understand the consequences.
+
+### Delete Operations
+
+{% callout type="danger" %}
+**Delete Operations**
+
+**Setting:** "Always approve delete operations"
+
+**Description:** Automatically delete files and directories without requiring approval
+
+**Risk level:** Very High
+
+This setting allows Kilo Code to permanently remove files without confirmation.
+
+**Safeguards:**
+
+- Kilo Code still respects `.kilocodeignore` rules
+- Protected files cannot be deleted
+- The delete tool shows what will be removed before execution
+
+**Recommendation:** Enable only in isolated environments or when working with temporary/generated files. Always ensure you have backups, checkpoints, or version control.
+{% /callout %}
+
+### Browser Actions
+
+{% image src="/docs/img/auto-approving-actions/auto-approving-actions-8.png" alt="Browser actions setting" width="800" caption="Browser actions settings" /%}
+
+**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
+
+{% image src="/docs/img/auto-approving-actions/auto-approving-actions-9.png" alt="API requests retry setting with delay slider" width="800" caption="API request retry settings" /%}
+
+**Setting:** "Always retry failed API requests"
+
+**Description:** Automatically retry failed API requests when server returns an error response
+
+**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
+
+{% image src="/docs/img/auto-approving-actions/auto-approving-actions-10.png" alt="MCP tools setting" width="800" caption="MCP tools auto-approval settings" /%}
+
+**Setting:** "Always approve MCP tools"
+
+**Description:** Enable auto-approval of individual MCP tools in the Agent Behaviour > 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 Agent Behaviour > MCP Servers view. Both this global setting and the tool-specific permission must be enabled for auto-approval.
+
+### Mode Switching
+
+{% image src="/docs/img/auto-approving-actions/auto-approving-actions-11.png" alt="Mode switching setting" width="800" caption="Mode switching settings" /%}
+
+**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
+
+{% image src="/docs/img/auto-approving-actions/auto-approving-actions-12.png" alt="Subtasks setting" width="800" caption="Subtasks auto-approval settings" /%}
+
+**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
+
+{% image src="/docs/img/auto-approving-actions/auto-approving-actions-13.png" alt="Command execution setting with whitelist interface" width="800" caption="Command execution settings with allowlist and denylist" /%}
+
+**Setting:** "Always approve allowed execute operations"
+
+**Description:** Automatically execute allowed terminal commands without requiring approval
+
+**Risk level:** High
+
+This setting allows terminal command execution with controls. While risky, the allowlist and denylist features limit what commands can run.
+
+- Allowlist specific command prefixes (recommended)
+- Never use `*` wildcard in production or with sensitive data
+- Consider security implications of each allowed command
+- Consider including potentially dangerous common commands in the deny list
+- Always verify commands that interact with external systems
+
+#### Allowed Commands
+
+**Setting:** "Command prefixes that can be auto-executed"
+
+Add command prefixes (e.g., `git`, `npm`, `ls`) that Kilo Code can run without asking. Use `*` to allow all commands (use with caution).
+
+**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
+
+#### Denied Commands
+
+**Setting:** "Command prefixes that are always blocked"
+
+Commands in this list will never run, even if `*` is in the allowed list. Use this to create exceptions for potentially dangerous commands.
+
+### Follow-Up Questions
+
+**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 Kilo Code proceed without manual intervention.
+
+**Visual countdown:** When enabled, a countdown timer appears on the first suggestion button in the chat interface, showing the remaining time before auto-selection. The timer displays seconds remaining (e.g., "3s") and counts down in real-time.
+
+**Timeout slider:** Use the slider to set the wait time (Range: 1-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 Kilo Code to continue working
+- Repetitive tasks where the default suggestions are usually correct
+- Testing workflows where interaction isn't critical
+
+### Update Todo List
+
+**Setting:** "Always approve todo list updates"
+
+**Description:** Automatically update the to-do list without requiring approval
+
+**Risk level:** Low
+
+This setting allows Kilo Code 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
+
+**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 Kilo Code to maintain a complete picture of project progress without constant approval requests.
+
+## YOLO Mode
+
+{% callout type="danger" %}
+**YOLO Mode (Risk: Maximum)**
+
+**"You Only Live Once"** mode enables _all_ auto-approve permissions at once using the master toggle. This gives Kilo Code complete autonomy to read files, write code, execute commands, and perform any operation without asking for permission.
+
+You can optionally enable an AI Safety Gatekeeper, which reviews every intended change in YOLO mode and intelligently approves or blocks actions before they execute. We suggest using a small, fast model such as OpenAI gpt-oss-safeguard-20b. When enabled, AI Safety Gatekeeper will incur additional costs, as well as additional latency.
+
+**When to use:**
+
+- Rapid prototyping in isolated environments
+- Trusted, low-stakes projects
+- When you want maximum AI autonomy
+
+**When NOT to use:**
+
+- Production code or sensitive projects
+- Working with important data
+- Any situation where mistakes could be costly
+
+This is the fastest way to work with Kilo Code, but also the riskiest. Use it only when you fully trust the AI and are prepared for the consequences.
+{% /callout %}
@@ -0,0 +1,275 @@
+# Auto Cleanup
+
+Auto Cleanup automatically manages your task history by removing old tasks to free up disk space and improve performance. Tasks are intelligently classified and retained based on their type and age, ensuring important work is preserved while temporary or experimental tasks are cleaned up.
+
+{% callout type="warning" %}
+Task deletion is permanent and cannot be undone. Deleted tasks are completely removed from disk, including all conversation history, checkpoints, and associated files.
+{% /callout %}
+
+## Overview
+
+As you work with Kilo Code, each task creates files containing conversation history, checkpoints, and other data. Over time, this accumulates and can consume significant disk space. Auto-Cleanup solves this by:
+
+- **Automatically removing old tasks** based on configurable retention periods
+- **Preserving important tasks** by classifying them into different types
+- **Protecting favorited tasks** from deletion
+- **Managing disk usage** without manual intervention
+
+{% callout type="info" title="Key Benefits" %}
+
+- **Free up disk space**: Automatically remove old task data
+- **Improve performance**: Reduce the size of task history
+- **Flexible control**: Configure different retention periods for different task types
+- **Safety first**: Favorited tasks can be protected from deletion
+- **Manual override**: Run cleanup manually whenever needed
+  {% /callout %}
+
+## How Auto-Cleanup Works
+
+Auto-Cleanup uses an intelligent classification system to determine how long each task should be retained:
+
+### Task Classification
+
+Every task is automatically classified into one of these categories:
+
+| Task Type      | Description                               | Default Retention                        |
+| -------------- | ----------------------------------------- | ---------------------------------------- |
+| **Favorited**  | Tasks you've marked as favorites          | Never deleted (or 90 days if configured) |
+| **Completed**  | Tasks that successfully finished          | 30 days                                  |
+| **Incomplete** | Tasks that were started but not completed | 7 days                                   |
+| **Regular**    | Default classification for other tasks    | 30 days                                  |
+
+#### Understanding Task Completion
+
+A task is considered "completed" when Kilo Code uses the [`attempt_completion`](/automate/tools/attempt-completion) tool to formally mark it as finished. Tasks without this completion marker are classified as incomplete, even if you consider them done. This distinction helps clean up abandoned or experimental tasks more aggressively.
+
+### Cleanup Process
+
+When Auto-Cleanup runs, it:
+
+1. **Scans all tasks** in your task history
+2. **Classifies each task** based on its properties and completion status
+3. **Checks retention periods** to determine eligibility for deletion
+4. **Protects active tasks** currently in use
+5. **Deletes eligible tasks** and their associated files
+6. **Reports results** including disk space freed
+
+## Configuration
+
+Access Auto-Cleanup settings through the Kilo Code settings panel:
+
+1. Click the gear icon ({% codicon name="gear" /%}) in Kilo Code
+2. Navigate to the **Auto-Cleanup** section (under Checkpoints)
+
+### Enable Auto-Cleanup
+
+{% image src="/docs/img/auto-cleanup/settings.png" alt="Auto-Cleanup settings panel" width="800" caption="Auto-Cleanup settings panel" /%}
+
+Check the **"Enable automatic task cleanup"** option to activate the feature. When enabled, tasks will be automatically removed based on your retention settings.
+
+### Retention Period Settings
+
+Configure how long different types of tasks are kept before cleanup:
+
+#### Default Retention Period
+
+```
+Default: 30 days
+Minimum: 1 day
+```
+
+Sets the base retention period for regular tasks that don't fall into other categories.
+
+#### Favorited Tasks
+
+**Never delete favorited tasks** (recommended)
+
+When enabled, favorited tasks are preserved indefinitely regardless of age. This is the safest option to prevent accidental deletion of important work.
+
+If disabled, you can set a custom retention period:
+
+```
+Default: 90 days
+Minimum: 1 day
+```
+
+To favorite a task, use the star icon in the task history panel.
+
+#### Completed Tasks
+
+```
+Default: 30 days
+Minimum: 1 day
+```
+
+Tasks successfully completed via the [`attempt_completion`](/automate/tools/attempt-completion) tool are retained for this period. These tasks typically represent finished work that may still be useful for reference.
+
+#### Incomplete Tasks
+
+```
+Default: 7 days
+Minimum: 1 day
+```
+
+Tasks without completion status are retained for a shorter period. This helps clean up experimental or abandoned tasks more quickly while still giving you time to review them.
+
+### Last Cleanup Display
+
+The settings show when the last cleanup operation ran, helping you understand the cleanup schedule.
+
+### Manual Cleanup
+
+Click the **"Run Cleanup Now"** button to immediately trigger a cleanup operation using your current settings. This is useful when:
+
+- You need to free up disk space urgently
+- You've changed retention settings and want them applied immediately
+- You want to preview what would be cleaned up (check the output)
+
+## Best Practices
+
+### Recommended Retention Periods
+
+**For Individual Developers:**
+
+- Default retention: 30 days
+- Completed tasks: 30 days
+- Incomplete tasks: 7 days
+- Favorited tasks: Never delete
+
+**For Experimentation:**
+
+- Default retention: 14 days
+- Completed tasks: 14 days
+- Incomplete tasks: 3 days
+- Favorited tasks: Never delete
+
+**For Limited Disk Space:**
+
+- Default retention: 14 days
+- Completed tasks: 14 days
+- Incomplete tasks: 3 days
+- Favorited tasks: 60 days
+
+### Protecting Important Work
+
+To ensure important tasks are never deleted:
+
+1. **Mark tasks as favorites** using the star icon in task history
+2. **Enable "Never delete favorited tasks"** in settings
+3. **Review cleanup results** periodically to ensure retention periods are appropriate
+
+### Balancing Disk Space and History
+
+Consider these factors when setting retention periods:
+
+- **Available disk space**: Shorter retention if space is limited
+- **Task frequency**: More tasks = shorter retention needed
+- **Reference needs**: Keep completed tasks longer if you often refer back
+- **Experimentation**: Shorter incomplete task retention for heavy experimentation
+
+## Troubleshooting
+
+### Tasks Not Being Cleaned Up
+
+**Issue**: Old tasks remain after cleanup runs
+
+**Solutions**:
+
+1. Verify Auto-Cleanup is enabled in settings
+2. Check retention periods - they may be too long
+3. Verify tasks are older than the retention period
+4. Check if tasks are favorited (they won't be deleted if "Never delete" is enabled)
+
+### Important Task Was Deleted
+
+**Issue**: A task you needed was removed
+
+**Prevention**:
+
+1. Always favorite important tasks before they age out
+2. Set longer retention periods for task types you reference frequently
+3. Consider enabling "Never delete favorited tasks"
+4. Export or backup critical task data before it ages out
+
+{% callout type="warning" %}
+Deleted tasks cannot be recovered. Always favorite important tasks or adjust retention periods to prevent accidental deletion.
+{% /callout %}
+
+### Cleanup Using Too Much Disk I/O
+
+**Issue**: Cleanup operation impacts system performance
+
+**Solutions**:
+
+1. Check the "Operation duration" in cleanup results
+2. If slow, consider reducing retention periods to clean fewer tasks at once
+3. Run manual cleanup during non-working hours
+4. Ensure adequate system resources during cleanup
+
+### Active Task Protection
+
+Auto-Cleanup automatically protects your currently active task from deletion, even if it meets the age criteria. This ensures you never lose work in progress during a cleanup operation.
+
+## Technical Details
+
+### What Gets Deleted
+
+When a task is deleted, the following are permanently removed:
+
+- Task directory and all contents
+- Conversation history and messages
+- Checkpoints (if enabled)
+- API request logs
+- Task metadata
+- Associated temporary files
+
+### Storage Location
+
+Task data is stored in your VS Code global storage location:
+
+- **macOS**: `~/Library/Application Support/Code/User/globalStorage/kilocode.kilo-code/`
+- **Windows**: `%APPDATA%\Code\User\globalStorage\kilocode.kilo-code\`
+- **Linux**: `~/.config/Code/User/globalStorage/kilocode.kilo-code/`
+
+## Privacy & Data Handling
+
+- **Local Operation**: All cleanup happens locally on your machine
+- **No Cloud Backup**: Deleted tasks are not backed up automatically
+- **Telemetry**: Anonymous usage statistics (tasks cleaned, disk space freed) are collected if telemetry is enabled
+- **No Content Sharing**: Task content, code, or personal information is never transmitted
+
+## Related Features
+
+- [**Checkpoints**](/code-with-ai/features/checkpoints): Version control for tasks that can be restored
+- [**Settings Management**](/getting-started/settings): Export/import settings including cleanup configuration
+- [**Task History**](/code-with-ai/agents/chat-interface): Managing and organizing your task history
+
+## Frequently Asked Questions
+
+### Does Auto-Cleanup run automatically?
+
+Yes, when enabled, Auto-Cleanup runs automatically based on the configured schedule. You can also trigger it manually using the "Run Cleanup Now" button.
+
+### Can I recover deleted tasks?
+
+No, task deletion is permanent. Always favorite important tasks or adjust retention periods to prevent accidental deletion.
+
+### Does cleanup affect my current task?
+
+No, the active task you're currently working on is automatically protected from deletion.
+
+### What happens to checkpoints when a task is deleted?
+
+All checkpoints associated with a deleted task are permanently removed along with the task data.
+
+### Can I temporarily disable cleanup?
+
+Yes, simply uncheck the "Enable automatic task cleanup" option in settings. Your configuration is preserved for when you enable it again.
+
+### Why are some old tasks not being deleted?
+
+Check if they are:
+
+1. Favorited with "Never delete favorited tasks" enabled
+2. Recently modified (even viewing a task may update its timestamp)
+3. Protected by a longer retention period based on their type
@@ -7,10 +7,9 @@ description: "Configure Kilo Code settings and preferences"

 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.
+You can find these options at the bottom of the Kilo Code settings page, accessible via the gear icon ({% codicon name="gear" /%}) 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.*
+{% image src="/docs/img/settings-management/settings-management.png" alt="Export, Import, and Reset buttons in Kilo Code settings" width="800" caption="Export, Import, and Reset buttons" /%}

 ## Export Settings

@@ -93,3 +92,19 @@ When enabled, Kilo Code will remind the model about the details of its current m
 **Default:** Disabled

 Learn more about [Custom Modes](/docs/customize/custom-modes) and how Power Steering can improve mode behavior.
+
+### File Read Auto-Truncate Threshold
+
+This setting controls the number of lines read from a file in one batch. To manage large files and reduce context/resource usage, adjust the `File read auto-truncate threshold` setting.
+
+**When to adjust:**
+
+- Working with very large files that consume too much context
+- Need to improve performance when reading large files
+- Want to reduce token usage for file operations
+
+**Trade-off:** Lower values can improve performance when working with very large files, but may require more read operations to access the full file content.
+
+**Default:** Set in Advanced Settings
+
+You can find this setting in the Kilo Code settings under 'Advanced Settings'.
@@ -0,0 +1,253 @@
+---
+title: "System Notifications"
+description: "Configure native OS notifications for Kilo Code"
+---
+
+# System Notifications
+
+System notifications are native operating system notifications that appear in your system's notification center or tray. Unlike VSCode's built-in notifications that only appear within the editor, system notifications are visible even when:
+
+- VSCode is minimized or in the background
+- You're working in other applications
+- Your screen is locked (depending on OS settings)
+- You're away from your computer
+
+Kilo Code uses system notifications to inform you about:
+
+- Task completion status
+- Important errors or warnings
+- Long-running operation updates
+- Critical system events
+
+## Supported Operating Systems
+
+Kilo Code's system notifications work on all major operating systems with different underlying technologies:
+
+| Operating System | Technology                      | Requirements                                 |
+| ---------------- | ------------------------------- | -------------------------------------------- |
+| **macOS**        | AppleScript + terminal-notifier | Built-in support, optional enhanced features |
+| **Windows**      | PowerShell + Windows Runtime    | PowerShell execution policy configuration    |
+| **Linux**        | notify-send                     | libnotify package installation               |
+
+## Platform-Specific Setup
+
+### macOS Setup
+
+macOS has the best built-in support for system notifications with two available methods:
+
+#### Method 1: Built-in AppleScript (Fallback)
+
+No additional setup required. Kilo Code uses macOS's built-in command to display notifications.
+
+#### Method 2: Enhanced with terminal-notifier (Recommended)
+
+For enhanced notifications with custom icons, install terminal-notifier:
+
+```bash
+# Install via Homebrew
+brew install terminal-notifier
+
+# Or install via npm
+npm install -g terminal-notifier
+```
+
+**How it works:** Kilo Code first attempts to use `terminal-notifier` and automatically falls back to AppleScript if it's not installed.
+
+### Windows Setup
+
+Windows notifications require PowerShell execution policy configuration to work properly.
+
+#### Step 1: Configure PowerShell Execution Policy
+
+Open PowerShell as Administrator and run:
+
+```powershell
+# Check current execution policy
+Get-ExecutionPolicy
+
+# Set execution policy to allow local scripts
+Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+#### Step 2: Verify Windows Runtime Access
+
+Windows notifications use the `Windows.UI.Notifications` API through PowerShell. This is available on:
+
+- ✅ Windows 10 (all versions)
+- ✅ Windows 11 (all versions)
+- ✅ Windows Server 2016 and later
+- ❌ Windows 8.1 and earlier (limited support)
+
+#### Execution Policy Options
+
+| Policy         | Description                                | Security Level | Recommended             |
+| -------------- | ------------------------------------------ | -------------- | ----------------------- |
+| `Restricted`   | No scripts allowed (default)               | Highest        | ❌ Blocks notifications |
+| `RemoteSigned` | Local scripts run, downloaded need signing | High           | ✅ **Recommended**      |
+| `Unrestricted` | All scripts run with warnings              | Medium         | ⚠️ Use with caution     |
+| `AllSigned`    | All scripts must be signed                 | Highest        | ❌ Too restrictive      |
+
+### Linux Setup
+
+Linux notifications require the `libnotify` package and `notify-send` command.
+
+#### Ubuntu/Debian Installation
+
+```bash
+# Install libnotify
+sudo apt update
+sudo apt install libnotify-bin
+
+# Verify installation
+which notify-send
+```
+
+#### Red Hat/CentOS/Fedora Installation
+
+```bash
+# RHEL/CentOS
+sudo yum install libnotify
+
+# Fedora
+sudo dnf install libnotify
+
+# Verify installation
+which notify-send
+```
+
+#### Arch Linux Installation
+
+```bash
+# Install libnotify
+sudo pacman -S libnotify
+
+# Verify installation
+which notify-send
+```
+
+#### Desktop Environment Requirements
+
+System notifications work best with these desktop environments:
+
+| Desktop Environment | Support Level   | Notes                                     |
+| ------------------- | --------------- | ----------------------------------------- |
+| **GNOME**           | ✅ Full support | Native notification center                |
+| **KDE Plasma**      | ✅ Full support | Native notification system                |
+| **XFCE**            | ✅ Good support | Requires notification daemon              |
+| **Unity**           | ✅ Full support | Ubuntu's notification system              |
+| **i3/Sway**         | ⚠️ Limited      | Requires manual notification daemon setup |
+| **Headless**        | ❌ No support   | No display server available               |
+
+#### Notification Daemon Setup (Advanced)
+
+For minimal window managers, you may need to start a notification daemon:
+
+```bash
+# Install and start dunst (lightweight notification daemon)
+sudo apt install dunst  # Ubuntu/Debian
+sudo pacman -S dunst    # Arch Linux
+
+# Start dunst manually
+dunst &
+
+# Or add to your window manager startup script
+echo "dunst &" >> ~/.xinitrc
+```
+
+## Verifying System Notifications
+
+### Test Commands by Platform
+
+#### macOS Test
+
+```bash
+# Test AppleScript method
+osascript -e 'display notification "Test message" with title "Test Title" sound name "Tink"'
+
+# Test terminal-notifier (if installed)
+terminal-notifier -message "Test message" -title "Test Title" -sound Tink
+```
+
+#### Windows Test
+
+```powershell
+# Test PowerShell notification
+$template = @"
+<toast>
+    <visual>
+        <binding template="ToastText02">
+            <text id="1">Test Title</text>
+            <text id="2">Test message</text>
+        </binding>
+    </visual>
+</toast>
+"@
+
+[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+[Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime] | Out-Null
+$xml = New-Object Windows.Data.Xml.Dom.XmlDocument
+$xml.LoadXml($template)
+$toast = [Windows.UI.Notifications.ToastNotification]::new($xml)
+[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier("Test App").Show($toast)
+```
+
+#### Linux Test
+
+```bash
+# Test notify-send
+notify-send "Test Title" "Test message"
+
+# Test with icon (optional)
+notify-send -i dialog-information "Test Title" "Test message"
+```
+
+## Troubleshooting
+
+### Common Issues and Solutions
+
+#### macOS Issues
+
+**Problem:** Notifications not appearing
+
+- **Solution 1:** Check System Preferences → Notifications → Terminal (or VSCode) → Allow notifications
+- **Solution 2:** Verify Do Not Disturb is disabled
+- **Solution 3:** Test with the manual commands above
+- **Solution 4:** Ensure terminal-notifier is properly installed: `brew install terminal-notifier`
+
+#### Windows Issues
+
+**Problem:** "Execution of scripts is disabled" error
+
+- **Solution:** Configure PowerShell execution policy as described in setup
+- **Command:** `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser`
+
+**Problem:** Notifications not appearing in Windows 11
+
+- **Solution 1:** Check Settings → System → Notifications → Allow notifications
+- **Solution 2:** Ensure Focus Assist is not blocking notifications
+- **Solution 3:** Verify Windows notification service is running
+
+**Problem:** PowerShell script errors
+
+- **Solution:** Update PowerShell to version 5.1 or later
+- **Check version:** `$PSVersionTable.PSVersion`
+
+#### Linux Issues
+
+**Problem:** `notify-send: command not found`
+
+- **Solution:** Install libnotify package for your distribution
+- **Ubuntu/Debian:** `sudo apt install libnotify-bin`
+- **RHEL/CentOS:** `sudo yum install libnotify`
+- **Arch:** `sudo pacman -S libnotify`
+
+**Problem:** Notifications not appearing in minimal window managers
+
+- **Solution:** Install and configure a notification daemon like dunst
+- **Install:** `sudo apt install dunst` (Ubuntu/Debian)
+- **Start:** `dunst &`
+
+**Problem:** Permission denied errors
+
+- **Solution:** Ensure your user has access to the display server
+- **Check:** `echo $DISPLAY` should return something like `:0`
@@ -1,7 +1,31 @@
 module.exports = [
+	{
+		source: "/docs/features/system-notifications",
+		destination: "/docs/getting-started/settings/system-notifications",
+		basePath: false,
+		permanent: true,
+	},
+	{
+		source: "/docs/features/auto-approving-actions",
+		destination: "/docs/getting-started/settings/auto-approving-actions",
+		basePath: false,
+		permanent: true,
+	},
+	{
+		source: "/docs/features/suggested-responses",
+		destination: "/docs/code-with-ai/agents/chat-interface#suggested-responses",
+		basePath: false,
+		permanent: true,
+	},
 	// ============================================
 	// GET STARTED
 	// ============================================
+	{
+		source: "/docs/basic-usage/byok",
+		destination: "/docs/getting-started/byok",
+		basePath: false,
+		permanent: true,
+	},
 	{
 		source: "/docs/getting-started/setting-up",
 		destination: "/docs/getting-started/setup-authentication",