Merge branch 'main' into fireworks-pull-1

.changeset/abbreviate-large-pasted-text.md

@@ -0,0 +1,5 @@
+---
+"@kilocode/cli": minor
+---
+
+Abbreviate large pasted text in CLI input as `[Pasted text #N +X lines]` to prevent input field overflow when pasting logs or large code blocks

.changeset/agent-manager-dropdown-ux.md

@@ -1,5 +0,0 @@
----
-"@roo-code/vscode-webview": patch
----
-
-Improve Agent Manager run mode dropdown UX: close dropdown when clicking outside, add tooltip on hover

.changeset/agent-manager-question-support.md

@@ -1,5 +0,0 @@
----
-"@roo-code/vscode-webview": patch
----
-
-Add follow-up question answer buttons to Agent Manager, allowing users to click suggestion buttons to respond to agent questions

.changeset/checkpoint-enable-disable.md

@@ -0,0 +1,5 @@
+---
+"@kilocode/cli": patch
+---
+
+Add `/checkpoint enable` and `/checkpoint disable` subcommands to toggle checkpoint creation and save disk space

.changeset/cli-custom-modes-error-message.md

@@ -0,0 +1,5 @@
+---
+"@kilocode/cli": patch
+---
+
+fix(cli): improve error message for custom mode not found

.changeset/cli-max-concurrent-file-reads.md

@@ -0,0 +1,5 @@
+---
+"@kilocode/cli": patch
+---
+
+Add maxConcurrentFileReads configuration support to CLI with documentation

.changeset/cli-models-api-command.md

@@ -0,0 +1,5 @@
+---
+"@kilocode/cli": minor
+---
+
+Add `kilocode models --json` command to expose available models as JSON for programmatic use

.changeset/cli-nano-gpt-router-models.md

@@ -0,0 +1,5 @@
+---
+"@kilocode/cli": patch
+---
+
+Fix CLI `/model list` returning "No models available" for nano-gpt provider

.changeset/colorblind-theme-support.md

@@ -0,0 +1,7 @@
+---
+"@kilocode/cli": minor
+---
+
+Add colorblind theme support to CLI
+
+- Colorblind-friendly theme with high contrast colors for accessibility

.changeset/delete-file-cli-display.md

@@ -0,0 +1,5 @@
+---
+"@kilocode/cli": patch
+---
+
+Add proper display for deleteFile tool in CLI instead of showing "Unknown tool: deleteFile"

.changeset/fix-approval-number-hotkeys.md

@@ -0,0 +1,5 @@
+---
+"@kilocode/cli": patch
+---
+
+Fix number key hotkeys (1, 2, 3) not working in command approval menu

.changeset/fix-chat-autocomplete-focus.md

@@ -0,0 +1,5 @@
+---
+"kilo-code": patch
+---
+
+Fix chat autocomplete to only show suggestions when textarea has focus, text hasn't changed, and clear suggestions on paste

.changeset/fix-cli-rate-limit-hang.md

@@ -0,0 +1,5 @@
+---
+"@kilocode/cli": patch
+---
+
+Fix CLI hanging on rate limit errors in autonomous mode by enabling auto-retry for API failures

.changeset/full-eagles-brush.md

@@ -0,0 +1,6 @@
+---
+"@kilocode/cli": patch
+"kilo-code": patch
+---
+
+fix: use correct api url for some endpoints

.changeset/good-tools-accept.md

@@ -0,0 +1,88 @@
+---
+"kilo-code": minor
+---
+
+Include changes from Roo Code v3.36.7-v3.38.3
+
+- Feat: Add option in Context settings to recursively load `.kilocode/rules` and `AGENTS.md` from subdirectories (PR #10446 by @mrubens)
+- Fix: Stop frequent Claude Code sign-ins by hardening OAuth refresh token handling (PR #10410 by @hannesrudolph)
+- Fix: Add `maxConcurrentFileReads` limit to native `read_file` tool schema (PR #10449 by @app/roomote)
+- Fix: Add type check for `lastMessage.text` in TTS useEffect to prevent runtime errors (PR #10431 by @app/roomote)
+- Align skills system with Agent Skills specification (PR #10409 by @hannesrudolph)
+- Prevent write_to_file from creating files at truncated paths (PR #10415 by @mrubens and @daniel-lxs)
+- Fix rate limit wait display (PR #10389 by @hannesrudolph)
+- Remove human-relay provider (PR #10388 by @hannesrudolph)
+- Fix: Flush pending tool results before condensing context (PR #10379 by @daniel-lxs)
+- Fix: Revert mergeToolResultText for OpenAI-compatible providers (PR #10381 by @hannesrudolph)
+- Fix: Enforce maxConcurrentFileReads limit in read_file tool (PR #10363 by @roomote)
+- Fix: Improve feedback message when read_file is used on a directory (PR #10371 by @roomote)
+- Fix: Handle custom tool use similarly to MCP tools for IPC schema purposes (PR #10364 by @jr)
+- Add support for npm packages and .env files to custom tools, allowing custom tools to import dependencies and access environment variables (PR #10336 by @cte)
+- Remove simpleReadFileTool feature, streamlining the file reading experience (PR #10254 by @app/roomote)
+- Remove OpenRouter Transforms feature (PR #10341 by @app/roomote)
+- Fix: Send native tool definitions by default for OpenAI to ensure proper tool usage (PR #10314 by @hannesrudolph)
+- Fix: Preserve reasoning_details shape to prevent malformed responses when processing model output (PR #10313 by @hannesrudolph)
+- Fix: Drain queued messages while waiting for ask to prevent message loss (PR #10315 by @hannesrudolph)
+- Feat: Add grace retry for empty assistant messages to improve reliability (PR #10297 by @hannesrudolph)
+- Feat: Enable mergeToolResultText for all OpenAI-compatible providers for better tool result handling (PR #10299 by @hannesrudolph)
+- Feat: Strengthen native tool-use guidance in prompts for improved model behavior (PR #10311 by @hannesrudolph)
+- Add MiniMax M2.1 and improve environment_details handling for Minimax thinking models (PR #10284 by @hannesrudolph)
+- Add GLM-4.7 model with thinking mode support for Zai provider (PR #10282 by @hannesrudolph)
+- Add experimental custom tool calling - define custom tools that integrate seamlessly with your AI workflow (PR #10083 by @cte)
+- Deprecate XML tool protocol selection and force native tool format for new tasks (PR #10281 by @daniel-lxs)
+- Fix: Emit tool_call_end events in OpenAI handler when streaming ends (#10275 by @torxeon, PR #10280 by @daniel-lxs)
+- Fix: Emit tool_call_end events in BaseOpenAiCompatibleProvider (PR #10293 by @hannesrudolph)
+- Fix: Disable strict mode for MCP tools to preserve optional parameters (PR #10220 by @daniel-lxs)
+- Fix: Move array-specific properties into anyOf variant in normalizeToolSchema (PR #10276 by @daniel-lxs)
+- Fix: Add graceful fallback for model parsing in Chutes provider (PR #10279 by @hannesrudolph)
+- Fix: Enable Requesty refresh models with credentials (PR #10273 by @daniel-lxs)
+- Fix: Improve reasoning_details accumulation and serialization (PR #10285 by @hannesrudolph)
+- Fix: Preserve reasoning_content in condense summary for DeepSeek-reasoner (PR #10292 by @hannesrudolph)
+- Refactor Zai provider to merge environment_details into tool result instead of system message (PR #10289 by @hannesrudolph)
+- Remove parallel_tool_calls parameter from litellm provider (PR #10274 by @roomote)
+- Fix: Normalize tool schemas for VS Code LM API to resolve error 400 when using VS Code Language Model API providers (PR #10221 by @hannesrudolph)
+- Add 1M context window beta support for Claude Sonnet 4 on Vertex AI, enabling significantly larger context for complex tasks (PR #10209 by @hannesrudolph)
+- Add native tool call defaults for OpenAI-compatible providers, expanding native function calling across more configurations (PR #10213 by @hannesrudolph)
+- Enable native tool calls for Requesty provider (PR #10211 by @daniel-lxs)
+- Improve API error handling and visibility with clearer error messages and better user feedback (PR #10204 by @brunobergher)
+- Add downloadable error diagnostics from chat errors, making it easier to troubleshoot and report issues (PR #10188 by @brunobergher)
+- Fix refresh models button not properly flushing the cache, ensuring model lists update correctly (#9682 by @tl-hbk, PR #9870 by @pdecat)
+- Fix additionalProperties handling for strict mode compatibility, resolving schema validation issues with certain providers (PR #10210 by @daniel-lxs)
+- Add native tool calling support for Claude models on Vertex AI, enabling more efficient and reliable tool interactions (PR #10197 by @hannesrudolph)
+- Fix JSON Schema format value stripping for OpenAI compatibility, resolving issues with unsupported format values (PR #10198 by @daniel-lxs)
+- Improve "no tools used" error handling with graceful retry mechanism for better reliability when tools fail to execute (PR #10196 by @hannesrudolph)
+- Change default tool protocol from XML to native for improved reliability and performance (PR #10186 by @mrubens)
+- Add native tool support for VS Code Language Model API providers (PR #10191 by @daniel-lxs)
+- Lock task tool protocol for consistent task resumption, ensuring tasks resume with the same protocol they started with (PR #10192 by @daniel-lxs)
+- Replace edit_file tool alias with actual edit_file tool for improved diff editing capabilities (PR #9983 by @hannesrudolph)
+- Fix LiteLLM router models by merging default model info for native tool calling support (PR #10187 by @daniel-lxs)
+- Fix: Add userAgentAppId to Bedrock embedder for code indexing (#10165 by @jackrein, PR #10166 by @roomote)
+- Update OpenAI and Gemini tool preferences for improved model behavior (PR #10170 by @hannesrudolph)
+- Add support for Claude Code Provider native tool calling, improving tool execution performance and reliability (PR #10077 by @hannesrudolph)
+- Enable native tool calling by default for Z.ai models for better model compatibility (PR #10158 by @app/roomote)
+- Enable native tools by default for OpenAI compatible provider to improve tool calling support (PR #10159 by @daniel-lxs)
+- Fix: Normalize MCP tool schemas for Bedrock and OpenAI strict mode to ensure proper tool compatibility (PR #10148 by @daniel-lxs)
+- Fix: Remove dots and colons from MCP tool names for Bedrock compatibility (PR #10152 by @daniel-lxs)
+- Fix: Convert tool_result to XML text when native tools disabled for Bedrock (PR #10155 by @daniel-lxs)
+- Fix: Support AWS GovCloud and China region ARNs in Bedrock provider for expanded regional support (PR #10157 by @app/roomote)
+- Implement interleaved thinking mode for DeepSeek Reasoner, enabling streaming reasoning output (PR #9969 by @hannesrudolph)
+- Fix: Preserve reasoning_content during tool call sequences in DeepSeek (PR #10141 by @hannesrudolph)
+- Fix: Correct token counting for context truncation display (PR #9961 by @hannesrudolph)
+- Fix: Normalize tool call IDs for cross-provider compatibility via OpenRouter, ensuring consistent handling across different AI providers (PR #10102 by @daniel-lxs)
+- Fix: Add additionalProperties: false to nested MCP tool schemas, improving schema validation and preventing unexpected properties (PR #10109 by @daniel-lxs)
+- Fix: Validate tool_result IDs in delegation resume flow, preventing errors when resuming delegated tasks (PR #10135 by @daniel-lxs)
+- Feat: Add full error details to streaming failure dialog, providing more comprehensive information for debugging streaming issues (PR #10131 by @roomote)
+- Implement incremental token-budgeted file reading for smarter, more efficient file content retrieval (PR #10052 by @jr)
+- Enable native tools by default for multiple providers including OpenAI, Azure, Google, Vertex, and more (PR #10059 by @daniel-lxs)
+- Enable native tools by default for Anthropic and add telemetry tracking for tool format usage (PR #10021 by @daniel-lxs)
+- Fix: Prevent race condition from deleting wrong API messages during streaming (PR #10113 by @hannesrudolph)
+- Fix: Prevent duplicate MCP tools error by deduplicating servers at source (PR #10096 by @daniel-lxs)
+- Remove strict ARN validation for Bedrock custom ARN users allowing more flexibility (#10108 by @wisestmumbler, PR #10110 by @roomote)
+- Add metadata to error details dialog for improved debugging (PR #10050 by @roomote)
+- Remove description from Bedrock service tiers for cleaner UI (PR #10118 by @mrubens)
+- Improve tool configuration for OpenAI models in OpenRouter (PR #10082 by @hannesrudolph)
+- Capture more detailed provider-specific error information from OpenRouter for better debugging (PR #10073 by @jr)
+- Add Amazon Nova 2 Lite model to Bedrock provider (#9802 by @Smartsheet-JB-Brown, PR #9830 by @roomote)
+- Add AWS Bedrock service tier support (#9874 by @Smartsheet-JB-Brown, PR #9955 by @roomote)
+- Remove auto-approve toggles for to-do and retry actions to simplify the approval workflow (PR #10062 by @hannesrudolph)
+- Move isToolAllowedForMode out of shared directory for better code organization (PR #10089 by @cte)

.changeset/markdown-autocomplete-filter.md

@@ -0,0 +1,5 @@
+---
+"kilo-code": patch
+---
+
+Minor improvement to markdown autocomplete suggestions

.changeset/wild-lobsters-shake.md

@@ -0,0 +1,5 @@
+---
+"kilo-code": patch
+---
+
+fix: configure husky hooks for reliable execution

.github/dependabot.yml

@@ -5,7 +5,12 @@
 
 version: 2
 updates:
-  - package-ecosystem: "npm" # See documentation for possible values
-    directory: "/" # Location of package manifests
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "npm"
+    directory: "/cli"
     schedule:
       interval: "weekly"

.github/workflows/code-qa.yml

@@ -174,6 +174,10 @@ jobs:
                   check-latest: false
               env:
                   GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+            - name: Setup Gradle
+              uses: gradle/actions/setup-gradle@v4
+              with:
+                  cache-read-only: ${{ github.ref != 'refs/heads/main' }}
             - name: Install system dependencies
               run: |
                   sudo apt-get update

.github/workflows/marketplace-publish.yml

@@ -189,6 +189,10 @@ jobs:
                   java-version: "21"
                   check-latest: false
                   token: ${{ secrets.GITHUB_TOKEN }}
+            - name: Setup Gradle
+              uses: gradle/actions/setup-gradle@v4
+              with:
+                  cache-read-only: false
             - name: Install system dependencies
               run: |
                   sudo apt-get update

.gitignore

@@ -70,4 +70,4 @@ qdrant_storage/
 # Act Secret Files
 .secrets
 # Architect plans
-plans/
+./plans/

.husky/pre-commit

@@ -1,3 +1,11 @@
+#!/usr/bin/env sh
+# Add node_modules/.bin to PATH for local binaries
+# Use git to find the repository root reliably
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "$(dirname -- "$0")/../..")"
+if [ -d "$REPO_ROOT/node_modules/.bin" ]; then
+    export PATH="$REPO_ROOT/node_modules/.bin:$PATH"
+fi
+
 branch="$(git rev-parse --abbrev-ref HEAD)"
 
 if [ "$branch" = "main" ]; then

.husky/pre-push

@@ -1,3 +1,11 @@
+#!/usr/bin/env sh
+# Add node_modules/.bin to PATH for local binaries
+# Use git to find the repository root reliably
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "$(dirname -- "$0")/../..")"
+if [ -d "$REPO_ROOT/node_modules/.bin" ]; then
+    export PATH="$REPO_ROOT/node_modules/.bin:$PATH"
+fi
+
 branch="$(git rev-parse --abbrev-ref HEAD)"
 
 if [ "$branch" = "main" ]; then

.roo/rules-translate/AGENTS.md → .kilocode/skills/translation/SKILL.md

@@ -1,17 +1,13 @@
-# AGENTS.md
-
-This file provides guidance to agents when working with code in this repository in Translate mode.
-
-## Workflow
-
-This workflow requires Orchestrator mode.
+---
+name: translation
+description: Guidelines for translating and localizing the Kilo Code extension, including language-specific rules for German, Simplified Chinese, and Traditional Chinese.
+---
 
-Execute `node scripts/find-missing-translations.js` in Code mode to find all missing translations.
+# Translation Guidelines
 
-For each language that is missing translations:
+This file provides guidance to agents when working with translations in this repository.
 
-- For each JSON file that is missing translations:
-    - Start a separate subtask in Translate mode for this language and JSON file to add the missing translations. Do not try to process mutliple languages or JSON files in one subtask.
+For the translation workflow, use the `/add-missing-translations` command or see `.kilocode/workflows/add-missing-translations.md`.
 
 ---
 
@@ -311,42 +307,13 @@ For each language that is missing translations:
 
 ### Common Patterns
 
-```markdown
-<<<<<<< BEFORE
-"dragFiles": "按住shift拖动文件"
-=======
-"dragFiles": "Shift+拖拽文件"
-
-> > > > > > > AFTER
-
-<<<<<<< BEFORE
-"description": "启用后，Kilo Code 将能够与 MCP 服务器交互以获取高级功能。"
-=======
-"description": "启用后 Kilo Code 可与 MCP 服务交互获取高级功能。"
-
-> > > > > > > AFTER
-
-<<<<<<< BEFORE
-"cannotUndo": "此操作无法撤消。"
-=======
-"cannotUndo": "此操作不可逆。"
-
-> > > > > > > AFTER
-
-<<<<<<< BEFORE
-"hold shift to drag in files" → "按住shift拖动文件"
-=======
-"hold shift to drag in files" → "Shift+拖拽文件"
-
-> > > > > > > AFTER
-
-<<<<<<< BEFORE
-"Double click to edit" → "双击进行编辑"
-=======
-"Double click to edit" → "双击编辑"
-
-> > > > > > > AFTER
-```
+| Original                        | Avoid                                                         | Preferred                                            |
+| ------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------- |
+| `"dragFiles"`                   | `"按住shift拖动文件"`                                         | `"Shift+拖拽文件"`                                   |
+| `"description"`                 | `"启用后，Kilo Code 将能够与 MCP 服务器交互以获取高级功能。"` | `"启用后 Kilo Code 可与 MCP 服务交互获取高级功能。"` |
+| `"cannotUndo"`                  | `"此操作无法撤消。"`                                          | `"此操作不可逆。"`                                   |
+| `"hold shift to drag in files"` | `"按住shift拖动文件"`                                         | `"Shift+拖拽文件"`                                   |
+| `"Double click to edit"`        | `"双击进行编辑"`                                              | `"双击编辑"`                                         |
 
 ### Common Pitfalls
 

.kilocode/workflows/add-missing-translations.md

@@ -0,0 +1,22 @@
+# Add missing translations
+
+This workflow requires Orchestrator mode.
+
+Execute `node scripts/find-missing-translations.js` in Code mode to find all missing translations.
+
+For each language that is missing translations:
+
+- For each JSON file that is missing translations:
+    - Start a separate subtask in Translate mode for this language and JSON file to add the missing translations. Do not try to process multiple languages or JSON files in one subtask.
+
+## Translation Guidelines
+
+When translating, follow these key rules:
+
+1. **Supported Languages**: ar, ca, cs, de, en, es, fr, hi, id, it, ja, ko, nl, pl, pt-BR, ru, th, tr, uk, vi, zh-CN, zh-TW
+2. **Voice**: Always use informal speech (e.g., "du" not "Sie" in German)
+3. **Technical Terms**: Don't translate "token", "API", "prompt" and domain-specific technical terms
+4. **Placeholders**: Keep `{{variable}}` placeholders exactly as in the English source
+5. **Validation**: Run `node scripts/find-missing-translations.js` to validate changes
+
+For comprehensive translation guidelines including language-specific rules, see `.kilocode/skills/translation/SKILL.md`.

.vscode/launch.json

@@ -16,7 +16,8 @@
 			"preLaunchTask": "${defaultBuildTask}",
 			"env": {
 				"NODE_ENV": "development",
-				"VSCODE_DEBUG_MODE": "true"
+				"VSCODE_DEBUG_MODE": "true",
+				"KILOCODE_DEV_CLI_PATH": "${workspaceFolder}/cli/dist/index.js"
 			},
 			"resolveSourceMapLocations": ["${workspaceFolder}/**", "!**/node_modules/**"],
 			"presentation": {
@@ -40,7 +41,8 @@
 			"preLaunchTask": "${defaultBuildTask}",
 			"env": {
 				"NODE_ENV": "development",
-				"VSCODE_DEBUG_MODE": "true"
+				"VSCODE_DEBUG_MODE": "true",
+				"KILOCODE_DEV_CLI_PATH": "${workspaceFolder}/cli/dist/index.js"
 			},
 			"resolveSourceMapLocations": ["${workspaceFolder}/**", "!**/node_modules/**"],
 			"presentation": { "hidden": false, "group": "tasks", "order": 1 }
@@ -57,6 +59,7 @@
 			"env": {
 				"NODE_ENV": "development",
 				"VSCODE_DEBUG_MODE": "true",
+				"KILOCODE_DEV_CLI_PATH": "${workspaceFolder}/cli/dist/index.js",
 				"KILOCODE_BACKEND_BASE_URL": "${input:kilocodeBackendBaseUrl}"
 			},
 			"resolveSourceMapLocations": ["${workspaceFolder}/**", "!**/node_modules/**"],

.vscode/tasks.json

@@ -5,7 +5,7 @@
 	"tasks": [
 		{
 			"label": "watch",
-			"dependsOn": ["watch:pnpm", "watch:webview", "watch:bundle", "watch:tsc"],
+			"dependsOn": ["watch:pnpm", "watch:webview", "watch:bundle", "watch:tsc", "watch:cli"],
 			"presentation": {
 				"reveal": "never"
 			},
@@ -34,10 +34,10 @@
 				"--exec",
 				"pnpm install"
 			],
-			"group": "none",
+			"group": "build",
 			"isBackground": true,
 			"presentation": {
-				"group": "none",
+				"group": "watch:core",
 				"reveal": "always"
 			},
 			"problemMatcher": {
@@ -66,7 +66,7 @@
 			},
 			"isBackground": true,
 			"presentation": {
-				"group": "watch",
+				"group": "watch:core",
 				"reveal": "always"
 			}
 		},
@@ -89,7 +89,7 @@
 			},
 			"isBackground": true,
 			"presentation": {
-				"group": "watch",
+				"group": "watch:core",
 				"reveal": "always"
 			}
 		},
@@ -98,11 +98,66 @@
 			"dependsOn": ["watch:pnpm"],
 			"type": "shell",
 			"command": "npx turbo watch:tsc",
-			"group": "none",
+			"group": "build",
 			"problemMatcher": "$tsc-watch",
 			"isBackground": true,
 			"presentation": {
-				"group": "none",
+				"group": "watch:core",
+				"reveal": "always"
+			}
+		},
+		{
+			"label": "watch:cli:setup",
+			"dependsOn": ["watch:pnpm"],
+			"type": "shell",
+			"command": "node -e \"require('fs').existsSync('cli/dist/node_modules') || process.exit(1)\" || pnpm --filter @kilocode/cli dev:setup",
+			"group": "build",
+			"presentation": {
+				"group": "watch:cli",
+				"reveal": "silent"
+			},
+			"problemMatcher": []
+		},
+		{
+			"label": "watch:cli:deps",
+			"dependsOn": ["watch:cli:setup"],
+			"type": "shell",
+			"command": "npx nodemon --watch cli/package.dist.json --exec \"pnpm --filter @kilocode/cli deps:install\"",
+			"group": "build",
+			"isBackground": true,
+			"presentation": {
+				"group": "watch:cli",
+				"reveal": "silent"
+			},
+			"problemMatcher": {
+				"pattern": { "regexp": "^$" },
+				"background": {
+					"activeOnStart": true,
+					"beginsPattern": "\\[nodemon\\] starting",
+					"endsPattern": "\\[nodemon\\] clean exit - waiting for changes before restart"
+				}
+			}
+		},
+		{
+			"label": "watch:cli",
+			"dependsOn": ["watch:cli:setup", "watch:cli:deps"],
+			"type": "shell",
+			"command": "pnpm --filter @kilocode/cli dev",
+			"group": "build",
+			"problemMatcher": {
+				"owner": "esbuild",
+				"pattern": {
+					"regexp": "^$"
+				},
+				"background": {
+					"activeOnStart": true,
+					"beginsPattern": "esbuild-problem-matcher#onStart",
+					"endsPattern": "esbuild-problem-matcher#onEnd"
+				}
+			},
+			"isBackground": true,
+			"presentation": {
+				"group": "watch:cli",
 				"reveal": "always"
 			}
 		},

AGENTS.md

@@ -2,11 +2,110 @@
 
 Kilo Code is an open source AI coding agent for VS Code that generates code from natural language, automates tasks, and supports 500+ AI models.
 
-## Mode-Specific Rules
+## Project Structure
 
-For mode-specific guidance, see the following files:
+This is a pnpm monorepo using Turbo for task orchestration:
 
-- **Translate mode**: `.roo/rules-translate/AGENTS.md` - Translation and localization guidelines
+- **`src/`** - VSCode extension (core logic, API providers, tools)
+- **`webview-ui/`** - React frontend (chat UI, settings)
+- **`cli/`** - Standalone CLI package
+- **`packages/`** - Shared packages (`types`, `ipc`, `telemetry`, `cloud`)
+- **`jetbrains/`** - JetBrains plugin (Kotlin + Node.js host)
+- **`apps/`** - E2E tests, Storybook, docs
+
+Key source directories:
+
+- `src/api/providers/` - AI provider implementations (50+ providers)
+- `src/core/tools/` - Tool implementations (ReadFile, ApplyDiff, ExecuteCommand, etc.)
+- `src/services/` - Services (MCP, browser, checkpoints, code-index)
+
+## Build Commands
+
+```bash
+pnpm install          # Install all dependencies
+pnpm build            # Build extension (.vsix)
+pnpm lint             # Run ESLint
+pnpm check-types      # TypeScript type checking
+```
+
+## Skills
+
+- **Translation**: `.kilocode/skills/translation/SKILL.md` - Translation and localization guidelines
+
+## Workflows
+
+- **Add Missing Translations**: `.kilocode/workflows/add-missing-translations.md` - Run `/add-missing-translations` to find and fix missing translations
+
+## Changesets
+
+Each PR requires a changeset unless it's documentation-only or internal tooling. Create one with:
+
+```bash
+pnpm changeset
+```
+
+Format (in `.changeset/<random-name>.md`):
+
+```md
+---
+"kilo-code": patch
+---
+
+Brief description of the change
+```
+
+- Use `patch` for fixes, `minor` for features, `major` for breaking changes
+- For CLI changes, use `"@kilocode/cli": patch` instead
+
+Keep changesets concise but well-written as they become part of release notes.
+
+## Fork Merge Process
+
+Kilo Code is a fork of [Roo Code](https://github.com/RooVetGit/Roo-Code). We periodically merge upstream changes using scripts in `scripts/kilocode/`.
+
+## kilocode_change Markers
+
+To minimize merge conflicts when syncing with upstream, mark Kilo Code-specific changes in shared code with `kilocode_change` comments.
+
+**Single line:**
+
+```typescript
+const value = 42 // kilocode_change
+```
+
+**Multi-line:**
+
+```typescript
+// kilocode_change start
+const foo = 1
+const bar = 2
+// kilocode_change end
+```
+
+**New files:**
+
+```typescript
+// kilocode_change - new file
+```
+
+### When markers are NOT needed
+
+Code in these directories is Kilo Code-specific and doesn't need markers:
+
+- `cli/` - CLI package
+- `jetbrains/` - JetBrains plugin
+- Any path containing `kilocode` in filename or directory name
+- `src/services/ghost/` - Ghost service
+
+### When markers ARE needed
+
+All modifications to core extension code (files that exist in upstream Roo Code) require markers:
+
+- `src/` (except Kilo-specific subdirectories listed above)
+- `webview-ui/`
+- `packages/` (shared packages)
+
+Keep changes to core extension code minimal to reduce merge conflicts during upstream syncs.
 
 ## Code Quality Rules
 

CHANGELOG.md

@@ -1,5 +1,169 @@
 # kilo-code
 
+## 4.145.0
+
+### Minor Changes
+
+- [#4955](https://github.com/Kilo-Org/kilocode/pull/4955) [`8789f84`](https://github.com/Kilo-Org/kilocode/commit/8789f84e7d652185fce1767dcc29893080c7da87) Thanks [@iscekic](https://github.com/iscekic)! - add /condense and /compact commands
+
+### Patch Changes
+
+- [#4876](https://github.com/Kilo-Org/kilocode/pull/4876) [`7010f60`](https://github.com/Kilo-Org/kilocode/commit/7010f60bec33b5e1cdeff4a5bc2ad3c638e584cc) Thanks [@markijbema](https://github.com/markijbema)! - Autocomplete: Show entire suggestion when first line has no word characters
+
+- [#4183](https://github.com/Kilo-Org/kilocode/pull/4183) [`de30ffa`](https://github.com/Kilo-Org/kilocode/commit/de30ffa307c2bf0ad72eec67782b67725172f71f) Thanks [@sebastiand-cerebras](https://github.com/sebastiand-cerebras)! - fix(cerebras): use conservative max_tokens and add integration header
+
+    **Conservative max_tokens:**
+    Cerebras rate limiter estimates token consumption using max_completion_tokens upfront rather than actual usage. When agentic tools automatically set this to the model maximum (e.g., 64K), users exhaust their quota prematurely and get rate-limited despite minimal actual token consumption.
+
+    This fix uses a conservative default of 8K tokens instead of the model maximum. This is sufficient for most agentic tool use while preserving rate limit headroom.
+
+    **Integration header:**
+    Added `X-Cerebras-3rd-Party-Integration: kilocode` header to all Cerebras API requests for tracking and analytics.
+
+- [#4856](https://github.com/Kilo-Org/kilocode/pull/4856) [`100462e`](https://github.com/Kilo-Org/kilocode/commit/100462e956f7f7799525ebddb7d10050435047da) Thanks [@markijbema](https://github.com/markijbema)! - Improve autocomplete tooltip messaging when there's no balance
+
+    When a user has a Kilo Code account with no credits, the autocomplete status bar now shows a helpful message explaining that they need to add credits to use autocomplete, rather than just showing a generic token error.
+
+- [#4793](https://github.com/Kilo-Org/kilocode/pull/4793) [`4fff873`](https://github.com/Kilo-Org/kilocode/commit/4fff873a4b28fa66afbcf837358bcd584665a8be) Thanks [@mcowger](https://github.com/mcowger)! - Restore various providers to modelCache endpoint to fix outdated entries.
+
+## 4.144.0
+
+### Minor Changes
+
+- [#4888](https://github.com/Kilo-Org/kilocode/pull/4888) [`334328d`](https://github.com/Kilo-Org/kilocode/commit/334328de5fa1825726b07be5d587550de2c52d91) Thanks [@hassoncs](https://github.com/hassoncs)! - Show notifications when skills are added or removed from the project or global config
+
+### Patch Changes
+
+- [#4880](https://github.com/Kilo-Org/kilocode/pull/4880) [`909bca7`](https://github.com/Kilo-Org/kilocode/commit/909bca7665b91753c3a9fd0435b13f1c91bcb2f2) Thanks [@markijbema](https://github.com/markijbema)! - Fixed that some tasks in task history were red
+
+- [#4862](https://github.com/Kilo-Org/kilocode/pull/4862) [`10ce725`](https://github.com/Kilo-Org/kilocode/commit/10ce72547d207b4f03538ebb3dc525d5bd92727d) Thanks [@catrielmuller](https://github.com/catrielmuller)! - Add Kilo icon to editor toolbar for quick access to open Kilo from any context
+
+- [#4940](https://github.com/Kilo-Org/kilocode/pull/4940) [`9809864`](https://github.com/Kilo-Org/kilocode/commit/9809864ce51474c29b0db2635a19a92520a2f1f1) Thanks [@Drilmo](https://github.com/Drilmo)! - Add KILOCODE_DEV_CLI_PATH support for easier extension + CLI development workflow
+
+- [#4899](https://github.com/Kilo-Org/kilocode/pull/4899) [`7a58919`](https://github.com/Kilo-Org/kilocode/commit/7a58919c7e4e12e0c954031081e12745419bf8b9) Thanks [@marius-kilocode](https://github.com/marius-kilocode)! - Disable ask_followup_question tool when yolo mode is enabled to prevent the agent from asking itself questions and auto-answering them. Applied to:
+
+    - XML tool descriptions (system prompt)
+    - Native tool filtering
+    - Tool execution (returns error message if model still tries to use the tool from conversation history)
+
+- [#4863](https://github.com/Kilo-Org/kilocode/pull/4863) [`c65b798`](https://github.com/Kilo-Org/kilocode/commit/c65b798d99cd07bae2312d284663cd298a1b3f9e) Thanks [@hassoncs](https://github.com/hassoncs)! - Allow users to pick an input device for Speech-to-Text input
+
+- [#4892](https://github.com/Kilo-Org/kilocode/pull/4892) [`b37c944`](https://github.com/Kilo-Org/kilocode/commit/b37c944a8bea644660b6f2c4400d0b47cbdee979) Thanks [@marius-kilocode](https://github.com/marius-kilocode)! - Fix Agent Manager session disappearing immediately after starting due to gitUrl race condition
+
+- [#4898](https://github.com/Kilo-Org/kilocode/pull/4898) [`14b22b6`](https://github.com/Kilo-Org/kilocode/commit/14b22b6b9b947ceab6418d6e43962b5535adad1e) Thanks [@marius-kilocode](https://github.com/marius-kilocode)! - Fix session becoming non-interactable after clicking "Finish to Branch" button. The session now remains active so users can continue working after committing changes.
+
+- [#4835](https://github.com/Kilo-Org/kilocode/pull/4835) [`d55c093`](https://github.com/Kilo-Org/kilocode/commit/d55c093797c4a816a86ee5ee000f32a98f28199b) Thanks [@lambertjosh](https://github.com/lambertjosh)! - Add section headers to model selection dropdowns for "Recommended models" and "All models"
+
+- [#4891](https://github.com/Kilo-Org/kilocode/pull/4891) [`20f1a16`](https://github.com/Kilo-Org/kilocode/commit/20f1a16e2ed37bd79332bac8ea1358b01c4acbc0) Thanks [@kevinvandijk](https://github.com/kevinvandijk)! - Fix: prevent double display of MCP marketplace section in settings view
+
+- [#4873](https://github.com/Kilo-Org/kilocode/pull/4873) [`72ed20b`](https://github.com/Kilo-Org/kilocode/commit/72ed20b686f28062fb795beb44377a993bb40a7b) Thanks [@chrarnoldus](https://github.com/chrarnoldus)! - Improve support for VSCode's HTTP proxy settings
+
+- [#4901](https://github.com/Kilo-Org/kilocode/pull/4901) [`140bbf7`](https://github.com/Kilo-Org/kilocode/commit/140bbf7630a81591b18cc60a989690142e6b6039) Thanks [@marius-kilocode](https://github.com/marius-kilocode)! - Agent Manager: Parallel mode no longer modifies .gitignore
+
+    Worktree exclusion rules are now written to `.git/info/exclude` instead, avoiding changes to tracked files in your repository.
+
+## 4.143.2
+
+### Patch Changes
+
+- [#4833](https://github.com/Kilo-Org/kilocode/pull/4833) [`2c7cd08`](https://github.com/Kilo-Org/kilocode/commit/2c7cd084bf4707eedda61fed554cf15fcc8b065b) Thanks [@sebastiand-cerebras](https://github.com/sebastiand-cerebras)! - Add `zai-glm-4.7` to Cerebras models
+
+- [#4853](https://github.com/Kilo-Org/kilocode/pull/4853) [`435c879`](https://github.com/Kilo-Org/kilocode/commit/435c879a29d55b75f5f6ffe7bf14854630e085cb) Thanks [@chrarnoldus](https://github.com/chrarnoldus)! - Improved prompt caching when using Anthropic models on OpenRouter with native tool calling
+
+- [#4859](https://github.com/Kilo-Org/kilocode/pull/4859) [`35fb2ad`](https://github.com/Kilo-Org/kilocode/commit/35fb2adc65dfb1e71e28f7368f96765062c43579) Thanks [@marius-kilocode](https://github.com/marius-kilocode)! - Fix Architect mode unnecessarily switching to Code mode to edit markdown files
+
+- [#4829](https://github.com/Kilo-Org/kilocode/pull/4829) [`4e09e36`](https://github.com/Kilo-Org/kilocode/commit/4e09e36bba165a2ab6f5e07f71a420faa49ea3ec) Thanks [@marius-kilocode](https://github.com/marius-kilocode)! - Fix browser action results displaying raw base64 screenshot data as hexadecimal garbage
+
+## 4.143.1
+
+### Patch Changes
+
+- [#4832](https://github.com/Kilo-Org/kilocode/pull/4832) [`22a4ebf`](https://github.com/Kilo-Org/kilocode/commit/22a4ebfcd9f885b6ef9979dc6830226db9a4f397) Thanks [@Drilmo](https://github.com/Drilmo)! - Support Cmd+V for pasting images on macOS in VSCode terminal
+
+    - Detect empty bracketed paste (when clipboard contains image instead of text)
+    - Trigger clipboard image check on empty paste or paste timeout
+    - Add Cmd+V (meta key) support alongside Ctrl+V for image paste
+
+- [#3856](https://github.com/Kilo-Org/kilocode/pull/3856) [`91e0a17`](https://github.com/Kilo-Org/kilocode/commit/91e0a1788963b8be50c58881f11ded96516ab163) Thanks [@markijbema](https://github.com/markijbema)! - Faster autocomplete when using the Mistral provider
+
+- [#4839](https://github.com/Kilo-Org/kilocode/pull/4839) [`abaada6`](https://github.com/Kilo-Org/kilocode/commit/abaada6b7ced6d3f4e37e69441e722e453289b81) Thanks [@markijbema](https://github.com/markijbema)! - Enable autocomplete by default in the JetBrains extension
+
+- [#4831](https://github.com/Kilo-Org/kilocode/pull/4831) [`a9cbb2c`](https://github.com/Kilo-Org/kilocode/commit/a9cbb2cebd75e0c675dc3b55e7a1653ccb93921b) Thanks [@Drilmo](https://github.com/Drilmo)! - Fix paste truncation in VSCode terminal
+
+    - Prevent React StrictMode cleanup from interrupting paste operations
+    - Remove `completePaste()` and `clearBuffers()` from useEffect cleanup
+    - Paste buffer refs now persist across React re-mounts and flush properly when paste end marker is received
+
+- [#4847](https://github.com/Kilo-Org/kilocode/pull/4847) [`8ee812a`](https://github.com/Kilo-Org/kilocode/commit/8ee812a18da5da691bf76ee5c5d9d94cfb678f25) Thanks [@chrarnoldus](https://github.com/chrarnoldus)! - Disable structured outputs for Anthropic models, because the tool schema doesn't yet support it
+
+- [#4843](https://github.com/Kilo-Org/kilocode/pull/4843) [`0e3520a`](https://github.com/Kilo-Org/kilocode/commit/0e3520a0aa9a74f7a28af1f820558d2343fd4fba) Thanks [@markijbema](https://github.com/markijbema)! - Filter unhelpful suggestions in chat autocomplete
+
+## 4.143.0
+
+### Minor Changes
+
+- [#4643](https://github.com/Kilo-Org/kilocode/pull/4643) [`bf89c48`](https://github.com/Kilo-Org/kilocode/commit/bf89c4849342d9c0f3cfa335d65e98980d869e36) Thanks [@marius-kilocode](https://github.com/marius-kilocode)! - Migrate worktree creation from CLI to extension for parallel mode sessions
+
+### Patch Changes
+
+- [#4804](https://github.com/Kilo-Org/kilocode/pull/4804) [`e83c30a`](https://github.com/Kilo-Org/kilocode/commit/e83c30a4160309c45bcfedf60faad3eedff0549e) Thanks [@kiloconnect](https://github.com/apps/kiloconnect)! - Add comprehensive AGENTS.md documentation page to Agent Behavior section
+
+- [#4810](https://github.com/Kilo-Org/kilocode/pull/4810) [`2d8f5b4`](https://github.com/Kilo-Org/kilocode/commit/2d8f5b4f823750d22701d962ba27885b01f78acb) Thanks [@kiloconnect](https://github.com/apps/kiloconnect)! - Add `--append-system-prompt` CLI option to append custom instructions to the system prompt
+
+- [#4808](https://github.com/Kilo-Org/kilocode/pull/4808) [`3253a5f`](https://github.com/Kilo-Org/kilocode/commit/3253a5f0a9ef3db176b0cc027a9a0f246faa27e6) Thanks [@markijbema](https://github.com/markijbema)! - Rename and reorganize autocomplete settings to use more familiar terminology
+
+- [#4815](https://github.com/Kilo-Org/kilocode/pull/4815) [`1530050`](https://github.com/Kilo-Org/kilocode/commit/15300507c8febd2096282e97148e39a0bfda9e23) Thanks [@chrarnoldus](https://github.com/chrarnoldus)! - Allow null for tool arguments
+
+## 4.142.0
+
+### Minor Changes
+
+- [#4587](https://github.com/Kilo-Org/kilocode/pull/4587) [`d1c35c5`](https://github.com/Kilo-Org/kilocode/commit/d1c35c54c253b22a264ee4ce90fd25f5d93343da) Thanks [@hassoncs](https://github.com/hassoncs)! - Improve the initial setup experience for the speech-to-text feature by adding an inline setup tooltip
+
+### Patch Changes
+
+- [#4785](https://github.com/Kilo-Org/kilocode/pull/4785) [`acc529e`](https://github.com/Kilo-Org/kilocode/commit/acc529e884be601d635ad9e714a0f3b2a4e9b639) Thanks [@markijbema](https://github.com/markijbema)! - Removed the cmd-i (quick inline task) functionality, as cmd-k-a (add to context) is now equivalent
+
+- [#4765](https://github.com/Kilo-Org/kilocode/pull/4765) [`725b0bc`](https://github.com/Kilo-Org/kilocode/commit/725b0bc56d1262b9e847861db86a3609c40479d9) Thanks [@Drilmo](https://github.com/Drilmo)! - Fixed exit prompt showing "Cmd+C" instead of "Ctrl+C" on Mac. Ctrl+C is the universal terminal interrupt signal on all platforms.
+
+- [#4787](https://github.com/Kilo-Org/kilocode/pull/4787) [`84033fa`](https://github.com/Kilo-Org/kilocode/commit/84033fa3015a757b358cc4799308b8209646ec5e) Thanks [@markijbema](https://github.com/markijbema)! - Keep config screen in sync with whether chat autocomplete is enabled
+
+- [#4800](https://github.com/Kilo-Org/kilocode/pull/4800) [`c089dc2`](https://github.com/Kilo-Org/kilocode/commit/c089dc2351daefe7690adf1a3f01cc8b82a27409) Thanks [@hassoncs](https://github.com/hassoncs)! - Add fuzzy matching to / commands
+
+## 4.141.2
+
+### Patch Changes
+
+- [#4747](https://github.com/Kilo-Org/kilocode/pull/4747) [`e4f9e65`](https://github.com/Kilo-Org/kilocode/commit/e4f9e65e130d0ef34cbf110b64b44f2156d0a425) Thanks [@chrarnoldus](https://github.com/chrarnoldus)! - Fixed no checkpoint being created before a file is edited
+
+- [#4754](https://github.com/Kilo-Org/kilocode/pull/4754) [`d936b50`](https://github.com/Kilo-Org/kilocode/commit/d936b50f6c28592a910c83c52433eb59aa019cf5) Thanks [@keeganwitt](https://github.com/keeganwitt)! - Added ability to use Codestral for autocomplete from HuggingFace, LiteLLM, LM Studio and Ollama
+
+## 4.141.1
+
+### Patch Changes
+
+- [#4736](https://github.com/Kilo-Org/kilocode/pull/4736) [`c7bd7b7`](https://github.com/Kilo-Org/kilocode/commit/c7bd7b7ad385d32e114f75dfffa6d5d4168ca073) Thanks [@marius-kilocode](https://github.com/marius-kilocode)! - Skip VSCode-specific diagnostic operations in CLI mode for improved performance
+
+- [#4725](https://github.com/Kilo-Org/kilocode/pull/4725) [`2dcce20`](https://github.com/Kilo-Org/kilocode/commit/2dcce2020b645b8c839a763d4ec97a03f8811aef) Thanks [@marius-kilocode](https://github.com/marius-kilocode)! - Prevent empty checkpoints from being created on every tool use
+
+- [#4723](https://github.com/Kilo-Org/kilocode/pull/4723) [`b9d0d16`](https://github.com/Kilo-Org/kilocode/commit/b9d0d164bd5a3feaab000a040fb9a04f4cd65f77) Thanks [@kiloconnect](https://github.com/apps/kiloconnect)! - Enable chat autocomplete by default
+
+- [#4681](https://github.com/Kilo-Org/kilocode/pull/4681) [`2be56b8`](https://github.com/Kilo-Org/kilocode/commit/2be56b8b09a0cab177adf18c8dd8998f6362cc2d) Thanks [@catrielmuller](https://github.com/catrielmuller)! - Jetbrains IDEs - Improve intialization process
+
+## 4.141.0
+
+### Minor Changes
+
+- [#4702](https://github.com/Kilo-Org/kilocode/pull/4702) [`b84a66f`](https://github.com/Kilo-Org/kilocode/commit/b84a66f5923cf2600a6d5c8e2b5fd49759406696) Thanks [@chrarnoldus](https://github.com/chrarnoldus)! - Add support for skills
+
+### Patch Changes
+
+- [#4710](https://github.com/Kilo-Org/kilocode/pull/4710) [`c128319`](https://github.com/Kilo-Org/kilocode/commit/c1283192df1b0e59fef8b9ab2d3442bf4a07abde) Thanks [@sebastiand-cerebras](https://github.com/sebastiand-cerebras)! - Update Cerebras maxTokens from 8192 to 16384 for all models
+
+- [#4718](https://github.com/Kilo-Org/kilocode/pull/4718) [`9a465b0`](https://github.com/Kilo-Org/kilocode/commit/9a465b06fe401f70dd166fb5b320a8070f07c727) Thanks [@marius-kilocode](https://github.com/marius-kilocode)! - Fix terminal scroll-flicker in CLI by disabling streaming output and enabling Ink incremental rendering
+
+- [#4719](https://github.com/Kilo-Org/kilocode/pull/4719) [`57b0873`](https://github.com/Kilo-Org/kilocode/commit/57b08737788cd504954563d46eb1e6323d619301) Thanks [@marius-kilocode](https://github.com/marius-kilocode)! - Confirm before exiting the CLI on Ctrl+C/Cmd+C.
+
 ## 4.140.3
 
 ### Patch Changes

README.md

@@ -9,12 +9,13 @@
 # 🚀 Kilo
 
 > Kilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.
-> #1 on OpenRouter. 750k+ Kilo Coders. 6.1 trillion tokens used per month.
+> #1 on OpenRouter. 1M+ Kilo Coders. 20T+ tokens processed
 
 - ✨ Generate code from natural language
 - ✅ Checks its own work
 - 🧪 Run terminal commands
 - 🌐 Automate the browser
+- ⚡ Inline autocomplete suggestions
 - 🤖 Latest AI models
 - 🎁 API keys optional
 - 💡 **Get $20 in bonus credits when you top-up for the first time** Credits can be used with 500+ models like Gemini 3 Pro, Claude 4.5 Sonnet & Opus, and GPT-5
@@ -29,6 +30,7 @@
 ## Key Features
 
 - **Code Generation:** Kilo can generate code using natural language.
+- **Inline Autocomplete:** Get intelligent code completions as you type, powered by AI.
 - **Task Automation:** Kilo can automate repetitive coding tasks.
 - **Automated Refactoring:** Kilo can refactor and improve existing code.
 - **MCP Server Marketplace**: Kilo can easily find, and use MCP servers to extend the agent capabilities.

apps/kilocode-docs/docs/advanced-usage/agent-manager.md

@@ -13,6 +13,7 @@ This page reflects the actual implementation in the extension.
 
 - Install/update the Kilo Code CLI (latest) — see [CLI setup](/cli)
 - Open a project in VS Code (workspace required)
+- Authentication: You must be logged in via the extension settings OR use CLI with kilocode as provider (see [Authentication Requirements](#authentication-requirements))
 
 ## Opening the Agent Manager
 
@@ -42,19 +43,74 @@ You can continue a session later (local or remote):
 
 Parallel Mode runs the agent in an isolated Git worktree branch, keeping your main branch clean.
 
-- Enable the “Parallel Mode” toggle before starting
+- Enable the "Parallel Mode" toggle before starting
 - The extension prevents using Parallel Mode inside an existing worktree
     - Open the main repository (where .git is a directory) to use this feature
-- While running, the Agent Manager parses and surfaces:
-    - Branch name created/used
-    - Worktree path
-    - A completion/merge instruction message when the agent finishes
-- After completion
-    - Review the branch in your VCS UI
-    - Merge or cherry-pick the changes as desired
-    - Clean up the worktree when finished
 
-If you need to resume with Parallel Mode later, the extension re-attaches to the same session with the same branch context.
+### Worktree Location
+
+Worktrees are created in `.kilocode/worktrees/` within your project directory. This folder is automatically excluded from git via `.git/info/exclude` (a local-only ignore file that doesn't require a commit).
+
+```
+your-project/
+├── .git/
+│   └── info/
+│       └── exclude   # local ignore rules (includes .kilocode/worktrees/)
+├── .kilocode/
+│   └── worktrees/
+│       └── feature-branch-1234567890/   # isolated working directory
+└── ...
+```
+
+### While Running
+
+The Agent Manager surfaces:
+
+- Branch name created/used
+- Worktree path
+- A completion/merge instruction message when the agent finishes
+
+### After Completion
+
+- The worktree is cleaned up automatically, but the branch is preserved
+- Review the branch in your VCS UI
+- Merge or cherry-pick the changes as desired
+
+### Resuming Sessions
+
+If you resume a Parallel Mode session later, the extension will:
+
+1. Reuse the existing worktree if it still exists
+2. Or recreate it from the session's branch
+
+## Authentication Requirements
+
+The Agent Manager requires proper authentication for full functionality, including session syncing and cloud features.
+
+### Supported Authentication Methods
+
+1. **Kilo Code Extension (Recommended)**
+
+    - Sign in through the extension settings
+    - Provides seamless authentication for the Agent Manager
+    - Enables session syncing and cloud features
+
+2. **CLI with Kilo Code Provider**
+    - Use the CLI configured with `kilocode` as the provider
+    - Run `kilocode config` to set up authentication
+    - See [CLI setup](/cli) for details
+
+### BYOK Limitations
+
+**Important:** Bring Your Own Key (BYOK) is not yet supported with the Agent Manager.
+
+If you're using BYOK with providers like Anthropic, OpenAI, or OpenRouter:
+
+- The Agent Manager will not have access to cloud-synced sessions
+- Session syncing features will be unavailable
+- You must use one of the supported authentication methods above for full functionality
+
+To use the Agent Manager with all features enabled, switch to the Kilo Code provider or sign in through the extension.
 
 ## Remote sessions (Cloud)
 
@@ -66,19 +122,23 @@ When signed in (Kilo Cloud), the Agent Manager lists your recent cloud-synced se
 - Selecting a remote session loads its message transcript
 - To continue the work locally, send a message — the Agent Manager will spawn a local process bound to that session
 
-Message transcripts are fetched from a signed blob and exclude internal checkpoint “save” markers as chat rows (checkpoints still appear as dedicated entries in the UI).
+Message transcripts are fetched from a signed blob and exclude internal checkpoint "save" markers as chat rows (checkpoints still appear as dedicated entries in the UI).
 
 ## Troubleshooting
 
 - CLI not found or outdated
     - Install/update the CLI: [CLI setup](/cli)
-    - If you see an “unknown option --json-io” error, update to the latest CLI
-- “Please open a folder…” error
+    - If you see an "unknown option --json-io" error, update to the latest CLI
+- "Please open a folder…" error
     - The Agent Manager requires a VS Code workspace folder
-- “Cannot use parallel mode from within a git worktree”
+- "Cannot use parallel mode from within a git worktree"
     - Open the main repository (where .git is a directory), not a worktree checkout
 - Remote sessions not visible
-    - Ensure you’re signed in and the repo’s remote URL matches the sessions you expect to see
+    - Ensure you're signed in and the repo's remote URL matches the sessions you expect to see
+    - If using BYOK, session syncing is not available — switch to Kilo Code provider or sign in through the extension
+- Authentication errors
+    - Verify you're logged in via extension settings or using CLI with kilocode provider
+    - BYOK configurations do not support Agent Manager authentication
 
 ## Related features
 

apps/kilocode-docs/docs/advanced-usage/auto-cleanup.md

@@ -241,7 +241,7 @@ Task data is stored in your VS Code global storage location:
 ## Related Features
 
 - [**Checkpoints**](../features/checkpoints): Version control for tasks that can be restored
-- [**Settings Management**](../features/settings-management): Export/import settings including cleanup configuration
+- [**Settings Management**](../basic-usage/settings-management): Export/import settings including cleanup configuration
 - [**Task History**](../basic-usage/the-chat-interface): Managing and organizing your task history
 
 ## Frequently Asked Questions

apps/kilocode-docs/docs/advanced-usage/cloud-agent.md

@@ -91,6 +91,16 @@ You can customize each Cloud Agent session by defining:
 
 ---
 
+## Skills
+
+Cloud Agents support project-level [skills](../cli#skills) stored in your repository. When your repo is cloned, any skills in `.kilocode/skills/` are automatically available.
+
+:::note
+Global skills (`~/.kilocode/skills/`) are not available in Cloud Agents since there is no persistent user home directory.
+:::
+
+---
+
 ## Perfect For
 
 Cloud Agents are great for:

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

@@ -35,7 +35,7 @@ When Memory Bank is active, Kilo Code begins each task with `[Memory Bank: Activ
 
 ## 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.
+Memory Bank is built on Kilo Code's [Custom Rules](/agent-behavior/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.
 

apps/kilocode-docs/docs/advanced-usage/migrating-from-cursor-windsurf.md

@@ -6,6 +6,15 @@ sidebar_label: Migrating from Cursor or Windsurf
 
 Quickly migrate your custom rules from Cursor or Windsurf to Kilo Code. The process typically takes just a few minutes per project.
 
+:::info Two Workflow Approaches
+Kilo Code supports **two complementary workflows**—choose the one that fits your style, or use both:
+
+1. **Autocomplete (Ghost)**: Tab-to-accept inline suggestions as you type, similar to Cursor and Windsurf. Enable via Settings → Ghost.
+2. **Chat-driven**: Describe what you want in the chat panel and the AI generates complete implementations.
+
+Many developers combine both approaches: autocomplete for quick completions while typing, and chat for larger refactors or multi-file changes. See [Choosing Your Workflow](#choosing-your-workflow) for details.
+:::
+
 **Last Updated**: November 2025
 
 ## Why Kilo Code's Rules System?
@@ -309,6 +318,7 @@ After migration:
 - [ ] **Update team docs:** Document new `.kilocode/rules/` location
 - [ ] **Commit to version control:** `git add .kilocode/`
 - [ ] **Remove old directories:** Delete `.cursor/` or `.windsurf/` folders once verified
+- [ ] **Set up autocomplete:** If you used Cursor/Windsurf autocomplete, enable Ghost (Settings → Ghost) for the same Tab-to-accept experience
 
 ## Troubleshooting
 
@@ -363,6 +373,34 @@ Cursor's nested directories don't map to Kilo Code. Flatten with descriptive nam
 - **Check setting:** Verify "Use Agent Rules" is enabled in Kilo Code settings (enabled by default)
 - **Reload:** Restart VS Code if needed
 
+### Choosing Your Workflow
+
+Kilo Code supports **both autocomplete and chat-driven workflows**. Choose the approach that fits your coding style, or combine them:
+
+**Autocomplete (Ghost) — Tab-to-accept inline suggestions:**
+
+1. Open Settings → Ghost
+2. Enable Ghost autocomplete
+3. Configure your preferred model for completions
+4. Start typing and press Tab to accept suggestions
+
+This works the same way as Cursor and Windsurf's autocomplete. Ghost provides context-aware suggestions as you type.
+
+**Chat-driven — describe what you want:**
+
+- Open the chat panel and describe your intent: "Add error handling to this function" or "Create a React component for user profiles"
+- The AI generates complete implementations, refactors, or fixes
+- Review and approve changes before they're applied
+
+**Combining both workflows:**
+
+Many developers use both approaches together:
+
+- **Autocomplete** for quick completions while writing new code
+- **Chat** for larger refactors, bug fixes, or multi-file changes
+
+There's no "right" workflow—use whatever helps you code faster
+
 ## Advanced: Creating Custom Modes
 
 For complex workflows, define custom modes with their own rules and permissions:
@@ -397,9 +435,9 @@ mkdir -p .kilocode/rules-docs
 
 ## Next Steps
 
-- [Learn about Custom Rules](/advanced-usage/custom-rules)
-- [Explore Custom Modes](/features/custom-modes)
-- [Set up Custom Instructions](/advanced-usage/custom-instructions)
+- [Learn about Custom Rules](/agent-behavior/custom-rules)
+- [Explore Custom Modes](/agent-behavior/custom-modes)
+- [Set up Custom Instructions](/agent-behavior/custom-instructions)
 - [Join our Discord](https://kilo.ai/discord) for migration support
 
 ## Additional Resources

apps/kilocode-docs/docs/agent-behavior/agents-md.md

@@ -0,0 +1,154 @@
+# AGENTS.md Files
+
+AGENTS.md files provide a standardized way to configure AI agent behavior across different AI coding tools. They allow you to define project-specific instructions, coding standards, and guidelines that AI agents should follow when working with your codebase.
+
+## What is AGENTS.md?
+
+AGENTS.md is an open standard for configuring AI agent behavior in software projects. It's a simple Markdown file placed at the root of your project that contains instructions for AI coding assistants. The standard is supported by multiple AI coding tools, including Kilo Code, Cursor, and Windsurf.
+
+Think of AGENTS.md as a "README for AI agents" - it tells the AI how to work with your specific project, what conventions to follow, and what constraints to respect.
+
+## Why Use AGENTS.md?
+
+- **Portability**: Works across multiple AI coding tools without modification
+- **Version Control**: Lives in your repository alongside your code
+- **Team Consistency**: Ensures all team members' AI assistants follow the same guidelines
+- **Project-Specific**: Tailored to your project's unique requirements and conventions
+- **Simple Format**: Plain Markdown - no special syntax or configuration required
+
+## File Location and Naming
+
+### Project-Level AGENTS.md
+
+Place your AGENTS.md file at the **root of your project**:
+
+```
+my-project/
+├── AGENTS.md          # Primary filename (recommended)
+├── src/
+├── package.json
+└── README.md
+```
+
+**Supported filenames** (in order of precedence):
+
+1. `AGENTS.md` (uppercase, plural - recommended)
+2. `AGENT.md` (uppercase, singular - fallback)
+
+:::warning Case Sensitivity
+The filename must be uppercase (`AGENTS.md`), not lowercase (`agents.md`). This ensures consistency across different operating systems and tools.
+:::
+
+### Subdirectory AGENTS.md Files
+
+You can also place AGENTS.md files in subdirectories to provide context-specific instructions:
+
+```
+my-project/
+├── AGENTS.md                    # Root-level instructions
+├── src/
+│   └── backend/
+│       └── AGENTS.md            # Backend-specific instructions
+└── docs/
+    └── AGENTS.md                # Documentation-specific instructions
+```
+
+When working in a subdirectory, Kilo Code will load both the root AGENTS.md and any subdirectory AGENTS.md files, with subdirectory files taking precedence for conflicting instructions.
+
+## File Protection
+
+Both `AGENTS.md` and `AGENT.md` are **write-protected files** in Kilo Code. This means:
+
+- The AI agent cannot modify these files without explicit user approval
+- You'll be prompted to confirm any changes to these files
+- This prevents accidental modifications to your project's AI configuration
+
+## Basic Syntax and Structure
+
+AGENTS.md files use standard Markdown syntax. There's no required structure, but organizing your content with headers and lists makes it easier for AI models to parse and understand.
+
+### Recommended Structure
+
+```markdown
+# Project Name
+
+Brief description of the project and its purpose.
+
+## Code Style
+
+- Use TypeScript for all new files
+- Follow ESLint configuration
+- Use 2 spaces for indentation
+
+## Architecture
+
+- Follow MVC pattern
+- Keep components under 200 lines
+- Use dependency injection
+
+## Testing
+
+- Write unit tests for all business logic
+- Maintain >80% code coverage
+- Use Jest for testing
+
+## Security
+
+- Never commit API keys or secrets
+- Validate all user inputs
+- Use parameterized queries for database access
+```
+
+## Best Practices
+
+- **Be specific and clear** - Use concrete rules like "limit cyclomatic complexity to < 10" instead of vague guidance like "write good code"
+- **Include code examples** - Show patterns for error handling, naming conventions, or architecture decisions
+- **Organize by category** - Group related guidelines under clear headers (Code Style, Architecture, Testing, Security)
+- **Keep it concise** - Use bullet points and direct language; avoid long paragraphs
+- **Update regularly** - Review and revise as your project's conventions evolve
+
+## How AGENTS.md Works in Kilo Code
+
+### Loading Behavior
+
+When you start a task in Kilo Code:
+
+1. Kilo Code checks for `AGENTS.md` or `AGENT.md` at the project root
+2. If found, the content is loaded and included in the AI's context
+3. The AI follows these instructions throughout the conversation
+4. Changes to AGENTS.md take effect in new tasks (reload may be required)
+
+### Interaction with Other Rules
+
+AGENTS.md works alongside Kilo Code's other configuration systems:
+
+| Feature                                                        | Scope   | Location                  | Purpose                                    | Priority    |
+| -------------------------------------------------------------- | ------- | ------------------------- | ------------------------------------------ | ----------- |
+| **[Mode-specific Custom Rules](/agent-behavior/custom-rules)** | Project | `.kilocode/rules-{mode}/` | Mode-specific rules and constraints        | 1 (Highest) |
+| **[Custom Rules](/agent-behavior/custom-rules)**               | Project | `.kilocode/rules/`        | Kilo Code-specific rules and constraints   | 2           |
+| **AGENTS.md**                                                  | Project | Project root or subfolder | Cross-tool standard for project guidelines | 3           |
+| **[Global Custom Rules](/agent-behavior/custom-rules)**        | Global  | `~/.kilocode/rules/`      | Global Kilo Code rules                     | 4           |
+| **[Custom Instructions](/agent-behavior/custom-instructions)** | Global  | IDE settings              | Personal preferences across all projects   | 5 (Lowest)  |
+
+### Enabling/Disabling AGENTS.md
+
+AGENTS.md support is **enabled by default** in Kilo Code. To disable it, edit `settings.json`:
+
+```json
+{
+	"kilocode.useAgentRules": false
+}
+```
+
+## Related Features
+
+- **[Custom Rules](/agent-behavior/custom-rules)** - Kilo Code-specific rules with more control
+- **[Custom Modes](/agent-behavior/custom-modes)** - Specialized workflows with specific permissions
+- **[Custom Instructions](/agent-behavior/custom-instructions)** - Personal preferences across all projects
+- **[Migrating from Cursor or Windsurf](/advanced-usage/migrating-from-cursor-windsurf)** - Migration guide for other tools
+
+## External Resources
+
+- [AGENTS.md Specification](https://agents.md) - Official standard documentation
+- [dotagent](https://github.com/johnlindquist/dotagent) - Universal converter tool for agent configuration files
+- [awesome-cursorrules](https://github.com/PatrickJS/awesome-cursorrules) - 700+ example rules you can adapt

apps/kilocode-docs/docs/advanced-usage/custom-instructions.md → apps/kilocode-docs/docs/agent-behavior/custom-instructions.md

@@ -7,7 +7,7 @@ Custom Instructions allow you to personalize how Kilo Code behaves, providing sp
 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.
+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](/agent-behavior/custom-rules) are project specific and allow you to setup workspace-based ruleset.
 :::
 
 ## Setting Custom Instructions
@@ -36,7 +36,7 @@ Mode-specific instructions can be set using the Modes Tab
 
 ## 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)
+- [Custom Modes](/agent-behavior/custom-modes)
+- [Custom Rules](/agent-behavior/custom-rules)
+- [Settings Management](/basic-usage/settings-management)
+- [Auto-Approval Settings](/features/auto-approving-actions)

apps/kilocode-docs/docs/advanced-usage/custom-rules.md → apps/kilocode-docs/docs/agent-behavior/custom-rules.md

@@ -217,7 +217,7 @@ If your custom rules aren't being properly followed:
 
 ## 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)
+- [Custom Modes](/agent-behavior/custom-modes)
+- [Custom Instructions](/agent-behavior/custom-instructions)
+- [Settings Management](/basic-usage/settings-management)
+- [Auto-Approval Settings](/features/auto-approving-actions)

apps/kilocode-docs/docs/advanced-usage/prompt-engineering.md → apps/kilocode-docs/docs/agent-behavior/prompt-engineering.md

@@ -44,7 +44,7 @@ Custom instructions are added to the system prompt, providing persistent guidanc
 - Define project-specific conventions.
 - Adjust Kilo Code's tone or personality.
 
-See the [Custom Instructions](/advanced-usage/custom-instructions) section for more details.
+See the [Custom Instructions](/agent-behavior/custom-instructions) section for more details.
 
 ## Handling Ambiguity
 

apps/kilocode-docs/docs/agent-behavior/skills.md

@@ -0,0 +1,288 @@
+# Skills
+
+Kilo Code implements [Agent Skills](https://agentskills.io/), a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows.
+
+## What Are Agent Skills?
+
+Agent Skills package domain expertise, new capabilities, and repeatable workflows that agents can use. At its core, a skill is a folder containing a `SKILL.md` file with metadata and instructions that tell an agent how to perform a specific task.
+
+This approach keeps agents fast while giving them access to more context on demand. When a task matches a skill's description, the agent reads the full instructions into context and follows them—optionally loading referenced files or executing bundled code as needed.
+
+### Key Benefits
+
+- **Self-documenting**: A skill author or user can read a `SKILL.md` file and understand what it does, making skills easy to audit and improve
+- **Interoperable**: Skills work across any agent that implements the [Agent Skills specification](https://agentskills.io/specification)
+- **Extensible**: Skills can range in complexity from simple text instructions to bundled scripts, templates, and reference materials
+- **Shareable**: Skills are portable and can be easily shared between projects and developers
+
+## How Skills Work in Kilo Code
+
+Skills can be:
+
+- **Generic** - Available in all modes
+- **Mode-specific** - Only loaded when using a particular mode (e.g., `code`, `architect`)
+
+The workflow is:
+
+1. **Discovery**: Skills are scanned from designated directories when Kilo Code initializes
+2. **Activation**: When a mode is active, relevant skills are included in the system prompt
+3. **Execution**: The AI agent follows the skill's instructions for applicable tasks
+
+## Skill Locations
+
+Skills are loaded from multiple locations, allowing both personal skills and project-specific instructions.
+
+### Global Skills (User-Level)
+
+Located in `~/.kilocode/skills/`:
+
+```
+~/.kilocode/
+├── skills/                    # Generic skills (all modes)
+│   ├── my-skill/
+│   │   └── SKILL.md
+│   └── another-skill/
+│       └── SKILL.md
+├── skills-code/              # Code mode only
+│   └── refactoring/
+│       └── SKILL.md
+└── skills-architect/         # Architect mode only
+    └── system-design/
+        └── SKILL.md
+```
+
+### Project Skills (Workspace-Level)
+
+Located in `.kilocode/skills/` within your project:
+
+```
+your-project/
+└── .kilocode/
+    ├── skills/               # Generic skills for this project
+    │   └── project-conventions/
+    │       └── SKILL.md
+    └── skills-code/          # Code mode skills for this project
+        └── linting-rules/
+            └── SKILL.md
+```
+
+## Mode-Specific Skills
+
+To create a skill that only appears in a specific mode:
+
+```bash
+# For Code mode only
+mkdir -p ~/.kilocode/skills-code/typescript-patterns
+
+# For Architect mode only
+mkdir -p ~/.kilocode/skills-architect/microservices
+```
+
+The directory naming pattern is `skills-{mode-slug}` where `{mode-slug}` matches the mode's identifier (e.g., `code`, `architect`, `ask`, `debug`).
+
+## Priority and Overrides
+
+When multiple skills share the same name, Kilo Code uses these priority rules:
+
+1. **Project skills override global skills** - A project skill with the same name takes precedence
+2. **Mode-specific skills override generic skills** - A skill in `skills-code/` overrides the same skill in `skills/` when in Code mode
+
+This allows you to:
+
+- Define global skills for personal use
+- Override them per-project when needed
+- Customize behavior for specific modes
+
+## When Skills Are Loaded
+
+Skills are discovered when Kilo Code initializes:
+
+- When VSCode starts
+- When you reload the VSCode window (`Cmd+Shift+P` → "Developer: Reload Window")
+
+Skills directories are monitored for changes to `SKILL.md` files. However, the most reliable way to pick up new skills is to reload VS or the Kilo Code extension.
+
+**Adding or modifying skills requires reloading VSCode for changes to take effect.**
+
+## Using Symlinks
+
+You can symlink skills directories to share skills across machines or from a central repository. When using symlinks, the skill's `name` field must match the **symlink name**, not the target directory name.
+
+## SKILL.md Format
+
+The `SKILL.md` file uses YAML frontmatter followed by Markdown content containing the instructions:
+
+```markdown
+---
+name: my-skill-name
+description: A brief description of what this skill does and when to use it
+---
+
+# Instructions
+
+Your detailed instructions for the AI agent go here.
+
+These instructions will be included in the system prompt when:
+
+1. The skill is discovered in a valid location
+2. The current mode matches (or the skill is generic)
+
+## Example Usage
+
+You can include examples, guidelines, code snippets, etc.
+```
+
+### Frontmatter Fields
+
+Per the [Agent Skills specification](https://agentskills.io/specification):
+
+| Field           | Required | Description                                                                                           |
+| --------------- | -------- | ----------------------------------------------------------------------------------------------------- |
+| `name`          | Yes      | Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen. |
+| `description`   | Yes      | Max 1024 characters. Describes what the skill does and when to use it.                                |
+| `license`       | No       | License name or reference to a bundled license file                                                   |
+| `compatibility` | No       | Environment requirements (intended product, system packages, network access, etc.)                    |
+| `metadata`      | No       | Arbitrary key-value mapping for additional metadata                                                   |
+
+### Example with Optional Fields
+
+```markdown
+---
+name: pdf-processing
+description: Extract text and tables from PDF files, fill forms, merge documents.
+license: Apache-2.0
+metadata:
+    author: example-org
+    version: 1.0.0
+---
+
+## How to extract text
+
+1. Use pdfplumber for text extraction...
+
+## How to fill forms
+
+...
+```
+
+### Name Matching Rule
+
+In Kilo Code, the `name` field **must match** the parent directory name:
+
+```
+✅ Correct:
+skills/
+└── frontend-design/
+    └── SKILL.md  # name: frontend-design
+
+❌ Incorrect:
+skills/
+└── frontend-design/
+    └── SKILL.md  # name: my-frontend-skill  (doesn't match!)
+```
+
+## Optional Bundled Resources
+
+While `SKILL.md` is the only required file, you can optionally include additional directories to support your skill:
+
+```
+my-skill/
+├── SKILL.md           # Required: instructions + metadata
+├── scripts/           # Optional: executable code
+├── references/        # Optional: documentation
+└── assets/            # Optional: templates, resources
+```
+
+These additional files can be referenced from your skill's instructions, allowing the agent to read documentation, execute scripts, or use templates as needed.
+
+## Example: Creating a Skill
+
+1. Create the skill directory:
+
+    ```bash
+    mkdir -p ~/.kilocode/skills/api-design
+    ```
+
+2. Create `SKILL.md`:
+
+    ```markdown
+    ---
+    name: api-design
+    description: REST API design best practices and conventions
+    ---
+
+    # API Design Guidelines
+
+    When designing REST APIs, follow these conventions:
+
+    ## URL Structure
+
+    - Use plural nouns for resources: `/users`, `/orders`
+    - Use kebab-case for multi-word resources: `/order-items`
+    - Nest related resources: `/users/{id}/orders`
+
+    ## HTTP Methods
+
+    - GET: Retrieve resources
+    - POST: Create new resources
+    - PUT: Replace entire resource
+    - PATCH: Partial update
+    - DELETE: Remove resource
+
+    ## Response Codes
+
+    - 200: Success
+    - 201: Created
+    - 400: Bad Request
+    - 404: Not Found
+    - 500: Server Error
+    ```
+
+3. Reload VSCode to load the skill
+
+4. The skill will now be available in all modes
+
+## Finding Skills
+
+There are community efforts to build and share agent skills. Some resources include:
+
+- [Skills Marketplace](https://skillsmp.com/) - Community marketplace of skills
+- [Skill Specification](https://agentskills.io/home) - Agent Skills specification
+
+## Troubleshooting
+
+### Skill Not Loading?
+
+1. **Check the Output panel**: Open `View` → `Output` → Select "Kilo Code" from dropdown. Look for skill-related errors.
+
+2. **Verify frontmatter**: Ensure `name` exactly matches the directory name and `description` is present.
+
+3. **Reload VSCode**: Skills are loaded at startup. Use `Cmd+Shift+P` → "Developer: Reload Window".
+
+4. **Check file location**: Ensure `SKILL.md` is directly inside the skill directory, not nested further.
+
+### Verifying a Skill is Activated
+
+To confirm a skill is properly loaded and available to the agent, you can ask the agent directly. Simply send a message like:
+
+- "Do you have access to skill X?"
+- "Is the skill called X loaded?"
+- "What skills do you have available?"
+
+The agent will respond with information about whether the skill is loaded and accessible. This is the most reliable way to verify that a skill has been activated after adding it or reloading VSCode.
+
+If the agent confirms the skill is available, you're ready to use it. If not, check the troubleshooting steps above to identify and resolve the issue.
+
+### Common Errors
+
+| Error                           | Cause                                        | Solution                                         |
+| ------------------------------- | -------------------------------------------- | ------------------------------------------------ |
+| "missing required 'name' field" | No `name` in frontmatter                     | Add `name: your-skill-name`                      |
+| "name doesn't match directory"  | Mismatch between frontmatter and folder name | Make `name` match exactly                        |
+| Skill not appearing             | Wrong directory structure                    | Verify path follows `skills/skill-name/SKILL.md` |
+
+## Related
+
+- [Custom Modes](/agent-behavior/custom-modes) - Create custom modes that can use specific skills
+- [Custom Instructions](/agent-behavior/custom-instructions) - Global instructions vs. skill-based instructions
+- [Custom Rules](/agent-behavior/custom-rules) - Project-level rules complementing skills

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

@@ -4,9 +4,13 @@ import { DISCORD_URL } from '@site/src/constants.ts'
 
 Once you've used any initial free Kilo Credits, 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 credits you use, and only when you choose to top up your credits!
-- Leverage your own API provider by [connecting your own API provider](/getting-started/connecting-api-provider.md)
+- Subscribe to the [Kilo Pass](https://kilo.ai/features/kilo-pass), the most cost effective way to add credits.
+- Purchase additional credits as a one-time transaction.
+- Enable automatic top-up, which purchases additional credits when your balance is below $5.
+
+These options are available to purchase from your [personal profile page](https://app.kilo.ai).
+
+You can also use subscriptions or credits you may have purchased directly with an AI provider by adding your keys on the [Bring your own Key (BYOK)](https://app.kilo.ai/byok) settings screen. If your provider is not yet supported, you can also [directly connect your provider](/getting-started/connecting-api-provider.md) in the extension and CLI.
 
 ## Transparent Pricing
 

apps/kilocode-docs/docs/basic-usage/autocomplete.md → apps/kilocode-docs/docs/basic-usage/autocomplete/index.md

@@ -1,6 +1,7 @@
 ---
 title: Autocomplete
 sidebar_position: 4
+slug: /basic-usage/autocomplete
 ---
 
 # Autocomplete
@@ -16,37 +17,19 @@ Autocomplete analyzes your code context and provides:
 - **Contextual suggestions** based on your surrounding code
 - **Multi-line completions** for complex code structures
 
-The feature uses your selected AI provider to generate intelligent suggestions that match your coding style and project context.
-
 ## Triggering Options
 
-### Pause to Complete
+### Code Editor Suggestions
+
+#### Auto-trigger suggestions
 
-When enabled, Kilo Code automatically triggers autocomplete when you pause typing. This provides a seamless coding experience where suggestions appear naturally as you work.
+When enabled, Kilo Code automatically shows inline suggestions when you pause typing. This provides a seamless coding experience where suggestions appear naturally as you work.
 
-- **Auto Trigger Delay**: Configure the delay (in seconds) before autocomplete triggers after you stop typing
+- **Auto Trigger Delay**: Configure the delay (in seconds) before suggestions appear after you stop typing
 - Default is 3 seconds, but this can be adjusted up or down
 - Shorter delays mean quicker suggestions but may be more resource-intensive
 
-### Quick Task (Cmd+I)
-
-Need to make a quick change? The Quick Task feature allows you to:
-
-1. Select code in your editor (or place your cursor where you want changes)
-2. Press `Cmd+I` (Mac) or `Ctrl+I` (Windows/Linux)
-3. Describe your goal in plain English
-4. Receive a code suggestion without going to the chat
-
-**Examples:**
-
-- "create a React component with these props"
-- "add error handling to this function"
-- "convert this to TypeScript"
-- "optimize this loop for performance"
-
-You can customize the keyboard shortcut in VS Code's keyboard shortcuts settings.
-
-### Manual Autocomplete (Cmd+L)
+#### Trigger on keybinding (Cmd+L)
 
 For more control over when suggestions appear:
 
@@ -64,6 +47,34 @@ This is ideal for:
 
 You can customize this keyboard shortcut as well in your VS Code settings.
 
+### Chat Suggestions
+
+#### Enable Chat Autocomplete
+
+When enabled, Kilo Code will suggest completions as you type in the chat input. Press Tab to accept suggestions.
+
+## Provider and Model Selection
+
+Autocomplete currently uses **Codestral** (by Mistral AI) as the underlying model. This model is specifically optimized for code completion tasks and provides fast, high-quality suggestions.
+
+### How the Provider is Chosen
+
+Kilo Code automatically selects a provider for autocomplete in the following priority order:
+
+- **Mistral** (using `codestral-latest`)
+- **Kilo Code** (using `mistralai/codestral-2508`)
+- **OpenRouter** (using `mistralai/codestral-2508`)
+- **Requesty** (using `mistral/codestral-latest`)
+- **Bedrock** (using `mistral.codestral-2508-v1:0`)
+- **Hugging Face** (using `mistralai/Codestral-22B-v0.1`)
+- **LiteLLM** (using `codestral/codestral-latest`)
+- **LM Studio** (using `mistralai/codestral-22b-v0.1`)
+- **Ollama** (using `codestral:latest`)
+
+:::note
+**Model Selection is Currently Fixed**: At this time, you cannot freely choose a different model for autocomplete. The feature is designed to work specifically with Codestral, which is optimized for Fill-in-the-Middle (FIM) completions. Support for additional models may be added in future releases.
+:::
+
 ## Disable Rival Autocomplete
 
 We recommend disabling rival autocompletes to optimize your experience with Kilo Code. To disable GitHub Copilot autocomplete in VSCode, go to **Settings** and navigate to **GitHub** > **Copilot: Advanced** (or search for 'copilot').
@@ -100,4 +111,4 @@ If using Cursor, go to **Settings** > **Cursor Settings** > **Tab**, and toggle
 
 ## Related Features
 
-- [Code Actions](../features/code-actions) - Context menu options for common coding tasks
+- [Code Actions](/features/code-actions) - Context menu options for common coding tasks

apps/kilocode-docs/docs/basic-usage/autocomplete/mistral-setup.md

@@ -0,0 +1,89 @@
+---
+title: Setting Up Mistral for Free Autocomplete
+sidebar_position: 1
+---
+
+# Setting Up Mistral for Free Autocomplete
+
+This guide walks you through setting up Mistral's Codestral model for free autocomplete in Kilo Code. Mistral offers a free tier that's perfect for getting started with AI-powered code completions.
+
+## Video Walkthrough
+
+<video controls width="100%">
+  <source src="/docs/videos/configure_free_codestral.mp4" type="video/mp4" />
+  Your browser does not support the video tag.
+</video>
+
+## Step 1: Open Kilo Code Settings
+
+In VS Code, open the Kilo Code panel and click the **Settings** icon (gear) in the top-right corner.
+
+![Open Kilo Code Settings](./mistral-setup/01-open-kilo-code-settings.png)
+
+## Step 2: Add a New Configuration Profile
+
+Navigate to **Settings → Providers** and click **Add Profile** to create a new configuration profile for Mistral.
+
+![Add Configuration Profile](./mistral-setup/02-add-configuration-profile.png)
+
+## Step 3: Name Your Profile
+
+In the "New Configuration Profile" dialog, enter a name like "Mistral profile" (the name can be anything you prefer) and click **Create Profile**.
+
+:::note
+The profile name is just a label for your reference—it doesn't affect functionality. Choose any name that helps you identify this configuration.
+:::
+
+![Create Mistral Profile](./mistral-setup/03-name-your-profile.png)
+
+## Step 4: Select Mistral as Provider
+
+In the **API Provider** dropdown, search for and select **Mistral**.
+
+:::note
+When creating an autocomplete profile, you don't need to select a specific model—Kilo Code will automatically use the appropriate Codestral model optimized for code completions.
+:::
+
+![Select Mistral Provider](./mistral-setup/04-select-mistral-provider.png)
+
+## Step 5: Get Your API Key
+
+You'll see a warning that you need a valid API key. Click **Get Mistral / Codestral API Key** to open the Mistral console.
+
+![Get API Key Button](./mistral-setup/05-get-api-key.png)
+
+## Step 6: Navigate to Codestral in Mistral AI Studio
+
+In the Mistral AI Studio sidebar, click **Codestral** under the Code section.
+
+![Select Codestral](./mistral-setup/06-navigate-to-codestral.png)
+
+## Step 7: Generate API Key
+
+Click the **Generate API Key** button to create your new Codestral API key.
+
+![Confirm Generate](./mistral-setup/07-confirm-key-generation.png)
+
+## Step 8: Copy Your API Key
+
+Once generated, click the **copy** button next to your API key to copy it to your clipboard.
+
+![Copy API Key](./mistral-setup/08-copy-api-key.png)
+
+## Step 9: Paste API Key in Kilo Code
+
+Return to Kilo Code settings and paste your API key into the **Mistral API Key** field.
+
+![Paste API Key](./mistral-setup/09-paste-api-key.png)
+
+## Step 10: Save Your Settings
+
+Click **Save** to apply your Mistral configuration. You're now ready to use free autocomplete!
+
+![Save Settings](./mistral-setup/10-save-settings.png)
+
+## Next Steps
+
+- Learn more about [Autocomplete features](./index.md)
+- Explore [triggering options](./index.md#triggering-options) for autocomplete
+- Check out [best practices](./index.md#best-practices) for optimal results

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

@@ -154,4 +154,4 @@ The feature integrates with VS Code's built-in git functionality. If you encount
 ## 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
+- [Settings Management](/basic-usage/settings-management) - Manage all your Kilo Code preferences

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

@@ -8,6 +8,12 @@ import Image from '@site/src/components/Image';
 
 :::
 
+:::note[Prefer quick completions?]
+
+If you're typing code in the editor and want AI to finish your line or block, check out [Autocomplete](/basic-usage/autocomplete) instead. Chat is best for larger tasks, explanations, and multi-file changes.
+
+:::
+
 ## 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.
@@ -41,6 +47,14 @@ find all instances of the variable oldValue in @/src/App.js and replace them wit
 - **One task at a time** - Break complex work into manageable steps
 - **Include examples** - Show the style or format you want
 
+:::info[Chat vs Autocomplete]
+
+**Use chat** when you need to describe what you want, ask questions, or make changes across multiple files.
+
+**Use [autocomplete](/basic-usage/autocomplete)** when you're already typing code and want the AI to finish your thought inline.
+
+:::
+
 ## The Chat Interface
 
 <Image 
@@ -74,12 +88,13 @@ find all instances of the variable oldValue in @/src/App.js and replace them wit
 
 ## 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                       |
+| 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                           |
+| Using chat for tiny code changes. | Use [autocomplete](/basic-usage/autocomplete) for inline completions |
 
 **Why it matters:** Kilo Code works best when you communicate like you're talking to a smart teammate who needs clear direction.
 

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

@@ -87,4 +87,4 @@ Four ways to switch 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.
+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](/agent-behavior/custom-modes) for setup instructions.

apps/kilocode-docs/docs/cli.md

@@ -38,9 +38,23 @@ Upgrade the Kilo CLI package:
 - **Switch between hundreds of LLMs without constraints.** Other CLI tools only work with one model or curate opinionated lists. With Kilo, you can switch models without booting up another tool.
 - **Choose the right mode for the task in your workflow.** Select between Architect, Ask, Debug, Orchestrator, or custom agent modes.
 - **Automate tasks.** Get AI assistance writing shell scripts for tasks like renaming all of the files in a folder or transforming sizes for a set of images.
+- **Extend capabilities with skills.** Add domain expertise and repeatable workflows through [Agent Skills](#skills).
 
 ## CLI reference
 
+### Keyboard shortcuts
+
+| Shortcut    | Description                                                                        |
+| ----------- | ---------------------------------------------------------------------------------- |
+| `Shift+Tab` | Cycle through modes (architect → code → ask → debug → orchestrator → custom modes) |
+| `Ctrl+C`    | Exit (press twice to confirm)                                                      |
+| `Ctrl+X`    | Cancel current task                                                                |
+| `Esc`       | Cancel current task (while streaming) or clear input                               |
+| `Ctrl+Y`    | Toggle YOLO mode (auto-approve all operations)                                     |
+| `Ctrl+R`    | Resume task (when a task is ready to resume)                                       |
+| `!`         | Enter shell mode (when input is empty)                                             |
+| `↑/↓`       | Navigate command history (when input is empty)                                     |
+
 ### CLI commands
 
 | Command               | Description                                                      | Example                        |
@@ -68,6 +82,65 @@ Upgrade the Kilo CLI package:
 | `/help`               | List available commands and how to use them                      |                                |
 | `/exit`               | Exit the CLI                                                     |                                |
 
+## Skills
+
+The CLI supports [Agent Skills](https://agentskills.io/), a lightweight format for extending AI capabilities with specialized knowledge and workflows.
+
+Skills are discovered from:
+
+- **Global skills**: `~/.kilocode/skills/` (available in all projects)
+- **Project skills**: `.kilocode/skills/` (project-specific)
+
+Skills can be:
+
+- **Generic** - Available in all modes
+- **Mode-specific** - Only loaded when using a particular mode (e.g., `code`, `architect`)
+
+For example:
+
+```
+your-project/
+└── .kilocode/
+    ├── skills/               # Generic skills for this project
+    │   └── project-conventions/
+    │       └── SKILL.md
+    └── skills-code/          # Code mode skills for this project
+        └── linting-rules/
+            └── SKILL.md
+```
+
+### Adding a Skill
+
+1. Create the skill directory:
+
+    ```bash
+    mkdir -p ~/.kilocode/skills/api-design
+    ```
+
+2. Create a `SKILL.md` file with YAML frontmatter:
+
+    ```markdown
+    ---
+    name: api-design
+    description: REST API design best practices and conventions
+    ---
+
+    # API Design Guidelines
+
+    When designing REST APIs, follow these conventions...
+    ```
+
+    The `name` field must match the directory name exactly.
+
+3. Start a new CLI session to load the skill
+
+#### Finding skills
+
+There are community efforts to build and share agent skills. Some resources include:
+
+- [Skills Marketplace](https://skillsmp.com/) - Community marketplace of skills
+- [Skill Specification](https://agentskills.io/home) - Agent Skills specification
+
 ## Checkpoint Management
 
 Kilo Code automatically creates checkpoints as you work, allowing you to revert to previous states in your project's history.

apps/kilocode-docs/docs/contributing/architecture/annual-billing.md

@@ -0,0 +1,67 @@
+---
+sidebar_position: 3
+title: "Annual Billing"
+---
+
+# Annual Billing
+
+# Overview
+
+we want to switch to doing annual billing for teams and enterprise with a 1 month free and a "self-serve" sign up.
+
+# Requirements
+
+- no more 20$ of one time free credits on team signup per seat. **this is done**
+- enable 30 day trial for both teams and enterprise
+    - no credit card required
+    - self-serve enterprise comes with no self-serve SSO. There's a button that puts them in touch with sales. (it costs us 125 a month for SSO per org)
+- monthly plan is not accessible via the UI but is still in effect for existing customers and can be flagged back on easily.
+- trial users can only upgrade to annual plans, 348/teams seat or $3588/ent seat, but we always talk about pricing in monthly terms.
+- once trial expires, the organization will be denied access to the openrouter proxy endpoint, effectively disabling their kilocode usage w/ our API provider, and any existing outstanding credits they purchased will be locked up until they subscribe.
+
+### Non-requirements
+
+- fully self-service SSO enrollment for enterprise. There's still a bit of a touch required. Its possible to implement, but out of scope for this spec.
+- pro-rated cancellation or refunds handled in a self-serve way.
+- elastic seat counts with custom billing agreements for enterprise organizations.
+- a full redesign of the team/enterprise sign up and pre-creation / marketing flow.
+
+# System Design
+
+System design is pretty straight-forward as we can _mostly_ leverage existing infrastructure and code.
+
+- System remains the same other than adding a `billing_cycle` column to `organization_seats_purcahses` where we can track if it is `monthly` or `yearly`. The migration will set the default to `monthly` so we backfill all existing customers.
+- We will use `created_at` on the organization as the start date for the free trial. If the organization does not have a valid entry in `organization_seats_purchases` after 30 days, we will disable their access to the openrouter proxy endpoint.
+
+## Engineering Scope
+
+#### Migrations:
+
+- add `billing_cycle TEXT NOT NULL DEFAULT 'monthly'` to `organization_seats_purchases`.
+- add `plan TEXT NOT NULL DEFAULT 'teams'` to `organizations` table which can be `teams` or `enterprise`. (While not strictly required we shouldn't rely on `seats_required` to decide if an org is a team or enterprise account and now is a good opportunity to fix this. Manually go through and set the very small number of design partner orgs and our org into `enterprise.` for now.)
+
+#### Tasks:
+
+- create yearly billing subscription product for teams AND for enterprise in stripe.
+- change the organization create flow to create organization on submit (it does this now) but instead of redirecting to stripe to pay, redirect to organization page. Do not require an ahead-of-time seat count on either teams or enterprise.
+- update logic for checking & displaying seats to take into consideration the free trial period, and allow invites for an unlimited number of seats while the trial is active.
+- update subscription management page to allow for creating a new subscription from the page.
+- update logic to actually block organizations which are not active on seats (they are either over their paid seat count or do not have an active seats purchases subscription). [a ticket for this already exists](https://github.com/orgs/Kilo-Org/projects/11?pane=issue&itemId=126001076&issue=Kilo-Org%7Ckilocode-backend%7C2167) note: this can wait until the end as by definition no one can have their trial expire for at least 30 days so we have a 30 day buffer to implement this.
+
+### Marketing Scope
+
+As a fast follow or in parallel the seats pod will pair up with someone from marketing or devrel to work on our engagement with this feature.
+
+- update / redesign team/enterprise "create" page in app with better CTAs
+- work with eng to get the 'buy credits' action more importantly called out when a new org is created. General org onboarding flow (both teams and enterprise) needs help.
+- significantly improve call-to-action flows around upgrading to paid subscriptions with potentially progressively louder noise as we get closer to the end of trial notice.
+- send welcome email when org is created explaining the trail period.
+- probably cut new videos to show off the enterprise features
+
+# Compliance Considerations
+
+No compliance concerns.
+
+# Features for the future
+
+Talks about what we might want to build or improve upon in the future but is out-of-scope of this spec.

apps/kilocode-docs/docs/contributing/specs/spec-enterprise-mcp-controls.md → apps/kilocode-docs/docs/contributing/architecture/enterprise-mcp-controls.md

@@ -1,9 +1,9 @@
 ---
 sidebar_position: 4
-title: "Spec: Enterprise MCP Controls"
+title: "Enterprise MCP Controls"
 ---
 
-# Spec: Enterprise MCP Controls
+# Enterprise MCP Controls
 
 ### Overview
 

apps/kilocode-docs/docs/contributing/specs/spec-template.md → apps/kilocode-docs/docs/contributing/architecture/feature-template.md

@@ -3,7 +3,7 @@ sidebar_position: 2
 title: "Spec Template"
 ---
 
-# SPEC: Template
+# Template
 
 # Overview
 

apps/kilocode-docs/docs/contributing/architecture.md → apps/kilocode-docs/docs/contributing/architecture/index.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 1
 title: "Architecture Overview"
 ---
 
@@ -13,85 +13,51 @@ Kilo Code is a VS Code extension built with TypeScript that connects to various
 
 ```
 ┌─────────────────────────────────────────────────────────────────────┐
-│                           VS Code Extension                          │
+│                           VS Code Extension                         │
 ├─────────────────────────────────────────────────────────────────────┤
-│                                                                      │
+│                                                                     │
 │  ┌──────────────────┐     ┌──────────────────┐                      │
 │  │   Extension Host │     │    Webview UI    │                      │
 │  │      (src/)      │◀───▶│  (webview-ui/)   │                      │
 │  └────────┬─────────┘     └──────────────────┘                      │
-│           │                                                          │
-│           │ Messages                                                 │
-│           ▼                                                          │
+│           │                                                         │
+│           │ Messages                                                │
+│           ▼                                                         │
 │  ┌──────────────────────────────────────────────────────────────┐   │
-│  │                      Core Services                            │   │
+│  │                      Core Services                           │   │
 │  ├────────────┬────────────┬────────────┬───────────────────────┤   │
 │  │   Tools    │   Browser  │    MCP     │    Code Index         │   │
 │  │  Service   │   Session  │  Servers   │     Service           │   │
 │  └────────────┴────────────┴────────────┴───────────────────────┘   │
-│           │                                                          │
-│           │ API Calls                                                │
-│           ▼                                                          │
+│           │                                                         │
+│           │ API Calls                                               │
+│           ▼                                                         │
 │  ┌──────────────────────────────────────────────────────────────┐   │
-│  │                   API Provider Layer                          │   │
+│  │                   API Provider Layer                         │   │
 │  ├────────────┬────────────┬────────────┬───────────────────────┤   │
 │  │  Anthropic │   OpenAI   │   Kilo     │     OpenRouter        │   │
 │  │    API     │    API     │ Provider   │        API            │   │
 │  └────────────┴────────────┴────────────┴───────────────────────┘   │
-│                                                                      │
+│                                                                     │
 └─────────────────────────────────────────────────────────────────────┘
 ```
 
-## Key Components
+### Features
 
-### Extension Host (`src/`)
+These pages document the architecture and design of a current or planned feature, as well as any unique development patterns.
 
-The extension host runs in Node.js within VS Code and contains:
+| Feature                                                            | Description                                |
+| ------------------------------------------------------------------ | ------------------------------------------ |
+| [Annual Billing](./annual-billing.md)                              | Annual subscription billing                |
+| [Enterprise MCP Controls](./enterprise-mcp-controls.md)            | Admin controls for MCP server allowlists   |
+| [Onboarding Improvements](./onboarding-engagement-improvements.md) | User onboarding and engagement features    |
+| [Organization Modes Library](./organization-modes-library.md)      | Shared modes for teams and enterprise      |
+| [Agentic Security Reviews](./security-reviews.md)                  | AI-powered security vulnerability analysis |
+| [Track Repo URL](./track-repo-url.md)                              | Usage tracking by repository/project       |
+| [Vercel AI Gateway](./vercel-ai-gateway.md)                        | Vercel AI Gateway integration              |
+| [Voice Transcription](./voice-transcription.md)                    | Live voice input for chat                  |
 
-- **`src/core/`** - The agent loop and core logic
-    - `Kilo.ts` - Main agent class that orchestrates interactions
-    - `prompts/` - System prompts and prompt construction
-    - `tools/` - Tool implementations (file operations, search, etc.)
-- **`src/services/`** - Service implementations
-
-    - `browser/` - Puppeteer-based browser automation
-    - `checkpoints/` - Git-based state checkpoints
-    - `code-index/` - Codebase indexing and semantic search
-    - `mcp/` - Model Context Protocol server integration
-    - `commit-message/` - Git commit message generation
-
-- **`src/api/`** - API provider implementations
-
-    - Handles communication with AI providers
-    - Manages streaming responses
-    - Implements provider-specific features
-
-- **`src/activate/`** - Extension activation and command registration
-
-### Webview UI (`webview-ui/`)
-
-A React-based frontend that provides the chat interface:
-
-- Built with React and TypeScript
-- Uses VS Code's webview API
-- Communicates with extension host via message passing
-- Styled with Tailwind CSS
-
-### Shared Packages (`packages/`)
-
-Shared code used across the monorepo:
-
-- `@kilocode/types` - Shared TypeScript types
-- `@kilocode/telemetry` - Telemetry utilities
-
-### Applications (`apps/`)
-
-- `kilocode-docs` - This documentation site (Docusaurus)
-- `kilocode-website` - Marketing website
-
-### Command-Line Interface (`cli/`)
-
-A standalone CLI for running Kilo Code outside of VS Code.
+To propose a new feature design, consider using the [feature template](./feature-template.md).
 
 ## Key Concepts
 
@@ -191,5 +157,4 @@ The project uses:
 ## Further Reading
 
 - [Development Environment](/contributing/development-environment) - Setup guide
-- [Engineering Specs](/contributing/specs) - Technical specifications
 - [Tools Reference](/features/tools/tool-use-overview) - Available tools

apps/kilocode-docs/docs/contributing/specs/spec-onboarding-engagement-improvements.md → apps/kilocode-docs/docs/contributing/architecture/onboarding-engagement-improvements.md

@@ -1,9 +1,9 @@
 ---
 sidebar_position: 5
-title: "Spec: Improve Onboarding Flow"
+title: "Improve Onboarding Flow"
 ---
 
-# SPEC: Kilo Code Onboarding & User Engagement Improvements
+# Kilo Code Onboarding & User Engagement Improvements
 
 # Overview
 

apps/kilocode-docs/docs/contributing/specs/spec-organization-modes-library.md → apps/kilocode-docs/docs/contributing/architecture/organization-modes-library.md

@@ -1,9 +1,9 @@
 ---
 sidebar_position: 6
-title: "Spec: Organization Modes Library"
+title: "Organization Modes Library"
 ---
 
-# Spec: Organization Modes Library
+# Organization Modes Library
 
 # Overview
 

apps/kilocode-docs/docs/contributing/specs/spec-security-reviews.md → apps/kilocode-docs/docs/contributing/architecture/security-reviews.md

@@ -1,9 +1,9 @@
 ---
 sidebar_position: 7
-title: "Spec: Agentic Security Reviews"
+title: "Agentic Security Reviews"
 ---
 
-# SPEC: Agentic Security Reviews
+# Agentic Security Reviews
 
 ## Overview
 

apps/kilocode-docs/docs/contributing/specs/spec-track-repo-url.md → apps/kilocode-docs/docs/contributing/architecture/track-repo-url.md

@@ -1,9 +1,9 @@
 ---
 sidebar_position: 8
-title: "Spec: Track Usage by Repository URL"
+title: "Track Usage by Repository URL"
 ---
 
-# Spec: Track Usage by Project
+# Track Usage by Project
 
 # Overview
 

apps/kilocode-docs/docs/contributing/architecture/vercel-ai-gateway.md

@@ -0,0 +1,77 @@
+---
+sidebar_position: 9
+title: "Vercel AI Gateway"
+---
+
+# OpenRouter and Vercel AI Gateway API compatibility
+
+Both OpenRouter and Vercel AI Gateway provide an OpenAI-compatible API.
+They are largely compatible and Vercel even adopted some of OpenRouter's non-standard extensions.
+
+OpenRouter API docs: https://openrouter.ai/docs/api/reference/overview
+
+Vercel AI Gateway API docs: https://vercel.com/docs/ai-gateway/openai-compat
+
+At time of writing, OpenRouter provides beta support for the Responses API, but Vercel does not: https://openrouter.ai/docs/api/reference/responses/overview
+
+## Available models and identifiers
+
+OpenRouter has more models than Vercel. The naming scheme is similar, sometimes identical but not always. For example `x-ai/grok-code-fast-1` (OpenRouter) has a different prefix from `xai/grok-code-fast-1` (Vercel). We will have to come up with a mapping from OpenRouter to Vercel model identifiers.
+
+- https://openrouter.ai/models
+- https://vercel.com/ai-gateway/models
+
+## Reasoning
+
+Vercel seems to have adopted OpenRouter's (non-standard) reasoning configuration:
+
+- https://openrouter.ai/docs/api/reference/responses/reasoning#reasoning-configuration
+- https://vercel.com/docs/ai-gateway/openai-compat#reasoning-configuration
+
+Both Vercel and OpenRouter use the same `reasoning` property for reasoning content (the standard is `reasoning_content`, although our extension will accept both):
+
+- https://openrouter.ai/docs/api/api-reference/chat/send-chat-completion-request#response.body.choices.message.reasoning
+- https://vercel.com/docs/ai-gateway/openai-compat#response-format-with-reasoning
+
+Vercel supports OpenRouter's way of preserving reasoning details in the Chat Completions API:
+
+- https://openrouter.ai/docs/guides/best-practices/reasoning-tokens#preserving-reasoning-blocks
+- https://vercel.com/docs/ai-gateway/openai-compat#preserving-reasoning-details-across-providers
+
+Other providers would require use of the Responses API (e.g. xAI) or Anthropic API (e.g. MiniMax)
+
+## Provider configuration
+
+OpenRouter's and Vercel's provider configuration are different:
+
+- https://openrouter.ai/docs/guides/routing/provider-selection
+- https://vercel.com/docs/ai-gateway/openai-compat#provider-options
+
+We will likely support OpenRouter's and convert between the two.
+
+Inference provider identifiers appear similar at first glance, but they may not always be identical.
+
+## Cost calculation
+
+Whether Vercel includes cost in the response (like OpenRouter) is unclear. In the docs there's an embeddings example, which suggests that it does, but in a different format than OpenRouter:
+
+- https://vercel.com/docs/ai-gateway/openai-compat#embeddings
+
+We may have to estimate the cost in the extension instead.
+
+There's a generation endpoint, which looks very similar to OpenRouter's at first glance:
+
+- https://openrouter.ai/docs/api/api-reference/generations/get-generation
+- https://vercel.com/docs/ai-gateway/usage#generation-lookup
+
+# Deciding where to route traffic
+
+We want to route some traffic to Vercel, ideally just enough so we can be first place on both leaderboards. However, we will initially start with a small portion of traffic < 5% and will evaluate whether it make sense to increase volume.
+
+Vercel will also act as fallback if we encounter issues with OpenRouter (such as the issue with Grok Code Fast and OpenRouter recently). We need the ability to route certain providers and / or models to Vercel vs OpenRouter.
+
+Requests from the same user for the same model should go to the same gateway for caching purposes.
+
+We can randomize users to a gateway in a way similar to what was done for autocomplete: https://github.com/Kilo-Org/kilocode/pull/3857
+
+Since not all models are available on Vercel, some traffic will have to go to OpenRouter regardless.

apps/kilocode-docs/docs/contributing/specs/spec-voice-transcription.md → apps/kilocode-docs/docs/contributing/architecture/voice-transcription.md

@@ -1,9 +1,9 @@
 ---
 sidebar_position: 10
-title: "Spec: Live Voice Transcription"
+title: "Live Voice Transcription"
 ---
 
-# SPEC: Live Voice Transcription
+# Live Voice Transcription
 
 # Overview
 

apps/kilocode-docs/docs/contributing/index.md

@@ -24,7 +24,7 @@ Setting Up the Development Environment is described in details on the [Developme
 
 ## Understanding the Architecture
 
-Before diving into the code, we recommend reviewing the [Architecture Overview](/contributing/architecture) to understand how the different components of Kilo Code fit together.
+Before diving into the code, we recommend reviewing the [Architecture Overview](architecture) to understand how the different components of Kilo Code fit together.
 
 ## Development Workflow
 
@@ -82,7 +82,7 @@ git checkout -b your-branch-name
 
 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
+1. Follow the [Custom Modes documentation](/agent-behavior/custom-modes) to create your mode
 
 2. Test your mode thoroughly
 
@@ -90,7 +90,7 @@ Custom modes are a powerful way to extend Kilo Code's capabilities. To create an
 
 ## Engineering Specs
 
-For larger features, we write engineering specs to align on requirements before implementation. Check out the [Engineering Specs](/contributing/specs) section to see planned features and learn how to contribute specs.
+For larger features, we write engineering specs to align on requirements before implementation. Check out the [Architecture](/contributing/architecture) section to see planned features and learn how to contribute specs.
 
 ## Documentation Contributions
 

apps/kilocode-docs/docs/contributing/specs/index.md

@@ -1,48 +0,0 @@
----
-sidebar_position: 1
-title: "Engineering Specs"
----
-
-# Engineering Specs
-
-Engineering specs are technical documents that describe how we plan to implement features and solve problems. They help us align on requirements, communicate progress, and document our architectural decisions.
-
-## Why Write Specs?
-
-As the company gets bigger and gains adoption, it's important to evolve how we work together. There are more teams and more stakeholders than ever, and with that, more opportunities for mis-communication and untimely disagreements.
-
-Writing specs for reasonably complicated projects has many benefits:
-
-- Improves clarity of implementation
-- Reduces time to implementation
-    - Often times, after a spec is written, it's fed into an LLM to implement the changes
-- Allows for discussion (and maybe some healthy bike shedding) prior to implementation
-    - Importantly, aligns on requirements prior to implementation
-- Communicates upward and outward
-    - Helps leadership understand the progress of a project
-    - Helps teammates understand how various parts of our application is architected
-
-It is useful to start with an outline/template for specs. For that, refer to the [SPEC: Template](./spec-template.md) document.
-
-## Current Specs
-
-| Spec                                                                    | Description                                |
-| ----------------------------------------------------------------------- | ------------------------------------------ |
-| [Enterprise MCP Controls](./spec-enterprise-mcp-controls.md)            | Admin controls for MCP server allowlists   |
-| [Onboarding Improvements](./spec-onboarding-engagement-improvements.md) | User onboarding and engagement features    |
-| [Organization Modes Library](./spec-organization-modes-library.md)      | Shared modes for teams and enterprise      |
-| [Agentic Security Reviews](./spec-security-reviews.md)                  | AI-powered security vulnerability analysis |
-| [Track Repo URL](./spec-track-repo-url.md)                              | Usage tracking by repository/project       |
-| [Voice Transcription](./spec-voice-transcription.md)                    | Live voice input for chat                  |
-
-Private specs, for example backend non-user facing features, can be found on the [company handbook (Kilo internal)](https://handbook.kilo.ai/engineering/specs/why-specs).
-
-## Contributing a Spec
-
-If you're working on a significant feature, consider writing a spec:
-
-1. Copy the [Spec Template](./spec-template.md)
-2. Fill in the sections with your proposal
-3. Submit a PR for review
-4. Discuss and iterate with the team
-5. Once approved, create GitHub issues from the implementation plan

apps/kilocode-docs/docs/faq.md

@@ -24,7 +24,7 @@ Kilo Code uses large language models (LLMs) to understand your requests and tran
 - 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.
+You interact with Kilo Code through a chat interface, where you provide instructions and review/approve its proposed actions, or you can use the inline autocomplete feature which helps you as you type.
 
 ### What can Kilo Code do?
 
@@ -105,6 +105,25 @@ Yes, Kilo Code supports running models locally using [Ollama](/providers/ollama)
 
 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.
 
+### When should I use chat vs autocomplete?
+
+Use **chat** when you need to:
+
+- Make complex, multi-file changes
+- Refactor code across your project
+- Get explanations or ask questions
+- Have Kilo Code execute commands or browse the web
+- Work on tasks that require planning and multiple steps
+
+Use **autocomplete** when you need to:
+
+- Complete the current line or block of code quickly
+- Get suggestions for common patterns and boilerplate
+- Make quick, localized edits without context switching
+- Speed up typing repetitive code
+
+In general, autocomplete is best for quick, in-flow coding assistance, while chat is better for larger tasks that require more context and interaction.
+
 ### 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:
@@ -113,7 +132,7 @@ Open the Kilo Code panel (<img src="/docs/img/kilo-v1.svg" width="12" />) and ty
 - **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).
+  You can also create [Custom Modes](/agent-behavior/custom-modes).
 
 ### How do I switch between modes?
 

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

@@ -38,15 +38,15 @@ Note that available settings vary by provider and model. Each provider offers di
       <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" />
+                   <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" />
+                   <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" />
+                   <img src="/docs/img/api-configuration-profiles/api-configuration-profiles-5.png" alt="Model parameter adjustment controls" width="550" />
 
 ### Switching Profiles
 
@@ -98,7 +98,7 @@ API keys are stored securely in VSCode's Secret Storage and are never exposed in
 
 ## Related Features
 
-- Works with [custom modes](/features/custom-modes) you create
+- Works with [custom modes](/agent-behavior/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-launch-configuration.md

@@ -48,7 +48,7 @@ This happens seamlessly in the background, requiring no manual intervention.
     - `"ask"` - Questions and explanations
     - `"debug"` - Problem diagnosis and troubleshooting
     - `"test"` - Testing-focused workflows
-    - Custom mode slugs (if you have [custom modes](/features/custom-modes))
+    - Custom mode slugs (if you have [custom modes](/agent-behavior/custom-modes))
 
 ## Example Configurations
 

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

@@ -4,6 +4,15 @@ import Image from '@site/src/components/Image';
 
 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.
 
+:::tip Code Actions vs Autocomplete
+**Code Actions** and **Autocomplete** are two different ways Kilo Code can assist you:
+
+- **Code Actions** (this page) are **explicit and user-triggered**. You invoke them via the lightbulb icon, right-click context menu, or keyboard shortcut (`Ctrl+.` / `Cmd+.`). They operate on selected code and open a conversation in the chat panel.
+- **[Autocomplete](/basic-usage/autocomplete)** is **inline and automatic**. It suggests completions as you type, appearing as ghost text directly in the editor. You accept suggestions with `Tab`.
+
+Use Code Actions when you want to explain, fix, or improve existing code. Use Autocomplete when you want AI to help you write new code as you type.
+:::
+
 ## 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:

apps/kilocode-docs/docs/features/mcp/using-mcp-in-cli.md

@@ -0,0 +1,109 @@
+---
+title: Using MCP in the CLI
+sidebar_label: Using MCP in CLI
+---
+
+# Using MCP in the CLI
+
+The Kilo Code CLI supports MCP servers, but uses a **different configuration path** than the VS Code extension.
+
+## Configuration Location
+
+| Environment | MCP Settings Path                                   |
+| ----------- | --------------------------------------------------- |
+| **CLI**     | `~/.kilocode/cli/global/settings/mcp_settings.json` |
+| **VS Code** | VS Code's global storage directory                  |
+
+MCP servers configured in VS Code are **not** automatically available in the CLI. You must configure them separately.
+
+## Configuration Format
+
+Edit `~/.kilocode/cli/global/settings/mcp_settings.json`:
+
+```json
+{
+	"mcpServers": {
+		"server-name": {
+			"command": "node",
+			"args": ["/path/to/server.js"],
+			"env": {
+				"API_KEY": "your_api_key"
+			},
+			"alwaysAllow": ["tool1", "tool2"],
+			"disabled": false
+		}
+	}
+}
+```
+
+## Transport Types
+
+### STDIO (Local Servers)
+
+```json
+{
+	"mcpServers": {
+		"local-server": {
+			"command": "node",
+			"args": ["/path/to/server.js"],
+			"env": {}
+		}
+	}
+}
+```
+
+### Streamable HTTP (Remote Servers)
+
+```json
+{
+	"mcpServers": {
+		"remote-server": {
+			"type": "streamable-http",
+			"url": "https://your-server.com/mcp",
+			"headers": {
+				"Authorization": "Bearer token"
+			}
+		}
+	}
+}
+```
+
+## Project-Level Configuration
+
+You can define MCP servers per-project by creating `.kilocode/mcp.json` in your project root. Project-level servers take precedence over global settings.
+
+## Configuration Options
+
+| Option        | Description                                                 |
+| ------------- | ----------------------------------------------------------- |
+| `command`     | Executable to run (STDIO)                                   |
+| `args`        | Command arguments (STDIO)                                   |
+| `env`         | Environment variables                                       |
+| `type`        | Transport type: `stdio` (default), `streamable-http`, `sse` |
+| `url`         | Server URL (HTTP transports)                                |
+| `headers`     | HTTP headers (HTTP transports)                              |
+| `alwaysAllow` | Array of tool names to auto-approve                         |
+| `disabled`    | Set `true` to disable without removing                      |
+| `timeout`     | Request timeout in seconds (default: 60)                    |
+
+## Auto-Approval
+
+MCP auto-approval is controlled via CLI config (`kilocode config`):
+
+```json
+{
+	"autoApproval": {
+		"mcp": {
+			"enabled": true
+		}
+	}
+}
+```
+
+Or via environment variable:
+
+```bash
+export KILO_AUTO_APPROVAL_MCP_ENABLED=true
+```
+
+Per-tool auto-approval uses the `alwaysAllow` array in the server configuration.

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

@@ -89,5 +89,5 @@ Remember that different models may respond differently to the same temperature v
 ## 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
+- Complements [custom instructions](/agent-behavior/custom-instructions) for fine-tuning responses
+- Works alongside [custom modes](/agent-behavior/custom-modes) you create

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

@@ -30,6 +30,13 @@ Type a clear, concise description of what you want Kilo Code to do in the chat b
 
 No special commands or syntax needed—just use plain English.
 
+<details>
+<summary>💡 Optional: Try Autocomplete</summary>
+
+While chat is great for complex tasks, Kilo Code also offers **inline autocomplete** for quick code suggestions. Open any code file, start typing, and watch for ghost text suggestions. Press `Tab` to accept. [Learn more about Autocomplete →](/basic-usage/autocomplete)
+
+</details>
+
 <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.*
 
@@ -76,4 +83,8 @@ You've completed your first task. Along the way you learned:
 - 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.
+Ready for more? Here are some next steps:
+
+- **[Autocomplete](/basic-usage/autocomplete)** — Get inline code suggestions as you type
+- **[Modes](/basic-usage/using-modes)** — Explore different modes for different tasks
+- **[Auto-approval](/features/auto-approving-actions)** — Speed up repetitive tasks

apps/kilocode-docs/docs/index.mdx

@@ -23,12 +23,14 @@ Kilo Code **accelerates** development with AI-driven code generation and task au
 - 🤔 **Answer Questions** about your codebase
 - 🔄 **Automate** repetitive tasks
 - 🏗️ **Create** new files and projects
+- ⚡ **Autocomplete** code as you type with AI-powered suggestions
 
 ## 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)
+4. [Enable Autocomplete](/basic-usage/autocomplete) for inline code suggestions
 
 ## Features
 
@@ -40,7 +42,7 @@ Kilo Code **accelerates** development with AI-driven code generation and task au
 
 ### 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.
+Use [the chat interface](/basic-usage/the-chat-interface) to tell Kilo Code what you need, or let [Autocomplete](/basic-usage/autocomplete) suggest code as you type. 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)
@@ -56,7 +58,7 @@ Kilo Code adapts to your needs with specialized [modes](/basic-usage/using-modes
 - [**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
+- **[Custom Modes](/agent-behavior/custom-modes):** Create unlimited specialized personas for security auditing, performance optimization, documentation, or any other task
 
 #### Core Tools
 
@@ -79,10 +81,10 @@ See the complete [Tools Reference](/features/tools/tool-use-overview) for all av
 
 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
+- [Settings Management](/basic-usage/settings-management) for configuring your experience
+- [Custom Modes](/agent-behavior/custom-modes) for specialized tasks
+- [Custom Rules](/agent-behavior/custom-rules) for project-specific rules
+- [Custom Instructions](/agent-behavior/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
 
@@ -91,8 +93,9 @@ Make Kilo Code work your way with:
 ### Documentation
 
 - [Using Kilo Code](/basic-usage/the-chat-interface) - Learn the basics
+- [Autocomplete](/basic-usage/autocomplete) - Get AI-powered code suggestions as you type
 - [Core Concepts](/features/auto-approving-actions) - Master key features
-- [Advanced Usage](/advanced-usage/prompt-engineering) - Take your skills further
+- [Advanced Usage](/agent-behavior/prompt-engineering) - Take your skills further
 - [Frequently Asked Questions](/faq) - Get answers to common questions
 
 ### Community

apps/kilocode-docs/docs/plans/adoption-dashboard/for-team-leads.md

@@ -0,0 +1,239 @@
+---
+sidebar_label: For Team Leads
+---
+
+# AI Adoption Dashboard for Team Leads
+
+This guide covers how engineering managers and team leads can use the AI Adoption Dashboard to drive AI integration, identify gaps, and communicate progress to stakeholders.
+
+## Reading Team-Wide Metrics
+
+### The Organization View
+
+Disable the **"Only my usage"** toggle to see aggregated metrics across your entire team. This view shows:
+
+- **Overall AI Adoption Score** — Your single benchmark number
+- **Dimension breakdown** — Frequency, Depth, and Coverage contributions
+- **Week-over-week trends** — Direction and magnitude of change
+- **Historical timeline** — Score progression over days, weeks, or months
+
+### Dimension Detail Panels
+
+Click on any dimension card (Frequency, Depth, or Coverage) to open its detail panel. Each panel provides:
+
+- A focused timeline for that dimension
+- The goal statement for that dimension
+- Three actionable improvement suggestions tailored to what that dimension measures
+
+Use these panels to diagnose specific issues and identify targeted actions.
+
+### Comparing Time Periods
+
+Switch between time filters to understand different patterns:
+
+| Filter         | Best For                                         |
+| -------------- | ------------------------------------------------ |
+| **Past Week**  | Recent changes, sprint-level trends              |
+| **Past Month** | Adoption initiative tracking, onboarding results |
+| **Past Year**  | Long-term trends, seasonal patterns              |
+| **All**        | Historical baseline, major milestones            |
+
+---
+
+## Identifying Adoption Gaps
+
+### Low Coverage Signals
+
+A low Coverage score often indicates adoption gaps—pockets of your team that aren't using AI.
+
+**Questions to investigate:**
+
+- Are all team members logged in and active?
+- Are certain roles or squads under-represented?
+- Is usage concentrated on specific days (spiky pattern)?
+
+**Actions:**
+
+1. Check your Organization Dashboard for inactive seats
+2. Look for patterns in who's not using AI (new hires? certain roles?)
+3. Consider targeted onboarding or pairing sessions
+
+### Low Depth Signals
+
+Low Depth indicates that developers may be trying AI but not trusting or shipping its output.
+
+**Questions to investigate:**
+
+- Are acceptance rates low? (Developers rejecting suggestions)
+- Is AI-generated code being merged?
+- Are developers using AI across multiple stages (plan → build → review)?
+
+**Actions:**
+
+1. Enable [Managed Indexing](/advanced-usage/managed-indexing) to improve context quality
+2. Review whether suggestions are relevant to your codebase
+3. Introduce chained workflows to increase multi-stage usage
+
+### Low Frequency Signals
+
+Low Frequency suggests AI hasn't become a daily habit.
+
+**Questions to investigate:**
+
+- Are developers aware of all available AI surfaces (IDE, CLI, Cloud)?
+- Is AI usage triggered only by specific, infrequent problems?
+- Have developers built AI into routine tasks?
+
+**Actions:**
+
+1. Map AI to existing daily tasks (stand-ups, PRs, documentation)
+2. Ensure the CLI is installed for terminal workflows
+3. Run a "try autocomplete for a week" challenge
+
+---
+
+## Running Adoption Initiatives
+
+### Setting Goals
+
+Use the score tiers as milestones:
+
+| Current Tier    | Reasonable Next Goal         |
+| --------------- | ---------------------------- |
+| 0–20 (Minimal)  | Reach 30–40 within 4–6 weeks |
+| 21–50 (Early)   | Reach 55–65 within 4–6 weeks |
+| 51–75 (Growing) | Reach 75–80 within 6–8 weeks |
+| 76–90 (Strong)  | Maintain and optimize        |
+
+**Tip:** Focus on one dimension at a time rather than trying to improve everything at once.
+
+### Initiative Ideas
+
+**For Frequency:**
+
+- "Autocomplete Week" — Everyone commits to using autocomplete daily
+- CLI onboarding session — 30-minute walkthrough of terminal AI
+- Daily AI tip in Slack — Share one use case per day
+
+**For Depth:**
+
+- "Chain Challenge" — Complete one feature using plan → build → review
+- Managed Indexing rollout — Enable better context for the whole team
+- Deploy previews — Validate AI output before merging
+
+**For Coverage:**
+
+- New hire onboarding includes Kilo setup
+- Weekly "AI wins" sharing in stand-ups
+- Pair low-usage developers with enthusiastic adopters
+
+### Tracking Progress
+
+1. **Set a baseline** — Note your score at the start of an initiative
+2. **Check weekly** — Watch for trend changes, not absolute numbers
+3. **Adjust tactics** — If a dimension isn't moving, try a different approach
+4. **Celebrate wins** — Acknowledge when the team hits a milestone
+
+---
+
+## Benchmarking Against Goals
+
+### Internal Benchmarking
+
+Use the score to compare:
+
+- **Teams within your organization** — Which teams are leading adoption?
+- **Before vs. after** — Did a specific initiative move the needle?
+- **This quarter vs. last** — Are you trending up or down?
+
+### Communicating to Stakeholders
+
+The AI Adoption Score is designed to be quotable:
+
+> "Last quarter we were at 38. This quarter we're at 57. Our goal is to reach 70 by Q2."
+
+**When presenting scores:**
+
+- Lead with the trend, not just the number
+- Explain the tier and what it means
+- Connect to business outcomes ("Higher adoption → faster development cycles")
+- Share specific actions you're taking
+
+### Sample Stakeholder Update
+
+> **AI Adoption Update — January 2025**
+>
+> - **Current Score:** 57 (Growing adoption tier)
+> - **Last Month:** 48
+> - **Change:** +9 points, driven by improved Depth scores
+>
+> **Key Actions Taken:**
+>
+> - Enabled Managed Indexing for better AI context
+> - Introduced Code Reviews for all PRs
+> - Onboarded 3 inactive team members
+>
+> **Next Steps:**
+>
+> - Target 65 by end of February
+> - Focus on Coverage—spread usage across the full week
+
+---
+
+## Privacy and Data Considerations
+
+### Anonymous Data
+
+Individual usage data is anonymized in the dashboard. While you can see aggregate metrics, the dashboard does not expose individual developer activity to managers.
+
+### Focus on Teams, Not Individuals
+
+The Dashboard is designed for:
+
+- Team-level insights
+- Organizational trends
+- Comparative benchmarking
+
+It is **not** designed for:
+
+- Individual performance evaluation
+- Identifying specific low performers
+- Surveillance of developer activity
+
+Use the score to identify adoption **gaps**, not to judge individual developers.
+
+---
+
+## Future Enhancements
+
+### Code Contribution Tracking
+
+A future enhancement will track AI-contributed code from feature branch to main branch:
+
+- What percentage of AI-suggested code actually ships?
+- How much of the codebase was AI-assisted?
+
+This metric is separate from the Adoption Score but valuable for measuring AI impact on output.
+
+### Team Comparison Views
+
+Additional views for comparing multiple teams within an organization are planned, enabling leadership to identify best practices from high-performing teams.
+
+---
+
+## Quick Reference: Dashboard Actions
+
+| What You Want to Know        | Where to Look                               |
+| ---------------------------- | ------------------------------------------- |
+| Overall adoption level       | Main score display                          |
+| Which dimension needs work   | Trend indicators (look for negative trends) |
+| Specific improvement actions | Click dimension → detail panel              |
+| Historical patterns          | Timeline chart with time filter             |
+| Your personal usage          | Toggle "Only my usage"                      |
+| Week-over-week change        | Metric cards at bottom                      |
+
+## Next Steps
+
+- [Understand what each dimension measures](/plans/adoption-dashboard/understanding-your-score)
+- [Learn strategies to improve your score](/plans/adoption-dashboard/improving-your-score)
+- [Return to the dashboard overview](/plans/adoption-dashboard/overview)

apps/kilocode-docs/docs/plans/adoption-dashboard/improving-your-score.md

@@ -0,0 +1,193 @@
+---
+sidebar_label: Improving Your Score
+---
+
+# Improving Your AI Adoption Score
+
+This guide provides actionable strategies to improve each dimension of your AI Adoption Score. Click on any dimension in the dashboard to see personalized suggestions based on your team's usage patterns.
+
+## Improving Frequency
+
+**Goal:** Help developers build AI into their daily workflow, not just reach for it on hard problems.
+
+### Expand Beyond the IDE
+
+A lot of development work happens in the terminal—git operations, debugging, scripting. Bringing AI to those contexts increases daily touchpoints.
+
+**Action:** Install the Kilo CLI to enable AI-assisted terminal workflows:
+
+```bash
+npm install -g @kilocode/cli
+```
+
+Teams that use both IDE and CLI surfaces tend to show higher daily engagement because AI is available wherever they're working.
+
+### Start with Autocomplete
+
+Autocomplete is low-friction by design. It doesn't require explicit prompting—it just works in the background.
+
+**Action:** Encourage your team to lean on autocomplete for:
+
+- Boilerplate code
+- Repetitive patterns
+- Common syntax
+- Test scaffolding
+
+Building muscle memory with autocomplete leads to consistent daily usage without requiring behavior change.
+
+### Tie AI to Existing Routines
+
+The teams with the strongest Frequency scores usually aren't doing anything flashy—they've woven AI into things they already do.
+
+**Action:** Identify daily tasks where AI can help:
+
+- **Stand-up prep** — Summarize recent changes or generate status updates
+- **Context checks** — Quickly understand unfamiliar code
+- **PR descriptions** — Generate first drafts of pull request descriptions
+- **Documentation** — Create or update inline comments
+
+Small, repeated use cases add up faster than occasional heavy lifts.
+
+---
+
+## Improving Depth
+
+**Goal:** Move AI from a side tool to an integrated part of how your team ships code.
+
+### Chain Your Workflows
+
+Depth increases when AI touches multiple stages of the same task. Each handoff reinforces context and keeps AI in the loop from idea to merge.
+
+**Action:** Adopt the "chain" workflow pattern:
+
+1. **Plan** — Use Architect mode to design a feature
+2. **Build** — Use Code mode to implement it
+3. **Review** — Use Code Reviews to critique it
+
+:::tip
+Linking coding → review → deploy actions significantly boosts your Depth score.
+:::
+
+### Give AI Better Context
+
+If acceptance rates are low, the issue is often context. The AI is making suggestions without understanding your codebase.
+
+**Action:** Enable [Managed Indexing](/advanced-usage/managed-indexing) to give the model vector-backed search across your repository.
+
+Better context leads to:
+
+- More relevant suggestions
+- Higher acceptance rates
+- Greater trust in AI output
+- Deeper integration over time
+
+### Validate AI Output in Real Environments
+
+Generated code that never runs is hard to trust. Teams that can verify AI output against live environments tend to retain more of that code long-term.
+
+**Action:** Use [Kilo Deploy](/advanced-usage/deploy) to spin up live URLs for branches, allowing your team to verify changes before merging.
+
+---
+
+## Improving Coverage
+
+**Goal:** Get more of your team using more of the platform.
+
+### Introduce Specialist Agents
+
+Most teams start with Code mode and stop there. But Kilo's other modes unlock additional value.
+
+**Action:** Introduce your team to specialized modes:
+
+| Mode             | Use Case                                                 |
+| ---------------- | -------------------------------------------------------- |
+| **Orchestrator** | Delegate and execute subtasks over long-horizon projects |
+| **Architect**    | Design and plan before implementation                    |
+| **Debug**        | Systematic error diagnosis                               |
+| **Ask**          | Quick questions and explanations                         |
+
+This increases efficacy and improves trust in AI-facilitated tasking.
+
+### Activate Unused Seats
+
+Coverage is partly a numbers game. If you have team members who haven't logged in or aren't using the tool, your score will reflect that.
+
+**Action:** Check your Organization Dashboard for inactive seats. Consider whether those team members need:
+
+- A reminder that access exists
+- A walkthrough or onboarding session
+- Guidance on where to start
+- Pairing with an enthusiastic team member
+
+### Spread Usage Across the Week
+
+Spiky usage—heavy on Mondays, quiet the rest of the week—limits your Coverage score.
+
+**Action:** Make [Code Reviews](/advanced-usage/code-reviews) part of your PR process. Reviews happen throughout the week, so AI usage naturally follows.
+
+Other ways to spread usage:
+
+- Daily stand-up preparation with AI
+- End-of-day documentation or commit messages
+- Mid-week design reviews using Architect mode
+
+---
+
+## Common Patterns and Anti-Patterns
+
+### Patterns That Drive Adoption
+
+| Pattern                          | Why It Works                                       |
+| -------------------------------- | -------------------------------------------------- |
+| **Pair AI with existing tools**  | Developers don't have to learn new workflows       |
+| **Start with quick wins**        | Autocomplete and commit messages build confidence  |
+| **Champion-led adoption**        | Enthusiastic team members model effective usage    |
+| **Weekly check-ins on AI usage** | Keeps AI top-of-mind without being prescriptive    |
+| **Celebrate retained code**      | Recognize when AI contributions ship to production |
+
+### Anti-Patterns to Avoid
+
+| Anti-Pattern                        | Why It Fails                                  |
+| ----------------------------------- | --------------------------------------------- |
+| **Mandating specific usage levels** | Creates resentment without changing habits    |
+| **Focusing only on power users**    | Neglects the majority who need onboarding     |
+| **Ignoring context quality**        | Leads to poor suggestions and abandoned usage |
+| **Measuring without acting**        | Scores drop when no one addresses gaps        |
+| **All-or-nothing adoption**         | Teams need gradual, sustainable change        |
+
+---
+
+## Quick Wins by Score Range
+
+### If You're at 0–20 (Minimal Adoption)
+
+1. Ensure all team members have access and are logged in
+2. Run a 30-minute "Getting Started" session
+3. Ask everyone to try autocomplete for one week
+4. Check back on completion rates
+
+### If You're at 21–50 (Early Adoption)
+
+1. Identify your most active users and learn what they're doing
+2. Introduce Code Reviews to spread usage
+3. Enable Managed Indexing for better context
+4. Set a monthly score goal (e.g., "reach 55 by next month")
+
+### If You're at 51–75 (Growing Adoption)
+
+1. Introduce chained workflows (plan → build → review)
+2. Focus on Depth—are suggestions being accepted and retained?
+3. Address any inactive seats or low-usage pockets
+4. Consider Kilo Deploy to validate AI output
+
+### If You're at 76–90 (Strong Adoption)
+
+1. You're doing well—maintain momentum
+2. Look at retention rates: what percentage of AI code ships unaltered?
+3. Expand to edge cases: CI/CD, documentation, testing
+4. Share your practices with other teams
+
+## Next Steps
+
+- [Use the dashboard for team leadership](/plans/adoption-dashboard/for-team-leads)
+- [Return to the dashboard overview](/plans/adoption-dashboard/overview)

apps/kilocode-docs/docs/plans/adoption-dashboard/overview.md

@@ -0,0 +1,96 @@
+---
+sidebar_label: AI Adoption Dashboard
+---
+
+# AI Adoption Dashboard
+
+The AI Adoption Dashboard helps engineering leaders understand how deeply and consistently their teams are using AI across development workflows. It provides a single **AI Adoption Score** (0–100) that quantifies organizational AI maturity, plus detailed breakdowns by dimension.
+
+<img src="/docs/img/ai-adoption/adoption-dashboard.png" alt="Monthly view of the AI Adoption Dashboard"  />
+
+## Who Is It For?
+
+This dashboard is designed for **team leads, engineering managers, and executives** who want to:
+
+- Track AI integration progress across their organization
+- Compare teams using a single benchmark number
+- Identify low-, medium-, and high-adoption teams
+- Quote a simple metric to stakeholders ("We're at 63; we want to be at 80")
+
+## Accessing the Dashboard
+
+1. Navigate to [app.kilo.ai](https://app.kilo.ai) and sign in
+2. Select your organization
+3. Click the **Usage** tab in the dashboard navigation
+4. The AI Adoption Score card appears at the top of the usage view
+
+## Dashboard Overview
+
+### Main Score Display
+
+The dashboard prominently displays your current AI Adoption Score as a percentage (e.g., "Current: 45%"). This score represents how deeply and consistently your organization uses AI across real development workflows.
+
+### Timeline Visualization
+
+<img src="/docs/img/ai-adoption/stacked-chart.png" alt="Monthly view of the AI Adoption Dashboard" width="300"  />
+
+A stacked bar chart shows your daily adoption scores over time. The chart uses three colors representing the score's dimensions:
+
+- **Blue** — Frequency (how often developers use AI)
+- **Green** — Depth (how integrated AI is into development)
+- **Orange** — Coverage (how broadly AI is adopted across the team)
+
+### Time Period Filters
+
+Filter the data by selecting:
+
+- **Past Week** — Last 7 days
+- **Past Month** — Last 30 days
+- **Past Year** — Last 365 days
+- **All** — Complete history
+
+### Personal vs. Organization View
+
+Use the **"Only my usage"** toggle to switch between:
+
+- **Enabled** — Your individual adoption metrics
+- **Disabled** — Organization-wide adoption metrics
+
+### Trend Indicators
+
+Four metric cards at the bottom of the dashboard show week-over-week changes:
+
+- **Total** — Overall score trend
+- **Frequency** — Changes in usage frequency
+- **Depth** — Changes in integration depth
+- **Coverage** — Changes in team-wide adoption
+
+Each card displays the percentage change (e.g., "+2.3%" or "-1.5%") with a directional indicator.
+
+## The Three Dimensions
+
+The AI Adoption Score is composed of three weighted dimensions:
+
+| Dimension     | Weight | Question It Answers                              |
+| ------------- | ------ | ------------------------------------------------ |
+| **Frequency** | 40%    | How often do developers use AI?                  |
+| **Depth**     | 40%    | How integrated is AI into actual development?    |
+| **Coverage**  | 20%    | How broadly is AI being adopted across the team? |
+
+Click on any dimension card to view detailed analysis and improvement suggestions specific to that dimension.
+
+## Quick Reference: Score Tiers
+
+| Score Range | Tier                     | Description                              |
+| ----------- | ------------------------ | ---------------------------------------- |
+| 0–20        | Minimal adoption         | AI usage is sporadic or experimental     |
+| 21–50       | Early adoption           | Some developers are using AI regularly   |
+| 51–75       | Growing adoption         | AI is becoming part of team workflows    |
+| 76–90       | Strong adoption          | AI is deeply integrated into development |
+| 91–100      | AI-first engineering org | AI is central to how the team ships code |
+
+## Next Steps
+
+- [Understand what each dimension measures](/plans/adoption-dashboard/understanding-your-score)
+- [Learn strategies to improve your score](/plans/adoption-dashboard/improving-your-score)
+- [Use the dashboard for team leadership](/plans/adoption-dashboard/for-team-leads)

apps/kilocode-docs/docs/plans/adoption-dashboard/understanding-your-score.md

@@ -0,0 +1,150 @@
+---
+sidebar_label: Understanding Your Score
+---
+
+# Understanding Your AI Adoption Score
+
+The AI Adoption Score is a 0–100 metric representing how deeply and consistently your team uses AI across real development workflows. This page explains what each dimension measures and how to interpret your score.
+
+## The Three Dimensions
+
+Your total score is calculated from three weighted dimensions:
+
+### Frequency (40% of total score)
+
+**"How often do developers use AI?"**
+
+This dimension measures the regularity of AI tool usage across your team, normalized per-user and blended across the organization.
+
+<img src="/docs/img/ai-adoption/frequency.png" alt="Frequency view of the AI Adoption Dashboard" width="600" />
+
+**Signals measured:**
+
+- Agent interactions per day
+- Autocomplete acceptance
+- Cloud Agent sessions
+- Reviewer Agent runs
+
+**What it tells you:** Teams with high Frequency scores have made AI a daily habit—not something they reach for only on difficult problems. Low Frequency often indicates that developers haven't yet built AI into their regular workflow.
+
+### Depth (40% of total score)
+
+**"How integrated is AI into actual development?"**
+
+This dimension captures trust and dependency—whether AI is a side tool or an integral part of how your team ships code.
+
+<img src="/docs/img/ai-adoption/depth.png" alt="Depth view of the AI Adoption Dashboard" width="600" />
+
+**Signals measured:**
+
+- Queries per hour worked
+- Percentage of AI suggestions accepted
+- AI-generated lines merged into the codebase
+- **Retention rate:** Percentage of AI-suggested lines merged unaltered
+- Multi-agent chains (coding → review → deploy)
+
+**What it tells you:** High Depth scores indicate that developers trust AI output enough to ship it. Low Depth may mean developers are experimenting with AI but not adopting its suggestions, which could signal context or quality issues.
+
+### Coverage (20% of total score)
+
+**"How broadly is AI being adopted across the team?"**
+
+This dimension captures reach and rollout—how many team members are using AI and how consistently throughout the week.
+
+<img src="/docs/img/ai-adoption/coverage.png" alt="Coverage view of the AI Adoption Dashboard" width="600" />
+
+**Signals measured:**
+
+- Percentage of users using any AI agent weekly
+- Percentage of users adopting 2+ agents
+- Percentage adopting 4+ agents
+- Weekday usage breadth (usage throughout the week vs. concentrated on specific days)
+
+**What it tells you:** Coverage reveals adoption gaps. A team might have power users driving high Frequency and Depth scores while other team members barely use AI at all.
+
+## Score Tiers
+
+Your score falls into one of five tiers:
+
+| Score Range | Tier                     | What It Means                                                                                               |
+| ----------- | ------------------------ | ----------------------------------------------------------------------------------------------------------- |
+| **0–20**    | Minimal adoption         | AI usage is sporadic or experimental. Most developers aren't using AI tools regularly.                      |
+| **21–50**   | Early adoption           | Some developers have incorporated AI into their workflow, but it's not yet team-wide.                       |
+| **51–75**   | Growing adoption         | AI is becoming a standard part of how the team works. Most developers use it, though depth varies.          |
+| **76–90**   | Strong adoption          | AI is deeply integrated into development workflows. Teams at this level trust and depend on AI suggestions. |
+| **91–100**  | AI-first engineering org | AI is central to how the team ships code. Usage is high, broad, and deeply integrated.                      |
+
+## How Scores Are Calculated
+
+The scoring system applies several normalization techniques to produce meaningful, comparable scores:
+
+### Per-Developer Normalization
+
+Usage is normalized on a per-developer basis. This means a 10-person team using AI moderately will score comparably to a 50-person team using AI moderately—raw volume doesn't inflate scores.
+
+### Outlier Capping
+
+Extreme usage by individual power users is capped to prevent a single enthusiastic developer from skewing the entire team's score.
+
+### Rolling Window
+
+Scores use a **weekly rolling window** for stability. This smooths out day-to-day fluctuations while still responding to real changes in behavior.
+
+### Multi-Source Aggregation
+
+The score aggregates event streams from multiple surfaces:
+
+- **IDE** — Autocomplete and coding agent interactions
+- **CLI** — Terminal-based AI usage
+- **Reviewer Agent** — AI-assisted code reviews
+- **Cloud Agent** — Browser-based AI sessions
+
+## Why Scores Fluctuate
+
+Your score may change from week to week for several reasons:
+
+**Normal fluctuations:**
+
+- Team members on vacation or leave
+- End-of-sprint vs. start-of-sprint patterns
+- Seasonal variations (holidays, summer slowdowns)
+
+**Meaningful changes:**
+
+- New team members onboarding (may temporarily lower Coverage)
+- Team members leaving the organization
+- Changes in development workflow or tooling
+- Successful adoption initiatives
+
+## Interpreting Your Score
+
+### Focus on Trends, Not Absolutes
+
+The exact number matters less than the direction. A score of 45 means "early adoption, room to grow"—but whether that's good or bad depends on where you were last month and where you're headed.
+
+### Compare Dimensions
+
+If your total score is low, look at which dimension is pulling it down:
+
+- **Low Frequency?** Focus on building daily habits
+- **Low Depth?** Work on trust and context quality
+- **Low Coverage?** Focus on onboarding and activation
+
+### Distribution Over Average
+
+While the dashboard shows aggregate scores, the real insight often comes from understanding distribution. A team with a 50 score might have half the team at 80+ and half at 20—that's different from everyone at 50.
+
+## What About Individual Scores?
+
+Individual user scores are available through the "Only my usage" toggle. However, the real value of the AI Adoption Score is in:
+
+- **Aggregate team metrics** — Understanding organizational trends
+- **Distribution analysis** — Identifying adoption gaps
+- **Comparative benchmarking** — Setting and tracking goals
+
+Individual scores are most useful for personal development and self-assessment, not performance evaluation.
+
+## Next Steps
+
+- [Learn strategies to improve each dimension](/plans/adoption-dashboard/improving-your-score)
+- [Use the dashboard for team leadership](/plans/adoption-dashboard/for-team-leads)

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

@@ -4,7 +4,7 @@ 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.
+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. This provider connects directly to AWS Bedrock and authenticates with the provided credentials.
 
 **Website:** [https://aws.amazon.com/bedrock/](https://aws.amazon.com/bedrock/)
 
@@ -20,13 +20,16 @@ Kilo Code supports accessing models through Amazon Bedrock, a fully managed serv
 
 ## Getting Credentials
 
-You have two main options for configuring AWS credentials:
+You have three options for configuring AWS credentials:
 
-1.  **AWS Access Keys (Recommended for Development):**
+1.  **Bedrock API Key:**
+    - Create a Bedrock-specific API key in the AWS Console. This is a simple service-specific authentication method.
+    - See the [AWS documentation on Bedrock credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_bedrock.html) for instructions on creating an API key.
+2.  **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:**
+3.  **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
@@ -75,6 +78,8 @@ Refer to the [Amazon Bedrock documentation](https://docs.aws.amazon.com/bedrock/
 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:**
+    - **Bedrock API Key:**
+        - Enter your Bedrock API key directly. This is the simplest setup option.
     - **AWS Credentials:**
         - Enter your "AWS Access Key" and "AWS Secret Key."
         - (Optional) Enter your "AWS Session Token" if you're using temporary credentials.

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

@@ -20,7 +20,8 @@ Cerebras is known for their ultra-fast AI inference powered by the Cerebras CS-3
 Kilo Code supports the following Cerebras models:
 
 - `gpt-oss-120b` (Default) – High-performance open-source model optimized for fast inference
-- `zai-glm-4.6` – Advanced GLM model with enhanced reasoning capabilities
+- `zai-glm-4.6` – Fast general-purpose model on Cerebras (up to 1,000 tokens/s). To be deprecated soon.
+- `zai-glm-4.7` – Highly capable general-purpose model on Cerebras (up to 1,000 tokens/s), competitive with leading proprietary models on coding tasks.
 
 Refer to the [Cerebras documentation](https://docs.cerebras.ai/) for detailed information on model capabilities and performance characteristics.
 

apps/kilocode-docs/docs/advanced-usage/slackbot.md → apps/kilocode-docs/docs/slack.md

@@ -1,15 +1,15 @@
 ---
-title: Kilo Slackbot
-sidebar_label: Kilo Slackbot
+title: Kilo for Slack
+sidebar_label: Kilo for Slack
 ---
 
-# Kilo Slackbot
+# Kilo for Slack
 
-The Kilo Slackbot brings the power of Kilo Code directly into your Slack workspace. Ask questions about your repositories, request code implementations, or get help with issues—all without leaving Slack.
+Kilo for Slack brings the power of Kilo Code directly into your Slack workspace. Ask questions about your repositories, request code implementations, or get help with issues—all without leaving Slack.
 
 ---
 
-## What You Can Do With the Slackbot
+## What You Can Do With Kilo for Slack
 
 - **Ask questions about your repositories** — Get explanations about code, architecture, or implementation details
 - **Request code implementations** — Tell the bot to implement fixes or features suggested in Slack threads
@@ -20,26 +20,27 @@ The Kilo Slackbot brings the power of Kilo Code directly into your Slack workspa
 
 ## Prerequisites
 
-Before using the Kilo Slackbot:
+Before using Kilo for Slack:
 
 - You must have a **Kilo Code account** with available credits
-- Your **GitHub Integration must be configured** via the [Integrations tab](https://app.kilo.ai/integrations) so the Slackbot can access your repositories 
+- Your **GitHub Integration must be configured** via the [Integrations tab](https://app.kilo.ai/integrations) so Kilo can access your repositories
 
-To install the Kilo Slackbot, simply go to the integrations menu in the sidebar on https://app.kilo.ai and set up the Slack integration.
+To install Kilo for Slack, simply go to the integrations menu in the sidebar on https://app.kilo.ai and set up the Slack integration.
 
 ---
 
-## How to Interact with the Slackbot
+## How to Interact with Kilo
 
 ### Direct Messages
 
-You can message the Kilo Slackbot directly through Slack DMs for private conversations:
+You can message Kilo directly through Slack DMs for private conversations:
 
 1. Find **Kilo** in your Slack workspace's app list
 2. Start a direct message conversation
 3. Ask your question or describe what you need
 
 This is ideal for:
+
 - Private questions about your code
 - Sensitive debugging sessions
 - Personal productivity tasks
@@ -53,6 +54,7 @@ Mention the bot in any channel where it's been added:
 ```
 
 This is great for:
+
 - Team discussions where AI assistance would help
 - Collaborative debugging sessions
 - Getting quick answers during code reviews
@@ -82,6 +84,7 @@ When your team identifies an issue or improvement in a Slack thread, ask the bot
 ```
 
 The bot can:
+
 - Read the context from the thread
 - Understand the proposed solution
 - Create a branch with the implementation
@@ -101,16 +104,16 @@ Can you help me understand what's causing it?
 
 ## How It Works
 
-1. **Message the bot** — Either through DMs or by mentioning it in a channel
-2. **Bot processes your request** — The Slackbot uses your connected GitHub repositories to understand context
+1. **Message Kilo** — Either through DMs or by mentioning it in a channel
+2. **Kilo processes your request** — Kilo uses your connected GitHub repositories to understand context
 3. **AI generates a response** — Kilo Code's AI analyzes your request and provides helpful responses
-4. **Code changes (if requested)** — For implementation requests, the bot can create pull requests
+4. **Code changes (if requested)** — For implementation requests, Kilo can create pull requests
 
 ---
 
 ## Cost
 
-- **Kilo Code credits are used** when the Slackbot performs work (model usage, operations, etc.)
+- **Kilo Code credits are used** when Kilo performs work (model usage, operations, etc.)
 - Credit usage is similar to using Kilo Code through other interfaces
 
 ---
@@ -126,22 +129,38 @@ Can you help me understand what's causing it?
 
 ## Limitations
 
-- The Slackbot can only access repositories you've connected through the [Integrations](https://app.kilo.ai/integrations) page
+- Kilo can only access repositories you've connected through the [Integrations](https://app.kilo.ai/integrations) page
 - Complex multi-step implementations may require follow-up messages
 - Response times may vary based on the complexity of your request
 
 ---
 
+## Changing the Model
+
+You can customize which AI model Kilo uses for generating responses. The model affects the quality, speed, and capabilities of Kilo's responses.
+
+1. Go to your [Kilo Workspace](https://app.kilo.ai/)
+2. Navigate to **Integrations** > **Slack**
+3. Select your preferred model for Kilo for Slack
+
+Kilo will start using the new model immediately for subsequent requests.
+
+### Available Models
+
+Kilo for Slack supports over 400+ models across different providers.
+
+---
+
 ## Troubleshooting
 
-**"The bot isn't responding."**  
-Ensure the Kilo Slackbot is installed in your workspace and has been added to the channel you're using.
+**"Kilo isn't responding."**
+Ensure Kilo for Slack is installed in your workspace and has been added to the channel you're using.
 
-**"The bot can't access my repository."**  
+**"Kilo can't access my repository."**
 Verify your GitHub integration is configured correctly in the [Integrations tab](https://app.kilo.ai/integrations).
 
-**"I'm getting incomplete responses."**  
+**"I'm getting incomplete responses."**
 Try breaking your request into smaller, more specific questions.
 
-**"The bot doesn't understand my codebase."**  
+**"Kilo doesn't understand my codebase."**
 Make sure the repository you're asking about is connected and accessible through your GitHub integration.

apps/kilocode-docs/docs/tips-and-tricks.md

@@ -4,8 +4,12 @@ A collection of quick tips to help you get the most out of Kilo Code.
 
 - Drag Kilo Code to the [Secondary Sidebar](https://code.visualstudio.com/api/ux-guidelines/sidebars#secondary-sidebar) so you can see the Explorer, Search, Source Control, etc.
 - Once you have Kilo Code in a separate sidebar from the file explorer, you can drag files from the explorer into the chat window (and even multiple at once). Just make sure to hold down the shift key after you start dragging the files.
+- **Autocomplete Tips:**
+    - 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.
+    - Steer autocomplete by writing a comment describing what you want before triggering it, or by typing a function signature—autocomplete will fill in the implementation.
+    - Treat autocomplete suggestions as drafts: accept them quickly, then refine. It's often faster to fix a 90% correct suggestion than to craft the perfect prompt.
 - If you're not using [MCP](/features/mcp/overview), turn it off in the <Codicon name="notebook" /> Prompts tab to significantly cut down the size of the system prompt.
-- To keep your [custom modes](/features/custom-modes) on track, limit the types of files that they're allowed to edit.
+- To keep your [custom modes](/agent-behavior/custom-modes) on track, limit the types of files that they're allowed to edit.
 - If you hit the dreaded `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.
 - In general, be thoughtful about your `Max Tokens` setting for thinking models. Every token you allocate to that 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.
 - 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]`

apps/kilocode-docs/docusaurus.config.ts

@@ -97,6 +97,17 @@ const config: Config = {
 		[
 			"@docusaurus/plugin-client-redirects",
 			{
+				createRedirects(existingPath) {
+					// Redirect old /contributing/specs/spec-* paths to /contributing/architecture/*
+					if (existingPath.startsWith("/contributing/architecture/")) {
+						const filename = existingPath.replace("/contributing/architecture/", "")
+						return [
+							`/contributing/specs/spec-${filename}`, // spec- prefix
+							`/contributing/specs/${filename}`, // without prefix
+						]
+					}
+					return undefined
+				},
 				redirects: [
 					// Files moved from advanced-usage to features
 					{
@@ -108,12 +119,36 @@ const config: Config = {
 						from: ["/advanced-usage/code-actions"],
 					},
 					{
-						to: "/advanced-usage/custom-instructions",
-						from: ["/features/custom-instructions"],
+						to: "/agent-behavior/custom-instructions",
+						from: [
+							"/advanced-usage/custom-instructions",
+							"/features/custom-instructions",
+							"/customization/custom-instructions",
+						],
+					},
+					{
+						to: "/agent-behavior/custom-modes",
+						from: ["/features/custom-modes", "/advanced-usage/custom-modes", "/customization/custom-modes"],
+					},
+					{
+						to: "/agent-behavior/custom-rules",
+						from: ["/advanced-usage/custom-rules", "/customization/custom-rules"],
+					},
+					{
+						to: "/agent-behavior/skills",
+						from: ["/features/skills", "/customization/skills"],
 					},
 					{
-						to: "/features/custom-modes",
-						from: ["/advanced-usage/custom-modes"],
+						to: "/agent-behavior/workflows",
+						from: ["/features/slash-commands/workflows", "/customization/workflows"],
+					},
+					{
+						to: "/basic-usage/settings-management",
+						from: ["/features/settings-management", "/customization/settings-management"],
+					},
+					{
+						to: "/agent-behavior/prompt-engineering",
+						from: ["/advanced-usage/prompt-engineering"],
 					},
 					{
 						to: "/features/enhance-prompt",
@@ -136,6 +171,11 @@ const config: Config = {
 						from: ["/advanced-usage/api-configuration-profiles"],
 					},
 
+					{
+						to: "/slack",
+						from: ["/advanced-usage/slackbot"],
+					},
+
 					// MCP related redirects
 					{
 						to: "/features/mcp/overview",

apps/kilocode-docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/advanced-usage/custom-instructions.md

@@ -7,7 +7,7 @@
 自定义指令定义了扩展的特定行为、偏好和约束，超出了 Kilo 的基本角色定义。示例包括编码风格、文档标准、测试要求和工作流指南。
 
 :::info 自定义指令 vs 规则
-自定义指令是 IDE 范围的，适用于所有工作区，无论你在处理哪个项目，都会保持你的偏好。与指令不同，[自定义规则](/advanced-usage/custom-rules.md) 是项目特定的，允许你设置基于工作区的规则集。
+自定义指令是 IDE 范围的，适用于所有工作区，无论你在处理哪个项目，都会保持你的偏好。与指令不同，[自定义规则](/agent-behavior/custom-rules) 是项目特定的，允许你设置基于工作区的规则集。
 :::
 
 ## 设置自定义指令
@@ -36,7 +36,7 @@
 
 ## 相关功能
 
-- [自定义模式](/features/custom-modes)
-- [自定义规则](/advanced-usage/custom-rules)
-- [设置管理](/features/settings-management)
+- [自定义模式](/agent-behavior/custom-modes)
+- [自定义规则](/agent-behavior/custom-rules)
+- [设置管理](/basic-usage/settings-management)
 - [自动批准设置](/features/auto-approving-actions)

apps/kilocode-docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/advanced-usage/custom-rules.md

@@ -211,7 +211,7 @@ Kilo Code 提供了一个内置界面，用于管理您的自定义规则，而
 
 ## 相关功能
 
-- [自定义模式](/features/custom-modes)
-- [自定义指令](/advanced-usage/custom-instructions)
-- [设置管理](/features/settings-management)
+- [自定义模式](/agent-behavior/custom-modes)
+- [自定义指令](/agent-behavior/custom-instructions)
+- [设置管理](/basic-usage/settings-management)
 - [自动批准设置](/features/auto-approving-actions)

apps/kilocode-docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/advanced-usage/memory-bank.md

@@ -31,7 +31,7 @@ Memory Bank 是一个结构化文档系统，使 Kilo Code 能够**更好地理
 
 ## Memory Bank 的工作原理
 
-Memory Bank 基于 Kilo Code 的 [自定义规则](/advanced-usage/custom-rules) 功能构建，为项目文档提供了一个专门的框架。Memory Bank 文件是存储在项目仓库 `.kilocode/rules/memory-bank` 文件夹中的标准 Markdown 文件。它们不是隐藏或专有的——它们是你和 Kilo Code 都可以访问的常规文档文件。
+Memory Bank 基于 Kilo Code 的 [自定义规则](/agent-behavior/custom-rules) 功能构建，为项目文档提供了一个专门的框架。Memory Bank 文件是存储在项目仓库 `.kilocode/rules/memory-bank` 文件夹中的标准 Markdown 文件。它们不是隐藏或专有的——它们是你和 Kilo Code 都可以访问的常规文档文件。
 
 在每个任务开始时，Kilo Code 会读取所有 Memory Bank 文件，以构建对项目的全面理解。这是自动进行的，不需要你采取任何操作。Kilo Code 然后会在其响应的开头显示 `[Memory Bank: Active]`，表示 Memory Bank 已成功激活，并简要总结其对项目的理解。