Add files using upload-large-folder tool

.agents/skills/gen-changesets/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: gen-changesets
+description: Use when generating changesets in the kimi-code repository — deciding whether to write one, which package to list, the bump level, the wording, and the confirmation workflow.
+---
+
+# Generate Changesets
+
+The only user-facing published package is the CLI: `@moonshot-ai/kimi-code`. All other `@moonshot-ai/*` packages (sdk, kosong, kaos, oauth, telemetry, and so on) are internal.
+
+## 1. Whether to Write
+
+Rule of thumb: **if users cannot perceive the change, write no changeset.** A changeset is a user-facing changelog entry, not a shipping gate — internal changes merged to main ship with the next release anyway, so skipping loses nothing.
+
+Do not write:
+- Docs-only or tests-only changes that never enter the shipped artifact.
+- Changes internal to core/server packages — architecture, protocols, refactors, config/journal/wire mechanics — unless they fix a bug users care about.
+- When you are unsure whether users can perceive a change, ask first.
+
+Do write: user-perceivable new features or behavior changes, and internal-package changes that fix a user-useful bug or change CLI output/behavior (list `@moonshot-ai/kimi-code` for those).
+
+## 2. What to Write
+
+Create a short kebab-case file under `.changeset/`:
+
+```markdown
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Fix occasional loss of tool call results in long conversations.
+```
+
+Wording:
+- One short, user-facing English sentence that states only what changed. Drop trailing clauses that explain the cause, the benefit, or the mechanism.
+- New features: say plainly what it is plus one line on how to use it, e.g. `Add the /foo slash command to list active sessions. Run /foo to see them.`
+- Experimental features: also state how to enable them (the flag, config key, or env var).
+- No file, class, or function names, and no PR numbers. No vague words like refactor, optimize, or improve. No real internal identifiers — use neutral placeholders such as `example.com` or `YOUR_API_KEY`.
+- Internal packages' own changelogs (such as the sdk) are not curated for end users — write those entries honestly and technically.
+- One logical change per changeset; split unrelated changes into separate files.
+
+## 3. Bump Level
+
+- `patch`: bug fixes, small improvements, configuration additions to existing features — when in doubt, use this.
+- `minor`: a real new capability users could not do before (a new slash command, a new subcommand, a new mode).
+- `major`: **never write it.** If you think a change qualifies, stop and ask the user; without explicit approval fall back to `minor`, or to `patch` if `minor` is also unclear.
+
+## 4. Which Package
+
+- An internal change enters the CLI bundle and is user-perceivable → list `@moonshot-ai/kimi-code`.
+- An internal change does not enter the CLI or is not user-perceivable → write nothing; if it is written, list only that internal package.
+- Never mix packages ignored in `.changeset/config.json` with non-ignored packages in one frontmatter.
+- pi-tui exception: pi-tui-only changes list `@moonshot-ai/pi-tui`; if the same change is also visible to CLI users, write a separate CLI changeset (two files, never mixed).
+- kimi-inspect and the vis packages never appear in a changeset.
+
+## 5. Workflow
+
+1. Run `git status` / `git diff --name-only` to see which packages actually changed.
+2. Apply section 1; if no changeset is needed, stop.
+3. Pick the package and the bump, and write the one sentence.
+4. **Show the changeset text to whoever requested the work and get their confirmation before committing.**
+5. Do not guess at changes you do not understand: finish the parts that are clear, then list what is unclear and ask whether you may dig into the code.
+
+Before a release, review the accumulated `.changeset/` entries and delete the non-user-facing ones — the release PR regenerates from `.changeset/` on main, so deleting a file removes its changelog entry without touching shipped code.

.agents/skills/gen-docs/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: gen-docs
+description: Update Kimi Code CLI user documentation after meaningful code changes that affect product behavior or user experience.
+---
+
+# Gen Docs
+
+## Overview
+
+This repository maintains bilingual user documentation under `docs/`. `docs/en/` and `docs/zh/` are mirrored pairs for most pages; update both in the same change. **Changelog is the exception** — English is the source, and Chinese is translated from English.
+
+Use this skill to update the corresponding documentation whenever the codebase has changes that affect product behavior or user experience.
+
+For a **full pre-release audit** of all pages (detecting hallucinations and coverage gaps), use the `audit-docs` skill instead.
+
+## Prerequisites
+
+This skill depends on the following being in place. If any are missing, stop and report to the user before continuing:
+
+- `docs/` directory with `docs/zh/`, `docs/en/`, and `docs/.vitepress/config.ts` set up (VitePress site).
+- `docs/AGENTS.md` style guide — defines source-of-truth rules, terminology table, typography, and writing style.
+- `docs/scripts/sync-changelog.mjs` — auto-syncs root `CHANGELOG.md` to `docs/en/release-notes/changelog.md`.
+- `translate-docs` skill in `.agents/skills/` — handles bilingual synchronization.
+
+## Workflow
+
+1. **Inspect changes**
+
+   - `git log main..HEAD --oneline` — commits on the current branch
+   - `git diff main..HEAD --stat` — file-level scope
+   - `ls .changeset/*.md` (excluding `README.md`) — pending changeset entries
+   - Read `CHANGELOG.md` and any subpackage `packages/*/CHANGELOG.md` for already-recorded entries.
+
+2. **Understand user-facing impact**
+
+   For each change, read the actual implementation when needed; **do not infer behavior from commit messages or PR titles alone**. Skip:
+
+   - Internal refactors with no externally visible behavior change
+   - Tests, CI, type-only changes
+   - Tooling / build-system changes that do not change how users invoke the CLI
+
+   If after the scan you conclude there is no user-facing impact, say so and stop.
+
+3. **Sync English changelog**
+
+   Run:
+
+   ```bash
+   node docs/scripts/sync-changelog.mjs
+   ```
+
+   This updates `docs/en/release-notes/changelog.md` from the root `CHANGELOG.md`. Never edit the docs changelog by hand.
+
+4. **Update user docs**
+
+   Following the rules in `docs/AGENTS.md`, edit the affected pages in whichever locale you are working in, then sync the mirror. Match terminology with the term table in `docs/AGENTS.md` and the existing wording in surrounding pages.
+
+   Cover all relevant sections:
+
+   - Guides (getting-started, use cases, interaction, sessions, IDE integration)
+   - Customization (skills, agents, MCP, hooks, plugins, etc.)
+   - Configuration (config files, env vars, providers, data locations)
+   - Reference (CLI subcommands, slash commands, keyboard shortcuts)
+   - Release notes (`docs/zh/release-notes/breaking-changes.md` if a breaking change is involved)
+
+5. **Sync bilingual content**
+
+   Invoke the `translate-docs` skill. It will:
+
+   - Sync updated non-changelog pages between `docs/en/` and `docs/zh/`
+   - Translate the English changelog → Chinese under `docs/zh/release-notes/changelog.md`
+
+## Rules and conventions
+
+- **Locale sync**: Non-changelog pages stay mirrored between `docs/en/` and `docs/zh/`. Changelog flows English → Chinese.
+- **Terminology**: Use the term table in `docs/AGENTS.md` exactly. Do not invent new translations or use synonyms.
+- **Scope discipline**: Only update sections affected by the recent changes. Do not opportunistically rewrite unrelated docs.
+- **Public examples**: Never write real internal endpoints, key names, account names, or service names into docs. Use neutral placeholders such as `https://api.example.com/v1`, `https://registry.example.com/v1/models/api.json`, `example.test`, and `YOUR_API_KEY`.
+- **Breaking changes**: If any change is breaking, also update `docs/en/release-notes/breaking-changes.md` (under `## Unreleased`) with `**Affected**` + `**Migration**` subsections, and mirror it in `docs/zh/release-notes/breaking-changes.md`.
+- **Do not edit auto-synced files**: `docs/en/release-notes/changelog.md` is regenerated by the sync script; any manual edit will be overwritten.
+
+## Common mistakes
+
+- Describing what code changed instead of what the user can now do (or can no longer do).
+- Adding a new section heading per feature instead of weaving the change into existing prose.
+- Updating only one locale and leaving its mirror stale.
+- Editing only the mirror to fix wording that should be corrected in the locale you changed first.
+- Inventing new terminology that drifts from the `docs/AGENTS.md` term table.
+- Using real internal values in examples instead of neutral `example` placeholders.

.agents/skills/pre-changelog/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: pre-changelog
+description: Use before merging a kimi-code release PR to preview the user-facing CLI changelog in Chinese. Reads the changelog that changesets pre-generated in the release PR, then reuses sync-changelog's strip / classify / translate logic to render a Chinese preview. Writes no files.
+---
+
+# Pre-Changelog
+
+Preview the user-facing **Chinese** changelog of an open `kimi-code` release PR **before** it is merged. Read-only: this skill writes no files and commits nothing.
+
+This skill reuses `sync-changelog`'s strip / classify / translate rules. Read `sync-changelog` first; only the data source (release PR diff instead of a published `CHANGELOG.md`) and the output (preview instead of docs files) differ.
+
+## Workflow
+
+### 1. Locate the release PR
+
+```bash
+gh pr list --state open --search "ci: release packages in:title" \
+  --json number,title,url,headRefName,baseRefName
+```
+
+Pick the one with `headRefName: changeset-release/main`; record `number`, `url` as `<RELEASE>`. If none is open, nothing to preview — stop.
+
+### 2. Read the pre-generated CLI changelog block
+
+changesets already pre-generates `apps/kimi-code/CHANGELOG.md` inside the release PR. Extract the new version block from the diff:
+
+```bash
+gh api repos/MoonshotAI/kimi-code/pulls/<RELEASE>/files \
+  --jq '.[] | select(.filename=="apps/kimi-code/CHANGELOG.md") | .patch'
+```
+
+Take the added lines (`+`) from the top `## <version>` down to (but not including) the next `## `. That is the version block to preview.
+
+If the CLI changelog is not in the diff (for example an SDK-only release), stop and tell the user — there is no user-facing CLI changelog to preview.
+
+### 3. Render the Chinese preview (reuse `sync-changelog`)
+
+Process the version block exactly as `sync-changelog` does for the docs site, but only in memory:
+
+- **Strip** (`sync-changelog` step 3): drop the H1, the `### Patch Changes` / `### Minor Changes` / `### Major Changes` subheadings, PR links, and commit-hash links; keep only each entry's body text. The `Thanks [@user](...)!` credit (including the multi-author form) must be removed every time. Within each entry, drop SDK-only and provider-internal sentences (SDK capability mapping / API exposure, provider wire-format mechanics, internal XML markers, hook/event payload mechanics such as what an event reports or carries) and keep only the user-facing effect and required constraints.
+- **Merge and deduplicate** (`sync-changelog` step 4): merge micro-tweaks to the same surface into one higher-level entry; when three or more fixes target the same UI area or the same class of problem, merge them into one higher-level fix entry (do not merge broad or genuinely distinct fixes); and drop a server/API entry that only backs a web feature already listed.
+- **Collapse low-signal entries** (`sync-changelog` step 4): keep standalone only entries that pass both gates — the reader-action test (the reader must do or re-evaluate something) and the channel test (the product cannot push it into the user's path: hidden controls, habit invalidations, capabilities users would not know to seek — a control merely sitting in the UI is not surfacing, users do not explore). Polish keeps only must-react items; experiences the product shows at the moment of need (recovery cards, post-install guidance) fold. Fixes keep only behavior-change entries (readers must update a habit, config, or workaround); loud failures fold (the fix itself notifies the victim), and silent past damage folds too — the changelog does not repair the past, and a notice that names no locatable instance and no realistic action is noise, not diligence. Section sizes follow density defaults (about 2 polish, 3 fixes) that yield to genuinely qualifying entries — flag the overflow for the reviewer instead of folding to hit the number. Fold everything else into one catch-all line placed last under 修复 — `修复了一些已知问题。` (or `修复了一些已知问题，并做了若干细节优化。` when non-fix entries were also collapsed; when nothing folded is a fix, place it under 优化 instead as `做了若干细节优化和内部改进。`), followed by a separate pointer sentence: `更详细的变更记录见 [GitHub](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/CHANGELOG.md)。` (file link, no version anchor; before the release PR merges, the target does not yet contain this version's block — expected for a preview).
+- **Classify** (`sync-changelog` step 4): bucket into Features / Bug Fixes / Polish / Refactors / Other; order within each section by reader value (in Polish, user-visible improvements before protocol/internal adjustments).
+- **Translate** (`sync-changelog` step 6): translate entry bodies to Chinese; keep one sentence per entry with a parallel rhythm within a section; section headings become 新功能 / 修复 / 优化 / 重构 / 其他.
+
+If an upstream entry is not in English, flag it and stop (changeset entries must be English).
+
+### 4. Output
+
+Print the preview directly. Use `<version>（预览）` as the heading because the version is not released yet. Write `无` for empty sections. Do not write any file.
+
+After the preview block, append a reviewer-only section titled `### 审稿参考（不进入文档）`: list every entry folded into the catch-all (short English title, one line each), note any section that exceeds the density defaults, and flag borderline calls for the reviewer to confirm. This breakdown is how reviewers see what was folded — before merge, the catch-all pointer's target does not yet contain the version's block. Never write this section into the docs pages.
+
+The preview is pasted into chat tools (for example Lark), where relative docs links do not resolve. Rewrite every docs link to its absolute published URL: map `../<path>.md[#anchor]` to `https://moonshotai.github.io/kimi-code/zh/<path>.html[#anchor]` — for example `../configuration/config-files.md#loop-control` → `https://moonshotai.github.io/kimi-code/zh/configuration/config-files.html#loop-control`. Never emit raw relative paths, and never wrap a link in backticks; code-style the link text inside the brackets instead ([`loop_control`](...)).
+
+```
+发版 PR: <url>
+
+## <version>（预览）
+
+### 新功能
+- ...
+
+### 修复
+- ...
+```
+
+## Rules
+
+- Read-only. Never write `CHANGELOG.md`, docs files, or commit anything.
+- Classification, ordering, and translation follow `sync-changelog` exactly — do not reword or reclassify beyond what it specifies.
+- If the release PR has no CLI changelog diff, report it and stop.

.agents/skills/sync-changelog/SKILL.md

@@ -0,0 +1,488 @@
+---
+name: sync-changelog
+description: Use after a release succeeds, when maintainers need to sync apps/kimi-code/CHANGELOG.md into docs/en/release-notes/changelog.md and docs/zh/release-notes/changelog.md, then open a PR on a dedicated branch.
+---
+
+# Sync Changelog
+
+## Overview
+
+`kimi-code` uses changesets for versioning. Each package gets its own `CHANGELOG.md`. The user-facing CLI package, `@moonshot-ai/kimi-code`, writes its changelog here:
+
+```text
+apps/kimi-code/CHANGELOG.md
+```
+
+This file is the **only upstream source** for the documentation-site changelog. Internal package changelogs such as `packages/*/CHANGELOG.md` do not go into the documentation site.
+
+After the release flow finishes (Release PR merged → `Version Packages` completed → npm publish succeeded), maintainers manually run this skill to copy the new CLI changelog entries into the docs site, translate the English increment into Chinese, wait for an optional human review, then commit on a dedicated branch and open a PR.
+
+## When To Use
+
+- A new version has been published to npm.
+- The top of `apps/kimi-code/CHANGELOG.md` contains version blocks that are not yet in `docs/en/release-notes/changelog.md`.
+- The `gen-docs` flow does not run this automatically; maintainers must explicitly do it after release.
+
+Do **not** run this before the Release PR is merged. At that point, changesets has not yet written the new version into `apps/kimi-code/CHANGELOG.md`.
+
+## Source And Targets
+
+| File | Role | Edited by |
+|---|---|---|
+| `apps/kimi-code/CHANGELOG.md` | **Only upstream source**, generated by changesets | Never edit manually |
+| `docs/en/release-notes/changelog.md` | English docs changelog; source of truth for docs | This skill |
+| `docs/zh/release-notes/changelog.md` | Chinese docs changelog, translated from English | This skill, following `translate-docs` |
+
+Core rule: the English docs changelog is the source of truth, and Chinese is translated from English. This matches `translate-docs`.
+
+## Preconditions
+
+Before editing, confirm:
+
+- The released version exists on npm (`npm view @moonshot-ai/kimi-code versions --json`) or has a matching GitHub Release tag.
+- The top of `apps/kimi-code/CHANGELOG.md` is that new version.
+
+If any condition is not true, stop and confirm with the user.
+
+Do **not** edit or commit directly on `main`. All sync work happens on a dedicated branch created in step 1.
+
+## Workflow
+
+### 1. Prepare Branch
+
+Start from an up-to-date default branch:
+
+```bash
+git fetch origin
+git checkout main
+git pull --ff-only origin main
+```
+
+Before creating the branch, peek at the version range so the branch name matches the newest version being synced:
+
+```bash
+rg '^## ' apps/kimi-code/CHANGELOG.md | head -5
+rg '^## ' docs/en/release-notes/changelog.md | head -5
+```
+
+Name the branch after the newest upstream version that is not yet in the English docs page:
+
+```text
+docs/changelog-sync-<newest-version>
+```
+
+Example: syncing `0.2.1` only → `docs/changelog-sync-0.2.1`.
+
+```bash
+git checkout -b docs/changelog-sync-<newest-version>
+```
+
+If the branch already exists locally or on the remote, stop and confirm with the user instead of reusing it.
+
+### 2. Find The Version Range
+
+Use the same version lists from step 1. Confirm:
+
+- First sync: copy all upstream version blocks into the English page.
+- Incremental sync: copy every upstream version block above the latest version already present in the English page.
+
+Use upstream order: newest version first.
+
+### 3. Strip Decorations And Extract Entry Text
+
+Upstream entries look like this:
+
+```markdown
+- [#317](https://github.com/...) [`2f51db4`](https://github.com/...) Thanks [@user](https://github.com/...)! - Clean up lint warnings ...
+```
+
+Changesets may add a `Thanks ...!` credit, but it must be removed every time. Keep:
+
+- Version headings such as `## 0.2.0`.
+- Only the body text of each entry, after the PR/hash decoration and any `Thanks ...!` credit have been removed.
+
+Remove:
+
+- The upstream H1 `# @moonshot-ai/kimi-code` because the docs page already has `# Changelog`.
+- Changesets subheadings such as `### Patch Changes`, `### Minor Changes`, and `### Major Changes`.
+- PR links such as `[#317](...)`.
+- Commit hash links such as ``[`2f51db4`](...)``.
+- The `Thanks [@user](...)!` credit, including the multi-author form `Thanks [@a](...), [@b](...)!`. Drop the whole `Thanks ...!` segment every time, regardless of whether the feature is enabled.
+
+After stripping, each entry is `- <body text>`.
+
+Drop SDK-only and provider-internal detail. This changelog serves `@moonshot-ai/kimi-code` CLI and web users. Within an entry, keep only what CLI/web users can perceive, and remove sentences that document internals instead of user-visible behavior. Apply this on both the English and Chinese pages:
+
+- Drop sentences about how the SDK maps a capability, builds model aliases, or exposes a flag through an API such as `getExperimentalFeatures()` — that belongs in the SDK changelog, not here.
+- Drop provider / wire-format implementation mechanics (XML markers like `<tools_added>`, protocol field explanations, "the wire protocol is unchanged", cache-hit mechanics) unless they are the behavior a user perceives.
+- Drop hook/event payload mechanics — clauses about what extra fields an event payload carries or what an event reports in a specific case (for example "enrich hook payloads with the session title and client type", "`SessionEnd` reports `archive` when a session is archived"). Keep the new events or capability itself and how to configure it.
+- Keep the user-facing effect and any constraints users must follow (for example "question texts must be unique").
+
+Do not change facts or drop a real user-facing behavior — only trim the internal-only scaffolding. For over-long, internal-heavy entries, this trim applies on the English page too, not only in translation.
+
+Upstream language rule: `gen-changesets` requires changelog entries to be English. If the upstream CLI changelog contains a non-English entry, stop and report it to the user. Do not silently rewrite it while syncing docs.
+
+Public-text rule: do not copy real internal endpoints, key names, account names, or service names into docs changelogs. Replace examples with neutral placeholders such as `example.com`, `example.test`, or `YOUR_API_KEY` while preserving the user-visible meaning.
+
+### 4. Merge, Deduplicate, And Classify Entries
+
+Before classifying, merge related entries and drop redundant ones from the user-facing changelog:
+
+- **Curate for end users: collapse low-signal entries into one catch-all line.** The docs changelog is the only curated, user-facing outlet; the full entry list always remains in the upstream package changelog, so hiding detail here loses nothing. Apply two gates to every candidate entry. Gate 1, the reader-action test: **after reading this, is there something the reader must do, or something they must re-evaluate?** Gate 2, the channel test: **is the changelog the only channel that can deliver this?** The changelog is the channel of last resort — when the product itself surfaces the information in context, at the moment of need, to exactly the affected users, the entry is redundant no matter how real the improvement is. "Surfaced" means pushed into the user's path, not merely present on screen: an event-triggered card, prompt, or post-install screen forces the encounter, while a toggle, menu item, command, or settings page only waits to be found. Users do not explore — a capability that lives only in ambient UI is effectively undiscoverable, so the changelog must announce it. What in-product surfacing cannot deliver: hidden controls (env vars, config keys, opt-out flags nobody would find unprompted), invalidations of existing habits or expectations (in-product discovery comes as confusion), and capabilities users would not know to seek. An entry that fails either gate folds. Anchor both gates to the changelog's reader, never to the bug's victim: someone who hit a loud failure does not need the changelog to confirm the fix — the product working again is the notification — and a reader who never hit it gets nothing from the entry.
+  - `Features`: keep when users would try it or must react to it — new capabilities create demand readers did not know to seek. Collapse only behavior that takes effect solely behind an experimental flag.
+  - `Polish`: keep only must-react items — a notification users may want to turn off, a behavior change to a command they already use, a default flip with an opt-out. Fold improved experiences the product surfaces in context (recovery cards, post-install guidance, progress or status displays): they are discovered at the moment of need, and pre-reading about them helps nobody. Also fold subtle or transient tweaks (status wording, spacing, animations) and internal-behavior adjustments — nobody acts on them.
+  - `Bug Fixes`: keep only **behavior-change** fixes — the fix changes how something works going forward, so readers must update a habit, a config, or a widely-adopted workaround. Everything else folds, for one of two opposite reasons. Loud failures (crashes, refusals, interrupted runs): the fix itself notifies whoever was hit — announcement value falls as bug visibility rises. Silent past damage (dropped data, wrong results the user never noticed): the changelog cannot repair the past, and in this product the notice names no locatable instance and no realistic action — users cannot enumerate which old sessions were affected, and they do not audit finished sessions; a "some past outputs may be wrong" line is anxiety without an outlet, not diligence. The rare exception is a retrospective notice with a concrete, locatable action (for example rotating a token after a credential-handling flaw); keep those. Never keep a fix merely because it was severe, and never keep one because the bug class feels important.
+  - Do not grade entries by engineering importance. Severity and effort are already represented upstream; the curated changelog is not a credit ledger — its only job is to change what the reader does or knows.
+  - **Density, not quota.** Standalone sections stay short so the changelog actually gets read — as a default, expect about 2 Polish and 3 Bug Fixes entries per version, while `Features` is gated by the test alone and has no count. The defaults yield whenever more entries genuinely pass the reader-action test: keep them and flag the overflow for the human reviewer; never fold a qualifying entry just to hit the number, and never pad a section to reach it. The reviewer owns the final cutoff — the curator's job is to surface the borderline calls, not to resolve them silently.
+  - Everything else collapses into a single catch-all bullet placed last under `Bug Fixes`: `Fix several known issues.` When entries beyond fixes were also collapsed, use `Fix several known issues and make various refinements.` instead (Chinese: `修复了一些已知问题。` / `修复了一些已知问题，并做了若干细节优化。`). End the catch-all line with a pointer to the upstream file so folded entries stay reachable, phrased as a separate short sentence — `See the [changelog on GitHub](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/CHANGELOG.md) for more technical entries.` (Chinese: `更详细的变更记录见 [GitHub](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/CHANGELOG.md)。`). Link the file itself, never a per-version anchor — GitHub's generated heading anchors are fragile. Keep the pointer wording restrained ("more technical entries"): upstream only contains changes that received a changeset, so never claim the list is complete.
+  - If no fix survives, the `Bug Fixes` section is the catch-all line alone; if the whole version has no user-facing change, the version block is a single section with that line. Match the catch-all to what was folded — never claim fixes that did not happen: when the folded entries include fixes, use the forms above under `Bug Fixes`; when everything folded is polish or internal work, place the catch-all under `Polish` as `Make several refinements and internal improvements.` (Chinese: `做了若干细节优化和内部改进。`).
+- **Merge micro-tweaks to the same surface.** Collapse several small tweaks to the same UI area or feature into one concise entry at the higher level. For example, "change the composer's default height" and "change the composer's default font" merge into "Polish the composer's default styling." Use the most specific common ancestor (composer, settings page, tool card, and so on). Classify the merged entry by its combined effect
+- **Merge same-surface or same-kind fixes when you have three or more.** The `Bug Fixes` section tends to accumulate many narrow UI/polish fixes that read as noise when listed one by one. When three or more fixes target the same area (for example several tool cards in the TUI, or the web session/conversation surface) or the same class of problem (for example several "jumping/flickering/collapsing during streaming" fixes), merge them into one higher-level entry. Examples:
+  - "Fix the Bash tool card collapsing...", "Fix the Edit tool card jumping in height...", "Fix the Edit tool card flickering while its result streams in" → "Fix several TUI tool cards jumping, flickering, or collapsing in height when results stream in or end with short output."
+  - "Fix the collapsed sidebar not hiding...", "Stop the chat history from replaying its entrance animation...", "Fix tool components jumping the conversation when expanded/collapsed" → "Fix several layout and display glitches when switching sessions, including the collapsed sidebar not hiding, the chat history replaying its entrance animation, and tool components jumping the conversation."
+  - Classify the merged fixes as `Bug Fixes`.
+  - **Do not over-merge.** Leave a fix standalone when it is broad, high-value, or genuinely distinct (for example model/provider tool-calling bugs, session-list corruption, file-completion gaps). Merging is for low-reader-value, similar-shape fixes that read as a wall of similar bullets. A merged fix entry must still pass the standalone test from the catch-all rule above; if the merged group is low-signal too, fold it into the catch-all line instead of listing it.
+- **Drop server/API plumbing covered by a web entry.** If one entry adds a web UI feature (for example, an Archived sessions page) and another entry only adds the server or REST/WebSocket endpoints that exist solely to power that web feature, keep the web UI entry and drop the API entry. CLI and web users perceive the web page; the backing API is implementation detail with no independent user value on this changelog. Keep the API entry only when it has independent user value — a new public endpoint that SDK or server consumers call directly, or a capability usable outside the web feature. When unsure, keep both and let the reviewer decide.
+
+The docs changelog uses five section types:
+
+| English section | Chinese section | Meaning |
+|---|---|---|
+| `### Features` | `### 新功能` | New user-facing functionality, such as a new command, flag, mode, or capability that did not exist before |
+| `### Polish` | `### 优化` | User-visible improvements to existing functionality, including UX adjustments, behavior tweaks, and performance improvements that are not fixes or new capabilities |
+| `### Bug Fixes` | `### 修复` | Fixes for behavior that was broken |
+| `### Refactors` | `### 重构` | Internal changes with no user-visible behavior change, including build, CI, tests, dependency cleanup, and internal renames |
+| `### Other` | `### 其他` | Anything that does not fit above, such as CDN/endpoint swaps and docs-related artifacts |
+
+With the catch-all rule above, `Refactors` and `Other` rarely appear in newly synced versions: entries with no user-perceivable effect fold into the catch-all, and an entry that does change user-perceivable default behavior (for example an engine default flip with an opt-out flag) is classified by that effect, usually `Polish`. Reserve `Other` for genuinely unclassifiable but user-facing entries. Older versions keep whatever sections they already have — do not rewrite history.
+
+Classification process:
+
+1. Classify from the stripped entry text first.
+2. If unclear, inspect the related commit or PR:
+   - Use the stripped commit hash with `git show <hash>`.
+   - Or use the PR number with `gh pr view <NNN>`.
+3. If it is still unclear, put it in `Other`. Do not guess or force entries into `Features`.
+
+Features vs. Polish: ask whether the entry introduces something the user could not do before. If yes (new command, flag, mode, viewer, or capability), use `Features`. If it only improves an existing surface (a UI panel that already existed, an existing prompt, an existing tool card, an existing payload pipeline), use `Polish`. Verbs like `Add` do not automatically mean `Features` — a small visual addition to an existing UI is still polish.
+
+Default-behavior changes: changing the default value of an existing capability (for example flipping a feature on by default) is usually `Polish`, because the capability already existed. Use `Features` only when the new default materially changes the out-of-box experience for most users in a way they could not get before. When genuinely ambiguous, flag it and confirm with the reviewer rather than guessing.
+
+Keyword hints:
+
+- **Features**: `Add ... command/flag/option/mode/viewer`, `Introduce`, `Support`, `Allow`, `Enable`, `Implement`, `New ... command/flag/option`
+- **Bug Fixes**: `Fix`, `Resolve`, `Correct`, `Address`, `Prevent ... from`, `Stop ... from`, `... no longer ...`
+- **Polish**: `Polish`, `Optimize`, `Improve`, `Enhance`, `Speed up`, `Reduce`, `Cap`, `Shorten`, `Wrap`, `Clarify`, `Tweak`, `Adjust`, `Offload`, `Show ... in existing surface`, performance and UX adjustments to existing features
+- **Refactors**: `Refactor`, `Rename`, `Clean up`, `Simplify`, `Remove unused`, `Migrate to`, `Unify`, `Restructure`, `Internal`, dependency bumps, pure CI/build/test changes
+- **Other**: docs artifacts, CDN/endpoint switches, anything that genuinely fits no other section
+
+Within each version, section order is:
+
+```text
+Features → Polish → Bug Fixes → Refactors → Other
+```
+
+Omit empty sections. Within each section, order entries by reader value, not upstream order:
+
+1. Put the most valuable, obvious, and larger changes first.
+2. Prefer broad user-visible features, workflow-changing fixes, high-frequency bugs, and large cross-cutting improvements over small polish, narrow edge cases, and internal cleanup.
+3. Within `Polish`, put directly user-visible UX or performance improvements (something users can see or feel) before protocol or internal-behavior adjustments (something that makes the model or pipeline behave more reliably but is invisible to users).
+4. If entries have similar value, preserve upstream order.
+
+Do not reword or exaggerate entries just to make them look more important; only reorder existing entries.
+
+### 5. Write The English Page
+
+Never change the English page header:
+
+```markdown
+# Changelog
+
+This page documents the changes in each Kimi Code CLI release.
+```
+
+Insert new version blocks immediately after the header paragraph and before the previous latest version.
+
+Every version heading must carry its release date in parentheses:
+
+```text
+## <version> (YYYY-MM-DD)
+```
+
+Take the date from the version's published GitHub Release tag, not from when you run the sync:
+
+```bash
+git log -1 --format=%cs "@moonshot-ai/kimi-code@<version>"
+```
+
+Use the half-width parenthesis form ` (YYYY-MM-DD)` on the English page. Never invent or guess a date; if the tag is missing, stop and confirm with the user.
+
+Example:
+
+```markdown
+## 0.2.0 (2026-05-26)
+
+### Bug Fixes
+
+- Fix the TUI not restoring the current todo list after resuming a session.
+
+### Refactors
+
+- Clean up lint warnings across the CLI, SDK examples, and bundled runtime code without changing product behavior.
+- Update the native release workflow to use current GitHub artifact actions.
+```
+
+Doc links: an entry that changes a documented config surface may end with a pointer to the docs page — `see [X](...) for details` (Chinese: `详见 [X](...)。`). Keep it a real Markdown link into the docs tree with a relative path (for example `../configuration/config-files.md#loop-control`). When the link text is a config key or another identifier, code-style the text inside the brackets: [`loop_control`](../configuration/config-files.md#loop-control). Never wrap the whole link in backticks — `` `[loop_control](...)` `` renders as raw inline code that exposes the relative path instead of a clickable link.
+
+### 6. Translate The Increment Into Chinese
+
+After updating the English page, translate only the newly added English content into `docs/zh/release-notes/changelog.md`.
+
+Follow `translate-docs`, direction `en → zh`. Changelog direction is English-to-Chinese even though many other docs flows use Chinese-to-English.
+
+Chinese page requirements:
+
+- Header:
+
+  ```markdown
+  # 变更记录
+
+  本页记录 Kimi Code CLI 每个版本的变更内容。
+  ```
+
+- Preserve version headings including the release date, but use full-width parentheses on the Chinese page, such as `## 0.2.0（2026-05-26）`. The date must match the English page; only the parenthesis style differs (half-width `()` in English, full-width `（）` in Chinese).
+- Translate section headings exactly:
+  - `### Features` → `### 新功能`
+  - `### Bug Fixes` → `### 修复`
+  - `### Polish` → `### 优化`
+  - `### Refactors` → `### 重构`
+  - `### Other` → `### 其他`
+- The Chinese page must mirror the English page 1:1 for versions, sections, section order, entry order, and entry counts.
+- Keep the classification and entry order from the English page. Do not reclassify or reorder while translating.
+- Translate only entry body text. Do not add entries that are not present in English.
+- Follow `docs/AGENTS.md` for Chinese typography: full-width punctuation, spaces between Chinese and English, and the glossary.
+
+#### Chinese wording style
+
+Structural fidelity does not mean literal translation. The Chinese entries should read like a concise, idiomatic Chinese changelog. Keep the same facts as the English entry, but rephrase for natural Chinese prose.
+
+Guidelines:
+
+- **One entry, one sentence.** Avoid chaining multiple effects with commas or semicolons. If the English entry is long, split it into shorter sentences or keep only the most important effect.
+- **Drop SDK-only and provider-internal detail.** Apply the trim from step 3 while translating: keep the user-facing effect and required constraints, drop SDK-mapping sentences, provider / wire-format mechanics, and internal XML markers. A long internal entry should collapse to one short Chinese sentence about what the user gets.
+- **Prefer common changelog verbs**: 新增、支持、修复、优化、改进、调整.
+- **Avoid indirect "through... make..." structures**. Do not write "通过 X，使 Y"; prefer direct cause-effect or just state the result.
+  - Bad: `通过缓存已渲染消息行，使终端在长篇对话中保持响应。`
+  - Better: `缓存已渲染消息行，提升长对话下终端的响应速度。`
+- **Be specific, not vague**. Prefer concrete actions over abstract quality words.
+  - Bad: `加固默认系统提示词和内置工具描述。`
+  - Better: `优化默认系统提示词与内置工具描述，避免 Agent 阻塞后台任务。`
+- **Name concrete files or config keys when it helps clarity**.
+  - Bad: `插件现在可以在其清单中声明 hooks。`
+  - Better: `插件现支持在 kimi.plugin.json 中声明生命周期 hooks。`
+- **Include required argument placeholders in CLI options**.
+  - Bad: `--allowed-host`
+  - Better: `--allowed-host <host>`
+- **Keep usage hints to one short clause**.
+  - Bad: `传入 --allowed-host 以允许额外的 host。例如 ... （多句展开）`
+  - Better: `例如 kimi web --allowed-host example.com。`
+- **Do not translate technical identifiers**: keep command names, flag names, file names, env vars, config keys as-is.
+- **Keep parallel rhythm within a section.** When several entries fix similar web surfaces (layout, animation, sizing), phrase them with a consistent structure (for example 修复 <问题>，现 <行为>) so the section reads as a tidy list rather than a mix of shapes.
+
+Example — translating a feature entry:
+
+English source:
+
+```markdown
+- Add a --allowed-host flag to kimi web that lets extra Host header values pass the DNS-rebinding check, and include allow guidance in the 403 error message. Pass --allowed-host <host> to allow an extra host.
+```
+
+Before (literal, wordy):
+
+```markdown
+- 为 `kimi web` 新增 `--allowed-host` 标志，允许额外的 Host 请求头值通过 DNS 重绑定检查，并在 403 错误消息中包含允许指引。传入 `--allowed-host <host>` 以允许额外的 host。例如 `kimi web --allowed-host example.com`。
+```
+
+After (concise, idiomatic):
+
+```markdown
+- `kimi web` 新增 `--allowed-host <host>` 选项，可将指定 Host 加入 DNS 重绑定白名单；403 错误会提示如何通过 `--allowed-host` 或 `KIMI_CODE_ALLOWED_HOSTS` 放行，例如 `kimi web --allowed-host example.com`。
+```
+
+### 7. Verify
+
+Review:
+
+```bash
+git diff docs/en/release-notes/changelog.md docs/zh/release-notes/changelog.md
+```
+
+Check:
+
+- Versions and version counts match between English and Chinese.
+- Every version heading carries its release date from the published tag, with half-width parentheses in English and full-width in Chinese.
+- Each version has the same section set and order on both pages.
+- Each section has the same number of entries on both pages.
+- Within each section, the most valuable, obvious, and larger entries appear before smaller or narrower entries.
+- Low-signal entries were collapsed into the single catch-all line, placed last under `Bug Fixes` — or under `Polish` when nothing folded is a fix (both the reader-action test and the channel test applied); the catch-all wording matches what was folded and never claims fixes that did not happen; section sizes stay within the density defaults (about 2 Polish, 3 Bug Fixes) unless extra qualifying entries were deliberately kept and flagged for review. The catch-all line ends with the upstream changelog pointer (file link, no version anchor).
+- PR links and commit hashes were stripped.
+- No `Thanks ...!` credit remains (remove it every time).
+- Real internal identifiers were replaced with neutral placeholders.
+- Doc links are real Markdown links (code-styled text inside the brackets when needed), never wrapped in backticks.
+- There are no empty sections.
+- Markdown indentation and blank lines are intact.
+
+Then run the docs build:
+
+```bash
+pnpm --filter docs run build
+```
+
+### 8. Human Review Checkpoint
+
+After verification passes, **before committing**, ask the user whether they want to review the sync result. Use `AskQuestion` with options such as:
+
+- **Review first** — show the diff and wait for the user to finish checking.
+- **Skip review, commit and open PR** — proceed directly to steps 9 and 10.
+
+If the user chooses review:
+
+1. Show the uncommitted diff:
+
+   ```bash
+   git diff docs/en/release-notes/changelog.md docs/zh/release-notes/changelog.md
+   ```
+
+2. Summarize synced versions, section counts, and anything that needed manual classification. List every entry folded into a catch-all line (short titles, one line each), any section that exceeds the density defaults, and every borderline call flagged during curation — the reviewer cannot own a cutoff they cannot see.
+3. Tell the user to reply when they are done reviewing, or to ask for edits.
+4. Do **not** commit, push, or open a PR until the user explicitly says review is complete, or asks to proceed.
+
+If the user requests edits during review, make the changes, re-run verification from step 7, and return to this checkpoint.
+
+### 9. Commit
+
+Only run this step when the user skipped review or confirmed review is complete.
+
+Stage only the changelog docs files:
+
+```bash
+git add docs/en/release-notes/changelog.md docs/zh/release-notes/changelog.md
+```
+
+Use a neutral docs-sync commit message:
+
+```text
+docs(changelog): sync <version range> from apps/kimi-code/CHANGELOG.md
+```
+
+Do **not** create a changeset for changelog docs sync. Docs sync does not enter the bundle.
+
+### 10. Push And Open PR
+
+Run immediately after step 9.
+
+Push the branch:
+
+```bash
+git push -u origin HEAD
+```
+
+Create the PR with `gh pr create`. Title follows Conventional Commits:
+
+```text
+docs(changelog): sync <version range> from apps/kimi-code/CHANGELOG.md
+```
+
+Fill in `.github/pull_request_template.md`. For changelog sync PRs:
+
+- **Related Issue**: write `N/A — post-release docs maintenance` (no issue required).
+- **Problem**: the docs-site changelog is behind the published CLI release(s).
+- **What changed**: list synced version(s), note English source + Chinese translation, and mention verification (`pnpm --filter docs run build`).
+- **Checklist**: check CONTRIBUTING; explain no issue, no tests, no changeset, and that `gen-docs` is not needed because this is the dedicated changelog sync flow.
+
+Example body:
+
+```markdown
+## Related Issue
+
+N/A — post-release docs maintenance
+
+## Problem
+
+The docs-site changelog has not yet been synced for `<version range>` after the npm release.
+
+## What changed
+
+- Synced `<version range>` from `apps/kimi-code/CHANGELOG.md` into `docs/en/release-notes/changelog.md`
+- Translated the new English increment into `docs/zh/release-notes/changelog.md`
+- Verified with `pnpm --filter docs run build`
+
+## Checklist
+
+- [x] I have read the CONTRIBUTING document.
+- [x] I have linked a related issue, or explained the problem above.
+- [ ] I have added tests that prove my feature works. (N/A — docs-only sync)
+- [x] Ran `gen-changesets` skill, or this PR needs no changeset. (No changeset — docs sync is out of bundle)
+- [x] Ran `gen-docs` skill, or this PR needs no doc update. (This PR is the dedicated changelog sync)
+```
+
+Return the PR URL to the user when done.
+
+## Rules
+
+- The English docs changelog is the source of truth.
+- Never edit upstream `apps/kimi-code/CHANGELOG.md`.
+- Do not backfill unreleased `.changeset/*.md` drafts into the docs site.
+- If upstream wording is wrong, leave upstream alone and fix it in a future changeset.
+- Always sync on a `docs/changelog-sync-*` branch and open a PR; never push changelog docs sync directly to `main`.
+- Wait for the human review checkpoint before committing, pushing, or opening a PR.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Adding entries directly to the English docs page without reading upstream | Use `apps/kimi-code/CHANGELOG.md` as the source |
+| Copying PR links or commit hashes into docs | Strip them; keep only body text |
+| Leaving the `Thanks ...!` credit in docs | Remove it every time, including the multi-author form |
+| Leaving near-duplicate micro-tweaks as separate bullets | Merge small tweaks to the same surface into one higher-level entry (e.g. composer height + font → composer's default styling) |
+| Listing many narrow fixes to the same surface as separate bullets | When three or more fixes target the same UI area or the same class of problem, merge them into one higher-level fix entry; keep genuinely distinct or high-value fixes standalone |
+| Listing low-signal fixes or internal changes as standalone bullets | Collapse them into the single catch-all line (`Fix several known issues.`) placed last under Bug Fixes; treat the section-size defaults (about 2 Polish, 3 Bug Fixes) as a density guard, not a quota |
+| Folding a qualifying entry just to hit the section-size default | The defaults are density guards; keep entries that genuinely pass the reader-action test and flag the overflow for the human reviewer |
+| Keeping a fix because it was severe or hard-won | Severity makes the announcement redundant — the fix itself notifies whoever was hit; keep only behavior-change fixes and retrospective notices with a concrete, locatable action |
+| Keeping an improvement the product surfaces in context (recovery cards, post-install guidance, progress displays) | The product is the better channel — right users, moment of need; fold it (channel test) |
+| Folding a new capability because its control is visible somewhere in the UI | Visible is not discoverable — users do not explore; a toggle, menu item, or settings page that only waits to be found needs the changelog announcement |
+| Keeping a silent-impact fix out of diligence (dropped data, wrong results the user never noticed) | The changelog does not repair the past; if the notice names no locatable instance and no realistic action, it is anxiety without an outlet — fold it |
+| Overstating the catch-all pointer (for example claiming the upstream changelog is complete) | Keep the pointer restrained — `See the [changelog on GitHub](...) for more technical entries.`; upstream only contains changes that received a changeset |
+| Writing `Fix several known issues.` when nothing folded is a fix | Never claim fixes that did not happen; all-polish/internal folds go under Polish as `Make several refinements and internal improvements.` |
+| Listing a server/API entry that only backs a web feature already listed | Drop the API entry and keep the web UI entry, unless the API has independent user value |
+| Rewording upstream English entries | Upstream is frozen; copy the body text unless the user explicitly asks otherwise |
+| Leaving English text untranslated in the Chinese page | The Chinese page must be fully Chinese except preserved technical terms |
+| Editing upstream changelog text | Do not edit upstream |
+| Losing two-space indentation in multi-line list items | Restore indentation so Markdown lists stay valid |
+| Copying `### Patch Changes` into docs | Remove changesets headings and classify under Features / Bug Fixes / Polish / Refactors / Other |
+| Guessing unclear entries as Features | Inspect commit/PR; if still unclear, use Other |
+| Treating any `Add ...` line as Features | If the entry only adds a small element to an existing UI/surface, use Polish |
+| Filing UX or performance tweaks under Other | Use Polish for user-visible improvements to existing functionality |
+| Preserving upstream order when a small entry hides a larger change | Reorder within the section so the highest-value, most obvious items appear first |
+| Reclassifying entries while translating | Chinese classification must mirror English |
+| Leaving empty sections | Delete sections with no entries |
+| Putting everything under Other for convenience | Classify what can be classified first |
+| Translating tool names, command names, or config keys | Keep them as written |
+| Wrapping a whole doc link in backticks | Code-style the link text inside the brackets instead, so the link stays clickable: [`loop_control`](...) |
+| Keeping hook/event payload-mechanics clauses | Drop what an event reports or carries; keep the new capability and how to configure it |
+| Creating a changeset for docs sync | Do not create one |
+| Committing or pushing directly on `main` | Create `docs/changelog-sync-<version>`, commit there, then open a PR |
+| Committing or opening a PR before the user skips review or confirms review is done | Wait at the human review checkpoint |
+| Using curly quotes or half-width Chinese punctuation | Follow `docs/AGENTS.md` |
+| Omitting the release date from a version heading, or guessing it | Add ` (YYYY-MM-DD)` (full-width `（）` in Chinese) taken from the published tag |
+
+## Stop Signals
+
+- The top version in `apps/kimi-code/CHANGELOG.md` is not published on npm or GitHub Releases.
+- You are about to edit `apps/kimi-code/CHANGELOG.md`.
+- You are about to add docs sync to a changeset.
+- English and Chinese versions, entry counts, or section sets do not match.
+- A section is empty.
+- A Chinese term is uncertain and `docs/AGENTS.md` does not answer it.
+- A `docs/changelog-sync-*` branch already exists for the same version and you cannot confirm whether it is stale.
+- The user asked to review but has not yet confirmed review is complete.

.agents/skills/tdd/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: tdd
+description: Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
+---
+
+# Test-Driven Development
+
+TDD is the red → green loop. This skill is the reference that makes that loop produce tests worth keeping: what a good test is, where tests go, the anti-patterns, and the rules of the loop. Every section applies on every cycle: consult them before and during the loop, not after.
+
+When exploring the codebase, read `CONTEXT.md` (if it exists) so test names and interface vocabulary match the project's domain language, and respect ADRs in the area you're touching.
+
+## What a good test is
+
+Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't. A good test reads like a specification: "user can checkout with valid cart" tells you exactly what capability exists, and it survives refactors because it doesn't care about internal structure.
+
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+
+## Seams: where tests go
+
+A **seam** is the public boundary you test at: the interface where you observe behavior without reaching inside. Tests live at seams, never against internals.
+
+**Test only at pre-agreed seams.** Before writing any test, write down the seams under test and confirm them with the user. No test is written at an unconfirmed seam. You can't test everything, so agreeing the seams up front is how testing effort lands on the critical paths and complex logic instead of every edge case.
+
+Ask: "What's the public interface, and which seams should we test?"
+
+When the shape of that interface is itself in question (how deep the module is, where the seam belongs, what the interface should expose), call the Skill tool with "codebase-design" for the vocabulary. It is the shared source of the module, interface, depth, seam, adapter, leverage and locality terms, and it is a reference to consult, not a session to run.
+
+## Anti-patterns
+
+- **Implementation-coupled**: mocks internal collaborators, tests private methods, or verifies through a side channel (querying the database instead of using the interface). The tell: the test breaks when you refactor but behavior hasn't changed.
+- **Tautological**: the assertion recomputes the expected value the way the code does (`expect(add(a, b)).toBe(a + b)`, a snapshot derived by hand the same way, a constant asserted equal to itself), so it passes by construction and can never disagree with the code. Expected values must come from an independent source of truth: a known-good literal, a worked example, the spec.
+- **Horizontal slicing**: writing all tests first, then all implementation. Bulk tests verify _imagined_ behavior: you test the _shape_ of things rather than user-facing behavior, the tests go insensitive to real changes, and you commit to test structure before understanding the implementation. Work in **vertical slices** instead: one test → one implementation → repeat, each test a **tracer bullet** that responds to what the last cycle taught you.
+
+## Rules of the loop
+
+- **Red before green.** Write the failing test first, then only enough code to pass it. Don't anticipate future tests or add speculative features.
+- **One slice at a time.** One seam, one test, one minimal implementation per cycle.
+- **Refactoring is not part of the loop.** It belongs to the review stage (see the `code-review` skill), not the red → green implementation cycle.

.agents/skills/tdd/mocking.md

@@ -0,0 +1,59 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes - prefer test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Prefer SDK-style interfaces over generic fetchers**
+
+Create specific functions for each external operation instead of one generic function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint

.agents/skills/tdd/tests.md

@@ -0,0 +1,77 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```
+
+**Tautological tests**: Expected value restates the implementation, so the test passes by construction.
+
+```typescript
+// BAD: Expected value is recomputed the way the code computes it
+test("calculateTotal sums line items", () => {
+  const items = [{ price: 10 }, { price: 5 }];
+  const expected = items.reduce((sum, i) => sum + i.price, 0);
+  expect(calculateTotal(items)).toBe(expected);
+});
+
+// GOOD: Expected value is an independent, known literal
+test("calculateTotal sums line items", () => {
+  expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
+});
+```

.agents/skills/translate-docs/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: translate-docs
+description: Translate and sync bilingual user documentation between docs/zh/ and docs/en/ following the source-of-truth rules in docs/AGENTS.md.
+---
+
+# Translate Docs
+
+## Overview
+
+This repository keeps bilingual user documentation under `docs/zh/` and `docs/en/`. This skill synchronizes the two locales, page by page, after either side has been updated.
+
+This skill is invoked by both `gen-docs` (incremental updates) and `audit-docs` (full pre-release audit) to keep locale mirrors in sync.
+
+## Prerequisites
+
+If any of the following are missing, stop and report to the user before continuing:
+
+- `docs/zh/` and `docs/en/` mirrored directory structure.
+- `docs/AGENTS.md` — terminology table, typography rules, and source-of-truth rules.
+
+## Locale sync rules
+
+- **Changelog** (`release-notes/changelog.md`): English is the source. Translate to Chinese.
+- **Breaking changes** (`release-notes/breaking-changes.md`): English is the source. Translate to Chinese.
+- **All other pages**: `docs/en/` and `docs/zh/` are mirrored pairs. After either side changes, update the other locale in the same change.
+
+When non-changelog pages change in either locale, sync the mirror before release. When the English changelog changes, sync the Chinese changelog.
+
+## Workflow
+
+1. **Detect what needs syncing**
+
+   - `git diff main..HEAD --stat docs/` — see which files changed
+   - For each changed file under `docs/en/` or `docs/zh/`, locate its mirror in the other locale (same relative path).
+
+2. **Translate page by page, section by section**
+
+   - Keep heading hierarchy, list structure, code blocks, callout blocks, and link targets identical between the two versions.
+   - When in doubt about a technical term, **read the actual code** to confirm behavior rather than guessing.
+
+3. **Apply terminology and typography rules from `docs/AGENTS.md`**
+
+   - Use the term table exactly. Do not invent translations or use synonyms.
+   - English H2+ uses sentence case (proper nouns excepted, per the term table).
+   - Chinese typography: full-width punctuation (`，。；：？！（）`), space between Chinese and ASCII (letters / numbers / inline code / links).
+   - Callout titles (`::: tip` / `::: warning` / `::: info` / `::: danger`) use the short Chinese labels from `docs/AGENTS.md`.
+
+4. **Verify**
+
+   - `git diff docs/` — scan for terminology drift or punctuation regressions.
+   - Run the docs build if available (`pnpm --filter docs run build` or equivalent) to catch broken links and Markdown errors.
+
+## Rules and conventions
+
+- **Do not one-sided fixes**: if the changed locale has an unclear or incorrect statement, fix it there first; do not patch only the mirror.
+- **Match style, not just words**: Chinese docs use a narrative tone (see `docs/AGENTS.md` writing-style examples); preserve that tone in Chinese; preserve sentence-case headings and concise English style in English.
+- **Code blocks and identifiers stay as-is**: do not translate code, command names, flag names, or file paths.
+- **Public examples**: Do not introduce real internal endpoints, key names, account names, or service names while translating. Keep or replace them with neutral placeholders such as `example.com`, `example.test`, and `YOUR_API_KEY` in both locales.
+
+## Common mistakes
+
+- Rewriting only the mirror because a phrase feels awkward in the target language — fix the changed locale first, then sync.
+- Letting English headings slip into Title Case (only sentence case is allowed for H2+).
+- Forgetting to add spaces between Chinese characters and inline code or English words.
+- Translating proper nouns listed in the term table (`Wire`, `MCP`, `ACP`, `JSON`, `OAuth`, `macOS`, `uv`, etc.).
+- Updating only one direction and leaving the other locale stale — always finish all pages flagged by the diff.
+- Copying real internal values into the mirror instead of using neutral `example` placeholders.

.agents/skills/write-tui/DESIGN.md

@@ -0,0 +1,178 @@
+# TUI 设计规范（Design Spec）
+
+> 本目录所有 dialog / selector / 输入框的**单一真值源**。新增或改造交互组件前先读本文件，提交前对照文末「自查清单」。
+> 基准组件：`components/dialogs/model-selector.ts`（`/model`）。所有列表型 dialog 的头部、hint、搜索、选中/当前态都以它为准对齐。
+
+---
+
+## 1. 视觉状态
+
+| 语义 | 规范 | 常量 / token |
+|---|---|---|
+| 选中项指针 | `❯ `（`primary`） | `constant/symbols.ts` → `SELECT_POINTER` |
+| 选中项文字 | `primary` + bold | `chalk.hex(colors.primary).bold` |
+| 当前 / 激活项 | 行尾 ` ← current`（`success`） | `constant/symbols.ts` → `CURRENT_MARK` |
+| 危险项 / 操作 | `error`（选中再加 bold） | `chalk.hex(colors.error)` |
+| 危险确认 `[y/N]` | `warning` + bold | `chalk.hex(colors.warning)` |
+| 开关项状态：开 | 名称后 `  enabled`（`success`） | `chalk.hex(colors.success)` |
+| 开关项状态：关 | 名称后 `  disabled`（`textDim`） | `chalk.hex(colors.textDim)` |
+| 列表 / 选择器边框 | 平直 `─`（`primary`），仅顶/底各一条 | — |
+| 输入框边框 | 圆角 `╭ ╮ ╰ ╯`（`primary`） | — |
+
+- **不要**自造选中指针（`>` / `▶` / `→` 等）；统一用 `SELECT_POINTER`。
+- **不要**用 `● ` / `(current)` 表示当前项；统一用 `CURRENT_MARK`（行尾、`success`、前置一个空格）。
+- 当前项与选中项**互相独立**：当前项是「现在生效的值」（行尾 marker），选中项是「光标所在行」（指针 + 高亮）；两者可同时落在同一行。
+
+## 2. 颜色
+
+- 一律使用**语义 token**：`chalk.hex(colors.<token>)`。仓库 `chalk-named-color-guard` 已强制此约定，**禁止** `chalk.red` / `chalk.gray` 等 named color。
+- `ThemeStyles`（`state.theme.styles.*()`）是可选的便捷封装；用与不用都可，但颜色必须来自 `ColorPalette` token。
+- 可用语义 token 见 `theme/colors.ts`：`primary` `accent` `text` `textStrong` `textDim` `textMuted` `border` `borderFocus` `success` `warning` `error` `status` …
+- **hint 行不做键位高亮**：整行 `textMuted`，不给 `Enter` / `Esc` / `D` 等键位单独上色。
+
+## 3. 列表 dialog 标准布局
+
+以 `model-selector` 为准，自上而下逐行固定为：
+
+```
+─────────────────────────────────────────  ① 顶部边框（primary，整宽 ─）
+ Select a model  (type to search)          ② 标题（primary+bold）+ 可搜索且无 query 时的后缀（textMuted）
+ ↑↓ navigate · Enter select · Esc cancel    ③ hint（textMuted，紧贴标题，无键位高亮）
+                                            ④ 空行
+ Search: gpt                                ⑤ 搜索行：仅在有 query 时出现（` Search: ` primary + query text）
+  ❯ GPT-5            openai                  ⑥ 列表项：指针 + 名称（左）+ 次要列（右，textMuted）
+    Kimi K2          Kimi Code ← current        当前项行尾 ` ← current`（success）
+                                            ⑦ 空行
+ ▼ 3 more                                   ⑧ 滚动 / 匹配指示：无 query 时 `▼ N more`，有 query 时 `x / y`
+─────────────────────────────────────────  ⑨ 底部边框（primary，整宽 ─）
+```
+
+硬性约定：
+
+- **头部只有顶部一条 `─`**。标题下方紧跟 hint，**不得**再插一条 `─`。整个 dialog 全宽 `─` 仅 2 条（顶 + 底）。
+- **`(type to search)` 只出现在标题后缀**（可搜索且 query 为空时）；hint 行**不再**重复出现「type to search」。
+- **`Search:` 行在空行之下、列表之上**，只在有 query 时渲染。
+- hint 紧贴标题（中间无空行）；hint 与正文之间有 1 空行。
+- 每行最终经 `truncateToWidth(line, width)`，CJK / 窄终端不超宽。
+
+## 4. hint 行与文案词汇（英文 UI）
+
+每段 hint 形如「**键位 + 描述**」，段间用 ` · `（单空格中点）分隔。
+
+| 动作 | 键位 token | 描述词 | 完整片段 |
+|---|---|---|---|
+| 移动 | `↑↓` | navigate | `↑↓ navigate` |
+| 翻页 | `←→` 或 `PgUp/PgDn` | page | `←→ page` |
+| 确认 / 选中 | `Enter` | select | `Enter select` |
+| 取消 / 关闭 | `Esc` | cancel | `Esc cancel` |
+| 删除 | `D` | delete | `D delete` |
+| 清空搜索 | `Backspace` | clear | `Backspace clear` |
+| 切 provider | `Tab` | toggle provider | `Tab toggle provider` |
+| 搜索（标题后缀） | 打字 | — | `(type to search)` |
+
+- **键位 token 首字母大写**（`Enter` / `Esc` / `Tab` / `Backspace` / `D`），**描述词全小写**（navigate / select / cancel / page / delete / clear）；方向符 `↑↓` / `←→` 原样。
+- 方向符统一 `↑↓`（不用 `▲/▼`）。
+- 「离开对话框」统一只说 `cancel`（不混用 close / back / exit / dismiss）。业务语义（如审批的 reject）例外。
+- hint 随状态精简：可搜索列表无 query 时，「type to search」在标题后缀已出现，hint 不重复；有 query 时 hint 追加 `Backspace clear`。
+
+## 5. Tab 条（`/model` 的 provider 切换）
+
+`tabbed-model-selector` 在 flat `model-selector` 外包一层 provider tab，样式对齐 **AskUserQuestion** 的 tab：
+
+```
+ Select a model  (type to search)
+ Tab toggle provider · ↑↓ navigate · Enter select · Esc cancel   ← hint 首项即 Tab 切换
+                                            ← 空行
+ All   Kimi Code   openai                   ← tab 条：激活项填充背景（primary 底 + text 字 + bold），其余 textMuted
+                                            ← 空行
+  ❯ ...
+```
+
+- tab 条位置：**在 hint 行下方**，且**上下各一空行**（与 hint、与列表都隔开）。
+- 激活 tab：`chalk.bgHex(colors.primary).hex(colors.text).bold(\` ${label} \`)`；非激活：`chalk.hex(colors.textMuted)`。两者可见宽度一致，切换不抖动。
+- 第一个 tab 恒为 `All`（聚合所有 provider）；**默认停在 `All`**。仅当显式传 `initialTabId`（如 `/provider` 新增完跳转）才停在指定 provider tab。
+- `Tab` / `Shift+Tab` 循环切换；hint 行首项即 `Tab toggle provider`。
+- 当前模型在所在 tab 内仍以 `❯` + ` ← current` 标记，切 tab 不丢失定位。
+
+## 6. 键位
+
+| 动作 | 键 | 判定方式 |
+|---|---|---|
+| 移动 | `↑` / `↓` | `matchesKey(data, Key.up/down)` |
+| 翻页 | `PgUp` / `PgDn` | `matchesKey(data, Key.pageUp/pageDown)` |
+| 确认 / 选中 | `Enter` | `matchesKey(data, Key.enter)` |
+| 取消 / 关闭 | `Esc` | `matchesKey(data, Key.escape)` |
+| 删除 | `D` | `printableChar(data) === 'D'`（也接受 `'d'`） |
+| 搜索 | 打字 | `printableChar(data)` |
+
+- **字符比较必须经 `printableChar()`**（Kitty 协议），由 `printable-key-guard` 强制；功能键用 `matchesKey(data, Key.*)`。
+- **`Esc` 两段式**：有 query 时先清空 query（`list.clearQuery()`），无 query 时才 `onCancel()`。
+- `←` / `→` 不固定语义：无翻页结构的组件里承担「值切换」（如 `/model` 的 thinking on/off）；`choice-picker` 这类无横向值的列表里用作翻页。**不要**在有 thinking 切换的组件里又拿 `←→` 翻页。
+- **删除键统一用字母 `D`**（`/provider`、`/plugins` 一致）。字母键要求该列表**不可 type-to-search**（否则会打进搜索框）——当前所有带删除动作的列表都不可搜索；若某列表既要搜索又要删除，删除须改用非打印键。
+
+## 7. 开关列表与多选（toggle / multi-select）
+
+适用于「每行可独立开 / 关」的列表（如 `/plugins` 的已装插件、MCP server 列表）。区别于单选（`Enter` 选中即提交并关闭），开关列表用 `Space` 就地切换每行状态，dialog 不关闭。
+
+```
+ Plugins
+ ↑↓ navigate · Space toggle · Enter details · Esc cancel
+                                            ← 空行
+ Installed plugins (2)                      ← 分区标题（textStrong / 加粗）
+  ❯ Kimi Datasource  enabled                ← 选中行（❯ + primary+bold 名称）+ 状态标签（success）
+    id kimi-datasource · 1 skill · MCP 1/1 · via code.kimi.com · official   ← 次要信息行（textMuted，` · ` 分隔）
+    Superpowers  disabled                   ← 未选中行（text 名称）+ 关态标签（textDim）
+    id superpowers · 14 skills · via code.kimi.com · curated
+```
+
+约定：
+
+- **`Space` 切换当前行状态**（开 ↔ 关），即时生效、dialog 保持打开；hint 含 `Space toggle`。
+- **状态标签**紧跟名称、空 2 格：开 ` enabled`（`success`）、关 ` disabled`（`textDim`）。其它语义（如 `installed`=success、`install…`=primary）按 `statusStyle` 同源处理。
+- `Enter` 在开关列表里另作他用（如「查看详情」`Enter details`），不承担 toggle。
+- 多套独立动作时（toggle / 详情 / 删除 / 进子菜单），hint 逐项列全，键位首字母大写：`Space toggle · Enter details · D remove`（参照第 4 节大小写规则）。
+- 行下可附 1 行次要信息（id / 数量 / 来源 / 信任级），`textMuted`、` · ` 分隔。
+
+## 8. Thinking 控件（`/model` 专属）
+
+列表下方展示当前选中模型的 thinking 三态，外观固定 `[ On ] Off` 段式：
+
+- 标题：`Thinking  (←→ to switch)`（仅 `toggle` 态显示括号提示）；其余态只显示 `Thinking`。
+- `toggle`：`[ On ]  Off` / `On  [ Off ]`，激活段 `primary+bold`。
+- `always-on`：`[ Always on ]`。
+- `unsupported`：`[ Off ]` + `unsupported`（textMuted）。
+- `←` / `→` 翻转草稿；提交时经 `effectiveThinking()` 归一（always-on→true、unsupported→false）。
+
+## 9. 输入框（多字段）
+
+- 圆角盒 `╭ ╮ ╰ ╯`（`primary`）。
+- 字段切换：`Tab` / `Shift+Tab` / `↑` / `↓`。
+- `Enter`：非末段→推进到下一字段；末段→提交。
+- 取消：`Esc` / `Ctrl+C` / `Ctrl+D`。
+- footer 随焦点动态：非末段显示 `Enter next`，末段显示 `Enter submit`。
+- 必填校验按字段顺序定位（如 custom-registry：URL 空→定位 URL，token 空→定位 token），错误用对应的子提示态。
+
+## 10. 共享组件（优先复用，不另起炉灶）
+
+| 形态 | 组件 |
+|---|---|
+| 列表光标 / 搜索 / 翻页状态机 | `utils/searchable-list.ts` → `SearchableList` |
+| 分页视图 | `utils/paging.ts` → `pageView` |
+| Kitty 可打印字符 | `utils/printable-key.ts` → `printableChar` / `isPrintableChar`（含 guard） |
+| 选中指针 / 当前项标记 | `constant/symbols.ts` → `SELECT_POINTER` / `CURRENT_MARK` |
+
+新列表组件**必须复用 `SearchableList`**（光标 / 搜索 / 翻页），并手工对齐本文件第 3–8 节的布局、键位、文案。
+
+## 11. 新增 / 改造 dialog 自查清单
+
+- [ ] 头部按第 3 节：顶部一条 `─`、标题（+`(type to search)` 后缀）、hint、空行、`Search:` 行、列表、底部一条 `─`；标题下**无**内层 `─`。
+- [ ] hint 整行 `textMuted`，**不**做键位高亮；键位首字母大写、描述词小写、` · ` 分隔。
+- [ ] 选中指针用 `SELECT_POINTER`，当前项用 `CURRENT_MARK`，未自造 `>` / `▶` / `→` / `● ` / `(current)`。
+- [ ] 颜色全部来自 `colors.<token>`，无 named color。
+- [ ] 键位：`↑↓` 移动、`PgUp/PgDn` 翻页、`Enter` 确认、`Esc` 取消（可搜索列表 `Esc` 两段式：先清 query 再关闭）、`D` 删除；字符比较经 `printableChar()`。
+- [ ] 「离开对话框」只说 `cancel`，不混用 close / back / exit / dismiss。
+- [ ] 开关列表用 `Space toggle` 就地切换、不关闭；状态标签 ` enabled`(`success`) / ` disabled`(`textDim`) 紧跟名称空 2 格（见第 7 节）。
+- [ ] 长列表有滚动 / 翻页指示（`▼ N more` 或 `x / y`），空态文案明确（`No matches` 等）。
+- [ ] 每行经 `truncateToWidth(line, width)`，CJK / 窄终端下不超宽。
+- [ ] 复用 `SearchableList`；输入框圆角盒，多字段支持 `Tab/↑↓` 切换、Enter 推进 / 末段提交。
+- [ ] 有对应的组件测试（render 快照 + handleInput 键行为）。

.agents/skills/write-tui/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: write-tui
+description: Use when writing or modifying the kimi-code terminal UI in apps/kimi-code/src/tui — components, dialogs/selectors, slash commands, themes, streaming render, or the KimiTUI controllers. Covers the architecture, where new features go, test placement, the theme system mechanics, and the dialog interaction/visual spec (DESIGN.md).
+---
+
+# Write TUI (apps/kimi-code)
+
+The terminal UI lives in `apps/kimi-code/src/tui`. Before writing TUI code, read `apps/kimi-code/AGENTS.md` for the always-on **map, module boundaries, and hard constraints** (printable-key decoding, no chalk named colors, etc.). This skill is the **how-to**: architecture orientation, feature routing, test placement, theme mechanics, and the dialog spec.
+
+For any list dialog, selector, input box, or status/toggle list, the interaction and visual rules are normative — see **[DESIGN.md](./DESIGN.md)** in this folder and follow its self-check list before submitting.
+
+## Architecture
+
+`KimiTUI` is a **coordinator** that wires state, layout, session, and dialogs together and delegates heavy logic to controllers.
+
+- `src/tui/kimi-tui.ts` — the `KimiTUI` coordinator. Holds `state`, owns startup/shutdown order, layout/editor wiring, user-input entry, sending/queueing, session lifecycle, and the slash-command handler dispatch. It should **not** accumulate event-routing or rendering logic — those live in controllers.
+- `src/tui/tui-state.ts` — `TUIState`, `createTUIState`, `createInitialAppState`. The single global UI state shape. Before adding a new global field, decide whether it truly belongs here vs. local component state.
+- `src/tui/controllers/` — the independently-testable responsibilities. Each controller owns one slice:
+  - `session-event-handler.ts` — routes SDK session events (`handleEvent` dispatch + the per-event `handleXxx`). Concrete event handling goes here, not in `KimiTUI`.
+  - `streaming-ui.ts` — streaming render: assistant delta, thinking, tool call / result, compaction, subagent, background agent, transcript aggregation.
+  - `session-replay.ts` — resume/replay orchestration; drives replay records through the same live render hooks. Stateless replay parsing/limiting/projection helpers belong in `src/tui/utils/message-replay.ts`.
+  - `tasks-browser.ts` — the tasks browser controller.
+  - `editor-keyboard.ts` — editor keyboard handling, exit shortcuts, external editor, clipboard image.
+  - `auth-flow.ts` — login/auth orchestration (`refreshConfigAfterLogin`, etc.).
+- `src/tui/commands/` — slash-command declaration, parsing, ordering, and dynamic skill-command generation. Parsing and types only; execution is dispatched from `KimiTUI`'s slash-command handler section, and complex execution sinks into `utils` or focused components.
+- `src/tui/components/` — pi-tui components by UI type: `chrome/` (footer, todo, welcome, loader, device code), `dialogs/` (selectors, approval/question panels, settings popups that replace the editor), `editor/` (input box + mention provider), `media/` (image, diff, code highlight), `messages/` (transcript blocks + tool-renderers), `panes/` (activity, queue).
+- `src/tui/reverse-rpc/` — adapts SDK approval/question callbacks into UI panel data and the user's choice back into an SDK response.
+- `src/tui/theme/` — themes, color tokens, style helpers, pi-tui markdown theme, terminal-background detection. The single source of truth for color.
+- `src/tui/utils/` — TUI-only utilities (need `TUIState` or a component). App-wide, UI-independent helpers go in `src/utils/`.
+
+When a controller or `KimiTUI` section keeps growing, split pure functions, state projections, and presentation components into the matching directory rather than expanding the file.
+
+## Where new features go
+
+The feature type decides the landing spot:
+
+- **CLI arguments** → `src/cli/commands.ts` / `src/cli/options.ts`, passed into the TUI via `src/cli/run-shell.ts`. The CLI never operates on the session directly.
+- **CLI subcommands** → `src/cli/sub/`, non-interactive only; reach core via `@moonshot-ai/kimi-code-sdk`.
+- **Slash commands** → declare/parse/type under `src/tui/commands/`; add the execution entry in `KimiTUI`'s slash-command handler section; sink complex logic into `utils` or a focused component.
+- **Skill-derived commands** → hook into `buildSkillSlashCommands` / the skill command map; do not hard-code a single skill.
+- **Transcript message types** → define the shape in `src/tui/types.ts`, add/extend a `components/messages/` component, register the renderer in the transcript builder.
+- **Tool-result display** → extend `components/messages/tool-renderers/registry.ts` and the renderer; do not stack branches inside `ToolCallComponent`.
+- **Popup / selector** → `components/dialogs/`, mounted via `mountEditorReplacement`; follow [DESIGN.md](./DESIGN.md). If triggered by an SDK callback, check whether `reverse-rpc/` needs an adapter/controller/handler.
+- **SDK event handling** → add the dispatch in `session-event-handler.ts`'s `handleEvent`, then the matching `handleXxx`.
+- **Streaming render** → `controllers/streaming-ui.ts`.
+- **Session start / resume behavior** → the session-management section of `KimiTUI`; replay behavior → `controllers/session-replay.ts`, reusing live render paths.
+- **Status bar / activity / queue** → `chrome/footer`, `panes/activity`, `panes/queue`, and the matching `updateXxx`.
+- **Configuration option** → read/write + schema in `src/tui/config.ts`, then the settings UI; persist through `saveTuiConfig` (a component never writes the config file itself).
+- **Constants** → shared CLI/TUI non-copy constants in `src/constant/`; TUI-only non-copy constants in `src/tui/constant/`. Component-local copy, option labels, help text, dialog titles/footers stay next to their component — do not centralize copy into a global module.
+- **General capability** → no TUI-state dependency → `src/utils/`; depends on TUI state or a component → `src/tui/utils/`.
+
+## Test placement
+
+- Component behavior tests sit next to the component's existing tests (`test/tui/components/...`).
+- Command parsing tests → `test/tui/commands/`.
+- reverse-rpc tests → `test/tui/reverse-rpc/`.
+- Pure utility tests → next to the corresponding utils tests.
+- Do not create a generic `some-feature.test.ts` just to land a small feature; extend the nearest existing test file.
+
+## Theme system mechanics
+
+Themes are managed centrally under `src/tui/theme/`:
+
+- `colors.ts` — semantic tokens: `ColorPalette`, `darkColors`, `lightColors`.
+- `styles.ts` — common chalk helpers built on top of `ColorPalette`.
+- `pi-tui-theme.ts` — the markdown/pi-tui theme config.
+- `terminal-background.ts` — terminal background detection used by auto resolution.
+- `bundle.ts` — packs `colors`, `styles`, `markdownTheme` into a `KimiTUIThemeBundle`.
+- `index.ts` / `detect.ts` — theme type and auto/dark/light resolution.
+
+> **Keep the color-token set in sync.** `ColorPalette` in `colors.ts` is the source of truth for color tokens. When you add, rename, or remove one, update its mirrors in the same change: the custom-theme JSON schema (`apps/kimi-code/src/tui/theme/theme-schema.json`), the token tables in the custom-theme docs (`docs/en/customization/themes.md` and `docs/zh/customization/themes.md`), and the token table in the `custom-theme` built-in skill (`packages/agent-core-v2/src/features/skill/catalog/builtin/custom-theme.md`).
+
+Apply / switch flow:
+
+- UI entry: `ThemeSelectorComponent` → `handleThemeCommand` → `applyThemeChoice`.
+- The real apply step is `KimiTUI.applyTheme`: it updates `state.theme`, `state.appState.theme`, and notifies components to refresh their palette.
+- Persist the choice through `saveTuiConfig` — a component must not write the config file itself.
+
+> The **hard color rules** (no chalk named colors, contrast ratios, no module-top-level cached styled functions, add a `ColorPalette` token before inventing a color) are normative and guard-enforced — they live in `apps/kimi-code/AGENTS.md`. This skill only covers the mechanics.
+
+## Before you submit
+
+- Run lint / format / test on the files you changed.
+- For any dialog/selector/input/toggle list, walk the self-check list at the end of [DESIGN.md](./DESIGN.md).
+- Keep `printableChar()` for printable-key comparisons (CI guard) and `chalk.hex(colors.<token>)` for color (CI guard).

.gitattributes

@@ -8,3 +8,8 @@
 *.gif binary
 *.ico binary
 *.png binary
+docs/media/kimi-rc-banner.jpg filter=lfs diff=lfs merge=lfs -text
+docs/media/kimi-web-ui.jpg filter=lfs diff=lfs merge=lfs -text
+docs/media/provider-manager.jpg filter=lfs diff=lfs merge=lfs -text
+docs/media/intro.gif filter=lfs diff=lfs merge=lfs -text
+apps/kimi-code/dist-web/assets/NotoSansSC_wght_-BkPpiACN.woff2 filter=lfs diff=lfs merge=lfs -text

apps/kimi-code/dist-web/assets/NotoSansSC_wght_-BkPpiACN.woff2

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:43c2f58299a21aaa962886e536c9e69f3c284f6cb6be39c57ce54a89d05205aa
+size 7782876

docs/.vitepress/config.ts

@@ -0,0 +1,215 @@
+import { defineConfig } from 'vitepress'
+import { withMermaid } from 'vitepress-plugin-mermaid'
+import llmstxt from 'vitepress-plugin-llms'
+
+const rawBase = process.env.VITEPRESS_BASE
+const base = rawBase
+  ? rawBase.startsWith('/')
+    ? rawBase.endsWith('/') ? rawBase : `${rawBase}/`
+    : `/${rawBase}/`
+  : '/'
+
+const mermaidOptimizeDeps = [
+  '@braintree/sanitize-url',
+  'dayjs',
+  'debug',
+  'cytoscape-cose-bilkent',
+  'cytoscape',
+]
+
+const config = withMermaid(defineConfig({
+  base,
+  title: 'Kimi Code CLI Docs',
+  description: 'Kimi Code CLI Documentation',
+
+  head: [
+    ['link', { rel: 'icon', type: 'image/x-icon', href: `${base}favicon.ico` }],
+    ['meta', { name: 'theme-color', content: '#0a7aff' }],
+  ],
+
+  srcExclude: ['AGENTS.md', 'superpowers/**'],
+
+  locales: {
+    zh: {
+      label: '简体中文',
+      lang: 'zh-CN',
+      link: '/zh/',
+      title: 'Kimi Code CLI 文档',
+      description: 'Kimi Code CLI 用户文档',
+      themeConfig: {
+        nav: [
+          { text: '指南', link: '/zh/guides/getting-started', activeMatch: '/zh/guides/' },
+          { text: '定制化', link: '/zh/customization/mcp', activeMatch: '/zh/customization/' },
+          { text: '配置', link: '/zh/configuration/config-files', activeMatch: '/zh/configuration/' },
+          { text: '参考手册', link: '/zh/reference/kimi-command', activeMatch: '/zh/reference/' },
+          { text: '发布说明', link: '/zh/release-notes/changelog', activeMatch: '/zh/release-notes/' },
+        ],
+        sidebar: {
+          '/zh/guides/': [
+            {
+              text: '指南',
+              items: [
+                { text: '开始使用', link: '/zh/guides/getting-started' },
+                { text: '从 kimi-cli 迁移', link: '/zh/guides/migration' },
+                { text: '常见使用案例', link: '/zh/guides/use-cases' },
+                { text: '交互与输入', link: '/zh/guides/interaction' },
+                { text: '会话与上下文', link: '/zh/guides/sessions' },
+                { text: '在 IDE 中使用', link: '/zh/guides/ides' },
+                { text: '在网页中使用', link: '/zh/guides/web' },
+                { text: '远程控制', link: '/zh/guides/remote-control' },
+              ],
+            },
+          ],
+          '/zh/customization/': [
+            {
+              text: '定制化',
+              items: [
+                { text: 'Model Context Protocol', link: '/zh/customization/mcp' },
+                { text: 'Agent Skills', link: '/zh/customization/skills' },
+                { text: 'Plugins', link: '/zh/customization/plugins' },
+                { text: 'Agent 与 subagent', link: '/zh/customization/agents' },
+                { text: 'Hooks', link: '/zh/customization/hooks' },
+                { text: '自定义主题', link: '/zh/customization/themes' },
+              ],
+            },
+          ],
+          '/zh/configuration/': [
+            {
+              text: '配置',
+              items: [
+                { text: '配置文件', link: '/zh/configuration/config-files' },
+                { text: '平台与模型', link: '/zh/configuration/providers' },
+                { text: '配置覆盖', link: '/zh/configuration/overrides' },
+                { text: '环境变量', link: '/zh/configuration/env-vars' },
+                { text: '数据路径', link: '/zh/configuration/data-locations' },
+              ],
+            },
+          ],
+          '/zh/reference/': [
+            {
+              text: '参考手册',
+              items: [
+                { text: 'kimi 命令', link: '/zh/reference/kimi-command' },
+                { text: 'kimi acp 子命令', link: '/zh/reference/kimi-acp' },
+                { text: '服务 API', link: '/zh/reference/server-api' },
+                { text: '内置工具', link: '/zh/reference/tools' },
+                { text: '斜杠命令', link: '/zh/reference/slash-commands' },
+                { text: '键盘快捷键', link: '/zh/reference/keyboard' },
+              ],
+            },
+          ],
+          '/zh/release-notes/': [
+            {
+              text: '发布说明',
+              items: [
+                { text: '变更记录', link: '/zh/release-notes/changelog' },
+              ],
+            },
+          ],
+        },
+      },
+    },
+    en: {
+      label: 'English',
+      lang: 'en-US',
+      link: '/en/',
+      title: 'Kimi Code CLI Docs',
+      description: 'Kimi Code CLI User Documentation',
+      themeConfig: {
+        nav: [
+          { text: 'Guides', link: '/en/guides/getting-started', activeMatch: '/en/guides/' },
+          { text: 'Customization', link: '/en/customization/mcp', activeMatch: '/en/customization/' },
+          { text: 'Configuration', link: '/en/configuration/config-files', activeMatch: '/en/configuration/' },
+          { text: 'Reference', link: '/en/reference/kimi-command', activeMatch: '/en/reference/' },
+          { text: 'Release Notes', link: '/en/release-notes/changelog', activeMatch: '/en/release-notes/' },
+        ],
+        sidebar: {
+          '/en/guides/': [
+            {
+              text: 'Guides',
+              items: [
+                { text: 'Getting Started', link: '/en/guides/getting-started' },
+                { text: 'Migrating from kimi-cli', link: '/en/guides/migration' },
+                { text: 'Common Use Cases', link: '/en/guides/use-cases' },
+                { text: 'Interaction and Input', link: '/en/guides/interaction' },
+                { text: 'Sessions and Context', link: '/en/guides/sessions' },
+                { text: 'Using in IDEs', link: '/en/guides/ides' },
+                { text: 'Using Kimi Code in the browser', link: '/en/guides/web' },
+                { text: 'Remote Control', link: '/en/guides/remote-control' },
+              ],
+            },
+          ],
+          '/en/customization/': [
+            {
+              text: 'Customization',
+              items: [
+                { text: 'Model Context Protocol', link: '/en/customization/mcp' },
+                { text: 'Agent Skills', link: '/en/customization/skills' },
+                { text: 'Plugins', link: '/en/customization/plugins' },
+                { text: 'Agents and Subagents', link: '/en/customization/agents' },
+                { text: 'Hooks', link: '/en/customization/hooks' },
+                { text: 'Custom Themes', link: '/en/customization/themes' },
+              ],
+            },
+          ],
+          '/en/configuration/': [
+            {
+              text: 'Configuration',
+              items: [
+                { text: 'Config Files', link: '/en/configuration/config-files' },
+                { text: 'Providers and Models', link: '/en/configuration/providers' },
+                { text: 'Config Overrides', link: '/en/configuration/overrides' },
+                { text: 'Environment Variables', link: '/en/configuration/env-vars' },
+                { text: 'Data Locations', link: '/en/configuration/data-locations' },
+              ],
+            },
+          ],
+          '/en/reference/': [
+            {
+              text: 'Reference',
+              items: [
+                { text: 'kimi Command', link: '/en/reference/kimi-command' },
+                { text: 'kimi acp Subcommand', link: '/en/reference/kimi-acp' },
+                { text: 'Server API', link: '/en/reference/server-api' },
+                { text: 'Built-in Tools', link: '/en/reference/tools' },
+                { text: 'Slash Commands', link: '/en/reference/slash-commands' },
+                { text: 'Keyboard Shortcuts', link: '/en/reference/keyboard' },
+              ],
+            },
+          ],
+          '/en/release-notes/': [
+            {
+              text: 'Release Notes',
+              items: [
+                { text: 'Changelog', link: '/en/release-notes/changelog' },
+              ],
+            },
+          ],
+        },
+      },
+    },
+  },
+
+  themeConfig: {
+    outline: [2, 3],
+    search: { provider: 'local' },
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/MoonshotAI/kimi-code' },
+    ],
+  },
+
+  vite: {
+    optimizeDeps: {
+      include: mermaidOptimizeDeps.map((dep) => `mermaid > ${dep}`),
+    },
+    plugins: [llmstxt()],
+  },
+}))
+
+if (config.vite?.optimizeDeps?.include) {
+  config.vite.optimizeDeps.include = config.vite.optimizeDeps.include.filter(
+    (dep) => !mermaidOptimizeDeps.includes(dep),
+  )
+}
+
+export default config

docs/.vitepress/theme/components/HomeFeatures.vue

@@ -0,0 +1,319 @@
+<script setup lang="ts">
+import { useData, withBase } from 'vitepress'
+import { computed } from 'vue'
+
+const { lang } = useData()
+const isZh = computed(() => lang.value.startsWith('zh'))
+
+interface Highlight {
+  icon: string
+  title: string
+  desc: string
+}
+
+interface Feature {
+  icon: string
+  title: string
+  desc: string
+  href: string
+}
+
+const highlights = computed<Highlight[]>(() => isZh.value
+  ? [
+      {
+        icon: '⚡',
+        title: '极速轻量',
+        desc: '一行命令装好的单文件 CLI，毫秒级启动，无需 Node.js，零环境干扰。',
+      },
+      {
+        icon: '🎬',
+        title: '视频也能输入',
+        desc: '屏幕录像、演示视频拖进对话——画面替你说清需求。',
+      },
+      {
+        icon: '🎨',
+        title: '精致 TUI',
+        desc: '为长时间、专注的 Agent 会话精心打磨的交互界面。',
+      },
+    ]
+  : [
+      {
+        icon: '⚡',
+        title: 'Fast & lightweight',
+        desc: 'Single-binary install with millisecond startup — no Node.js, no PATH gymnastics.',
+      },
+      {
+        icon: '🎬',
+        title: 'Video input',
+        desc: 'Drop a screen recording or demo clip in chat; the agent reads the frames and acts on them.',
+      },
+      {
+        icon: '🎨',
+        title: 'Polished TUI',
+        desc: 'A carefully tuned interface designed for long, focused agent sessions.',
+      },
+    ])
+
+const features = computed<Feature[]>(() => isZh.value
+  ? [
+      {
+        icon: '🧩',
+        title: 'Agent Skills',
+        desc: '把团队的工作流程封装成 Kimi 随时调用的技能，不必每次都重新解释。',
+        href: '/zh/customization/skills',
+      },
+      {
+        icon: '🪝',
+        title: 'Hooks',
+        desc: '在生命周期关键点注入脚本，做格式化、审批、通知或任意自定义逻辑。',
+        href: '/zh/customization/hooks',
+      },
+      {
+        icon: '🤖',
+        title: 'Sub-agents',
+        desc: '并行派发独立任务，每个子 agent 自带上下文，主对话保持清爽。',
+        href: '/zh/customization/agents',
+      },
+      {
+        icon: '🔌',
+        title: 'MCP',
+        desc: '通过 Model Context Protocol 接入任意工具、数据源与企业系统。',
+        href: '/zh/customization/mcp',
+      }
+    ]
+  : [
+      {
+        icon: '🧩',
+        title: 'Agent Skills',
+        desc: "Package your team's workflows into skills Kimi can invoke on demand.",
+        href: '/en/customization/skills',
+      },
+      {
+        icon: '🪝',
+        title: 'Hooks',
+        desc: 'Inject scripts at lifecycle checkpoints — formatting, approvals, notifications, anything.',
+        href: '/en/customization/hooks',
+      },
+      {
+        icon: '🤖',
+        title: 'Sub-agents',
+        desc: 'Dispatch isolated tasks in parallel, each with its own context — main thread stays clean.',
+        href: '/en/customization/agents',
+      },
+      {
+        icon: '🔌',
+        title: 'MCP',
+        desc: 'Plug in any tool, data source, or enterprise system via the Model Context Protocol.',
+        href: '/en/customization/mcp',
+      }
+    ])
+
+const highlightsTitle = computed(() => isZh.value ? '开箱即得' : 'Ready out of the box')
+const highlightsLede = computed(() => isZh.value
+  ? '装好就能用，关键能力默认就绪。'
+  : 'Install once. The essentials are already there.')
+
+const featuresTitle = computed(() => isZh.value ? '按需扩展' : 'Extend it your way')
+const featuresLede = computed(() => isZh.value
+  ? '内置可编程的扩展点，按自己的方式塑造工作流。'
+  : 'Programmable extension points to shape the workflow around you.')
+
+const ctaText = computed(() => isZh.value ? '了解' : 'Learn more')
+</script>
+
+<template>
+  <section class="KimiHome__section KimiHighlights">
+    <h2 class="KimiHome__sectionTitle">{{ highlightsTitle }}</h2>
+    <p class="KimiHome__sectionLede">{{ highlightsLede }}</p>
+    <div class="KimiHighlights__grid">
+      <div
+        v-for="h in highlights"
+        :key="h.title"
+        class="KimiHighlights__card"
+      >
+        <div class="KimiHighlights__icon" aria-hidden="true">{{ h.icon }}</div>
+        <h3 class="KimiHighlights__title">{{ h.title }}</h3>
+        <p class="KimiHighlights__desc">{{ h.desc }}</p>
+      </div>
+    </div>
+  </section>
+
+  <section class="KimiHome__section KimiFeatures">
+    <h2 class="KimiHome__sectionTitle">{{ featuresTitle }}</h2>
+    <p class="KimiHome__sectionLede">{{ featuresLede }}</p>
+    <div class="KimiFeatures__grid">
+      <a
+        v-for="f in features"
+        :key="f.title"
+        class="KimiFeatures__card"
+        :href="withBase(f.href)"
+      >
+        <div class="KimiFeatures__icon" aria-hidden="true">{{ f.icon }}</div>
+        <h3 class="KimiFeatures__title">{{ f.title }}</h3>
+        <p class="KimiFeatures__desc">{{ f.desc }}</p>
+        <span class="KimiFeatures__cta">
+          {{ ctaText }}
+          <svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+            <path d="M6 3l5 5-5 5" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
+          </svg>
+        </span>
+      </a>
+    </div>
+  </section>
+</template>
+
+<style scoped>
+/* === Highlights (top section: non-clickable product attributes) === */
+.KimiHighlights__grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 16px;
+}
+
+@media (max-width: 720px) {
+  .KimiHighlights__grid {
+    grid-template-columns: 1fr;
+  }
+}
+
+.KimiHighlights__card {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  padding: 22px 22px 24px;
+  border-radius: var(--kimi-radius-card);
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg-soft);
+}
+
+.KimiHighlights__icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 36px;
+  height: 36px;
+  border-radius: 10px;
+  background: var(--kimi-brand-soft);
+  font-size: 18px;
+  margin-bottom: 14px;
+}
+
+.KimiHighlights__title {
+  font-size: 16px;
+  font-weight: 700;
+  letter-spacing: -0.01em;
+  margin: 0 0 6px;
+  color: var(--vp-c-text-1);
+}
+
+.KimiHighlights__desc {
+  font-size: 14px;
+  line-height: 1.55;
+  color: var(--vp-c-text-2);
+  margin: 0;
+}
+
+/* === Features (bottom section: clickable extension points) === */
+.KimiFeatures__grid {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: 20px;
+}
+
+@media (max-width: 1024px) {
+  .KimiFeatures__grid {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+@media (max-width: 640px) {
+  .KimiFeatures__grid {
+    grid-template-columns: 1fr;
+  }
+}
+
+.KimiFeatures__card {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  padding: 28px 24px 26px;
+  border-radius: var(--kimi-radius-card);
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+  text-decoration: none;
+  transition: transform var(--kimi-transition), border-color var(--kimi-transition),
+              box-shadow var(--kimi-transition), background var(--kimi-transition);
+  overflow: hidden;
+}
+
+.KimiFeatures__card::before {
+  content: '';
+  position: absolute;
+  inset: 0;
+  background: var(--kimi-brand-gradient-soft);
+  opacity: 0;
+  transition: opacity var(--kimi-transition);
+  pointer-events: none;
+  border-radius: inherit;
+}
+
+.KimiFeatures__card:hover {
+  transform: translateY(-3px);
+  border-color: var(--vp-c-brand-1);
+  box-shadow: var(--vp-shadow-3);
+}
+.KimiFeatures__card:hover::before {
+  opacity: 1;
+}
+
+.KimiFeatures__icon {
+  position: relative;
+  z-index: 1;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 44px;
+  height: 44px;
+  border-radius: 12px;
+  background: var(--kimi-brand-soft);
+  font-size: 22px;
+  margin-bottom: 18px;
+}
+
+.KimiFeatures__title {
+  position: relative;
+  z-index: 1;
+  font-size: 18px;
+  font-weight: 700;
+  letter-spacing: -0.015em;
+  margin: 0 0 8px;
+  color: var(--vp-c-text-1);
+}
+
+.KimiFeatures__desc {
+  position: relative;
+  z-index: 1;
+  font-size: 14.5px;
+  line-height: 1.6;
+  color: var(--vp-c-text-2);
+  margin: 0 0 20px;
+}
+
+.KimiFeatures__cta {
+  position: relative;
+  z-index: 1;
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--vp-c-brand-1);
+  margin-top: auto;
+  transition: transform var(--kimi-transition);
+}
+
+.KimiFeatures__card:hover .KimiFeatures__cta {
+  transform: translateX(3px);
+}
+</style>

docs/.vitepress/theme/components/HomeHero.vue

@@ -0,0 +1,147 @@
+<script setup lang="ts">
+import { useData, withBase } from 'vitepress'
+import { computed } from 'vue'
+import KimiLogo from './KimiLogo.vue'
+
+const { lang } = useData()
+
+const isZh = computed(() => lang.value.startsWith('zh'))
+
+const copy = computed(() => isZh.value
+  ? {
+      titleLead: 'Kimi',
+      titleAccent: 'Code',
+      titleTail: ' CLI',
+      tagline: 'The Starting Point for Next-Gen Agents',
+      primaryText: '开始使用',
+      primaryHref: '/zh/guides/getting-started',
+      secondaryText: '在 GitHub 查看',
+      secondaryHref: 'https://github.com/MoonshotAI/kimi-code',
+    }
+  : {
+      titleLead: 'Kimi',
+      titleAccent: 'Code',
+      titleTail: ' CLI',
+      tagline: 'The Starting Point for Next-Gen Agents',
+      primaryText: 'Get started',
+      primaryHref: '/en/guides/getting-started',
+      secondaryText: 'View on GitHub',
+      secondaryHref: 'https://github.com/MoonshotAI/kimi-code',
+    })
+</script>
+
+<template>
+  <section class="KimiHero">
+    <div class="KimiHero__halo" aria-hidden="true" />
+    <div class="KimiHero__inner">
+      <div class="KimiHero__logo">
+        <KimiLogo :size="64" />
+      </div>
+      <h1 class="KimiHero__title">
+        {{ copy.titleLead }}&nbsp;<span class="KimiHero__accent">{{ copy.titleAccent }}</span>{{ copy.titleTail }}
+      </h1>
+      <p class="KimiHero__tagline">{{ copy.tagline }}</p>
+      <div class="KimiHero__actions">
+        <a class="KimiBtn KimiBtn--primary" :href="withBase(copy.primaryHref)">
+          {{ copy.primaryText }}
+          <svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+            <path d="M6 3l5 5-5 5" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
+          </svg>
+        </a>
+        <a class="KimiBtn KimiBtn--ghost" :href="copy.secondaryHref" target="_blank" rel="noopener">
+          <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
+            <path d="M8 .2C3.58.2 0 3.78 0 8.2c0 3.54 2.3 6.54 5.48 7.6.4.07.55-.17.55-.38l-.01-1.5c-2.23.49-2.7-.95-2.7-.95-.37-.93-.9-1.18-.9-1.18-.73-.5.06-.49.06-.49.81.06 1.24.83 1.24.83.72 1.23 1.88.88 2.34.67.07-.52.28-.88.51-1.08-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.13 0 0 .67-.21 2.2.82a7.65 7.65 0 014 0c1.53-1.03 2.2-.82 2.2-.82.44 1.11.16 1.93.08 2.13.51.56.82 1.28.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.55.74.55 1.49l-.01 2.21c0 .21.15.46.55.38C13.7 14.74 16 11.74 16 8.2 16 3.78 12.42.2 8 .2z" />
+          </svg>
+          {{ copy.secondaryText }}
+        </a>
+      </div>
+    </div>
+  </section>
+</template>
+
+<style scoped>
+.KimiHero {
+  position: relative;
+  padding: clamp(72px, 12vw, 140px) 0 clamp(48px, 8vw, 96px);
+  overflow: hidden;
+}
+
+.KimiHero__halo {
+  position: absolute;
+  top: -120px;
+  left: 50%;
+  width: 900px;
+  height: 600px;
+  transform: translateX(-50%);
+  background:
+    radial-gradient(closest-side, rgba(10, 122, 255, 0.22), transparent 70%),
+    radial-gradient(closest-side, rgba(129, 196, 255, 0.20) 30%, transparent 75%);
+  filter: blur(40px);
+  pointer-events: none;
+  z-index: 0;
+  opacity: 0.55;
+}
+:global(.dark) .KimiHero__halo {
+  opacity: 0.85;
+  background:
+    radial-gradient(closest-side, rgba(61, 149, 255, 0.36), transparent 70%),
+    radial-gradient(closest-side, rgba(129, 196, 255, 0.30) 30%, transparent 75%);
+}
+
+.KimiHero__inner {
+  position: relative;
+  z-index: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  text-align: center;
+}
+
+.KimiHero__logo {
+  margin-bottom: 28px;
+  filter: drop-shadow(0 12px 32px rgba(10, 122, 255, 0.28));
+}
+
+.KimiHero__title {
+  font-size: clamp(40px, 7vw, 84px);
+  font-weight: 700;
+  letter-spacing: -0.035em;
+  line-height: 1.05;
+  margin: 0 0 20px;
+  color: var(--vp-c-text-1);
+  max-width: 18ch;
+}
+
+.KimiHero__accent {
+  background: var(--kimi-brand-gradient);
+  background-clip: text;
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  color: transparent;
+}
+
+.KimiHero__tagline {
+  font-size: clamp(16px, 1.5vw, 20px);
+  line-height: 1.55;
+  color: var(--vp-c-text-2);
+  max-width: 620px;
+  margin: 0 0 40px;
+}
+
+.KimiHero__actions {
+  display: flex;
+  gap: 14px;
+  flex-wrap: wrap;
+  justify-content: center;
+}
+
+@media (max-width: 480px) {
+  .KimiHero__actions {
+    width: 100%;
+    flex-direction: column;
+  }
+  .KimiHero__actions .KimiBtn {
+    width: 100%;
+  }
+}
+</style>

docs/.vitepress/theme/components/HomeLayout.vue

@@ -0,0 +1,38 @@
+<script setup lang="ts">
+import DefaultTheme from 'vitepress/theme'
+import { useData } from 'vitepress'
+import HomeHero from './HomeHero.vue'
+import HomeFeatures from './HomeFeatures.vue'
+import HomeQuickStart from './HomeQuickStart.vue'
+
+const { Layout } = DefaultTheme
+const { frontmatter } = useData()
+</script>
+
+<template>
+  <Layout>
+    <template v-if="frontmatter.layout === 'home'" #home-hero-before>
+      <div class="KimiHome">
+        <HomeHero />
+      </div>
+    </template>
+
+    <template v-if="frontmatter.layout === 'home'" #home-features-after>
+      <div class="KimiHome">
+        <HomeQuickStart />
+        <HomeFeatures />
+      </div>
+    </template>
+  </Layout>
+</template>
+
+<style>
+/* Hide the default hero + features rendered by VitePress when our custom home is active.
+   We keep frontmatter.layout: home so VitePress still applies layout-specific behavior. */
+.VPHome > .VPHero {
+  display: none;
+}
+.VPHome > .VPFeatures {
+  display: none;
+}
+</style>

docs/.vitepress/theme/components/HomeQuickStart.vue

@@ -0,0 +1,210 @@
+<script setup lang="ts">
+import { useData, withBase } from 'vitepress'
+import { computed, ref } from 'vue'
+
+const { lang } = useData()
+const isZh = computed(() => lang.value.startsWith('zh'))
+
+const installMacCommand = 'curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash'
+const installWinCommand = 'irm https://code.kimi.com/kimi-code/install.ps1 | iex'
+const runCommand = 'kimi'
+
+const copy = computed(() => isZh.value
+  ? {
+      title: '一行命令开始',
+      lede: '装好之后跑 kimi，立刻在你当前的项目里开聊。',
+      macLabel: 'macOS / Linux',
+      winLabel: 'Windows (PowerShell)',
+      runLabel: '在任意目录运行',
+      copyHint: '复制',
+      copiedHint: '已复制',
+      ctaText: '查看完整安装指南',
+      ctaHref: '/zh/guides/getting-started',
+    }
+  : {
+      title: 'Get started in one line',
+      lede: 'Once installed, run kimi inside any project to start a conversation.',
+      macLabel: 'macOS / Linux',
+      winLabel: 'Windows (PowerShell)',
+      runLabel: 'Run anywhere',
+      copyHint: 'Copy',
+      copiedHint: 'Copied',
+      ctaText: 'Read the full install guide',
+      ctaHref: '/en/guides/getting-started',
+    })
+
+const copiedKey = ref<string | null>(null)
+let copiedTimer: ReturnType<typeof setTimeout> | null = null
+
+function copyText(value: string, key: string) {
+  if (typeof navigator === 'undefined' || !navigator.clipboard) return
+  navigator.clipboard.writeText(value).then(() => {
+    copiedKey.value = key
+    if (copiedTimer) clearTimeout(copiedTimer)
+    copiedTimer = setTimeout(() => { copiedKey.value = null }, 1600)
+  })
+}
+</script>
+
+<template>
+  <section class="KimiHome__section KimiQuick">
+    <h2 class="KimiHome__sectionTitle">{{ copy.title }}</h2>
+    <p class="KimiHome__sectionLede">{{ copy.lede }}</p>
+
+    <div class="KimiQuick__installs">
+      <div class="KimiQuick__block">
+        <div class="KimiQuick__label">{{ copy.macLabel }}</div>
+        <div class="KimiQuick__cmd">
+          <code><span class="KimiQuick__prompt">$</span> {{ installMacCommand }}</code>
+          <button
+            type="button"
+            class="KimiQuick__copy"
+            @click="copyText(installMacCommand, 'mac')"
+            :aria-label="copy.copyHint"
+          >
+            <template v-if="copiedKey === 'mac'">{{ copy.copiedHint }}</template>
+            <template v-else>{{ copy.copyHint }}</template>
+          </button>
+        </div>
+      </div>
+
+      <div class="KimiQuick__block">
+        <div class="KimiQuick__label">{{ copy.winLabel }}</div>
+        <div class="KimiQuick__cmd">
+          <code><span class="KimiQuick__prompt">PS&gt;</span> {{ installWinCommand }}</code>
+          <button
+            type="button"
+            class="KimiQuick__copy"
+            @click="copyText(installWinCommand, 'win')"
+            :aria-label="copy.copyHint"
+          >
+            <template v-if="copiedKey === 'win'">{{ copy.copiedHint }}</template>
+            <template v-else>{{ copy.copyHint }}</template>
+          </button>
+        </div>
+      </div>
+    </div>
+
+    <div class="KimiQuick__block KimiQuick__block--run">
+      <div class="KimiQuick__label">{{ copy.runLabel }}</div>
+      <div class="KimiQuick__cmd">
+        <code><span class="KimiQuick__prompt">$</span> {{ runCommand }}</code>
+        <button
+          type="button"
+          class="KimiQuick__copy"
+          @click="copyText(runCommand, 'run')"
+          :aria-label="copy.copyHint"
+        >
+          <template v-if="copiedKey === 'run'">{{ copy.copiedHint }}</template>
+          <template v-else>{{ copy.copyHint }}</template>
+        </button>
+      </div>
+    </div>
+
+    <a class="KimiQuick__more" :href="withBase(copy.ctaHref)">
+      {{ copy.ctaText }}
+      <svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+        <path d="M6 3l5 5-5 5" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
+      </svg>
+    </a>
+  </section>
+</template>
+
+<style scoped>
+.KimiQuick__installs {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  margin-bottom: 16px;
+}
+
+.KimiQuick__block {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.KimiQuick__block--run {
+  margin-bottom: 28px;
+}
+
+.KimiQuick__label {
+  font-size: 13px;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+  color: var(--vp-c-text-3);
+}
+
+.KimiQuick__cmd {
+  position: relative;
+  display: flex;
+  align-items: center;
+  padding: 18px 22px;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: var(--kimi-radius-code);
+  font-family: var(--vp-font-family-mono);
+  font-size: 14.5px;
+  line-height: 1.4;
+  color: var(--vp-c-text-1);
+  overflow: hidden;
+  transition: border-color var(--kimi-transition), box-shadow var(--kimi-transition);
+}
+.KimiQuick__cmd:hover {
+  border-color: var(--vp-c-brand-1);
+  box-shadow: var(--vp-shadow-2);
+}
+.KimiQuick__cmd code {
+  flex: 1;
+  white-space: pre;
+  overflow-x: auto;
+  background: transparent !important;
+  color: inherit;
+  padding: 0;
+  font-size: inherit;
+  font-family: inherit;
+  border-radius: 0;
+}
+.KimiQuick__prompt {
+  color: var(--vp-c-brand-1);
+  margin-right: 8px;
+  user-select: none;
+  font-weight: 600;
+}
+
+.KimiQuick__copy {
+  flex: none;
+  margin-left: 12px;
+  padding: 6px 12px;
+  font-size: 12px;
+  font-weight: 600;
+  font-family: var(--vp-font-family-base);
+  letter-spacing: 0.01em;
+  color: var(--vp-c-text-2);
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  cursor: pointer;
+  transition: color var(--kimi-transition), border-color var(--kimi-transition), background var(--kimi-transition);
+}
+.KimiQuick__copy:hover {
+  color: var(--vp-c-brand-1);
+  border-color: var(--vp-c-brand-1);
+}
+
+.KimiQuick__more {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 15px;
+  font-weight: 600;
+  color: var(--vp-c-brand-1);
+  text-decoration: none;
+  transition: transform var(--kimi-transition), color var(--kimi-transition);
+}
+.KimiQuick__more:hover {
+  color: var(--vp-c-brand-2);
+  transform: translateX(3px);
+}
+</style>

docs/.vitepress/theme/components/KimiLogo.vue

@@ -0,0 +1,22 @@
+<script setup lang="ts">
+import logoUrl from '../Kimi.png'
+
+withDefaults(defineProps<{ size?: number }>(), { size: 56 })
+</script>
+
+<template>
+  <img
+    class="KimiLogo"
+    :src="logoUrl"
+    :width="size"
+    :height="size"
+    alt="Kimi"
+  />
+</template>
+
+<style scoped>
+.KimiLogo {
+  display: block;
+  object-fit: contain;
+}
+</style>

docs/.vitepress/theme/index.ts

@@ -0,0 +1,12 @@
+import type { Theme } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+import HomeLayout from './components/HomeLayout.vue'
+
+import './styles/vars.css'
+import './styles/base.css'
+import './styles/home.css'
+
+export default {
+  extends: DefaultTheme,
+  Layout: HomeLayout,
+} satisfies Theme

docs/.vitepress/theme/styles/base.css

@@ -0,0 +1,282 @@
+/**
+ * Base overrides applied to all pages.
+ * Touches links, inline code, code blocks, custom blocks, blockquotes, navbar, sidebar.
+ */
+
+html {
+  font-feature-settings: 'cv11', 'ss01', 'ss03';
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+body {
+  font-family: var(--vp-font-family-base);
+}
+
+/* --- Top navbar: blur + remove the hard bottom line --- */
+.VPNav,
+.VPNavBar {
+  background: rgba(255, 255, 255, 0.72) !important;
+  backdrop-filter: saturate(180%) blur(14px);
+  -webkit-backdrop-filter: saturate(180%) blur(14px);
+}
+.dark .VPNav,
+.dark .VPNavBar {
+  background: rgba(13, 17, 23, 0.72) !important;
+}
+.VPNavBar.has-sidebar .content,
+.VPNavBar:not(.home) {
+  border-bottom: 1px solid var(--vp-c-divider);
+}
+
+/* --- Sidebar: brand-tinted active item, slim left accent bar --- */
+.VPSidebarItem.is-active > .item .link .text,
+.VPSidebarItem.is-active > .item > .text {
+  color: var(--vp-c-brand-1);
+  font-weight: 600;
+}
+.VPSidebarItem.is-link.is-active > .item {
+  position: relative;
+}
+.VPSidebarItem.is-link.is-active > .item::before {
+  content: '';
+  position: absolute;
+  left: -14px;
+  top: 50%;
+  transform: translateY(-50%);
+  width: 3px;
+  height: 16px;
+  border-radius: 2px;
+  background: var(--kimi-brand-gradient);
+}
+
+/* --- Headings: tighter tracking, no underline on h2 --- */
+.vp-doc h1,
+.vp-doc h2,
+.vp-doc h3 {
+  letter-spacing: -0.02em;
+}
+.vp-doc h2 {
+  border-top: none;
+  padding-top: 24px;
+  margin-top: 48px;
+}
+
+/* --- Links --- */
+.vp-doc a:not(.header-anchor) {
+  color: var(--vp-c-brand-1);
+  text-decoration: underline;
+  text-decoration-color: transparent;
+  text-underline-offset: 4px;
+  text-decoration-thickness: 2px;
+  transition: text-decoration-color var(--kimi-transition), color var(--kimi-transition);
+  font-weight: 500;
+}
+.vp-doc a:not(.header-anchor):hover {
+  color: var(--vp-c-brand-2);
+  text-decoration-color: currentColor;
+}
+
+/* --- Inline code --- */
+.vp-doc :not(pre) > code {
+  background: var(--kimi-brand-soft);
+  color: var(--vp-c-brand-1);
+  padding: 2px 6px;
+  border-radius: 6px;
+  font-weight: 500;
+  font-size: 0.875em;
+  border: none;
+}
+
+/* Inline code inside headings: drop the chip, keep just the brand-colored monospace word */
+.vp-doc :is(h1, h2, h3, h4, h5, h6) code {
+  background: transparent;
+  padding: 0;
+  border-radius: 0;
+  font-size: 0.9em;
+  font-weight: inherit;
+  color: var(--vp-c-brand-1);
+}
+
+/* --- Code blocks --- */
+.vp-doc div[class*='language-'] {
+  border-radius: var(--kimi-radius-code);
+  background: var(--vp-c-bg-soft);
+  margin: 20px 0;
+  box-shadow: var(--vp-shadow-1);
+}
+.vp-doc div[class*='language-'] pre {
+  padding: 20px 24px;
+}
+.vp-doc div[class*='language-'] code {
+  font-family: var(--vp-font-family-mono);
+  font-size: 13.5px;
+  line-height: 1.7;
+}
+.vp-doc div[class*='language-'] .lang {
+  color: var(--vp-c-text-3);
+  font-size: 12px;
+}
+.vp-doc div[class*='language-'] button.copy {
+  border-radius: 8px;
+}
+
+/* --- Blockquote --- */
+.vp-doc blockquote {
+  border-left: 3px solid var(--vp-c-brand-1);
+  background: var(--kimi-brand-soft);
+  padding: 14px 18px;
+  border-radius: 0 var(--kimi-radius-code) var(--kimi-radius-code) 0;
+  margin: 20px 0;
+}
+.vp-doc blockquote > p {
+  color: var(--vp-c-text-2);
+  margin: 0;
+}
+
+/* --- Custom blocks (tip / warning / danger / info) --- */
+.vp-doc .custom-block {
+  border-radius: var(--kimi-radius-code);
+  border: none;
+  padding: 16px 20px;
+  margin: 20px 0;
+}
+.vp-doc .custom-block .custom-block-title {
+  font-weight: 600;
+  letter-spacing: -0.005em;
+}
+.vp-doc .custom-block.tip {
+  background: rgba(10, 122, 255, 0.08);
+  color: var(--vp-c-text-1);
+}
+.dark .vp-doc .custom-block.tip {
+  background: rgba(61, 149, 255, 0.12);
+}
+.vp-doc .custom-block.warning {
+  background: rgba(234, 179, 8, 0.10);
+  color: var(--vp-c-text-1);
+}
+.vp-doc .custom-block.danger {
+  background: rgba(239, 68, 68, 0.10);
+  color: var(--vp-c-text-1);
+}
+.vp-doc .custom-block.info {
+  background: rgba(148, 163, 184, 0.12);
+  color: var(--vp-c-text-1);
+}
+.vp-doc .custom-block.tip .custom-block-title { color: var(--vp-c-brand-1); }
+.vp-doc .custom-block.warning .custom-block-title { color: #ca8a04; }
+.vp-doc .custom-block.danger .custom-block-title { color: #dc2626; }
+.dark .vp-doc .custom-block.warning .custom-block-title { color: #eab308; }
+.dark .vp-doc .custom-block.danger .custom-block-title { color: #ef4444; }
+
+/* --- Tables --- */
+.vp-doc table {
+  border-radius: var(--kimi-radius-code);
+  overflow: hidden;
+  border-collapse: separate;
+  border-spacing: 0;
+  display: table;
+  width: 100%;
+}
+.vp-doc tr {
+  background: transparent !important;
+  border-top: 1px solid var(--vp-c-divider);
+}
+.vp-doc tr:first-child { border-top: none; }
+.vp-doc th {
+  background: var(--vp-c-bg-soft);
+  font-weight: 600;
+  color: var(--vp-c-text-1);
+}
+
+/* --- Outline / TOC --- */
+.VPDocAsideOutline .outline-link.active,
+.VPDocAsideOutline .outline-link:hover {
+  color: var(--vp-c-brand-1);
+}
+
+/* --- Buttons globally (e.g. hero CTAs) --- */
+.VPButton.brand {
+  background: var(--kimi-brand-gradient) !important;
+  border: none !important;
+  box-shadow: var(--vp-shadow-3);
+  transition: transform var(--kimi-transition), box-shadow var(--kimi-transition);
+}
+.VPButton.brand:hover {
+  transform: translateY(-2px);
+  box-shadow: var(--vp-shadow-4);
+}
+.VPButton.alt {
+  background: transparent !important;
+  border: 1px solid var(--vp-c-divider) !important;
+  color: var(--vp-c-text-1) !important;
+  transition: border-color var(--kimi-transition), transform var(--kimi-transition);
+}
+.VPButton.alt:hover {
+  border-color: var(--vp-c-brand-1) !important;
+  transform: translateY(-2px);
+}
+
+/* --- Hero default frontmatter (used as fallback when custom Home not rendered) --- */
+.VPHero .name,
+.VPHero .text {
+  letter-spacing: -0.03em;
+}
+
+/* --- Footer --- */
+.VPFooter {
+  border-top: 1px solid var(--vp-c-divider);
+  background: transparent;
+}
+
+/* --- Step rail (numbered steps on guides/web) --- */
+.vp-doc .step-num {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.45em;
+  height: 1.45em;
+  border-radius: 50%;
+  background: #f4f5f7;
+  color: #8a919c;
+  font-size: 0.85em;
+  font-weight: 500;
+  line-height: 1;
+  margin-right: 0.6em;
+  vertical-align: 0.1em;
+}
+.vp-doc .step {
+  position: relative;
+  border-left: 2px solid #f0f2f5;
+  padding-left: 1.4em;
+  margin-left: 0.75em;
+  padding-bottom: 0.6em;
+}
+.vp-doc .step:last-of-type {
+  border-left-color: transparent;
+}
+.vp-doc .step .step-num {
+  position: absolute;
+  left: -0.78em;
+  top: 0.15em;
+  margin-right: 0;
+}
+
+/* --- Feature compare table (fixed-width ✓ columns on guides/web) --- */
+.feature-compare-table table {
+  table-layout: fixed;
+  width: 100%;
+}
+.feature-compare-table th:nth-child(1),
+.feature-compare-table td:nth-child(1) {
+  width: 8em;
+  white-space: nowrap;
+}
+.feature-compare-table th:nth-child(2),
+.feature-compare-table td:nth-child(2),
+.feature-compare-table th:nth-child(3),
+.feature-compare-table td:nth-child(3) {
+  width: 4.5em;
+  text-align: center;
+}

docs/.vitepress/theme/styles/home.css

@@ -0,0 +1,85 @@
+/**
+ * Home-only styles. Scoped CSS in components handles most rules;
+ * shared utilities and layout container live here.
+ */
+
+.KimiHome {
+  --section-px: clamp(20px, 5vw, 64px);
+  --section-py: clamp(28px, 4vw, 56px);
+  position: relative;
+  padding: 0 var(--section-px);
+}
+
+.KimiHome__section {
+  max-width: 1152px;
+  margin: 0 auto;
+  padding: var(--section-py) 0;
+  position: relative;
+}
+
+.KimiHome__sectionTitle {
+  font-size: clamp(28px, 4vw, 40px);
+  font-weight: 700;
+  letter-spacing: -0.03em;
+  margin: 0 0 12px;
+  color: var(--vp-c-text-1);
+}
+
+.KimiHome__sectionLede {
+  font-size: 17px;
+  color: var(--vp-c-text-2);
+  margin: 0 0 40px;
+  max-width: 640px;
+  line-height: 1.6;
+}
+
+.KimiBtn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  height: 48px;
+  padding: 0 22px;
+  border-radius: var(--kimi-radius-button);
+  font-size: 15px;
+  font-weight: 600;
+  letter-spacing: -0.005em;
+  text-decoration: none;
+  transition: transform var(--kimi-transition), box-shadow var(--kimi-transition),
+              border-color var(--kimi-transition), background var(--kimi-transition);
+  white-space: nowrap;
+  cursor: pointer;
+  border: 1px solid transparent;
+}
+.KimiBtn--primary {
+  color: #ffffff;
+  background: var(--kimi-brand-gradient);
+  box-shadow: var(--vp-shadow-3);
+  border: 0;
+}
+.KimiBtn--primary:hover {
+  transform: translateY(-2px);
+  box-shadow: var(--vp-shadow-4);
+  color: #ffffff;
+}
+.KimiBtn--ghost {
+  color: var(--vp-c-text-1);
+  background: transparent;
+  border-color: var(--vp-c-divider);
+}
+.KimiBtn--ghost:hover {
+  border-color: var(--vp-c-brand-1);
+  transform: translateY(-2px);
+  color: var(--vp-c-text-1);
+}
+.KimiBtn--link {
+  color: var(--vp-c-brand-1);
+  height: auto;
+  padding: 0;
+  background: transparent;
+  border: none;
+}
+.KimiBtn--link:hover {
+  color: var(--vp-c-brand-2);
+  transform: translateX(2px);
+}

docs/.vitepress/theme/styles/vars.css

@@ -0,0 +1,120 @@
+/**
+ * Design tokens for the Kimi Code docs theme.
+ * Light + dark live side by side; VitePress toggles the .dark class on <html>.
+ */
+
+:root {
+  /* Brand palette — cool blue family from design board */
+  --kimi-brand-1: #0a7aff;          /* primary */
+  --kimi-brand-2: #5baeff;           /* mid */
+  --kimi-brand-3: #81c4ff;           /* soft sky */
+  --kimi-brand-deep: #043153;        /* deep navy (anchor for dark surfaces) */
+  --kimi-brand-whisper: #eff8ff;     /* near-white blue (light tints) */
+  --kimi-brand-gradient: linear-gradient(135deg, #0a7aff 0%, #5baeff 60%, #81c4ff 100%);
+  --kimi-brand-gradient-soft: linear-gradient(135deg, rgba(10, 122, 255, 0.14) 0%, rgba(91, 174, 255, 0.12) 60%, rgba(129, 196, 255, 0.10) 100%);
+  --kimi-brand-soft: rgba(10, 122, 255, 0.10);
+  --kimi-brand-soft-strong: rgba(10, 122, 255, 0.16);
+
+  /* Shape */
+  --kimi-radius-card: 16px;
+  --kimi-radius-button: 10px;
+  --kimi-radius-chip: 999px;
+  --kimi-radius-code: 12px;
+  --kimi-transition: 200ms cubic-bezier(0.4, 0, 0.2, 1);
+
+  /* Typography */
+  --vp-font-family-base:
+    'Inter', -apple-system, BlinkMacSystemFont,
+    'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei',
+    'Helvetica Neue', 'Segoe UI', Arial, sans-serif;
+  --vp-font-family-mono:
+    ui-monospace, SFMono-Regular, 'SF Mono',
+    Menlo, Consolas, 'Liberation Mono', 'Courier New', monospace;
+
+  /* Surfaces (light) — clean white + subtle blue-tinted off-white */
+  --vp-c-bg: #ffffff;
+  --vp-c-bg-alt: #f6f9fd;
+  --vp-c-bg-elv: #ffffff;
+  --vp-c-bg-soft: #eff5fc;
+
+  /* Text (light) */
+  --vp-c-text-1: #0b1a30;
+  --vp-c-text-2: #475569;
+  --vp-c-text-3: #94a3b8;
+
+  /* Borders (light) — picked up from palette E1E3E6 */
+  --vp-c-divider: #e1e3e6;
+  --vp-c-gutter: #e1e3e6;
+  --vp-c-border: #e1e3e6;
+
+  /* Brand applied to VitePress vars (light) */
+  --vp-c-brand-1: var(--kimi-brand-1);
+  --vp-c-brand-2: var(--kimi-brand-2);
+  --vp-c-brand-3: #006ae3;          /* hover, slightly deeper than primary */
+  --vp-c-brand-soft: var(--kimi-brand-soft);
+
+  /* Shadows (light) — no negative spread, avoids "kink" at rounded corners */
+  --vp-shadow-1: 0 1px 2px rgba(11, 26, 48, 0.04);
+  --vp-shadow-2: 0 6px 20px rgba(10, 122, 255, 0.15);
+  --vp-shadow-3: 0 10px 28px rgba(10, 122, 255, 0.22);
+  --vp-shadow-4: 0 18px 44px rgba(10, 122, 255, 0.30);
+
+  /* Buttons (light) */
+  --vp-button-brand-bg: var(--kimi-brand-1);
+  --vp-button-brand-hover-bg: var(--vp-c-brand-3);
+  --vp-button-brand-active-bg: var(--vp-c-brand-3);
+  --vp-button-brand-border: transparent;
+  --vp-button-brand-hover-border: transparent;
+  --vp-button-brand-text: #ffffff;
+  --vp-button-brand-hover-text: #ffffff;
+  --vp-button-brand-active-text: #ffffff;
+
+  /* Custom blocks tinting (light) */
+  --vp-custom-block-tip-border: transparent;
+  --vp-custom-block-tip-text: var(--vp-c-text-1);
+  --vp-custom-block-tip-bg: rgba(10, 122, 255, 0.07);
+  --vp-custom-block-tip-code-bg: rgba(10, 122, 255, 0.10);
+}
+
+.dark {
+  /* Surfaces (dark) — neutral dark with subtle navy undertone */
+  --vp-c-bg: #0a1422;
+  --vp-c-bg-alt: #0f1b2e;
+  --vp-c-bg-elv: #0f1b2e;
+  --vp-c-bg-soft: #15263f;
+
+  /* Text (dark) — avoid pure white */
+  --vp-c-text-1: #e2e8f0;
+  --vp-c-text-2: #94a3b8;
+  --vp-c-text-3: #64748b;
+
+  /* Borders (dark) — navy-leaning to stay in family */
+  --vp-c-divider: #1b2e47;
+  --vp-c-gutter: #1b2e47;
+  --vp-c-border: #1b2e47;
+
+  /* Brand applied (dark) — keep the pure blue family, brightened */
+  --vp-c-brand-1: #3d95ff;
+  --vp-c-brand-2: #81c4ff;
+  --vp-c-brand-3: #5baeff;
+  --vp-c-brand-soft: rgba(61, 149, 255, 0.16);
+
+  /* Softs (dark) */
+  --kimi-brand-soft: rgba(61, 149, 255, 0.16);
+  --kimi-brand-soft-strong: rgba(61, 149, 255, 0.22);
+
+  /* Shadows (dark) — brand-tinted glow, no negative spread */
+  --vp-shadow-1: 0 1px 2px rgba(0, 0, 0, 0.4);
+  --vp-shadow-2: 0 6px 24px rgba(61, 149, 255, 0.22);
+  --vp-shadow-3: 0 10px 32px rgba(61, 149, 255, 0.32);
+  --vp-shadow-4: 0 18px 48px rgba(61, 149, 255, 0.42);
+
+  /* Buttons (dark) */
+  --vp-button-brand-bg: var(--kimi-brand-1);
+  --vp-button-brand-hover-bg: #1f8cff;
+  --vp-button-brand-active-bg: #1f8cff;
+
+  /* Custom blocks tinting (dark) */
+  --vp-custom-block-tip-bg: rgba(61, 149, 255, 0.12);
+  --vp-custom-block-tip-code-bg: rgba(61, 149, 255, 0.16);
+}

docs/en/configuration/config-files.md

@@ -0,0 +1,619 @@
+# Configuration files
+
+Kimi Code CLI writes all long-term preferences into TOML (plain-text configuration) files under `~/.kimi-code/`: runtime settings live in `config.toml`, and terminal-UI preferences live in a companion `tui.toml`.
+
+## Config file location
+
+The CLI reads configuration from `~/.kimi-code/config.toml`, created automatically on first run. To relocate the data directory, override it with the `KIMI_CODE_HOME` environment variable:
+
+```sh
+export KIMI_CODE_HOME=/path/to/kimi-home
+```
+
+The config file path then becomes `$KIMI_CODE_HOME/config.toml`. Regardless of where the directory lives, the file name is always `config.toml`.
+
+::: tip
+TOML field names always use snake_case, for example `default_model` and `max_context_size`. If a key contains `.`, you must quote it (for example `[models."gpt-4.1"]`); otherwise TOML treats `.` as a nested table separator.
+:::
+
+## Complete example
+
+The following example covers the most commonly used configuration fields. You can copy it and adjust as needed:
+
+```toml
+default_model = "kimi-code/k3"
+default_permission_mode = "manual"
+default_plan_mode = false
+merge_all_available_skills = true
+telemetry = true
+
+[providers."managed:kimi-code"]
+type = "kimi"
+base_url = "https://api.kimi.com/coding/v1"
+api_key = ""
+
+[models."kimi-code/k3"]
+provider = "managed:kimi-code"
+model = "k3"
+max_context_size = 1048576
+capabilities = [ "thinking", "always_thinking", "image_in", "video_in", "tool_use" ]
+display_name = "K3"
+support_efforts = [ "low", "high", "max" ]
+default_effort = "max"
+
+[models."kimi-code/kimi-for-coding"]
+provider = "managed:kimi-code"
+model = "kimi-for-coding"
+max_context_size = 262144
+capabilities = [ "thinking", "always_thinking", "image_in", "video_in", "tool_use" ]
+
+[models."kimi-code/kimi-for-coding-highspeed"]
+provider = "managed:kimi-code"
+model = "kimi-for-coding-highspeed"
+max_context_size = 262144
+capabilities = [ "thinking", "always_thinking", "image_in", "video_in", "tool_use" ]
+
+[thinking]
+enabled = true
+effort = "high"
+keep = "all"
+
+[loop_control]
+max_attempts_per_step = 10
+reserved_context_size = 50000
+
+[background]
+max_running_tasks = 4
+keep_alive_on_exit = false
+
+[services.moonshot_search]
+base_url = "https://api.kimi.com/coding/v1/search"
+api_key = ""
+
+[services.moonshot_fetch]
+base_url = "https://api.kimi.com/coding/v1/fetch"
+api_key = ""
+
+[[permission.rules]]
+decision = "allow"
+pattern = "Read"
+
+[[permission.rules]]
+decision = "deny"
+pattern = "Bash(rm -rf*)"
+
+[[hooks]]
+event = "PreToolUse"
+matcher = "Bash"
+command = "node ~/.kimi-code/hooks/check-bash.mjs"
+timeout = 5
+```
+
+## Top-level fields
+
+Fields in the config file fall into two categories: **top-level scalars** that directly control default behavior, and **nested tables** (`providers`, `models`, `thinking`, etc.) that each have their own structure, described individually in the sections below.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `default_model` | `string` | — | Default model alias; must be defined in `models` |
+| `default_permission_mode` | `string` | `manual` | Default permission mode for new sessions: `manual`, `yolo`, or `auto`. See [the three permission modes](../guides/interaction.md#the-three-permission-modes) |
+| `default_plan_mode` | `boolean` | `false` | Whether new sessions start in [Plan mode](../guides/interaction.md#plan-mode) by default |
+| `merge_all_available_skills` | `boolean` | `true` | Whether to merge Agent Skills from all available directories |
+| `extra_skill_dirs` | `array<string>` | — | Extra skill search directories, layered on top of the default directories |
+| `extra_agent_dirs` | `array<string>` | — | Extra custom agent search directories, layered on top of the default directories |
+| `builtin_product_skills` | `boolean` | `true` | Whether the built-in skills that document Kimi Code itself are offered to the model |
+| `telemetry` | `boolean` | `true` | Whether anonymous telemetry is enabled; disabled only when explicitly set to `false` |
+| [`providers`](#providers) | `table` | `{}` | API provider table |
+| [`models`](#models) | `table` | — | Model alias table |
+| [`thinking`](#thinking) | `table` | — | Default parameters for Thinking mode |
+| [`loop_control`](#loop_control) | `table` | — | Agent loop control parameters |
+| [`background`](#background) | `table` | — | Background task runtime parameters |
+| [`tools`](#tools) | `table` | — | Global tool switch |
+| [`image`](#image) | `table` | — | Image compression parameters |
+| [`services`](#services) | `table` | — | Built-in external service configuration |
+| [`permission`](#permission) | `table` | — | Initial permission rules |
+| [`hooks`](../customization/hooks.md) | `array<table>` | — | Lifecycle hooks |
+| [`identity`](#identity) | `table` | — | Custom agent identity |
+
+## `providers`
+
+Each entry in the `providers` table defines an API provider, keyed by a unique name. The CLI reads credentials only from here. It does **not** fall back to shell environment variables automatically: running `export KIMI_API_KEY` in the terminal does not give any provider its key; you must write it explicitly in the config file (see [Config overrides](./overrides.md#provider-credentials)).
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `type` | `string` | Yes | Provider type: `kimi`, `anthropic`, `openai`, `openai_responses`, `google-genai`, `vertexai` |
+| `api_key` | `string` | No | API key, written in plain text in the config file |
+| `base_url` | `string` | No | API base URL |
+| `oauth` | `table` | No | OAuth credential reference (`storage` and `key` fields); injected automatically by the login flow, so you normally never write this by hand |
+| `env` | `table<string, string>` | No | Fallback source for provider credentials; see the `env` sub-table |
+| `custom_headers` | `table<string, string>` | No | Custom HTTP headers attached to each request |
+
+**`env` sub-table**: You can write provider-conventional key names (such as `KIMI_API_KEY`) inside `[providers.<name>.env]` as a fallback source for `api_key` / `base_url`. This sub-table is **read only from the config file** and does not modify the shell environment:
+
+```toml
+[providers.kimi.env]
+KIMI_API_KEY = "sk-xxx"
+KIMI_BASE_URL = "https://api.moonshot.ai/v1"
+```
+
+Priority: `api_key` field > `env` sub-table key > if both are absent, startup fails with an error.
+
+## `models`
+
+Each entry in the `models` table defines a model alias (the name used in `default_model` or the `-m` flag), keyed by a unique name.
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `provider` | `string` | Yes | Name of the provider to use; must be defined in `providers` |
+| `model` | `string` | Yes | Model identifier sent to the server when calling the API |
+| `max_context_size` | `integer` | Yes | Maximum context length in tokens; must be at least 1 |
+| `max_input_size` | `integer` | No | Declared per-request input limit; compaction, context-overflow checks, and usage ratios prefer it, completion budgeting keeps the total window |
+| `max_output_size` | `integer` | No | Per-request output token cap (maps to `max_tokens`); currently only the `anthropic` provider reads it |
+| `capabilities` | `array<string>` | No | Capability tags added explicitly: `thinking`, `always_thinking`, `image_in`, `video_in`, `audio_in`, `tool_use`, `dynamically_loaded_tools`; only ever added, never removed |
+| `support_efforts` | `array<string>` | No | Thinking effort levels the model accepts; unsupported values fall back to `default_effort`, out-of-list values fail; managed refreshes may rewrite it (pin via overrides) |
+| `default_effort` | `string` | No | Default thinking effort for the model; managed and open-platform refreshes may rewrite it. Pin via [model overrides](#model-overrides) |
+| `off_effort` | `string` | No | Effort value sent on the wire to disable thinking (e.g. `none` for xai grok); the only way to actually stop reasoning on models that reason by default |
+| `base_url` | `string` | No | Per-model endpoint override (written by catalog imports); takes precedence over the provider's `base_url`, only effective together with `protocol` |
+| `display_name` | `string` | No | Name shown in the UI; falls back to `model` when unset |
+| `reasoning_key` | `string` | No | `openai` provider only; set when the gateway returns reasoning content under a non-standard field name (`reasoning_content` and friends are auto-detected) |
+| `adaptive_thinking` | `boolean` | No | `anthropic` provider only; force adaptive thinking on or off, omit to infer from the model name (Claude ≥ 4.6 uses adaptive) |
+
+When an alias contains `.`, use a quoted key:
+
+```toml
+[models."gpt-4.1"]
+provider = "openai"
+model = "gpt-4.1"
+max_context_size = 1047576
+```
+
+### Model overrides
+
+Use `[models."<alias>".overrides]` for user overrides that must survive provider-model refreshes. Runtime consumers read the effective value: the override when present, otherwise the top-level field.
+
+```toml
+[models."kimi-code/kimi-for-coding"]
+provider = "managed:kimi-code"
+model = "kimi-for-coding"
+max_context_size = 262144
+
+[models."kimi-code/kimi-for-coding".overrides]
+max_context_size = 131072
+display_name = "Kimi for Coding (custom)"
+```
+
+`[models."<alias>".overrides]` accepts ordinary model fields such as `max_context_size`, `max_input_size`, `max_output_size`, `capabilities`, `display_name`, `reasoning_key`, `adaptive_thinking`, `support_efforts`, `default_effort`, and `off_effort`. It does not accept identity / routing fields: `provider`, `model`, `protocol`, `beta_api`, and `base_url`.
+
+You can also switch models temporarily without touching the config file: setting `KIMI_MODEL_*` environment variables synthesizes a temporary provider in memory that does not persist after restart. See [Define a model from environment variables](./env-vars.md#define-a-model-from-environment-variables-kimi_model_).
+
+## `secondary_model`
+
+Subagents inherit the model the main agent is running by default. The `[secondary_model]` section makes this configurable: it offers subagents a pool of candidate models plus a default binding. Typically that is a cheaper model for subtasks that do not need the main model's capability.
+
+### Subagent model pool
+
+The pool is always available and needs no opt-in; with no `[secondary_model]` keys configured, subagents simply inherit the caller's model.
+
+The minimal configuration is one line. A lone `default_model` is a pool with a single entry:
+
+```toml
+[secondary_model]
+default_model = "kimi-code/kimi-for-coding-highspeed"
+```
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `default_model` | `string` | — | The default model for subagents |
+| `models` | `table<string, string>` | — | Subagent model pool; each key is the alias of a configured [`[models]`](#models) entry, each value a selection hint |
+| `force` | `boolean` | `false` | Pin every subagent to `default_model`, taking the choice away from the main agent |
+| `default_effort` | `string` | — | The thinking effort every spawned subagent binds with; outranks the bound model entry's own `default_effort` |
+
+Constraints between the fields:
+
+- `default_model`: required when a `models` table is configured, and must be one of its keys.
+- `models`: values may be Chinese or English; an empty string lists the alias with no hint.
+- `force`: requires `default_model` and cannot be combined with a `models` table: the table exists to offer a choice, and force removes it.
+- `default_effort` is section-wide: every spawn binds it regardless of the chosen pool entry (or the forced model). For per-entry efforts, leave it unset and use model variants (see below).
+- `primary` is a reserved alias (see below) and cannot be a pool key.
+
+Pool aliases reference the current `[models]` table: if a provider is later deleted or logged out, or its refreshed model list no longer contains an alias, session startup fails with a configuration error naming the broken alias. Fix or remove the entry to recover. The `[secondary_model]` section itself is never rewritten automatically.
+
+In the interactive TUI, the [`/secondary-model`](../reference/slash-commands.md) command (alias `/subagent-model`) opens a model selector: the choice is written to `default_model` (when a models table exists and the picked alias is not in it, an entry with an empty description is added), and newly spawned subagents pick up the new default immediately, no session restart needed.
+
+A configured pool (an explicit `models` table or a lone `default_model`) enables model selection: the `Agent` / `AgentSwarm` tools gain a `model` parameter, and the tool description lists the pool (the default marked `[default]`) so the main agent can choose per spawn. Pool keys can only reference configured [`[models]`](#models) entries. The `kimi-code/*` aliases below are provisioned by `/login`:
+
+```toml
+[secondary_model]
+default_model = "kimi-code/kimi-for-coding-highspeed"
+[secondary_model.models]
+"kimi-code/k3" = "Pick this for hard problems. Strong at complex reasoning, algorithm design, deep debugging, math, and systematic challenges."
+"kimi-code/kimi-for-coding-highspeed" = "Fast but priced higher. Good for latency-sensitive tasks: daily refactoring, code explanation, small edits, and summaries."
+"kimi-code/kimi-for-coding" = "A balanced coding workhorse. Good for most feature development and code-change tasks."
+```
+
+A spawn resolves the subagent's model in this order:
+
+1. An explicit `model` passed in the tool call
+2. `default_model`
+
+Rules for the `model` parameter:
+
+- It accepts any pool alias, or `"primary"`, the model the caller itself is running; always valid even when not in the pool.
+- When neither `default_model` nor `models` is configured, the parameter is not advertised and subagents inherit the caller's model.
+- Binding a pool alias does not inherit the caller's thinking effort. The section's `default_effort` wins when set. Otherwise, `[thinking].enabled = false` keeps Thinking off; when Thinking is enabled, resolution continues with the bound model entry's `default_effort`, the global `[thinking].effort`, then the middle of the bound model's `support_efforts`.
+- `"primary"` inherits both the model and the effort level from the caller.
+- A value that is neither a pool alias nor `"primary"` fails the spawn with an error listing the available choices.
+
+To take the choice away from the main agent and run every subagent on one fixed model, add `force = true`:
+
+```toml
+[secondary_model]
+default_model = "kimi-code/kimi-for-coding-highspeed"
+force = true
+```
+
+With `force` set, the `model` parameter is not advertised (just like when nothing is configured) and every spawn binds `default_model`; an explicit `model` argument, `"primary"` included, is rejected with an error.
+
+### Different thinking efforts per pool entry
+
+Binding a pool alias lands the subagent on the bound model's default effort. You can exploit this by registering a "variant" entry for the same underlying model, so the main agent picks the thinking level together with the alias:
+
+1. Register a second entry for the same underlying model in [`[models]`](#models), overriding only `default_effort` via [`[models."<alias>".overrides]`](#model-overrides).
+2. List both the original alias and the variant alias in the pool.
+
+```toml
+# "kimi-code/k3" is provisioned by /login (default: high); this registers
+# a max-effort variant of the same model
+[models.k3-max]
+provider = "managed:kimi-code"
+model = "k3"
+max_context_size = 1048576
+capabilities = [ "thinking", "always_thinking", "image_in", "video_in", "tool_use" ]
+support_efforts = [ "low", "high", "max" ]
+
+[models.k3-max.overrides]
+default_effort = "max"
+
+[secondary_model]
+default_model = "kimi-code/k3"
+[secondary_model.models]
+"kimi-code/k3" = "Default high effort. Good for most implementation, analysis, and multi-turn interaction tasks."
+k3-max = "The same model at max thinking effort. Good for the hardest subtasks."
+```
+
+Two prerequisites:
+
+- The underlying model must declare `support_efforts` (under `managed:kimi-code` only the k3 family currently declares effort levels).
+- The variant is a standalone entry and does not inherit fields from the entry it points at: copy `capabilities`, `support_efforts`, and the other metadata over in full, otherwise `default_effort` has no effect (it must be a member of `support_efforts`).
+
+Note the asymmetry between the main agent and pool-bound subagents: for the main agent, a configured global `[thinking].effort` overrides the variant's `default_effort`; for subagents the variant's `default_effort` wins over the global value, and only `[secondary_model].default_effort` outranks it. Value and fallback rules follow the [`[models]` entry's `default_effort`](#models).
+
+::: warning Note
+Configuration errors fail loudly instead of falling back silently. Session creation, resume, and fork all fail at startup when:
+
+- `default_model` is missing, is not a pool key, or a pool key does not resolve to a configured [`[models]`](#models) entry;
+- `force` is set without `default_model`, or combined with a `models` table.
+:::
+
+## `thinking`
+
+`thinking` sets the global default behavior for Thinking mode.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | `boolean` | `true` | Whether Thinking is enabled by default for new sessions; set to `false` to force Thinking off |
+| `effort` | `string` | — | Thinking effort: `low` / `medium` / `high` / `xhigh` / `max`; falls back to the model default when not in its supported list |
+| `keep` | `string` | `"all"` | Preserved Thinking passthrough: `kimi` sends it as `thinking.keep`, `anthropic` as a `clear_thinking_20251015` edit (routes to the beta Messages API). An off-value disables it; overridden by `KIMI_MODEL_THINKING_KEEP`; injected only while Thinking is on |
+
+<details><summary>Deprecated fields</summary>
+
+| Field | Deprecated in | Description |
+| --- | --- | --- |
+| `default_thinking` | 0.21.0 | Top-level boolean, replaced by `[thinking] enabled`. Migrate `default_thinking = true` to `enabled = true`, and `default_thinking = false` to `enabled = false`. |
+| `thinking.mode` | 0.21.0 | One of `auto` / `on` / `off`, replaced by `[thinking] enabled`. `mode = "off"` becomes `enabled = false`; `mode = "on"` and `mode = "auto"` are equivalent to `enabled = true` (the default) and can be removed. |
+| `loop_control.max_retries_per_step` | 0.32.0 | Replaced by `loop_control.max_attempts_per_step` (the value was always a total-attempt limit, including the first try). The old key is ignored and reports a warning on startup; rename it in `config.toml`. |
+| `loop_control.max_steps_per_run` | 0.32.0 | Replaced by `loop_control.max_steps_per_turn`. The old key is ignored and reports a warning on startup; rename it in `config.toml`. |
+
+</details>
+
+## `loop_control`
+
+`loop_control` governs the step count limit, the per-step attempt limit, and the thresholds and attempt limit for automatic context compaction in the Agent execution loop.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `max_steps_per_turn` | `integer` | — | Maximum steps per turn; unset or `0` means unlimited |
+| `max_attempts_per_step` | `integer` | `10` | Maximum total attempts for a failing step, including the initial attempt |
+| `reserved_context_size` | `integer` | — | Number of tokens reserved for model output; automatic compaction is triggered when the remaining context window falls below this value |
+| `compaction_max_attempts` | `integer` | `5` | Maximum total attempts for a failing compaction request, including the initial attempt |
+
+`max_steps_per_turn` can be overridden by the `KIMI_LOOP_MAX_STEPS_PER_TURN` environment variable, and `max_attempts_per_step` by `KIMI_LOOP_MAX_ATTEMPTS_PER_STEP`; both take higher priority than the config file. The former `KIMI_LOOP_MAX_RETRIES_PER_STEP` variable is deprecated but still honored (with a startup warning) when the new one is unset.
+
+Retries only apply to transient failures: connection errors, timeouts, HTTP 429 rate limits, and 5xx server errors. A 429 caused by an exhausted quota or insufficient account balance is not retried and fails immediately, since it cannot succeed until the account is recharged.
+
+## `token_counting`
+
+`token_counting` selects which context token count is reported externally, the value behind the context-size display. Internal logic (automatic compaction triggers, budgets, and overflow backoff) always uses both provider-reported usage and estimates, regardless of this setting.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `strategy` | `"measured+estimated" \| "measured" \| "estimated"` | `"measured+estimated"` | `measured+estimated` combines measured usage with an estimate of the unmeasured tail; `measured` reports provider usage alone, updated when a request completes; `estimated` is a pure estimate, for providers that do not report usage |
+
+`strategy` can be overridden by the `KIMI_TOKEN_COUNTING_STRATEGY` environment variable, which takes higher priority than `config.toml`.
+
+## `background`
+
+`background` controls the concurrency behavior of background tasks (launched via the `Bash` tool or the `Agent` tool's `run_in_background=true` parameter).
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `max_running_tasks` | `integer` | — | Maximum number of background tasks running concurrently |
+| `keep_alive_on_exit` | `boolean` | `false` | Whether to keep still-running background tasks when the session closes; in print mode only a fallback when `print_background_mode` is unset (`true` = `drain`) |
+| `kill_grace_period_ms` | `integer` | `5000` | Grace period in milliseconds after a task is asked to terminate; still-running tasks are force-stopped when it elapses |
+| `bash_auto_background_on_timeout` | `boolean` | `true` | Move a foreground `Bash` command to a background task on timeout instead of killing it; set to `false` to kill timed-out foreground commands instead |
+| `bash_task_timeout_s` | `integer` | `600` | Default timeout (seconds) for background `Bash` tasks when the call omits `timeout`; `0` means no timeout. Explicit per-call `timeout` values are unaffected; print mode defaults to `0` |
+| `print_background_mode` | `"exit" \| "drain" \| "steer"` | `"steer"` | Print mode only: how pending background tasks are handled when the main agent's turn ends; `"exit"` exits immediately, `"drain"` waits for terminal states without feeding results back, `"steer"` injects completions as synthetic user messages steering new turns until none are pending |
+| `print_wait_ceiling_s` | `integer` | `2147483` | Wall-clock ceiling (seconds) for the print-mode wait/steer loop; no effect outside print mode or with `"exit"` |
+| `print_max_turns` | `integer` | `100000` | Maximum number of new turns triggered by background-task completions in `"steer"` mode; keeps the steering loop bounded |
+
+`keep_alive_on_exit` can be overridden by the `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` environment variable, `max_running_tasks` by `KIMI_CODE_BACKGROUND_MAX_RUNNING_TASKS`, `bash_task_timeout_s` by `KIMI_CODE_BACKGROUND_BASH_TASK_TIMEOUT_S`, and `print_background_mode`, `print_wait_ceiling_s`, and `print_max_turns` by `KIMI_CODE_BACKGROUND_PRINT_BACKGROUND_MODE`, `KIMI_CODE_BACKGROUND_PRINT_WAIT_CEILING_S`, and `KIMI_CODE_BACKGROUND_PRINT_MAX_TURNS`; all take higher priority than `config.toml`.
+
+In print mode (`kimi -p "<prompt>"`), Kimi Code stays alive after the main agent's turn as long as background tasks are still pending: each completion is fed back to the main agent as a synthetic user message, steering it into a new turn (`print_background_mode = "steer"` by default), and the run exits once a turn ends with nothing pending. The loop is bounded by `print_wait_ceiling_s` and `print_max_turns`, both effectively unbounded by default. Background work is never killed by a wall-clock cap in print mode either: background `Bash` tasks default to no timeout (`bash_task_timeout_s = 0`), and subagents run without a timeout (`[subagent] timeout_ms` and `[swarm] timeout_ms` both default to `0` unless explicitly set), so only the model itself stops a task. Set `print_background_mode` to `"drain"` to wait for tasks without feeding results back, or `"exit"` to end the run as soon as the main agent finishes.
+
+## `subagent`
+
+`subagent` controls how subagents spawned by the `Agent` tool run.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `timeout_ms` | `integer` | `7200000` (2 hours) | Maximum wall-clock time (milliseconds) a single `Agent` subagent may run before it is settled as `timed_out`; `0` means no timeout |
+
+`timeout_ms` can be overridden by the `KIMI_SUBAGENT_TIMEOUT_MS` environment variable, which takes higher priority than `config.toml`.
+
+## `swarm`
+
+`swarm` controls how subagents launched by the `AgentSwarm` tool run, independently of `[subagent]`.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `timeout_ms` | `integer` | `7200000` (2 hours) | Maximum wall-clock time (milliseconds) a single `AgentSwarm` subagent may run; on timeout it is aborted and the aggregated report marks `Subagent timed out.`; `0` means no timeout |
+
+`timeout_ms` can be overridden by the `KIMI_CODE_SWARM_TIMEOUT_MS` environment variable, which takes higher priority than `config.toml`.
+
+## `mcp`
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `startup_timeout_ms` | `integer` | `30000` (30 seconds) | Global default connection (startup + tool discovery) timeout in milliseconds for all MCP servers; a per-server `startupTimeoutMs` in `mcp.json` wins |
+| `tool_timeout_ms` | `integer` | `60000` (60 seconds) | Global default single tool-call timeout in milliseconds for all MCP servers; a per-server `toolTimeoutMs` in `mcp.json` wins |
+
+`startup_timeout_ms` and `tool_timeout_ms` can be overridden by the `KIMI_MCP_STARTUP_TIMEOUT_MS` and `KIMI_MCP_TOOL_TIMEOUT_MS` environment variables respectively, which take higher priority than `config.toml`. See [MCP](../customization/mcp.md) for the full MCP server configuration.
+
+## `identity`
+
+Customizes how the agent identifies itself. Leave it unset and nothing changes.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | — | Display name the agent calls itself in the system prompt (fills the `${product_name}` slot, including in your own `SYSTEM.md` and agent files) |
+| `slug` | `string` | derived from `name` | Machine identifier in protocol fields (`User-Agent` product token, MCP client name); derived from `name` when omitted: lowercased, non-alphanumeric runs folded to `-` |
+
+```toml
+[identity]
+name = "Acme Dev Agent"
+slug = "acme-dev"        # optional
+```
+
+Both fields can be set through the `KIMI_CODE_IDENTITY_NAME` and `KIMI_CODE_IDENTITY_SLUG` environment variables, which take higher priority than `config.toml` and are never written back to it, making them convenient for containers and CI, where writing a config file is awkward.
+
+A name that contains no ASCII letters or digits (for example a purely Chinese name) leaves nothing to derive a slug from and falls back to `agent`; write `slug` explicitly if you need a specific protocol token.
+
+The identity is resolved once at startup and holds for the life of the process: it is announced to MCP servers and providers when connections are made, so it cannot change midway. Edits to this section take effect on the next start, for new sessions: a resumed session keeps the system prompt it was recorded with, since its past turns already speak under that identity. Likewise, an MCP OAuth authorization keeps the client registration it was granted under; reset that server's authentication to register under the new identity.
+
+This section is read by the `agent-core-v2` engine, which powers every Kimi Code surface.
+
+## `tools`
+
+`tools` is the global tool switch: it applies to every agent in all sessions and intersects with each agent's own `tools` / `disallowedTools` policy.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | `array<string>` | — | Global allowlist: when non-empty, only the listed tools are available; omitting the field or setting an empty array imposes no constraint |
+| `disabled` | `array<string>` | — | Global denylist, applied after `enabled` |
+
+Name matching follows the same rules as the same-named fields in an agent file: built-in tools match by exact name (such as `Read`), and MCP tools match with globs (such as `mcp__github__*`). Three entry shapes never match anything and are reported with a warning: a wildcard outside an `mcp__` pattern (`enabled = ["*"]` disables every tool, `disabled = ["*"]` disables none), an `mcp__` literal missing the tool segment (`mcp__github`; use `mcp__github__*` for a whole server), and a name no registered or built-in tool has (matching is case-sensitive).
+
+```toml
+[tools]
+disabled = ["EnterPlanMode", "ExitPlanMode", "mcp__github__*"]
+```
+
+::: warning Note
+Like the `tools` / `disallowedTools` fields of an agent file, this section shapes the tools shown to the model and is enforced again before execution. [Permission rules](#permission) remain a separate control for operations that require approval.
+:::
+
+## `read`
+
+`read` controls the character limits for the [`Read` tool](../reference/tools.md). The limit includes file content, line numbers, and the status block; it does not impose a separate line-count or UTF-8 byte limit.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `default_max_chars` | `integer` | `100000` | Character budget when the tool call omits `max_chars` |
+| `max_chars` | `integer` | `500000` | Maximum character budget a tool call may request |
+
+```toml
+[read]
+default_max_chars = 100000
+max_chars = 500000
+```
+
+Both values must be positive integers. A call's `max_chars` overrides the default, but is capped at the configured maximum; the result reports the effective budget. If the configured default exceeds the maximum, the maximum also limits default reads. Raise `default_max_chars` when you want larger documents to be returned in one call without the agent requesting a larger budget.
+
+## `image`
+
+`image` controls how images are compressed before being sent to the model, across every ingestion point (pasted images, `ReadMediaFile` reads, images in MCP tool results, and so on).
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `max_edge_px` | `integer` | `2000` | Longest-edge ceiling in pixels; larger images scale down proportionally. Raising it preserves more detail at the cost of larger request bodies |
+| `read_byte_budget` | `integer` | `262144` (256 KB) | Per-image byte budget for images the model reads for itself (`ReadMediaFile` default reads); `region` and `full_resolution` read-backs are exempt |
+
+`max_edge_px` can be overridden by the `KIMI_IMAGE_MAX_EDGE_PX` environment variable and `read_byte_budget` by `KIMI_IMAGE_READ_BYTE_BUDGET`; both take higher priority than `config.toml`.
+
+## `database`
+
+`database` controls the embedded storage engines behind session indexing and global search. Both keys default to `true` and act as kill switches that fall back to the legacy behavior when set to `false`.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `base` | `boolean` | `true` | Use the minidb-backed read model for session indexing; `false` falls back to reading session metadata directly |
+| `search` | `boolean` | `true` | Run the global search index in a dedicated worker thread; `false` runs it in the server process |
+
+`base` can be overridden by the `KIMI_CODE_PERSISTENCE_MINIDB_READMODEL` environment variable and `search` by `KIMI_CODE_SEARCH_WORKER`; both take higher priority than `config.toml`.
+
+<!--
+## `experimental`
+
+`experimental` stores persistent overrides for experimental-feature flags. Currently, `micro_compaction` is the only user-facing entry and defaults to `false`; set it to `true` to enable automatic trimming of older large tool results.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `micro_compaction` | `boolean` | `false` | Trim older large tool results from context while preserving recent conversation |
+-->
+
+## `services`
+
+`services` configures two built-in services: web search (`moonshot_search`) and web fetch (`moonshot_fetch`). Only these two fixed keys are recognized; other keys are ignored. Both entries share the same fields:
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `base_url` | `string` | No | Service API URL |
+| `api_key` | `string` | No | API key |
+| `oauth` | `table` | No | OAuth credential reference, same structure as `providers.*.oauth` |
+| `custom_headers` | `table<string, string>` | No | Custom HTTP headers attached to each request |
+
+`base_url` and `api_key` can also come from environment variables, which take priority over the config file: `KIMI_WEB_SEARCH_BASE_URL` / `KIMI_WEB_SEARCH_API_KEY` for `moonshot_search`, and `KIMI_WEB_FETCH_BASE_URL` / `KIMI_WEB_FETCH_API_KEY` for `moonshot_fetch`. An env base URL defines a separate service endpoint, so the persisted API key, OAuth reference, and custom headers are not forwarded to it; set the matching env API key when that endpoint requires authentication. An env API key without an env base URL keeps the configured endpoint and custom headers but replaces both configured credential forms. Setting the base URL and API key through env without any config section also enables the service.
+
+```toml
+[services.moonshot_search]
+base_url = "https://api.moonshot.cn/v1/search"
+api_key = "sk-xxx"
+
+[services.moonshot_fetch]
+base_url = "https://api.moonshot.cn/v1/fetch"
+api_key = "sk-xxx"
+```
+
+## `permission`
+
+`permission` sets permission rules that are automatically loaded when a session starts, controlling whether the Agent needs user confirmation before calling a tool. Rules are written as a `[[permission.rules]]` array of tables, matched in order; the first matching rule takes effect.
+
+You can also set `dangerous_command_guard = false` under `[permission]` to turn off the built-in dangerous-command policy entirely (no dangerous-command confirmation in Always Ask and Ask When Needed mode; the policy is never active in Never Ask mode); the default is `true`. An environment variable `KIMI_CODE_DANGEROUS_COMMAND_GUARD=false` overrides the file setting and restores the behavior before the policy was introduced. Use this switch only for environments that already gate commands outside the agent.
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `decision` | `string` | Yes | Action on match: `allow` (permit immediately), `deny` (reject immediately), `ask` (prompt each time) |
+| `scope` | `string` | No | Rule scope: `turn-override`, `session-runtime`, `project`, `user`; defaults to `user` |
+| `pattern` | `string` | Yes | Match pattern in the form `ToolName` or `ToolName(arg-pattern)`, e.g. `Read` or `Bash(rm -rf*)` |
+| `reason` | `string` | No | Rule description for debugging and auditing |
+
+Built-in tool names are listed in [Built-in tools](../reference/tools.md). Most built-in tools that accept rule arguments define their own matching subject, such as `Bash(command-pattern)` or `Read(path-pattern)`. `AgentSwarm`, MCP tools, and custom tools can only be matched by tool name; argument patterns are not supported for them.
+
+```toml
+[[permission.rules]]
+decision = "allow"
+pattern = "Read"
+
+[[permission.rules]]
+decision = "allow"
+pattern = "Grep"
+
+[[permission.rules]]
+decision = "deny"
+pattern = "Bash(rm -rf*)"
+
+[[permission.rules]]
+decision = "ask"
+pattern = "Bash"
+```
+
+::: tip
+MCP server declarations are configured in `~/.kimi-code/mcp.json` or the project-local `.kimi-code/mcp.json`, not in `config.toml`. The interactive configuration entry point is `/mcp-config`; see [Model Context Protocol](../customization/mcp.md).
+:::
+
+## `tui.toml`
+
+Alongside `config.toml`, the CLI keeps terminal-UI and client preferences in a companion `tui.toml` in the same directory (`~/.kimi-code/tui.toml`, or `$KIMI_CODE_HOME/tui.toml` when overridden). It is created with defaults on first run, and the interactive commands `/config`, `/theme`, and `/editor` write to it for you, so you rarely need to edit it by hand. If the file is malformed, the CLI falls back to defaults and shows a notice instead of failing to start.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `theme` | `string` | `auto` | Color theme: `auto`, `dark`, `light`, or the name of a [custom theme](../customization/themes.md) |
+| `render_latex` | `boolean` | `true` | Render LaTeX math expressions in Markdown messages as Unicode text; `false` keeps the raw source |
+| `disable_paste_burst` | `boolean` | `false` | Disable the non-bracketed paste-burst fallback that keeps rapid multi-line pastes from submitting line by line |
+| `cache_expiry_hint` | `boolean` | `true` | On resume or when submitting after a long idle stretch, warn that the context cache may have expired and offer to compact or start a new session (v2 engine only) |
+| `disable_feedback_survey` | `boolean` | `false` | Disable the occasional session rating prompt above the input box |
+| `[editor].command` | `string` | `""` | External editor command for composing long input; empty falls back to `$VISUAL` / `$EDITOR` |
+| `[notifications].enabled` | `boolean` | `true` | Whether desktop notifications are sent |
+| `[notifications].notification_condition` | `string` | `unfocused` | When to notify: `unfocused` (only when the terminal is not focused) or `always` |
+| `[upgrade].auto_install` | `boolean` | `true` | Whether new versions are installed automatically |
+| `[status_line].items` | `string[]` | `[]` | Built-in slots on the first footer line and their order: `mode`, `goal`, `model`, `tasks`, `cwd`, `git`, `tips`; unknown ids are skipped with a warning |
+| `[status_line].command` | `string` | `""` | Custom status line command: its first stdout line replaces the footer, and a JSON snapshot is passed on stdin; capped at 300ms, throttled to once per second, failures fall back to the built-in layout |
+
+<details>
+<summary>Fields in the stdin JSON snapshot</summary>
+
+Model, cwd, git branch, permission mode, plan mode, context usage, session id, version.
+
+</details>
+
+```toml
+# ~/.kimi-code/tui.toml
+theme = "auto" # "auto" | "dark" | "light" | custom theme name
+render_latex = true # false keeps LaTeX math in messages as raw source
+disable_paste_burst = false # true disables non-bracketed paste-burst fallback
+cache_expiry_hint = true # false disables the "cache expired" dialog on resume / idle submit
+disable_feedback_survey = false # true hides the occasional session rating prompt
+
+[editor]
+command = "" # empty uses $VISUAL / $EDITOR
+
+[notifications]
+enabled = true
+notification_condition = "unfocused" # "unfocused" | "always"
+
+[upgrade]
+auto_install = true
+
+# [status_line]
+# items = ["mode", "goal", "model", "tasks", "cwd", "git", "tips"]
+# command = "~/.kimi-code/statusline.sh"
+```
+
+Changes apply on the next start, or immediately with `/reload-tui` (which reloads only `tui.toml`); `/reload` reloads both `config.toml` and `tui.toml`.
+
+## Project-local configuration
+
+In addition to the user-level files under `~/.kimi-code`, Kimi Code reads a project-local configuration file at `<project-root>/.kimi-code/local.toml`. It holds settings that are specific to one project checkout and typically should not be shared with teammates.
+
+The file is created automatically when you add an extra workspace directory with [`/add-dir`](../reference/slash-commands.md) and choose to remember it for the project. You rarely need to edit it by hand.
+
+### `[workspace]`
+
+The `[workspace]` table groups project-level workspace settings:
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `additional_dir` | `array<string>` | No | Additional workspace directories (absolute paths); written automatically when you confirm "remember this directory" in `/add-dir`, and available in every session of this project |
+
+```toml
+[workspace]
+additional_dir = ["/absolute/path/to/shared"]
+```
+
+Because directories are stored as absolute paths, which are specific to your machine, we recommend adding `.kimi-code/local.toml` to your project's `.gitignore` so it is not committed.
+
+## Next steps
+
+- [Providers and models](./providers.md) — connection examples for each provider type (Kimi, Claude, OpenAI, Gemini)
+- [Config overrides](./overrides.md) — priority rules for CLI options, config file, and environment variables
+- [Environment variables](./env-vars.md) — complete list of runtime variables like `KIMI_CODE_HOME`

docs/en/configuration/data-locations.md

@@ -0,0 +1,126 @@
+# Data locations
+
+Kimi Code CLI stores the config file, session history, login credentials, diagnostic logs, and other runtime data under `~/.kimi-code/`. This page helps you understand where each type of data lives, what it is for, and how to clean up or relocate it when needed.
+
+## Data root directory
+
+The default data root is `~/.kimi-code/`. The actual path varies by platform:
+
+- macOS: `/Users/<name>/.kimi-code`
+- Linux: `/home/<name>/.kimi-code`
+- Windows: `C:\Users\<name>\.kimi-code`
+
+If you need to move the data directory elsewhere (for example, to isolate configs for different projects with independent environments), set `KIMI_CODE_HOME`:
+
+```sh
+export KIMI_CODE_HOME="$HOME/.config/kimi-code"
+```
+
+Once set, **all** Kimi Code data lands under the new path: config, sessions, logs, OAuth credentials, Kimi-specific user Skills, global `AGENTS.md`, and more. For the full reference on `KIMI_CODE_HOME`, see [Environment variables](./env-vars.md).
+
+::: tip Note
+
+**Generic `.agents` resources** stay under the real OS home so they can be shared across tools. For example, user-level generic Skills remain at `~/.agents/skills/`, while Kimi-specific user Skills move with `KIMI_CODE_HOME` as `$KIMI_CODE_HOME/skills/`.
+:::
+
+## Directory layout
+
+```
+$KIMI_CODE_HOME  (default: ~/.kimi-code)
+├── config.toml             # User configuration
+├── tui.toml                # Terminal UI preferences (including auto-update toggle)
+├── AGENTS.md               # Global Kimi-specific agent instructions (optional)
+├── mcp.json                # User-level MCP server declarations (optional)
+├── skills/                 # Kimi-specific user-level Skills (optional)
+├── plugins/
+│   ├── installed.json      # Installed plugin records and enabled state
+│   └── managed/            # Plugin copies installed from zip/local paths
+├── session_index.jsonl     # Session index
+├── credentials/            # OAuth credentials (dir 0700, files 0600)
+│   ├── <name>.json
+│   └── mcp/
+│       └── <key>-<suffix>.json
+├── sessions/               # Session data (see below)
+│   └── <workDirKey>/<sessionId>/
+├── bin/
+│   ├── rg                  # managed ripgrep binary for Grep (rg.exe on Windows)
+│   └── fd                  # managed fd binary for file references (fd.exe on Windows)
+├── logs/
+│   └── kimi-code.log       # Global diagnostic log
+├── updates/
+│   ├── latest.json
+│   ├── install.json
+│   ├── install.lock
+│   └── rollout.log
+└── user-history/
+    └── <md5(workDir)>.jsonl
+```
+
+## File descriptions
+
+Each top-level file under the data root serves a specific purpose; most are managed automatically by the CLI:
+
+- **`config.toml`**: the main runtime configuration file, storing user-level settings such as providers, models, and loop control. See [Configuration files](./config-files.md).
+- **`tui.toml`**: terminal UI client preferences, including `[upgrade].auto_install` (auto-update, on by default). You can disable it in `/settings` or by manually setting `auto_install = false`.
+- **`AGENTS.md`**: global Kimi-specific agent instructions. This file moves with `KIMI_CODE_HOME`; generic cross-tool instructions can still live under `~/.agents/AGENTS.md`.
+- **`mcp.json`**: user-level MCP server declarations, merged with the project-local `.kimi-code/mcp.json` on startup. See [MCP](../customization/mcp.md).
+- **`skills/`**: Kimi-specific user-level Skills. This directory moves with `KIMI_CODE_HOME`; generic cross-tool Skills can still live under `~/.agents/skills/`. See [Agent Skills](../customization/skills.md).
+- **`plugins/installed.json`**: records installed plugins, each plugin's enabled state, and MCP server capability state changes made via `/plugins` or `/plugins mcp disable|enable`. Files installed from local paths or zip URLs are copied to `plugins/managed/<id>/`. See [Plugins](../customization/plugins.md).
+- **`credentials/`**: OAuth credential directory, with permissions `0o700` (directory) / `0o600` (files), readable and writable only by the current user. Managed provider credentials are stored as `credentials/<name>.json`; MCP server credentials are stored under `credentials/mcp/`. Credentials are written using an atomic flow (tmp → fsync → rename) to prevent corruption.
+
+## Session data
+
+Each session's data is stored under `sessions/<workDirKey>/<sessionId>/`, and a top-level `session_index.jsonl` index is maintained (one record per line, each containing `sessionId`, `sessionDir`, and `workDir`). `workDirKey` is a bucket name derived from the working directory path, in the format `wd_<slug>_<first-12-chars-of-sha256>`.
+
+Inside each session directory:
+
+- **`state.json`**: session metadata including title, `lastPrompt`, creation/update timestamps, and `forkedFrom`.
+- **`upcoming-goals.json`**: the TUI-only queue created by `/goal next <objective>`. It is not part of the agent conversation until a queued goal is promoted after the current goal completes.
+- **`agents/main/wire.jsonl`**: the main Agent's complete communication record, used for session resumption and replay.
+- **`agents/main/plans/`**: plan files written in Plan mode, named by plan id (`<id>.md`).
+- **`agents/agent-0/` etc.**: sub-Agent instance directories, each containing their own `wire.jsonl`.
+- **`logs/kimi-code.log`**: diagnostic log for this session; only present when a diagnostic event occurs.
+- **`tasks/`**: background task persistence. `tasks/<task_id>.json` stores status/pid/exit code; `tasks/<task_id>/output.log` stores output.
+- **`cron/`**: scheduled task persistence; reloaded into the scheduler when the session is resumed with `kimi --session`. See [Scheduled tasks](../reference/tools.md#scheduled-tasks).
+
+## Built-in tool cache
+
+The first time the `Grep` tool needs ripgrep, the CLI can automatically download `rg` and cache it at `bin/rg` (`bin/rg.exe` on Windows). File-reference completion in the terminal UI uses `fd`; the CLI downloads and caches it at `bin/fd` (`bin/fd.exe` on Windows) in the background when needed. Subsequent runs reuse the cached binaries. `rg` prefers the system `PATH` before the cache, while `fd` checks the managed cache before falling back to system `fd` / `fdfind`. Deleting the `bin/` directory triggers a fresh download on the next use.
+
+## Logs and update state
+
+- **`logs/kimi-code.log`** (global): records startup, login, export, and other cross-session events.
+- **`<sessionDir>/logs/kimi-code.log`** (session-level): records diagnostic events within a single session.
+
+When reporting a bug, prefer exporting the relevant session with `kimi export` (see [kimi command](../reference/kimi-command.md)); the session log is included in the export by default. Add `--no-include-global-log` if you do not want to share the global log.
+
+The files under `updates/` (`latest.json`, `install.json`, `install.lock`, `rollout.log`) are maintained automatically by the auto-update mechanism and normally do not need manual editing. `rollout.log` records which staged-rollout case each update check hit, which helps explain when a device will receive a new release.
+
+## Input history
+
+Terminal input history is saved separately per working directory, at `user-history/<md5(workDir)>.jsonl`. It is used to browse previously typed prompts in the terminal UI using the arrow keys.
+
+## Clearing data
+
+Deleting the data root directory (`~/.kimi-code/` or the path set by `KIMI_CODE_HOME`) removes all runtime data. To clear only part of the data:
+
+| Goal | Action |
+| --- | --- |
+| Reset configuration | Delete `~/.kimi-code/config.toml` |
+| Reset terminal UI preferences | Delete `~/.kimi-code/tui.toml` |
+| Clear all sessions | Delete `~/.kimi-code/sessions/` and `session_index.jsonl` |
+| Clear diagnostic logs | Delete `~/.kimi-code/logs/` |
+| Clear input history | Delete `~/.kimi-code/user-history/` |
+| Reset update state | Delete `~/.kimi-code/updates/latest.json` |
+| Force re-download of managed `rg` and `fd` | Delete `~/.kimi-code/bin/` |
+| Clear provider OAuth login state | Run `/logout`, or delete the corresponding `credentials/<name>.json` |
+| Clear MCP server OAuth login state | Delete `credentials/mcp/` (`/logout` does not clear MCP credentials) |
+| Remove user-level MCP declarations | Delete `$KIMI_CODE_HOME/mcp.json` (default `~/.kimi-code/mcp.json`) |
+| Clear global Kimi-specific agent instructions | Delete `$KIMI_CODE_HOME/AGENTS.md` (default `~/.kimi-code/AGENTS.md`) |
+| Clear plugin install records | Delete `$KIMI_CODE_HOME/plugins/` (local plugin source directories are not affected) |
+| Clear Kimi-specific user-level Skills | Delete `$KIMI_CODE_HOME/skills/` (default `~/.kimi-code/skills/`) |
+
+## Next steps
+
+- [Configuration files](./config-files.md) — full reference for `config.toml` fields
+- [Environment variables](./env-vars.md) — detailed usage of `KIMI_CODE_HOME` and related path variables

docs/en/configuration/env-vars.md

@@ -0,0 +1,236 @@
+# Environment variables
+
+Kimi Code CLI uses environment variables to control a small number of runtime behaviors: relocating the data directory, turning off telemetry, and temporarily switching models without touching the config file.
+
+::: warning Important: API keys are not configured here
+Credential variables such as `KIMI_API_KEY`, `ANTHROPIC_API_KEY`, and `OPENAI_API_KEY` are **not** read automatically from shell environment variables. Running `export KIMI_API_KEY=xxx` in the terminal does not give any provider its key. They must be written in `config.toml` under `[providers.<name>]` or the `[providers.<name>.env]` sub-table.
+
+The only exception is the `KIMI_MODEL_*` family, an explicit channel that *does* read credentials from the shell. See [Define a model from environment variables](#define-a-model-from-environment-variables-kimi_model_).
+
+For background, see [Config overrides: provider credentials](./overrides.md#provider-credentials).
+:::
+
+## Core paths
+
+### `KIMI_CODE_HOME`
+
+Overrides the data root directory; the default is `~/.kimi-code`. Once set, the config file, sessions, logs, OAuth credentials, and all other data land under the new path:
+
+```sh
+export KIMI_CODE_HOME="/path/to/custom/kimi-code"
+```
+
+> Make sure the directory is writable. Multiple `kimi` instances sharing the same `KIMI_CODE_HOME` will share config and credential files.
+
+For the complete data directory structure, see [Data locations](./data-locations.md).
+
+### `KIMI_DISABLE_TELEMETRY`
+
+Set to `1` to turn off anonymous telemetry reporting (also accepts `true`, `yes`, `y`, case-insensitive):
+
+```sh
+export KIMI_DISABLE_TELEMETRY=1
+```
+
+### `KIMI_MODEL_*` family
+
+Switch models temporarily without modifying `config.toml`: when `KIMI_MODEL_NAME` is set, the CLI synthesizes a temporary provider in memory, and the change does not persist after restart. See [Define a model from environment variables](#define-a-model-from-environment-variables-kimi_model_).
+
+### `KIMI_CODE_CUSTOM_HEADERS`
+
+::: info Added
+Added in 0.20.2.
+:::
+
+Attaches custom HTTP headers to every outbound model request: both LLM chat requests (across all provider protocols) and `/models` listing requests carry them. Useful when a gateway routes by header, for example to pin a specific cluster:
+
+```sh
+export KIMI_CODE_CUSTOM_HEADERS=$'X-Gateway-Cluster: my-cluster\nX-Custom-Tag: debug'
+```
+
+The format mirrors `ANTHROPIC_CUSTOM_HEADERS`: newline-separated `Name: Value` lines. Names and values are trimmed, and lines without a colon are ignored.
+
+> Precedence: the Kimi identity headers (`User-Agent`, `X-Msh-*`) and a provider's `custom_headers` in `config.toml` (see [Config files](./config-files.md#providers)) override same-named entries here. Authentication is protocol-dependent: on the `kimi`, `openai`, and `openai_responses` protocols an exact `Authorization` entry replaces the generated bearer token, while `/models` listing requests keep their own authentication. A case variant such as `authorization` is never treated as the same name. It merges with the real header, which can break requests. Do not use this variable for authentication or other reserved headers. Use `custom_headers` when headers need to differ per provider.
+
+## Provider credential key names (written in config.toml)
+
+The key names below are not read directly from the shell. They are key names written inside the `[providers.<name>.env]` sub-table of `config.toml`, serving as fallback values for `api_key` / `base_url`. The CLI reads only from the config file, not from `process.env`.
+
+This design lets you keep familiar key name conventions while centralizing secret management in the config file:
+
+```toml
+[providers.kimi.env]
+KIMI_API_KEY = "sk-xxx"
+KIMI_BASE_URL = "https://api.moonshot.ai/v1"
+```
+
+Key names per provider:
+
+| Key | Applicable provider | Default |
+| --- | --- | --- |
+| `KIMI_API_KEY` | Kimi / Moonshot | None |
+| `KIMI_BASE_URL` | Kimi / Moonshot | `https://api.moonshot.ai/v1` |
+| `ANTHROPIC_API_KEY` | Anthropic | None |
+| `ANTHROPIC_BASE_URL` | Anthropic | Follows Anthropic SDK default |
+| `OPENAI_API_KEY` | OpenAI (`openai` and `openai_responses`) | None |
+| `OPENAI_BASE_URL` | OpenAI (`openai` and `openai_responses`) | `https://api.openai.com/v1` |
+| `GOOGLE_API_KEY` | Google GenAI, Vertex AI | None |
+| `VERTEXAI_API_KEY` | Vertex AI | None |
+| `GOOGLE_CLOUD_PROJECT` | Vertex AI | None |
+| `GOOGLE_CLOUD_LOCATION` | Vertex AI | None |
+
+::: warning
+`GOOGLE_APPLICATION_CREDENTIALS` (path to a service account JSON file) is the only exception that goes through the system environment variable mechanism. It is read by the Google SDK directly via the standard ADC flow; the CLI does not participate. All other key names must be placed in the `[providers.<name>.env]` sub-table to take effect.
+:::
+
+For the full provider type and field reference, see [Providers and models](./providers.md).
+
+## OAuth and managed services
+
+This group of variables redirects OAuth authentication and managed service endpoints to a self-hosted or test environment. They are not needed for everyday use.
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `KIMI_CODE_OAUTH_HOST` | OAuth auth host; highest priority | Falls back to `KIMI_OAUTH_HOST` when unset |
+| `KIMI_OAUTH_HOST` | OAuth auth host; fallback for `KIMI_CODE_OAUTH_HOST` | Falls back to `https://auth.kimi.com` when unset |
+| `KIMI_CODE_BASE_URL` | Managed API base URL used after OAuth login | `https://api.kimi.com/coding/v1` |
+
+::: warning
+`KIMI_CODE_BASE_URL` (OAuth-managed service, targeting `kimi.com`) and `KIMI_BASE_URL` (direct API key connection, targeting `moonshot.ai`) are two distinct variables. Use each one in its appropriate context.
+:::
+
+## Define a model from environment variables (`KIMI_MODEL_*`)
+
+Want to switch models for testing without touching `config.toml`? When `KIMI_MODEL_NAME` is set, the CLI synthesizes a temporary provider and model alias from the `KIMI_MODEL_*` variables in memory; nothing is written back to the config file. These variables take priority over `default_model` in `config.toml`, but the `-m <alias>` option at startup still has the highest priority.
+
+```sh
+export KIMI_MODEL_NAME="kimi-for-coding"
+export KIMI_MODEL_API_KEY="YOUR_API_KEY"
+export KIMI_MODEL_BASE_URL="https://api.example.com/v1"
+export KIMI_MODEL_MAX_CONTEXT_SIZE="262144"
+export KIMI_MODEL_CAPABILITIES="image_in,thinking"
+kimi
+```
+
+Complete variable list:
+
+| Variable | Required | Purpose | Default |
+| --- | --- | --- | --- |
+| `KIMI_MODEL_NAME` | Yes (also the enable switch) | Model id sent to the API | — |
+| `KIMI_MODEL_API_KEY` | Yes | API key | — |
+| `KIMI_MODEL_PROVIDER_TYPE` | No | Provider type: `kimi`, `anthropic`, `openai` | `kimi` |
+| `KIMI_MODEL_BASE_URL` | No | API base URL | Each type has its own default |
+| `KIMI_MODEL_MAX_CONTEXT_SIZE` | No | Maximum context length (tokens) | `262144` (256 K) |
+| `KIMI_MODEL_CAPABILITIES` | No | Comma-separated capability tags, unioned with auto-detected capabilities | `image_in,thinking` |
+| `KIMI_MODEL_DISPLAY_NAME` | No | Name shown in `/model` | Falls back to `KIMI_MODEL_NAME` |
+| `KIMI_MODEL_MAX_OUTPUT_SIZE` | No | Per-request output cap (`anthropic` only); when set, overrides the built-in Claude ceiling | Model default |
+| `KIMI_MODEL_REASONING_KEY` | No | Reasoning field name override (`openai` only) | Auto-detected |
+| `KIMI_MODEL_THINKING_EFFORT` | No | Thinking effort level: `low`/`medium`/`high`/`xhigh`/`max` | — |
+| `KIMI_MODEL_ADAPTIVE_THINKING` | No | Force adaptive thinking on or off (`anthropic` only) | Inferred from model name |
+
+If `KIMI_MODEL_NAME` is set but a required variable is missing, startup fails immediately with a clear error message.
+
+## Runtime switches
+
+Switches that control the behavior of subsystems such as telemetry, background tasks, and the plugin marketplace:
+
+| Variable | Purpose | Valid values |
+| --- | --- | --- |
+| `KIMI_DISABLE_TELEMETRY` | Disable anonymous telemetry reporting | `1`, `true`, `yes`, `y` (case-insensitive) |
+| `KIMI_CODE_PASSWORD` | Parallel auth credential for `kimi web`, recommended when binding beyond loopback (see [Security notes](../guides/web.md#security-notes)) | Any non-empty string; when unset, only the token is valid |
+| `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` | Keep background tasks when the session closes; higher priority than `config.toml` (default: stop them on exit) | Truthy: `1`/`true`/`yes`/`on`; falsy: `0`/`false`/`no`/`off` |
+| `KIMI_CODE_BACKGROUND_MAX_RUNNING_TASKS` | Cap on concurrently running background tasks; higher priority than `[background] max_running_tasks` (unset = no cap) | Positive integer; invalid values are ignored |
+| `KIMI_CODE_BACKGROUND_BASH_TASK_TIMEOUT_S` | Default timeout (seconds) for background `Bash` tasks, also used to re-arm foreground commands moved to the background; higher priority than `[task] bash_task_timeout_s` (`0` = no timeout) | Non-negative integer; invalid values are ignored |
+| `KIMI_CODE_BACKGROUND_PRINT_BACKGROUND_MODE` | What `kimi -p` does while background tasks are still pending after the main turn; higher priority than `[task] print_background_mode` | `exit`, `drain`, or `steer`; invalid values are ignored |
+| `KIMI_CODE_BACKGROUND_PRINT_WAIT_CEILING_S` | Wall-clock ceiling (seconds) for the print-mode drain/steer wait; higher priority than `[task] print_wait_ceiling_s` | Positive integer; invalid values are ignored |
+| `KIMI_CODE_BACKGROUND_PRINT_MAX_TURNS` | Max number of new turns triggered by background-task completions in print mode; higher priority than `[task] print_max_turns` | Positive integer; invalid values are ignored |
+| `KIMI_IMAGE_MAX_EDGE_PX` | Longest-edge ceiling (px) for image compression; higher priority than `[image] max_edge_px` (default `2000`) | Positive integer; invalid values are ignored |
+| `KIMI_IMAGE_READ_BYTE_BUDGET` | Per-image byte budget for model-initiated image reads; higher priority than `[image] read_byte_budget` (default `262144`) | Positive integer; invalid values are ignored |
+| `KIMI_CODE_PLUGIN_MARKETPLACE_URL` | Override the marketplace JSON loaded by `/plugins`; default `https://code.kimi.com/kimi-code/plugins/marketplace.json` | Also accepts `http://`, `file://` URLs, and local paths |
+| `KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCY` | Cap on AgentSwarm subagents running concurrently during the initial ramp; unset = no cap | Positive integer; invalid values fail fast |
+| `KIMI_CODE_SUBAGENT_SCOPE_CACHE_SIZE` | How many completed subagent scopes stay resident for fast resume; older ones are evicted and rebuilt from persisted state on demand (default `32`; `0` or negative = never evict) | Integer; invalid values fail fast |
+| `KIMI_CODE_SUBAGENT_SCOPE_EVICT_TIMEOUT_MS` | Max wall-clock time (ms) a single subagent scope eviction may take before the eviction queue skips it and moves on (default `15000`) | Positive integer; invalid values fail fast |
+| `KIMI_SUBAGENT_TIMEOUT_MS` | Max wall-clock time (ms) a single `Agent` subagent may run; higher priority than `[subagent] timeout_ms` | Positive integer; invalid values fall back to the config or default |
+| `KIMI_CODE_SWARM_TIMEOUT_MS` | Max wall-clock time (ms) an `AgentSwarm` subagent may run; higher priority than `[swarm] timeout_ms` | Positive integer; invalid values fall back to the config or default |
+| `KIMI_CODE_IDENTITY_NAME` | Name the agent calls itself in the system prompt; higher priority than `[identity] name`, never written back | Any non-empty string; blank values read as unset |
+| `KIMI_CODE_IDENTITY_SLUG` | `User-Agent` product token and MCP client name; higher priority than `[identity] slug`; derived from the name when unset | Any non-empty string; normalized to lowercase with non-alphanumeric runs folded to `-` |
+| `KIMI_CODE_BUILTIN_PRODUCT_SKILLS` | Offer the built-in skills documenting Kimi Code itself to the model; higher priority than `builtin_product_skills` | Truthy: `1`/`true`/`yes`/`on`; falsy: `0`/`false`/`no`/`off` |
+| `KIMI_CODE_TUI_FULL_SCREEN` | Experimental fullscreen UI: scrollable transcript, mouse selection, clickable links, Ctrl-Shift-F search | `1` enables it; anything else keeps the regular inline UI |
+| `KIMI_CODE_EXPERIMENTAL_SUBAGENT_FORK` | Experimental `fork` parameter on `Agent`/`AgentSwarm`: start the subagent from a snapshot of the caller's history instead of an empty context; `KIMI_CODE_EXPERIMENTAL_FLAG=1` also enables it | Truthy: `1`/`true`/`yes`/`on`; falsy: `0`/`false`/`no`/`off` |
+| `KIMI_CODE_EXPERIMENTAL_TOOL_SELECT` | Experimental on-demand tool loading: tools of MCP servers marked `deferred: true` stay out of the top-level tool list and are loaded via `select_tools`; also requires the model to declare the `dynamically_loaded_tools` capability — see [MCP](../customization/mcp.md#loading-tools-on-demand) | Truthy: `1`/`true`/`yes`/`on`; falsy: `0`/`false`/`no`/`off` |
+| `KIMI_CODE_SEARCH_WORKER` | Run the global search index in a dedicated worker thread; higher priority than `[database] search` (default `true`) | Truthy: `1`/`true`/`yes`/`on`; falsy: `0`/`false`/`no`/`off` |
+| `KIMI_CODE_PERSISTENCE_MINIDB_READMODEL` | Use the minidb-backed read model for session indexing; higher priority than `[database] base` (default `true`) | Truthy: `1`/`true`/`yes`/`on`; falsy: `0`/`false`/`no`/`off` |
+| `KIMI_MCP_STARTUP_TIMEOUT_MS` | Global default connection timeout (ms) for MCP servers; overrides the config file, but `mcp.json` `startupTimeoutMs` still wins | Integer from `1` to `2147483647`; invalid values are ignored |
+| `KIMI_MCP_TOOL_TIMEOUT_MS` | Global default single tool-call timeout (ms) for MCP servers; overrides the config file, but `mcp.json` `toolTimeoutMs` still wins | Integer from `1` to `2147483647`; invalid values are ignored |
+| `KIMI_LOOP_MAX_STEPS_PER_TURN` | Max Agent steps per turn; higher priority than `[loop_control] max_steps_per_turn` (`0` = unlimited) | Non-negative integer; invalid values are ignored |
+| `KIMI_LOOP_MAX_ATTEMPTS_PER_STEP` | Max total attempts for a failing step (including the first); higher priority than `[loop_control] max_attempts_per_step` | Non-negative integer; invalid values are ignored |
+| `KIMI_CODE_INFINITE_RETRY` | Retry failed LLM requests indefinitely; exponential backoff (32 s cap) honoring `Retry-After`; aborting still cancels immediately | Truthy: `1`/`true`/`yes`/`on`; falsy: `0`/`false`/`no`/`off` |
+| `KIMI_TOKEN_COUNTING_STRATEGY` | Context token count reported externally; higher priority than `[token_counting] strategy` | `measured+estimated`, `measured`, `estimated` (case-insensitive); invalid values are ignored |
+| `KIMI_WEB_SEARCH_BASE_URL` | Web search (`WebSearch`) service API URL; higher priority than the config file; credentials and custom headers not forwarded | Non-blank string; blank values are ignored |
+| `KIMI_WEB_SEARCH_API_KEY` | Web search (`WebSearch`) service API key; replaces both the configured key and the OAuth credential | Non-blank string; blank values are ignored |
+| `KIMI_WEB_FETCH_BASE_URL` | Web fetch (`FetchURL`) service API URL; higher priority than the config file; credentials not forwarded. Without an endpoint, signed-in users get the managed Kimi OAuth fetch service before direct local requests | Non-blank string; blank values are ignored |
+| `KIMI_WEB_FETCH_API_KEY` | Web fetch (`FetchURL`) service API key; replaces both the configured key and the OAuth credential | Non-blank string; blank values are ignored |
+| `KIMI_CODE_EXPERIMENTAL_FLAG` | Enable all registered experimental features for this process | `1`, `true`, `yes`, `on` |
+| `KIMI_SHELL_PATH` | Override the Git Bash path on Windows (used when auto-detection fails) | Absolute path |
+| `KIMI_MODEL_MAX_COMPLETION_TOKENS` | Hard cap on `max_completion_tokens` per LLM step; applies to the `kimi` provider only | Positive integer; `0` or negative disables clamping |
+| `KIMI_MODEL_TEMPERATURE` | Sampling temperature for every request; `kimi` provider only (global, independent of `KIMI_MODEL_NAME`) | Number, e.g. `0.3` |
+| `KIMI_MODEL_TOP_P` | Nucleus-sampling `top_p` for every request; `kimi` provider only (global) | Number, e.g. `0.95` |
+| `KIMI_MODEL_THINKING_EFFORT` | Force a thinking effort (`thinking.effort`), bypassing the model's declared `support_efforts`; `kimi` provider only | An effort value, e.g. `max` |
+| `KIMI_MODEL_THINKING_KEEP` | Preserved-thinking passthrough: `thinking.keep` on `kimi`, a `clear_thinking_20251015` edit on `anthropic`; overrides `[thinking] keep` | A value the API accepts, e.g. `all`; an off-value (`false`/`0`/`no`/`off`/`none`/`null`) disables it |
+| `KIMI_CODE_NO_AUTO_UPDATE` | Fully disable the update preflight: no check, background install, or prompt. Legacy alias `KIMI_CLI_NO_AUTO_UPDATE` also honored | Truthy: `1`/`true`/`yes`/`on` |
+| `KIMI_DISABLE_CRON` | Disable the scheduled-task tool (`CronCreate` rejects new schedules; existing tasks do not fire) | `1` to disable |
+
+The `KIMI_CODE_INFINITE_RETRY`, `KIMI_CODE_IDENTITY_*`, and `KIMI_CODE_BUILTIN_PRODUCT_SKILLS` variables are read by the `agent-core-v2` engine.
+
+## Diagnostic logs
+
+These variables control log level and file rotation, read once at process startup:
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `KIMI_LOG_LEVEL` | Log level: `off`, `error`, `warn`, `info`, `debug` | `info` |
+| `KIMI_LOG_GLOBAL_MAX_BYTES` | Maximum bytes per global log file | `6291456` (6 MB) |
+| `KIMI_LOG_GLOBAL_FILES` | Number of global log files to retain | `5` |
+| `KIMI_LOG_SESSION_MAX_BYTES` | Maximum bytes per session log file | `5242880` (5 MB) |
+| `KIMI_LOG_SESSION_FILES` | Number of session log files to retain | `3` |
+
+## System environment variables
+
+The CLI also reads several standard system variables to detect the runtime environment; it does not modify them:
+
+- `HOME`: used to resolve the default data path
+- `VISUAL`, `EDITOR`: external editor command (`VISUAL` takes precedence)
+- `PATH`: used to locate dependencies such as `rg`, `fd`, `fdfind`, and `git`; on Windows, Git Bash detection checks each `git.exe` found on `PATH`, including package-manager shims such as Scoop
+- `NO_COLOR`, `FORCE_COLOR`: control color output (following the [no-color.org](https://no-color.org) convention)
+- `CI`: when non-empty and not `"0"`, disables theme detection and falls back to the dark theme
+- `TERM_PROGRAM`, `TERM`, `TMUX`: detect terminal features and notification support
+- `DISPLAY`, `WAYLAND_DISPLAY`, `XDG_SESSION_TYPE`: detect Linux graphical sessions (for clipboard and image features)
+- `WSL_DISTRO_NAME`, `WSLENV`: detect WSL for the clipboard PowerShell bridge
+- `LOCALAPPDATA`: used on Windows as a fallback when probing for the Git Bash installation path
+
+## HTTP proxy
+
+Kimi Code honors the standard proxy environment variables for all outbound traffic: model API calls, MCP servers, web tools, telemetry, sign-in, and update checks:
+
+- `HTTP_PROXY` / `http_proxy`: proxy for `http://` requests
+- `HTTPS_PROXY` / `https_proxy`: proxy for `https://` requests
+- `ALL_PROXY` / `all_proxy`: fallback proxy used when the scheme-specific variable is unset; this is where a SOCKS proxy is usually set
+- `NO_PROXY` / `no_proxy`: comma-separated hosts that bypass the proxy
+
+### Proxy types and precedence
+
+Both HTTP(S) and SOCKS proxies are supported. A SOCKS proxy is recognized by its scheme: `socks5://`, `socks5h://`, `socks4://`, or `socks://` (an alias for `socks5://`). It is typically set via `ALL_PROXY` (the form used by tools like Clash and V2RayN). An HTTP(S) proxy takes precedence over `ALL_PROXY` for HTTP/HTTPS traffic.
+
+### Activation conditions and loopback addresses
+
+The proxy is applied only when one of these variables is set; otherwise connections are made directly. Loopback hosts (`localhost`, `127.0.0.1`, `::1`) always bypass the proxy, so a local server such as a localhost MCP server keeps working when a proxy is configured. Add your own internal hosts to `NO_PROXY` to exempt them too.
+
+### MCP child processes
+
+Stdio MCP servers that run as Node child processes honor `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` automatically when the child's Node version supports `NODE_USE_ENV_PROXY` (Node ≥ 22.21 or ≥ 24.5); SOCKS proxying applies to Kimi Code's own traffic only.
+
+## Next steps
+
+- [Config overrides](./overrides.md) — how environment variables, CLI options, and the config file interact by priority
+- [Data locations](./data-locations.md) — directory structure affected by `KIMI_CODE_HOME`
+- [Providers and models](./providers.md) — full connection examples per provider type

docs/en/configuration/overrides.md

@@ -0,0 +1,107 @@
+# Config overrides
+
+Kimi Code CLI has three places where runtime parameters can be influenced: the config file, command-line options, and environment variables. They are not a simple priority stack: the three serve different scenarios and have non-overlapping scopes:
+
+- **Config file** stores long-term preferences (model, keys, loop control, etc.); takes effect on every startup
+- **Command-line options** make one-off changes for the current startup; discarded after exit
+- **Environment variables** primarily handle data directory location, OAuth endpoint switching, and a small number of runtime switches. They are **not a general fallback mechanism for config fields**.
+
+This distinction matters: many users run `export KIMI_API_KEY=xxx` in the shell expecting the CLI to pick it up automatically, but it does not. See [Provider credentials](#provider-credentials) below for why.
+
+## Three roles of environment variables
+
+Environment variables fall into three categories by function and cannot be collapsed into a single linear priority order:
+
+1. **Locating the config file**: `KIMI_CODE_HOME` sets the data root directory, making the config file path `$KIMI_CODE_HOME/config.toml`. This step runs before all other resolution and is not a fallback for individual parameters.
+2. **Runtime switches**: A small set of variables like `KIMI_DISABLE_TELEMETRY` directly shut down the corresponding subsystem. Even if `config.toml` has `telemetry = true`, a truthy value for this variable disables telemetry. The semantics are "additionally disable", not "ordinary override".
+3. **Runtime endpoints and diagnostics**: Variables like `KIMI_CODE_OAUTH_HOST`, `KIMI_CODE_BASE_URL`, and `KIMI_LOG_LEVEL` are read when the OAuth or logging subsystems initialize. For the full list, see [Environment variables](./env-vars.md).
+
+## Priority for ordinary runtime parameters
+
+For ordinary runtime parameters such as model alias, Plan mode, permission mode, and Skills directories, priority from highest to lowest is:
+
+1. **Command-line options** (`-m`, `--plan`, `--yolo`, etc.): apply only to the current startup
+2. **User config file** (`~/.kimi-code/config.toml`): stores long-term preferences
+
+A small number of environment variables explicitly override specific config file fields. For example, `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` has higher priority than `[background].keep_alive_on_exit`. These exceptions are noted in [Environment variables](./env-vars.md) and in the relevant field descriptions in [Configuration files](./config-files.md).
+
+::: warning
+**Ordinary runtime parameters do not fall back to shell environment variables.** Provider `api_key` / `base_url` are read only from `config.toml` (including the `[providers.<name>.env]` sub-table) and do not fall back to `export`-ed shell variables. The only exception is the explicit `KIMI_MODEL_*` channel; see [Define a model from environment variables](./env-vars.md#define-a-model-from-environment-variables-kimi_model_).
+:::
+
+The CLI currently reads a single user-level config file and has no project-level config file mechanism. To isolate config between different projects, point `KIMI_CODE_HOME` at different data directories; see [Common scenarios](#common-scenarios) below.
+
+## Provider credentials
+
+Provider credentials (`api_key`, `base_url`) follow their own resolution rules, separate from the ordinary parameter priority chain.
+
+For a single provider, credentials are resolved in this order:
+
+1. `[providers.<name>].api_key`: key written directly in the config file; highest priority
+2. The matching key inside the `[providers.<name>.env]` sub-table (`KIMI_API_KEY`, `ANTHROPIC_API_KEY`, etc.): consulted only when `api_key` is empty
+3. If both are absent, startup fails with an error indicating the provider is missing credentials
+
+`base_url` is resolved the same way: first `[providers.<name>].base_url`, then the `*_BASE_URL` key in `[providers.<name>.env]`.
+
+> The `[providers.<name>.env]` sub-table is just a TOML section in the config file and does not write anything into the shell environment. It is only consulted when the corresponding direct field (`api_key` / `base_url`) is empty.
+
+For the full list of credential key names, see [Environment variables: provider credential key names](./env-vars.md#provider-credential-key-names-written-in-configtoml).
+
+## Command-line options
+
+Options passed at startup have the highest priority and apply only to the current session:
+
+| Option | Effect |
+| --- | --- |
+| `-S, --session [id]` | Resume a specific session; enters interactive selection when no id is given |
+| `-c, --continue` | Resume the last session for the current working directory |
+| `-y, --yolo` | Ask When Needed mode: routine edits and commands run automatically; the agent may still ask questions |
+| `--auto` | Never Ask mode: never interrupts you; the agent will not ask questions |
+| `--plan` | Start in Plan mode |
+| `-m, --model <model>` | Use a specific model alias for this session |
+| `-p, --prompt <prompt>` | Run in non-interactive mode: execute a single prompt and exit |
+| `--output-format <format>` | Output format for `-p` mode: `text` or `stream-json` |
+| `--skills-dir <dir>` | Replace auto-discovered Skills directories (repeatable; applies to this session only) |
+
+Mutual exclusion rules (startup fails if violated):
+
+- `--output-format` can only be used with `-p`
+- `--prompt` cannot be combined with `--yolo` or `--plan`
+- `--continue` and `--session` cannot be used together
+- In non-prompt mode, `--yolo` and `--plan` cannot be combined with `--continue` or `--session`
+
+::: tip
+`--skills-dir` is a one-shot replacement that only affects the current startup. To persistently add search directories, write `extra_skill_dirs` in `config.toml` (see [Agent Skills](../customization/skills.md)).
+:::
+
+## Common scenarios
+
+**Isolated test environment**: use a separate data directory to avoid polluting the main config and sessions:
+
+```sh
+KIMI_CODE_HOME="$PWD/.kimi-sandbox" kimi
+```
+
+**One-off test key**: since provider credentials are read only from the config file, write a test key into the `env` sub-table:
+
+```toml
+[providers.kimi.env]
+KIMI_API_KEY = "sk-test"
+```
+
+**Skip approval for batch tasks**:
+
+```sh
+kimi --yolo -p "Batch rename the following files..."
+```
+
+**Enter Plan mode temporarily** (to make it permanent, set `default_plan_mode = true` in the config file):
+
+```sh
+kimi --plan
+```
+
+## Next steps
+
+- [Configuration files](./config-files.md) — complete reference for all configurable fields
+- [Environment variables](./env-vars.md) — full list and description of `KIMI_CODE_HOME` and related variables

docs/en/configuration/providers.md

@@ -0,0 +1,165 @@
+# Providers and models
+
+Kimi Code CLI supports connecting to multiple LLM platforms simultaneously: one-click login via the Kimi Code managed service, connecting Claude with an Anthropic API key, or connecting third-party inference services via the OpenAI-compatible protocol. Each provider corresponds to a specific API protocol; models are declared on top of providers with their own name, context length, and capabilities. This page explains how to configure each type of provider in `config.toml`.
+
+## Supported provider types
+
+The `type` field in the `providers` table determines which protocol implementation to use:
+
+| Type | Protocol | Typical use |
+| --- | --- | --- |
+| [`kimi`](#kimi) | OpenAI-compatible | Kimi Code managed service, Kimi Platform API key |
+| [`anthropic`](#anthropic) | Anthropic Messages | Claude model family |
+| [`openai`](#openai) | OpenAI Chat Completions | OpenAI and compatible services, DeepSeek, Qwen, etc. |
+| [`openai_responses`](#openai_responses) | OpenAI Responses API | OpenAI's newer Responses interface |
+| [`google-genai`](#google-genai) | Google GenAI | Gemini API |
+| [`vertexai`](#vertexai) | Google GenAI on Vertex | Google Cloud Vertex AI |
+
+All providers communicate with models in streaming mode by default. Capabilities such as thinking, vision, and tool use are matched automatically by model name prefix, so you typically do not need to declare them manually.
+
+**Credential priority**: `api_key` direct field > `[providers.<name>.env]` sub-table key > if both are absent, startup fails with an error. The CLI does not fall back to shell environment variables for credentials. See [Config overrides: provider credentials](./overrides.md#provider-credentials).
+
+## `/provider` — interactive provider management
+
+Prefer not to edit TOML by hand? Type `/provider` in the TUI to open the **provider manager**, where you can interactively add or remove providers.
+
+![The /provider provider manager](../../media/provider-manager.jpg)
+
+The manager displays providers as a list of entries grouped by source. Navigation:
+
+- ↑/↓ to move the cursor, ←/→ to page
+- `d` to delete the current provider (with `[y/N]` confirmation)
+- Press Enter on the `[ Add New Platform ]` row to add a new provider
+
+Two paths when adding:
+
+- **Known third-party provider**: fetches the model catalog from [models.dev](https://models.dev/), select a provider → enter an API key → select a default model. Vendors whose protocol the catalog does not declare (e.g. xai, openrouter, and other vendor-specific SDKs) are imported as OpenAI-compatible with a "guessed" note; when the catalog provides no usable endpoint, a base URL prompt appears first; proprietary protocols (Amazon Bedrock, Cohere) and unrecognized explicit protocols are refused. Deprecated and alpha-status models are excluded from the import list. If the public catalog is unreachable, the CLI falls back to a built-in snapshot of the catalog, so the import still works offline or in blocked networks
+- **Custom registry (api.json)**: paste a custom registry URL and Bearer token; the CLI automatically creates the `providers` / `models` entries. On later startup, providers from the same registry URL are refreshed together, so upstream provider additions, removals, and model metadata changes are synced.
+
+::: warning
+Kimi Code OAuth managed accounts logged in via `/login` do not appear in `/provider`. Use `/login` and `/logout` to manage them.
+:::
+
+The same operations are also available in non-interactive environments via the shell command: [`kimi provider`](../reference/kimi-command.md#kimi-provider).
+
+## `kimi`
+
+For connecting to Moonshot AI's OpenAI-compatible interface, including the Kimi Code managed service and Kimi Platform API keys.
+
+- Default `base_url`: `https://api.moonshot.ai/v1`
+- Credential key names: `KIMI_API_KEY`, `KIMI_BASE_URL`
+- Additional capability: supports video upload
+
+```toml
+[providers.kimi]
+type = "kimi"
+base_url = "https://api.moonshot.ai/v1"
+api_key = "sk-xxxxx"
+```
+
+> When using the Kimi Code managed service, running `/login` automatically configures `base_url` and credentials, so no manual setup is needed.
+
+## `anthropic`
+
+For connecting to the Claude API. Standard Claude models automatically enable vision, tool use, and Thinking (where supported); custom or uncovered models need `capabilities` declared explicitly on `[models.<alias>]`.
+
+- Default `base_url`: follows Anthropic SDK default
+- Credential key names: `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`
+- Default `max_tokens`: inferred per model. To override, set `max_output_size` on the model alias
+
+```toml
+[providers.anthropic]
+type = "anthropic"
+api_key = "sk-ant-xxxxx"
+
+[models."claude-opus-4-7"]
+provider = "anthropic"
+model = "claude-opus-4-7"
+max_context_size = 200000
+# max_output_size = 32000  # optional; omit to use the model-inferred default
+```
+
+## `openai`
+
+For connecting to the OpenAI Chat Completions protocol, as well as any third-party service compatible with that protocol (override `base_url` as needed).
+
+Third-party reasoning models (DeepSeek, Qwen, One API, etc.) work out of the box: the CLI automatically handles the `reasoning_content` field and `reasoning_effort` injection. If your gateway returns reasoning content under a non-standard field name, set `reasoning_key` on the model alias to override.
+
+- Default `base_url`: `https://api.openai.com/v1`
+- Credential key names: `OPENAI_API_KEY`, `OPENAI_BASE_URL`
+
+```toml
+[providers.openai]
+type = "openai"
+base_url = "https://api.openai.com/v1"
+api_key = "sk-xxxxx"
+```
+
+## `openai_responses`
+
+Corresponds to OpenAI's newer Responses API, always operating in streaming mode. Configuration is the same as `openai`.
+
+- Default `base_url`: `https://api.openai.com/v1`
+- Credential key names: `OPENAI_API_KEY`, `OPENAI_BASE_URL`
+
+```toml
+[providers.openai-responses]
+type = "openai_responses"
+base_url = "https://api.openai.com/v1"
+api_key = "sk-xxxxx"
+```
+
+## `google-genai`
+
+For connecting directly to the Google Gemini API. Thinking, vision, and multimodal capabilities are auto-detected by model name.
+
+- Credential key name: `GOOGLE_API_KEY`
+
+```toml
+[providers.gemini]
+type = "google-genai"
+api_key = "xxxxx"
+```
+
+To route through a Gemini-compatible proxy or gateway, set `base_url` (or the `GOOGLE_GEMINI_BASE_URL` env var); when omitted, the SDK default `https://generativelanguage.googleapis.com` is used.
+
+> Give the **host root only**. The Google GenAI SDK appends the API version and path itself (e.g. `/v1beta/models/<model>:generateContent`), so a trailing `/v1beta` would produce a doubled `/v1beta/v1beta/…`.
+
+```toml
+[providers.gemini]
+type = "google-genai"
+api_key = "xxxxx"
+base_url = "https://your-gateway.example"
+```
+
+## `vertexai`
+
+Shares the same implementation as `google-genai`; setting `type = "vertexai"` switches to the Vertex AI access path.
+
+Authentication follows the standard Google Cloud ADC flow (`gcloud auth application-default login` or a `GOOGLE_APPLICATION_CREDENTIALS` service account JSON); this part is unrelated to Kimi Code. **The project ID and region must be written in the `[providers.vertexai.env]` sub-table**. Simply `export GOOGLE_CLOUD_PROJECT` in the shell will not be read by the CLI.
+
+```toml
+[providers.vertexai]
+type = "vertexai"
+
+[providers.vertexai.env]
+GOOGLE_CLOUD_PROJECT = "my-gcp-project"
+GOOGLE_CLOUD_LOCATION = "us-central1"
+```
+
+```sh
+gcloud auth application-default login   # one-time authentication
+kimi
+```
+
+To route Vertex requests through a custom (e.g. proxied) endpoint, set `base_url` (or the `GOOGLE_VERTEX_BASE_URL` env var); when omitted, the SDK default regional `*-aiplatform.googleapis.com` host is used. As with `google-genai`, give the host root only. The SDK appends `/v1beta1/publishers/google/models/…` itself.
+
+## OAuth and credential injection
+
+The Kimi Code managed service uses OAuth rather than static API keys. After running `/login`, the built-in authentication toolchain automatically writes and refreshes credentials, so no manual configuration is needed in `config.toml` for this.
+
+## Next steps
+
+- [Configuration files](./config-files.md) — full field reference for the `providers` and `models` tables
+- [Config overrides](./overrides.md) — credential resolution priority rules for providers
+- [Environment variables](./env-vars.md) — credential key names per provider type

docs/en/customization/agents.md

@@ -0,0 +1,210 @@
+# Agents and Sub-Agents
+
+Every session in Kimi Code CLI is driven by a **main Agent**. The main Agent understands the user's intent, plans steps, calls tools, and when needed dispatches **sub-agents** to handle more focused sub-tasks, such as exploring an unfamiliar codebase, reviewing multiple implementations in parallel, or planning a large refactor without touching the main context.
+
+A sub-agent receives a task description from the main Agent, works in its own isolated context, and then returns its conclusions. It does not communicate with the user directly, and its intermediate reasoning and tool call records do not mix into the main Agent's history.
+
+## Built-in Sub-Agents
+
+Kimi Code CLI includes three built-in sub-agents, ready to use out of the box, each aimed at a different task shape:
+
+- **`coder`**: The default sub-agent, a general-purpose software engineering assistant that can read and write files, execute commands, search code, and land concrete changes.
+- **`explore`**: Dedicated to codebase exploration; performs read-only operations only and does not modify any files. Ideal for quickly searching, reading, and summarizing a repository without touching files.
+- **`plan`**: Dedicated to implementation planning and architecture design; even shell commands are not available, keeping the focus on "figuring out how to do something" rather than "actually doing it."
+
+Beyond the three types, three conventions govern how sub-agents work: tool boundaries, delegation depth, and completion timing.
+
+A `coder` sub-agent shares most of the main Agent's tool set: it can run shell commands in the background, maintain todo lists, enter Plan mode, and invoke Agent Skills. The three built-in sub-agents cannot dispatch further sub-agents.
+
+By default a custom agent inherits the built-in delegation allowlist (`coder`, `explore`, `plan`), whose members cannot dispatch further either, so delegation chains always terminate and unbounded recursive spawning is impossible without an explicit opt-in. A custom agent can opt into deeper chains by declaring an explicit [`subagents`](#agent-file-format) allowlist.
+
+If a sub-agent finishes its turn while background tasks are still running, its run only reports completion after those tasks settle, so the parent receives the result after the underlying work has actually finished.
+
+## How to Invoke
+
+The full pipeline has only three stages (dispatch, approval, and collection), and none of them require manual management.
+
+Sub-agents are scheduled automatically by the main Agent, based on task complexity, context consumption, and sub-task independence. They are dispatched at the right moment without the user having to specify one.
+
+Each dispatch is presented in the terminal as an approval request (unless it matches an allow rule or Ask When Needed mode is active), giving you a chance to review the task description. You can also instruct the main Agent directly in conversation to use a specific sub-agent, for example: "Use explore to map out the relevant files before making any changes."
+
+Sub-agents support running in the background: results are automatically returned to the main Agent upon completion, with no manual polling needed. You can also call back an existing sub-agent instance to continue the same task.
+
+## Context Isolation and Resource Cost
+
+Each sub-agent has a fully independent context window. It can only see the task description explicitly passed by the main Agent and cannot see the main Agent's conversation history. The sub-agent's own intermediate reasoning and tool call records do not flow back; only the final result appears in the main Agent's context.
+
+This isolation provides two benefits:
+
+- **The main Agent's context stays lean** and is not filled with large volumes of exploratory logs during long sessions.
+- **Multiple sub-agents can run in parallel** without interfering with each other.
+
+Note that each sub-agent independently consumes model tokens. For simple tasks, there is no need to dispatch a sub-agent; the main Agent handles them more economically.
+
+## Permission Inheritance
+
+Sub-agent permission rules are inherited from the main Agent: "always allow" rules that the main Agent has accepted via `/permission` or through an approval dialog automatically propagate to all sub-agents it dispatches, so sub-agents do not need to re-approve the same types of tool calls. The `Agent` tool itself is allowed by default, enabling the main Agent to delegate multiple times without interrupting the user.
+
+If you need a particular type of tool to be permanently unavailable inside sub-agents, tighten the corresponding permission rule on the main Agent.
+
+## Custom Agents
+
+Beyond the three built-in sub-agents, you can define your own agents as Markdown files. Each file describes one agent: the frontmatter (YAML metadata at the top of the file) declares its name, description, and tool access, and the file body is its system prompt. The main Agent discovers custom agents automatically alongside the built-in ones, so they can be delegated to as sub-agents. They can also be selected as the main Agent at startup.
+
+### Agent Locations
+
+Kimi Code CLI discovers agent files by scope; more specific scopes take higher priority: **Explicit (`--agent-file`) > Project > Extra > User > Plugin > Built-in**. When two files define the same `name`, the higher-priority scope wins. Each directory is scanned recursively for `.md` files.
+
+**User level** (applies to all projects):
+- `$KIMI_CODE_HOME/agents/` (default: `~/.kimi-code/agents/`)
+- `~/.agents/agents/`
+
+The Kimi-specific user agent directory moves with `KIMI_CODE_HOME`, while the generic `~/.agents/agents/` directory stays under the real OS home so it can be shared across tools.
+
+**Project level** (project root = the nearest directory containing `.git`, searching upward from the working directory):
+- `.kimi-code/agents/`
+- `.agents/agents/`
+
+**Extra directories**: Declared via `extra_agent_dirs` at the top level of `config.toml`:
+
+```toml
+extra_agent_dirs = ["~/team-agents", ".agents/team-agents"]
+```
+
+**Plugin level**: directories declared in an enabled plugin's manifest `agents` field (when omitted, the `agents/` directory under the plugin root is picked up automatically); see [Plugin Agents](./plugins.md#plugin-agents). Plugin agents outrank only the built-in agents.
+
+**Built-in agents** are distributed with the CLI and have the lowest priority. A directory-discovered file does not override a same-name built-in Agent unless its frontmatter declares `override: true`. A file loaded through `--agent-file` is treated as explicit launch intent, may override a same-name built-in Agent, outranks every directory scope, and applies to the current launch only.
+
+Separately, `$KIMI_CODE_HOME/SYSTEM.md` permanently overrides the default main agent's system prompt; it is not part of agent-file discovery. Its precedence interactions are covered in the [SYSTEM.md section](#overriding-the-main-agents-system-prompt-with-systemmd).
+
+::: warning Trust model
+Agent files are prompt configuration, and project-level files come from the repository itself, including repositories you have just cloned and do not trust yet. A project-scoped file can take over a built-in agent entirely: naming it `agent.md` with `override: true` replaces the **default main agent's whole system prompt**, and `coder.md` with `override: true` replaces the default sub-agent type. Unlike `AGENTS.md` content, which is injected into the prompt as reference data, an override file *is* the system prompt, and a file without a `tools` list keeps every tool. Review `.kimi-code/agents/` and `.agents/agents/` in unfamiliar repositories with the same caution you would apply to scripts, before running Kimi Code inside them.
+:::
+
+### Agent File Format
+
+An agent file is plain Markdown with a frontmatter block:
+
+```markdown
+---
+name: reviewer
+description: Strict code reviewer that reports severity-ranked findings
+whenToUse: Code reviews and PR checks
+override: false
+tools:
+  - Read
+  - Grep
+  - Glob
+  - mcp__github__*
+disallowedTools:
+  - Bash
+---
+
+You are a strict code reviewer. Read the diff, then report findings grouped by severity…
+```
+
+Frontmatter fields:
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `name` | no | Unique kebab-case identifier; defaults to the file name without its extension. A file with a missing or non-kebab-case name is skipped with a warning |
+| `description` | yes | What the agent does, shown to the main Agent when it picks a sub-agent. Write it to guide delegation decisions |
+| `whenToUse` | no | Extra hint describing when the agent should be used |
+| `override` | no | Whether the file may replace a same-name built-in Agent; defaults to `false`. `--agent-file` does not need it |
+| `tools` | no | Tool allowlist (`Read`, `Bash`); MCP tools match as globs (`mcp__github__*`). YAML list or comma-separated string; omit or use a lone `*` to allow all tools, `tools: []` disables all tools |
+| `disallowedTools` | no | Denylist with the same syntax and matching rules, applied after `tools` |
+| `subagents` | no | Sub-agent allowlist, same syntax as `tools`. Omit to inherit the built-in default (`coder`, `explore`, `plan`); a lone `*` allows every type. The main agent's effective list also includes every discovered custom agent |
+
+Built-in and user tools match by exact, case-sensitive name; entries starting with `mcp__` match MCP tools as globs. Three entry shapes never match anything and are reported with a warning when the profile takes effect:
+
+- A wildcard outside an `mcp__` pattern: a bare `*` in `disallowedTools` disables nothing.
+- An incomplete `mcp__` literal: `mcp__github` matches nothing; use `mcp__github__*` for the whole server.
+- A name no registered or built-in tool has, usually a typo such as `read` instead of `Read`.
+
+The body is the agent's system prompt, and it is rendered as a template each time the prompt is built: `${var}` placeholders substitute live context values. Unknown variables stay verbatim, a bare `$` is never special, and a variable with no context value renders as an empty string. `${base_prompt}` embeds the effective default system prompt (the built-in default, or your `SYSTEM.md` override when present), so a file can wrap the default behavior instead of replacing it. If the file replaces the default prompt but should still honor instructions contributed by enabled plugins, place `${plugin_sections}` where those instructions should appear. The available variables are listed in the [SYSTEM.md section](#overriding-the-main-agents-system-prompt-with-systemmd).
+
+Unknown fields are ignored, so newer files stay readable by older versions. Fields from other agent tools (such as Claude Code's `model` or OpenCode's `mode`) are ignored the same way, the comma-separated `tools` form keeps Claude Code-style agent files loadable, and a missing `name` falls back to the file name so OpenCode-style files load too. A minimal file with `description` and a body works across tools.
+
+A file with invalid content discovered in a directory is skipped with a warning and does not affect other files. A file passed explicitly via `--agent-file` must be valid, otherwise the CLI reports the error and exits.
+
+::: warning Note
+`tools` and `disallowedTools` shape the tools shown to the model and are enforced again before execution. `subagents` works the same way: the `Agent` tool lists only the sub-agent types the caller may delegate to, and both `Agent` and `AgentSwarm` re-check the allowlist before dispatching; resuming an existing sub-agent is exempt. Permission rules remain a separate control for operations that require approval.
+:::
+
+Custom agents delegated as sub-agents run without the built-in sub-agent framing ("your final message is the entire handoff"). If you write an agent meant for delegation, state in the body that its last message should be the complete, self-contained result for the caller.
+
+### Selecting the Main Agent
+
+Two CLI flags select which agent drives a new session, in both print mode (`kimi -p`) and the interactive TUI:
+
+- **`--agent <name>`**: Start the session with the named agent as the main Agent. The name can refer to a built-in agent or to any discovered file; an unknown name fails with an error listing the available agents.
+- **`--agent-file <path>`**: Load one agent file at the highest priority for this launch and start with it. The flag accepts exactly one file: it cannot be repeated, and it cannot be combined with `--agent`.
+
+Both flags only apply when starting a new session: neither can be combined with `--session`/`--continue`. The agent is bound at session creation, and resuming restores the bound agent automatically, so no flag is needed (or allowed) on resume.
+
+For example:
+
+```sh
+kimi --agent reviewer
+kimi -p --agent reviewer "Review the changes on this branch"
+```
+
+The bound agent is the session's identity: it is fixed at the session's first bind and cannot be switched later. In the TUI the flags bind only the startup session; a session created later in the same process (for example via `/new`) starts with the default agent.
+
+For main-agent customization, reference `${base_prompt}` in the body so the environment, workspace-instruction, Skill, and plugin injections already present in the effective default prompt stay in effect. When you want to replace the default prompt but keep only plugin-contributed instructions, use `${plugin_sections}` instead. A body without `${base_prompt}` or `${plugin_sections}` owns the entire prompt and excludes plugin instructions, which fits self-contained sub-agents.
+
+### Overriding the main agent's system prompt with SYSTEM.md
+
+To override the main agent's system prompt permanently, without passing `--agent` or `--agent-file` on every launch, write a `$KIMI_CODE_HOME/SYSTEM.md` file (default: `~/.kimi-code/SYSTEM.md`; it moves with `KIMI_CODE_HOME`). While the file exists and is non-empty, it fully replaces the built-in default main agent's system prompt (and only the prompt: the description, tool set, and sub-agent delegation allowlist are inherited from the built-in defaults). SYSTEM.md takes effect in every launch mode, including interactive TUI sessions.
+
+SYSTEM.md is a plain Markdown body; no frontmatter is required or read. A missing or empty file has no effect, and a read failure falls back to the built-in prompt with a warning.
+
+Explicit intent still outranks it:
+
+- A project-scoped same-name agent file declaring `override: true`, and any file passed via `--agent-file`, rank ahead of SYSTEM.md.
+- Selecting another agent with `--agent` bypasses SYSTEM.md entirely.
+- Within the user scope itself, SYSTEM.md wins over a same-name file discovered in the `agents/` directories.
+
+Like the body of a regular agent file, SYSTEM.md is rendered as a template each time the prompt is built, and `${var}` placeholders in the body are substituted from the live context:
+
+| Variable | Content |
+| --- | --- |
+| `${skills}` | The merged Agent Skills injection; empty when the `Skill` tool is unavailable |
+| `${agents_md}` | Content of the workspace instruction files (such as `AGENTS.md`) |
+| `${cwd}` | Current working directory |
+| `${cwd_listing}` | Listing of the working directory |
+| `${os}` | Operating system kind |
+| `${shell}` | Shell name and path, for example `bash (\`/bin/bash\`)` |
+| `${now}` | Current time (ISO format) |
+| `${additional_dirs_info}` | Additional directories added to the workspace; empty when there are none |
+| `${base_prompt}` | The default system prompt. Inside `SYSTEM.md` itself this is the built-in default; inside an agent file it is the effective default (the built-in default, or your `SYSTEM.md` override when present) |
+| `${plugin_sections}` | A complete Plugin Instructions block contributed by enabled plugins; empty when no enabled plugin contributes instructions |
+
+Unknown variables stay verbatim, a bare `$` is never special, and a variable with no context value renders as an empty string. Four pre-composed blocks (`${windows_notes}`, `${additional_dirs_section}`, `${skills_section}`, and `${plugin_sections}`) render the matching built-in prompt section, or an empty string when it does not apply. The built-in default prompt already includes `${plugin_sections}`, so do not add it again when `${base_prompt}` already expands to that prompt. The variables are enough to rebuild the skeleton of the built-in prompt, for example:
+
+```markdown
+You are Kimi, running at ${cwd} on ${os}.
+
+${agents_md}
+
+${skills}
+
+${plugin_sections}
+```
+
+## Instruction Files
+
+Global Kimi-specific instructions can live at `$KIMI_CODE_HOME/AGENTS.md` (default: `~/.kimi-code/AGENTS.md`). When you relocate the data root with `KIMI_CODE_HOME`, this global instruction file moves with it. Generic cross-tool instructions can still live under `~/.agents/AGENTS.md` in the real OS home, and project-level instructions remain under the project tree, for example `.kimi-code/AGENTS.md` or `AGENTS.md`.
+
+## Storage Location in the Session Directory
+
+Sub-agent runtime state is persisted to the `agents/` subdirectory of the current session directory. Each sub-agent instance has its own directory, which contains a `wire.jsonl` file that records prompts, message history, and final state in chronological order. Background sub-agents also expose their lifecycle status through a `tasks/` subdirectory.
+
+::: warning Note
+Session directories, wire files, and task records are all local debug materials that may contain user prompts, command output, repository paths, tool return values, or traces of credentials. Do not commit these files directly to public repositories, issues, or chat logs; redact sensitive information before sharing.
+:::
+
+## Next steps
+
+- [Hooks](./hooks.md) — Trigger local script notifications or interceptions at key points such as sub-agent completion
+- [Agent Skills](./skills.md) — Inject specialized knowledge and workflows into sub-agents

docs/en/customization/datasource.md

@@ -0,0 +1,10 @@
+---
+head:
+  - - meta
+    - http-equiv: refresh
+      content: 0; url=./plugins.html#kimi-datasource
+---
+
+# Kimi Datasource
+
+This page has moved to [Plugins: Kimi Datasource](./plugins.md#kimi-datasource).

docs/en/customization/hooks.md

@@ -0,0 +1,170 @@
+# Hooks
+
+Hooks are an automatic trigger mechanism: you tell Kimi Code CLI in advance "whenever X happens, run this script." The script runs on your local machine, and you can put any logic inside it. Typical use cases:
+
+- **Security interception**: Before the Agent executes a shell command, check whether it contains dangerous operations (such as `rm -rf`) and block execution if so
+- **Desktop notifications**: When a background task completes, pop up a system notification to bring you back to review the results
+- **Automatic checks**: Each time the user submits a message, automatically append some background information to the context (such as the current Git branch)
+
+## How Hooks Work
+
+Configuring a hook rule requires specifying three things: **which event to trigger on**, **which targets to match**, and **which script to run**.
+
+When triggered, the CLI packages the event's details (trigger reason, tool name, command content, etc.) into JSON and passes it to your script via **standard input** (stdin). The script reads this information and decides how to respond.
+
+The script's response is determined by two things:
+
+- **Exit code**: `0` means allow, `2` means block, other non-zero values default to allow
+- **Standard output** (stdout): can include explanatory text
+
+Even if the script errors or times out, the CLI **will not interrupt your work** as a result. This "allow on failure" design is called fail-open, preventing hook errors from becoming blockers.
+
+::: warning Note
+Precisely because of fail-open, Hooks are suitable for alerts and lightweight interception, but **should not be used as the sole security barrier**. For truly high-risk operations, rely on permission approvals and manual confirmation.
+:::
+
+## Quick Start: A Minimal Hook
+
+The following hook flashes a notification in the terminal title bar each time a background task completes (macOS requires `terminal-notifier` to be installed):
+
+```toml
+# Written in ~/.kimi-code/config.toml
+[[hooks]]
+event = "Notification"           # Trigger: when a background task status changes
+matcher = "task\\.completed"     # Only care about "completed" notifications
+command = "terminal-notifier -title Kimi -message 'Task done'"
+```
+
+Save the config, start a new session, and a notification will appear the next time a background task completes.
+
+## Configuration
+
+All hook rules are written in the `[[hooks]]` array in `~/.kimi-code/config.toml`, where each entry is one rule:
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `event` | `string` | Yes | Trigger event name; must be one of the events in the [event reference](#event-reference) |
+| `matcher` | `string` | No | A regular expression to filter event targets; if omitted, matches all |
+| `command` | `string` | Yes | The shell command to run when triggered |
+| `timeout` | `integer` | No | Timeout in seconds, range 1–600; defaults to 30 seconds |
+
+`[[hooks]]` only allows these four fields; extra fields will cause the config file to fail to load.
+
+**When multiple rules match the same event**, all matching hooks run in parallel; multiple rules with identical `command` values run only once.
+
+The working directory for hook commands is the current session's project directory.
+
+<details>
+<summary>Process group and timeout handling</summary>
+
+On non-Windows platforms, hook processes run in a separate process group; on timeout, the CLI first sends a signal to give the script a chance to clean up, then forcibly terminates it.
+
+</details>
+
+### Event Data Format
+
+Each time a hook triggers, the CLI passes the following base information to the script via stdin:
+
+```json
+{
+  "hook_event_name": "PreToolUse",
+  "session_id": "session_abc",
+  "session_title": "Fix the login page",
+  "client_type": "kimi_code_cli",
+  "cwd": "/path/to/project"
+}
+```
+
+Specific events will also include additional fields (such as tool name and command content); see the [event reference](#event-reference). All field names use snake_case.
+
+## Return Values
+
+After the script exits, the CLI determines the hook's intent based on the exit code:
+
+| Exit code | Meaning | CLI behavior |
+| --- | --- | --- |
+| `0` | Normal exit, allow | Continue execution; stdout content (if any) may be appended to context |
+| `2` | Intentional block | Stop the current operation; stderr content (printed via `console.error`) is used as the reason for blocking |
+| Other non-zero | Script error | Default allow (fail-open) |
+| Timeout or crash | Script exception | Default allow (fail-open) |
+
+You can also return a JSON object via stdout to block:
+
+```json
+{
+  "hookSpecificOutput": {
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Please use rg instead of grep"
+  }
+}
+```
+
+::: info Which events support blocking?
+Only **blockable events** (`PreToolUse`, `Stop`, `UserPromptSubmit`) have return values that affect the main flow. All other events are **observation-only events**: they fire and forget, and the main flow is unaffected regardless of what the script returns.
+:::
+
+## Event Reference
+
+| Event | Matcher matches | Supports blocking? | Description |
+| --- | --- | --- | --- |
+| `UserPromptSubmit` | The text submitted by the user | ✓ | Triggered when the user sends a message; returned text is appended to context; blocking skips the model call this turn |
+| `UserPromptQueued` | The queued prompt text | — | Triggered when a message is queued while a turn is still running; payload includes `prompt_id`, `prompt`, `queue_length` |
+| `PreToolUse` | Tool name | ✓ | Triggered before a tool call (before permission checks); the tool will not execute if blocked |
+| `Stop` | Empty string | ✓ | Triggered when the model is about to end the turn; if blocked, a message can be appended to let the model continue |
+| `TurnStarted` | Turn origin kind (e.g. `user`, `task`, `system_trigger`) | — | Triggered when a new turn begins; payload includes `turn_id`, `origin_kind`, `origin_name`, `prompt` |
+| `PostToolUse` | Tool name | — | Triggered after a tool executes successfully |
+| `PostToolUseFailure` | Tool name | — | Triggered after a tool fails or is blocked |
+| `PermissionRequest` | Tool name | — | Triggered just before waiting for user approval |
+| `PermissionResult` | Tool name | — | Triggered after approval completes |
+| `SessionStart` | `startup` or `resume` | — | Triggered after a session starts or resumes; payload includes `source`, `model`, `profile` |
+| `SessionEnd` | `exit` or `archive` | — | Triggered after a session closes; `archive` means the session was archived rather than exited |
+| `SessionHeartbeat` | Empty string | — | Triggered every 60 seconds while the session is alive; the timer runs only when this event is configured; payload includes `uptime_ms` |
+| `SubagentStart` | Sub-agent name | — | Triggered before a sub-agent starts running |
+| `SubagentStop` | Sub-agent name | — | Triggered after a sub-agent completes successfully |
+| `TaskStarted` | Task kind (`agent`, `process`, or `question`) | — | Triggered when a background task starts; payload includes `task_id`, `description`, `detached` |
+| `StopFailure` | Error type | — | Triggered after the current turn fails due to an error |
+| `Interrupt` | Empty string | — | Triggered when the user interrupts the turn (e.g. pressing Esc); not fired for timeouts or programmatic aborts; fires in place of `Stop`; payload includes `reason` |
+| `PreCompact` | `manual` or `auto` | — | Triggered before context compaction begins; return values are completely ignored |
+| `PostCompact` | `manual` or `auto` | — | Triggered after context compaction completes |
+| `Notification` | Notification type (e.g. `task.completed`) | — | Triggered when a background task status changes |
+
+## Example: Blocking Dangerous Shell Commands
+
+The following hook checks the command content before the Agent calls the `Bash` tool and blocks it if `rm -rf` is detected:
+
+```toml
+[[hooks]]
+event = "PreToolUse"
+matcher = "Bash"
+command = "node ~/.kimi-code/hooks/block-dangerous-bash.mjs"
+timeout = 5
+```
+
+```js
+// block-dangerous-bash.mjs
+// Read event data passed by the CLI from stdin
+let input = '';
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  const payload = JSON.parse(input);         // Parse event data
+  const command = payload.tool_input?.command ?? '';
+
+  if (command.includes('rm -rf')) {
+    // Explain the blocking reason via stderr; exit code 2 means block
+    console.error('Dangerous command detected, blocked');
+    process.exit(2);
+  }
+  // Normal exit (exit code 0) means allow
+});
+```
+
+After blocking, Kimi Code CLI writes the blocking reason back into the context, and the model can use this to choose a safer alternative.
+
+::: warning Note
+This example only demonstrates the blocking mechanism and is not a production-grade security parser. Real scenarios are better served by whitelists, or a dedicated shell parser to handle quoting, variable expansion, and multi-command sequences.
+:::
+
+## Next steps
+
+- [Configuration](#configuration) — Full field reference for `[[hooks]]` in `config.toml`
+- [Agents and sub-agents](./agents.md) — Use the `SubagentStop` event to trigger notifications after a sub-agent completes

docs/en/customization/mcp.md

@@ -0,0 +1,140 @@
+# Model Context Protocol
+
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open protocol that lets models safely call tools exposed by external processes or services: reading GitHub issues, querying databases, or operating the local file system. Kimi Code CLI acts as an MCP client to connect these external tools and exposes them to the Agent alongside built-in tools (`Read`, `Bash`, `Grep`, etc.) with no behavioral difference.
+
+MCP tool results can include text (`content`) and structured data (`structuredContent`). Kimi Code CLI makes both available to the agent and omits the structured copy only when it can confirm that a text block already contains the same complete JSON value. Text summaries and media do not replace structured records.
+
+Kimi Code CLI preserves embedded MCP attachments that cannot be delivered directly because of format or size limits. Embedded images, audio, and video are saved even when they can be delivered unchanged, because provider conversion or later history reduction may omit them. Session-attachment readers remain available without workspace filesystem access when the model supports the corresponding content. Originals are retained in the session's media storage instead of an evictable image cache. Saved originals, including images preserved during compression, have absolute paths and stable `kimi-file://` references. Pass a reference as the `path` to `Read` or `ReadMediaFile`; bytes are read from the current session's storage even when the workspace runtime cannot access it. Pagination keeps the reference, including after a fork. For binary formats that `Read` cannot open, its error includes a server-local path when available; an external converter must have access to that filesystem. Text attachments such as CSV, HTML, JSON, and plain SVG use readable extensions.
+
+Attachment paths and compression details share the tool-output budget. Large lists are saved to a text file, with a short pointer that remains visible when accompanying text is shortened; the agent can pass the list’s `kimi-file://` reference to `Read` and page through it. Canceling the tool stops subsequent attachment processing and signals active writes. If decoding or saving fails, the result explicitly reports that the original could not be preserved while retaining other usable output. Resource links are not automatically downloaded.
+
+## Connection Methods
+
+Kimi Code CLI supports three MCP server connection methods:
+
+- **stdio**: The CLI starts the local MCP server as a child process and communicates via standard input/output. Suitable for local command-line tools.
+- **HTTP**: The CLI connects to an already-running HTTP endpoint. Suitable for remote services or processes that need to run persistently.
+- **SSE**: The CLI connects to a legacy HTTP+SSE endpoint (Server-Sent Events, a streaming HTTP mechanism). Prefer HTTP for new MCP servers, but use `transport: "sse"` when a service still exposes only the older SSE transport.
+
+## Configuration
+
+MCP server configuration is written in `mcp.json`, at two levels:
+
+- **User level**: `~/.kimi-code/mcp.json` (or `$KIMI_CODE_HOME/mcp.json`), shared across projects
+- **Project level**: `.kimi-code/mcp.json` in the working directory, effective only for the current repository
+
+Entries with the same name: the project-level entry takes precedence and overrides the user-level entry.
+
+Run `/mcp-config` in the TUI to interactively add, edit, or delete servers without manually editing the JSON file. Run `/mcp` to view the connection status of all current servers.
+
+Deleting a server from the configuration does not interrupt open sessions: the server stays listed in `/mcp` as `removed`, its tools remain visible there, and calls to them fail with a removal notice, while new sessions do not register the tools at all. Conversely, a server added mid-session by editing `mcp.json` or installing a plugin is not registered in already-open sessions; it only joins sessions created later.
+
+When Kimi Code finds project-level MCP servers in an untrusted folder, it shows each server's transport and launch target in the workspace trust prompt. The prompt defaults to `Trust this folder`; review the listed command and arguments or remote URL before confirming. Trusting the folder enables the project-level MCP servers for that workspace.
+
+Structure of `mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+    },
+    "linear": {
+      "url": "https://mcp.linear.app/mcp"
+    },
+    "legacy-events": {
+      "transport": "sse",
+      "url": "https://mcp.example.com/sse"
+    }
+  }
+}
+```
+
+Entries with a `command` field are stdio servers; entries with a `url` field and no `transport` are HTTP servers. For legacy SSE servers, set `transport` to `"sse"` explicitly.
+
+Optional fields:
+
+| Field | Type | Applies to | Description |
+| --- | --- | --- | --- |
+| `env` | `Record<string, string>` | stdio | Environment variables injected into the child process |
+| `cwd` | `string` | stdio | Working directory for the child process |
+| `headers` | `Record<string, string>` | HTTP, SSE | Static request headers appended to every request |
+| `bearerTokenEnvVar` | `string` | HTTP, SSE | Name of an environment variable that contains a bearer token |
+| `enabled` | `boolean` | All | Set to `false` to disable this server |
+| `deferred` | `boolean` | All | Experimental: set to `true` to let the model load this server's tools on demand. Defaults to `false` (always exposed inline). Prerequisites and behavior: [Loading tools on demand](#loading-tools-on-demand) |
+| `startupTimeoutMs` | `number` | All | Connection timeout from `1` to `2147483647` milliseconds; default `30000` |
+| `toolTimeoutMs` | `number` | All | Timeout from `1` to `2147483647` milliseconds for a single tool call |
+| `enabledTools` | `string[]` | All | Tool allowlist |
+| `disabledTools` | `string[]` | All | Tool blocklist |
+
+You do not have to set the connection timeout or the single tool-call timeout per server: `[mcp] startup_timeout_ms` / `[mcp] tool_timeout_ms` in `config.toml` or the `KIMI_MCP_STARTUP_TIMEOUT_MS` / `KIMI_MCP_TOOL_TIMEOUT_MS` environment variables change the global defaults. Precedence is: per-server field > environment variable > `config.toml` > built-in default. See [Configuration files](../configuration/config-files.md#mcp).
+
+HTTP and SSE servers support providing static credentials via `headers` or `bearerTokenEnvVar`. When OAuth is needed, run `/mcp-config login <server-name>` to complete browser-based authorization.
+
+Plugins can also declare MCP servers in their manifest. Servers declared by a plugin are enabled by default and can be disabled or re-enabled in `/plugins`: disabling or removing one makes calls from open sessions fail with a removal notice, and adding or enabling a server connects it in open sessions right away. See [Plugins](./plugins.md#mcp-servers-in-plugins) for details.
+
+::: warning Note
+stdio entries in a project-level `.kimi-code/mcp.json` execute local commands when a session starts. Only enable these in repositories you trust.
+:::
+
+## Loading tools on demand
+
+By default, every tool of a server goes straight into the model's top-level tool list; with many connected servers — or a single server that exposes many tools — those definitions occupy context for the whole session. Marking a server as deferred keeps its tools out of the top-level list: the model first sees a manifest of loadable tools, loads full definitions on demand through the built-in `select_tools` tool, and can call them in the same turn once loaded.
+
+Loading tools on demand is experimental and takes effect only when both prerequisites are met:
+
+- The `tool-select` experimental flag is on: set `KIMI_CODE_EXPERIMENTAL_TOOL_SELECT=1`, or write `tool-select = true` under `[experimental]` in `config.toml`; the master switch `KIMI_CODE_EXPERIMENTAL_FLAG=1` enables it too.
+- The current model declares the `dynamically_loaded_tools` capability: official models declare it automatically; for other models, add it to `capabilities` in `config.toml` — see [Configuration files](../configuration/config-files.md#models).
+
+With both prerequisites met, set `deferred: true` on the server entry in `mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "url": "https://mcp.example.com/mcp",
+      "deferred": true
+    }
+  }
+}
+```
+
+Servers without `deferred` are unaffected and always exposed inline; when a prerequisite is missing, the field is ignored with the same result. The authentication tool exposed by an OAuth server before authorization completes follows the same field.
+
+## Tool Naming and Permissions
+
+MCP tools are named in the format `mcp__<server>__<tool>`, for example `mcp__github__create_issue`. Permission rules support `*` and `**` wildcards, for example `mcp__github__*` matches all tools under that server. MCP tool parameters are not included in permission matching.
+
+Calls that do not match any permission rule trigger an approval request. Selecting "Approve for this session" in the approval dialog automatically allows subsequent calls of the same kind within the current session.
+
+You can also pre-configure permanent rules in `[[permission.rules]]` in `config.toml`:
+
+```toml
+[[permission.rules]]
+decision = "allow"
+pattern = "mcp__github__*"
+
+[[permission.rules]]
+decision = "deny"
+pattern = "mcp__filesystem__write_file"
+```
+
+For the full permission rule syntax, see [Configuration files](../configuration/config-files.md#permission).
+
+## Security
+
+When connecting to external MCP servers, be aware of:
+
+- Only connect to servers from trusted sources
+- Verify that tool names and parameters look reasonable in approval requests
+- Keep manual approval for high-risk tools (file writes, command execution, etc.); avoid using `mcp__*` wildcards to allow all tools at once
+
+::: warning Note
+In [Ask When Needed mode](../guides/interaction.md#the-three-permission-modes), MCP tool calls are automatically approved. Only use this mode when you fully trust the MCP servers you have connected.
+:::
+
+## Next steps
+
+- [Plugins](./plugins.md) — Declare MCP servers in a plugin manifest to package and distribute them together
+- [Configuration files](../configuration/config-files.md#permission) — Full field reference for permission rules

docs/en/customization/plugins.md

@@ -0,0 +1,500 @@
+# Plugins
+
+Plugins package reusable Kimi Code CLI capabilities into installable units: they can add [Agent Skills](./skills.md), custom [agents](./agents.md), automatically load a specified Skill at session start, contribute system-prompt instructions, and declare MCP servers to provide real tool capabilities. They are ideal for sharing workflows with a team, connecting to external services, or installing extensions from the [official plugins](#official-plugins).
+
+## Installation and Management
+
+Run `/plugins` in the TUI to open the plugin manager. It is a single panel with four tabs, switched with `Tab` / `Shift-Tab`:
+
+- **Installed**: Manage installed plugins
+- **Official**: Kimi-maintained marketplace plugins
+- **Curated**: Third-party plugins from Kimi partners in the default marketplace
+- **Custom**: Install from a URL
+
+Common keys:
+
+| Key | Action |
+| --- | --- |
+| `Tab` / `Shift-Tab` | Switch between the Installed / Official / Curated / Custom tabs |
+| `Space` | Enable or disable the selected installed plugin (Installed tab) |
+| `D` | Remove the selected installed plugin (Installed tab) |
+| `M` | Manage MCP servers for the selected plugin (Installed tab) |
+| `R` | Reload `installed.json` and all manifests (Installed tab) |
+| `Enter` | Installed: update if available, or view details · Official/Curated: install or update · Custom: install |
+| `I` | View plugin details (Installed tab) |
+| `Esc` | Go back or cancel |
+
+You can also use slash commands directly:
+
+| Command | Description |
+| --- | --- |
+| `/plugins` | Open the interactive plugin manager |
+| `/plugins list` | List installed plugins |
+| `/plugins install <path-or-url>` | Install from a local directory, zip URL, or GitHub repository URL |
+| `/plugins marketplace [source]` | Browse the official marketplace, or pass a custom marketplace JSON path or URL |
+| `/plugins info <id>` | View plugin details and diagnostics |
+| `/plugins enable <id>` | Enable a plugin |
+| `/plugins disable <id>` | Disable a plugin |
+| `/plugins remove <id>` | Remove a plugin (requires confirmation) |
+| `/plugins reload` | Reload `installed.json` and all plugin manifests |
+| `/plugins mcp enable <id> <server>` | Enable an MCP server declared by a plugin |
+| `/plugins mcp disable <id> <server>` | Disable an MCP server declared by a plugin |
+
+### Installing from GitHub
+
+Use `/plugins install <url>` to install directly from a GitHub repository. Four URL forms are supported:
+
+- `https://github.com/<owner>/<repo>`: Install the latest release; falls back to the default branch if no release exists
+- `https://github.com/<owner>/<repo>/tree/<ref>`: Install a specific branch, tag, or short commit SHA
+- `https://github.com/<owner>/<repo>/releases/tag/<tag>`: Pin to a specific tag
+- `https://github.com/<owner>/<repo>/commit/<sha>`: Pin to a specific commit
+
+Network requests only go through `github.com` redirects and `codeload.github.com` downloads; `api.github.com` is not called.
+
+### Notes
+
+- Plugin changes apply after `/reload` or in new sessions. After installing, enabling/disabling, or removing a plugin, run `/reload` or `/new`; the current session will not update.
+- Local installations are copied to `$KIMI_CODE_HOME/plugins/managed/<id>/`, and the CLI always runs from this managed copy. Editing the original source directory after installation has no effect; you must reinstall.
+- Removing a plugin only deletes the installation record; the managed copy and original source files remain on disk.
+- Plugins are currently installed per-user and apply to all projects; project-level installation scope is not yet supported.
+
+### Custom marketplace JSON
+
+Pass a custom marketplace JSON path or URL to `/plugins marketplace <source>`, or set [`KIMI_CODE_PLUGIN_MARKETPLACE_URL`](../configuration/env-vars.md) to override the default catalog. Each entry in the `plugins` array needs an `id` and a `source` (local path, zip URL, or GitHub URL):
+
+```json
+{
+  "version": "2",
+  "plugins": [
+    {
+      "id": "my-plugin",
+      "displayName": "My Plugin",
+      "source": "./my-plugin"
+    }
+  ]
+}
+```
+
+## Official Plugins
+
+Official plugins are plugins and built-in product capabilities maintained by Kimi. There are currently three:
+
+- **[Kimi Datasource](#kimi-datasource)**: Query financial market data, financial news, macroeconomic indicators, corporate registration records, academic literature, Chinese laws and regulations, and official data from intergovernmental organizations in natural language
+- **[Kimi Browser Extension](#kimi-browser-extension)**: Let AI drive your own browser to get web tasks done
+- **[Kimi Computer Use](#kimi-computer-use)**: Let AI operate your desktop apps (macOS and Windows)
+
+### Installation and Upgrade
+
+All official plugins share the same installation and upgrade flow:
+
+1. Run `/plugins` and press `Tab` to select **Official**
+2. Find the plugin you want and press `Enter` to install
+3. After installation completes, run `/reload` or `/new` to activate it
+
+::: info Note
+Kimi Browser Extension installs in two parts: after the steps above, you also need to [install the browser extension](#install-the-browser-extension) before it works.
+:::
+
+Official plugins do not update automatically. When an update is available, you'll be prompted the next time you use the old version. To upgrade, repeat the installation steps above.
+
+### Kimi Datasource <Badge type="tip" text="v3.4.0" />
+
+Kimi Datasource is the official Kimi Code data plugin, letting you query financial market data, financial news, macroeconomic indicators, corporate registration records, academic literature, Chinese laws and regulations, and official data from intergovernmental organizations in natural language. No manual API calls or data accounts required.
+
+Sources include authoritative institutions and leading databases such as the World Bank, IMF, OECD, FRED, WHO, FAO, the National Bureau of Statistics of China, Wind, S&P Capital IQ, SEC EDGAR, Caixin, Xinhua Finance, and Hundsun Juyuan, all traceable to their original publishers.
+
+You must first complete OAuth login with a Kimi Code account via `/login`; data queries consume your Kimi Code plan quota.
+
+#### How to use
+
+1. Describe your need in natural language, and Kimi Code will automatically invoke the data capabilities
+2. Explicitly trigger the data query skill with `/skill:kimi-datasource`
+
+#### What you can do
+
+::: details **Live market research** — Want to run a quantitative analysis on a stock?
+Pull three years of daily closing prices, MACD, and KDJ signals in a single query, no third-party data platforms needed.
+:::
+
+::: details **Cross-country macro comparison** — Studying supply-chain shifts across China, India, and Vietnam?
+Get complete GDP growth, trade volume, and demographic time-series for multiple countries from World Bank data spanning 50+ years, all in one go.
+:::
+
+::: details **Pre-contract risk check** — Need to vet a counterparty minutes before signing?
+Type the company name and instantly get business registration, equity structure, litigation disputes, and credit blacklist status, right when you need it.
+:::
+
+::: details **Literature review acceleration** — Tracing the research arc of RLHF for a paper?
+Get the most-cited papers, key authors, and core findings in seconds, so your literature review outline takes shape in half the time.
+:::
+
+::: details **On-the-spot legal lookup** — Need to confirm the statute behind a residence-right contract dispute?
+Pinpoint the relevant Civil Code articles (full text, authority level, and validity) in one query, then pull a few comparable precedents to back them up, without digging through statute databases.
+:::
+
+::: details **Institutional-grade US equity research** — Writing a deep dive on a US stock?
+Pull the annual report, standardized financial metrics, top-50 holders, and consensus estimates in one go, no more juggling multiple data terminals.
+:::
+
+::: details **Financial news and industry data** — Tracking market hotspots or policy moves?
+Query Caixin's market news, bond/fund/futures data, and listed-company supply-chain relationships, plus news, policies, announcements, and market flashes from the Xinhua Finance national financial information platform. All sources are authoritative and traceable.
+:::
+
+::: details **Standards lookup** — Need to check compliance against Chinese standards?
+Look up national (GB), industry, local, and association standards by number or topic, with status and full-text entry points.
+:::
+
+#### Coverage
+
+| Category | Scope |
+|---|---|
+| Stocks & financial markets | Wind, S&P Capital IQ, SEC EDGAR; A-share/HK/US quotes, indicators, financials, valuation, estimates; 8,000+ US-listed filings |
+| Financial news & industry data | Caixin, Xinhua Finance; market news and flashes, company announcements, regulatory policy, bond/fund/futures data, credit-violation records, supply-chain ties |
+| Macroeconomics | World Bank, IMF, OECD, FRED, China's NBS, WHO, FAO; 50+ years, 189 countries; national/provincial/municipal China indicators (GDP, trade, population, exchange rates, CPI, balance of payments) |
+| China standards | National (GB), industry, local, and association standards: IDs, titles, status, details; official full text for some GB and public association standards |
+| Corporate data | Registration, equity chain, legal risk, and related-entity graph for mainland Chinese companies |
+| Academic literature | Millions of papers in physics, mathematics, CS, quantitative finance, economics, including preprints |
+| Legal | Yuandian Legal and other leading legal databases: Chinese laws, regulations, judicial cases; statute search across authority levels; ordinary and authoritative case search |
+| Smart screening | Gildata and other well-known databases: natural-language screening of stocks, funds, and fund managers; macro-industry data, research reports, announcements, news |
+
+#### Billing and limitations
+
+- Data queries are billed per call and consume Kimi Code account credits
+- The plugin provides read-only queries; no write or trading functionality is available
+- Technical indicators and real-time prices are only available during active trading hours
+- AI-generated output is for reference only and does not constitute investment or business advice
+
+<a id="kimi-webbridge"></a>
+
+### Kimi Browser Extension <Badge type="tip" text="v1.11.4" />
+
+Kimi Browser Extension lets AI drive your browser directly: not an emulator, not a crawler, but the browser you use every day, with your login sessions and cookies. AI can open pages, read content, click buttons, fill in forms, and take screenshots just like you do, taking repetitive web operations off your hands. See the [Kimi Browser Extension site](https://www.kimi.com/features/webbridge) for a product overview.
+
+#### Install the browser extension
+
+After installing via `/plugins`, you also need the Kimi Browser Extension in your browser before AI can drive it. There are two ways to install it:
+
+**Option 1: Install from a store (recommended)**
+
+Open the [Chrome Web Store](https://chromewebstore.google.com/detail/kimi-webbridge/fldmhceldgbpfpkbgopacenieobmligc) or [Edge Add-ons](https://microsoftedge.microsoft.com/addons/detail/kimi-webbridge/bnlffdbcfnanfbknnlaflhlhkocccckg) page and click Add.
+
+**Option 2: Install manually**
+
+Use this when you can't reach the stores:
+
+1. [Download the extension package](https://kimi-web-img.moonshot.cn/webbridge/latest/extension/kimi-webbridge-extension.zip) and unzip it
+2. Type `chrome://extensions/` in the address bar to open the extensions page, then turn on **Developer mode** in the top-right corner
+
+   ![Turn on Developer mode](../../media/webbridge-dev-mode.jpeg)
+
+3. Click **Load unpacked** in the top-left corner and select the unzipped `kimi-webbridge-extension` folder
+
+   ![Load the unpacked extension](../../media/webbridge-load-unpacked.jpeg)
+
+4. Once installed, the Kimi Browser Extension icon appears in the browser toolbar. Seeing the icon means the installation succeeded, and AI can start working on web pages for you.
+
+   ![The Kimi Browser Extension icon in the browser toolbar](../../media/webbridge-install-success.jpeg)
+
+#### What you can do
+
+- **Web automation**: Just say what you need, and AI clicks through pages, fills in forms, reads content, and takes screenshots for you
+- **Social trending research**: Automatically browse trending topics on X (Twitter), Weibo, and Xiaohongshu, open the top-liked posts one by one to screenshot and extract key viewpoints, then organize everything into a research library with topic suggestions
+- **Job listing collection**: Filter positions on recruiting sites by keyword, city, and job type, and organize titles, links, companies, salaries, and application methods into a table
+- **Competitive analysis**: Batch-question multiple AI products and collect their answers to build side-by-side comparison reports
+- **Flight price comparison**: Query the same itinerary across multiple travel platforms, record airlines, departure/arrival times, and links sorted by price, and get recommended options
+
+### Kimi Computer Use <Badge type="tip" text="v0.5.4" />
+
+Kimi Computer Use lets AI operate your desktop apps directly, clicking, dragging, scrolling, and typing. The macOS version works silently in the background without taking over your mouse (a few popup actions may still bring an app to the foreground); see [the notes below](#notes-for-the-windows-version) for how the Windows version differs.
+
+#### Authorization (macOS)
+
+The first time you use Kimi Computer Use after installation, it shows an authorization window. Just follow the prompts:
+
+1. Click **Authorize** next to **Accessibility** and **Screen Recording**, and enable both permissions in System Settings: the former lets it perform clicks, typing, and scrolling; the latter lets it read screen content and locate UI elements
+2. Turn on the **Kimi Code** switch under "Connect local agents", then restart Kimi Code for it to take effect
+
+<div style="max-width: 380px; margin: 0 auto;">
+
+![Kimi Computer Use authorization window](../../media/kimi-computer-use-auth.jpeg)
+
+</div>
+
+#### Notes for the Windows version
+
+The Windows version (WinCU) installs differently from the macOS one: run `/plugins install https://cdn.kimi.com/kimi-computer-use-windows/latest/kimi-cu-win-plugin.zip` in Kimi Code, then restart after installation. A few things to know before using it:
+
+- **It may briefly take over your mouse and keyboard**: Unlike the macOS version, the Windows version cannot reliably inject input in the background; it may briefly activate the target window and use your real mouse and keyboard while performing actions
+- **System requirements**: Windows 10 version 1903 (Build 18362) or later, or Windows 11, x64; a real interactive desktop session is required, and Windows Server needs Desktop Experience
+- **No extra permissions needed**: Windows does not require the Accessibility and Screen Recording grants that macOS does
+- **Matching privilege level**: If the target app runs as administrator, KimiCU must run at the same privilege level
+
+#### What you can do
+
+- **Organize and enter information**: Have AI gather scattered information into Notes, spreadsheets, or your note-taking app, instead of typing everything in by hand
+- **Walk through site and app flows**: After changing a page, let AI click through the key flows and screenshot each step to confirm rendering and navigation work
+- **Handle repetitive operations**: Repeatedly opening, copying, pasting, and checking can run silently in the background without taking over your mouse
+- **Run fixed-step tasks**: For flows with clear steps, spell them out and AI follows along; for example, ask AI to open NetEase Cloud Music and play a specific song
+- **Handle software that has no API**: Plenty of professional tools and internal systems have no CLI or API at all; what used to require your own clicking can now be handed to AI, like trimming the first three seconds off a clip in Final Cut Pro and exporting it
+
+::: warning Note
+Don't hand it anything involving money, accounts, or publishing, such as payments and transfers, deleting important files, changing passwords, or posting content. To judge whether a task is suitable, check three things: the result is verifiable, the action is reversible, and the risk of getting it wrong is low.
+:::
+
+## Plugin Manifest
+
+A plugin is a directory or zip file containing a manifest. The manifest can be placed at either of the following locations:
+
+```text
+<plugin_root>/kimi.plugin.json
+<plugin_root>/.kimi-plugin/plugin.json
+```
+
+When both files exist, `kimi.plugin.json` takes precedence.
+
+Example:
+
+```json
+{
+  "name": "kimi-finance",
+  "version": "1.0.0",
+  "description": "Finance data and analysis workflows for Kimi Code CLI",
+  "skills": "./skills/",
+  "systemPromptPath": "./SYSTEM.md",
+  "sessionStart": {
+    "skill": "using-finance"
+  },
+  "interface": {
+    "displayName": "Kimi Finance",
+    "shortDescription": "Market data and financial analysis workflows"
+  }
+}
+```
+
+Supported fields:
+
+| Field | Description |
+| --- | --- |
+| `name` | Required; serves as the plugin id. Must match `[a-z0-9][a-z0-9_-]{0,63}` |
+| `version`, `description`, `keywords`, `author`, `homepage`, `license` | Display metadata |
+| `interface` | Shown in `/plugins`: `displayName`, `shortDescription`, `longDescription`, `developerName`, `websiteURL` |
+| `skills` | One or more `./` paths within the plugin root; if omitted, root `SKILL.md` is the single Skill root |
+| `agents` | One or more `./` paths within the plugin root, pointing to [agent files](./agents.md#custom-agents); if omitted, `agents/` is auto-discovered |
+| `sessionStart.skill` | Loads the specified plugin Skill into the main Agent when a new or resumed session starts |
+| `skillInstructions` | Additional instructions appended whenever a Skill from this plugin is loaded |
+| `systemPrompt` | Inline instructions contributed to the agent's system prompt while the plugin is enabled |
+| `systemPromptPath` | A `./` path to a UTF-8 text file; content is appended after `systemPrompt` when both are present |
+| `mcpServers` | MCP server declarations; enabled by default, can be disabled from `/plugins` |
+| `hooks` | Hook rules run on lifecycle events while enabled; see [Hooks in Plugins](#hooks-in-plugins) |
+| `commands` | One or more `./` paths to a directory or `.md` file; registers the Markdown files inside as slash commands. See [Plugin Slash Commands](#plugin-slash-commands) |
+
+Unsupported runtime fields such as `tools`, `apps`, `inject`, and `configFile` appear as diagnostics and are ignored.
+
+### System-prompt instructions
+
+Plugins inject instructions into the agent's system prompt through the `systemPrompt` and `systemPromptPath` fields. This section covers three parts: writing format and read timing, size limits, and the differences between the two engines.
+
+### Writing format and read timing
+
+Use `systemPrompt` for a short inline instruction, or `systemPromptPath` to keep longer instructions in a file inside the plugin root. If both fields are present, the inline text appears first, followed by the file content. The file content is read when the plugin is installed or reloaded, so edits take effect only after `/plugins reload`. For example:
+
+```json
+{
+  "name": "code-review",
+  "systemPromptPath": "./SYSTEM.md"
+}
+```
+
+The built-in agent prompt includes instructions from enabled plugins automatically. A custom `SYSTEM.md` or agent file owns its template, so include `${plugin_sections}` where plugin-contributed instructions should appear. If the custom template includes `${base_prompt}` and that effective default already contains the plugin block, do not add `${plugin_sections}` again. See [Custom agents and SYSTEM.md](./agents.md#overriding-the-main-agents-system-prompt-with-systemmd) for the complete variable table.
+
+### Size limits
+
+Each field (the inline `systemPrompt` and the `systemPromptPath` file) is limited to 32 KB (UTF-8 bytes): oversized content is ignored and reported in the plugin diagnostics. Across all enabled plugins, one prompt build injects at most 64 KB of instructions; contributions beyond the budget are skipped with a warning, including a single plugin whose inline text and file together exceed that budget.
+
+### Differences between the two engines
+
+System-prompt contributions take effect on every Kimi Code surface: the interactive TUI, `kimi -p`, and `kimi web` all run on the v2 engine.
+
+<details>
+<summary>Instruction refresh behavior under the two engines</summary>
+
+New sessions and newly created agents read the contributions from the plugins currently enabled. An in-flight request keeps its existing system prompt. `/plugins reload` refreshes the plugin skill list and requests prompt rebuilds for live agents; use it when you need the change to converge deliberately before the next turn.
+
+On the v2 engine, installing, enabling, disabling, or removing a plugin updates the catalog immediately, and a later prompt rebuild (for example after compaction or a tool-policy change) may pick up the new sections. The legacy engine keeps each live session's plugin snapshot until `/plugins reload` or a new session. A resumed session starts from its persisted prompt, and later rebuilds follow the engine-specific behavior above. Toggling a plugin's MCP server does not change system-prompt sections.
+
+</details>
+
+## Plugin Slash Commands
+
+Slash commands save a prompt you use often as a `/command`, so you can trigger it by typing the command instead of retyping the whole thing.
+
+Here is a minimal end-to-end example. The plugin's directory structure:
+
+```text
+kimi-finance/
+  kimi.plugin.json
+  commands/
+    report.md
+```
+
+In the manifest (`kimi.plugin.json`), the `commands` field points to where the command files live:
+
+```json
+{
+  "name": "kimi-finance",
+  "version": "1.0.0",
+  "commands": "./commands/"
+}
+```
+
+The command file `commands/report.md`. The block between the two `---` lines at the top is frontmatter (metadata describing the command); everything below is the prompt sent to the Agent:
+
+```markdown
+---
+description: Pull and summarize a stock's latest financials
+---
+
+Pull the latest financials for $ARGUMENTS and summarize revenue, profit, and key risks.
+```
+
+After installing and enabling the plugin, type this in the chat:
+
+```text
+/kimi-finance:report TSLA
+```
+
+Kimi replaces `$ARGUMENTS` in the body with `TSLA`, then runs the prompt. The three details below cover each step.
+
+### Declaring Commands (the `commands` field)
+
+`commands` takes a single `./` path or an array of paths, each pointing to a directory or `.md` file inside the plugin root:
+
+- Pointing at a **directory**: collects every `.md` file under it recursively; each becomes one command.
+- Pointing at a **single `.md` file**: registers just that one.
+- Pointing at a non-`.md` file or a missing path: appears as a diagnostic (shown in the `/plugins` panel) and is ignored.
+
+### Writing a Command File
+
+A command file has two parts: an optional **frontmatter** (the metadata between the two `---` lines at the top, where you set `name` and `description`) and the **body** (the prompt after the `---`). When a field is omitted, it falls back as follows:
+
+- `name` (the command name): derived from the file's path relative to the declared `commands` path (without `.md`, using `/` separators), e.g. `commands/frontend/component.md` → `frontend/component`. A `name` set in the frontmatter takes precedence.
+- `description` (shown in the command list): the first non-empty line of the body (truncated past 240 characters); if the body is empty too, `No description provided.` is shown.
+
+### Running Commands and Passing Arguments
+
+Commands are prefixed with the plugin id (their namespace) and registered as `<plugin>:<command>`, so the command above is actually `/kimi-finance:report`. This keeps same-named commands from different plugins from colliding.
+
+Whatever you type after the command replaces `$ARGUMENTS` in the body (above, `TSLA` replaces `$ARGUMENTS`). If the body has no `$ARGUMENTS` but you pass arguments anyway, they are not dropped; they are appended to the end of the body as `ARGUMENTS: <what you typed>`.
+
+## Skills and Session Start
+
+Plugin Skills use the same `SKILL.md` format as ordinary [Agent Skills](./skills.md). A typical directory structure:
+
+```text
+my-plugin/
+  kimi.plugin.json
+  skills/
+    using-my-plugin/
+      SKILL.md
+    another-workflow/
+      SKILL.md
+```
+
+`sessionStart.skill` loads a plugin Skill into the main Agent at session start, making it suitable for initialization instructions, workflow rules, or mapping terminology from other tools to Kimi Code CLI. It only injects text; it does not execute code.
+
+Regardless of how a Skill is loaded (`sessionStart.skill`, `/skill:<name>`, or automatic model invocation), `skillInstructions` appears alongside that plugin's Skill.
+
+## Plugin Agents
+
+A plugin can ship custom agents: declare one or more `./` directories in the manifest's `agents` field (or simply place an `agents/` directory under the plugin root). The agent files inside use the same format as [custom agents](./agents.md#custom-agents) and, while the plugin is enabled, are discovered automatically and can be delegated to as sub-agents by the main Agent.
+
+```text
+my-plugin/
+  kimi.plugin.json
+  agents/
+    reviewer.md
+```
+
+Plugin agents rank below every other file source: on a name collision, user-level, extra, project-level, and `--agent-file` agents all win over the plugin-provided one, and replacing a built-in agent still requires an explicit `override: true` in the frontmatter. After installing, enabling, disabling, or removing a plugin, the agent list refreshes in a new session (or on `/reload`); on the v2 engine the live session also refreshes after `/plugins reload`.
+
+## MCP Servers in Plugins
+
+When a plugin needs real tool capabilities, it can declare `mcpServers` in its manifest, reusing the [MCP](./mcp.md) schema.
+
+Stdio server (local command):
+
+```json
+{
+  "mcpServers": {
+    "finance": {
+      "command": "uvx",
+      "args": ["kimi-finance-mcp"]
+    }
+  }
+}
+```
+
+HTTP server (remote service):
+
+```json
+{
+  "mcpServers": {
+    "docs": {
+      "url": "https://example.com/mcp"
+    }
+  }
+}
+```
+
+For stdio servers, `command` can be a command on `PATH` or a path starting with `./` within the plugin root directory. `cwd` likewise must start with `./` and be within the plugin root directory; otherwise the server is ignored.
+
+Plugin MCP servers start after `/reload` or in new sessions. To enable or disable a server:
+
+```sh
+/plugins mcp disable kimi-finance finance
+/reload
+
+/plugins mcp enable kimi-finance finance
+/reload
+```
+
+## Hooks in Plugins
+
+A plugin can declare hook rules in its manifest that run on lifecycle events while the plugin is enabled. Each entry uses the same fields as a [`[[hooks]]` rule in `config.toml`](./hooks.md#configuration) (`event`, `matcher`, `command`, `timeout`):
+
+```json
+{
+  "hooks": [
+    {
+      "event": "PreToolUse",
+      "matcher": "Bash",
+      "command": "node ./hooks/check-bash.mjs",
+      "timeout": 5
+    }
+  ]
+}
+```
+
+Plugin hooks reuse the same mechanism as global hooks. See [Hooks](./hooks.md) for the event list, the stdin JSON payload, and how exit codes and return values affect the main flow. The differences are:
+
+- A plugin's hooks are active only while the plugin is **enabled**; disabling the plugin stops its hooks.
+- Each hook runs with its working directory set to the plugin root, so `command` can use `./` paths inside the plugin.
+- The hook process receives two extra environment variables: `KIMI_CODE_HOME` and `KIMI_PLUGIN_ROOT` (the plugin root directory).
+
+Installing a plugin never runs its hooks by itself. They only fire when their matching event occurs while the plugin is enabled.
+
+## Security Model
+
+Plugins have a limited loading scope. The following operations do not occur during installation or session startup:
+
+- Command-type plugin tools and legacy tool runtimes are not executed
+- All paths must remain within the plugin root directory after symbolic link resolution
+- MCP servers of enabled plugins start after `/reload` or in new sessions and can be disabled at any time from `/plugins`
+- Broken manifests or unsafe paths appear in `/plugins info <id>` diagnostics and do not affect other sessions
+
+## Next steps
+
+- [Agent Skills](./skills.md) — Learn the `SKILL.md` format and write Skills that ship with your plugins
+- [Custom agents](./agents.md) — Agent file format and directory-scope precedence
+- [MCP](./mcp.md) — The schema that MCP server declarations in plugins reuse
+- [Hooks](./hooks.md) — The global hook mechanism that plugin hooks reuse

docs/en/customization/skills.md

@@ -0,0 +1,151 @@
+# Agent Skills
+
+Agent Skills are a lightweight mechanism for extending model capabilities in Kimi Code CLI. A Skill is a Markdown document with YAML frontmatter that describes a specialized area of knowledge or a workflow: a project's code style guidelines, a PR review process, or a commit message format.
+
+Compared to pasting the same instructions into a prompt every time, Skills offer the advantage of keeping content in a file, enabling reuse across projects and teams, allowing instant loading via a slash command, and letting the model invoke them automatically when needed.
+
+## Creating a Skill
+
+Skill files must be placed in a [known scan directory](#skill-locations). Two file structures are supported:
+
+- **Directory form (recommended)**: Create a subdirectory under the skills directory with the main file named `SKILL.md`, and place scripts, reference material, and other supporting files alongside it.
+- **Flat form**: Skip the subdirectory and drop a single `.md` file directly into the skills directory — handy for simple Skills that need no supporting files.
+
+Both structures register a Skill; they differ only in how the files are organized:
+
+```text
+skills/
+├── review-pr/              # Directory form → Skill name review-pr
+│   ├── SKILL.md            # Main file
+│   └── checklist.md        # Supporting file, referenced via ${KIMI_SKILL_DIR}
+└── commit.md               # Flat form → Skill name commit
+```
+
+How the Skill name is derived:
+
+- Directory form: from the required frontmatter `name` field (see the table below); by convention the subdirectory carries the same name — `review-pr/SKILL.md` with `name: review-pr` registers as `review-pr`.
+- Flat form: `name` may be omitted, falling back to the filename without the `.md` extension — `commit.md` registers as `commit`. The extension is stripped only from the registered Skill name; the file on disk must keep its `.md` extension to be picked up by the scanner, so don't actually create an extensionless `commit` file.
+- When both `<name>/SKILL.md` and `<name>.md` exist in the same directory, the directory form wins and the flat file is ignored.
+
+Two limitations of the flat form:
+
+- Only `.md` files placed directly at the top level of a skills directory are recognized; loose `.md` files inside subdirectories (other than `SKILL.md`) are not treated as Skills.
+- A flat Skill has no directory of its own, so `${KIMI_SKILL_DIR}` points at the skills directory itself — switch to the directory form whenever the Skill needs supporting files.
+
+### File Format
+
+`SKILL.md` consists of two parts: YAML frontmatter and a Markdown body:
+
+```markdown
+---
+name: code-style
+description: Project code style guidelines defining naming, indentation, comments, and file organization
+type: prompt
+whenToUse: When the user asks me to write, modify, or review project source code
+disableModelInvocation: false
+arguments:
+  - target
+  - mode
+---
+
+Please handle code according to the following guidelines:
+
+- Use 2-space indentation
+- Variable names use `camelCase`, type names use `PascalCase`
+- Public functions must have TSDoc comments
+- Lines must not exceed 100 characters
+```
+
+### Frontmatter Fields
+
+| Field | Description |
+| --- | --- |
+| `name` | Skill name (case-insensitive). Required in directory-form `SKILL.md`; flat `.md` falls back to the filename without the `.md` extension |
+| `description` | One-line summary the model uses to decide when to invoke. Required in directory-form `SKILL.md`; flat `.md` falls back to the first non-empty body line (up to 240 characters) |
+| `type` | Skill type: `prompt` (default), `inline` (same as `prompt`), `flow` (manual invocation only). Other values are skipped |
+| `whenToUse` | Description of when the Skill should be triggered. Also accepts `when-to-use` and `when_to_use` |
+| `disableModelInvocation` | If `true`, blocks automatic model invocation. Also accepts `disable-model-invocation`, `disable_model_invocation` |
+| `arguments` | Named parameters; a string array or whitespace-separated string (e.g., `arguments: target mode`). Once declared, readable in the body as `$<name>` |
+
+::: warning Note
+In a directory-form `SKILL.md`, both `name` and `description` **must** be explicitly provided. Omitting either one will cause parsing to fail.
+:::
+
+### Body Placeholders
+
+Before the body is sent to the model, a small set of placeholders are expanded:
+
+- `$ARGUMENTS`: The full raw argument string passed at invocation
+- `$ARGUMENTS[0]`, `$ARGUMENTS[1]` and shorthand `$0`, `$1`: Positional arguments after whitespace tokenization (zero-indexed)
+- `$<name>`: Named parameters declared in `arguments`
+- `${KIMI_SKILL_DIR}`: The directory containing the current Skill file
+
+Positional arguments support single and double quoting, so in `/skill:commit "fix login" patch`, `$0` expands to `fix login`. If the body contains no argument placeholders, text passed at invocation is appended to the end of the body as `\n\nARGUMENTS: <text>`.
+
+## Skill Locations
+
+Kimi Code CLI scans four tiers by scope; more specific scopes take higher priority: **Project > User > Extra > Built-in**
+
+**User level** (applies to all projects):
+- `$KIMI_CODE_HOME/skills/` (default: `~/.kimi-code/skills/`)
+- `~/.agents/skills/`
+
+The Kimi-specific user Skill directory moves with `KIMI_CODE_HOME`, so isolated data roots also get isolated Kimi-specific Skills. The generic `~/.agents/skills/` directory stays under the real OS home so it can be shared across tools.
+
+**Project level** (project root = the nearest directory containing `.git`, searching upward from the working directory):
+- `.kimi-code/skills/`
+- `.agents/skills/`
+
+**Extra directories**: Declared via `extra_skill_dirs` at the top level of `config.toml`:
+
+```toml
+extra_skill_dirs = ["~/team-skills", ".agents/team-skills"]
+```
+
+**Built-in Skills** are distributed with the CLI and have the lowest priority. They provide out-of-the-box workflows for common tasks: configuring MCP servers, customizing the TUI theme, and editing config files. See [Built-in skill commands](../reference/slash-commands.md#built-in-skill-commands) for the full list. Those describing Kimi Code itself can be turned off with the top-level [`builtin_product_skills`](../configuration/config-files.md#top-level-fields) field.
+
+## Invoking a Skill
+
+Users can invoke a Skill manually with a slash command:
+
+```
+/skill:code-style
+/skill:git-commits fix concurrency issue in login endpoint
+```
+
+The model can also invoke a Skill automatically based on `description` and `whenToUse` (unless `disableModelInvocation` is `true` or `type` is `flow`). Skill invocations allow up to 3 levels of nesting; beyond that they are terminated.
+
+## Complete Example
+
+```markdown
+---
+name: review-pr
+description: Review a Pull Request according to team standards and produce a structured review report
+type: prompt
+whenToUse: When the user asks me to review a PR, inspect code changes, or evaluate commit quality
+arguments:
+  - pr_ref
+---
+
+Please review the PR the user specified: $pr_ref
+
+1. Fetch and read the full diff for `$pr_ref`.
+2. Check each of the following items:
+   - Whether corresponding test cases are included
+   - Whether public API documentation has been updated
+   - Whether new dependencies have been introduced; if so, state the reason
+   - Whether error handling covers edge cases
+3. Refer to the checklist in the same directory: `references/checklist.md`
+4. Produce a review report containing:
+   - Overall conclusion (approve / request changes / comment)
+   - Required changes (blocking)
+   - Suggested improvements (non-blocking)
+   - Noteworthy positives
+```
+
+Save this as `$KIMI_CODE_HOME/skills/review-pr/SKILL.md` (or `~/.kimi-code/skills/review-pr/SKILL.md` when `KIMI_CODE_HOME` is unset), place the checklist at `references/checklist.md` in the same directory, and after starting a new session you can invoke it with `/skill:review-pr #1234`, where `#1234` is expanded into `$pr_ref`.
+
+## Next steps
+
+- [Plugins](./plugins.md) — Package Skills into installable units to share with your team
+- [Agents and sub-agents](./agents.md) — How Skills influence sub-agent behavior

docs/en/customization/themes.md

@@ -0,0 +1,116 @@
+# Custom Themes
+
+Kimi Code CLI can use a built-in color scheme or a custom JSON theme file. Custom files live in the themes directory and appear in `/theme` alongside the built-in choices.
+
+## Built-in color tokens
+
+Custom themes can override the tokens below. The `dark` and `light` columns show the built-in values; `auto` resolves to one of those palettes at startup, and falls back to `dark` when terminal background detection is unavailable.
+
+| Token | `dark` | `light` | What it controls |
+| --- | --- | --- | --- |
+| `primary` | `#4FA8FF` | `#1565C0` | The most-used color. Links, inline code, selected items in dialogs, focus borders, badges, spinners |
+| `accent` | `#5BC0BE` | `#00838F` | Secondary highlight. Approval `▶` prefix, device-code box, image placeholder, panes, registry import |
+| `text` | `#E0E0E0` | `#1A1A1A` | Body text. Dialog bodies, todo titles, footer model label, Markdown headings, list bullets |
+| `textStrong` | `#F5F5F5` | `#1A1A1A` | Emphasized / bold text. Input dialogs, status messages |
+| `textDim` | `#888888` | `#454545` | Secondary, dimmed text. Thinking, hints, completed todos, Markdown quotes, footer status bar |
+| `textMuted` | `#6B6B6B` | `#5F5F5F` | Faintest text. Counters, scroll info, Markdown link URLs, code-block borders |
+| `border` | `#5A5A5A` | `#737373` | Pane and editor borders, Markdown horizontal rule |
+| `borderFocus` | `#E8A838` | `#92660A` | Focus / attention border, currently only the approval panel |
+| `success` | `#4EC87E` | `#0E7A38` | Success state. `✓`, "enabled", completed |
+| `warning` | `#E8A838` | `#92660A` | Warning state. Ask When Needed/Never Ask badges, stale markers, Plan mode hint |
+| `error` | `#E85454` | `#B91C1C` | Error state. Error messages, failed tool output |
+| `diffAdded` | `#4EC87E` | `#0E7A38` | Diff added lines |
+| `diffRemoved` | `#E85454` | `#B91C1C` | Diff removed lines |
+| `diffAddedStrong` | `#7AD99B` | `#0E7A38` | Diff intra-line changed words, added and bold |
+| `diffRemovedStrong` | `#F08585` | `#B91C1C` | Diff intra-line changed words, removed and bold |
+| `diffGutter` | `#6B6B6B` | `#737373` | Diff line-number gutter |
+| `diffMeta` | `#888888` | `#5F5F5F` | Diff meta / hunk headers |
+| `roleUser` | `#FFCB6B` | `#9A4A00` | User message bullet and text, skill-activation name |
+| `shellMode` | `#BD93F9` | `#7C3AED` | Shell mode (`!`) prompt, editor border, and the echoed `$ command` line |
+
+## Use the custom-theme skill
+
+You do not need to write the JSON by hand. Run the built-in `/custom-theme [extra text]` skill command to enter the custom-theme workflow; the skill can choose colors, write the file under `~/.kimi-code/themes/`, validate the hex values, and tell you how to apply it.
+
+Example invocations:
+
+- `/custom-theme Create a warm dark theme with amber accents.`
+- `/custom-theme Make a light theme based on Solarized, but keep errors easy to see.`
+- `/custom-theme Tweak my ember theme so diffs have higher contrast.`
+
+After activation, the skill usually asks whether you want a light or dark base, what mood or palette you prefer, and whether you have exact colors to include. If you use it to edit an existing theme, make sure it reads and backs up the file before overwriting it.
+
+## Create a theme
+
+Add a `.json` file to the themes directory:
+
+- `~/.kimi-code/themes/`
+- or `$KIMI_CODE_HOME/themes/` when the `KIMI_CODE_HOME` environment variable is set
+
+Create the directory if it does not exist. **The filename is the theme name**: `ember.json` appears in `/theme` as `Custom: ember`.
+
+A minimal theme only sets the colors you want to change; the rest fall back to the **base palette** (`dark` by default):
+
+```json
+{
+  "name": "ember",
+  "colors": {
+    "primary": "#83A598",
+    "accent": "#FE8019"
+  }
+}
+```
+
+Fields:
+
+- `name` (required): the theme identifier.
+- `displayName` (optional): a human-readable name.
+- `base` (optional): the built-in palette that unspecified tokens inherit, `"dark"` (default) or `"light"`. Set `"base": "light"` when you are building a **light** theme so the tokens you leave out stay readable on a light background (otherwise they fall back to the dark palette).
+- `colors` (optional): the color tokens to override, each a 6-digit hex value (e.g. `#FE8019`).
+
+Use the token names from [Built-in color tokens](#built-in-color-tokens). Any token you omit falls back to the selected base palette, so partial themes are fine:
+
+```json
+{
+  "name": "just-blue",
+  "colors": {
+    "primary": "#3B82F6",
+    "roleUser": "#3B82F6"
+  }
+}
+```
+
+## Select a theme
+
+Two ways:
+
+1. **The `/theme` command** (recommended): opens the theme picker, where custom themes appear as `Custom: <filename>`. The picker **re-scans the themes directory every time it opens**, so a theme file you just added shows up **without a restart**.
+2. **[`tui.toml`](../configuration/config-files.md#tuitoml)**: set `theme` to your theme name:
+
+   ```toml
+   # ~/.kimi-code/tui.toml
+   theme = "ember"
+   ```
+
+## What happens on errors
+
+Custom themes are designed to never get in your way:
+
+- **An invalid color value** (not `#` followed by 6 hex digits): that one entry is silently skipped and falls back to the selected base palette; the rest of the colors still apply.
+- **An unrecognized token**: ignored, with no effect on other colors.
+- **A missing custom theme file or malformed JSON**: silently falls back to the built-in `dark` palette. It does not retry `auto`.
+
+## Editing the active theme
+
+If you edit the theme file that is **currently active**, the change is not reloaded automatically. To apply the new colors:
+
+- run `/reload-tui`, which reloads `tui.toml` and re-applies the current theme (including re-reading the theme file); or
+- switch to another theme in `/theme` and back.
+
+::: warning Note
+Re-selecting the **same** theme in `/theme` does not reload it (you get a "Theme unchanged" message). To reload changes to the active theme, use one of the two methods above.
+:::
+
+## Next steps
+
+- [Configuration files](../configuration/config-files.md#tuitoml) — Full field reference for `tui.toml`, including the `theme` option

docs/en/guides/getting-started.md

@@ -0,0 +1,175 @@
+# Getting started
+
+## What is Kimi Code CLI
+
+Kimi Code CLI is an AI agent that runs in the terminal, helping you carry out software development tasks and day-to-day terminal operations — reading and modifying code, running shell commands, searching files, fetching web pages, and autonomously planning and adjusting its next steps based on feedback as it works.
+
+It fits scenarios such as:
+
+- **Writing and modifying code**: implementing new features, fixing bugs, completing refactors
+- **Understanding a project**: exploring an unfamiliar codebase and answering questions about architecture and implementation
+- **Automating tasks**: batch-processing files, running builds and tests, chaining multiple scripts together
+
+The CLI is written in TypeScript, distributed via npm, and runs on Node.js.
+
+## Installation
+
+Two installation options are available: the official install script (recommended, no pre-installed Node.js required) and a global npm install.
+
+::: tip Before you install
+Kimi Code CLI is a fully interactive TUI application. For the best visual experience, run it in a terminal with true-color and ligature support, such as [Kitty](https://sw.kovidgoyal.net/kitty/) or [Ghostty](https://ghostty.org/).
+:::
+
+### Install script (recommended)
+
+::: code-group
+
+```sh [macOS / Linux]
+curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash
+```
+
+```powershell [Windows (PowerShell)]
+irm https://code.kimi.com/kimi-code/install.ps1 | iex
+```
+
+:::
+
+> On Windows, install [Git for Windows](https://gitforwindows.org/) before first launch. Kimi Code CLI uses the bundled Git Bash as its shell environment; if Git Bash is installed in a custom location, set `KIMI_SHELL_PATH` to the absolute path of `bash.exe`.
+
+The script automatically downloads the latest release, verifies the checksum, and places the `kimi` executable on your `PATH`.
+
+### npm installation
+
+Requires Node.js 22.19.0 or later:
+
+```sh
+node --version
+```
+
+::: code-group
+
+```sh [npm]
+npm install -g @moonshot-ai/kimi-code
+```
+
+```sh [pnpm]
+pnpm add -g @moonshot-ai/kimi-code
+```
+
+:::
+
+## First launch
+
+Move into your project directory and run `kimi` to start the interactive UI:
+
+```sh
+cd your-project
+kimi
+```
+
+To run a single instruction without entering the interactive UI, use `-p`:
+
+```sh
+kimi -p "Take a look at this project's directory structure"
+```
+
+To resume the previous session, add `-c`:
+
+```sh
+kimi -c
+```
+
+On first launch you need to configure an API source. In the interactive UI, enter `/login` to begin the login flow:
+
+```
+/login
+```
+
+`/login` opens a platform selector supporting two options:
+
+- **Kimi Code (OAuth)** — device-code flow; open the link on any device, sign in, and enter the code to authorize
+- **Kimi Platform API key** — enter an API key from `platform.kimi.com` or `platform.kimi.ai`
+
+To sign out, enter `/logout` to clear the current credentials.
+
+::: tip Using other AI providers
+If you want to connect Anthropic, OpenAI, Google, or other providers, edit `~/.kimi-code/config.toml` directly to configure the API key. See [Providers and models](../configuration/providers.md) for details. For the full reference of all config options, see [Configuration files](../configuration/config-files.md), [Environment variables](../configuration/env-vars.md), and [Configuration overrides](../configuration/overrides.md).
+:::
+
+## Your first conversation
+
+Once logged in, describe a task in natural language. A good starting point is to let Kimi Code CLI familiarize itself with the project:
+
+```
+Take a look at this project's directory structure and briefly describe what each directory is for.
+```
+
+Kimi Code CLI automatically calls file-reading, search, and other tools to browse the relevant content before responding. Read-only operations are executed automatically by default without requiring confirmation. For operations that modify files or run shell commands, it asks for your confirmation before proceeding.
+
+You can also describe a more concrete task directly:
+
+```
+Add a function in src/utils that converts any string to kebab-case, and add a unit test for it.
+```
+
+Kimi Code CLI plans the steps, modifies the code, runs the tests, and tells you what it did at each step.
+
+::: tip Not sure what to do? Type `/help`
+Type `/help` at any time to open the built-in command and keyboard shortcut panel. Use `↑`/`↓` to browse and `Esc` to close. To exit, type `/exit`, press `Ctrl-C` twice, or press `Ctrl-D` with the input box empty.
+:::
+
+## Common commands and keyboard shortcuts
+
+For a first-time user, the following is all you need to know:
+
+**Session commands**
+
+| Command | Description |
+| --- | --- |
+| `/new` | Start a new session, clearing the current context |
+| `/sessions` | Browse session history and choose one to resume |
+| `/model` | Switch the current model |
+| `/compact` | Manually compress the context to free up tokens |
+| `/fork` | Fork the current session into an independent copy with full history (you stay in the current session) |
+
+**Most-used keyboard shortcuts**
+
+| Shortcut | Description |
+| --- | --- |
+| `Esc` | Interrupt streaming output / close a popup |
+| `Ctrl-C` | Interrupt output; press twice while idle to exit |
+| `Shift-Tab` | Toggle Plan mode |
+| `Ctrl-S` | Inject a message mid-stream without waiting for the current response to finish |
+| `Ctrl-O` | Collapse / expand tool output and compaction summaries |
+
+For the full list, type `/help` or visit [Slash commands reference](../reference/slash-commands.md) and [Keyboard shortcuts](../reference/keyboard.md).
+
+## Where data is stored
+
+Kimi Code CLI stores its local data under `~/.kimi-code/` by default — config files, session records, logs, and the update cache. To move it elsewhere, point to a new path via the `KIMI_CODE_HOME` environment variable. For the full directory layout, see [Data locations](../configuration/data-locations.md) and [Environment variables](../configuration/env-vars.md).
+
+## Upgrade and uninstall
+
+After installation, verify that the executable is ready:
+
+```sh
+kimi --version
+```
+
+**Upgrade**: run `kimi upgrade` — the CLI checks for the latest version and presents update options. Choose `Install update now` to upgrade based on your current install source. You can also upgrade directly via the package manager:
+
+```sh
+npm install -g @moonshot-ai/kimi-code@latest
+```
+
+**Uninstall**: if you installed via the script, delete the `kimi` executable. If you installed via npm:
+
+```sh
+npm uninstall -g @moonshot-ai/kimi-code
+```
+
+## Next steps
+
+- [Interaction and input](./interaction.md) — input box operations, approval flow, Plan mode, and Ask When Needed mode explained
+- [Sessions and context](./sessions.md) — resuming sessions, compressing context, exporting sessions
+- [Common use cases](./use-cases.md) — prompt examples for typical tasks

docs/en/guides/ides.md

@@ -0,0 +1,96 @@
+# Using Kimi Code CLI in IDEs
+
+Kimi Code CLI supports integration into IDEs via the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/), letting you use AI-assisted coding directly inside your editor.
+
+## Prerequisites
+
+Before configuring your IDE, make sure Kimi Code CLI is installed and you have completed the login setup.
+
+The ACP server is exposed as the `kimi acp` subcommand. The IDE launches it as a child process and communicates over stdin/stdout using JSON-RPC. Each time the IDE creates a session, the CLI reuses its existing authentication state — no need to log in again.
+
+::: tip Path note
+Child processes launched from an IDE GUI on macOS typically do **not** inherit the terminal shell's `PATH`. If `kimi` is not in a system directory like `/usr/local/bin`, use the absolute path in your IDE configuration. Run `which kimi` in a terminal to find the active path.
+:::
+
+## Using Kimi Code CLI in Zed
+
+[Zed](https://zed.dev/) is a modern editor with native ACP support.
+
+Add the following to Zed's config file at `~/.config/zed/settings.json`:
+
+```json
+{
+  "agent_servers": {
+    "Kimi Code CLI": {
+      "type": "custom",
+      "command": "kimi",
+      "args": ["acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+Configuration fields:
+
+- `type`: fixed value `"custom"`
+- `command`: path to the Kimi Code CLI executable. If `kimi` is not on `PATH`, use the full path (e.g. `/Users/you/.local/bin/kimi`).
+- `args`: startup arguments. The `acp` subcommand switches the CLI into ACP mode.
+- `env`: additional environment variables; usually leave this empty. Zed injects a default environment automatically.
+
+After saving, open a new conversation in Zed's Agent panel and it will launch a `Kimi Code CLI` ACP subprocess using the configuration above. MCP servers declared in Zed's `agent_servers` section are also forwarded to the kimi side via the ACP protocol.
+
+## Using Kimi Code CLI in JetBrains IDEs
+
+JetBrains IDEs (IntelliJ IDEA, PyCharm, WebStorm, etc.) support ACP through the AI chat plugin.
+
+If you do not have a JetBrains AI subscription, you can enable `llm.enable.mock.response` in the Registry to access the AI chat panel in ACP-only scenarios. Press Shift twice and search for "Registry" to open it.
+
+In the AI chat panel menu, click **Configure ACP agents** and add the following configuration:
+
+```json
+{
+  "agent_servers": {
+    "Kimi Code CLI": {
+      "command": "~/.local/bin/kimi",
+      "args": ["acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+JetBrains is strict about the `command` field — always use an **absolute path**, which you can get by running `which kimi` in a terminal. After saving, `Kimi Code CLI` will appear in the AI chat's agent selector.
+
+## Using Kimi Code CLI in Paseo
+
+[Paseo](https://paseo.sh/) is a self-hosted orchestrator that runs and supervises agent CLIs from your desktop, web, and mobile. It connects to Kimi Code CLI over ACP, the same way an IDE does.
+
+Pick **Kimi Code CLI** from Paseo's built-in ACP provider catalog, or add a custom provider in `~/.paseo/config.json`:
+
+```json
+{
+  "agents": {
+    "providers": {
+      "kimi": {
+        "extends": "acp",
+        "label": "Kimi Code CLI",
+        "command": ["kimi", "acp"]
+      }
+    }
+  }
+}
+```
+
+Paseo's generic ACP adapter does not drive the login flow, so complete the terminal login first (see [Prerequisites](#prerequisites)) — otherwise session creation fails with `Authentication required`.
+
+## Troubleshooting
+
+- **Session disconnects immediately / IDE shows "agent exited"**: usually a wrong `command` path or a missing login. Run `kimi acp` in a terminal first to verify — if it blocks waiting for stdin, the CLI itself is fine and the problem is in the IDE configuration; if it exits immediately with an error, follow the error message (most commonly you need to run `/login`).
+- **IDE shows "auth required"**: the CLI has no usable authentication token. Exit the IDE, run `kimi` in a terminal to complete login, then restart the IDE.
+- **MCP tools not visible**: check the [`kimi acp` reference](../reference/kimi-acp.md) capability table to confirm that the MCP transport type configured in your IDE is supported. The Kimi Code CLI ACP server currently supports `http`, `stdio`, and `sse` transports; `acp` transport MCP servers are silently dropped and a warning is written to the log.
+
+## Next steps
+
+- [kimi acp reference](../reference/kimi-acp.md) — ACP capability matrix and method coverage details
+- [kimi command reference](../reference/kimi-command.md) — full subcommand list

docs/en/guides/interaction.md

@@ -0,0 +1,147 @@
+# Interaction and input
+
+Kimi Code CLI runs as an interactive TUI (terminal user interface) built around three components: the input box, the conversation view, and the status bar. This page covers how to enter text, paste media, navigate the approval flow, and switch between modes.
+
+## Input box basics
+
+The input box accepts free-form text. Press `Enter` to send, or `Shift-Enter` / `Ctrl-J` to insert a newline. When the input box is empty, press `↑` / `↓` to browse the input history for the current working directory, including previous shell commands.
+
+**Exiting the CLI**: press `Ctrl-D` with the input box empty, press `Ctrl-C` twice while idle, or type `/exit`. Pressing `Ctrl-C` or `Esc` during streaming output interrupts the current turn — it does not exit the program.
+
+## Pasting images and video
+
+Kimi Code CLI supports pasting images and video directly into the input box, so you can discuss screenshots, UI mockups, architecture diagrams, or code demos without uploading or converting files first.
+
+**Video input is a distinctive Kimi Code capability** — you can paste a video clip and have the model analyze its content, UI flow, or code walkthrough.
+
+How to paste:
+
+- **macOS / Linux**: `Ctrl-V`
+- **Windows**: `Alt-V`
+
+After pasting, the input box shows a placeholder that you can edit like normal text; on submit, the placeholder is replaced with the actual content. A plain-text clipboard falls back to ordinary paste. Media support depends on the current model's multimodal capabilities (`image_in` / `video_in`); it is enabled by default when you are logged in to a Kimi Code account.
+
+If a conversation accumulates more than 20 MB of media, the oldest images and videos are omitted from requests automatically, and a warning is shown when this happens.
+
+## Slash commands
+
+Type `/` to open the completion menu — it filters as you type, `Esc` closes it, and unmatched input goes to the agent as a regular message. Common commands:
+
+| Command | Action |
+| --- | --- |
+| `/new` | Start a new session |
+| `/sessions` | Browse and resume past sessions |
+| `/compact` | Compact the current session's context |
+| `/undo` | Undo recent prompts |
+| `/model` | Switch the model used in the current session |
+| `/plan` | Toggle Plan mode (plan first, then execute) |
+| `/yolo` | Open the permission mode list with Ask When Needed preselected (routine edits and commands run automatically) |
+| `/goal` | Start or manage goal mode |
+| `/help` | Show all commands |
+
+Active [Agent Skills](../customization/skills.md) are also registered as slash commands (e.g. `/skill:<name>`). For the full list, see [Slash commands reference](../reference/slash-commands.md).
+
+## File references
+
+Type `@` to trigger file-path completion; the selected path is inserted in relative form, and the agent loads the file content directly when it reads your message.
+
+- **Where it works**: both git and non-git directories; hidden paths are included, `.git` is excluded
+- **Folder suggestions**: end with `/`, so you can keep completing paths inside them
+- **Fallback**: while the fast search helper is still downloading, Kimi Code falls back to a basic filesystem scan
+
+> `@` references and slash commands are two separate mechanisms: `@` gives the agent file context, while `/` invokes built-in features or Skills.
+
+## Approval flow
+
+When the agent calls a tool that has side effects — modifying files, running commands — the TUI displays an approval panel for your confirmation.
+
+- **Approve**: select with the arrow keys and press `Enter`, or press `1` / `2` / `3` to choose directly
+- **Reject**: `Esc`, `Ctrl-C`, or `Ctrl-D`
+- **Approve for this session**: auto-approves the same kind of call for the rest of the session
+- **Permanent rules**: add allow / deny entries in [Configuration files](../configuration/config-files.md#permission)
+
+Approvals are not triggered for regular tool calls in Ask When Needed mode, nor for writes to plan files in Plan mode.
+
+### The three permission modes
+
+**Always Ask mode** (formerly Manual) is the default: read-only operations run automatically, while every other action — editing files, running commands — asks for your confirmation one by one. Use it when you want full control over every change.
+
+**Ask When Needed mode** (formerly YOLO), enabled with `/yolo`, auto-approves regular tool calls, making it suitable for batch tasks you know are safe. It still asks before sensitive actions — accessing sensitive files such as `.env` or SSH keys, running dangerous commands such as `shutdown` or `rm -rf`, or exiting Plan mode — and the agent can still ask you questions.
+
+**Never Ask mode** (formerly Auto), enabled with `/auto`, is the fully unattended mode: every tool approval is handled automatically, including sensitive files and plan exits, and the agent never asks you questions — it decides everything on its own. The built-in dangerous-command guard asks for your confirmation before commands such as `shutdown`, `reboot`, or `rm -rf` in Always Ask and Ask When Needed mode; in Never Ask mode these commands run without interruption.
+
+
+## Mode switching
+
+### Plan mode
+
+In Plan mode the agent first outputs an action plan and waits for your approval before modifying any files — useful for complex or high-risk tasks.
+
+- Toggle: `Shift-Tab` or `/plan`
+- Clear the current plan: `/plan clear` (only while idle)
+
+After producing a plan the agent pauses for your review — you can approve it, reject it, or ask for revisions. Exiting Plan mode requires your confirmation even if Ask When Needed mode is also active. Never Ask mode is the exception: plan exits are approved automatically and marked as "Auto-approved" in the transcript.
+
+### Shell mode
+
+Shell mode lets you run terminal commands without leaving the conversation. The command output is written into the conversation context, so the agent can see the results in later turns.
+
+- Enter: type `!` in an empty input box, or paste a command that starts with `!`.
+- Exit: press `Backspace` or `Esc` in an empty input box; submitting a command also returns you to normal mode automatically.
+- Run in background: while a command is running, press `Ctrl+B` to move it to a background task.
+- Recall previous commands: with the input box empty in shell mode, press `↑` to browse earlier shell commands; recalling one keeps you in shell mode so it runs as a command again.
+- Long output: when a finished command's output is too long, the output card collapses automatically; press `Ctrl-O` to expand or collapse it together with tool output.
+
+In shell mode the input box shows a `!` prompt on the left and the border turns violet. For example, you can run `!gh auth login` to sign in to the GitHub CLI without opening a new terminal, so Kimi can use `gh` afterward.
+
+### Goal mode
+
+A goal keeps the agent working toward a defined outcome across turns — a normal prompt says what to do next, a goal says what must become true. Use `/goal` for tasks with a clear finish line and verifiable evidence, like fixing a batch of failing tests or tracking down why a build fails. For one-off edits or single-answer questions, a normal prompt is usually better.
+
+Write the objective after `/goal`, naming the finish line and the stop condition (up to 4000 characters; longer input is rejected and stays in the input box for editing):
+
+```sh
+/goal Fix every checkout-regression bug, add or update tests for each fix, then run the checkout test suite
+```
+
+Avoid broad objectives like `/goal find every bug in this codebase` — with no success criteria, the agent may block immediately or work far longer than expected. Clearly impossible goals (like `/goal prove that 1 + 1 = 3`) are marked as blocked right away.
+
+Common management commands:
+
+| Command | Action |
+| --- | --- |
+| `/goal` or `/goal status` | Show the current goal and its progress |
+| `/goal pause` / `/goal resume` | Pause / resume the goal |
+| `/goal cancel` | Cancel the goal (asks for confirmation; a cancelled goal cannot be resumed) |
+| `/goal replace <objective>` | Replace the current goal |
+| `/goal next <objective>` | Queue a follow-up goal that starts when the current one completes |
+
+A goal stops in three ways: **complete** — achieved, cleared, and summarized; **paused** — you paused it, interrupted a turn, or an error occurred; **blocked** — the agent can't continue as stated and writes a short message explaining why. The time budget only ticks while the goal is active and the session is open — closing the session or pausing the goal stops the clock, and `/goal resume` continues with the remaining budget after you reopen the session.
+
+In the web UI, the goal bar below the conversation lets you pause, resume, or cancel the goal directly; click it to expand details, including budget progress when a token budget is configured.
+
+Use `/goal next <objective>` to line up follow-up work without interrupting the current goal — queued goals stay invisible to the agent until the current one completes, then the first starts automatically. `/goal next manage` opens an interactive manager to reorder, edit, or delete queued goals (arrow keys to browse, `Space` to select, `E` to edit, `D` to delete, `Esc` to cancel). Queued goals never start while the current goal is paused, cancelled, or blocked.
+
+> Tip: in `manual` permission mode a goal may stop at tool approvals; non-interactive mode only supports creating goals (`kimi -p "/goal ..."`) — exit code `0` on complete, `3` on blocked, `6` on paused.
+
+## During streaming output
+
+The input box remains usable while the agent is thinking or calling tools, and supports the following extra actions:
+
+- **`Ctrl-S`**: inject the content in the input box into the running turn immediately, without waiting for it to finish
+- **`Esc` / `Ctrl-C`**: interrupt the current turn
+- **`Ctrl-O`**: globally toggle the collapsed/expanded state of tool output and compaction summaries
+
+When the agent is waiting for background tasks through `WaitFor`, pressing `Ctrl-S` ends that wait early. Background tasks keep running and existing tool results are preserved. If other foreground tools remain in the same batch, the agent processes your message after they return.
+
+## External editor
+
+Press `Ctrl-G` to send the current input content to an external editor. When you save and close, the text is written back into the input box; if you close without saving, the original content is preserved. This is handy when you need to enter large blocks of text or content with complex formatting.
+
+Editor priority: `/editor` config → `$VISUAL` environment variable → `$EDITOR` environment variable. If none are set, run `/editor` first to choose a default.
+
+## Next steps
+
+- [Keyboard shortcuts](../reference/keyboard.md) — full quick-reference table of all shortcuts
+- [Slash commands](../reference/slash-commands.md) — all built-in commands with descriptions and aliases
+- [Sessions and context](./sessions.md) — how to resume sessions, compress context, and export conversations

docs/en/guides/migration.md

@@ -0,0 +1,40 @@
+# Migrating from kimi-cli
+
+::: info
+Kimi Code CLI has gone through a major version upgrade — moving from Python/uv to Node.js, bringing a simpler install experience, faster startup, and a redesigned terminal UI. The legacy version will gradually be phased out, so we recommend upgrading as soon as possible.
+:::
+
+If you are migrating from the legacy version, follow the steps below — a single command migrates your config, MCP servers, and session history to the new version.
+
+## What's new
+
+- **No more Python / uv**: Rebuilt on Node.js — no Python environment needed, simpler to install
+- **Native binary, works out of the box**: Faster startup, lighter footprint
+- **Redesigned terminal UI**: Smoother, more responsive experience
+- **Full data migration**: Config, MCP servers, and session history all carry over seamlessly
+
+## How to migrate
+
+There are two ways to migrate.
+
+The **first time you run `kimi`** after installing kimi-code, it automatically checks whether kimi-cli data exists under `~/.kimi/`. If it finds any, a migration prompt appears, and you can choose to migrate now, do it later, or never be asked again.
+
+You can also **run it manually at any time**:
+
+```sh
+kimi migrate
+```
+
+You can choose whether to migrate chat sessions as well. If you don't need the history yet, pick **Config only**; otherwise pick **Config + N sessions** to bring everything across in one go. A summary is printed at the end.
+
+## What happens during migration
+
+**What gets migrated**: configuration (`config.toml`), MCP server configuration, input history, and whichever chat sessions you chose to migrate.
+
+**What does not get migrated**: OAuth login credentials and MCP service authorizations are not copied, so you will need to run `/login` again and re-authorize MCP servers after migrating. kimi-cli plugins are also out of scope.
+
+::: tip
+Migration **never modifies or deletes** any of the old data under `~/.kimi/`. kimi-cli keeps working as before, and the two do not interfere with each other. Migration can also be run repeatedly — sessions that have already been migrated are not imported again.
+:::
+
+After migration, sessions imported from kimi-cli are tagged with `[imported]` in the session picker so you can tell them apart from new ones.

docs/en/guides/remote-control.md

@@ -0,0 +1,147 @@
+# Remote Control
+
+Start Kimi Code CLI with remote control enabled by running `kimi rc` in a terminal — it generates a link that can remotely control this machine. Scan the QR code with your phone to open the link, or visit it directly on another device. After opening the link, log in with the same Kimi account as in your local Kimi Code CLI to check on task progress, handle approvals, continue conversations, or start new sessions. Tasks always run on your machine — the web page is just a remote window.
+
+## Getting started
+
+### Prerequisites
+
+Before turning on Remote Control, make sure your machine meets the following conditions:
+
+- **Kimi Code CLI installed**: see [Getting started](../guides/getting-started.md)
+- **Logged in to your Kimi account with a paid membership**: Remote Control requires a paid membership and is not available to free users
+- **Machine stays awake and online**: Remote Control depends on a persistent connection between your machine and the Kimi service; remote sessions are unavailable after shutdown, sleep, or network loss
+
+### Step 1: Start Remote Control
+
+Start it on your machine in any of the following ways — they are equivalent: each starts a foreground process and prints the remote access info.
+
+- **`kimi rc`** (alias `kimi remote`): start Remote Control directly
+- **`kimi web --remote-control`**: equivalent to `kimi rc` — starts the local web interface and exposes it to the public internet at the same time
+- **`/remote-control`** (alias `/rc`): use while already in a CLI session to hand the current session over to the remote interface
+
+Once started, the terminal prints the access URL (like `https://code-rc.kimi.com/devices/<device ID>/`), a QR code, and the device name (the machine's hostname), and the default browser opens the URL automatically (use `--no-open` to skip). Besides the terminal rendering, the QR code is also saved as a PNG file (the path is printed in the startup output) — if the QR code doesn't render properly in your terminal, open that file instead.
+
+![Terminal output after starting kimi rc: QR code and connection status](../../media/kimi-rc-banner.jpg)
+
+::: warning Note
+The Remote Control link is a remote control entry point to this machine — anyone who has it may control your sessions and files. Do not share it with others or post it anywhere public.
+:::
+
+Two limitations:
+
+- Only one Remote Control instance can run per machine. Starting it again reports the existing instance and prints the link already in use — see [How to turn off Remote Control](#how-to-turn-off-remote-control) for how to stop the old one
+- Remote Control cannot be combined with `--dangerous-bypass-auth`, and it only binds to the loopback address (`--host` LAN sharing is not supported — remote access goes through the Kimi relay service)
+
+### Step 2: Connect from another device
+
+1. Open the access URL from the startup output in a browser on your phone or another computer — on a phone, you can also scan the QR code in the terminal directly.
+2. Log in with the same Kimi account as on the machine.
+3. After logging in, pick this machine in the device list (shown by its hostname) to see its sessions and start working.
+
+Remote Control works in the browser.
+
+::: info Device limit
+Each account currently supports up to about **3 devices**.
+:::
+
+### How to turn off Remote Control
+
+Remote Control is a foreground process; how you stop it depends on whether you can find the terminal that started it:
+
+- **The terminal is still there**: press `Ctrl+C` in that terminal (or just close the window) — the device immediately goes offline from the remote list
+- **Can't find the terminal**: the single-instance lock file `~/.kimi-code/server/rc.json` records the process pid and the link in use (the error from starting a second instance prints both as well) — run `kill <pid>`
+- **The process already died** (power loss, crash, …): the stale lock file is cleaned up automatically on the next start — nothing to delete by hand
+
+To start a fresh instance, stop the old one in any of the ways above and run `kimi rc` again — there is no dedicated restart command. The device ID is derived from the machine's data directory, so the device and its access URL stay the same. The web-side device management and revocation UI is subject to the final release.
+
+## What you can do in a remote session
+
+Remote sessions have essentially the same capabilities as local ones:
+
+- **Send new tasks**: describe what you need; the task runs on your machine
+- **Watch progress**: execution steps and tools in use are shown in real time
+- **Continue the conversation**: follow up on existing sessions
+- **Inspect tool calls**: expand the input and output of each tool execution
+- **Handle approvals**: approve or deny file edits, Shell execution, and other confirmation requests right in the web page
+- **Interrupt or stop tasks**: stop the running task at any time
+- **Check subagent / workflow status**: track subagents or workflows dispatched by the task in the task panel
+
+## What happens on your machine
+
+Remote Control is only a remote window — all computation and file operations still happen on your machine. The boundaries:
+
+| Content | Happens locally |
+| --- | --- |
+| Reading project files | Yes |
+| Modifying project files | Yes |
+| Running Shell commands | Yes |
+| Using local MCP | Yes |
+| Phone or browser UI | No |
+| Session sync | Via the Kimi service |
+
+## Disconnects, sleep, and recovery
+
+- **Closing the browser**: the task keeps running on your machine. Reopen the access URL to get the session view back
+- **Machine loses network**: while offline, the remote UI disconnects and becomes unusable. The Remote Control process and the local server keep running, but an in-flight task may stall or fail because model requests can't get out. Once the network is back, the machine reconnects to the relay automatically — just refresh the remote page, no restart needed
+- **Machine sleeps**: the Remote Control connection drops and tasks may pause or fail. Set the computer to never sleep in system settings, or keep it awake while in use
+- **Local process exits**: pressing `Ctrl+C` or closing the terminal stops Remote Control and takes the device off the remote list. Restart it to recover
+- **End the remote connection but keep the local task**: just close the web page — the local task is unaffected
+
+## What's the difference between Remote Control and Kimi Code Web?
+
+[Kimi Code Web](../guides/web.md) is the graphical interface on your machine or LAN; Remote Control extends it to any device on the public internet:
+
+| | Kimi Code Web | Remote Control |
+| --- | --- | --- |
+| Access scope | `localhost`, or the LAN with `--host` | Any device on the public internet (via the Kimi relay) |
+| How to start | Run `kimi web` in a terminal | `kimi rc`, `kimi web --remote-control`, or `/remote-control` in the CLI |
+| Authentication | Local token | Log in with the same Kimi account |
+| Where data and execution live | Your machine | Your machine (the web page is just a remote window) |
+| Typical scenario | GUI in a local browser | Following up remotely from a phone, tablet, or another computer |
+
+For the web interface's features, see [Using Kimi Code in the browser](../guides/web.md).
+
+## Security and permissions
+
+### How remote devices authenticate
+
+A remote device must log in with the same Kimi account as the machine to view and control sessions. Your devices are never exposed to other accounts, and there is no public link that works without logging in.
+
+### Does the access URL contain sensitive information
+
+The access URL itself contains no session data or local token — everything is shown per account permissions after login. But it is a remote control entry point to this machine, and the startup output also warns you not to share it.
+
+## FAQ
+
+### The link won't open from inside WeChat — what do I do?
+
+WeChat's in-app browser restricts some external webpages under its own security policies, so the Remote Control access URL (`https://code-rc.kimi.com/…`) opened directly in WeChat may be blocked with a "web page access stopped" notice.
+
+The fix: tap the "…" menu in the top-right corner and open the page in your default browser, or copy the link and paste it into a system browser such as Safari or Chrome. The same applies when scanning the startup QR code with WeChat's scanner — open it in a browser to get the full session functionality.
+
+### Does the task stop when I close the browser?
+
+No. The browser is just a window — the task runs on your machine. Closing the page doesn't affect it; reopen the link to get the view back.
+
+### Can I keep going after closing the local terminal?
+
+No. Remote Control depends on the Remote Control process on your machine staying alive; once the process exits, the remote connection drops. Restart it to recover.
+
+### Can a phone access local files directly?
+
+No. The phone has no direct channel to your machine's file system: what you see on the phone is the content rendered inside the session interface (such as diffs and file cards after the AI edits files), while all file reads/writes and command execution happen on the machine. The phone cannot browse, open, or download local files outside of a session.
+
+### How to troubleshoot a failed remote connection
+
+Check in this order:
+
+1. **Wake state**: make sure the machine is awake and hasn't gone to sleep
+2. **Network connectivity**: can the machine reach the internet
+3. **Process status**: is the Remote Control process running on the machine
+4. **Account match**: is the web side logged in with the same Kimi account
+5. **Firewall and proxy**: is your corporate network or proxy blocking `code-rc.kimi.com`
+
+## Next steps
+
+- [Using Kimi Code in the browser](../guides/web.md) — Remote Control opens the same web interface; learn what the interface itself can do

docs/en/guides/sessions.md

@@ -0,0 +1,122 @@
+# Sessions and context
+
+Kimi Code CLI persists every conversation as a "session" — storing message history and metadata so you can close the terminal and pick up right where you left off. This page covers how to resume sessions, manage context, and export or fork sessions.
+
+## Session storage
+
+All sessions are saved under `$KIMI_CODE_HOME/sessions/` (default: `~/.kimi-code/sessions/`), grouped by working directory:
+
+```text
+~/.kimi-code/
+├── config.toml
+├── session_index.jsonl
+└── sessions/
+    └── <workDirKey>/
+        └── <sessionId>/
+            ├── state.json
+            └── agents/
+                ├── main/
+                │   └── wire.jsonl
+                └── <subagentId>/
+                    └── wire.jsonl
+```
+
+- `state.json`: session metadata such as title and creation time.
+- `agents/*/wire.jsonl`: the agent event stream, used for session recovery and replay. It also carries a request trace — the tool schemas, request parameters, and MCP tool listings sent to the model — for debugging.
+
+::: warning
+Do not manually edit files inside the `sessions/` directory — doing so may prevent sessions from being restored correctly.
+:::
+
+## Starting and resuming sessions
+
+Every time you run `kimi` directly it creates a new session. To resume a previous session, use one of the following:
+
+**Resume the most recent session in the current directory:**
+
+```sh
+kimi --continue
+```
+
+**Resume a specific session by ID:**
+
+```sh
+kimi --session abc123
+```
+
+**Interactively browse session history and choose one:**
+
+```sh
+kimi --session
+```
+
+::: warning
+`--continue` and `--session` are mutually exclusive.
+:::
+
+## Switching sessions inside the TUI
+
+You can manage sessions without leaving the terminal. The following slash commands are available only when the agent is idle:
+
+- **`/new`** (alias `/clear`): switch to a new session, discarding the current context.
+- **`/sessions`** (alias `/resume`): browse and resume a previous session.
+- **`/fork`**: fork the current session (see below).
+- **`/title <text>`** (alias `/rename`): set a session title for easier identification; without arguments, displays the current title.
+
+## Context compression
+
+As a conversation grows, Kimi Code CLI automatically compresses the message history when the context approaches the window limit, freeing up token space. You can also trigger compression manually at any time:
+
+```
+/compact
+```
+
+You can pass a hint to tell the model what to prioritize when compressing:
+
+```
+/compact Keep the discussion about database migrations
+```
+
+## Forking a session
+
+To explore a new direction without disrupting the current conversation, use `/fork`:
+
+```
+/fork
+```
+
+Forking does not switch you away: you stay in the original session and the conversation continues untouched. The fork is an independent copy you can switch to at any time using `/sessions`. A saved `/goal` is not copied to the fork. Start a new goal there if you want autonomous goal work.
+
+After forking, the CLI prints a ready-to-run `kimi --resume` command (also copied to the clipboard) so you can enter the fork directly from a new terminal process.
+
+## Exporting a session
+
+Use `kimi export` to package a session as a ZIP file — useful for sharing, archiving, or filing a bug report:
+
+```sh
+kimi export <sessionId>
+```
+
+Omitting `sessionId` exports the most recent session in the current directory (with an interactive confirmation prompt; add `-y` to skip). Use `-o` to specify an output path:
+
+```sh
+kimi export <sessionId> -o ~/Desktop/my-session.zip
+```
+
+The export includes all files in the session directory, including diagnostic logs. The global diagnostic log (`~/.kimi-code/logs/kimi-code.log`) is also bundled by default; add `--no-include-global-log` to exclude it.
+
+You can also export from inside the TUI without leaving the interactive session:
+
+- **`/export-debug-zip`**: produces the same debug ZIP as `kimi export`.
+- **`/export-md`** (alias `/export`): exports the conversation as a human-readable Markdown file, suitable for sharing or archiving. Accepts an optional path argument; without one, it writes to `kimi-export-<short-id>-<timestamp>.md` in the current working directory.
+
+In the web UI, `/export` downloads the current session as a diagnostic ZIP. It includes the persisted session data, diagnostic logs, and a bounded metadata-only `logs/kimi-web.jsonl` record of key browser events. Prompt text, WebSocket payloads, and console arguments are not copied into this browser log. This web command differs from the TUI `/export` alias above.
+
+::: tip
+Exported files may contain code, command output, and file paths that are sensitive. Review the content before sharing.
+:::
+
+## Next steps
+
+- [Data locations](../configuration/data-locations.md) — full directory layout for session files
+- [kimi command reference](../reference/kimi-command.md) — complete parameter reference for `--continue`, `--session`, `export`, and other commands

docs/en/guides/use-cases.md

@@ -0,0 +1,148 @@
+# Common use cases
+
+This page collects typical Kimi Code CLI scenarios along with ready-to-use prompt examples — copy them as-is or adapt them to your needs.
+
+## Understanding an unfamiliar project
+
+When taking over an unfamiliar repository, a good first step is to use `kimi --plan` or press `Shift-Tab` to enter Plan mode, so the agent outputs a research plan before touching anything:
+
+```
+Give me an overview of this repository's architecture. Specifically:
+1. Where is the entry point and what happens at startup?
+2. How do the main modules depend on each other?
+3. How are configuration and data loaded?
+Finally, draw a simple module dependency diagram.
+```
+
+You can also focus on a specific question:
+
+```
+How does the event loop in src/runtime work? Where do events originate, and what consumes them?
+```
+
+```
+How is "permission approval" implemented in this project? Which files are involved, and what are the key types?
+```
+
+For large-scale investigations, you can have the main agent dispatch **sub-agents** to handle sub-tasks in parallel. See [Agents and sub-agents](../customization/agents.md).
+
+## Implementing a new feature
+
+Describe the requirement and acceptance criteria clearly. For complex changes, use Plan mode to confirm the approach before execution:
+
+```
+Add a retry utility under src/utils:
+- Signature: retry<T>(fn: () => Promise<T>, options): Promise<T>
+- Options: maxAttempts, initialDelayMs, backoffFactor
+- On failure, throw the error from the last attempt
+- Add a unit test suite covering: success on first try, success after retries, and all attempts failing
+```
+
+If the result isn't right, just describe what you want changed — no need to edit manually:
+
+```
+The backoff calculation used a fixed value. I'd like to add some jitter to avoid the thundering-herd effect. Update the implementation and the tests.
+```
+
+## Fixing a bug
+
+Give the symptom, reproduction steps, and expected behavior all at once to avoid back-and-forth clarification:
+
+```
+Running npm test occasionally produces this error:
+
+  TypeError: Cannot read properties of undefined (reading 'id')
+      at SessionStore.update (src/session/store.ts:142:18)
+
+It only appears in test cases that concurrently trigger multiple updates. Please locate the cause and fix it, then run the full test suite to confirm.
+```
+
+When the root cause is unclear, ask the agent to investigate before making changes:
+
+```
+User feedback: after a successful login, the first page refresh sends you back to the login page; a second refresh works fine. Please find the most likely causes first and list the most suspicious locations. I'll confirm the direction before you start making changes.
+```
+
+For purely mechanical tasks, you can let the agent run freely:
+
+```
+Run the test suite, fix every failing test case, then run it again to confirm everything is green.
+```
+
+## Writing tests and refactoring
+
+Tasks with clear boundaries and explicit acceptance criteria are particularly well-suited for the agent:
+
+```
+src/parser/markdown.ts currently has almost no tests. Please add a unit test suite covering: normal paragraphs, nested lists, code blocks, tables, blockquotes, and mixed content. Follow the testing style already used in the project.
+```
+
+```
+Extract the repeated "read body → validate → log → respond" pattern in src/handlers into a middleware. Run the tests afterwards to make sure existing behavior is unchanged.
+```
+
+For multi-file refactors, use Plan mode first to confirm the approach. You can also `/fork` the session into an experimental branch and switch to it from `/sessions` — forking itself never disrupts the original session, so you can simply switch back if you don't like the result.
+
+## One-off scripts and automation
+
+Batch file edits, statistics collection, and research comparisons can all be done with a single prompt:
+
+```
+Change all var declarations in .js files under src to const or let, preferring const where possible. Run lint once you're done to confirm.
+```
+
+```
+Analyze the access logs in logs/ from the past 7 days. For each API path, compute the call count, p50, and p99 response times, and output the results as a Markdown table.
+```
+
+```
+Research the main dependency injection options for TypeScript (tsyringe, inversify, awilix). Compare them across three dimensions: API style, decorator requirements, and runtime overhead. Give me a recommendation that fits on one page.
+```
+
+For batch tasks you know are safe, use `--yolo` or `/yolo` to skip approval prompts, or add pre-approved allowlist rules for specific tools in [Configuration files](../configuration/config-files.md#permission).
+
+## Scheduled tasks and reminders
+
+Inside an interactive session, you can ask the agent to set one-time reminders or recurring tasks. The agent generates a cron expression in your local timezone and re-injects the prompt into the same session when it fires:
+
+```
+Remind me at 2:30 PM to check the deployment.
+```
+
+```
+Every weekday at 9 AM, summarize recent CI failures for me.
+```
+
+```
+Check the production health endpoint every hour and let me know if anything looks wrong.
+```
+
+```
+Come back in about 10 minutes and check whether the build has finished.
+```
+
+Scheduled tasks are bound to their session — closing the terminal is fine, and they are reloaded and continue firing when you resume the same session with `kimi --session`. They are not carried into brand-new sessions. Recurring tasks expire after 7 days — the agent receives a `stale` signal on the final trigger and decides whether to stop or renew based on your original instructions.
+
+To see what tasks are currently pending, just ask the agent (it calls the read-only `CronList` tool). To cancel a task, tell the agent to remove it or reference its 8-character ID. For the full tool reference, see [Scheduled tasks](../reference/tools.md#scheduled-tasks). The global kill switch is `KIMI_DISABLE_CRON=1`.
+
+## Generating and maintaining documentation
+
+```
+I just changed the interface signature in src/auth/login.ts. Please update the corresponding JSDoc, the example code in README, and any paragraphs in docs/en/guides that mention this interface.
+```
+
+```
+For every public function under src/api that is missing a docstring, add a documentation comment following the style of the existing ones.
+```
+
+```
+Based on the command implementations in src/cli, generate a draft command reference listing each subcommand, its arguments, and default values. Put it in docs/en/reference for me to review later.
+```
+
+When you need a record or a retrospective, use `kimi export <sessionId>` to package the session as a ZIP, or use `/export-md` inside the TUI to export a readable Markdown transcript.
+
+## Next steps
+
+- [Agents and sub-agents](../customization/agents.md) — how to have the agent dispatch sub-tasks for parallel execution
+- [Hooks](../customization/hooks.md) — trigger local scripts at task-completion and other lifecycle points
+- [Built-in tools](../reference/tools.md) — full reference of all tools the agent can call

docs/en/guides/web.md

@@ -0,0 +1,107 @@
+# Using Kimi Code in the browser
+
+Kimi Code Web is the browser-based graphical interface built into Kimi Code CLI: run `kimi web` in a terminal, and you can start sessions, chat, handle approvals, and review file changes in a browser — a friendlier interface, while sessions and data still live entirely on your machine.
+
+![Kimi Code Web UI](../../media/kimi-web-ui.jpg)
+
+## Getting started
+
+<div class="step">
+<span class="step-num">1</span> <strong>Install Kimi Code CLI and log in</strong>
+
+`kimi web` is a built-in CLI command — it isn't available without the CLI. See [Getting started](./getting-started.md) for installation and login.
+</div>
+
+<div class="step">
+<span class="step-num">2</span> <strong>Run <code>kimi web</code> in a terminal</strong>
+
+If you're already in the CLI, you can also type `/web` to hand the current session off to the browser.
+</div>
+
+<div class="step">
+<span class="step-num">3</span> <strong>The web UI opens in your default browser once ready</strong>
+
+The startup banner prints the access URL — if the browser doesn't open by itself, copy this URL and open it manually:
+
+```text
+Local:   http://127.0.0.1:58627/#token=...
+Token:   ...
+Stop:    Ctrl+C
+```
+
+::: warning
+The `#token=` fragment is the access credential — don't share it. Stop the server with `Ctrl+C` in the terminal.
+:::
+</div>
+
+### Startup options
+
+| Option | Description |
+| --- | --- |
+| `--port <port>` | Bind port; defaults to `58627`, auto-increments when taken |
+| `--host [host]` | Let phones, tablets, or other computers on the same LAN access the web address; you can also specify an IP, e.g. `--host 192.168.1.10` |
+| `--no-open` | Don't open the browser when ready |
+| `--log-level <level>` | Enable server logs at the given level; off by default |
+
+### Common slash commands
+
+| Slash command | Description |
+| --- | --- |
+| `/new` | Start a new session |
+| `/goal` | Enter Goal mode and keep working toward the same objective across turns |
+| `/compact` | Compact the current session's context |
+| `/tower` | Tower multi-agent collaboration (experimental); `/tower <base-branch>` sets the base branch |
+| `/export` | Export the session content and troubleshooting logs as a ZIP |
+| `/remote-control` | Enable remote control to access the local web session remotely |
+
+## Relationship with the CLI
+
+The web UI and the CLI share the same login state, configuration (`config.toml`), and session data.
+
+The web UI supports only a subset of the CLI's slash commands — see [Common slash commands](#common-slash-commands) above. Everything else usually has a point-and-click equivalent in the UI (the settings page, the model picker, the account menu, the task panel).
+
+How the two sides compare:
+
+<div class="feature-compare-table">
+
+| Feature | CLI | Web | Notes |
+| --- | --- | --- | --- |
+| Streaming chat | ✓ | ✓ | Web renders rich formats incrementally (tables, code highlighting, diffs, tool cards) |
+| Session management | ✓ | ✓ | Web lets you archive less-used sessions away; the archive page sorts them by time and you can restore them anytime; the Open / Done / Workspaces tabs are a Lab experiment (off by default) — enable them on the settings Lab page |
+| Approvals | ✓ | ✓ | Web handles them with clicks in the UI — no commands needed |
+| Background tasks | ✓ | ✓ | Web shows live progress in the task panel |
+| Files and changes | ✓ | ✓ | Web has a changed-files summary card and per-file diffs |
+| Settings | ✓ | ✓ | Web adds a settings UI (providers, account & usage, Lab experiments) |
+| Global search | — | ✓ | Web searches across sessions and workspaces |
+| Mobile layout | — | ✓ | With LAN sharing on (`--host`), it works in phone browsers on the same network |
+
+</div>
+
+## Security notes
+
+- **Set a parallel credential**: when binding a LAN address, also set the `KIMI_CODE_PASSWORD` environment variable; the server then rate-limits authentication failures automatically.
+- **Don't disable authentication entirely**: `--dangerous-bypass-auth` turns off all authentication — anyone who can reach the port can control your sessions, file system, and shell. Only use it on trusted networks or behind your own authenticating proxy. See the [kimi command reference](../reference/kimi-command.md#kimi-web).
+
+## FAQ
+
+### The port is already taken
+
+Nothing to do. `kimi web` automatically retries with the next port (58628, 58629, …) — just use the address printed in the startup banner.
+
+### The URL won't open in the browser
+
+First check the server is still running in the terminal (it runs in the foreground there). Copy the full URL including the `#token=` part; opening only `http://127.0.0.1:58627` lands on a token input page, where pasting the `Token` value from the banner also works.
+
+### How to recover from an invalid token
+
+Run `kimi web rotate-token` to generate a new token, then open the new banner URL. All running instances switch to the new token automatically — no restart needed.
+
+### Other devices on the same Wi-Fi can't connect
+
+Make sure you started with `--host` (bare is fine), and use the LAN URL from the banner (like `http://192.168.x.x:58627/#token=...`). If it still fails, check that the machine's firewall allows the port, and that both devices are really on the same network segment — guest Wi-Fi, VPNs, and switching to a 4G/5G hotspot all isolate devices.
+
+## Next steps
+
+- [Server API](../reference/server-api.md) — REST / WebSocket APIs for scripts and third-party integrations (experimental)
+- [kimi command](../reference/kimi-command.md#kimi-web) — all `kimi web` command-line options
+- [Remote Control](./remote-control.md) — remotely view and take over local sessions from any device over the public internet

docs/en/index.md

@@ -0,0 +1,13 @@
+---
+layout: home
+hero:
+  name: Kimi Code CLI
+  text: The Starting Point for Next-Gen Agents
+  actions:
+    - theme: brand
+      text: Get started
+      link: guides/getting-started
+    - theme: alt
+      text: GitHub
+      link: https://github.com/MoonshotAI/kimi-code
+---

docs/en/reference/keyboard.md

@@ -0,0 +1,104 @@
+# Keyboard Shortcuts
+
+Kimi Code CLI's TUI interactive mode supports a set of keyboard shortcuts. The shortcuts are organized into five groups by usage context: general input, mode switching, during streaming, tool output control, the approval panel, and popup navigation. Type `/help` in the TUI at any time to open the built-in shortcut reference.
+
+## General Shortcuts
+
+The following keys are always available in the input box:
+
+| Shortcut | Function |
+| --- | --- |
+| `Enter` | Submit the current input |
+| `Shift-Enter` / `Ctrl-J` | Insert a newline in the input |
+| `↑` / `↓` | Browse input history |
+| `Esc` | Close a popup / cancel completion / interrupt streaming output or context compaction |
+| `Ctrl-C` | Interrupt the current streaming output, or clear the input box |
+| `Ctrl-D` | Exit Kimi Code CLI when the input box is empty |
+| `Ctrl-T` | Expand or collapse the todo list when it is truncated |
+| `Ctrl-P` | Previous page in the experimental `Updates` panel when it has multiple pages |
+| `Ctrl-N` | Next page in the experimental `Updates` panel when it has multiple pages |
+
+Pressing `Ctrl-C` **during streaming** cancels immediately — no second confirmation needed.
+
+**Exiting the program** (pressing `Ctrl-C` with an empty input box, or pressing `Ctrl-D`) uses a double-press confirmation mechanism: after the first press, a prompt appears in the status bar; a second press of the same key actually exits. Pressing any other key in between clears the confirmation state.
+
+## Mode Switching
+
+| Shortcut | Function |
+| --- | --- |
+| `Shift-Tab` | Toggle Plan mode |
+| `!` | Enter shell mode (in an empty input box) |
+
+Press `Shift-Tab` to enable or disable Plan mode. When enabled, the Agent prioritizes read-only tools for research and planning and can write to the current plan file; `Bash` is subject to the current permission mode and regular rules, without any additional separate approval triggered by Plan mode. Simply toggling does not create an empty plan file. Press `Shift-Tab` again to exit Plan mode.
+
+Type `!` in an empty input box to enter shell mode and run terminal commands directly; while a command is running, press `Ctrl+B` to move it to a background task. See [Interaction and input](../guides/interaction.md#shell-mode).
+
+## Input & Editing
+
+| Shortcut | Function |
+| --- | --- |
+| `Ctrl-G` | Edit the current input in an external editor |
+| `Ctrl-V` | Paste an image or video from the clipboard (Unix / macOS) |
+| `Alt-V` | Paste an image or video from the clipboard (Windows) |
+| `Ctrl--` | Undo |
+| `Esc` `Esc` | Open the undo selector (double-press while idle) |
+
+Pressing `Ctrl-G` opens an external editor, selected according to the following priority:
+
+1. The editor configured via the `/editor` command
+2. The `$VISUAL` environment variable
+3. The `$EDITOR` environment variable
+
+After saving and exiting, the edited content replaces the input box; exiting without saving leaves the input unchanged.
+
+When pasting an image or video, a placeholder is shown in the input box — the actual media data is sent to the model when the message is submitted. The system clipboard is read first; on Linux, Wayland and X11 are tried; on WSL, PowerShell is also used as a fallback to read the Windows clipboard.
+
+## During Streaming
+
+While streaming output is active, the input box can still receive input and supports the following additional operations:
+
+| Shortcut | Function |
+| --- | --- |
+| `Ctrl-S` | Steer: inject the current input directly into the running turn |
+| `Esc` | Interrupt the current streaming output |
+| `Ctrl-C` | Interrupt the current streaming output |
+
+Pressing `Ctrl-S` causes the model to see your message at the next interruptible point, without waiting for the current turn to finish.
+
+## Tool Output
+
+| Shortcut | Function |
+| --- | --- |
+| `Ctrl-O` | Expand or collapse tool output, shell command output, and compaction summaries |
+
+When collapsed tool call results or shell command outputs exist in the history, press `Ctrl-O` to toggle between collapsed and expanded views. After compaction, the same shortcut shows or hides the compaction summary in the compaction block.
+
+## Approval Panel
+
+When the Agent initiates a tool call that requires confirmation, the TUI displays an approval panel. For the full approval workflow, see [Interaction & Input](../guides/interaction.md#approval-flow). The available keys inside the panel are:
+
+| Shortcut | Function |
+| --- | --- |
+| `↑` / `↓` | Move the cursor between candidate options |
+| `Enter` | Confirm the currently selected option |
+| `1` ~ `9` | Directly select the option at the corresponding index |
+| `Esc` / `Ctrl-C` / `Ctrl-D` | Reject the current request |
+| `Ctrl-E` | Expand or collapse the full content when the panel contains a diff or file preview |
+| `Ctrl-O` | Toggle the collapsed state of other tool output |
+
+Options that require feedback (such as "Reject" or "Revise") switch to a feedback input state after confirmation: type the feedback text and press `Enter` to submit; press `Esc` to exit feedback input and return to the candidate list.
+
+## Popup Mode
+
+After opening the help panel with `/help`, use the following keys to navigate and close it:
+
+| Shortcut | Function |
+| --- | --- |
+| `↑` / `↓` | Scroll one line at a time |
+| `PageUp` / `PageDown` | Scroll 10 lines at a time |
+| `Esc` / `Enter` / `q` / `Q` | Close the panel |
+
+## Next steps
+
+- [Slash Commands](./slash-commands.md) — Quick reference for built-in TUI control commands
+- [`kimi` Command](./kimi-command.md) — Complete reference for startup flags and subcommands

docs/en/reference/kimi-acp.md

@@ -0,0 +1,97 @@
+# `kimi acp` Subcommand
+
+`kimi acp` switches Kimi Code CLI to **ACP (Agent Client Protocol)** mode: it communicates with an ACP client (such as Zed, JetBrains AI Chat, etc.) via JSON-RPC over stdin/stdout, letting the IDE directly drive kimi's sessions, prompts, and tool calls.
+
+```sh
+kimi acp
+```
+
+Once started, the command prints no banner and immediately waits for the ACP client to send an `initialize` request on stdin. Logs are written to stderr (as well as the diagnostic log under `~/.kimi-code/logs/`), so the ACP channel itself stays clean.
+
+::: tip Who calls this?
+You typically do not need to run `kimi acp` manually — this command is the subprocess entry point for IDEs. For IDE-side configuration, see [Using in IDEs](../guides/ides.md).
+:::
+
+## Capability matrix
+
+The table below lists the capabilities declared by the ACP server. The `agentCapabilities` field is returned in full in the `initialize` response, so the IDE can adjust its UI accordingly.
+
+| Capability | Value | Description |
+| --- | --- | --- |
+| `loadSession` | `true` | Supports `session/load` to resume an existing session, replaying history on load |
+| `promptCapabilities.image` | `true` | Supports ACP `image` content blocks (base64 + mimeType) |
+| `promptCapabilities.audio` | `false` | Audio prompts not yet supported |
+| `promptCapabilities.embeddedContext` | `true` | Client may send `resource`/`resource_link` embedded resource blocks; text content is injected into the prompt as `<resource uri="...">...</resource>`; blob resources are dropped with a warn |
+| `sessionCapabilities.list` | `{}` | Supports `session/list` to enumerate the current user's sessions |
+| `sessionCapabilities.resume` | `{}` | Supports `session/resume` to reattach to a session without history replay |
+| `sessionCapabilities.close` | `{}` | Supports `session/close` to tear down a live session |
+| `sessionCapabilities.delete` | `{}` | Supports `session/delete` to permanently remove a session |
+| `sessionCapabilities.fork` | `{}` | Supports `session/fork` to branch an existing session |
+| `sessionCapabilities.additionalDirectories` | `{}` | Extra working directories; honored on `session/new` only |
+| `mcpCapabilities.http` | `true` | Forwards HTTP MCP services configured by the IDE |
+| `mcpCapabilities.sse` | `true` | Forwards legacy SSE MCP services configured by the IDE |
+| `auth.logout` | `{}` | Supports ACP `logout` to drop the managed provider's token |
+
+## ACP method coverage
+
+With `@agentclientprotocol/sdk@1.x`, the ACP method set is organized by namespace: `core` and `session` cover the main agent flow, while `providers`, `nes` (inline-edit prediction), and `document` (buffer sync) are optional extension surfaces. On the client side, reverse-RPC methods are grouped under `session`, `fs`, `terminal`, and `elicitation`.
+
+**Summary: the ACP server implements the full core (3/3) and session (11/11) agent-side surface, 10/11 client reverse-RPC methods, and the `session/set_model` extension. Not implemented: `providers/*`, `nes/*`, `document/*`, and `elicitation/complete` — requests for them return `methodNotFound`.**
+
+### Core agent-side — IDE → agent (3 / 3)
+
+| Method | Implemented | Description |
+| --- | --- | --- |
+| `initialize` | Yes | Version negotiation; returns `agentInfo: { name: 'Kimi Code CLI', version }`, capability matrix, and `authMethods` (first-class `type:'terminal'` plus the legacy `_meta['terminal-auth']` fallback) |
+| `authenticate` | Yes | Validates `method_id='login'`; returns `authRequired (-32000)` if the token is missing, `invalidParams (-32602)` for an unknown ID |
+| `logout` | Yes | Drops the managed provider's token; subsequent gated calls return `auth_required` again |
+
+### Session agent-side — IDE → agent (11 / 11)
+
+| Method | Implemented | Description |
+| --- | --- | --- |
+| `session/new` | Yes | Accepts `cwd` / `mcpServers` / `additionalDirectories`; returns `sessionId` + `configOptions[]` + `modes` |
+| `session/load` | Yes | Restores a session from disk and replays history via `session/update` before the response settles |
+| `session/resume` | Yes | Lightweight sibling of `session/load`; skips history replay |
+| `session/list` | Yes | Enumerates sessions on disk, filterable by `cwd` |
+| `session/fork` | Yes | Branches a source session; `cwd` / `additionalDirectories` / `mcpServers` on the request are ignored with a warning |
+| `session/close` | Yes | Best-effort teardown: cancels any in-flight turn, disposes per-session resources, and closes the live session; an unknown id is not an error |
+| `session/delete` | Yes | Permanently removes a session and its persisted data; an unknown id returns `invalidParams (-32602)` |
+| `session/prompt` | Yes | Accepts `text` / `image` / `resource` / `resource_link` content blocks; streams `agent_message_chunk` |
+| `session/cancel` | Yes | Interrupts the current turn (a JSON-RPC `$/cancel_request` for a prompt lands in the same cancel path) |
+| `session/set_mode` | Yes | Validates `modeId`; the same underlying mode switch as `set_config_option({configId:'mode'})` |
+| `session/set_config_option` | Yes | Unified model / thinking / mode picker dispatcher |
+
+### Client-side reverse-RPC — agent → IDE (10 / 11)
+
+| Method | Implemented | Description |
+| --- | --- | --- |
+| `session/update` | Yes | Streams `agent_message_chunk` / `tool_call*` / `plan` / `config_option_update` / `available_commands_update` |
+| `session/request_permission` | Yes | Shared channel for tool approval and question prompts |
+| `fs/read_text_file` | Yes | Engine file reads are routed to the client when it advertises `fsCapabilities` |
+| `fs/write_text_file` | Yes | Engine file writes are routed to the client |
+| `terminal/create` · `output` · `release` · `kill` · `wait_for_exit` | Yes | Shell executions reverse-RPC to the client when it advertises `clientCapabilities.terminal` |
+| `elicitation/create` | Yes | Ask-user questions go through the native form when the client advertises `elicitation.form`; RPC failures fall back to `session/request_permission` |
+| `elicitation/complete` | No | |
+
+### Extension methods
+
+| Method | Implemented | Description |
+| --- | --- | --- |
+| `session/set_model` | Yes | Carried over from the ACP 0.23 unstable surface as an extension method; equivalent to `set_config_option({configId:'model'})` |
+
+All methods not listed above return `methodNotFound`.
+
+## MCP forwarding
+
+When an ACP client provides `mcpServers` in `session/new` or `session/load`, the ACP server performs the following conversions:
+
+- `http` → kimi's `transport: 'http'` configuration
+- `stdio` → kimi's `transport: 'stdio'` configuration
+- `sse` → kimi's `transport: 'sse'` configuration
+- `acp` → discarded with a warn log entry
+
+## Next steps
+
+- [Using in IDEs](../guides/ides.md) — Zed / JetBrains configuration steps and troubleshooting
+- [`kimi` Command Reference](./kimi-command.md) — Complete subcommand list

docs/en/reference/kimi-command.md

@@ -0,0 +1,384 @@
+# `kimi` Command
+
+`kimi` is the main command for Kimi Code CLI, used to start an interactive session in the terminal. Running it without any arguments opens a new session in the current working directory; combined with different flags, you can resume a previous session, skip approvals, start in Plan mode, or load Skills from a custom directory.
+
+```sh
+kimi [options]
+kimi <subcommand> [options]
+```
+
+## Main Command Options
+
+All flags are optional — run `kimi` directly to enter an interactive session:
+
+| Option | Short | Description |
+| --- | --- | --- |
+| `--version` | `-V` | Print the version number and exit |
+| `--help` | `-h` | Show help information and exit |
+| `--session [id]` | `-S` | Resume a session. With an ID, opens that session directly; without an ID, enters an interactive selector |
+| `--continue` | `-c` | Continue the most recent session in the current working directory, without specifying an ID manually |
+| `--model <model>` | `-m` | Specify a model alias for this launch. When omitted, new sessions use `default_model` from the config file |
+| `--prompt <prompt>` | `-p` | Run a single prompt non-interactively and stream the Assistant output to stdout. This mode does not open the TUI |
+| `--output-format <format>` | | Set the non-interactive output format; supports `text` and `stream-json`. Can only be used with `--prompt`; defaults to `text` |
+| `--yolo` | `-y` | Start in Ask When Needed mode: routine edits and commands run automatically; risky actions, questions, and plans still ask |
+| `--auto` | | Start in Never Ask mode: never interrupts you; everything runs and is decided automatically |
+| `--plan` | | Start a new session in Plan mode — the AI will prioritize read-only tools for exploration and planning |
+| `--skills-dir <dir>` | | Load Skills from the specified directory, replacing the automatically discovered user and project directories. Can be repeated |
+| `--agent <name>` | | Start a new session with the specified agent as the main Agent. Cannot be combined with `--session`/`--continue` |
+| `--agent-file <path>` | | Load a custom agent from a Markdown file for the new session and select it. Cannot be repeated or combined with `--agent`, `--session`, or `--continue` |
+| `--add-dir <dir>` | | Add an extra workspace directory for this session. Relative paths resolve against the current working directory. Can be repeated |
+
+`-r` / `--resume` is a hidden alias for `--session`; `--yes` and `--auto-approve` are hidden aliases for `--yolo` and are not shown in help output.
+
+::: warning
+`--yolo` skips human approval for regular tool calls, including file writes and shell command execution. Use it only in trusted working directories. Plan mode exit approval is not bypassed by `--yolo`; `Bash` inside Plan mode is handled under the regular allow rules.
+:::
+
+### Flag Conflict Rules
+
+The following combinations are rejected at startup:
+
+- `--continue` and `--session` are mutually exclusive — both mean "resume a previous session"
+- `--yolo` and `--auto` are mutually exclusive — the two permission modes cannot be combined
+- `--prompt` cannot be used with `--yolo`, `--auto`, or `--plan` — non-interactive mode uses `auto` permission by default
+- `--output-format` can only be used together with `--prompt`
+
+When resuming a session, you can override its saved permission or plan mode by adding `--auto`, `--yolo`, or `--plan`. For example, `kimi --continue --auto` resumes the latest session and switches it to Never Ask mode.
+
+## Common Usage
+
+Start a new session directly:
+
+```sh
+kimi
+```
+
+Pick up where you left off (automatically finds the most recent session in the current directory):
+
+```sh
+kimi --continue
+```
+
+Choose from the session history list, or specify a known ID directly:
+
+```sh
+kimi --session
+kimi --session 01HZ...XYZ
+```
+
+Skip approval prompts — suitable for batch tasks that are known to be safe:
+
+```sh
+kimi --yolo
+```
+
+Let the Agent handle everything autonomously, without asking the user questions:
+
+```sh
+kimi --auto
+```
+
+Read the code and produce an implementation plan before making any file changes:
+
+```sh
+kimi --plan
+```
+
+### Custom Skills Directories
+
+There are two ways to specify Skills directories, with different semantics:
+
+- **`--skills-dir <dir>`** (CLI flag): **Replaces** the automatically discovered user and project directories for this launch only. Can be repeated to stack multiple directories:
+
+  ```sh
+  kimi --skills-dir /path/to/team-skills --skills-dir ./local-skills
+  ```
+
+- **`extra_skill_dirs`** (`config.toml`): **Adds** directories on top of the automatically discovered ones, taking effect permanently. Suitable for configuring team-shared Skills. See [Agent Skills](../customization/skills.md).
+
+### Custom Agents
+
+`--agent` and `--agent-file` select which agent drives a new session, in both print mode (`kimi -p`) and the interactive TUI:
+
+```sh
+kimi --agent reviewer
+kimi -p --agent reviewer "Review the changes on this branch"
+```
+
+`--agent-file` registers a single agent file at the highest priority for this launch only and selects it; the flag cannot be repeated, and `--agent` and `--agent-file` are mutually exclusive. Both flags only apply when starting a new session — neither can be combined with `--session`/`--continue`, because the agent is bound at session creation and resuming restores the bound agent automatically. The selection is fixed at the session's first bind and cannot be switched later; in the TUI the flags bind only the startup session, and a session created later in the same process (for example via `/new`) starts with the default agent. See [Agents and Sub-Agents](../customization/agents.md#custom-agents) for the agent file format and discovery directories.
+
+## Non-Interactive Execution
+
+When running a single prompt in a script or CI environment, use `-p`:
+
+```sh
+kimi -p "Summarize the current repository status"
+```
+
+Output uses a transcript style: thinking content and Assistant text are both prefixed with `• `, and wrapped lines are indented by two spaces. Assistant text goes to stdout; thinking, tool progress, and "resuming session" notices go to stderr. In `-p` mode, no human approval is requested — regular tool calls are handled under the `auto` permission policy, while static deny rules remain in effect.
+
+Temporarily switch the model:
+
+```sh
+kimi -m kimi-code/kimi-for-coding -p "Explain the latest diff"
+```
+
+When you need to parse output programmatically, use the `stream-json` format — each line on stdout is a JSON object:
+
+```sh
+kimi -p "List changed files" --output-format stream-json
+```
+
+In `stream-json` mode, regular replies produce an Assistant message; when the model calls a tool, an Assistant message with `tool_calls` is emitted first, followed by the corresponding Tool message, then subsequent Assistant messages. Thinking content is not written to JSONL; tool progress and "resuming session" notices are still written to stderr.
+
+## Subcommands
+
+`kimi` provides the following subcommands: `login` (non-interactive login), `acp` (ACP IDE mode), `web` (run the local REST/WebSocket/web service in the foreground and open the web UI), `doctor` (validate configuration files), `export` (export a session), `migrate` (migrate legacy data), `upgrade` (check for updates), and `provider` (manage providers).
+
+### `kimi login`
+
+Log in to Kimi Code OAuth via the RFC 8628 device-code flow, without entering the TUI. The command issues a device authorization request, prints the verification URL and user code to stderr, then polls until the browser-side authorization is complete. The generated token is written to the same local location as TUI `/login` and is loaded automatically the next time `kimi` starts.
+
+```sh
+kimi login
+```
+
+This subcommand has no flags. Press `Ctrl-C` at any time during polling to cancel; the exit code is `1` on cancellation or failure, and `0` on success.
+
+### `kimi acp`
+
+Switch Kimi Code CLI to ACP (Agent Client Protocol) mode, communicating with an IDE via JSON-RPC over stdin/stdout so the editor can directly drive kimi's sessions and tool calls. You typically do not need to run this manually — the IDE starts it as a subprocess entry point. For configuration, see [Using in IDEs](../guides/ides.md); for technical details, see the [kimi acp reference](./kimi-acp.md).
+
+```sh
+kimi acp
+```
+
+### `kimi web`
+
+Run the local Kimi server in the foreground of the current terminal — a single process that exposes the REST + WebSocket API and serves the web UI from the same origin — and open the web UI in the default browser once it is ready. The command stays attached to the terminal and shuts down cleanly on `SIGINT` / `SIGTERM` (e.g. `Ctrl-C`).
+
+When the server is running, `GET /openapi.json` returns the REST OpenAPI document and `GET /asyncapi.json` returns the local WebSocket AsyncAPI document. For an end-to-end walkthrough of driving sessions over the API, see [Server API: Drive a session over the API](./server-api.md#drive-a-session-over-the-api); for the protocol details, see the [Server API](./server-api.md) reference.
+
+```sh
+kimi web                 # run the server in the foreground and open the browser
+kimi web --no-open       # don't open the browser
+kimi web --port 58628    # pick a specific bind port
+```
+
+Multiple instances can share one home directory: each registers itself under `~/.kimi-code/server/instances/`, and a busy port is retried with `port + 1` (58628, 58629, …).
+
+| Option | Description |
+| --- | --- |
+| `--port <port>` | Bind port; defaults to `58627`; a busy port is retried with `+1` |
+| `--host [host]` | Bind host; omit for `127.0.0.1` (this machine only), pass a bare `--host` for `0.0.0.0` (all interfaces) |
+| `--allowed-host <host...>` | Extra Host header values allowed through the DNS-rebinding check; repeatable or comma-separated |
+| `--log-level <level>` | Enable server logs at the selected level; omitted by default |
+| `--debug-endpoints` | Mount `/api/v1/debug/*` routes (off by default) |
+| `--dangerous-bypass-auth` | Disable bearer-token auth on all REST and WebSocket routes so the web UI connects without a token; only for trusted networks or behind an authenticating proxy |
+| `--web-title <title>` | Custom browser tab title for the web UI; defaults to the workspace directory name |
+| `--no-open` | Do not open the browser once the server is ready |
+
+`kimi web` binds to local loopback only by default and prints the bearer token in the startup banner; the web UI authenticates automatically via the `#token=` URL fragment.
+
+::: info
+The `kimi server` command tree is deprecated: any `kimi server …` invocation (including all legacy subcommands) only prints a deprecation notice and exits with code 1 — use `kimi web` instead. The one exception is `kimi server kill`, which stays functional for stopping servers started by a version before 0.28.0. The notice will be removed in the next major version of Kimi Code.
+:::
+
+::: danger
+`--dangerous-bypass-auth` disables authentication entirely. Anyone who can reach the port gets full access to your sessions, filesystem, and shell. Only use it on a trusted network or behind your own authenticating reverse proxy, and stop the server with `Ctrl+C` when you are done.
+:::
+
+#### `kimi server kill`
+
+Deprecated — only stops a server started by a version before 0.28.0. Those versions could leave a background server behind, recorded in the legacy single-instance lock at `~/.kimi-code/server/lock`; the command first tries `POST /api/v1/shutdown` for a graceful exit, then signals the recorded pid with SIGTERM, escalating to SIGKILL when needed, and removes the lock file once the process is confirmed dead. Servers started by `kimi web` run in the foreground — stop them with `Ctrl+C` instead.
+
+#### `kimi web rotate-token`
+
+Generate a new persistent bearer token (written to `~/.kimi-code/server.token`); the previous token stops working immediately. The token is shared by the whole home directory, so every running instance picks the new one up on its next auth check — no restart needed.
+
+### `kimi doctor`
+
+Validate `config.toml` and `tui.toml` without starting the TUI or modifying either file. By default, the command checks the files under `KIMI_CODE_HOME` (or `~/.kimi-code` when the environment variable is unset). Missing default files are reported as skipped because built-in defaults can apply.
+
+```sh
+kimi doctor
+```
+
+| Command | Description |
+| --- | --- |
+| `kimi doctor` | Validate the default `config.toml` and `tui.toml` |
+| `kimi doctor config [path]` | Validate only `config.toml`, using `path` instead of the default file when provided |
+| `kimi doctor tui [path]` | Validate only `tui.toml`, using `path` instead of the default file when provided |
+
+When an explicit path is passed, the file must exist. The command exits with `0` when all checked files are valid or skipped, and `1` when any requested file is missing or invalid.
+
+```sh
+# Check the default config files
+kimi doctor
+
+# Check only the default runtime config
+kimi doctor config
+
+# Check a candidate TUI config before replacing the live config
+kimi doctor tui ./tui.toml
+```
+
+### `kimi export`
+
+Package a session into a ZIP file for sharing, archiving, or submitting bug reports.
+
+```sh
+kimi export [sessionId] [options]
+```
+
+| Parameter / Option | Short | Description |
+| --- | --- | --- |
+| `sessionId` | | The ID of the session to export. When omitted, the most recent session in the current working directory is automatically selected and requires confirmation |
+| `--output <path>` | `-o` | Output ZIP file path. When omitted, writes to a default filename in the current directory |
+| `--yes` | `-y` | Skip the confirmation prompt for the default session and export directly |
+| `--no-include-global-log` | | Do not include the global diagnostic log. Included by default |
+
+The export contains all files in the target session directory. The global diagnostic log (`~/.kimi-code/logs/kimi-code.log`) is included by default because it may contain events from other sessions or projects; add `--no-include-global-log` if you do not want to share it.
+
+```sh
+# Export the most recent session in the current directory, skipping confirmation
+kimi export -y
+
+# Export a specific session to a custom path
+kimi export 01HZ...XYZ -o ./bug-report.zip
+
+# Exclude the global diagnostic log
+kimi export 01HZ...XYZ -o ./bug-report.zip --no-include-global-log
+```
+
+### `kimi migrate`
+
+Migrate local data from a legacy kimi-cli installation to kimi-code, including session history and configuration files. Runs entirely interactively, guiding you through the full process.
+
+```sh
+kimi migrate
+```
+
+For full migration instructions, see [Migrating from kimi-cli](../guides/migration.md).
+
+### `kimi upgrade`
+
+Immediately check for the latest version and display an update prompt; exits after you make a selection. `kimi update` is an alias for this command.
+
+```sh
+kimi upgrade [-y]
+```
+
+For global npm, pnpm, yarn, and bun installations, `kimi upgrade` shows update options; selecting `Install update now` runs the corresponding foreground install command. For native installations (including Windows), it downloads and verifies the new binary in the foreground and swaps it in on the next start. When the current installation method cannot be upgraded automatically, the manual update command is printed instead. Pass `-y, --yes` to skip the confirmation prompt and install the update directly.
+
+### `kimi vis`
+
+Launch the session visualizer in your browser to inspect a session as it unfolds. The command starts an in-process server pointed at your local sessions, prints the URL, opens your browser, and keeps running until you press `Ctrl-C`.
+
+```sh
+kimi vis [sessionId] [options]
+```
+
+| Parameter / Option | Description |
+| --- | --- |
+| `sessionId` | Open the visualizer directly to this session. When omitted, it opens the home view listing your sessions |
+| `--port <number>` | Port to bind. By default an available port is picked automatically |
+| `--host <host>` | Host to bind. Default: `127.0.0.1` |
+| `--no-open` | Do not open the browser automatically; just print the URL |
+
+```sh
+# Start the visualizer and open the browser at the home view
+kimi vis
+
+# Open directly to a specific session
+kimi vis 01HZ...XYZ
+
+# Bind a fixed port and host without opening a browser (e.g. on a remote host)
+kimi vis --host 0.0.0.0 --port 8123 --no-open
+```
+
+### `kimi provider`
+
+Manage providers in the shell — the non-interactive equivalent of `/provider` in the TUI. Suitable for scripted deployments, CI initialization, and one-line setup on a new machine.
+
+```sh
+kimi provider <action> [options]
+```
+
+Five actions are available:
+
+#### `kimi provider add <url>`
+
+Bulk-import all providers from a custom registry (`api.json`). The command fetches the registry, creates a `[providers.<id>]` and `[models.<alias>]` entry for each item, and writes `source` metadata so the TUI refreshes providers and models from the same registry URL automatically on next startup.
+
+| Parameter / Option | Description |
+| --- | --- |
+| `<url>` | Registry URL |
+| `--api-key <key>` | Bearer token for accessing the registry. Falls back to the `KIMI_REGISTRY_API_KEY` environment variable if not provided; required |
+
+```sh
+kimi provider add https://registry.example.com/v1/models/api.json --api-key YOUR_KEY
+
+# Or via environment variable (suitable for CI / .envrc)
+KIMI_REGISTRY_API_KEY=YOUR_KEY kimi provider add https://registry.example.com/v1/models/api.json
+```
+
+If a provider ID already exists, it is removed and re-created. The default model is not set automatically; you can select one later with `-m` or `/model` in the TUI.
+
+#### `kimi provider remove <providerId>`
+
+Remove the specified provider and all its model aliases. If the removed provider is the one referenced by `default_model`, `default_model` is also cleared.
+
+```sh
+kimi provider remove kohub
+```
+
+#### `kimi provider list`
+
+Print each configured provider on a separate line, including type, model count, and source. Add `--json` to output the raw `providers` and `models` tables for programmatic processing.
+
+```sh
+kimi provider list
+kimi provider list --json | jq '.providers | keys'
+```
+
+#### `kimi provider catalog list [providerId]`
+
+Browse the public [models.dev](https://models.dev/) model catalog without modifying any configuration. Without an argument, lists all providers along with their protocol type and model count; with a `providerId`, lists all models under that provider along with their context window and capabilities. If the catalog URL cannot be reached, a built-in snapshot of the catalog is used instead.
+
+| Parameter / Option | Description |
+| --- | --- |
+| `[providerId]` | Optional — the provider ID to inspect |
+| `--filter <substring>` | Case-insensitive substring filter on ID or name |
+| `--url <url>` | Override the catalog URL; defaults to `https://models.dev/api.json` |
+| `--json` | Output matching entries as JSON |
+
+```sh
+kimi provider catalog list
+kimi provider catalog list --filter anthropic
+kimi provider catalog list anthropic
+```
+
+#### `kimi provider catalog add <providerId>`
+
+Import a known provider directly from the catalog by ID. The protocol type, base URL, and model information are all supplied by the catalog — only an API key is required. Vendors whose protocol the catalog does not declare (e.g. xai, openrouter, and other vendor-specific SDKs) are imported as OpenAI-compatible and the output notes the guess; when the catalog provides no usable endpoint, `--base-url` is required. Proprietary protocols (e.g. Amazon Bedrock) cannot be imported. When the public catalog is unreachable, the import uses the built-in snapshot, so it still works offline or in blocked networks.
+
+| Parameter / Option | Description |
+| --- | --- |
+| `<providerId>` | Provider ID in the catalog, e.g., `anthropic`, `openai` |
+| `--api-key <key>` | Provider API key. Falls back to `KIMI_REGISTRY_API_KEY` if not provided; required |
+| `--default-model <modelId>` | Optional — set `default_model` to `<providerId>/<modelId>` after import |
+| `--base-url <url>` | Override the catalog endpoint; required when the catalog declares none (or only an env placeholder) |
+| `--url <url>` | Override the catalog URL; defaults to `https://models.dev/api.json` |
+
+```sh
+kimi provider catalog list anthropic          # Browse available models first
+kimi provider catalog add anthropic --api-key sk-ant-... --default-model claude-opus-4-7
+```
+
+## Next steps
+
+- [Slash Commands](./slash-commands.md) — Quick reference for control commands in the interactive TUI
+- [Configuration Files](../configuration/config-files.md) — Persistent configuration for `default_model`, permission mode, and other startup parameters
+- [Agent Skills](../customization/skills.md) — Skill file format for directories loaded via `--skills-dir`
+- [Agents and Sub-Agents](../customization/agents.md) — Built-in sub-agents, custom agent files, and main Agent selection via `--agent`

docs/en/reference/slash-commands.md

@@ -0,0 +1,165 @@
+# Slash Commands
+
+Slash commands are built-in control commands provided by Kimi Code CLI in the interactive TUI, covering account configuration, session management, mode switching, information queries, and more. Type `/` in the input box to trigger command completion — the candidate list filters in real time as you continue typing; command aliases are also matched.
+
+After typing the full command name, press `Enter` to execute. If the `/`-prefixed input does not match any built-in or Skill command, it is sent to the Agent as a regular message.
+
+::: tip
+Some commands are only available in the idle state. Executing these commands while a session is streaming output or compacting context will be blocked — press `Esc` or `Ctrl-C` to interrupt first. The "Always available" column in the tables below indicates commands that are also available during streaming.
+:::
+
+## Account & Configuration
+
+| Command | Alias | Description | Always available |
+| --- | --- | --- | --- |
+| `/login` | — | Select an account or platform and log in: Kimi Code uses OAuth device-code flow; Kimi Platform uses API key login | No |
+| `/logout` | — | Clear credentials for the currently selected account | No |
+| `/provider` | — | Open the interactive provider manager to view, add, and remove configured providers. See [Platforms & Models — `/provider` and provider management](../configuration/providers.md#provider-—-interactive-provider-management) | Yes |
+| `/model` | — | Switch the LLM model used in the current session | Yes |
+| `/secondary-model` | `/subagent-model` | Pick the default model for subagents (writes `[secondary_model] default_model`; see the [subagent model pool](../configuration/config-files.md#subagent-model-pool)) | Yes |
+| `/settings` | `/config` | Open the settings panel inside the TUI | Yes |
+| `/experiments` | `/experimental` | Open the experimental feature panel | Yes |
+| `/permission` | — | Select a permission mode | Yes |
+| `/editor` | — | Configure the external editor launched by `Ctrl-G` | Yes |
+| `/theme` | — | Switch the terminal UI color theme | Yes |
+
+## Session Management
+
+| Command | Alias | Description | Always available |
+| --- | --- | --- | --- |
+| `/new` | `/clear` | Start a fresh session, discarding the current context | No |
+| `/sessions` | `/resume` | Browse historical sessions and switch to / restore one | No |
+| `/tasks` | `/task` | Browse the background task list | Yes |
+| `/fork` | — | Fork a new session from the current one, preserving the full conversation history; you stay in the current session | No |
+| `/title [<text>]` | `/rename` | Without arguments, display the current session title; with an argument, set a new title (max 200 characters) | Yes |
+| `/compact [<instruction>]` | — | Compact the current conversation context to free up token usage; an optional custom instruction can hint to the model what to preserve | No |
+| `/undo [<count>]` | — | Undo recent prompts from the active context. Without a count, opens a selector; with a count, undoes that many prompts. Prompts before the last compaction cannot be undone. Undoing also rolls back the todo list and plan mode state produced by those prompts (code changes are not reverted) | No |
+| `/reload` | — | Reload the current session and apply the latest `config.toml` settings (providers, models, etc.) and `tui.toml` UI preferences, without restarting the CLI | No |
+| `/reload-tui` | — | Reload only the `tui.toml` UI preferences (theme, editor, notifications, etc.) without rebuilding the session | Yes |
+| `/init` | — | Analyze the current codebase and generate `AGENTS.md` | No |
+| `/export-md [<path>]` | `/export` | Export the current session as a Markdown file | No |
+| `/export-debug-zip` | — | Export the current session as a debug ZIP archive (same behavior as [`kimi export`](./kimi-command.md#kimi-export)) | No |
+| `/copy` | — | Copy the last assistant message to the clipboard | No |
+| `/add-dir [<path>]` | — | Add an extra workspace directory to the current session. Run without a path (or with `list`) to list configured directories. When adding, choose whether to remember the directory for the project in `.kimi-code/local.toml` | No |
+| `/web` | — | Open the current session in the web UI: pick a running server to connect to, or start a new foreground server after the TUI exits. See [`kimi web`](./kimi-command.md#kimi-web) | Yes |
+
+## Modes & Run Control
+
+| Command | Alias | Description | Always available |
+| --- | --- | --- | --- |
+| `/yolo` | `/yes` | Open the permission mode list with Ask When Needed preselected; press `Enter` to confirm. In this mode, routine edits and commands run automatically; risky actions, questions, and plans still ask | Yes |
+| `/auto` | — | Open the permission mode list with Never Ask preselected; press `Enter` to confirm. In this mode, Kimi never interrupts you; everything runs and is decided automatically | Yes |
+| `/plan [on\|off]` | — | Toggle Plan mode. Without arguments, flips the current state; explicitly passing `on`/`off` forces the setting. Simply toggling does not create an empty plan file | Yes |
+| `/plan clear` | — | Clear the current plan | No |
+| `/swarm on\|off` | — | Turn swarm mode on or off without sending a prompt. | Yes |
+| `/swarm <task>` | — | Turn swarm mode on, then send `<task>` as a normal prompt. If the turn completes normally, swarm mode turns off automatically. In `manual` permission mode, Kimi Code asks whether to switch to Ask When Needed or Never Ask mode before starting. | No |
+| `/goal [...]` | — | Start or manage an autonomous goal | See below |
+
+::: warning
+`/yolo` skips approval for regular tool calls. Please make sure you understand the potential risks before enabling it. Plan mode exit approval is not bypassed by `/yolo`; `Bash` inside Plan mode is still subject to the regular `/yolo` allow rules.
+:::
+
+## Autonomous Goal
+
+`/goal` starts or manages goal mode: a persistent objective that Kimi Code works toward across automatically continuing turns. For usage guidance and examples, see [Interaction and input: Goal mode](../guides/interaction.md#goal-mode).
+
+```sh
+/goal Update the checkout docs, run docs build, and stop if still blocked after 20 turns
+```
+
+| Command | Action | Availability |
+| --- | --- | --- |
+| `/goal` or `/goal status` | Display the current goal along with its status, elapsed time, turn count, and token count | Always available |
+| `/goal pause` | Pause an active goal and keep it | Always available |
+| `/goal resume` | Resume a paused or blocked goal | Idle only |
+| `/goal cancel` | Remove the current goal | Always available |
+| `/goal replace <objective>` | Replace the saved goal with a new objective | Idle only |
+| `/goal next <objective>` | Queue an upcoming goal for this session. If no goal is active, start it immediately. The agent does not see queued goals until the current goal completes | Always available |
+| `/goal next manage` | Open the upcoming-goal manager. Use <kbd>↑</kbd> / <kbd>↓</kbd> to browse, <kbd>Space</kbd> to select a goal for moving, selected <kbd>↑</kbd> / <kbd>↓</kbd> to reorder it, <kbd>E</kbd> to edit, <kbd>D</kbd> to delete, and <kbd>Esc</kbd> to cancel. In the edit field, use <kbd>Shift-Enter</kbd> or <kbd>Ctrl-J</kbd> for a new line and <kbd>Enter</kbd> to save | Always available |
+
+The words `status`, `pause`, `resume`, `cancel`, `replace`, and `next` act as subcommands only when they are the first word after `/goal`. If your objective needs to start with one of those words, put `--` before it:
+
+```sh
+/goal -- cancel the old rollout note after the new docs are published
+```
+
+If an upcoming goal needs to start with `manage`, put `--` after `next`:
+
+```sh
+/goal next -- manage the release checklist
+```
+
+In non-interactive prompt mode, only the create forms start goal mode:
+
+```sh
+kimi -p "/goal Fix the failing checkout test"
+```
+
+Prompt mode exits with code `0` when the goal completes, `3` when it blocks, and `6` when it pauses. Other `/goal` subcommands, including `next`, are TUI controls and are not handled by `kimi -p`.
+
+## Information & Status
+
+| Command | Alias | Description | Always available |
+| --- | --- | --- | --- |
+| `/help` | `/h`, `/?` | Show keyboard shortcuts and all available commands | Yes |
+| `/btw [question]` | — | Open a side conversation in a forked sub-Agent without affecting the current main Agent turn; without a question, opens the panel first to wait for input | Yes |
+| `/usage` | — | Show token usage, context consumption, and quota information | Yes |
+| `/status` | — | Show the current session runtime state: version, model, working directory, permission mode, etc. | Yes |
+| `/mcp` | — | List MCP servers and their connection status in the current session | Yes |
+| `/plugins` | — | Open the interactive plugin manager | Yes |
+| `/version` | — | Display the Kimi Code CLI version number | Yes |
+| `/feedback` | `/bug` | Submit feedback with optional diagnostic logs and codebase context | Yes |
+
+## Exit
+
+| Command | Alias | Description | Always available |
+| --- | --- | --- | --- |
+| `/exit` | `/quit`, `/q` | Exit Kimi Code CLI | No |
+
+## Built-in skill commands
+
+Kimi Code CLI ships with a set of built-in Skills that appear directly as `/<name>` slash commands. Unlike external Skills, they do not require the `skill:` prefix and are available out of the box.
+
+| Command | Description |
+| --- | --- |
+| `/mcp-config` | Configure MCP servers and handle MCP OAuth login. See [MCP](../customization/mcp.md) |
+| `/custom-theme [<text>]` | Create or edit a custom TUI color theme. See [Themes](../customization/themes.md) |
+| `/update-config` | Inspect or edit `config.toml` (model, provider, permission, hooks) and `tui.toml` (theme, editor, notifications, auto-update) |
+| `/check-kimi-code-docs` | Answer Kimi Code product questions (CLI usage, configuration, membership, error codes) against the official docs |
+| `/import-from-cc-codex` | Import Claude Code and Codex instructions, skills, and MCP settings into Kimi Code |
+| `/sub-skill` | Discover and reorganize the local skill inventory into hierarchical sub-skill bundles. Includes `/sub-skill.review` (read-only proposal) and `/sub-skill.consolidate` (apply the reorganization) |
+
+All built-in Skill commands are only available in the idle state.
+
+## Skill Dynamic Commands
+
+Activated external Skills are automatically registered as slash commands. Ordinary external Skills use the `skill:` namespace prefix:
+
+```
+/skill:<name> [extra text]
+```
+
+For example, `/skill:code-style` loads the Skill named `code-style` and sends it to the Agent; any text appended after the command is concatenated to the Skill prompt.
+
+External sub-skills appear directly in the slash command panel with dotted names:
+
+```
+/<parent-skill>.<sub-skill> [extra text]
+```
+
+For example, a child Skill named `review` inside a parent Skill named `code-style` is shown as `/code-style.review`. The dotted command name is derived from the hierarchy; the child `SKILL.md` can keep its local `name`.
+
+For convenience, external Skill commands also support a shorthand form that omits the `skill:` prefix — `/<name>` — as long as the name is not taken by a system slash command. That is, `/code-style` falls back to matching `/skill:code-style`.
+
+Built-in Skills shipped with Kimi Code CLI appear directly as `/<name>` in the slash command panel. For example, `/mcp-config` helps configure MCP servers and handle MCP OAuth login, and `/custom-theme [extra text]` invokes the custom-theme workflow to create or edit a TUI theme.
+
+::: info
+External Skill commands entered while the agent is busy are queued behind the running turn instead of being rejected — press `Ctrl-S` to steer a queued command into the running turn immediately. `flow`-type Skills are also exposed via `/skill:<name>` — there is no separate `/flow:` namespace.
+:::
+
+For installing and authoring Skills, see [Agent Skills](../customization/skills.md).
+
+## Next steps
+
+- [Keyboard Shortcuts](./keyboard.md) — Quick reference for TUI keyboard operations
+- [Built-in Tools](./tools.md) — Complete reference for tools the Agent can call

docs/en/reference/tools.md

@@ -0,0 +1,158 @@
+# Built-in Tools
+
+Built-in tools are the tool set provided by Kimi Code CLI alongside its core engine — no MCP server installation required. The Agent automatically selects and calls these tools based on the task at hand during each conversation; users can inspect the details of each tool call through the approval interface.
+
+Compared to MCP tools, built-in tools are managed directly by the runtime, their lifecycle is bound to the session, and no external process is required. Both follow the same unified approval mechanism: **read-only tools** (such as `Read`, `Grep`, `Glob`) are automatically allowed by default, while **write and execution tools** (such as `Write`, `Edit`, `Bash`) require user approval by default. In Ask When Needed mode, approval for regular tool calls is skipped; Plan mode exit approval is not affected.
+
+## File Tools
+
+File tools handle reading, writing, and searching the local filesystem — the foundation for code analysis and modification tasks.
+
+| Tool | Default Approval | Description |
+| --- | --- | --- |
+| `Read` | Auto-allow | Read a text file's contents |
+| `Write` | Requires approval | Create or overwrite a file |
+| `Edit` | Requires approval | Precise string replacement |
+| `Grep` | Auto-allow | Full-text search powered by ripgrep |
+| `Glob` | Auto-allow | Find files by glob pattern |
+| `ReadMediaFile` | Auto-allow | Read an image or video file |
+
+**`Read`** accepts a file path (`path`) plus optional `line_offset` (starting line number; negative values count from the end), `column_offset` (zero-based position within the first line of a forward read), `n_lines` (requested number of source lines), and `max_chars` (maximum characters in the result, including line numbers and status). Omitting `n_lines` reads toward the end of the file. The default is 100,000 characters, and calls can request up to 500,000; both values can be changed in the [`read` configuration](../configuration/config-files.md#read). Characters and column offsets use JavaScript string length in the displayed text, excluding the line-number prefix for column offsets: common letters and Chinese characters count as one, while many emoji count as two.
+
+`Read` prefers complete lines and its results are not shortened again by the general tool-output limit. A line that cannot fit on its own page is returned in fragments; the status reports the column range and `Next Read` arguments to retrieve the rest without raising the budget. Join fragments of the same line without adding a newline. A partial line remains in the requested `n_lines` range until its ending is returned. Invalid column positions return an error rather than skipping content.
+
+Tail reads return the newest complete lines in the requested range first. If no complete line fits, the result includes forward `Next Read` arguments for the unread range; `column_offset` cannot be combined with a negative `line_offset`. Continuation positions refer to the current file contents, so start a new read if the file changes. If a tail read reports that the file changed during reading, retry against the updated file. UTF-16 LE/BE files up to 10 MiB are checked with strict decoding first. If decoding fails, `Read` returns readable text with malformed sequences replaced by `�`, and every page warns that decoding was lossy and the text may differ from the original. The warning counts toward the character budget; a literal `�` in a valid file does not trigger it. Use `ReadMediaFile` for images or videos.
+
+**`Write`** accepts `path`, `content`, and an optional `mode` (`overwrite` or `append`; defaults to overwrite). Missing parent directories are created automatically; `append` mode appends content to the end of the file without automatically adding a newline. Writing to an existing file — in either `overwrite` or `append` mode — requires a prior `Read` of that file in the session; the write is rejected if the file changed on disk since the last read, while creating a new file is exempt.
+
+**`Edit`** accepts `path`, `old_string` (the exact text to replace), and `new_string` (the replacement text). By default it replaces only one unique match; if the same content appears multiple times in the file, the tool returns an error and suggests using `replace_all: true`. `old_string` and `new_string` must not be identical. The target file must have been read with `Read` earlier in the session, and the edit is rejected if the file changed on disk since that read.
+
+**`Grep`** invokes ripgrep to search file contents, supporting regular expressions (`pattern`), a search path (`path`), file type filtering (`type`, e.g., `ts`, `py`), glob filtering (`glob`), and output mode (`output_mode`: `files_with_matches` / `content` / `count_matches`; defaults to `files_with_matches`). `content` mode supports context lines (`-A`, `-B`, `-C`), case-insensitive matching (`-i`), line numbers (`-n`, default true), and multiline matching (`multiline`). All modes support `offset` + `head_limit` pagination; `head_limit` defaults to 250 and `0` means unlimited. Sensitive files such as `.env` files and private keys are automatically filtered out; set `include_ignored=true` to search files ignored by `.gitignore`, though sensitive files remain filtered.
+
+**`Glob`** matches files in a specified directory (`path`; defaults to the working directory) by glob pattern (`pattern`). Results are sorted by modification time in descending order, returning 100 entries by default. It respects `.gitignore`, `.ignore`, and `.rgignore` by default; set `include_ignored=true` to include ignored files such as build outputs, while sensitive files remain filtered. Brace patterns such as `*.{ts,tsx}` are supported, and broad wildcard patterns are allowed.
+
+Use `offset` (default 0) and `head_limit` (default 100) to page through matching paths; the result provides the next offset when more matches are available. Set `head_limit: 0` to remove the match-count limit. The character limit still applies: pages end at a complete path and provide the next offset when necessary. Large pages are saved to a file that the agent can read with `Read`. Each call searches the current filesystem again, so file changes can shift results between pages. Timeouts, unreadable directories, or the output capture limit can still leave the search incomplete; the result warns about these cases, and increasing the offset cannot recover uncollected paths.
+
+**`ReadMediaFile`** sends an image or video to the model as multimodal content. It accepts `path`, plus optional image-detail controls such as `region` and `full_resolution`; the file size limit is 100 MB. Default image reads are compressed to the configured model limits. If automatic compression cannot meet those limits safely, the tool returns an error without sending the original image and directs the model to create and read a smaller copy. Availability depends on the current model's vision capabilities (`image_in` / `video_in`).
+
+## Shell
+
+| Tool | Default Approval | Description |
+| --- | --- | --- |
+| `Bash` | Requires approval | Execute a shell command |
+
+**`Bash`** is the most permission-demanding tool and also the most general-purpose. Parameters:
+
+- `command` (required): the shell command to execute
+- `cwd`: working directory
+- `timeout`: timeout in milliseconds; foreground default is 60 seconds, maximum is 5 minutes
+- `run_in_background`: whether to run as a background task; background tasks default to a 10-minute timeout (no timeout by default in print mode `kimi -p`)
+- `description`: background task description; required when `run_in_background=true`
+- `disable_timeout`: whether to remove the timeout limit for background tasks
+
+Foreground mode blocks the current turn until the command completes or times out, and the TUI streams stdout and stderr into the running `Bash` tool card while the command is still active. By default, a foreground command that hits its timeout is not killed — it keeps running as a background task (bounded by the 600s default background timeout); to restore kill-on-timeout, set [`bash_auto_background_on_timeout`](../configuration/config-files.md#background) to `false` under `[background]`. The 600s background default is configurable via [`bash_task_timeout_s`](../configuration/config-files.md#background) (`0` = no timeout) and defaults to no timeout in print mode (`kimi -p`). Background mode returns a task ID immediately and automatically notifies the Agent when the task finishes. stdin is always closed — interactive commands receive EOF immediately. A two-phase termination strategy (SIGTERM → 5-second grace period → SIGKILL) ensures reliable process cleanup when a task is stopped or hits its background timeout. On Windows, Git Bash is used by default.
+
+## Web Tools
+
+| Tool | Default Approval | Description |
+| --- | --- | --- |
+| `WebSearch` | Auto-allow | Web search |
+| `FetchURL` | Auto-allow | Fetch the content of a specified URL |
+
+**`WebSearch`** accepts `query` (search terms). Requires the host to provide a search implementation; when not injected, the tool does not appear in the tool list.
+
+**`FetchURL`** accepts a single `url` parameter and returns the page content. For HTML pages, the host extracts the body text rather than returning the full HTML; plain text or Markdown pages are passed through directly. Also requires a host-provided implementation.
+
+## Plan Mode
+
+| Tool | Default Approval | Description |
+| --- | --- | --- |
+| `EnterPlanMode` | Auto-allow | Enter Plan mode |
+| `ExitPlanMode` | Auto-allow (requires user to confirm the plan) | Exit Plan mode and submit the plan |
+
+Plan mode is a constrained working state: once entered, `Write` and `Edit` are restricted to writing the current plan file only, and `TaskStop` is blocked entirely. All other tools (including `Bash`) are still governed by the current permission rules.
+
+**`EnterPlanMode`** accepts no parameters; upon success it returns workflow guidance and the plan file path.
+
+**`ExitPlanMode`** reads the current plan file, presents the plan to the user for approval, then exits Plan mode. The optional `options` parameter lets the Agent offer 1–3 alternative approaches (each with a `label` and `description`; `label` max 80 characters) for the user to choose from during approval. Labels must be unique and cannot use reserved words such as `Approve`, `Reject`, `Reject and Exit`, or `Revise`.
+
+## State Management
+
+| Tool | Default Approval | Description |
+| --- | --- | --- |
+| `TodoList` | Auto-allow | Manage a task to-do list |
+
+**`TodoList`** maintains a visible subtask list across multi-step operations; state is stored within the Agent session. The `todos` parameter accepts an array where each item has a `title` and `status` (`pending` / `in_progress` / `done`). Omitting `todos` queries the current list; passing an empty array clears it.
+
+## Collaboration Tools
+
+Collaboration tools handle inter-Agent coordination, user interaction, and Skill invocation.
+
+| Tool | Default Approval | Description |
+| --- | --- | --- |
+| `Agent` | Auto-allow | Spawn a sub-Agent to execute a subtask |
+| `AgentSwarm` | Auto-allow in swarm mode; otherwise requires approval | Launch item-based subagents or resume existing subagents |
+| `AskUserQuestion` | Auto-allow | Ask the user a question to gather structured input |
+| `NotifyUser` | Auto-allow | Show the user a short progress update mid-turn |
+| `Skill` | Auto-allow | Invoke a registered inline Skill |
+
+**`Agent`** delegates a subtask to a sub-Agent. Required parameters: `prompt` (complete task description) and `description` (a 3–5 word short summary). Optional parameters: `subagent_type` (defaults to `coder`), `resume` (ID of an existing Agent to resume; mutually exclusive with `subagent_type`), `run_in_background` (defaults to false), and `model` (available when a [subagent model pool](../configuration/config-files.md#subagent-model-pool) is configured — either a `[secondary_model.models]` table or a lone `default_model`: a pool alias, or `"primary"` for the model the caller itself is running; ignored when resuming). Without it, the subagent binds the pool's `default_model`; without a configured pool, subagents always inherit the caller's model. Agent tasks time out after 2 hours by default; the limit is configurable via `[subagent] timeout_ms` in `config.toml` (`0` = no timeout, or the `KIMI_SUBAGENT_TIMEOUT_MS` env var), and defaults to no timeout in print mode (`kimi -p`). In foreground mode the parent Agent waits for the sub-Agent to complete before continuing; in background mode a task ID is returned immediately and the result is automatically delivered back to the main Agent via a synthetic User message when done. When several foreground `Agent` calls run in the same step, the TUI groups them and shows each subagent's running, waiting, completed, or failed status with elapsed time. See [Agent & Sub-Agents](../customization/agents.md) for details.
+
+**`AgentSwarm`** launches subagents from a shared `prompt_template` and an `items` array, resumes existing subagents through `resume_agent_ids`, or combines both in one call. The template must contain the `{{item}}` placeholder; each item replaces that placeholder and launches one new subagent. Pass `subagent_type` to choose the profile used by every spawned subagent in the swarm, or omit it to use `coder`. Pass `model` (available when a [subagent model pool](../configuration/config-files.md#subagent-model-pool) is configured — a `[secondary_model.models]` table or a lone `default_model`) to run item-spawned subagents on a pool alias or on the caller's own model (`"primary"`). Without it, item-spawned subagents bind the pool's `default_model`; without a configured pool, they inherit the caller's model. Resumed subagents keep their own model. Without `resume_agent_ids`, the tool requires at least 2 items; with `resume_agent_ids`, it can resume one or more existing subagents. The tool supports up to 128 total subagents, waits for all subagents to finish, and returns an aggregated report. Each subagent times out after 2 hours by default; the limit is configurable via [`[swarm] timeout_ms`](../configuration/config-files.md#swarm) in `config.toml` (`0` = no timeout, or the `KIMI_CODE_SWARM_TIMEOUT_MS` env var), and defaults to no timeout in print mode (`kimi -p`). A timed-out subagent is aborted and marked as failed in the aggregated report. In the TUI, foreground swarms show a live `Agent swarm` progress panel above the input box. If a model response calls `AgentSwarm`, that call must be the only tool call in the response; to run multiple swarms, call one `AgentSwarm`, wait for its result, then call the next, or combine the work into one swarm when a single template can cover it. In `manual` permission mode, `AgentSwarm` calls outside active swarm mode request approval unless a permission rule allows them; while swarm mode is active, `AgentSwarm` itself is auto-approved. Permission rules match `AgentSwarm` by tool name only — argument patterns such as `AgentSwarm(swarm)` are not supported. By default the tool ramps up concurrency without an upper limit (5 subagents start immediately, then 1 more every 700 ms); set `KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCY` to a positive integer to cap how many subagents run at the same time during that ramp, or leave it unset for no cap. If it is set to a value that is not a positive integer, the AgentSwarm call fails fast.
+
+**`AskUserQuestion`** asks the user a structured multiple-choice question — useful for disambiguation or option selection. The `questions` parameter accepts 1–4 questions; each question requires `question` (ending with `?`), `options` (2–4 choices, each with a `label` and `description`), and optional `header` (max 12 characters) and `multi_select` (defaults to false). An "Other" option is appended automatically. Setting `background` to true starts a background question task and returns a task ID immediately; the question stays open after the turn ends, and the answer is delivered to the Agent as a notification once the user responds. When the host does not support interactive questioning, a failure message is returned and the Agent should ask the user directly in a text reply instead.
+
+**`NotifyUser`** lets the main Agent and subagents send short progress updates using a single `message` parameter with light Markdown. The TUI's `Updates` panel keeps every update in order, including multiple messages from the same source. Subagent messages show their existing agent ID, such as `[agent-7]`, on the same line as the message. Main-agent messages have no prefix. Complete messages remain available through pagination rather than being replaced by a one-line preview.
+
+The panel defaults to the latest page and groups rendered message rows from the end, up to eight per page. For ten one-line updates, the first page contains two and the last page contains eight. Short pages use only the space their content needs. Press `Ctrl-P` for the previous page and `Ctrl-N` for the next page. Paging happens in the panel without changing input focus or the draft, and stops at the first and last pages instead of wrapping. While you read older pages, newly appended updates keep the existing page boundaries and show a count. Returning to the latest page fills it from the end again and resumes following new updates. When there is only one page, these keys retain their normal editor behavior.
+
+Finishing a turn leaves the messages and selected page visible. The next main-agent turn clears them; child turns do not clear the panel. New sessions, `/clear`, and reopening a session start with an empty panel. Updates appear only after a successful tool result confirms display; argument fragments are not shown while awaiting approval. Failed, interrupted, or suppressed notifications do not enter the panel, and the transcript preserves whether each call displayed an update. Important findings still belong in the final reply or the subagent's handoff.
+
+The entire feature is experimental and off by default. Enable it with `KIMI_CODE_EXPERIMENTAL_NOTIFY_USER=1`, `[experimental] notify_user = true` in `config.toml`, or `/experiments` before creating a TUI session. Sessions created while it is disabled have neither the tool nor its prompt guidance.
+
+Existing sessions keep their notification tool availability and prompt unchanged, including after reopening. Turning the feature off hides the panel and disables its paging shortcuts; any existing `NotifyUser` calls finish normally and report that the update was not displayed. Turning it back on restores display for sessions that already have the tool. If a session was created with the feature disabled, start a new session to use Updates. Changing only this flag in `/experiments` does not reload the session.
+
+**`Skill`** allows the Agent to actively invoke a registered inline-type Skill. Accepts `skill` (the Skill name) and optional `args` (additional argument text). Only `type = "inline"` Skills can be called via this tool; Skills with `disableModelInvocation: true` are rejected. Maximum nesting depth is 3 levels. See [Agent Skills](../customization/skills.md) for details.
+
+## Background Tasks
+
+Background task tools manage tasks started via `Bash`, `Agent`, or `AskUserQuestion`. When a task reaches a terminal state, its status and saved output path (or, for questions, the answer itself) are automatically delivered back to the Agent; use `TaskOutput` to check progress early, or `WaitFor` to wait for a result inside the current turn.
+
+| Tool | Default Approval | Description |
+| --- | --- | --- |
+| `TaskList` | Auto-allow | List background tasks |
+| `TaskOutput` | Auto-allow | View the output of a background task |
+| `TaskStop` | Requires approval | Stop a running background task |
+| `WaitFor` | Auto-allow | Wait for background tasks to finish |
+
+**`TaskList`** returns the list of background tasks. Optional parameters: `active_only` (defaults to true; lists only running tasks) and `limit` (defaults to 20; range 1–100).
+
+**`TaskOutput`** returns the status and output of a task given its `task_id`. The inline preview includes at most the most recent 32 KB of content; the full log is saved to disk, and the tool also returns an `output_path` with a suggestion to use `Read` for paginated access. The call is always non-blocking — it returns the current snapshot immediately, and task completion is delivered via automatic notification.
+
+**`TaskStop`** accepts a `task_id` and optional `reason` (defaults to `Stopped by TaskStop`). Safe to call on tasks that are already in a terminal state.
+
+**`WaitFor`** suspends the current turn until a background task finishes, the timeout elapses, or a steer message arrives. Parameters: `timeout` (required, in seconds, max 600) and optional `task_id`. Without `task_id`, the wait ends as soon as any background task that was running at call time finishes; when no background tasks are running, it returns immediately. A timeout is not an error — the result lists the tasks still running, and the Agent can wait again or do other work meanwhile. Steering (`Ctrl-S` in the terminal) ends the wait early; background tasks keep running and still notify the agent on completion. A task whose result was reported by `WaitFor` does not also produce an automatic completion notification.
+
+## Scheduled Tasks
+
+Scheduled task tools allow the Agent to re-inject a prompt into the current session at a future time — either as a one-time reminder or as a recurring cron-triggered task (periodic checks, daily reports, deployment monitoring, etc.). Schedules are bound to the session and remain active when you resume it with `kimi --session`, but are not carried into a brand-new session. A single session can hold at most 50 active scheduled tasks. Set `KIMI_DISABLE_CRON=1` to disable them entirely; see [Environment Variables](../configuration/env-vars.md#runtime-switches).
+
+| Tool | Default Approval | Description |
+| --- | --- | --- |
+| `CronCreate` | Requires approval | Schedule a prompt to fire at a future time |
+| `CronList` | Auto-allow | List scheduled tasks |
+| `CronDelete` | Requires approval | Cancel a scheduled task |
+
+**`CronCreate`** accepts `cron` (a standard 5-field cron expression in the user's local timezone: `minute hour day-of-month month day-of-week`), `prompt` (the text to inject when triggered; UTF-8 limit 8 KB), and optional `recurring` (defaults to `true`; pass `false` for a one-time reminder that auto-deletes after firing). On success, returns an 8-hex-digit `id`, a human-readable `humanSchedule` (e.g., `every 5 minutes`), and `nextFireAt` (the ISO timestamp of the next fire time).
+
+To prevent all users from firing at the same time on the hour, the scheduler applies deterministic jitter: recurring tasks are shifted forward by `min(10% of the period, 15 minutes)`; one-time tasks that fall exactly on `:00` or `:30` are moved forward by up to 90 seconds. If the scheduler misses several fire times (e.g., because the laptop was sleeping), it fires only once on wake-up — the prompt is wrapped in a `<cron-fire>` envelope with a `coalescedCount`. Recurring tasks that have been alive for more than 7 days fire one final time with `stale="true"` and are then automatically deleted; call `CronCreate` again to keep them.
+
+**`CronList`** is a read-only tool that accepts no parameters. It returns one record per active task with fields: `id`, `cron`, `humanSchedule`, `nextFireAt`, `recurring`, `ageDays`, and `stale`. Records are separated by `---` and sorted by schedule time.
+
+**`CronDelete`** accepts a single `id`. For recurring tasks, all future fires stop immediately; for one-time tasks, the pending fire is cancelled. One-time tasks that have already fired are auto-deleted, so calling `CronDelete` on an already-fired one-time task returns `No cron job with id ...`. Deletion is irreversible — use `CronCreate` again to restore. `CronDelete` is also blocked in Plan mode.
+
+## Next steps
+
+- [Agent & Sub-Agents](../customization/agents.md) — Scheduling mechanics and context isolation for the `Agent` tool
+- [Hooks](../customization/hooks.md) — Trigger local scripts before and after tool calls
+- [Slash Commands](./slash-commands.md) — Quick reference for TUI built-in control commands