docs(kilo-docs): add platform tabs infrastructure and getting-started pages

Combines infrastructure (PR 1) and getting-started content (PR 2) into a single reviewable PR. Infrastructure: - Platform type (legacy/new/all) in NavLink interface - PageVersionSwitcher banner for legacy-only and new-only pages - PlatformBadge component in SideNav with Legacy/New labels - Tabs hydration fix (SSR-safe useState + useEffect) - _app.tsx reads frontmatter.platform and renders banner Getting Started pages with tab content: - quickstart.md: Auth flow, kilo run --auto, config overview - setup-authentication.md: Tabbed auth flows per platform - settings/index.md: Config locations, precedence, export/import - auto-approving-actions.md: Per-tool permission system Platform markers: - settings/auto-cleanup.md: platform: legacy (frontmatter + nav) - settings/system-notifications.md: platform: legacy (frontmatter + nav) Fixes from code validation and PR review: - Remove false Variable Substitution section (does not exist) - Replace misleading provider env config format - Fix 'most tools prompt for approval' (default is mostly allow) - Add warning about secrets in kilo.json for version control - Fix experimental features tab referencing VSCode instead of Legacy
2026-08-28 19:11:03 +08:00 · 2026-03-25 00:55:59 -04:00
parent 181e3a24f8
commit 373bbf84f2
10 changed files with 556 additions and 45 deletions
@@ -14,8 +14,8 @@ export function PageVersionSwitcher({ platform }: Props) {
      <span className="version-banner-icon">{legacy ? "\u24D8" : "\u2728"}</span>
      <span>
        {legacy
-          ? "This page documents the legacy VSCode extension. The current VSCode extension & CLI does not have an equivalent page yet."
-          : "This page documents the current VSCode extension & CLI. There is no equivalent page for the legacy VSCode extension."}
+          ? "This page applies to the legacy VSCode extension."
+          : "This page applies to the current VSCode extension & CLI."}
      </span>

      <style jsx>{`
@@ -27,6 +27,7 @@ export function PageVersionSwitcher({ platform }: Props) {
          border-radius: 0.5rem;
          font-size: 0.875rem;
          line-height: 1.5;
+          margin-top: 1rem;
          margin-bottom: 1.5rem;
          border: 1px solid var(--border-color);
          background-color: var(--bg-secondary);
@@ -336,9 +336,8 @@ export function TopNav({ onMobileMenuToggle, isMobileMenuOpen = false, showMobil
      {/* Announcement banner */}
      <div className="announcement-banner">
        <p>
-          We're <Link href="https://blog.kilo.ai/p/kilo-cli">replatforming our extensions on the new Kilo CLI</Link>.
-          Contribute to the new CLI and pre-release extensions at{" "}
-          <Link href="https://github.com/Kilo-Org/kilocode">Kilo-Org/kilocode</Link>.
+          We've <Link href="https://blog.kilo.ai/p/kilo-cli">replatformed our extensions on the new Kilo CLI</Link>.
+          Contribute at <Link href="https://github.com/Kilo-Org/kilocode">Kilo-Org/kilocode</Link>.
        </p>
      </div>

@@ -30,8 +30,12 @@ export const GettingStartedNav: NavSection[] = [
        children: "Settings",
        subLinks: [
          { href: "/getting-started/settings/auto-approving-actions", children: "Auto-Approving Actions" },
-          { href: "/getting-started/settings/auto-cleanup", children: "Auto Cleanup" },
-          { href: "/getting-started/settings/system-notifications", children: "System Notifications" },
+          { href: "/getting-started/settings/auto-cleanup", children: "Auto Cleanup", platform: "legacy" },
+          {
+            href: "/getting-started/settings/system-notifications",
+            children: "System Notifications",
+            platform: "legacy",
+          },
        ],
      },
      { href: "/getting-started/adding-credits", children: "Adding Credits" },
@@ -14,47 +14,30 @@ Get started with Kilo Code by installing it on your preferred platform. Choose y

 ## VS Code Extension

-{% partial file="install-vscode.md" /%}
-
-{% /tab %}
-{% tab label="VS Code (Preview)" %}
-
-## VS Code Preview Extension
-
-{% callout type="info" %}
-We're rebuilding Kilo Code from the ground up on the new [Kilo CLI](https://github.com/Kilo-Org/kilocode). The pre-release extension is available for users who want to try the latest architecture and provide feedback, and don't mind some missing features and rough edges.
-{% /callout %}
-
-The pre-release extension is a complete rebuild featuring:
-
- A new Solid.js-based UI
- Deep integration with the Kilo CLI backend
- Improved session management and model switching
-
-### Current Status
-
-This is an early pre-release. Core features like chat, markdown rendering, authentication, and model/mode switching are working. Some features from the stable extension are still being implemented.
-
-For the full feature status, see the [feature parity tracking document](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/docs/opencode-migration-plan.md).
-
-### Installing the Pre-Release
+The current Kilo Code extension is built on the [Kilo CLI](https://github.com/Kilo-Org/kilocode) and is distributed as the **pre-release version** on the VS Code Marketplace.

 1. Open VS Code
 2. Go to Extensions (`Ctrl+Shift+X` / `Cmd+Shift+X`)
 3. Search for "Kilo Code"
 4. Click the dropdown arrow next to **Install** and select **Install Pre-Release Version**

-### Switching Back to Stable
+{% callout type="info" %}
+The "pre-release" label is a VS Code Marketplace distribution channel — the extension is stable and recommended for all users.
+{% /callout %}

-If you need to return to the stable version:
+{% /tab %}
+{% tab label="VS Code (Legacy)" %}

-1. Open Extensions in VS Code
-2. Find Kilo Code
-3. Click the dropdown and select **Switch to Release Version**
+## VS Code Legacy Extension

-### Feedback and Issues
+The legacy extension is the previous version of Kilo Code for VS Code. It is still available but is no longer actively developed. We recommend installing the current extension (see the **VS Code** tab).

-Report issues or provide feedback in the [Kilo-Org/kilocode repository](https://github.com/Kilo-Org/kilocode/issues).
+To install or switch back to the legacy version:
+
+1. Open VS Code
+2. Go to Extensions (`Ctrl+Shift+X` / `Cmd+Shift+X`)
+3. Search for "Kilo Code"
+4. Click the dropdown arrow next to **Install** and select **Switch to Release Version**

 {% /tab %}
 {% tab label="JetBrains" %}
@@ -5,12 +5,15 @@ description: "Get up and running with Kilo Code in minutes"

 # Quickstart

+After you [set up Kilo Code](/docs/getting-started/setup-authentication), follow the guide for your platform below.
+
+{% tabs %}
+{% tab label="VSCode (Legacy)" %}
+
 ## Video Tour

 {% youtube url="https://www.youtube.com/watch?v=pO7zRLQS-p0" caption="This quick tour shows how Kilo Code handles a simple request from start to finish" /%}

-After you [set up Kilo Code](/docs/getting-started/setup-authentication), follow these steps:
-
 ## Step by Step Guide

 ### Step 1: Open Kilo Code
@@ -66,6 +69,106 @@ Kilo Code works iteratively. After each action, it waits for your feedback befor

 {% image src="/docs/img/your-first-task/your-first-task-8.png" alt="Final result of a completed task showing the iteration process" width="500" caption="After completing the task, Kilo Code shows the final result and awaits your next instruction." /%}

+{% /tab %}
+{% tab label="VSCode" %}
+
+## Step by Step Guide
+
+### Step 1: Open Kilo Code
+
+Click the Kilo Code icon in the VS Code Primary Side Bar to open the chat panel. If you don't see the icon, verify the [extension is installed](/docs/getting-started/installing).
+
+### Step 2: Type Your Task
+
+Type a clear, concise description of what you want Kilo Code to do in the chat box. The same examples work here:
+
+- "Create a file named `hello.txt` containing 'Hello, world!'."
+- "Write a Python function that adds two numbers."
+- "Create an HTML file for a simple website with the title 'Kilo test'"
+
+No special commands or syntax needed—just use plain English.
+
+### Step 3: Send Your Task
+
+Press **Enter** to send.
+
+### Step 4: Review & Approve Actions
+
+Kilo Code analyzes your request and proposes actions. By default, most tools are auto-approved — only shell commands, external directory access, and sensitive file reads will prompt for confirmation. You'll see the tool name, arguments, and can approve or reject each action.
+
+To change which actions require approval, open **Settings** (gear icon) and go to the **Auto-Approve** tab. You can set each tool to Allow, Ask, or Deny. See [Auto-Approving Actions](/docs/getting-started/settings/auto-approving-actions) for details.
+
+### Step 5: Iterate
+
+Kilo Code works iteratively. Continue giving feedback or follow-up instructions until your task is complete.
+
+### Key Differences from Legacy
+
+- **Settings** are managed via `kilo.json` config files (the Settings webview reads and writes the same files)
+- **Permissions** use a granular per-tool system instead of broad approval categories
+- **Modes** are called "agents" and configured as `.md` files or via the `agent` config key
+- **Autocomplete** uses FIM (Fill-in-the-Middle) with Codestral
+
+{% /tab %}
+{% tab label="CLI" %}
+
+## CLI Quickstart
+
+### Step 1: Open a Terminal
+
+Navigate to your project directory:
+
+```bash
+cd /path/to/your/project
+```
+
+### Step 2: Launch Kilo
+
+Run the `kilo` command to start the interactive TUI (terminal user interface):
+
+```bash
+kilo
+```
+
+If this is your first time, run `kilo auth login` first to authenticate (see [Setup & Authentication](/docs/getting-started/setup-authentication)).
+
+### Step 3: Type Your Task
+
+Type your request in natural language at the prompt. The same examples work here:
+
+- "Create a file named `hello.txt` containing 'Hello, world!'."
+- "Write a Python function that adds two numbers."
+- "Create an HTML file for a simple website with the title 'Kilo test'"
+
+Press **Enter** to send.
+
+### Step 4: Review & Approve Actions
+
+Kilo analyzes your request and proposes actions. By default, most tools are auto-approved — only shell commands, external directory access, and sensitive file reads will prompt for confirmation. You'll see the tool name, arguments, and can approve or reject each action.
+
+To change permission defaults, configure the `permission` key in your `kilo.json` config file. See [Auto-Approving Actions](/docs/getting-started/settings/auto-approving-actions) for details.
+
+### Step 5: Iterate
+
+Kilo works iteratively. Continue giving feedback or follow-up instructions until your task is complete.
+
+### One-Shot Mode
+
+For quick, non-interactive tasks, use `kilo run`:
+
+```bash
+kilo run "add error handling to src/api.ts"
+```
+
+Add `--auto` to auto-approve all permissions (use carefully):
+
+```bash
+kilo run --auto "fix the failing tests in test/auth.test.ts"
+```
+
+{% /tab %}
+{% /tabs %}
+
 ## Conclusion

 You've completed your first task. Along the way you learned:
@@ -9,7 +9,10 @@ description: "Configure automatic approval settings for Kilo Code operations"
 **Security Warning:** Auto-approve settings bypass confirmation prompts, giving Kilo Code direct access to your system. This can result in data loss, file corruption, or worse. Command line access is particularly dangerous, as it can potentially execute harmful operations that could damage your system or compromise security. Only enable auto-approval for actions you fully trust.
 {% /callout %}

-Auto-approve settings speed up your workflow by eliminating repetitive confirmation prompts, but they significantly increase security risks.
+Auto-approve settings speed up your workflow by eliminating repetitive confirmation prompts, but they significantly increase security risks. The **VSCode (Legacy)**, **VSCode**, and **CLI** versions each handle permissions differently — choose the tab that matches your setup.
+
+{% tabs %}
+{% tab label="VSCode (Legacy)" %}

 ## Quick Start Guide

@@ -343,3 +346,238 @@ You can optionally enable an AI Safety Gatekeeper, which reviews every intended

 This is the fastest way to work with Kilo Code, but also the riskiest. Use it only when you fully trust the AI and are prepared for the consequences.
 {% /callout %}
+
+{% /tab %}
+{% tab label="VSCode" %}
+
+## Overview
+
+The new extension uses a granular, per-tool permission system. You can configure permissions through the **Settings → Auto Approve** tab, which provides a UI with per-tool **Allow / Ask / Deny** dropdowns.
+
+The UI reads and writes to the same `kilo.json` config files used by the CLI, so changes made in either place are reflected in both.
+
+## Permission Levels
+
+Each tool permission can be set to one of three values:
+
+| Value     | Behavior                                                  |
+| --------- | --------------------------------------------------------- |
+| `"allow"` | The tool runs automatically without prompting             |
+| `"ask"`   | Kilo pauses and asks for approval before running the tool |
+| `"deny"`  | The tool is blocked entirely                              |
+
+When no rule matches a permission check, the default action is `ask`.
+
+## Available Tool Permissions
+
+The Auto Approve tab lists the following tool-specific permissions. Some tools are grouped together in the UI and share a single permission level:
+
+| Permission                 | Controls                                               |
+| -------------------------- | ------------------------------------------------------ |
+| `external_directory`       | Accessing files outside the project directory          |
+| `bash`                     | Executing shell commands                               |
+| `read`                     | Reading file contents                                  |
+| `edit`                     | Editing existing files                                 |
+| `glob`                     | File pattern matching / searching by name              |
+| `grep`                     | Searching file contents by regex                       |
+| `list`                     | Listing directory contents                             |
+| `task`                     | Launching sub-agents                                   |
+| `skill`                    | Loading specialized skills                             |
+| `lsp`                      | Language server protocol operations                    |
+| `todoread` / `todowrite`   | Reading and updating the todo list                     |
+| `websearch` / `codesearch` | Performing web or code searches                        |
+| `webfetch`                 | Fetching content from URLs                             |
+| `doom_loop`                | Allowing the agent to continue after repeated failures |
+
+## Runtime Permission Requests
+
+When a tool is set to `"ask"`, Kilo pauses and displays a permission request popup. You have three options:
+
+| Option     | Behavior                                                 |
+| ---------- | -------------------------------------------------------- |
+| **Once**   | Allow this specific invocation only                      |
+| **Always** | Allow this tool (or pattern) for the rest of the session |
+| **Reject** | Block this specific invocation                           |
+
+## Defaults
+
+Most tools default to `"*": "allow"` for a smooth out-of-the-box experience. Notable exceptions that prompt by default:
+
+- **`.env` files** — reading `.env` files prompts for approval. Files matching `*.env.*` (e.g., `.env.local`, `.env.production`) also trigger an ask, while `*.env.example` is explicitly allowed.
+- **`external_directory`** — accessing files outside the project prompts for approval
+- **`doom_loop`** — prompts when the agent enters a repeated failure cycle
+
+{% /tab %}
+{% tab label="CLI" %}
+
+## Overview
+
+The CLI uses a granular, per-tool permission system configured in `kilo.json`. Instead of broad categories like "read" or "write," each tool has its own permission level with glob-pattern rules for fine-grained control.
+
+## Permission Levels
+
+Each tool permission can be set to one of three values:
+
+| Value     | Behavior                                                  |
+| --------- | --------------------------------------------------------- |
+| `"allow"` | The tool runs automatically without prompting             |
+| `"ask"`   | Kilo pauses and asks for approval before running the tool |
+| `"deny"`  | The tool is blocked entirely                              |
+
+When no rule matches a permission check, the default action is `ask`.
+
+## Available Tool Permissions
+
+Permissions are configured under the `permission` key in `kilo.json`. The following tool-specific permission levels are available:
+
+| Permission                 | Controls                                               |
+| -------------------------- | ------------------------------------------------------ |
+| `external_directory`       | Accessing files outside the project directory          |
+| `bash`                     | Executing shell commands                               |
+| `read`                     | Reading file contents                                  |
+| `edit`                     | Editing existing files                                 |
+| `glob`                     | File pattern matching / searching by name              |
+| `grep`                     | Searching file contents by regex                       |
+| `list`                     | Listing directory contents                             |
+| `task`                     | Launching sub-agents                                   |
+| `skill`                    | Loading specialized skills                             |
+| `lsp`                      | Language server protocol operations                    |
+| `todoread` / `todowrite`   | Reading and updating the todo list                     |
+| `websearch` / `codesearch` | Performing web or code searches                        |
+| `webfetch`                 | Fetching content from URLs                             |
+| `doom_loop`                | Allowing the agent to continue after repeated failures |
+
+## Glob-Pattern Rules
+
+Instead of a simple `"allow"` or `"deny"`, each tool can use glob-pattern rules for granular control. Patterns are matched against the tool's arguments (command strings, file paths, etc.), and the last matching rule wins.
+
+### Example: Shell Commands
+
+Allow git commands automatically, but prompt for everything else:
+
+```json
+{
+  "permission": {
+    "bash": {
+      "git *": "allow",
+      "*": "ask"
+    }
+  }
+}
+```
+
+### Example: File Reading
+
+Prompt before reading `.env` files, but allow all other reads:
+
+```json
+{
+  "permission": {
+    "read": {
+      "*.env": "ask",
+      "*": "allow"
+    }
+  }
+}
+```
+
+### Example: Blocking Dangerous Commands
+
+Deny `rm -rf` commands, allow common dev commands, and ask for anything else:
+
+```json
+{
+  "permission": {
+    "bash": {
+      "rm -rf *": "deny",
+      "npm *": "allow",
+      "bun *": "allow",
+      "git *": "allow",
+      "*": "ask"
+    }
+  }
+}
+```
+
+## Per-Agent Permission Overrides
+
+Different agents can have different permission levels. Override the default permissions for a specific agent under the `agent.<name>.permission` key:
+
+```json
+{
+  "permission": {
+    "bash": { "*": "ask" }
+  },
+  "agent": {
+    "code": {
+      "permission": {
+        "bash": { "git *": "allow", "*": "ask" }
+      }
+    },
+    "plan": {
+      "permission": {
+        "bash": { "*": "deny" }
+      }
+    }
+  }
+}
+```
+
+In this example, the `code` agent can run `git` commands automatically and asks for other shell commands, while the `plan` agent cannot run shell commands at all.
+
+## Runtime Permission Requests
+
+When a tool is set to `"ask"`, Kilo pauses and displays a permission request popup. You have three options:
+
+| Option     | Behavior                                                 |
+| ---------- | -------------------------------------------------------- |
+| **Once**   | Allow this specific invocation only                      |
+| **Always** | Allow this tool (or pattern) for the rest of the session |
+| **Reject** | Block this specific invocation                           |
+
+## Defaults
+
+Most tools default to `"*": "allow"` for a smooth out-of-the-box experience. Notable exceptions that prompt by default:
+
+- **`.env` files** — reading `.env` files prompts for approval. Files matching `*.env.*` (e.g., `.env.local`, `.env.production`) also trigger an ask, while `*.env.example` is explicitly allowed.
+- **`external_directory`** — accessing files outside the project prompts for approval
+- **`doom_loop`** — prompts when the agent enters a repeated failure cycle
+
+## Full Configuration Example
+
+{% callout type="info" %}
+This is a custom example showing the available configuration options — it does not represent the shipped defaults.
+{% /callout %}
+
+```json
+{
+  "permission": {
+    "read": { "*.env": "ask", "*": "allow" },
+    "edit": { "*.env": "ask", "*": "allow" },
+    "glob": { "*": "allow" },
+    "grep": { "*": "allow" },
+    "list": { "*": "allow" },
+    "bash": { "git *": "allow", "npm *": "allow", "*": "ask" },
+    "task": { "*": "allow" },
+    "skill": { "*": "allow" },
+    "lsp": { "*": "allow" },
+    "todoread": { "*": "allow" },
+    "todowrite": { "*": "allow" },
+    "webfetch": { "*": "allow" },
+    "websearch": { "*": "allow" },
+    "codesearch": { "*": "allow" },
+    "external_directory": { "*": "ask" },
+    "doom_loop": { "*": "ask" }
+  },
+  "agent": {
+    "code": {
+      "permission": {
+        "bash": { "git *": "allow", "npm *": "allow", "*": "ask" }
+      }
+    }
+  }
+}
+```
+
+{% /tab %}
+{% /tabs %}
@@ -1,3 +1,7 @@
+---
+platform: legacy
+---
+
 # Auto Cleanup

 Auto Cleanup automatically manages your task history by removing old tasks to free up disk space and improve performance. Tasks are intelligently classified and retained based on their type and age, ensuring important work is preserved while temporary or experimental tasks are cleaned up.
@@ -5,13 +5,20 @@ description: "Configure Kilo Code settings and preferences"

 # Settings

+Both the VS Code extension and CLI can be configured through their respective UIs. The current VS Code extension and CLI share the same underlying settings, so changes in one are reflected in the other.
+
+## Managing Settings
+
+{% tabs %}
+{% tab label="VSCode (Legacy)" %}
+
 Kilo Code allows you to manage your configuration settings effectively through export, import, and reset options. These features are useful for backing up your setup, sharing configurations with others, or restoring default settings if needed.

 You can find these options at the bottom of the Kilo Code settings page, accessible via the gear icon ({% codicon name="gear" /%}) in the Kilo Code chat view.

 {% image src="/docs/img/settings-management/settings-management.png" alt="Export, Import, and Reset buttons in Kilo Code settings" width="800" caption="Export, Import, and Reset buttons" /%}

-## Export Settings
+### Export Settings

 Clicking the **Export** button saves your current Kilo Code settings to a JSON file.

@@ -24,7 +31,7 @@ Clicking the **Export** button saves your current Kilo Code settings to a JSON f

 This creates a backup of your configuration or a file you can share.

-## Import Settings
+### Import Settings

 Clicking the **Import** button allows you to load settings from a previously exported JSON file.

@@ -35,7 +42,7 @@ Clicking the **Import** button allows you to load settings from a previously exp
 - **Merging:** Importing settings **merges** the configurations. It adds new API profiles and updates existing ones and global settings based on the file content. It does **not** delete configurations present in your current setup but missing from the imported file.
 - **Validation:** Only valid settings matching the internal schema can be imported, preventing configuration errors. A success notification appears upon completion.

-## Reset Settings
+### Reset Settings

 Clicking the **Reset** button completely clears all Kilo Code configuration data and returns the extension to its default state. This is a destructive action intended for troubleshooting or starting fresh.

@@ -57,8 +64,102 @@ Clicking the **Reset** button completely clears all Kilo Code configuration data

 Use this option only if you are certain you want to remove all Kilo Code data or if instructed during troubleshooting. Consider exporting your settings first if you might want to restore them later.

+{% /tab %}
+{% tab label="VSCode" %}
+
+The VS Code extension provides a **Settings webview UI** accessible from the extension sidebar by clicking the gear icon ({% codicon name="gear" /%}). The UI is organized into tabs including Providers, Auto-Approve, Models, and more.
+
+This UI reads and writes to the same underlying JSONC config files used by the CLI, so changes made in either place are reflected in both.
+
+### Config File Locations
+
+There are two primary config files:
+
+- **Global config:** `~/.config/kilo/kilo.json` — applies to all projects.
+- **Project config:** `kilo.json` in your project root, or `.kilo/kilo.json` for a cleaner setup. The `.kilo/` version takes priority if both exist.
+
+{% callout type="warning" %}
+If you check config files into version control, make sure they do not contain API keys or other secrets (e.g., `provider.*.options.apiKey`). Use environment variables for credentials instead.
+{% /callout %}
+
+### Export and Import
+
+Config files are plain-text and portable — copy them between machines and you're done.
+
+{% /tab %}
+{% tab label="CLI" %}
+
+In the CLI, settings are managed via config files directly.
+
+### Config File Locations
+
+- **Global config:** `~/.config/kilo/kilo.json` — applies to all projects.
+- **Project config:** `kilo.json` in your project root, or `.kilo/kilo.json` for a cleaner setup. The `.kilo/` version takes priority if both exist.
+
+{% callout type="warning" %}
+If you check config files into version control, make sure they do not contain API keys or other secrets (e.g., `provider.*.options.apiKey`). Use environment variables for credentials instead.
+{% /callout %}
+
+Higher-priority levels override lower ones. This allows organizations to enforce settings at the enterprise level while still letting individual developers customize their local environment.
+
+### Export and Import
+
+There is no traditional export/import of settings -- the JSONC config files themselves are portable. Copy `~/.config/kilo/kilo.json` or `kilo.json` to another machine and you're done.
+
+{% /tab %}
+{% tab label="CLI" %}
+
+In the CLI, settings are managed via **JSONC config files** directly. Config files are plain-text and portable -- you can copy them between machines.
+
+{% callout type="warning" %}
+If you check `kilo.json` into version control, make sure it does not contain API keys or other secrets (e.g., `provider.*.options.apiKey`). Use environment variables for credentials instead.
+{% /callout %}
+
+### Config File Locations
+
+There are two primary config files:
+
+- **Global config:** `~/.config/kilo/kilo.json` -- applies to all projects.
+- **Project config:** `kilo.json` in the root of your project -- overrides global settings for that project.
+
+Both files use the [JSONC](https://code.visualstudio.com/docs/languages/json#_json-with-comments) format (JSON with comments).
+
+### Config File Precedence
+
+Settings are resolved through an 8-level precedence system (lowest to highest priority):
+
+1. **Legacy Kilocode** -- migrated settings from the VSCode extension
+2. **Remote well-known** -- remotely fetched defaults
+3. **Global** -- `~/.config/kilo/kilo.json`
+4. **Custom** -- additional custom config paths
+5. **Project** -- `kilo.json` in the project root
+6. **`.kilo` directory** -- config from a `.kilo/` directory in the project
+7. **Inline environment** -- environment variable overrides
+8. **Managed / Enterprise** -- enterprise-managed configuration (highest priority)
+
+Higher-priority levels override lower ones. This allows organizations to enforce settings at the enterprise level while still letting individual developers customize their local environment.
+
+### Schema Auto-Injection
+
+When you create or open a `kilo.json` file, the CLI automatically injects a `$schema` property pointing to the config JSON schema. This gives you **autocompletion and validation** in any editor that supports JSON Schema (VS Code, JetBrains, etc.).
+
+### Export and Import
+
+There is no traditional export/import of settings -- the JSONC config files themselves are portable. Copy `~/.config/kilo/kilo.json` or `kilo.json` to another machine and you're done.
+
+For **session** export and import, use the CLI commands:
+
+- `kilo export` -- export session data
+- `kilo import` -- import session data
+
+{% /tab %}
+{% /tabs %}
+
 ## Experimental Features

+{% tabs %}
+{% tab label="VSCode (Legacy)" %}
+
 {% callout type="info" %}
 These features are experimental and may change in future releases. They provide advanced control over Kilo Code's behavior for specific use cases.
 {% /callout %}
@@ -106,3 +207,16 @@ This setting controls the number of lines read from a file in one batch. To mana
 **Default:** Set in Advanced Settings

 You can find this setting in the Kilo Code settings under 'Advanced Settings'.
+
+{% /tab %}
+{% tab label="VSCode" %}
+
+The new extension does not currently expose the same experimental feature toggles as the **VSCode (Legacy)** version. Advanced options are configured via the JSONC config files that the Settings webview reads and writes. Refer to the auto-generated `$schema` in your `kilo.json` for the full list of available options.
+
+{% /tab %}
+{% tab label="CLI" %}
+
+The CLI does not currently expose the same experimental feature toggles as the **VSCode (Legacy)** version. Configuration of model behavior, file editing strategies, and other advanced options is handled directly in the JSONC config files. Refer to the auto-generated `$schema` in your `kilo.json` for the full list of available options.
+
+{% /tab %}
+{% /tabs %}
@@ -1,6 +1,7 @@
 ---
 title: "System Notifications"
 description: "Configure native OS notifications for Kilo Code"
+platform: legacy
 ---

 # System Notifications
@@ -9,6 +9,9 @@ When you install Kilo Code, you'll be prompted to sign in or create a free accou

 ## Quick Start with Kilo Account

+{% tabs %}
+{% tab label="VSCode (Legacy)" %}
+
 1. Click **"Try Kilo Code for Free"** in the extension
 2. Sign in with your Google account
 3. Allow VS Code to open the authorization URL
@@ -17,6 +20,31 @@ When you install Kilo Code, you'll be prompted to sign in or create a free accou

 That's it! You're ready to [start your first task](/docs/getting-started/quickstart).

+{% /tab %}
+{% tab label="VSCode" %}
+
+The extension prompts you to sign in when you first open the sidebar. Click **Sign In** and complete the browser-based flow. The extension communicates with the CLI backend, so authentication is shared between the CLI and extension.
+
+{% /tab %}
+{% tab label="CLI" %}
+
+Run the auth command and follow the browser-based sign-in flow:
+
+```bash
+kilo auth login
+```
+
+This may open your browser to complete authentication. Once signed in, your credentials are stored locally and used for all future sessions.
+
+To verify your auth status:
+
+```bash
+kilo auth list
+```
+
+{% /tab %}
+{% /tabs %}
+
 {% callout type="tip" title="Bonus Credits" %}
 [Add credits to your account](https://app.kilo.ai/profile) and get $20 bonus credits, or sign up for [Kilo Pass](https://kilo.ai/features/kilo-pass).
 {% /callout %}
@@ -75,12 +103,48 @@ Already have a ChatGPT subscription? You can use it with Kilo Code through the [

 ### Configuring Your Provider

+{% tabs %}
+{% tab label="VSCode (Legacy)" %}
+
 1. Click the {% kilo-code-icon /%} icon in the VS Code sidebar
 2. Select your API provider from the dropdown
 3. Paste your API key
-4. Choose your model:
+4. Choose your model
 5. Click **"Let's go!"**

+{% /tab %}
+{% tab label="VSCode" %}
+
+1. Open the Kilo Code sidebar in VS Code
+2. Click the gear icon ({% codicon name="gear" /%}) to open **Settings**
+3. Go to the **Providers** tab
+4. Select your provider and enter your API key
+5. Choose your model
+
+You can also use `kilo auth login` for providers that support OAuth (like GitHub Copilot). The extension reads from the same underlying config files as the CLI, so provider settings are shared.
+
+{% /tab %}
+{% tab label="CLI" %}
+
+Set the API key as an environment variable:
+
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
+
+Or use `kilo auth login` for providers that support OAuth (like GitHub Copilot).
+
+To set a default model:
+
+```jsonc
+{
+  "model": "anthropic/claude-sonnet-4-20250514",
+}
+```
+
+{% /tab %}
+{% /tabs %}
+
 {% callout type="info" title="Need Help?" %}
 Reach out to our [support team](mailto:hi@kilo.ai) or join our [Discord community](https://kilo.ai/discord).
 {% /callout %}