Kimi For Coding

2026-07-09 17:29:12 +00:00 · 2026-05-22 15:54:50 +08:00 · 2026-05-22 15:54:50 +08:00 · 842e699a64
commit 842e699a64
1131 changed files with 206253 additions and 0 deletions
--- a/docs/.gitignore
+++ b/docs/.gitignore
@ -0,0 +1,3 @@
+node_modules
+.vitepress/dist
+.vitepress/cache
--- a/docs/.npmrc
+++ b/docs/.npmrc
@ -0,0 +1 @@
+shamefully-hoist=true
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@ -0,0 +1,184 @@
+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}/`
+  : '/'
+
+export default 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/faq' },
+          { 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' },
+              ],
+            },
+          ],
+          '/zh/customization/': [
+            {
+              text: '定制化',
+              items: [
+                { text: 'Model Context Protocol', link: '/zh/customization/mcp' },
+                { text: 'Agent Skills', link: '/zh/customization/skills' },
+                { text: 'Agent 与子 Agent', link: '/zh/customization/agents' },
+                { text: 'Hooks', link: '/zh/customization/hooks' },
+              ],
+            },
+          ],
+          '/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: '内置工具', 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: 'FAQ', link: '/en/faq' },
+          { 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' },
+              ],
+            },
+          ],
+          '/en/customization/': [
+            {
+              text: 'Customization',
+              items: [
+                { text: 'Model Context Protocol', link: '/en/customization/mcp' },
+                { text: 'Agent Skills', link: '/en/customization/skills' },
+                { text: 'Agents and Subagents', link: '/en/customization/agents' },
+                { text: 'Hooks', link: '/en/customization/hooks' },
+              ],
+            },
+          ],
+          '/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: '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: {
+    plugins: [llmstxt()],
+  },
+}))
--- a/docs/.vitepress/theme/Kimi.png
+++ b/docs/.vitepress/theme/Kimi.png
--- a/docs/.vitepress/theme/components/HomeFeatures.vue
+++ b/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>
--- a/docs/.vitepress/theme/components/HomeHero.vue
+++ b/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>
--- a/docs/.vitepress/theme/components/HomeLayout.vue
+++ b/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>
--- a/docs/.vitepress/theme/components/HomeQuickStart.vue
+++ b/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>
--- a/docs/.vitepress/theme/components/KimiLogo.vue
+++ b/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>
--- a/docs/.vitepress/theme/index.ts
+++ b/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
--- a/docs/.vitepress/theme/styles/base.css
+++ b/docs/.vitepress/theme/styles/base.css
@ -0,0 +1,231 @@
+/**
+ * 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;
+}
--- a/docs/.vitepress/theme/styles/home.css
+++ b/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);
+}
--- a/docs/.vitepress/theme/styles/vars.css
+++ b/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);
+}
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@ -0,0 +1,179 @@
+# Documentation Agent Guide
+
+This repository uses VitePress for the documentation site. Most user-facing pages under `docs/en/` and `docs/zh/` are fully written; New or updated content should keep both locales in sync.
+
+## Structure
+
+- Locales live under `docs/en/` and `docs/zh/` with mirrored paths and filenames.
+- Main sections (nav + sidebar) are:
+  - Guides: getting-started, migration, use-cases, interaction, sessions
+  - Customization: mcp, skills, agents, hooks
+  - Configuration: config-files, providers, overrides, env-vars, data-locations
+  - Reference: kimi-command, tools, slash-commands, keyboard
+  - FAQ
+  - Release notes: changelog
+- Navigation and sidebar are defined in `docs/.vitepress/config.ts`. Any new or renamed page must be wired there for both locales.
+
+## Source of truth
+
+- **Changelog page**: The English version (`docs/en/release-notes/changelog.md`) is the source of truth; the Chinese changelog should be translated from it. The changelog is currently generated manually by a skill that syncs from the CLI package's `CHANGELOG.md` after each release.
+- **All other pages**: `docs/en/` and `docs/zh/` are mirrored pairs with the same paths, headings, and section structure. Edit whichever locale you are working in, and update the other locale in the same change.
+
+Keep both locales in sync before release. Machine-assisted translation is fine; review the locale you changed and its mirror for accuracy, terminology, and broken links.
+
+## Authoring workflow
+
+- Each page should keep the section ordering established by surrounding pages. Changelog and FAQ are exceptions until their placeholder content is replaced.
+- For other pages: edit either locale, then update its mirror in the same change.
+
+## Naming conventions
+
+- Filenames are kebab-case and mirror across locales (same slug in `docs/en/` and `docs/zh/`).
+- Use consistent section labels that match the sidebar titles.
+- Use backticks for flags, commands, subcommands, command arguments, file paths, code identifiers, type names, field names, field values, and keyboard shortcuts.
+
+## Wording conventions
+
+- Do not change H1 titles or nav/sidebar labels.
+- English H2+ headings use sentence case (only the first word capitalized unless it is a proper noun). Treat "Wire", "Plan mode", "YOLO mode", and "Thinking mode" as proper nouns; do not treat "agent" as a proper noun.
+- Chinese H2+ headings keep English words in sentence case; preserve proper nouns listed in the term table below.
+- Use `API key` in English and `API 密钥` in Chinese; keep `JSON`, `JSONL`, `OAuth`, `macOS`, `Node.js`, `npm`, `pnpm`, and `TypeScript` as-is.
+- Use straight double quotes with spaces for quoted content: `"被引内容"` (not curly quotes). Add a space before and after the quoted text when adjacent to CJK characters. Use corner brackets `「」` for special terms (e.g., `「工具」`, `「会话」`).
+- Prefer "终端" over "命令行" in Chinese when both are applicable (e.g., "运行在终端中", "终端界面", "终端操作").
+- Use "工具调用" / "tool call", not "工具使用" / "tool use".
+- Use inline code for tool names (e.g., `Read`, `Grep`, `Bash`).
+
+Term mapping (Chinese <-> English, and proper noun handling):
+
+| Chinese | English | Proper noun (zh) | Proper noun (en) |
+| --- | --- | --- | --- |
+| Agent | agent | yes | no |
+| 主 Agent | main agent | yes (Agent) | no |
+| 子 Agent | subagent | yes (Agent) | no |
+| Shell | shell | yes | no |
+| Plan 模式 | Plan mode | yes | yes (Plan mode) |
+| YOLO 模式 | YOLO mode | yes | yes (YOLO mode) |
+| Thinking 模式 | Thinking mode | yes | yes (Thinking mode) |
+| MCP | MCP | yes | yes |
+| Kimi Code CLI | Kimi Code CLI | yes | yes |
+| Agent Skills | Agent Skills | yes | yes |
+| Skill | skill | yes | no |
+| 系统提示词 | system prompt | no | no |
+| 提示词 | prompt | no | no |
+| 会话 | session | no | no |
+| 上下文 | context | no | no |
+| API 密钥 | API key | yes | no |
+| JSON | JSON | yes | yes |
+| JSONL | JSONL | yes | yes |
+| OAuth | OAuth | yes | yes |
+| macOS | macOS | yes | yes |
+| TypeScript | TypeScript | yes | yes |
+| Node.js | Node.js | yes | yes |
+| npm | npm | yes | yes |
+| pnpm | pnpm | yes | yes |
+| kimi | kimi | yes | yes |
+| 审批请求 | approval request | no | no |
+| 斜杠命令 | slash command | no | no |
+| 工具调用 | tool call | no | no |
+| Frontmatter | frontmatter | yes | no |
+| User 消息 | user message | yes (User) | no |
+| Assistant 消息 | assistant message | yes (Assistant) | no |
+| Tool 消息 | tool message | yes (Tool) | no |
+| 轮次 | turn | no | no |
+| 供应商 | provider | no | no |
+| Prompt Flow | Prompt Flow | yes | yes |
+| Diff | diff | yes | no |
+
+## Typography
+
+- **Spacing around mixed content**: Add a space between Chinese characters and English words, numbers, inline code, or links. Exception: no space before full-width punctuation.
+  - ✓ 在 TypeScript 中使用 `class` 关键字
+  - ✗ 在TypeScript中使用`class`关键字
+  - ✓ 详见 [配置文件](./config.md)。
+  - ✗ 详见[配置文件](./config.md)。
+- **Full-width punctuation**: Use full-width punctuation in Chinese text: `，。；：？！（）` not `, . ; : ? ! ( )`.
+- **Keyboard shortcuts**: Use hyphen between modifier and key (`Ctrl-C`, `Ctrl-D`, `Shift-Tab`, `Alt-V`), not plus sign. Exception: literal application output (e.g., the `Press Ctrl+C again to exit` hint produced by the product itself) keeps its exact rendering.
+- **Code block language**: Always specify language for fenced code blocks (e.g., ` ```sh `, ` ```toml `, ` ```json `, ` ```ts `). Exception: natural language examples (user prompts) may omit the language.
+- **Callout titles**: Use short category titles for callout blocks (`::: tip`, `::: warning`, `::: info`, `::: danger`). Put the detailed description in the block content, not the title.
+  - Chinese: use `提示` for tip, `注意` for warning, `说明` for info, `警告` for danger.
+  - English: use no title or short words like `Note` for warning.
+  - ✓ `::: tip 提示` + content starting with the key point
+  - ✓ `::: warning 注意` + content `\`KIMI_CODE_HOME\` 不影响 Skills 的搜索路径。...`
+  - ✗ `::: warning 不影响 Skills` (title too long, should be in content)
+  - ✗ `::: tip Skills 路径独立于 KIMI_CODE_HOME` (title too long)
+- **Version info blocks**: For version change callouts, use `::: info` with a category title (Added/Changed/Removed in English; 新增/变更/移除 in Chinese). The content should be a complete sentence.
+  - ✓ `::: info 新增` + content `新增于 0.2.0。`
+  - ✗ `::: info 新增于 0.2.0` (title too long)
+  - ✓ `::: info Changed` + content `Renamed in 0.2.0. ...`
+  - ✗ `::: info Renamed in 0.2.0` (title too long)
+
+## Writing style
+
+- **Natural narrative**: Organize content like writing an article, guiding readers smoothly through the material.
+- **Avoid fragmentation**: Don't turn every point into a subheading; use paragraph transitions instead.
+- **Global perspective**: "Getting Started" introduces core concepts only; detailed usage belongs in later pages.
+- **Progressive depth**: Guides → Customization → Configuration → Reference, information deepens gradually.
+- **No "next steps"**: VitePress already provides prev/next navigation; don't add manual `::: tip 接下来` blocks at page end.
+
+### Example: good vs bad
+
+Outline prompt:
+
+```
+* Install and upgrade
+  * System requirements: Node.js 24.15.0+, recommend pnpm
+  * Install, upgrade, uninstall steps
+```
+
+**Bad** (mechanical conversion to headings):
+
+```markdown
+## Install and upgrade
+
+### System requirements
+
+- Node.js 24.15.0+
+- Recommend pnpm
+
+### Install
+
+...
+
+### Upgrade
+
+...
+```
+
+**Good** (natural narrative):
+
+```markdown
+## Install and upgrade
+
+Kimi Code CLI requires Node.js 24.15.0 or later. We recommend using pnpm for installation and management.
+
+If you haven't installed pnpm yet, please refer to the pnpm installation docs first. Install Kimi Code CLI:
+
+(code block)
+
+Verify the installation:
+
+(code block)
+
+Upgrade to the latest version:
+
+(code block)
+```
+
+## Build and preview
+
+- Docs are built with VitePress from `docs/`.
+- Common commands (run inside `docs/`):
+  - `npm install`
+  - `npm run dev`
+  - `npm run build`
+  - `npm run preview`
+- The build output is `docs/.vitepress/dist`.
+
+## Changelog syncing
+
+See `sync-changelog` skill for the changelog generation workflow.
--- a/docs/en/configuration/config-files.md
+++ b/docs/en/configuration/config-files.md
@ -0,0 +1,230 @@
+# Config files
+
+Kimi Code CLI stores its global configuration in a single TOML file that covers API providers, model aliases, agent loop parameters, background tasks, external services, and more. This page describes the location of the config file, its top-level fields, each nested structure, and a complete example.
+
+## Config file location
+
+The default config file is located at `~/.kimi-code/config.toml`. The directory and file are created automatically on first run with restrictive permissions.
+
+If you want to place the data directory elsewhere, set 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`, `max_context_size`). If a key contains `.`, you must use a quoted TOML key; otherwise TOML will treat `.` as a nested table separator.
+:::
+
+## Top-level fields
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `default_model` | `string` | — | Default model alias; must be defined in `models` |
+| `default_thinking` | `boolean` | `false` | Initial value of the Thinking toggle for new sessions; can be flipped from the model menu inside a session. Even when this is `true`, setting `[thinking].mode = "off"` will still force Thinking off. See [`thinking`](#thinking) below |
+| `default_permission_mode` | `string` | `manual` | Default permission mode for new sessions; one of `manual`, `auto`, `yolo` |
+| `default_plan_mode` | `boolean` | `false` | Whether new sessions start in Plan mode by default; omitting it is equivalent to `false` |
+| `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 |
+| `telemetry` | `boolean` | `true` | Whether anonymous telemetry is enabled; only disabled when explicitly set to `false` |
+| `providers` | `table` | `{}` | API provider table; see below |
+| `models` | `table` | — | Model alias table; see below |
+| `thinking` | `table` | — | Default parameters for Thinking mode |
+| `loop_control` | `table` | — | Agent loop control parameters |
+| `background` | `table` | — | Background task runtime parameters |
+| `services` | `table` | — | Built-in external service configuration |
+| `permission` | `table` | — | Permission rule configuration; see below |
+| `hooks` | `array<table>` | — | Lifecycle hook configuration. See [Hooks](../customization/hooks.md) |
+
+## Complete example
+
+```toml
+default_model = "kimi-code/kimi-for-coding"
+default_thinking = true
+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/kimi-for-coding"]
+provider = "managed:kimi-code"
+model = "kimi-for-coding"
+max_context_size = 262144
+
+[thinking]
+mode = "auto"
+
+[loop_control]
+max_steps_per_turn = 1000
+max_retries_per_step = 3
+reserved_context_size = 50000
+
+[background]
+max_running_tasks = 4
+keep_alive_on_exit = false
+agent_task_timeout_s = 900
+
+[[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
+```
+
+## `providers`
+
+Each entry in the `providers` table defines the connection info for one API provider, keyed by a unique name.
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `type` | `string` | Yes | Provider type; one of `anthropic`, `openai`, `kimi`, `google-genai`, `openai_responses`, `vertexai` |
+| `api_key` | `string` | No | API key |
+| `base_url` | `string` | No | API base URL |
+| `oauth` | `table` | No | OAuth credential reference; see below |
+| `env` | `table<string, string>` | No | A configuration sub-table keyed by provider-specific names (such as `KIMI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_CLOUD_PROJECT`), used as fallback values for `api_key` / `base_url` and related fields. This is just a sub-table inside the config file — **it is not written into your shell environment** — and is consulted only when the corresponding field on `[providers.<name>]` is unset |
+| `custom_headers` | `table<string, string>` | No | Custom HTTP headers attached to each request |
+
+OAuth credential reference structure:
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `storage` | `string` | Yes | Credential storage location; currently only `file` is supported |
+| `key` | `string` | Yes | Unique identifier of the credential entry |
+
+```toml
+[providers.openai]
+type = "openai"
+base_url = "https://api.openai.com/v1"
+api_key = "sk-xxx"
+custom_headers = { "X-Custom-Header" = "value" }
+```
+
+## `models`
+
+Each entry in the `models` table defines a model alias, 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 used when calling the API |
+| `max_context_size` | `integer` | Yes | Maximum context length in tokens; must be at least 1 |
+| `max_output_size` | `integer` | No | Per-request output budget cap (`max_tokens` on the wire). Only the `anthropic` provider currently honors it. When the alias resolves to a known Claude family, the value is clamped to that model's documented ceiling to avoid exceeding the server-side limit. Omit to use the per-model default — see [`providers.md`](./providers.md#anthropic). |
+| `capabilities` | `array<string>` | No | Capability tags to add explicitly, for example `thinking`, `image_in`, `video_in`, `audio_in`, `tool_use` |
+| `display_name` | `string` | No | Name shown in the UI; falls back to `model` when unset |
+
+`capabilities` is unioned with the capabilities that the provider capability registry matches by model-name prefix — entries can only be added, never removed. You usually do not need to set this by hand; reach for it only when the model is not covered by the registry, or when you want to force-enable a particular capability.
+
+If a model alias contains `.`, use a quoted key:
+
+```toml
+[models."gpt-4.1"]
+provider = "openai"
+model = "gpt-4.1"
+max_context_size = 1047576
+```
+
+## `thinking`
+
+`thinking` controls the default behavior of Thinking mode. Even when the top-level `default_thinking = true`, setting `mode` to `"off"` will still force Thinking off.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `mode` | `string` | — | Trigger policy; one of `auto`, `on`, `off`. `"off"` forces Thinking off; any other value or omission does not disable it, and the effective behavior is decided together by the per-session Thinking toggle and `effort` |
+| `effort` | `string` | `high` | Default effort level used when Thinking is on; one of `low`, `medium`, `high`, `xhigh`, `max`. The levels actually available depend on the provider |
+
+## `loop_control`
+
+`loop_control` governs the step count, retries, and context compaction threshold of the agent execution loop.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `max_steps_per_turn` | `integer` | `1000` | Maximum number of steps per turn |
+| `max_retries_per_step` | `integer` | `3` | Maximum retries per step |
+| `reserved_context_size` | `integer` | — | Number of tokens reserved for response generation; compaction is triggered when the context approaches this threshold |
+
+
+
+## `background`
+
+`background` controls the runtime limits for background tasks. Background tasks are launched through 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` | `true` | Whether to keep still-running background tasks when the session closes. Set to `false` to request stopping background tasks when `kimi -p` finishes and exits, when an SDK session closes, or when a harness closes |
+| `agent_task_timeout_s` | `integer` | — | Maximum runtime in seconds for background agent tasks |
+
+`keep_alive_on_exit` can be overridden by the `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` environment variable; the environment variable has higher priority than `config.toml`. The schema also reserves `kill_grace_period_ms` and `print_wait_ceiling_s`; these fields currently pass schema validation only and are not read by the CLI runtime.
+
+## `services`
+
+`services` configures the built-in external services Kimi Code CLI calls. Only the two fixed keys `moonshot_search` (web search) and `moonshot_fetch` (web fetch) 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 |
+
+```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` configures the initial permission rules loaded when a session starts, controlling the default approval behavior for tool calls. The default permission mode for new sessions is controlled by the top-level `default_permission_mode` field; an explicit startup permission mode, such as the CLI's `--yolo` flag, overrides that default.
+
+Rules are written as a `[[permission.rules]]` array of tables, where each rule contains the following fields:
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `decision` | `string` | Yes | Decision result; one of `allow`, `deny`, `ask` |
+| `scope` | `string` | No | Rule scope; one of `turn-override`, `session-runtime`, `project`, `user`; defaults to `user` |
+| `pattern` | `string` | Yes | Match pattern in the form `ToolName` or `ToolName(arg-pattern)`. `ToolName` must match the runtime tool name exactly — built-in tools are `Read`, `Write`, `Edit`, `Bash`, `Grep`, and so on (see [Built-in tools](../reference/tools.md)) |
+| `reason` | `string` | No | Rule description for debugging or auditing |
+
+Example:
+
+```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).
+:::
--- a/docs/en/configuration/data-locations.md
+++ b/docs/en/configuration/data-locations.md
@ -0,0 +1,131 @@
+# Data Locations
+
+Kimi Code CLI stores its runtime data centrally under the `~/.kimi-code/` directory in the user's home folder. This page describes where each type of data lives, what it is for, and how to customize or clean it up.
+
+## Data root
+
+The default data root is `~/.kimi-code/`. The `~` is resolved by Node.js's `os.homedir()`, so the actual path differs slightly across platforms: on macOS it is `/Users/<name>/.kimi-code`, on Linux `/home/<name>/.kimi-code`, and on Windows `C:\Users\<name>\.kimi-code`.
+
+You can override it to any path with the `KIMI_CODE_HOME` environment variable:
+
+```sh
+export KIMI_CODE_HOME="$HOME/.config/kimi-code"
+```
+
+Once set, runtime data such as the config, sessions, logs, input history, update cache, and OAuth credentials lands under that path. For the full reference on `KIMI_CODE_HOME` and other environment variables, see [Environment variables](./env-vars.md).
+
+::: tip Exceptions
+The **built-in tool cache** (such as the auto-downloaded ripgrep binary) does not follow `KIMI_CODE_HOME`. It uses `KIMI_CODE_CACHE_DIR`, falling back to a platform cache directory — `~/Library/Caches/kimi-code` on macOS, `$XDG_CACHE_HOME/kimi-code` (default `~/.cache/kimi-code`) on Linux, and `%LOCALAPPDATA%\kimi-code` on Windows.
+
+User-level Agent Skills search directories live at `~/.kimi-code/skills` and `~/.agents/skills`; project-level Skills live under the working directory at `.kimi-code/skills` and `.agents/skills`. See [Agent Skills](../customization/skills.md) for details.
+:::
+
+## Directory layout
+
+A typical layout under the data root looks like:
+
+```
+$KIMI_CODE_HOME  (default ~/.kimi-code)
+├── config.toml             # User config
+├── mcp.json                # User-level MCP server declarations (optional)
+├── session_index.jsonl     # Session index
+├── credentials/            # OAuth credential root (directory 0o700, files 0o600)
+│   ├── <name>.json         # Hosted Kimi / Open Platform provider OAuth credentials
+│   └── mcp/                # MCP server OAuth credentials
+│       └── <key>-<suffix>.json
+├── sessions/               # Session data
+│   └── <workDirKey>/
+│       └── <sessionId>/
+│           ├── state.json
+│           ├── logs/
+│           │   └── kimi-code.log
+│           ├── tasks/          # Background task persistence
+│           │   ├── <task_id>.json
+│           │   └── <task_id>/
+│           │       └── output.log
+│           └── agents/
+│               ├── main/
+│               │   ├── wire.jsonl
+│               │   └── plans/  # Plan mode plan files
+│               └── agent-0/
+│                   └── wire.jsonl
+├── bin/
+│   └── rg                  # ripgrep cache (rg.exe on Windows)
+├── logs/                   # Global diagnostic logs
+│   └── kimi-code.log
+├── updates/
+│   └── latest.json         # Update check status
+└── user-history/
+    └── <md5(workDir)>.jsonl
+```
+
+::: tip
+The tree above shows a typical layout under the default data root (`~/.kimi-code/`). The paths for Agent Skills and the built-in tool cache have some special cases — see the "Exceptions" note above.
+:::
+
+## Config files
+
+`config.toml` is Kimi Code CLI's main config file, holding user-level settings such as providers, models, and loop control. See [Config files](./config-files.md) for details.
+
+`mcp.json` holds user-level MCP server declarations and is merged with the project-local `.kimi-code/mcp.json` at load time. The fields are the same as the project-level file; see [MCP](../customization/mcp.md) for details.
+
+OAuth credentials are stored as files under the `credentials/` subdirectory of the data root. The parent directory uses mode `0o700` and each credential file uses mode `0o600`, readable and writable only by the current user. There are two sub-locations:
+
+- **Hosted Kimi / Open Platform provider OAuth credentials** live at `credentials/<name>.json`, for example `~/.kimi-code/credentials/managed:kimi-code.json`.
+- **MCP server OAuth credentials** live under the `credentials/mcp/` subdirectory, with file names generated from the server key, for example `credentials/mcp/<key>-<suffix>.json`.
+
+Writes follow a `tmp → fsync → rename` atomic flow: strictly atomic on POSIX, best-effort on Windows.
+
+## Session data
+
+Session-related data is grouped under `sessions/`, with a top-level `session_index.jsonl` maintaining a JSONL index: one record per line containing the three fields `sessionId`, `sessionDir`, and `workDir`. Entries are appended when a session is created. When the index is loaded, each entry is validated to ensure `sessionDir` still lives under `sessions/` and that its last path component equals `sessionId`, preventing external tampering from pointing entries to illegal paths.
+
+Each session directory has a path like `sessions/<workDirKey>/<sessionId>/`, where `workDirKey` is a bucket name encoded from the working directory in the format `wd_<slug>_<first-12-chars-of-sha256>` (for example, `wd_myproject_a3f8c1d20e9b`), and `sessionId` is the session's unique identifier. The full path under `sessions/`, including each `<workDirKey>/` bucket, is created with mode `0o700` and accessible only by the current user.
+
+The internal structure of a session directory includes:
+
+- `state.json`: session title, `lastPrompt`, `createdAt`, `updatedAt`, `isCustomTitle`, `forkedFrom`, and metadata for each agent.
+- `agents/main/wire.jsonl`: the Wire event stream of the main agent, used for replay and resumption. `main` is the fixed id of the main agent.
+- `agents/main/plans/`: plan files written by the main agent in Plan mode, named `<id>.md` by plan id.
+- `agents/agent-0/`, `agents/agent-1/`, etc.: subagent instance directories, each with its own `wire.jsonl`. Subagent ids are generated by a per-session incrementing counter (`agent-` followed by an integer starting from 0).
+- `logs/kimi-code.log`: the diagnostic log for this session. It only appears after a recorded diagnostic event; an ordinary conversation may not create this file.
+- `tasks/`: background task persistence directory. Each task stores its metadata (status, pid, exit code, etc.) in `tasks/<task_id>.json`, with stdout and stderr written to `tasks/<task_id>/output.log`. Task ids use a `bash-` or `agent-` prefix followed by 8 random alphanumeric characters (for example, `bash-a1b2c3d4`).
+
+`sessionId` is restricted to `[A-Za-z0-9._-]+` and cannot be `.` or `..`, preventing path injection. The session list is sorted by `updatedAt` in descending order, where `updatedAt` is the maximum mtime of the directory and its key files. See [Sessions](../guides/sessions.md) for details.
+
+## Built-in tool cache
+
+The first time Kimi Code CLI needs ripgrep, it downloads and caches it automatically. During the download, the archive is written to the system temporary directory and verified by SHA-256 before extraction; the binary is then installed directly to `bin/rg` under the data root (or `bin/rg.exe` on Windows) and marked `0o755` so it can be executed. Subsequent runs under the same data root reuse it with no further download. If `rg` is already on the system `PATH`, the system version takes precedence; deleting `bin/` triggers a redownload the next time it is needed.
+
+## Logs and update state
+
+The top-level `logs/kimi-code.log` is the global diagnostic log. It mainly records issues that do not belong to a single session, such as startup, login, and export failures. A single session's diagnostic log lives at `<sessionDir>/logs/kimi-code.log`.
+
+When filing a bug report, prefer `kimi export` for the relevant session (see [The kimi command](../reference/kimi-command.md) for details). If a session log exists, it is included in the export by default. The global diagnostic log is also bundled by default; because it may contain events from other sessions or projects, use `--no-include-global-log` when you do not want to share it.
+
+`updates/latest.json` records the version update status detected via npm and is maintained automatically by the CLI — there is usually no need to edit it by hand.
+
+## Input history
+
+Command input history from the terminal is saved per working directory. Each working directory corresponds to one file, at `user-history/<md5(workDir)>.jsonl`, where the file name is the MD5 hash of the working directory string (UTF-8 encoded). The file format is JSONL, with one history record per line.
+
+Input history is used to browse and search previously entered prompts in the terminal interface.
+
+## Cleaning up data
+
+Deleting the data root directory (default `~/.kimi-code/`, or the path specified by `KIMI_CODE_HOME`) wipes all of Kimi Code CLI's runtime data, including config, sessions, logs, input history, and the built-in tool cache.
+
+To clean up only part of the data:
+
+| Goal | Action |
+| --- | --- |
+| Reset config | Delete `~/.kimi-code/config.toml` |
+| Clear all sessions | Delete `~/.kimi-code/sessions/` and `~/.kimi-code/session_index.jsonl` |
+| Clear diagnostic logs | Delete the `~/.kimi-code/logs/` directory |
+| Clear input history | Delete the `~/.kimi-code/user-history/` directory |
+| Reset update check state | Delete `~/.kimi-code/updates/latest.json` |
+| Force a ripgrep redownload | Delete the `~/.kimi-code/bin/` directory |
+| Clear hosted Kimi / Open Platform OAuth login state | Run `/logout` (clears only the current provider's OAuth), or delete the corresponding `~/.kimi-code/credentials/<name>.json` |
+| Clear MCP server OAuth login state | Delete the `~/.kimi-code/credentials/mcp/` directory; `/logout` **does not** clear MCP OAuth credentials |
+| Remove user-level MCP declarations | Delete `~/.kimi-code/mcp.json` |
+| Clear user-level Skills | Delete the `~/.kimi-code/skills/` directory |
--- a/docs/en/configuration/env-vars.md
+++ b/docs/en/configuration/env-vars.md
@ -0,0 +1,124 @@
+# Environment variables
+
+Kimi Code CLI uses environment variables to override default paths, switch OAuth endpoints, and adjust runtime behavior. Most variables are read when the `kimi` process starts up; a few (such as the telemetry switch, the OAuth lock, and diagnostic logging) are read when the relevant subsystem initializes. Kimi's own variables use the `KIMI_*` prefix; in addition, the CLI also reads a number of standard system variables.
+
+::: warning Note
+**Provider credentials are not in this list**: key variables such as `KIMI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and `GOOGLE_API_KEY` are **not** read automatically from `process.env`. They must be written into the `[providers.<name>]` section of `config.toml` (as `api_key` / `base_url`) or into the `[providers.<name>.env]` subtable; merely `export`ing them in your shell will not give a provider credentials automatically. See [Configuration overrides](./overrides.md#provider-credentials) and [Providers](./providers.md) for details.
+:::
+
+## Core paths
+
+`KIMI_CODE_HOME` overrides Kimi Code CLI's data root directory, defaulting to `~/.kimi-code`. The CLI's own application data, `kimi-core`'s config, the ripgrep cache, and OAuth credentials all land under this directory.
+
+```sh
+export KIMI_CODE_HOME="/path/to/custom/kimi-code"
+```
+
+For details on the data layout, see [Data locations](./data-locations.md).
+
+::: warning Note
+Make sure the directory is writable once you set it. Multiple `kimi` instances that share the same `KIMI_CODE_HOME` will share both the config and credential files.
+:::
+
+## Provider credential key names
+
+The following key names appear in the `[providers.<name>.env]` subtable of `config.toml`, where they serve as fallback sources for the provider's `api_key` / `base_url`. **The main `kimi` process does not read them directly from `process.env`**; only the values keyed under a `[providers.<name>.env]` subtable are recognized by the provider clients. See [Configuration overrides: provider credentials](./overrides.md#provider-credentials) for the full resolution order.
+
+| Key name | Applicable provider | Purpose | Default |
+| --- | --- | --- | --- |
+| `KIMI_API_KEY` | Kimi / Moonshot | API key | None |
+| `KIMI_BASE_URL` | Kimi / Moonshot | API base URL | `https://api.moonshot.ai/v1` |
+| `ANTHROPIC_API_KEY` | Anthropic | API key | None |
+| `ANTHROPIC_BASE_URL` | Anthropic | API base URL | Follows the Anthropic SDK default |
+| `OPENAI_API_KEY` | OpenAI (used by both `openai` and `openai_responses`) | API key | None |
+| `OPENAI_BASE_URL` | OpenAI (used by both `openai` and `openai_responses`) | API base URL | `https://api.openai.com/v1` |
+| `GOOGLE_API_KEY` | Google GenAI, Vertex AI (as a fallback for `VERTEXAI_API_KEY`) | API key | None |
+| `VERTEXAI_API_KEY` | Vertex AI | API key (when not using ADC) | None |
+| `GOOGLE_CLOUD_PROJECT` | Vertex AI | GCP project ID | None |
+| `GOOGLE_CLOUD_LOCATION` | Vertex AI | GCP region | None |
+
+For example, to pre-populate Kimi credentials in `config.toml`:
+
+```toml
+[providers.kimi.env]
+KIMI_API_KEY = "sk-xxx"
+KIMI_BASE_URL = "https://api.moonshot.ai/v1"
+```
+
+::: warning Note
+`GOOGLE_APPLICATION_CREDENTIALS` (the path to a service-account JSON file) is read by the Google SDK itself from the shell environment, making it the **only** key in this group that goes through a system environment variable. It follows Google Cloud's standard ADC flow, and the CLI is not involved in resolving it. Every other key only takes effect when written into a `[providers.<name>.env]` subtable.
+:::
+
+For the full description of provider types and fields, see [Providers](./providers.md).
+
+## OAuth and the hosted service
+
+The OAuth flow connects to Kimi's official authentication and hosted endpoints by default. The variables below can point them at a self-hosted or test environment.
+
+| Environment variable | Purpose | Default |
+| --- | --- | --- |
+| `KIMI_CODE_OAUTH_HOST` | OAuth authentication host; takes the highest precedence | — (falls back to `KIMI_OAUTH_HOST`, then to the hardcoded default below) |
+| `KIMI_OAUTH_HOST` | OAuth authentication host; used as a fallback for `KIMI_CODE_OAUTH_HOST` | — (falls back to the hardcoded default below) |
+| `KIMI_CODE_BASE_URL` | Base URL of the hosted Kimi API, used for API calls after OAuth login | `https://api.kimi.com/coding/v1` |
+
+When neither `KIMI_CODE_OAUTH_HOST` nor `KIMI_OAUTH_HOST` is set, the OAuth authentication host uses the hardcoded constant `https://auth.kimi.com`.
+
+::: warning Note
+`KIMI_CODE_BASE_URL` and the `KIMI_BASE_URL` from the previous section are two different variables: the former targets the OAuth-logged-in hosted service and defaults to `kimi.com`; the latter targets providers that use a Kimi API key directly and defaults to `moonshot.ai`. Distinguish them by use case.
+:::
+
+## Runtime switches
+
+| Environment variable | Purpose | Valid values / Default |
+| --- | --- | --- |
+| `KIMI_DISABLE_TELEMETRY` | Disable telemetry reporting | `1`, `true`, `t`, `yes`, `y` (case-insensitive) |
+| `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` | Override `[background].keep_alive_on_exit`, controlling whether still-running background tasks are kept when the session closes | True values: `1`, `true`, `yes`, `on`; false values: `0`, `false`, `no`, `off`; when unset, reads `config.toml`, then falls back to `true` |
+| `KIMI_SHELL_PATH` | Override the absolute path to Git Bash (`bash.exe`) on Windows; only needed when auto-detection fails on Windows | None |
+| `KIMI_MODEL_MAX_COMPLETION_TOKENS` | Desired budget for `max_completion_tokens` in a single-step LLM request (the actual value is further clamped by the context window and input size); set to `0` or a negative value to disable clamping entirely. **Currently effective only for providers of type `kimi`**; for Anthropic and other providers, use `[models.<alias>].max_output_size` instead (see [Config files](./config-files.md#models)) | Defaults to 32000, influenced by `loop_control.reserved_context_size` |
+
+For example, to disable telemetry on a shared host:
+
+```sh
+export KIMI_DISABLE_TELEMETRY="1"
+```
+
+`KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` has higher priority than `config.toml`. For example, running `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT=0 kimi -p "..."` temporarily requests stopping background tasks before this process exits, even if the config file sets `keep_alive_on_exit = true`.
+## Diagnostic logging
+
+The variables below control `kimi`'s diagnostic logs. Logs are written to two locations: the global diagnostic log at `$KIMI_CODE_HOME/logs/kimi-code.log`, and each session's own diagnostic log at `<sessionDir>/logs/kimi-code.log` (see [Data locations](./data-locations.md#logs-and-update-state) for path details). All of these variables are read only once at process startup.
+
+| Environment variable | Purpose | Default |
+| --- | --- | --- |
+| `KIMI_LOG_LEVEL` | Log level; one of `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` |
+
+When an integer variable fails to parse (non-positive integer or non-numeric), it silently falls back to the default value.
+
+## Clipboard bridge
+
+`KIMI_WSL_CLIPBOARD_IMAGE_PATH` is injected automatically by the CLI when it spawns the WSL clipboard helper subprocess, used to pass a temporary image path. The variable is written into the PowerShell subprocess's environment and read by the subprocess script internally; the main `kimi` process does not read this variable itself. Setting it in an external shell has **no effect** on the main `kimi` process — users do not need to manage this variable manually.
+
+## System environment variables
+
+Kimi Code CLI also reads a handful of standard system environment variables to detect the runtime environment and pick default behavior:
+
+- `HOME`: the user's home directory, used to resolve the default data path.
+- `VISUAL`, `EDITOR`: the executable invoked as the external editor, with `VISUAL` taking precedence.
+- `PATH`: used to locate external dependencies such as `rg` and `git`.
+- `NO_COLOR`: when set and non-empty, forces color and theme detection off, falling back to the dark theme. Follows the [no-color.org](https://no-color.org) convention.
+- `FORCE_COLOR`: when set to `"0"`, also disables color and theme detection, falling back to the dark theme.
+- `CI`: when non-empty and not `"0"`, disables theme detection and falls back to the dark theme; the telemetry module also reads this variable to mark the CI environment.
+- `LANG`: used to tag the locale in the telemetry context (purely as a tag; it does not change CLI behavior).
+- `TERM_PROGRAM`: used to detect terminal support for OSC 9 notifications (iTerm2, WezTerm, ghostty, WarpTerminal, etc.); also written into the telemetry context.
+- `TERM`: used to detect terminal support for OSC 9 notifications (xterm-kitty, xterm-ghostty, etc.).
+- `TMUX`: detects whether the CLI is running inside tmux, used for the terminal notification path.
+- `COLORFGBG`: detects the terminal color scheme (dark / light).
+- `DISPLAY`, `WAYLAND_DISPLAY`, `XDG_SESSION_TYPE`: detect a Linux graphical session, used by clipboard and image-related features. A `XDG_SESSION_TYPE` value of `wayland` is also treated as a Wayland session.
+- `WSL_DISTRO_NAME`, `WSLENV`: detect whether the CLI is running inside WSL, used for the PowerShell-bridged clipboard fallback.
+- `TERMUX_VERSION`: detects whether the CLI is running inside Termux.
+- `LOCALAPPDATA`: used on Windows when probing for the Git Bash installation path.
+
+These variables follow the usual conventions of each operating system; `kimi` only reads them and never modifies them.
--- a/docs/en/configuration/overrides.md
+++ b/docs/en/configuration/overrides.md
@ -0,0 +1,110 @@
+# Configuration overrides
+
+Kimi Code CLI's runtime parameters come from the user config file, command-line flags, and a handful of runtime paths, endpoints, and switches read from process-level environment variables. Each layer serves a different purpose — the config file captures long-term preferences, CLI flags are well suited for temporary tweaks at this launch, and environment variables mainly locate the data directory, switch OAuth endpoints, and toggle a small number of runtime switches.
+
+Environment variables are **not a universal fallback for configuration fields** in Kimi Code CLI. They fall into three categories with different scopes, and cannot be flattened into a single linear priority list.
+
+## Three roles of environment variables
+
+1. **Config file location**: `KIMI_CODE_HOME` determines the data root holding the config file, sessions, logs, and so on, making the config file path `$KIMI_CODE_HOME/config.toml` (otherwise `~/.kimi-code/`). This is a "where to find the config" step that runs before everything else; it is not a fallback source for ordinary parameters. There is also no `KIMI_CONFIG_PATH`-style variable for pointing at an arbitrary config file.
+2. **Runtime switches**: a small number of switches such as `KIMI_DISABLE_TELEMETRY` directly turn off the corresponding subsystem. Even if `config.toml` has `telemetry = true`, telemetry is still disabled whenever this variable is set to a truthy value — its semantics are "additionally disable", not "ordinary override".
+3. **Runtime endpoints and diagnostics**: `KIMI_CODE_OAUTH_HOST`, `KIMI_OAUTH_HOST`, `KIMI_CODE_BASE_URL`, `KIMI_LOG_LEVEL`, and friends are read during OAuth and diagnostic subsystem initialization. See [Environment variables](./env-vars.md) for the full list.
+
+## Priority of ordinary runtime parameters
+
+For other runtime parameters (model alias, Plan / yolo mode, Skills directories, and so on), resolution is:
+
+1. **Command-line flags**: parameters supplied at this launch; override every other source and apply only to the current launch.
+2. **User config file**: `$KIMI_CODE_HOME/config.toml` (defaulting to `~/.kimi-code/config.toml`), used to capture long-term preferences.
+
+A few environment variables explicitly override related config fields. For example, `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` has higher priority than `[background].keep_alive_on_exit`. These exceptions are called out in [Environment variables](./env-vars.md) and in the corresponding [Config files](./config-files.md) field reference.
+
+::: warning Note
+Ordinary runtime parameters **do not** fall back to shell environment variables. For example, provider `api_key` / `base_url` are read only from fields in `config.toml` (including the `[providers.<name>.env]` subtable); they do not fall back to shell exports like `export KIMI_API_KEY`. See [Provider credentials](#provider-credentials) below.
+:::
+
+Kimi Code CLI currently reads only one user-level config file. There is no project-level (in-repo) config file mechanism. To isolate configuration between projects, point `KIMI_CODE_HOME` at a different data directory (see [Typical scenarios](#typical-scenarios) below) or temporarily override specific fields with CLI flags at launch.
+
+## Config file
+
+The config file location is controlled by the `KIMI_CODE_HOME` environment variable, falling back to `~/.kimi-code/` when unset. The file name is fixed as `config.toml`, and the directory is created with `0o700` permissions. The file can declare long-term preferences such as `default_model`, `providers`, `models`, `thinking`, and `loop_control`. See [Config files](./config-files.md) for the field reference.
+
+## Provider credentials
+
+Provider credentials (`api_key`, `base_url`) have their own resolution rules: Kimi Code CLI reads provider fields only from `config.toml` and **does not** fall back to shell environment variables. Running `export KIMI_API_KEY` in your terminal alone will not give a `[providers.<name>]` entry credentials — you have to write them into the config file explicitly.
+
+For a single provider, credentials are resolved in this order:
+
+1. `[providers.<name>].api_key` — the key written explicitly into the config file; highest priority.
+2. The corresponding key in the `[providers.<name>.env]` subtable (such as `KIMI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`) — moving the environment-variable names you would normally write in your shell into a TOML subtable. Used only when `api_key` is left empty. This is just the form of a config sub-table; it does not actually modify your process environment.
+3. If both are missing, startup fails with a message that the provider has no credentials configured.
+
+`base_url` resolves similarly to `api_key`: `[providers.<name>].base_url` is checked first, then `*_BASE_URL` keys (such as `ANTHROPIC_BASE_URL`, `OPENAI_BASE_URL`, `KIMI_BASE_URL`) in `[providers.<name>.env]`. See [Providers](./providers.md) for the full reference of provider types and fields.
+
+## Process-level environment variables
+
+Variables in `process.env` are read at Kimi Code CLI startup and fall into the three roles described above in [Three roles of environment variables](#three-roles-of-environment-variables):
+
+- **Data root and log paths**: `KIMI_CODE_HOME` switches `~/.kimi-code/`; `KIMI_LOG_LEVEL` and friends control diagnostic logs.
+- **Runtime switches**: `KIMI_DISABLE_TELEMETRY` disables telemetry (overriding `telemetry = true` in `config.toml`).
+- **OAuth endpoints and diagnostics**: `KIMI_CODE_OAUTH_HOST`, `KIMI_OAUTH_HOST`, and `KIMI_CODE_BASE_URL` control the hosted Kimi login endpoints; `KIMI_LOG_LEVEL` and friends control diagnostic logs.
+- **Background-task exit policy**: `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` overrides `[background].keep_alive_on_exit`, letting you decide for this process whether background tasks are kept on exit.
+
+See [Environment variables](./env-vars.md) for the full list of variables and their scopes.
+
+## Command-line flags
+
+Parameters supplied via CLI flags at launch have the highest priority and only apply to the current launch. Common flags:
+
+| Flag | Effect |
+| --- | --- |
+| `-S, --session [id]` | Resume the specified session; without an id, enters interactive selection |
+| `-C, --continue` | Continue the most recent session for the current working directory |
+| `-y, --yolo` | Auto-approve ordinary tool calls (aliases: `--yes`, `--auto-approve`) |
+| `--plan` | Launch in Plan mode |
+| `-m, --model <model>` | Specify the model alias to use for this launch |
+| `-p, --prompt <prompt>` | Execute a single prompt in non-interactive mode and exit |
+| `--output-format <format>` | Specify the output format for `-p` mode: `text` or `stream-json` |
+| `--skills-dir <dir>` | Replace the auto-discovered Skills directory (can be specified multiple times; applies to this launch only) |
+
+Mutually exclusive flag rules:
+
+- `--output-format` can only be used in prompt mode (`-p / --prompt`).
+- `--prompt` cannot be combined with `--yolo`, nor with `--plan`.
+- In prompt mode, `-S / --session` must be given an id; the interactive selector (bare `--session`) is not accepted.
+- `--continue` and `--session` cannot be used together.
+- Outside prompt mode, `--yolo` cannot be combined with `--continue` or `--session`; `--plan` cannot be combined with `--continue` or `--session`.
+- `--yolo` and `--plan` can be used together.
+
+::: tip Tip
+`--skills-dir` replaces the auto-discovered Skills directory for this launch and is suitable for one-off use. To persistently append search directories, set `extra_skill_dirs` at the top level of `config.toml` (see [Agent Skills](../customization/skills.md)). The two options have different semantics and can be chosen based on your needs.
+:::
+
+## Typical scenarios
+
+**Switch the data directory for isolated testing.** `KIMI_CODE_HOME` simultaneously affects the config file, session archives, ripgrep cache, and every other data location:
+
+```sh
+KIMI_CODE_HOME="$PWD/.kimi-sandbox" kimi
+```
+
+**Stage temporary credentials in the config file.** Since provider credentials are read only from `config.toml`, to use a different API key for a single launch, write it into the `[providers.<name>.env]` subtable in advance:
+
+```toml
+[providers.kimi.env]
+KIMI_API_KEY = "sk-test"
+```
+
+You can also set `api_key` directly on the provider; see [Provider credentials](#provider-credentials) above for the priority between the two.
+
+**Skip approvals for this launch.** Suitable for batch tasks you already know are safe:
+
+```sh
+kimi --yolo
+```
+
+**Enter Plan mode for this launch.** If you want the same default behavior, set `default_plan_mode = true` in the config file:
+
+```sh
+kimi --plan
+```
--- a/docs/en/configuration/providers.md
+++ b/docs/en/configuration/providers.md
@ -0,0 +1,136 @@
+# Providers and models
+
+Kimi Code CLI integrates with multiple LLM platforms through a unified provider abstraction. Each provider handles one API protocol, and models are declared on top of a provider with their own name, context length, and capabilities. This page describes every provider type currently supported and how to configure them in `~/.kimi-code/config.toml`.
+
+## Overview
+
+The `type` field of each entry in the `providers` table determines which implementation is used. The currently supported types are:
+
+| Type | Protocol | Typical platforms |
+| --- | --- | --- |
+| `kimi` | OpenAI-compatible (chat completions style) | Kimi Code, Moonshot AI Open Platform |
+| `anthropic` | Anthropic Messages | Claude API |
+| `openai` | OpenAI Chat Completions | OpenAI and compatible services |
+| `openai_responses` | OpenAI Responses API | OpenAI's newer Responses endpoint |
+| `google-genai` | Google GenAI | Gemini API |
+| `vertexai` | Google GenAI on Vertex | Google Cloud Vertex AI |
+
+All providers stream model interactions by default. Thinking, vision, and tool-call capabilities are matched automatically by model name prefix, so you do not need to spell them out in the config.
+
+API keys may be written into the `api_key` field, or supplied under the `[providers.<name>.env]` sub-table. The lookup order is `api_key` > sub-table key > missing error. **Kimi Code CLI does not automatically fall back to shell environment variables** — `export KIMI_API_KEY` in your terminal alone will not give a provider credentials; you must write them into `config.toml` (see [Configuration overrides: provider credentials](./overrides.md#provider-credentials) for details). `api_key` and `oauth` are mutually exclusive on the same provider; setting both causes an error when the model is resolved. OAuth credentials are handled by the built-in login flow and do not need to be configured manually.
+
+The `[providers.<name>.env]` sub-table lets you supply credentials or endpoint overrides directly inside `config.toml`. These values are scoped to the provider and do not leak into the global shell environment:
+
+```toml
+[providers.my-anthropic.env]
+ANTHROPIC_API_KEY = "sk-ant-xxxxx"
+ANTHROPIC_BASE_URL = "https://my-proxy.example.com"
+```
+
+The most common ways to switch providers are: use the `/model` slash command inside the TUI to pick from already-configured models, or edit `config.toml` directly to adjust the `[providers.*]` and `[models.*]` tables. See [Config files](./config-files.md) for the full field reference.
+
+## `kimi`
+
+`kimi` connects to the Moonshot AI API using the OpenAI-compatible protocol.
+
+- Default `base_url`: `https://api.moonshot.ai/v1`
+- Environment variables: `KIMI_API_KEY`, `KIMI_BASE_URL`
+- Extra capability: video upload
+
+```toml
+[providers.kimi]
+type = "kimi"
+base_url = "https://api.moonshot.ai/v1"
+api_key = "sk-xxxxx"
+```
+
+The Kimi Code hosted service configures its `base_url` and credentials automatically after OAuth login; see [OAuth and credential injection](#oauth-and-credential-injection) and [Environment variables](./env-vars.md) for details.
+
+## `anthropic`
+
+`anthropic` integrates with the Claude API. Standard Claude models automatically enable vision, tool calls, and thinking where supported. For custom or unreleased models, declare `capabilities` explicitly under `[models.<alias>]`.
+
+Thinking can be controlled via `/model`, `/settings`, or configuration.
+
+- Default `base_url`: follows the Anthropic SDK default
+- Environment variables: `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`
+- Default `max_tokens`: set automatically per model. To override it (for example for testing or for an unrecognized alias), set `max_output_size` on the model alias (see [`config-files.md`](./config-files.md#models)). Recognized aliases are capped at the documented server-side ceiling.
+
+```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
+# Optional: lower the output budget for testing, or set one for a model
+# this CLI doesn't know about yet. Omit to use the per-model default
+# above.
+# max_output_size = 32000
+```
+
+## `openai`
+
+`openai` corresponds to the OpenAI Chat Completions protocol and can also be used to connect to any third-party service that speaks the same protocol (simply override `base_url`). Thinking, vision, and tool-call capabilities are inferred automatically from the model name.
+
+- Default `base_url`: `https://api.openai.com/v1`
+- Environment variables: `OPENAI_API_KEY`, `OPENAI_BASE_URL`
+
+```toml
+[providers.openai]
+type = "openai"
+base_url = "https://api.openai.com/v1"
+api_key = "sk-xxxxx"
+```
+
+## `openai_responses`
+
+`openai_responses` corresponds to OpenAI's newer Responses API. It always operates in streaming mode; capabilities are inferred automatically from the model name.
+
+- Default `base_url`: `https://api.openai.com/v1`
+- Environment variables: `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`
+
+`google-genai` connects directly to the Google Gemini API. Thinking, vision, and multimodal capabilities are inferred automatically from the model name.
+
+- Environment variable: `GOOGLE_API_KEY`
+
+```toml
+[providers.gemini]
+type = "google-genai"
+api_key = "xxxxx"
+```
+
+## `vertexai`
+
+`vertexai` shares the same implementation as `google-genai`; setting `type = "vertexai"` switches it to the Vertex AI access path.
+
+Authentication follows the standard Google Cloud flow: authenticate via `gcloud auth application-default login`, or set `GOOGLE_APPLICATION_CREDENTIALS` to a service-account JSON (this step is a generic Google SDK mechanism unrelated to Kimi Code configuration). **The project and region must be written into the `[providers.vertexai.env]` sub-table** — `export GOOGLE_CLOUD_PROJECT` or `export GOOGLE_CLOUD_LOCATION` in the shell will not be read by the CLI. When `GOOGLE_CLOUD_LOCATION` is missing, the CLI tries to infer it from `base_url`. API keys (`VERTEXAI_API_KEY` or `GOOGLE_API_KEY`) likewise go into the sub-table.
+
+```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
+kimi
+```
+
+## OAuth and credential injection
+
+Some platforms (such as the Kimi Code hosted service) use OAuth instead of static API keys. Credentials are injected at runtime by the built-in kimi-oauth toolchain, and the login flow takes care of writing and refreshing them automatically — there is nothing to configure by hand for this in your config file.
--- a/docs/en/customization/agents.md
+++ b/docs/en/customization/agents.md
@ -0,0 +1,45 @@
+# Agents and subagents
+
+The agent in Kimi Code CLI is the core that drives a session. A session is always hosted by a single main agent, which may dispatch one or more subagents to handle more focused subtasks as the work progresses.
+
+The main agent is responsible for understanding the user's overall intent, planning the steps, conversing with the user, calling tools, and finally aggregating the results. Its context spans the entire session, and it is the entity the user interacts with directly in the terminal.
+
+A subagent is a temporary "assistant" spawned by the main agent. It takes a clearly defined task description, completes the work independently in its own context, and then returns the conclusion to the main agent. Subagents do not converse with the user directly, nor do they pollute the main agent's context history. This division of labor is particularly suited for work with clear boundaries that requires a lot of reading but produces a short output — such as "exploring a codebase", "reviewing a large implementation", or "planning a complex change".
+
+## Built-in subagents
+
+Kimi Code CLI ships with three built-in subagents, each targeting a different kind of task, ready to use out of the box:
+
+- **`coder`**: The default subagent, a general software engineering assistant that can read and write files, run shell commands, search code, and land concrete changes.
+- **`explore`**: Dedicated to codebase exploration. It operates read-only and will not modify any files. Suitable for quickly searching, reading, and summarizing a repository without making changes.
+- **`plan`**: For implementation planning and architectural design. Its toolset is narrowed further — not even shell commands are provided — focusing on "thinking through how to do it" rather than "doing it".
+
+## Invocation
+
+Subagents are dispatched automatically by the main agent. The main agent decides when to dispatch one based on task complexity, context usage, and the independence of the subtask — you don't need to manually specify the timing.
+
+Each dispatch surfaces as an approval request in the terminal (unless it matches an existing allow rule or you are in YOLO mode), so you can inspect the task description before it runs. You can also ask the main agent to prefer a particular type of subagent for a task — for example, "use `explore` first to map out the relevant files before making changes."
+
+Subagents can also run in the background; their results are synthesized back to the main agent automatically on a later turn, with no manual polling needed. You can also resume an existing subagent instance to continue the same task.
+
+## Context isolation and resource cost
+
+Each subagent has a completely independent context window. It cannot see the main agent's conversation history; it can only see the task description that the main agent explicitly passed. The subagent's own intermediate thoughts and tool call records do not flow back to the main agent — only the final result appears in the main agent's context.
+
+This isolation brings two direct benefits. First, the main agent's context stays concise and isn't flooded with exploratory logs over a long session. Second, multiple subagents can run in parallel without interfering with each other.
+
+The cost is that each subagent independently consumes model tokens, so it is unnecessary to dispatch a subagent for simple tasks — letting the main agent handle them directly is more economical. Subagents also cannot dispatch further subagents.
+
+## Permission inheritance
+
+A subagent's permission rules are inherited from the main agent: "always allow" rules that the main agent has accepted via `/permission` or during an approval automatically cover every subagent it dispatches, so the subagent does not need to re-approve the same kind of tool call. The `Agent` tool itself is allowed by default, so the main agent can complete multiple delegations without interrupting the user.
+
+If you want a particular kind of tool to be permanently unavailable inside subagents, you should tighten the main agent's permission rules.
+
+## Storage location in the session directory
+
+A subagent's runtime state is persisted to the session directory for later inspection and debugging. Each subagent instance corresponds to a separate subdirectory under `agents/`, which contains a `wire.jsonl` file recording prompts, message history, and final status in chronological order. Background subagents additionally expose their lifecycle through the `tasks/` subdirectory.
+
+::: warning Note
+Session directories, wire files, and task records are local debugging material and may contain user prompts, command output, repository paths, tool results, or traces of credentials. Do not commit these files to public repositories, issues, or chat transcripts directly; redact them first if you need to share them.
+:::
--- a/docs/en/customization/hooks.md
+++ b/docs/en/customization/hooks.md
@ -0,0 +1,150 @@
+# Hooks
+
+Hooks let you run local commands at key lifecycle points in Kimi Code CLI. They are useful for lightweight policy checks, audit logging, desktop notifications, or wiring into local automation scripts — for example, intercepting a risky tool call before it runs, or firing a notification when a background subagent finishes.
+
+Hook commands run in the local shell, and Kimi Code CLI writes the event payload as JSON to the command's stdin. The command's stdout, stderr, and exit code determine the hook result. Except for explicit blocking cases, hook failures fail open and do not interrupt the main flow because of a misbehaving script.
+
+::: warning Note
+Hooks are useful for local notifications and lightweight interception, but they should not be treated as the only security boundary. Script errors, timeouts, and ordinary non-zero exit codes fail open and continue to allow the operation; high-risk tool calls should still rely on permission approval and human review.
+:::
+
+## Configuration
+
+Declare hooks in `~/.kimi-code/config.toml` with `[[hooks]]` array tables:
+
+```toml
+[[hooks]]
+event = "PreToolUse"
+matcher = "Bash"
+command = "node ~/.kimi-code/hooks/check-bash.mjs"
+timeout = 5
+
+[[hooks]]
+event = "Notification"
+matcher = "task\\.completed"
+command = "terminal-notifier -title Kimi -message 'Background task finished'"
+```
+
+The fields are:
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `event` | `string` | Yes | Event name. The value must be one of the entries in the "Events" table below; any other value causes the entire config to fail to load |
+| `matcher` | `string` | No | Regular expression matched against the event target. Missing or empty means match everything |
+| `command` | `string` | Yes | Shell command to run. Must be non-empty |
+| `timeout` | `integer` | No | Timeout in seconds, range 1–600. Defaults to 30 seconds when unset |
+
+Each `[[hooks]]` table accepts only these four fields. Misspelled or extra fields cause the configuration file to fail to parse.
+
+When one event fires, all matching hooks run in parallel. If multiple entries share the exact same `command`, that command runs only once. `matcher` uses JavaScript regular expression semantics; invalid regular expressions are silently skipped and treated as no match.
+
+Hook commands are launched through the shell (equivalent to `sh -c <command>`), and the child process's working directory is the current session's `cwd`. On non-Windows platforms, the child is placed in its own process group; on timeout or session interruption, Kimi Code CLI first sends `SIGTERM` and then `SIGKILL` 100 milliseconds later, so any grandchild processes forked inside the hook are cleaned up as well.
+
+JSON fields passed to hooks use snake_case. Every payload includes:
+
+```json
+{
+  "hook_event_name": "PreToolUse",
+  "session_id": "session_abc",
+  "cwd": "/path/to/project"
+}
+```
+
+Additional fields depend on the event type, as shown in the event table below.
+
+## Return values
+
+Hook command exit codes and stdout are interpreted as follows:
+
+| Result | Behavior |
+| --- | --- |
+| Exit code `0` | Allow. If stdout is JSON, text may be read from `message` or `hookSpecificOutput.message` |
+| Exit code `2` | Block. stderr is used as the blocking reason |
+| Any other non-zero exit code | Fail open and allow |
+| Timeout or process error | Fail open and allow |
+
+If stdout is JSON and `hookSpecificOutput.permissionDecision` is `deny`, the result is also treated as a block:
+
+```json
+{
+  "hookSpecificOutput": {
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Use rg instead"
+  }
+}
+```
+
+Blocking only applies to events that participate in control flow. For example, `PreToolUse` can block a tool call, and `Stop` can append one continuation message to the current turn. Observer events (such as `PostToolUse`, `PostToolUseFailure`, `PostCompact`, `SubagentStop`, `StopFailure`, and `Notification`) are dispatched asynchronously in a fire-and-forget fashion; their return values are ignored and do not change the main flow. `PreCompact` is invoked with `trigger` (not `triggerBlock`); its return value is likewise completely ignored, and it is not a blockable event.
+
+When a block takes effect, if the script does not provide a reason through stderr or JSON output, the CLI falls back to `Blocked by <event> hook` as a placeholder reason. A `PreToolUse` block is written back into context as a failed tool result, so the model can choose an alternative based on the reason.
+
+## Events
+
+The following events are triggered automatically today:
+
+| Event | Matcher | Main payload | Behavior |
+| --- | --- | --- | --- |
+| `UserPromptSubmit` | Text content submitted by the user | `prompt` (`ContentPart[]` array) | Fires only for real user messages. Text returned by the hook is wrapped as a hook result, written into session history for transcript/replay, shown to the user, and the current LLM turn continues without sending the hook result to the model; if the hook blocks, the block reason is returned to the user as an assistant message and no model call is made; if all hooks produce no output, the normal LLM turn continues |
+| `PreToolUse` | Tool name | `tool_name`, `tool_input`, `tool_call_id` | Fires before permission checks. If blocked, the tool does not run |
+| `PostToolUse` | Tool name | `tool_name`, `tool_input`, `tool_call_id`, `tool_output` | Fires after a successful tool call. `tool_output` is truncated to the first 2000 characters |
+| `PostToolUseFailure` | Tool name | `tool_name`, `tool_input`, `tool_call_id`, `error` | Fires after a tool call fails or is blocked by a hook |
+| `Stop` | Empty string | `stop_hook_active` | Fires when the model is about to stop. If blocked, the reason is appended directly to context as a system-triggered user message, and the turn may continue once |
+| `StopFailure` | Error type | `error_type`, `error_message` | Fires after the current turn fails with a non-cancellation error |
+| `SessionStart` | `startup` or `resume` | `source` | Fires after the main agent is created for a new session, or after a historical session is resumed |
+| `SessionEnd` | `exit` | `reason` | Fires after the session is closed and its metadata is flushed |
+| `SubagentStart` | Subagent name | `agent_name`, `prompt` | Fires after a subagent is configured and before it actually starts running. `prompt` is truncated to the first 500 characters |
+| `SubagentStop` | Subagent name | `agent_name`, `response` | Fires asynchronously after a subagent completes successfully; does not fire on failure. `response` is truncated to the first 500 characters |
+| `PreCompact` | `manual` or `auto` | `trigger`, `token_count` | Fires before context compaction actually starts. This event is invoked with `trigger` (not `triggerBlock`); its return value is completely ignored and blocking decisions are not read |
+| `PostCompact` | `manual` or `auto` | `trigger`, `estimated_token_count` | Fires asynchronously after context compaction is successfully written. Blocking results do not change the main flow |
+| `Notification` | Notification type | `sink`, `notification_type`, `title`, `body`, `severity`, `source_kind`, `source_id` | Currently fires when a background subagent result is written into context. `notification_type` is one of `task.completed`, `task.failed`, `task.killed`, or `task.lost`; the sink is `context` |
+
+`UserPromptSubmit` return text is wrapped as a hook result:
+
+```xml
+<hook_result hook_event="UserPromptSubmit">
+hook response
+</hook_result>
+```
+
+If multiple `UserPromptSubmit` hooks return text, each result gets its own `<hook_result>` tag. This message keeps its hook-result origin for transcript/replay, but is not sent to the model. The model sees the original user prompt and the current turn continues.
+
+If a `UserPromptSubmit` hook blocks the request, the block reason uses the same format and is returned to the user, but the turn does not continue to a model call.
+
+`Stop` block reasons are appended directly as system-triggered user messages so the current turn can continue:
+
+```text
+continue from hook
+```
+
+## Example: block risky shell commands
+
+The following hook reads `tool_input.command` from stdin before a `Bash` tool call. If the command contains `rm -rf`, the script exits with code `2` and writes the reason to stderr:
+
+::: warning Note
+This example only demonstrates how a hook blocks a tool call; it is not a complete shell safety parser. Real policies are better implemented with an allowlist, or with dedicated shell parsing that handles quoting, variable expansion, aliases, and multi-part commands.
+:::
+
+```toml
+[[hooks]]
+event = "PreToolUse"
+matcher = "Bash"
+command = "node ~/.kimi-code/hooks/block-dangerous-bash.mjs"
+timeout = 5
+```
+
+```js
+let input = '';
+process.stdin.on('data', (chunk) => {
+  input += chunk;
+});
+process.stdin.on('end', () => {
+  const payload = JSON.parse(input);
+  const command = payload.tool_input?.command ?? '';
+  if (command.includes('rm -rf')) {
+    console.error('Blocked dangerous shell command');
+    process.exit(2);
+  }
+});
+```
+
+When the hook blocks the tool call, Kimi Code CLI writes the blocking reason back into context as a failed tool result, so the model can choose a safer alternative.
--- a/docs/en/customization/mcp.md
+++ b/docs/en/customization/mcp.md
@ -0,0 +1,83 @@
+# 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. Kimi Code CLI acts as an MCP client to integrate these external tools, exposing them to the agent alongside built-in tools (`Read`, `Bash`, `Grep`, etc.).
+
+## Integration scope
+
+Kimi Code CLI connects to MCP servers via stdio (local subprocess) or HTTP. Once connected, MCP tools behave the same as built-in tools: they are available to the agent, subject to permission rules, and go through the approval flow.
+
+## Configuration and login
+
+MCP server configurations live in `mcp.json` in two layers:
+
+- User-level: `~/.kimi-code/mcp.json` (or `$KIMI_CODE_HOME/mcp.json`), shared across projects
+- Project-level: `.kimi-code/mcp.json` in the current workspace
+
+Project entries override user-level entries with the same name.
+
+The easiest entry point is running `/mcp-config` in the TUI, which guides you through adding, editing, or removing servers. To check connection status, run `/mcp`.
+
+The top-level shape of `mcp.json` is:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+    },
+    "linear": {
+      "url": "https://mcp.linear.app/mcp"
+    }
+  }
+}
+```
+
+Entries with `command` are stdio servers; entries with `url` are HTTP servers, so you usually do not need to write a `transport` field. HTTP servers can provide static credentials through `headers` or `bearerTokenEnvVar`. When OAuth is required, run `/mcp-config login <server-name>` to complete browser authorization.
+
+Optional fields:
+
+| Field | Type | Applies to | Description |
+| --- | --- | --- | --- |
+| `env` | `Record<string, string>` | stdio | Environment variables injected into the subprocess |
+| `cwd` | `string` | stdio | Working directory for the subprocess |
+| `headers` | `Record<string, string>` | HTTP | Static headers appended to every request |
+| `enabled` | `boolean` | both | Set to `false` to disable the server without removing the entry |
+| `startupTimeoutMs` | `number` | both | Connection timeout in milliseconds, default `30000` |
+| `toolTimeoutMs` | `number` | both | Per-tool-call timeout in milliseconds |
+| `enabledTools` | `string[]` | both | Allowlist: only expose the tools in this list |
+| `disabledTools` | `string[]` | both | Blocklist: exclude the tools in this list |
+
+::: warning Note
+Stdio entries in a project-level `.kimi-code/mcp.json` execute local commands when the session starts. Only enable project-level MCP servers in repositories you trust.
+:::
+
+## Tool naming and permissions
+
+MCP tools are exposed using the naming convention `mcp__<server>__<tool>`. Permission matching supports `*` and `**` wildcards, so `mcp__github__*` covers every tool from the `github` server.
+
+Calls that do not match any rule trigger an approval request. Choosing "Approve for this session" in the approval prompt auto-approves subsequent matching calls.
+
+You can also pre-load permanent rules in the `[[permission.rules]]` array of tables in `config.toml`:
+
+```toml
+[[permission.rules]]
+decision = "allow"
+pattern = "mcp__github__*"
+
+[[permission.rules]]
+decision = "deny"
+pattern = "mcp__filesystem__write_file"
+```
+
+The full syntax of the `pattern` field and the accepted values of other fields such as `decision`, `scope`, and `reason` are documented in [Config files](../configuration/config-files.md#permission).
+
+## Security
+
+- Only integrate MCP servers from trusted sources
+- Check that the tool name and arguments are reasonable in approval requests
+- Keep manual approval for high-risk tools, and avoid broad `mcp__*` wildcard allowlisting
+
+::: warning Note
+In YOLO mode, MCP tool calls are auto-approved like any other tool. Only use this mode when you fully trust the integrated MCP servers.
+:::
--- a/docs/en/customization/skills.md
+++ b/docs/en/customization/skills.md
@ -0,0 +1,127 @@
+# Agent Skills
+
+Agent Skills are the lightweight mechanism Kimi Code CLI uses to extend a model's capabilities. A skill is a Markdown document with YAML frontmatter that describes a piece of expertise or a workflow. Kimi Code CLI scans known directories on startup and injects the discovered skills into the system prompt, so the agent knows which skills are available in the current session.
+
+Compared to pasting the same guidance into the prompt every time, skills offer these advantages: the content is captured in a file, reusable across projects and teams, can be loaded with a one-shot slash command, and can also be invoked automatically by the model when needed.
+
+## Creating a skill
+
+Skill files must be placed in a [known scan directory](#skill-locations). A skill can use one of two file structures:
+
+- **Directory form (recommended)**: create a subdirectory with the main file named `SKILL.md`. You can also place scripts, references, and other auxiliary files in the same directory. If both `<name>/SKILL.md` and a flat `<name>.md` exist in the same directory, the subdirectory wins.
+- **Flat form**: use a single `.md` file directly; the skill name defaults to the filename with `.md` removed.
+
+### File format
+
+`SKILL.md` consists of two parts: YAML frontmatter and a Markdown body.
+
+```markdown
+---
+name: code-style
+description: Project code style conventions, covering naming, indentation, comments, and file organization
+type: prompt
+whenToUse: When the user asks me to write, modify, or review the project's source code
+disableModelInvocation: false
+arguments:
+  - target
+  - mode
+---
+
+Please handle the code according to the following conventions:
+
+- Use 2-space indentation
+- Use `camelCase` for variable names and `PascalCase` for type names
+- Public functions must have TSDoc comments
+- Lines must not exceed 100 characters
+```
+
+### Frontmatter fields
+
+| Field | Description |
+| --- | --- |
+| `name` | Skill name. Required in a directory-style `SKILL.md`; in a flat `.md` file the filename is used when omitted. Names are case-insensitive. |
+| `description` | A one-line summary. The model uses it to decide when to use this skill. Required in a directory-style `SKILL.md`; in a flat `.md` file falls back to the first non-empty line of the body (truncated to 240 characters) when omitted. |
+| `type` | Skill type. Supported values: `prompt` (default), `inline` (same semantics as `prompt`), or `flow` (manual invocation only, not auto-invoked by the model). Other values are skipped. |
+| `whenToUse` | Description of the trigger scenario. Aliases `when-to-use` and `when_to_use` are also accepted. |
+| `disableModelInvocation` | Set to `true` to forbid the model from invoking this skill automatically. Aliases `disable-model-invocation` and `disable_model_invocation` are also accepted. |
+| `arguments` | Named arguments the skill accepts. Can be written as an array of strings, or as a single whitespace-separated string (e.g. `arguments: target mode`). Once declared, the body can read them with `$<name>`. Purely numeric or empty entries are ignored. |
+
+::: warning Note
+In a directory-style `SKILL.md`, both `name` and `description` **must** be filled in explicitly. Omitting either one causes the skill to fail parsing.
+:::
+
+### Body placeholders
+
+The skill body expands a small set of placeholders before being sent to the model:
+
+- `$ARGUMENTS`: the complete raw argument string passed when the skill was invoked
+- `$ARGUMENTS[0]`, `$ARGUMENTS[1]`, and shorthand `$0`, `$1`: positional arguments after whitespace splitting, starting at 0
+- `$<name>`: a named argument declared in `arguments`
+- `${KIMI_SKILL_DIR}`: the directory containing the current skill file
+
+Positional arguments respect single- and double-quoted text: in `/skill:commit "fix login" patch`, `$0` expands to `fix login`. If the body does not contain any argument placeholders, the appended text is added to the end of the body as `\n\nARGUMENTS: <text>`.
+
+## Skill locations
+
+Kimi Code CLI scans skills in four scope tiers, with more specific scopes taking higher priority:
+
+**Project > User > Extra > Built-in**
+
+User-level:
+
+- `~/.kimi-code/skills/`
+- `~/.agents/skills/`
+
+Project-level (project root = the nearest ancestor directory containing `.git`):
+
+- `.kimi-code/skills/`
+- `.agents/skills/`
+
+Extra directories are declared via the top-level `extra_skill_dirs` field in `config.toml`:
+
+```toml
+extra_skill_dirs = ["~/team-skills", ".agents/team-skills"]
+```
+
+Built-in skills ship with CLI and have the lowest priority.
+
+## Invoking a skill
+
+Users can invoke a skill explicitly with a slash command:
+
+```
+/skill:code-style
+/skill:git-commits Fix the concurrency issue in the login API
+```
+
+The model can also decide to invoke a skill automatically based on `description` and `whenToUse`, unless `disableModelInvocation` is set to `true` or `type` is `flow`. When the model invokes a skill, body placeholders are expanded first, then the content is injected into the system prompt. Skill calls are allowed to nest up to 3 levels deep; deeper invocations are terminated.
+
+## Full example
+
+```markdown
+---
+name: review-pr
+description: Review a pull request against the team's standards and produce a structured review report
+type: prompt
+whenToUse: When the user asks me to review a PR, inspect code changes, or assess commit quality
+arguments:
+  - pr_ref
+---
+
+Please review the PR specified by the user using the following process: $pr_ref
+
+1. Fetch and read the full diff of `$pr_ref`.
+2. Check against the following items one by one:
+   - Whether corresponding test cases are included
+   - Whether public APIs have documentation updates
+   - Whether new dependencies are introduced; if so, explain the rationale
+   - 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)
+   - Things worth acknowledging
+```
+
+Save the above as `~/.kimi-code/skills/review-pr/SKILL.md`, and put the checklist at `references/checklist.md` in the same directory. Then restart the session, and you can invoke it via `/skill:review-pr #1234`; the appended `#1234` will expand into `$pr_ref` in the body.
--- a/docs/en/faq.md
+++ b/docs/en/faq.md
@ -0,0 +1,3 @@
+# FAQ
+
+This page collects the questions new users hit most often, along with short answers. When a topic needs a fuller explanation, the answer links to the relevant doc at the end.
--- a/docs/en/guides/getting-started.md
+++ b/docs/en/guides/getting-started.md
@ -0,0 +1,135 @@
+# 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. It can read and edit code, run shell commands, search files, and fetch web pages, autonomously planning and adjusting the next step 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 entire CLI is written in TypeScript, distributed through npm, and runs on Node.js.
+
+## Installation
+
+### Install script (recommended)
+
+The quickest way to install Kimi Code CLI is with the install script; no pre-installed Node.js is required:
+
+- **macOS / Linux**:
+
+```sh
+curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash
+```
+
+- **Windows (PowerShell)**:
+
+```powershell
+irm https://code.kimi.com/kimi-code/install.ps1 | iex
+```
+
+This downloads the latest release, verifies the checksum, and places the `kimi` executable on your `PATH`.
+
+### npm installation
+
+If you prefer to install via npm, you need Node.js 24.15.0 or later:
+
+```sh
+node --version
+```
+
+The package name is `@moonshot-ai/kimi-code`:
+
+```sh
+npm install -g @moonshot-ai/kimi-code
+```
+
+Or with pnpm:
+
+```sh
+pnpm add -g @moonshot-ai/kimi-code
+```
+
+## Upgrade and uninstall
+
+After installation, verify that the executable is ready:
+
+```sh
+kimi --version
+```
+
+**Upgrade**: if you installed via the script, re-run it. If you installed via npm:
+
+```sh
+npm install -g @moonshot-ai/kimi-code@latest
+```
+
+**Uninstall**: if you installed via the script, remove the `kimi` executable. If you installed via npm:
+
+```sh
+npm uninstall -g @moonshot-ai/kimi-code
+```
+
+## First launch
+
+Move into the project directory you want to work in and simply run `kimi` to start the interactive UI:
+
+```sh
+cd your-project
+kimi
+```
+
+If you only want to run a single instruction without entering the interactive UI, use the `-p` flag:
+
+```sh
+kimi -p "Take a look at this project's directory structure"
+```
+
+To resume the previous session, add the `-C` flag:
+
+```sh
+kimi -C
+```
+
+On the first launch, Kimi Code CLI has no credentials yet, and you need to configure an API source before you can start a conversation. In the interactive UI, enter the slash command `/login` to begin the login flow:
+
+```
+/login
+```
+
+`/login` opens a platform selector supporting:
+
+- **Kimi Code** — OAuth device code flow; open the URL on any device, sign in, and enter the code to authorize
+- **Moonshot AI Open Platform** — log in directly with an API key
+
+To sign out, enter `/logout` to clear the current credentials.
+
+::: tip
+If you want to use Anthropic, OpenAI, Google, or other providers, edit `config.toml` directly to configure the API key. See [Providers and models](../configuration/providers.md) for details. Runtime configuration such as the model and provider is also written to `config.toml`. See [Config files](../configuration/config-files.md), [Environment variables](../configuration/env-vars.md), and [Configuration overrides](../configuration/overrides.md) for details.
+:::
+
+## Your first conversation
+
+Once login is complete, you can describe a task to Kimi Code CLI directly in natural language. For example, you can have it familiarize itself with the current project first:
+
+```
+Take a look at this project's directory structure and briefly describe what each directory is for.
+```
+
+Kimi Code CLI will automatically call file-reading, search, and web-fetching tools, browse the relevant content, and then give you an answer. Read-only operations such as reading files and searching the web are executed automatically by default without requiring confirmation. For operations that modify files or run shell commands, it asks for your confirmation before executing by default, and you can approve or reject as you see fit.
+
+You can also have it do something more concrete, such as:
+
+```
+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.
+
+In the interactive UI, entering `/help` shows all available [slash commands](../reference/slash-commands.md) along with common keyboard shortcut hints. To exit Kimi Code CLI, enter `/exit`. You can also press `Ctrl-C` — the UI will first clear the current input and prompt you to press it again, and the second press exits. Or press `Ctrl-D` twice with the input box empty to exit.
+
+## Where data is stored
+
+Kimi Code CLI stores its local data under `~/.kimi-code/` by default, including config files, session records, logs, and the update cache. If you want to move it elsewhere, you can point to a new root directory via the `KIMI_CODE_HOME` environment variable. For the full directory layout and environment variable reference, see [Data locations](../configuration/data-locations.md) and [Environment variables](../configuration/env-vars.md).
--- a/docs/en/guides/interaction.md
+++ b/docs/en/guides/interaction.md
@ -0,0 +1,67 @@
+# Interaction and Input
+
+Kimi Code CLI runs as an interactive TUI with an input box, conversation view, and status bar. This page covers basic operations, mode switches, the approval flow, and shortcuts. The full list is available via `/help`.
+
+## Input box basics
+
+The input box accepts free-form text; pressing `Enter` sends, and `Shift-Enter` inserts a line break. When the input box is empty, press `↑` / `↓` to browse history for the current directory.
+
+Press `Ctrl-D` twice to exit the CLI. `Ctrl-C` interrupts the current turn while streaming; press it twice in the idle state to exit. `Esc` closes dialogs and also interrupts a turn while streaming.
+
+## Slash commands and `@` mentions
+
+Anything starting with `/` is recognized as a slash command, covering session management, mode switching, configuration, and more — such as `/help`, `/new`, `/sessions`, and `/model`. See the [slash command reference](../reference/slash-commands.md) for the full list.
+
+Type `/` to open the command completion menu, which also includes commands from [Agent Skills](../customization/skills.md). If a skill name collides with a built-in command, use the full `/skill:<name>` form. Press `Esc` to dismiss.
+
+Some commands are only available while the agent is idle; interrupt the current turn first if the agent is streaming. Mode-switch and query commands such as `/yolo`, `/plan`, and `/help` are always available.
+
+Type `@` to trigger file-path completion. Selecting an entry inserts the relative path, and the agent can read the file directly. Dot-prefixed directories are hidden by default; write `@.github/` to include them explicitly.
+
+## Plan mode
+
+In Plan mode, the agent spells out its plan before taking action. Press `Shift-Tab` or `/plan` to toggle; `/plan clear` clears the current plan file (available while idle only).
+
+The agent outputs a plan and waits for your confirmation instead of making changes directly. Once the plan is ready, you can reject it (staying in Plan mode) or request changes. Leaving Plan mode still requires your confirmation, even when YOLO mode is on.
+
+## YOLO mode
+
+YOLO mode automatically approves most tool calls, skipping the approval step. Enter `/yolo` (or `/yes`) to toggle; available both idle and streaming.
+
+::: warning Note
+YOLO mode skips ordinary approvals, but not the approval required to leave Plan mode.
+:::
+
+## Approval flow
+
+When the agent invokes a tool with side effects (such as modifying a file or running a command), an approval panel pops up for your confirmation. This is skipped in YOLO mode and for plan-file writes in Plan mode.
+
+Use arrow keys to select an option and `Enter` to confirm; press `1` / `2` / `3` to select by position directly. `Esc`, `Ctrl-C`, and `Ctrl-D` all reject the request. The panel usually also offers an "Approve for this session" option to auto-allow similar calls going forward.
+
+## Working while output is streaming
+
+While the agent is thinking or making tool calls ("streaming output"), the input box is still usable:
+
+- `Esc` — interrupt the current turn.
+- `Ctrl-C` — also interrupts; press twice in the idle state to exit.
+- `Ctrl-S` — insert the current input-box content as an additional message into the in-progress turn.
+- `Ctrl-O` — globally toggle the collapsed state of all tool output.
+
+## External editor
+
+Press `Ctrl-G` to open the current input in an external editor; saved content is loaded back when the editor closes.
+
+Editor priority: `/editor` config > `$VISUAL` > `$EDITOR`. Run `/editor` first if none is configured.
+
+## Pasting images and videos
+
+Paste images or videos from the clipboard directly into the input box for multimodal models:
+
+- Unix (macOS / Linux): `Ctrl-V`
+- Windows: `Alt-V`
+
+Placeholders appear in the input box and behave like ordinary text; they are replaced with the actual content when sent. Plain text falls back to a normal paste. Media attachments are kept in the current session only.
+
+## Viewing all shortcuts
+
+Enter `/help` to open a panel listing all shortcuts and slash commands. Scroll with `↑` / `↓`, page with `PageUp` / `PageDown`, and close with `Esc`, `Enter`, or `q`.
--- a/docs/en/guides/migration.md
+++ b/docs/en/guides/migration.md
@ -0,0 +1,37 @@
+# Migrating from kimi-cli
+
+Kimi Code CLI is the next-generation terminal agent — and a fresh start. If you have been using the previous generation, kimi-cli, you don't need to start over: a single command brings your configuration, MCP servers, and session history across to the new version.
+
+## Why migrate
+
+kimi-code is rebuilt on Node.js and no longer depends on Python or the `uv` toolchain, making installation and upgrades simpler. It also ships native binaries out of the box.
+
+The terminal UI has been redesigned for a faster and lighter experience.
+
+kimi-cli is transitioning to kimi-code, and migrating lets you keep your existing configuration and session history going forward.
+
+## 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.
--- a/docs/en/guides/sessions.md
+++ b/docs/en/guides/sessions.md
@ -0,0 +1,110 @@
+# Sessions and context
+
+Kimi Code CLI persists every conversation as a "session", preserving message history and metadata so you can close the terminal and resume later. This page covers resuming sessions, context compaction, and managing sessions from inside the TUI.
+
+## Session storage
+
+All sessions are stored under `$KIMI_CODE_HOME/sessions/` (default `~/.kimi-code/sessions/`), bucketed 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 title and metadata.
+- `agents/*/wire.jsonl` — agent event stream.
+
+::: warning Note
+Manually editing files under `sessions/` can leave a session unrecoverable due to ordering constraints in `state.json` and `wire.jsonl`.
+:::
+
+## Starting and resuming sessions
+
+By default, `kimi` creates a new session each time. To continue where you left off:
+
+**Resume the most recent session in the current directory:**
+
+```sh
+kimi --continue
+```
+
+**Resume a specific session:**
+
+```sh
+kimi --session abc123
+```
+
+`-r` / `--resume` are equivalent aliases.
+
+**Pick interactively:**
+
+```sh
+kimi --session
+```
+
+::: warning Note
+`--continue` and `--session` are mutually exclusive; `--yolo` and `--plan` also cannot be combined with them.
+:::
+
+## Switching sessions inside the TUI
+
+- `/new` (`/clear`): switch to a new session.
+- `/sessions` (`/resume`): browse and resume past sessions.
+- `/fork`: fork the current session (see below).
+- `/title <text>` (`/rename`): set a session title for easier recognition. Without an argument, shows the current title.
+
+`/sessions` works even while streaming, but switching requires interrupting the turn first with `Esc` or `Ctrl-C`. `/new`, `/fork`, and `/compact` are only available while idle.
+
+## Context compaction
+
+Kimi Code CLI automatically compresses message history when context approaches the window limit. You can also trigger it manually:
+
+```text
+/compact
+```
+
+Pass a custom hint to tell the model what to preserve:
+
+```text
+/compact Keep the discussion related to database migrations
+```
+
+## Forking sessions
+
+To try a new line of thinking without disrupting the current conversation, use `/fork`:
+
+```text
+/fork
+```
+
+The forked session is fully independent; you can switch back to the original at any time.
+
+## Exporting sessions
+
+Package a session into a ZIP:
+
+```sh
+kimi export <sessionId>
+```
+
+Without a `sessionId`, it exports the most recent session (interactively asks for confirmation; pass `-y` to skip). Use `-o` to set the output path:
+
+```sh
+kimi export <sessionId> -o ~/Desktop/my-session.zip
+```
+
+The ZIP is written to the current working directory by default. The session's own diagnostic log is always bundled along with the session directory. The global diagnostic log at `$KIMI_CODE_HOME/logs/kimi-code.log` — which captures events that do not belong to a session, such as TUI startup and login — is also bundled by default; pass `--no-include-global-log` to skip it.
+
+::: tip Tip
+Exported files may contain sensitive information. Review the contents before sharing.
+:::
--- a/docs/en/guides/use-cases.md
+++ b/docs/en/guides/use-cases.md
@ -0,0 +1,118 @@
+# Common use cases
+
+Below are typical scenarios and prompt samples for Kimi Code CLI.
+
+## Understanding an unfamiliar project
+
+Use `kimi --plan` or press `Shift-Tab` to enter Plan mode for large-scale research. Ask it to produce a plan first and approve before execution:
+
+```
+Walk me through the overall architecture of this repository. Focus on:
+1. Where the entry point is and what happens at startup
+2. The dependency relationships between major modules
+3. How configuration and data are loaded
+At the end, draw a simple module relationship diagram.
+```
+
+For focused questions, ask directly:
+
+```
+How does the event loop under src/runtime work? Where do events originate, and who consumes them?
+```
+
+```
+How is "permission approval" implemented in this project? Which files are involved, and what are the key types?
+```
+
+For large investigations, the main agent can spawn **subagents** to handle subtasks in parallel. See [Agents](../customization/agents.md).
+
+## Implementing a new feature
+
+State the requirement and acceptance criteria clearly. Use Plan mode for complex or risky changes.
+
+```
+Add a retry utility under src/utils:
+- Function signature retry<T>(fn: () => Promise<T>, options): Promise<T>
+- Supports three options: maxAttempts, initialDelayMs, backoffFactor
+- Throws the last error on failure
+- Add a set of unit tests covering success, success after retry, and full failure
+```
+
+Tell it how to change the result — no need to edit by hand:
+
+```
+The backoff uses a fixed value. I want some jitter added to avoid thundering herd. Update the code and the tests.
+```
+
+## Fixing bugs
+
+State the symptom, reproduction conditions, and expected behavior:
+
+```
+Running npm test occasionally throws this error:
+
+  TypeError: Cannot read properties of undefined (reading 'id')
+      at SessionStore.update (src/session/store.ts:142:18)
+
+It only appears in cases that trigger multiple updates concurrently. Locate the cause, fix it, and run the full test suite once at the end to confirm.
+```
+
+Not sure where the cause is? Have it investigate first:
+
+```
+User report: after a successful login, the first page refresh sends them back to the login page; refreshing again works fine. Investigate the possible causes first, list the most suspicious spots, and wait for me to confirm a direction before making any changes.
+```
+
+For mechanical tasks, just hand it off:
+
+```
+Run the tests, fix any failing cases, and run them again to confirm everything is green.
+```
+
+## Writing tests and refactoring
+
+Tasks with clear boundaries and acceptance criteria are a great fit:
+
+```
+src/parser/markdown.ts currently has almost no tests. Add a set of unit tests covering plain paragraphs, nested lists, code blocks, tables, blockquotes, and mixed scenarios. Follow the existing test style in this project.
+```
+
+```
+Extract the repeated "read body → validate → write log → return" logic under src/handlers into a middleware. Run the tests after the changes and make sure existing behavior is unchanged.
+```
+
+For multi-file refactors, use Plan mode to confirm the plan first. Use `/fork` to explore alternative approaches.
+
+## One-off scripts and automation tasks
+
+Bulk edits, statistics, and research can be done with a single prompt:
+
+```
+Change all var declarations in .js files under src/ to const or let, preferring const when possible. Run lint after the changes to confirm.
+```
+
+```
+Analyze the access logs under logs/ for the past 7 days. Group by endpoint path and report the number of calls plus p50 and p99 response times. Output the result as a markdown table.
+```
+
+```
+Research the mainstream dependency injection options in TypeScript (tsyringe, inversify, awilix). Compare them along three dimensions: API style, decorator dependencies, and runtime overhead. Give me a recommendation within one page.
+```
+
+Use `--yolo` or `/yolo` to skip approvals, or set an allow list under [permission configuration](../configuration/config-files.md#permission) for a safer middle ground.
+
+## Generating and maintaining documentation
+
+```
+I just changed the interface signature of src/auth/login.ts. Update the corresponding JSDoc, the example code in the README, and any paragraph that mentions this interface under docs/en/guides.
+```
+
+```
+For every public function under src/api that does not have a docstring, add one. Match the style of the existing comments.
+```
+
+```
+Based on the command implementations under src/cli, generate a draft command reference listing each subcommand, its arguments, and default values. Put it under docs/en/reference for me to review later.
+```
+
+Archive or share a session with `kimi export <sessionId>`.
--- a/docs/en/index.md
+++ b/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
+---
--- a/docs/en/reference/keyboard.md
+++ b/docs/en/reference/keyboard.md
@ -0,0 +1,97 @@
+# Keyboard shortcuts
+
+The TUI interactive mode of Kimi Code CLI supports the keyboard shortcuts listed below. These keys primarily take effect inside the input box; some have different behavior inside popups (such as the `/help` panel or the approval panel) or during streaming output.
+
+Type `/help` at any time inside the TUI to open the built-in shortcut list.
+
+## General shortcuts
+
+The following keys are always available in the input box:
+
+| Shortcut | Action |
+| --- | --- |
+| `Enter` | Submit the current input |
+| `Shift-Enter` | Insert a newline in the input |
+| `↑` / `↓` | Browse input history |
+| `Esc` | Close popup / cancel completion / interrupt streaming output or an in-progress 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 |
+
+Pressing `Ctrl-C` **during streaming output** cancels immediately with no second confirmation needed.
+
+**Exiting the program** (pressing `Ctrl-C` when the input box is empty, or pressing `Ctrl-D`) uses a "double-press to confirm" mechanism: the first press shows a hint in the status bar (for example, `Press Ctrl+C again to exit`), and only a second press of the same key actually exits. Pressing any other key in between clears the confirmation state.
+
+## Mode switching
+
+| Shortcut | Action |
+| --- | --- |
+| `Shift-Tab` | Toggle Plan mode |
+
+Press `Shift-Tab` to turn Plan mode on or off. While Plan mode is on, the agent favors read-only tools for research and planning and can write the current plan file; when needed, it can also call `Bash`, which follows the current permission mode and ordinary rules without triggering an extra independent approval just because Plan mode is active. Toggling the mode alone does not create an empty plan file. Press `Shift-Tab` again to leave Plan mode.
+
+## Input and editing
+
+| Shortcut | Action |
+| --- | --- |
+| `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-E` | Expand or collapse the Plan card (when no Plan card is present, follows the system default behavior of moving the cursor to the end of the line) |
+| `Ctrl--` | Undo |
+
+Pressing `Ctrl-G` opens an external editor to edit the current input. The editor is chosen in the following order of priority:
+
+1. The editor configured by the `/editor` command
+2. The `$VISUAL` environment variable
+3. The `$EDITOR` environment variable
+
+After saving and exiting the editor, the edited content replaces the input box contents; exiting without saving leaves the input unchanged.
+
+When pasting an image or video, it appears in the input box as a placeholder, and the actual media data is sent to the model together with the message on submit. The preferred source is an image or file path on the system clipboard; on Linux, both Wayland and X11 are tried, and on WSL the Windows clipboard is also read via PowerShell as a fallback.
+
+## During streaming output
+
+While output is streaming, the input box still accepts input and supports the following extra actions:
+
+| Shortcut | Action |
+| --- | --- |
+| `Ctrl-S` | Steer: inject the current input into the running turn immediately |
+| `Esc` | Interrupt the current streaming output |
+| `Ctrl-C` | Interrupt the current streaming output |
+
+When you press `Ctrl-S`, the model sees your message at the next interruptible point, without waiting for the current turn to finish.
+
+## Tool output
+
+| Shortcut | Action |
+| --- | --- |
+| `Ctrl-O` | Expand or collapse tool output |
+
+When collapsed tool call results are present in the history, press `Ctrl-O` to toggle between collapsed and expanded views to inspect the full tool output.
+
+## Approval panel
+
+When the agent issues a tool call that requires confirmation, the TUI shows an approval panel. For the full approval flow, see [Interaction and Input](../guides/interaction.md#approval-flow); the table below lists the keys available inside the panel:
+
+| Shortcut | Action |
+| --- | --- |
+| `↑` / `↓` | Move the cursor between options |
+| `Enter` | Confirm the currently selected option |
+| `1` ~ `9` | Directly select the option with the matching number |
+| `Esc` / `Ctrl-C` / `Ctrl-D` | Reject the current request |
+| `Ctrl-E` | Expand or collapse the full content when the panel includes a diff or file preview |
+| `Ctrl-O` | Toggle the collapsed state of other tool output |
+
+Options that require additional feedback (such as "Reject" or "Revise") switch to a feedback input state after confirmation: type the feedback text directly and press `Enter` to submit, or press `Esc` to exit the feedback input and return to the option list.
+
+## Popup mode
+
+After typing `/help` to open the help panel, the following keys are available to navigate and close the panel:
+
+| Shortcut | Action |
+| --- | --- |
+| `↑` / `↓` | Scroll one line |
+| `PageUp` / `PageDown` | Scroll 10 lines |
+| `Esc` | Close the panel |
+| `Enter` | Close the panel |
+| `q` / `Q` | Close the panel |
--- a/docs/en/reference/kimi-command.md
+++ b/docs/en/reference/kimi-command.md
@ -0,0 +1,154 @@
+# kimi Command
+
+`kimi` is the main command of Kimi Code CLI, used to start an interactive session in the terminal. When run without any arguments, it opens a new session in the current working directory; with different flags, you can resume a previous session, skip approvals, start in Plan mode, or point at custom Skills directories.
+
+```sh
+kimi [options]
+kimi <subcommand> [options]
+```
+
+## Main command options
+
+The table below lists all options supported by the `kimi` main command. All flags are optional — running `kimi` on its own is enough 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, open the specified session directly; without an ID, enter the interactive picker to choose from historical sessions. |
+| `--continue` | `-C` | Continue the most recent session in the current working directory, without manually specifying an ID. |
+| `--model <model>` | `-m` | Use a model alias for this invocation. When omitted, new sessions use `default_model` from the config file, and resumed sessions use the session's current model. |
+| `--prompt <prompt>` | `-p` | Run one prompt non-interactively and stream assistant output to stdout. This mode uses `auto` permission for tool calls and does not open the TUI. |
+| `--output-format <format>` | | Set the non-interactive output format. Supported values are `text` and `stream-json`. Only valid with `--prompt`; defaults to `text`. |
+| `--yolo` | `-y` | Auto-approve ordinary tool calls, skipping approval requests; Plan mode `Bash` approval and Plan mode exit approval are not skipped. |
+| `--plan` | | Start a new session in Plan mode, where the AI favors read-only tools for exploration and planning and can write the current plan file; Plan mode `Bash` is handled separately according to the permission mode. |
+| `--skills-dir <dir>` | | Load Skills from the specified directory, replacing the auto-discovered user and project directories. Can be passed multiple times to stack several directories. See [Custom Skills directories](#custom-skills-directories) below. |
+
+`-r` / `--resume` is a hidden alias for `--session`; `--yes` and `--auto-approve` are hidden aliases for `--yolo`. They do not appear in the help output and behave identically to their official counterparts.
+
+::: warning Note
+`--yolo` skips human confirmation for ordinary tool calls, including file writes and shell command execution. Use it only inside trusted working directories. Plan mode exit approval is not skipped by `--yolo`; in Plan mode, `Bash` also follows the same ordinary allow rules as `--yolo`.
+:::
+
+### Flag conflict rules
+
+The following combinations are rejected at startup:
+
+- `--continue` and `--session` are mutually exclusive: both mean "resume a previous session" and overlap in meaning.
+- `--yolo` cannot be combined with `--continue` or `--session`: when resuming a session, the original session's approval settings are preserved. This rule only applies to interactive mode; in `--prompt` mode, `--yolo` is rejected earlier because it is mutually exclusive with `--prompt`.
+- `--plan` cannot be combined with `--continue` or `--session`: Plan mode only applies to new sessions.
+- `--prompt` cannot be combined with `--yolo` or `--plan`: non-interactive mode always uses `auto` permission and does not enter Plan mode.
+- `--prompt` can be combined with `--continue` or `--session <id>` with an ID; bare `--session` without an ID would open the interactive picker and therefore cannot be used in non-interactive mode.
+- `--output-format` can only be used with `--prompt`; the interactive TUI does not support writing the full event stream as stdout JSONL.
+
+If you need to force YOLO or Plan mode while resuming a session, switch into them from inside the interactive session via slash commands instead.
+
+## Typical usage
+
+The most common entry point is to run `kimi` directly to start a fresh session in the current directory:
+
+```sh
+kimi
+```
+
+If the previous session was interrupted (terminal closed, network disconnected, etc.) and you want to pick up where you left off, use `--continue`:
+
+```sh
+kimi --continue
+```
+
+This automatically finds and resumes the most recent session under the current working directory. To pick a different historical session, run `kimi --session` to enter the interactive picker, or pass a known session ID directly:
+
+```sh
+kimi --session 01HZ...XYZ
+```
+
+When the task is trivial and you don't want to be interrupted by frequent approval requests, add `--yolo`:
+
+```sh
+kimi --yolo
+```
+
+If you want the AI to read the code and produce an implementation plan first, rather than immediately editing files, use `--plan` to enter Plan mode:
+
+```sh
+kimi --plan
+```
+
+### Custom Skills directories
+
+To load custom Skills directories, you have two options:
+
+- **CLI flag `--skills-dir <dir>`**: Can be passed multiple times and **replaces** the auto-discovered user and project directories. Useful for temporary overrides or use in scripts. For example, to mount two directories at once:
+
+  ```sh
+  kimi --skills-dir /path/to/team-skills --skills-dir ./local-skills
+  ```
+
+- **`extra_skill_dirs` in `config.toml`**: Appends extra directories in the config file and **stacks** them with the auto-discovered ones. Suitable for persistent configuration of team-shared Skills (see [Agent Skills](../customization/skills.md)).
+
+## Non-interactive execution
+
+Use `-p` when a script or CI job needs to run one prompt:
+
+```sh
+kimi -p "Summarize the current repository status"
+```
+
+Output uses transcript-style blocks: thinking and assistant text start with `• `, with continuation lines indented by two spaces. Assistant text is written to stdout; thinking, tool progress, and the `To resume this session: kimi -r <id>` hint are written to stderr. Prompt mode does not wait for manual approvals: ordinary tool calls, Plan approvals, and agent questions follow the `auto` permission policy. Static deny rules still block matching tool calls.
+
+To switch models for a single invocation, add `-m`:
+
+```sh
+kimi -m kimi-code/kimi-for-coding -p "Explain the latest diff"
+```
+
+If a script needs structured output, use JSONL:
+
+```sh
+kimi -p "List changed files" --output-format stream-json
+```
+
+In `stream-json` mode, each stdout line is one JSON object. Ordinary replies are emitted as assistant messages. If the model calls tools, the output first includes an assistant message with `tool_calls`, then the corresponding tool message, followed by later assistant messages. Thinking content is not written to JSONL; tool progress and the resume-session hint still go to stderr.
+
+## Subcommands
+
+### `kimi export`
+
+Bundle a session into a ZIP file for sharing, archival, or bug reports. The exported archive contains all files under the session directory, such as context records, state files, and the session diagnostic log if that session has already produced `logs/kimi-code.log`.
+
+```sh
+kimi export [sessionId] [options]
+```
+
+| Argument / Option | Short | Description |
+| --- | --- | --- |
+| `sessionId` | | The ID of the session to export. When omitted, the most recent session under the current working directory is selected automatically and a confirmation is requested. |
+| `--output <path>` | `-o` | Output path for the ZIP file. 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` | | Skip bundling the active global diagnostic log, `~/.kimi-code/logs/kimi-code.log`. It is included by default. |
+
+By default, export includes files inside the target session directory. If that directory contains `logs/kimi-code.log`, it appears in the ZIP as `logs/kimi-code.log`. The global diagnostic log at `~/.kimi-code/logs/kimi-code.log` is also bundled by default, because it may contain events from other sessions or projects. Add `--no-include-global-log` when you do not want to share it. When included, its ZIP path is `logs/global/kimi-code.log`; rotated files such as `kimi-code.log.1` are not bundled.
+
+When `sessionId` is omitted, the command first prints the session to be exported and asks for confirmation; `-y` skips this prompt, which is handy for scripts:
+
+```sh
+# Export the most recent session under the current working 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 to avoid sharing events from other sessions
+kimi export 01HZ...XYZ -o ./bug-report.zip --no-include-global-log
+```
+
+### `kimi migrate`
+
+Migrate local data from an older version of kimi-cli to kimi-code. This command has no flags and runs fully interactively, guiding you through the entire migration process.
+
+```sh
+kimi migrate
+```
+
+If you previously used an older version of kimi-cli, run this command to migrate historical sessions, configuration, and other data to kimi-code to avoid data loss. For the full migration flow, what gets migrated, and things to watch out for, see [Migrating from kimi-cli](../guides/migration.md).
--- a/docs/en/reference/slash-commands.md
+++ b/docs/en/reference/slash-commands.md
@ -0,0 +1,86 @@
+# Slash Commands
+
+Slash commands are built-in control commands provided by Kimi Code CLI in the interactive TUI, used to switch modes, manage sessions, view status, and more. Type `/` in the input box to trigger command completion; the candidate list filters in real time as you continue typing, and command aliases participate in matching as well.
+
+After typing a full command name (such as `/help`), press `Enter` to execute it. If the `/`-prefixed input does not match any built-in or skill command, it is sent to the agent as an ordinary message.
+
+::: tip Tip
+Some commands are only available in the idle state. Running them while the session is streaming a response or compacting the context will be blocked, with a hint to press `Esc` or `Ctrl-C` first to interrupt the current operation. The "Always available" column in the tables below marks commands that remain available during streaming or compacting.
+:::
+
+## Account and configuration
+
+| Command | Alias | Description | Always available |
+| --- | --- | --- | --- |
+| `/login` | — | Pick an account or platform and sign in: Kimi Code uses the OAuth device code flow, while the Moonshot AI Open Platform signs in with an API key. | No |
+| `/logout` | — | Clear the credentials of the currently selected account (Kimi Code OAuth credentials, or the corresponding open platform provider config). | No |
+| `/model` | — | Switch the LLM model used by the current session. | Yes |
+| `/settings` | `/config` | Open the settings panel inside the TUI. | Yes |
+| `/permission` | — | Choose 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 brand-new session, discarding the current context. | No |
+| `/sessions` | `/resume` | Browse historical sessions and switch to or resume one. | Yes |
+| `/tasks` | `/task` | Browse the background task list. | Yes |
+| `/fork` | — | Fork a new session from the current one, preserving the full conversation history. | No |
+| `/title [<text>]` | `/rename` | Without arguments, show the current session title; with an argument, set it as the new title (up to 200 characters). | Yes |
+| `/compact [<instruction>]` | — | Compact the current conversation context to free up token usage; optionally pass a custom instruction telling the model what to preserve during compaction. | No |
+| `/init` | — | Analyze the current codebase and generate `AGENTS.md`. | No |
+
+## Mode and runtime control
+
+| Command | Alias | Description | Always available |
+| --- | --- | --- | --- |
+| `/yolo [on\|off]` | `/yes` | Toggle auto-approve mode. Without arguments, flip the current state; pass `on`/`off` explicitly to force the corresponding state. When enabled, ordinary tool call approvals are skipped; the Plan mode exit approval is not skipped. | Yes |
+| `/plan [on\|off]` | — | Toggle Plan mode. Without arguments, flip the current state; pass `on`/`off` explicitly to force the corresponding state. Toggling alone does not create an empty plan file. | Yes |
+| `/plan clear` | — | Clear the current plan. | No |
+
+::: warning Note
+`/yolo` skips approval confirmation for ordinary tool calls. Make sure you understand the potential risks before enabling it. It does not skip the approval required to leave Plan mode; in Plan mode, `Bash` follows the same ordinary allow rules as `/yolo`.
+:::
+
+## Information and status
+
+| Command | Alias | Description | Always available |
+| --- | --- | --- | --- |
+| `/help` | `/h`, `/?` | Show keyboard shortcuts and all available commands. | Yes |
+| `/usage` | — | Show token usage, context consumption, and quota information. | Yes |
+| `/status` | — | Show the current session runtime status, including version, model, working directory, and permission mode. | Yes |
+| `/mcp` | — | List the MCP servers in the current session and their connection status. | Yes |
+| `/version` | — | Show the Kimi Code CLI version number. | Yes |
+| `/feedback` | — | Submit feedback to help improve Kimi Code CLI. | Yes |
+
+## Exit
+
+| Command | Alias | Description | Always available |
+| --- | --- | --- | --- |
+| `/exit` | `/quit`, `/q` | Exit Kimi Code CLI. | No |
+
+## Dynamic skill commands
+
+In addition to the built-in commands, user-activatable skills are automatically registered as slash commands under the `skill:` namespace:
+
+```
+/skill:<name> [extra text]
+```
+
+For example, `/skill:code-style` loads the content of the `code-style` skill and sends it to the agent; any text after the command is appended to the skill prompt, as in `/skill:git-commits fix the login failure issue`.
+
+For convenience, skill commands also support a short form `/<name>` that omits the `skill:` prefix, provided the name is not already taken by a built-in command. In other words, `/code-style` falls back to matching `/skill:code-style`.
+
+Kimi Code CLI ships with a built-in `mcp-config` skill for configuring MCP servers and handling MCP OAuth login. It still belongs to the skill namespace in completion and help (`/skill:mcp-config`), and it can also be invoked directly as `/mcp-config`.
+
+Skill types that can be exposed as slash commands include `prompt`, `inline`, `flow`, and skills without an explicitly declared type. For skill installation and authoring, see [Agent Skills](../customization/skills.md).
+
+::: info Note
+All skill commands are only available while the agent is idle; during streaming or compacting, press `Esc` or `Ctrl-C` first to interrupt the current operation.
+:::
+
+::: info Note
+Flow-type skills are also exposed via `/skill:<name>`; there is no separate `/flow:` namespace.
+:::
--- a/docs/en/reference/tools.md
+++ b/docs/en/reference/tools.md
@ -0,0 +1,104 @@
+# Built-in tools
+
+Built-in tools are the toolset that Kimi Code CLI ships with its core engine — no MCP server installation required. During each conversation, the agent automatically selects and invokes these tools based on the task at hand; users can also inspect every tool call in detail through the approval request 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 needed. Both follow a unified approval mechanism: **read-only tools** (such as `Read`, `Grep`, `Glob`, and `WebSearch`) are auto-approved by default, while **write and execute tools** (such as `Write`, `Edit`, `Bash`, and `TaskStop`) require user approval by default. In YOLO mode, approval for ordinary tool calls is skipped, but exit approval in Plan mode is not affected.
+
+## File tools
+
+File tools handle reading, writing, and searching the local filesystem, and are the foundational tools for code analysis and modification tasks.
+
+| Tool | Default approval | Description |
+| --- | --- | --- |
+| `Read` | Auto-approved | Read the contents of a text file |
+| `Write` | Requires approval | Create or overwrite a file |
+| `Edit` | Requires approval | Exact string replacement |
+| `Grep` | Auto-approved | Full-text search powered by ripgrep |
+| `Glob` | Auto-approved | Find files by glob pattern |
+| `ReadMediaFile` | Auto-approved | Read an image or video file |
+
+**`Read`** accepts a file path (`path`) along with the optional `line_offset` (starting line number; negative values count from the end) and `n_lines` (maximum number of lines to read). At most 1000 lines or 100 KB are returned per call, with a truncation notice appended for anything beyond that limit. If the file is an image or video, the tool suggests using `ReadMediaFile` instead.
+
+**`Write`** accepts `path`, `content`, and an optional `mode` (`overwrite` or `append`; defaults to overwrite). The parent directory must already exist; `append` mode appends content to the end of the file without automatically inserting a newline.
+
+**`Edit`** accepts `path`, `old_string` (the exact text to replace), and `new_string` (the replacement text). By default it replaces only a single unique match; if the same content appears more than once in the file, the tool returns an error and suggests using `replace_all: true`. `old_string` and `new_string` must differ.
+
+**`Grep`** invokes ripgrep to search file contents. It supports regular expressions (`pattern`), a search path (`path`), file-type filtering (`type`, e.g. `ts`, `py`), glob filtering (`glob`), and an output mode (`output_mode`: `files_with_matches` / `content` / `count_matches`, defaulting to `files_with_matches`). `content` mode supports `-A`, `-B`, and `-C` context-line arguments along with `-i` (case-insensitive), `-n` (line numbers, default true), and `multiline` (cross-line matching). All modes support `offset` + `head_limit` pagination; `head_limit` defaults to 250, and passing 0 removes the limit. In `files_with_matches` mode, results are sorted by the most recent file modification time in descending order; other modes preserve ripgrep's original output order. Sensitive files such as `.env`, private keys, `.aws/credentials`, and `.gcp/credentials` are automatically filtered out; `include_ignored=true` also searches files ignored by `.gitignore` and the like, but sensitive files remain filtered.
+
+**`Glob`** matches files against a glob pattern (`pattern`) within a specified directory (`path`, defaulting to the working directory). Results are sorted by modification time in descending order, with a maximum of 1000 entries. The optional `include_dirs` (default true) controls whether directory entries are returned. Pure wildcard patterns (such as `**` or `**/*`) are rejected with a prompt to add a literal anchor; patterns containing brace expansion (`{a,b,c}`) are likewise rejected — the underlying glob engine treats `{` and `}` as literals, so such patterns silently match zero files.
+
+**`ReadMediaFile`** sends an image or video file to the model as multimodal content, accepting only `path`. The file size limit is 100 MB. Tool 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 versatile and the most permission-sensitive tool. It accepts `command` (required) along with the optional `cwd` (working directory), `timeout` (milliseconds), `description` (background task description, required when `run_in_background=true`), `run_in_background` (whether to run as a background task), and `disable_timeout` (whether to disable the timeout for a background task). The foreground `timeout` defaults to 60 seconds and is capped at 5 minutes; the background `timeout` defaults to 10 minutes and is also capped at 10 minutes.
+
+In foreground mode `Bash` blocks the current turn until the command finishes or times out; in background mode it returns a task ID immediately. Background tasks time out after 10 minutes by default; if a task really needs to run without a timeout, set `disable_timeout=true`. When the task completes, fails, or is stopped, the agent is automatically notified to continue processing; during execution, the result can also be inspected explicitly via `TaskOutput`. stdin is always closed, so interactive commands receive EOF immediately. A two-phase termination strategy (SIGTERM → 5-second grace period → SIGKILL) ensures processes terminate reliably after a timeout. On Windows, Git Bash is used as the shell by default.
+
+## Network tools
+
+| Tool | Default approval | Description |
+| --- | --- | --- |
+| `WebSearch` | Auto-approved | Search the web |
+| `FetchURL` | Auto-approved | Fetch the content of a given URL |
+
+**`WebSearch`** accepts `query` (search terms) and the optional `limit` (number of results to return, 1–20, default 5) and `include_content` (whether to return the page body; default false — enabling this consumes significantly more tokens). This tool requires the host to provide a search implementation; if no implementation is injected, it 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 main article body (`extracted`) rather than returning the full HTML; plain-text or Markdown pages are passed through directly (`passthrough`). Likewise requires a host-injected implementation.
+
+## Plan mode
+
+| Tool | Default approval | Description |
+| --- | --- | --- |
+| `EnterPlanMode` | Auto-approved | Enter Plan mode |
+| `ExitPlanMode` | Auto-approved (requires user plan confirmation) | Exit Plan mode and submit the plan |
+
+Plan mode is a constrained working state: once entered, `Write` and `Edit` are tightened — they may only write to the current plan file, and other paths are blocked; `TaskStop` is also blocked entirely. The remaining tools (including `Bash`) are still governed by the current permission rules, so a `Bash` command can in principle still modify files — whether it is allowed depends on the active approval policy.
+
+**`EnterPlanMode`** takes no parameters. On success it returns workflow instructions, including the plan file path if one was provided by the host.
+
+**`ExitPlanMode`** reads the current plan file contents, presents the plan to the user for approval, and then exits Plan mode. The optional `options` parameter lets the agent provide 1–3 alternative proposals (each with a `label` and `description`; the `label` is capped at 80 characters) for the user to choose from during approval. Labels must be unique and cannot use the reserved words `Approve`, `Reject`, `Reject and Exit`, or `Revise` (the system uses these to mark approval results). Once the user approves, all tools become available again; if the user requests changes, the agent remains in Plan mode.
+
+## State management
+
+| Tool | Default approval | Description |
+| --- | --- | --- |
+| `TodoList` | Auto-approved | Manage the 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 a `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-approved | Spawn a subagent to execute a subtask |
+| `AskUserQuestion` | Auto-approved | Ask the user a question to obtain structured input |
+| `Skill` | Auto-approved | Invoke a registered inline skill |
+
+**`Agent`** delegates a subtask to a subagent. Required parameters are `prompt` (the full task description) and `description` (a short 3–5 word summary for UI display). Optional parameters include `subagent_type` (agent type, default `coder`), `resume` (the ID of an existing agent to resume), `run_in_background` (whether to run in the background, default false), and `timeout` (timeout in seconds, 30–3600). `subagent_type` and `resume` are mutually exclusive: when resuming an existing agent, addressing is done solely by ID. When the foreground `timeout` is omitted, the subagent runs to completion with no time limit; when the background `timeout` is omitted, it falls back to `[background] agent_task_timeout_s` in `config.toml`, and if that field is also unset, there is no time limit. In foreground mode the parent agent waits for the subagent to complete before continuing; in background mode it returns a task ID immediately, and upon completion a synthetic user message automatically routes control back to the main agent, with no polling required. For details on the subagent system, see [Subagents](../customization/agents.md).
+
+**`AskUserQuestion`** presents the user with a structured multiple-choice question, suitable for disambiguation or option-selection scenarios. The `questions` parameter accepts 1–4 questions; each question requires a `question` (question text ending with `?`), `options` (2–4 choices, each with a `label` and `description`), and the optional `header` (a short category label of up to 12 characters, such as `Auth` or `Style`) and `multi_select` (whether multiple choices are allowed, default false). An "Other" option is automatically appended by the system, so there is no need to provide it manually in `options`. If the host does not implement interactive questioning, this tool returns a failure notice and the agent should instead ask the user directly in its text reply.
+
+**`Skill`** allows the agent to explicitly invoke a registered inline-type skill. It accepts `skill` (the skill name) and an optional `args` (additional argument text). Only skills with `type = "inline"` can be invoked through this tool; other types (such as `prompt` or `flow`) and skills that set `disableModelInvocation: true` in their frontmatter are rejected. To prevent recursive infinite loops, skill nesting depth is limited to 3 levels. For details on the skill system, see [Skills](../customization/skills.md).
+
+## Background tasks
+
+Background task tools manage background tasks started via `Bash` or `Agent`. When a background task reaches a terminal state such as completed, failed, stopped, or lost, its status and tail output are automatically sent back to the agent; use `TaskOutput` only when you want to inspect progress before that automatic notification arrives.
+
+| Tool | Default approval | Description |
+| --- | --- | --- |
+| `TaskList` | Auto-approved | List background tasks |
+| `TaskOutput` | Auto-approved | View the output of a background task |
+| `TaskStop` | Requires approval | Stop a running background task |
+
+**`TaskList`** returns a list of background tasks; each record includes the task ID, status, command, description, and PID. Optional parameters: `active_only` (default true, lists only running tasks) and `limit` (maximum number of entries to return, default 20, range 1–100). Tasks that have reached a terminal state also include `exit_code`; tasks explicitly terminated by `TaskStop` additionally include `reason`.
+
+**`TaskOutput`** returns the status and output of a specified task by `task_id`. The inline preview includes at most the most recent 32 KB of content; the full log is saved on disk, and the tool also returns `output_path` with a prompt to paginate it via `Read` (around 300 lines per page is recommended). Optional `block` (default false) and `timeout` (seconds to wait, default 30, range 0–3600) parameters can be used to wait for the task to finish before returning. In the response, `retrieval_status` is one of `success` / `timeout` / `not_ready`; tasks aborted by an external deadline timeout additionally include `timed_out: true` and `terminal_reason: timed_out`, and tasks explicitly terminated by `TaskStop` additionally include `stop_reason` and `terminal_reason: stopped`.
+
+**`TaskStop`** accepts `task_id` and an optional `reason` (reason for stopping, default `Stopped by TaskStop`). It is safe to call on a task that is already in a terminal state — it returns the current status without error.
--- a/docs/en/release-notes/changelog.md
+++ b/docs/en/release-notes/changelog.md
@ -0,0 +1,5 @@
+# Changelog
+
+::: info Note
+Detailed release notes will be published alongside the first official release.
+:::
--- a/docs/index.md
+++ b/docs/index.md
@ -0,0 +1,29 @@
+---
+layout: home
+hero:
+  name: Kimi Code CLI
+  text: ' '
+  actions:
+    - theme: brand
+      text: 简体中文
+      link: zh/
+    - theme: alt
+      text: English
+      link: en/
+---
+
+<script setup>
+import { onMounted } from 'vue'
+import { useRouter, withBase } from 'vitepress'
+
+const router = useRouter()
+
+onMounted(() => {
+  const lang = navigator.language || navigator.userLanguage
+  if (lang.startsWith('en')) {
+    router.go(withBase('/en/'))
+  } else {
+    router.go(withBase('/zh/'))
+  }
+})
+</script>
--- a/docs/media/intro.gif
+++ b/docs/media/intro.gif
--- a/docs/package.json
+++ b/docs/package.json
@ -0,0 +1,19 @@
+{
+  "name": "kimi-code-docs",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "dev": "vitepress dev",
+    "build": "vitepress build",
+    "preview": "vitepress preview"
+  },
+  "devDependencies": {
+    "vitepress": "^1.5.0"
+  },
+  "dependencies": {
+    "mermaid": "^11.12.2",
+    "vitepress-plugin-llms": "^1.10.0",
+    "vitepress-plugin-mermaid": "^2.0.17"
+  }
+}
--- a/docs/pnpm-lock.yaml
+++ b/docs/pnpm-lock.yaml
--- a/docs/public/favicon.ico
+++ b/docs/public/favicon.ico
--- a/docs/zh/configuration/config-files.md
+++ b/docs/zh/configuration/config-files.md
@ -0,0 +1,228 @@
+# 配置文件
+
+Kimi Code CLI 把全局配置保存在一份 TOML 文件中，包含 API 供应商、模型别名、Agent 循环参数、后台任务、外部服务等。这份文档介绍配置文件的位置、顶层字段、各嵌套结构，以及一份完整示例。
+
+## 配置文件位置
+
+默认配置文件位于 `~/.kimi-code/config.toml`。目录和文件会在首次运行时自动创建，并设置严格的访问权限。
+
+如果你希望把数据目录放到别处，可以通过环境变量 `KIMI_CODE_HOME` 覆盖默认路径：
+
+```sh
+export KIMI_CODE_HOME=/path/to/kimi-home
+```
+
+此时配置文件路径变为 `$KIMI_CODE_HOME/config.toml`。无论目录在哪里，文件名固定为 `config.toml`。
+
+::: tip 提示
+TOML 中的字段名一律使用 snake_case（例如 `default_model`、`max_context_size`）。如果 key 中包含 `.`，需要使用带引号的 TOML key，否则 TOML 会把 `.` 当作嵌套表分隔符。
+:::
+
+## 顶层字段
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `default_model` | `string` | — | 默认使用的模型别名，必须在 `models` 中定义 |
+| `default_thinking` | `boolean` | `false` | 新会话启动时 Thinking 开关的初始值，可在会话内通过模型菜单切换。即使该字段为 `true`，`[thinking].mode = "off"` 也会强制禁用 Thinking。详见下文 [`thinking`](#thinking) |
+| `default_permission_mode` | `string` | `manual` | 新会话的默认权限模式，可选 `manual`、`auto`、`yolo` |
+| `default_plan_mode` | `boolean` | `false` | 新会话是否默认以 Plan 模式启动；省略等同 `false` |
+| `merge_all_available_skills` | `boolean` | `true` | 是否合并所有可用目录中的 Agent Skills |
+| `extra_skill_dirs` | `array<string>` | — | 额外的 Skill 搜索目录，会叠加到默认目录之上 |
+| `telemetry` | `boolean` | `true` | 是否启用匿名遥测；仅在显式设为 `false` 时关闭 |
+| `providers` | `table` | `{}` | API 供应商表，详见下文 |
+| `models` | `table` | — | 模型别名表，详见下文 |
+| `thinking` | `table` | — | Thinking 模式默认参数 |
+| `loop_control` | `table` | — | Agent 循环控制参数 |
+| `background` | `table` | — | 后台任务运行参数 |
+| `services` | `table` | — | 内置外部服务配置 |
+| `permission` | `table` | — | 权限规则配置，详见下文 |
+| `hooks` | `array<table>` | — | 生命周期 hook 配置，详见 [Hooks](../customization/hooks.md) |
+
+## 完整示例
+
+```toml
+default_model = "kimi-code/kimi-for-coding"
+default_thinking = true
+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/kimi-for-coding"]
+provider = "managed:kimi-code"
+model = "kimi-for-coding"
+max_context_size = 262144
+
+[thinking]
+mode = "auto"
+
+[loop_control]
+max_steps_per_turn = 1000
+max_retries_per_step = 3
+reserved_context_size = 50000
+
+[background]
+max_running_tasks = 4
+keep_alive_on_exit = false
+agent_task_timeout_s = 900
+
+[[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
+```
+
+## `providers`
+
+`providers` 表中的每一项定义一个 API 供应商连接信息，以唯一的名称作为 key。
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `type` | `string` | 是 | 供应商类型，可选 `anthropic`、`openai`、`kimi`、`google-genai`、`openai_responses`、`vertexai` |
+| `api_key` | `string` | 否 | API 密钥 |
+| `base_url` | `string` | 否 | API 基础 URL |
+| `oauth` | `table` | 否 | OAuth 凭据引用，详见下文 |
+| `env` | `table<string, string>` | 否 | 按供应商约定的键读取的配置子表，作为 `api_key` / `base_url` 等字段的备用来源（如 `KIMI_API_KEY`、`ANTHROPIC_API_KEY`、`GOOGLE_CLOUD_PROJECT` 等）。这只是写在配置文件里的子表，**不会真正写入到终端的环境变量**；仅在 `[providers.<name>]` 上直接字段缺省时被 CLI 读取 |
+| `custom_headers` | `table<string, string>` | 否 | 请求时附加的自定义 HTTP 头 |
+
+OAuth 凭据引用结构：
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `storage` | `string` | 是 | 凭据存储位置；目前只支持 `"file"` |
+| `key` | `string` | 是 | 凭据条目的唯一标识 |
+
+```toml
+[providers.openai]
+type = "openai"
+base_url = "https://api.openai.com/v1"
+api_key = "sk-xxx"
+custom_headers = { "X-Custom-Header" = "value" }
+```
+
+## `models`
+
+`models` 表中的每一项定义一个模型别名，以唯一的名称作为 key。
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `provider` | `string` | 是 | 使用的供应商名称，必须在 `providers` 中定义 |
+| `model` | `string` | 是 | 调用 API 时使用的模型标识符 |
+| `max_context_size` | `integer` | 是 | 最大上下文长度（token 数），必须大于等于 1 |
+| `max_output_size` | `integer` | 否 | 单次请求的输出预算上限（即请求层面的 `max_tokens`）。目前仅 `anthropic` 供应商会读取该字段。当别名能识别到具体的 Claude 家族时，覆盖值不会超过模型允许的上限，避免超出服务端限制。省略时使用模型推导出的默认值，详见 [`providers.md`](./providers.md#anthropic)。 |
+| `capabilities` | `array<string>` | 否 | 显式追加的模型能力标签，例如 `thinking`、`image_in`、`video_in`、`audio_in`、`tool_use` |
+| `display_name` | `string` | 否 | 在 UI 中显示的名称，未设置时回退到 `model` |
+
+`capabilities` 与供应商 capability registry 按模型名前缀自动匹配出来的能力做并集 —— 只能追加、不能移除。通常无需手写；只有当模型未被 registry 覆盖、或希望强制启用某项能力时才用得到。
+
+如果模型别名包含 `.`，需要使用带引号的 key：
+
+```toml
+[models."gpt-4.1"]
+provider = "openai"
+model = "gpt-4.1"
+max_context_size = 1047576
+```
+
+## `thinking`
+
+`thinking` 控制 Thinking 模式的默认行为。即便顶层 `default_thinking = true`，将 `mode` 设为 `"off"` 也会强制禁用 Thinking。
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `mode` | `string` | — | 触发策略，可选 `auto`、`on`、`off`。设为 `"off"` 时强制禁用 Thinking；其它取值或省略时不禁用，由会话内的 Thinking 开关与 `effort` 共同决定 |
+| `effort` | `string` | `high` | 启用 Thinking 时使用的默认强度，可选 `low`、`medium`、`high`、`xhigh`、`max`，实际可用等级由供应商决定 |
+
+## `loop_control`
+
+`loop_control` 控制 Agent 执行循环的步数、重试和上下文压缩阈值。
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `max_steps_per_turn` | `integer` | `1000` | 单轮最大步数 |
+| `max_retries_per_step` | `integer` | `3` | 单步最大重试次数 |
+| `reserved_context_size` | `integer` | — | 预留给响应生成的 token 数；上下文逼近该阈值时触发压缩 |
+
+## `background`
+
+`background` 控制后台任务的运行限制。后台任务通过 `Bash` 工具或 `Agent` 工具的 `run_in_background=true` 参数启动。
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `max_running_tasks` | `integer` | — | 同时运行的最大后台任务数 |
+| `keep_alive_on_exit` | `boolean` | `true` | 会话关闭时是否保留仍在运行的后台任务。设为 `false` 后，`kimi -p` 完成退出、SDK 关闭 session 或 harness 关闭时会请求停止后台任务 |
+| `agent_task_timeout_s` | `integer` | — | 后台 Agent 任务的最大运行时间（秒） |
+
+`keep_alive_on_exit` 可以被环境变量 `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` 覆盖；环境变量优先级高于 `config.toml`。schema 还预留了 `kill_grace_period_ms`、`print_wait_ceiling_s` 两个字段，目前仅 schema 校验通过，CLI 运行时不会读取。
+
+## `services`
+
+`services` 配置 Kimi Code CLI 调用的内置外部服务。当前仅识别 `moonshot_search`（网页搜索）和 `moonshot_fetch`（网页抓取）两个固定 key，其他 key 会被忽略。两项的字段相同：
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `base_url` | `string` | 否 | 服务 API URL |
+| `api_key` | `string` | 否 | API 密钥 |
+| `oauth` | `table` | 否 | OAuth 凭据引用，结构同 `providers.*.oauth` |
+| `custom_headers` | `table<string, string>` | 否 | 请求时附加的自定义 HTTP 头 |
+
+```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` 配置会话启动时加载的初始权限规则，控制工具调用的默认审批行为。新会话的默认权限模式由顶层 `default_permission_mode` 控制；启动时显式传入的权限模式（例如 CLI 的 `--yolo`）会覆盖这个默认值。
+
+规则通过 `[[permission.rules]]` 数组表写出，每条规则包含以下字段：
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `decision` | `string` | 是 | 决策结果，可选 `allow`、`deny`、`ask` |
+| `scope` | `string` | 否 | 规则作用域，可选 `turn-override`、`session-runtime`、`project`、`user`；默认 `user` |
+| `pattern` | `string` | 是 | 匹配模式，格式为 `ToolName` 或 `ToolName(arg-pattern)`。`ToolName` 必须与运行时真实工具名一致——内置工具是 `Read`、`Write`、`Edit`、`Bash`、`Grep` 等（详见 [内置工具](../reference/tools.md)） |
+| `reason` | `string` | 否 | 规则说明，供调试或审计使用 |
+
+示例：
+
+```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 的声明配置写在 `~/.kimi-code/mcp.json` 或项目内 `.kimi-code/mcp.json` 中，不在 `config.toml` 里。交互式配置入口是 `/mcp-config`，详见 [Model Context Protocol](../customization/mcp.md)。
+:::
--- a/docs/zh/configuration/data-locations.md
+++ b/docs/zh/configuration/data-locations.md
@ -0,0 +1,131 @@
+# 数据路径
+
+Kimi Code CLI 将运行时数据集中存储在用户主目录下的 `~/.kimi-code/` 目录中。本页介绍各类数据的存放位置、用途，以及如何自定义和清理。
+
+## 数据根目录
+
+默认数据根是 `~/.kimi-code/`。`~` 由 Node.js 的 `os.homedir()` 解析，因此实际路径在不同平台略有差异：macOS 上是 `/Users/<name>/.kimi-code`，Linux 上是 `/home/<name>/.kimi-code`，Windows 上是 `C:\Users\<name>\.kimi-code`。
+
+可以通过 `KIMI_CODE_HOME` 环境变量覆盖到任意路径：
+
+```sh
+export KIMI_CODE_HOME="$HOME/.config/kimi-code"
+```
+
+设置后，配置、会话、日志、输入历史、更新缓存、OAuth 凭据等运行时数据都会落到该路径下。`KIMI_CODE_HOME` 与其他环境变量的完整说明见 [环境变量](./env-vars.md)。
+
+::: tip 例外
+**内置工具缓存**（例如自动下载的 ripgrep 二进制）不走 `KIMI_CODE_HOME`，而是走 `KIMI_CODE_CACHE_DIR`；未设置时使用平台缓存目录——macOS 上是 `~/Library/Caches/kimi-code`，Linux 上是 `$XDG_CACHE_HOME/kimi-code`（缺省 `~/.cache/kimi-code`），Windows 上是 `%LOCALAPPDATA%\kimi-code`。
+
+用户级 Agent Skills 的搜索目录位于 `~/.kimi-code/skills` 与 `~/.agents/skills`；项目级则是工作目录下的 `.kimi-code/skills` 与 `.agents/skills`。详见 [Agent Skills](../customization/skills.md)。
+:::
+
+## 目录结构
+
+数据根下的典型布局如下：
+
+```
+$KIMI_CODE_HOME  (默认 ~/.kimi-code)
+├── config.toml             # 用户配置
+├── mcp.json                # 用户级 MCP server 声明（可选）
+├── session_index.jsonl     # 会话索引
+├── credentials/            # OAuth 凭据根目录（目录 0o700、文件 0o600）
+│   ├── <name>.json         # 托管 Kimi / Open Platform 等 provider OAuth 凭据
+│   └── mcp/                # MCP server OAuth 凭据
+│       └── <key>-<suffix>.json
+├── sessions/               # 会话数据
+│   └── <workDirKey>/
+│       └── <sessionId>/
+│           ├── state.json
+│           ├── logs/
+│           │   └── kimi-code.log
+│           ├── tasks/          # 后台任务持久化
+│           │   ├── <task_id>.json
+│           │   └── <task_id>/
+│           │       └── output.log
+│           └── agents/
+│               ├── main/
+│               │   ├── wire.jsonl
+│               │   └── plans/  # Plan 模式计划文件
+│               └── agent-0/
+│                   └── wire.jsonl
+├── bin/
+│   └── rg                  # ripgrep 缓存（Windows 为 rg.exe）
+├── logs/                   # 全局诊断日志
+│   └── kimi-code.log
+├── updates/
+│   └── latest.json         # 更新检查状态
+└── user-history/
+    └── <md5(workDir)>.jsonl
+```
+
+::: tip
+上面的目录树展示的是默认数据根（`~/.kimi-code/`）下的典型布局。Agent Skills 与内置工具缓存的路径略有特殊性，详见上方"例外"提示。
+:::
+
+## 配置文件
+
+`config.toml` 是 Kimi Code CLI 的主配置文件，存放供应商、模型、循环控制等用户级设置。详见 [配置文件](./config-files.md)。
+
+`mcp.json` 是用户级 MCP server 声明，会与项目内的 `.kimi-code/mcp.json` 合并加载。字段与项目级文件相同，详见 [MCP](../customization/mcp.md)。
+
+OAuth 凭据以文件形式存放在数据根下的 `credentials/` 子目录，目录权限 `0o700`、文件权限 `0o600`，仅当前用户可读写。其中：
+
+- **托管 Kimi / Open Platform 等供应商的 OAuth 凭据**位于 `credentials/<name>.json`，例如 `~/.kimi-code/credentials/managed:kimi-code.json`。
+- **MCP server 的 OAuth 凭据**位于 `credentials/mcp/` 子目录下，文件名按 server key 自动生成，例如 `credentials/mcp/<key>-<suffix>.json`。
+
+凭据写入采用 `tmp → fsync → rename` 的原子流程；POSIX 下严格保证原子性，Windows 上则尽最大努力保证。
+
+## 会话数据
+
+会话相关的数据集中在 `sessions/` 下，并通过顶层 `session_index.jsonl` 维护一份 JSONL 索引：每行一条记录，包含 `sessionId`、`sessionDir`、`workDir` 三个字段。索引在创建会话时追加写入，加载时会校验 `sessionDir` 是否仍在 `sessions/` 下、且最后一级目录名等于 `sessionId`，以防止外部篡改指向非法路径。
+
+每个会话目录的路径形如 `sessions/<workDirKey>/<sessionId>/`，其中 `workDirKey` 是按工作目录编码出来的桶名，格式为 `wd_<slug>_<sha256前12位>`（例如 `wd_myproject_a3f8c1d20e9b`），`sessionId` 是会话的唯一标识。`sessions/` 整条路径包括 `<workDirKey>/` 桶都按 `0o700` 权限创建，仅当前用户可访问。
+
+会话目录的内部结构包含：
+
+- `state.json`：会话标题、`lastPrompt`、`createdAt`、`updatedAt`、`isCustomTitle`、`forkedFrom` 以及各个 Agent 的元数据。
+- `agents/main/wire.jsonl`：主 Agent 的 Wire 事件流（内部通信记录），用于回放和恢复。`main` 是主 Agent 的固定 id。
+- `agents/main/plans/`：Plan 模式下主 Agent 写入的计划文件，按计划 id 命名为 `<id>.md`。
+- `agents/agent-0/`、`agents/agent-1/` 等：子 Agent 实例的目录，各自包含 `wire.jsonl`。子 Agent id 由会话内的递增计数器生成（`agent-` 加从 0 起的整数）。
+- `logs/kimi-code.log`：该会话的诊断日志。只有发生被记录的诊断事件时才会出现；普通对话不一定产生这个文件。
+- `tasks/`：后台任务持久化目录。每个任务在 `tasks/<task_id>.json` 保存元信息（状态、pid、退出码等），标准输出与标准错误写入 `tasks/<task_id>/output.log`。任务 id 格式为 `bash-` 或 `agent-` 前缀加 8 位随机字母数字（如 `bash-a1b2c3d4`）。
+
+`sessionId` 仅允许 `[A-Za-z0-9._-]+` 且不能为 `.` 或 `..`，以避免路径注入。会话列表按 `updatedAt` 倒序排序，`updatedAt` 取目录与各关键文件 mtime 的最大值。详见 [会话管理](../guides/sessions.md)。
+
+## 内置工具缓存
+
+Kimi Code CLI 在首次需要 ripgrep 时会自动下载并缓存。下载过程中，压缩包写入系统临时目录，校验 SHA-256 后解压，二进制直接安装到数据根下的 `bin/rg`（Windows 上为 `bin/rg.exe`）并赋予 `0o755` 执行权限。后续在同一数据根下直接复用，无需再次下载。如果系统 `PATH` 中本来就有 `rg`，会优先使用系统版本；删除 `bin/` 会在下一次需要时触发重新下载。
+
+## 日志与更新状态
+
+顶层 `logs/kimi-code.log` 是全局诊断日志，主要记录启动、登录、导出等不属于单个会话的问题。单个会话自己的诊断日志在 `<sessionDir>/logs/kimi-code.log`。
+
+如需报告 bug，优先使用 `kimi export` 导出相关会话（详见 [kimi 命令](../reference/kimi-command.md)）；如果会话日志存在，它会默认包含在导出包里。全局诊断日志默认也会打包；因为它可能包含其它会话或其它项目的事件，不想分享时使用 `--no-include-global-log` 排除。
+
+`updates/latest.json` 记录通过 npm 检查到的版本更新状态，由 CLI 自动维护，通常无需手动编辑。
+
+## 输入历史
+
+终端中的命令输入历史按工作目录分别保存。每个工作目录对应一个文件，路径为 `user-history/<md5(workDir)>.jsonl`，其中文件名是工作目录字符串的 MD5 哈希值（UTF-8 编码）。文件格式为 JSONL，每行一条历史记录。
+
+输入历史用于在终端界面下浏览和搜索此前输入过的提示词。
+
+## 清理数据
+
+直接删除数据根目录（默认 `~/.kimi-code/`，或 `KIMI_CODE_HOME` 指定的路径）可以完全清理 Kimi Code CLI 的所有运行时数据，包括配置、会话、日志、输入历史和内置工具缓存。
+
+如只需清理部分数据：
+
+| 需求 | 操作 |
+| --- | --- |
+| 重置配置 | 删除 `~/.kimi-code/config.toml` |
+| 清理所有会话 | 删除 `~/.kimi-code/sessions/` 与 `~/.kimi-code/session_index.jsonl` |
+| 清理诊断日志 | 删除 `~/.kimi-code/logs/` 目录 |
+| 清理输入历史 | 删除 `~/.kimi-code/user-history/` 目录 |
+| 重置更新检查状态 | 删除 `~/.kimi-code/updates/latest.json` |
+| 强制重新下载 ripgrep | 删除 `~/.kimi-code/bin/` 目录 |
+| 清除托管 Kimi / Open Platform OAuth 登录态 | 运行 `/logout`（仅清理当前供应商的 OAuth），或删除对应 `~/.kimi-code/credentials/<name>.json` |
+| 清除 MCP server OAuth 登录态 | 删除 `~/.kimi-code/credentials/mcp/` 目录；`/logout` **不会**清理 MCP 的 OAuth 凭据 |
+| 移除用户级 MCP 声明 | 删除 `~/.kimi-code/mcp.json` |
+| 清空用户级 Skills | 删除 `~/.kimi-code/skills/` 目录 |
--- a/docs/zh/configuration/env-vars.md
+++ b/docs/zh/configuration/env-vars.md
@ -0,0 +1,125 @@
+# 环境变量
+
+Kimi Code CLI 通过环境变量来覆盖默认路径、切换 OAuth 端点以及调整运行时行为。大部分变量在 `kimi` 进程启动时读取，少数（如遥测开关、OAuth 锁、诊断日志）在相关子系统初始化时读取。Kimi 自有变量使用 `KIMI_*` 前缀；此外，CLI 也会读取若干系统标准变量。
+
+::: warning 注意
+**供应商凭证不在此列**：`KIMI_API_KEY`、`ANTHROPIC_API_KEY`、`OPENAI_API_KEY`、`GOOGLE_API_KEY` 等密钥变量**不会**从 `process.env` 自动读取。它们必须写在 `config.toml` 的 `[providers.<name>]` 段（`api_key` / `base_url`）或 `[providers.<name>.env]` 子表中；仅在 shell 中 `export` 不会让某个供应商自动获得凭证。详见 [配置覆盖](./overrides.md#供应商凭证) 与 [供应商](./providers.md)。
+:::
+
+## 核心路径
+
+`KIMI_CODE_HOME` 用于覆盖 Kimi Code CLI 的数据根目录，默认值是 `~/.kimi-code`。CLI 自身的应用数据、`kimi-core` 的配置、ripgrep 缓存以及 OAuth 凭证都会落在这个目录下。
+
+```sh
+export KIMI_CODE_HOME="/path/to/custom/kimi-code"
+```
+
+数据布局的详细说明请参阅 [数据路径](./data-locations.md)。
+
+::: warning 注意
+设置后请确保目录可写。多个 `kimi` 实例如果共享同一个 `KIMI_CODE_HOME`，会共享配置与凭证文件。
+:::
+
+## 供应商凭证键名
+
+下列键名出现在 `config.toml` 的 `[providers.<name>.env]` 子表中，用作供应商 `api_key` / `base_url` 的回退来源。**`kimi` 主进程不会从 `process.env` 直接读取它们**；只有 `[providers.<name>.env]` 子表内对应键的值才会被供应商客户端识别。详细解析顺序见 [配置覆盖：供应商凭证](./overrides.md#供应商凭证)。
+
+| 键名 | 适用供应商 | 用途 | 默认值 |
+| --- | --- | --- | --- |
+| `KIMI_API_KEY` | Kimi / Moonshot | API 密钥 | 无 |
+| `KIMI_BASE_URL` | Kimi / Moonshot | API 基础 URL | `https://api.moonshot.ai/v1` |
+| `ANTHROPIC_API_KEY` | Anthropic | API 密钥 | 无 |
+| `ANTHROPIC_BASE_URL` | Anthropic | API 基础 URL | 跟随 Anthropic SDK 默认值 |
+| `OPENAI_API_KEY` | OpenAI（`openai` 与 `openai_responses` 均使用） | API 密钥 | 无 |
+| `OPENAI_BASE_URL` | OpenAI（`openai` 与 `openai_responses` 均使用） | API 基础 URL | `https://api.openai.com/v1` |
+| `GOOGLE_API_KEY` | Google GenAI、Vertex AI（作为 `VERTEXAI_API_KEY` 的备用） | API 密钥 | 无 |
+| `VERTEXAI_API_KEY` | Vertex AI | API 密钥（未使用 ADC 时） | 无 |
+| `GOOGLE_CLOUD_PROJECT` | Vertex AI | GCP 项目 ID | 无 |
+| `GOOGLE_CLOUD_LOCATION` | Vertex AI | GCP 区域 | 无 |
+
+例如在 `config.toml` 中预置 Kimi 凭证：
+
+```toml
+[providers.kimi.env]
+KIMI_API_KEY = "sk-xxx"
+KIMI_BASE_URL = "https://api.moonshot.ai/v1"
+```
+
+::: warning 注意
+`GOOGLE_APPLICATION_CREDENTIALS`（服务账号 JSON 路径）由 Google SDK 自身从终端环境变量中读取，是这组键名中**唯一**走系统环境变量的；它走的是 Google Cloud 标准的 ADC 流程，CLI 不参与解析。其它键名都需要写在 `[providers.<name>.env]` 子表里才会生效。
+:::
+
+供应商类型与字段的完整说明请参阅 [供应商](./providers.md)。
+
+## OAuth 与托管服务
+
+OAuth 流程默认连接 Kimi 官方的认证与托管端点，下列变量可以将它们指向自建或测试环境。
+
+| 环境变量 | 用途 | 默认值 |
+| --- | --- | --- |
+| `KIMI_CODE_OAUTH_HOST` | OAuth 认证 host，优先级最高 | —（未设置时回退到 `KIMI_OAUTH_HOST`，再回退到下面的硬编码默认） |
+| `KIMI_OAUTH_HOST` | OAuth 认证 host，作为 `KIMI_CODE_OAUTH_HOST` 的 fallback | —（未设置时回退到下面的硬编码默认） |
+| `KIMI_CODE_BASE_URL` | 托管 Kimi API 的 base URL，用于 OAuth 登录后的 API 调用 | `https://api.kimi.com/coding/v1` |
+
+当 `KIMI_CODE_OAUTH_HOST` 和 `KIMI_OAUTH_HOST` 都未设置时，OAuth 认证 host 使用硬编码常量 `https://auth.kimi.com`。
+
+::: warning 注意
+`KIMI_CODE_BASE_URL` 与上一节的 `KIMI_BASE_URL` 是两个不同变量：前者面向 OAuth 登录的托管服务，默认指向 `kimi.com`；后者面向直接使用 Kimi API 密钥的供应商，默认指向 `moonshot.ai`。请按场景区分。
+:::
+
+## 运行时开关
+
+| 环境变量 | 用途 | 合法值 / 默认值 |
+| --- | --- | --- |
+| `KIMI_DISABLE_TELEMETRY` | 关闭遥测上报 | `1`、`true`、`t`、`yes`、`y`（不区分大小写） |
+| `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` | 覆盖 `[background].keep_alive_on_exit`，控制会话关闭时是否保留仍在运行的后台任务 | 真值：`1`、`true`、`yes`、`on`；假值：`0`、`false`、`no`、`off`；未设置时读取 `config.toml`，再回退到 `true` |
+| `KIMI_SHELL_PATH` | 覆盖 Windows 上 Git Bash (`bash.exe`) 的绝对路径，仅在 Windows 自动探测失败时需要 | 无 |
+| `KIMI_MODEL_MAX_COMPLETION_TOKENS` | 单步 LLM 请求 `max_completion_tokens` 的期望预算（实际值按上下文窗口与输入大小再做 clamp）；设为 `0` 或负数则完全禁用 clamp。**目前只对 `kimi` 类型的供应商生效**；Anthropic 等其它供应商请改用 `[models.<alias>].max_output_size`（详见 [配置文件](./config-files.md#models)） | 默认 32000，受 `loop_control.reserved_context_size` 影响 |
+
+例如在共享主机上禁用遥测：
+
+```sh
+export KIMI_DISABLE_TELEMETRY="1"
+```
+
+`KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` 的优先级高于 `config.toml`。例如临时运行 `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT=0 kimi -p "..."` 时，即使配置文件里写了 `keep_alive_on_exit = true`，本次进程退出前也会请求停止后台任务。
+
+## 诊断日志
+
+下列变量控制 `kimi` 的诊断日志。日志会写入两个位置：全局诊断日志在 `$KIMI_CODE_HOME/logs/kimi-code.log`，每个会话自身的诊断日志在 `<sessionDir>/logs/kimi-code.log`（路径细节见 [数据路径](./data-locations.md#日志与更新状态)）。所有变量都只在进程启动时读取一次。
+
+| 环境变量 | 用途 | 默认值 |
+| --- | --- | --- |
+| `KIMI_LOG_LEVEL` | 日志级别，可选 `off`、`error`、`warn`、`info`、`debug` | `info` |
+| `KIMI_LOG_GLOBAL_MAX_BYTES` | 全局日志文件单个最大字节数 | `6291456`（6 MB） |
+| `KIMI_LOG_GLOBAL_FILES` | 全局日志文件保留份数 | `5` |
+| `KIMI_LOG_SESSION_MAX_BYTES` | 会话级日志文件单个最大字节数 | `5242880`（5 MB） |
+| `KIMI_LOG_SESSION_FILES` | 会话级日志文件保留份数 | `3` |
+
+整数类变量解析失败（非正整数、非数字）时静默回落到默认值。
+
+## 剪贴板桥接
+
+`KIMI_WSL_CLIPBOARD_IMAGE_PATH` 由 CLI 在调用 WSL 剪贴板辅助子进程时自动注入，用于传递临时图片路径。该变量写入到 PowerShell 子进程的环境中，由子进程脚本内部读取；kimi 主进程自身不读取此变量。在外部 shell 中设置它对 kimi 主进程**无效**，用户无需手动管理此变量。
+
+## 系统环境变量
+
+Kimi Code CLI 也会读取一些标准的系统环境变量，用于检测运行环境与默认行为：
+
+- `HOME`：用户主目录，用于解析默认数据路径。
+- `VISUAL`、`EDITOR`：调用外部编辑器时的可执行命令，`VISUAL` 优先。
+- `PATH`：定位 `rg`、`git` 等外部依赖。
+- `NO_COLOR`：设置且非空时，强制关闭颜色与主题检测，界面回退到深色主题。遵循 [no-color.org](https://no-color.org) 约定。
+- `FORCE_COLOR`：值为 `"0"` 时，同样关闭颜色与主题检测，界面回退到深色主题。
+- `CI`：非空且非 `"0"` 时，关闭主题检测并回退到深色主题；遥测模块也会读取此变量以标记 CI 环境。
+- `LANG`：用于在遥测上下文中标记 locale（仅作为标记，不改变 CLI 行为）。
+- `TERM_PROGRAM`：用于检测终端对 OSC 9 通知的支持（iTerm2、WezTerm、ghostty、WarpTerminal 等）；也会写入遥测上下文。
+- `TERM`：用于检测终端对 OSC 9 通知的支持（xterm-kitty、xterm-ghostty 等）。
+- `TMUX`：检测是否运行在 tmux 内，用于终端通知路径的判断。
+- `COLORFGBG`：检测终端配色（深色 / 浅色）。
+- `DISPLAY`、`WAYLAND_DISPLAY`、`XDG_SESSION_TYPE`：检测 Linux 图形会话，用于剪贴板与图片相关功能。`XDG_SESSION_TYPE` 值为 `wayland` 时也判定为 Wayland 会话。
+- `WSL_DISTRO_NAME`、`WSLENV`：检测是否运行在 WSL 内，用于剪贴板的 PowerShell 桥接回退。
+- `TERMUX_VERSION`：检测是否运行在 Termux 中。
+- `LOCALAPPDATA`：Windows 上探测 Git Bash 安装路径时使用。
+
+这些变量遵循各操作系统的常规约定，`kimi` 仅读取不修改。
--- a/docs/zh/configuration/overrides.md
+++ b/docs/zh/configuration/overrides.md
@ -0,0 +1,110 @@
+# 配置覆盖
+
+Kimi Code CLI 的运行参数来自用户配置文件、命令行选项，以及若干在进程级环境变量上读取的运行时路径、端点与开关。三者面向不同场景 —— 配置文件保存长期偏好，命令行选项做本次启动的临时切换，环境变量主要负责定位数据目录、切换 OAuth 端点和少量运行时开关。
+
+环境变量在 Kimi Code CLI 中**不是配置字段的通用后备来源**：它们分成下面三类，作用范围互不相同，不能简单合并成一条线性优先级。
+
+## 环境变量的三类作用
+
+1. **配置文件定位**：`KIMI_CODE_HOME` 决定配置文件、会话、日志等所在的数据根目录，配置文件路径变为 `$KIMI_CODE_HOME/config.toml`，否则使用 `~/.kimi-code/`。这是先于其它解析的"在哪里找配置"步骤，不是普通参数的后备来源；也无法通过 `KIMI_CONFIG_PATH` 之类的变量任意切换配置文件路径。
+2. **运行时开关**：`KIMI_DISABLE_TELEMETRY` 等少量开关会直接关闭对应子系统。即便 `config.toml` 中 `telemetry = true`，只要这个变量被设置成真值，遥测仍会被关闭——它对相关子系统的语义是"额外禁用"，而不是"普通覆盖"。
+3. **运行端点与诊断**：`KIMI_CODE_OAUTH_HOST`、`KIMI_OAUTH_HOST`、`KIMI_CODE_BASE_URL`、`KIMI_LOG_LEVEL` 等供 OAuth 与诊断子系统初始化时读取。完整列表见 [环境变量](./env-vars.md)。
+
+## 普通运行参数的优先级
+
+对其它运行参数（模型别名、Plan / yolo 模式、Skills 目录等），按下面顺序解析：
+
+1. **命令行选项**：本次启动指定的参数，覆盖所有其他来源；仅对本次启动生效。
+2. **用户配置文件**：`$KIMI_CODE_HOME/config.toml`（缺省为 `~/.kimi-code/config.toml`），保存长期偏好。
+
+少数环境变量会明确覆盖配置文件中的相关字段，例如 `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` 的优先级高于 `[background].keep_alive_on_exit`。这类例外会在 [环境变量](./env-vars.md) 与对应的 [配置文件](./config-files.md) 字段说明里标出。
+
+::: warning 注意
+普通运行参数**不会**从 shell 环境变量取后备值。例如供应商 `api_key` / `base_url` 只读取 `config.toml` 中的字段（包括 `[providers.<name>.env]` 子表），不会回退到 `export KIMI_API_KEY` 这类终端变量；详见下文 [供应商凭证](#供应商凭证)。
+:::
+
+Kimi Code CLI 目前只读取一份用户级配置文件，没有项目级（仓库内）配置文件机制。如果需要在不同项目之间隔离配置，可以通过 `KIMI_CODE_HOME` 指向不同的数据目录（详见下文 [典型场景](#典型场景)），或在启动时用 CLI 选项临时覆盖具体字段。
+
+## 配置文件
+
+配置文件位置由 `KIMI_CODE_HOME` 环境变量控制，未设置时使用 `~/.kimi-code/`。文件名固定为 `config.toml`，目录会以 `0o700` 权限创建。文件内可声明 `default_provider`、`default_model`、`providers`、`models`、`thinking`、`loop_control` 等长期偏好。具体字段见 [配置文件](./config-files.md)。
+
+## 供应商凭证
+
+供应商凭证（`api_key`、`base_url`）的解析有自己的规则：Kimi Code CLI 只从 `config.toml` 中读取供应商字段，**不会**从 shell 环境变量取后备值。仅在终端里 `export KIMI_API_KEY` 不会让某个 `[providers.<name>]` 自动获得凭证，必须显式写到配置文件里。
+
+对单个供应商而言，凭证按以下顺序解析：
+
+1. `[providers.<name>].api_key` —— 配置文件中显式写入的密钥，优先级最高。
+2. `[providers.<name>.env]` 子表中的对应键（如 `KIMI_API_KEY`、`ANTHROPIC_API_KEY`、`OPENAI_API_KEY`、`GOOGLE_API_KEY`）—— 把习惯写在 shell 里的环境变量名搬到 TOML 子表里，仅在 `api_key` 留空时生效。这只是配置子表的形式，不会真正修改进程环境。
+3. 若两者都缺，启动时会报错并提示对应的供应商缺少凭证。
+
+`base_url` 的解析方式与 `api_key` 类似：先读 `[providers.<name>].base_url`，再读 `[providers.<name>.env]` 中的 `*_BASE_URL` 键（如 `ANTHROPIC_BASE_URL`、`OPENAI_BASE_URL`、`KIMI_BASE_URL`）。供应商类型与字段的完整说明见 [供应商](./providers.md)。
+
+## 进程级环境变量
+
+`process.env` 中的变量在 Kimi Code CLI 启动时被读取，作用分成上文 [环境变量的三类作用](#环境变量的三类作用) 中已说明的三类：
+
+- **数据根目录与日志路径**：`KIMI_CODE_HOME` 切换 `~/.kimi-code/`；`KIMI_LOG_LEVEL` 等控制诊断日志。
+- **运行时开关**：`KIMI_DISABLE_TELEMETRY` 关闭遥测（会覆盖 `config.toml` 中 `telemetry = true` 的设置）。
+- **OAuth 端点与诊断**：`KIMI_CODE_OAUTH_HOST`、`KIMI_OAUTH_HOST`、`KIMI_CODE_BASE_URL` 控制托管 Kimi 登录端点；`KIMI_LOG_LEVEL` 等控制诊断日志。
+- **后台任务退出策略**：`KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` 覆盖 `[background].keep_alive_on_exit`，用于临时决定本次进程退出时是否保留后台任务。
+
+完整变量与适用范围见 [环境变量](./env-vars.md)。
+
+## 命令行选项
+
+启动时通过 CLI 选项指定的参数优先级最高，仅对本次启动生效。常用选项：
+
+| 选项 | 作用 |
+| --- | --- |
+| `-S, --session [id]` | 恢复指定 session；不带 id 时进入交互式选择 |
+| `-C, --continue` | 续上当前工作目录的上一次 session |
+| `-y, --yolo` | 自动批准普通工具调用（别名 `--yes`、`--auto-approve`） |
+| `--plan` | 以 Plan 模式启动 |
+| `-m, --model <model>` | 指定本次启动使用的模型别名 |
+| `-p, --prompt <prompt>` | 以非交互模式执行单次提示词后退出 |
+| `--output-format <format>` | 指定 `-p` 模式的输出格式，可选 `text` 或 `stream-json` |
+| `--skills-dir <dir>` | 替换自动发现的 Skills 目录（可重复指定多个，仅对本次启动生效） |
+
+选项互斥规则：
+
+- `--output-format` 只能在 prompt 模式（`-p / --prompt`）下使用。
+- `--prompt` 不能与 `--yolo` 同用，也不能与 `--plan` 同用。
+- `--prompt` 模式下使用 `-S / --session` 必须给出 session id，不接受不带 id 的交互式选择。
+- `--continue` 与 `--session` 不能同用。
+- 在非 prompt 模式下，`--yolo` 不能与 `--continue` 或 `--session` 组合；`--plan` 不能与 `--continue` 或 `--session` 组合。
+- `--yolo` 与 `--plan` 可以同时使用。
+
+::: tip 提示
+`--skills-dir` 替换本次启动自动发现的 Skills 目录，适合一次性指定；若需长期追加搜索目录，可在 `config.toml` 顶层写 `extra_skill_dirs`（详见 [Agent Skills](../customization/skills.md)），两者语义不同，可按需选用。
+:::
+
+## 典型场景
+
+**切换数据目录用于隔离测试。** `KIMI_CODE_HOME` 会同时影响配置文件、session 存档、ripgrep 缓存等所有数据位置：
+
+```sh
+KIMI_CODE_HOME="$PWD/.kimi-sandbox" kimi
+```
+
+**在配置文件中预置临时凭证。** 由于供应商凭证只读取 `config.toml`，若要在一次启动里使用另一个 API key，可以预先把它写入 `[providers.<name>.env]` 子表：
+
+```toml
+[providers.kimi.env]
+KIMI_API_KEY = "sk-test"
+```
+
+也可以直接为该供应商写 `api_key`；两者优先级见上文 [供应商凭证](#供应商凭证)。
+
+**本次启动跳过审批。** 适用于已知安全的批处理任务：
+
+```sh
+kimi --yolo
+```
+
+**本次启动进入 Plan 模式。** 若希望默认行为也如此，可在配置文件中设置 `default_plan_mode = true`：
+
+```sh
+kimi --plan
+```
--- a/docs/zh/configuration/providers.md
+++ b/docs/zh/configuration/providers.md
@ -0,0 +1,135 @@
+# 平台与模型
+
+Kimi Code CLI 通过统一的供应商抽象对接多家 LLM 平台。每个供应商负责一种 API 协议，模型则在供应商之上声明自己的名称、上下文长度和能力。本页介绍当前支持的所有供应商类型，以及如何在 `~/.kimi-code/config.toml` 中配置它们。
+
+## 概述
+
+`providers` 表里的 `type` 字段决定使用哪一种实现。目前支持的类型有：
+
+| 类型 | 协议 | 典型平台 |
+| --- | --- | --- |
+| `kimi` | OpenAI 兼容（chat completions 风格） | Kimi Code、Moonshot AI 开放平台 |
+| `anthropic` | Anthropic Messages | Claude API |
+| `openai` | OpenAI Chat Completions | OpenAI 及其兼容服务 |
+| `openai_responses` | OpenAI Responses API | OpenAI 较新的 Responses 接口 |
+| `google-genai` | Google GenAI | Gemini API |
+| `vertexai` | Google GenAI on Vertex | Google Cloud Vertex AI |
+
+所有供应商默认以流式方式与模型交互；thinking、视觉、工具调用等能力按模型名前缀自动匹配，无需在配置里手写。
+
+API 密钥可以写在 `api_key` 字段，也可以放在 `[providers.<name>.env]` 子表里。优先级为 `api_key` > 子表键 > 若均未配置，启动时将报错。**Kimi Code CLI 不会从 shell 环境变量自动取后备值**——仅在终端里 `export KIMI_API_KEY` 不会让某个供应商自动获得凭证，需要显式写入 `config.toml`（详见 [配置覆盖：供应商凭证](./overrides.md#供应商凭证)）。`api_key` 与 `oauth` 在同一个供应商上互斥，同时设置会在解析模型时报错；OAuth 由内置登录流程自动注入，无需手写。
+
+`[providers.<name>.env]` 子表可以在 `config.toml` 内直接提供凭证或端点覆盖，这些值仅对当前供应商生效，不会泄漏到全局 shell 环境：
+
+```toml
+[providers.my-anthropic.env]
+ANTHROPIC_API_KEY = "sk-ant-xxxxx"
+ANTHROPIC_BASE_URL = "https://my-proxy.example.com"
+```
+
+切换供应商最常见的方式有两种：在 TUI 里用 `/model` 斜杠命令选择已配置的模型，或者直接编辑 `config.toml` 调整 `[providers.*]` 与 `[models.*]` 表。完整字段说明见 [配置文件](./config-files.md)。
+
+## `kimi`
+
+`kimi` 通过 OpenAI 兼容协议对接 Moonshot AI。
+
+- 默认 `base_url`：`https://api.moonshot.ai/v1`
+- 环境变量：`KIMI_API_KEY`、`KIMI_BASE_URL`
+- 额外能力：支持视频上传
+
+```toml
+[providers.kimi]
+type = "kimi"
+base_url = "https://api.moonshot.ai/v1"
+api_key = "sk-xxxxx"
+```
+
+Kimi Code 托管服务在 OAuth 登录后会自动配置 `base_url` 与凭证，无需手动填写；详见 [OAuth 与凭证注入](#oauth-与凭证注入) 与 [环境变量](./env-vars.md)。
+
+## `anthropic`
+
+`anthropic` 用于对接 Claude API。标准 Claude 模型会自动启用视觉、工具调用及 Thinking（如支持）。若使用自定义或尚未覆盖的模型，需在 `[models.<alias>]` 中显式声明 `capabilities`。
+
+Thinking 可通过 `/model`、`/settings` 或配置控制。
+
+- 默认 `base_url`：跟随 Anthropic SDK 默认值
+- 环境变量：`ANTHROPIC_API_KEY`、`ANTHROPIC_BASE_URL`
+- 默认 `max_tokens`：按模型自动设置。如需覆盖（例如测试或为尚未识别的别名指定值），在模型别名上设置 `max_output_size`（详见 [`config-files.md`](./config-files.md#models)）。已识别别名的覆盖值会被限制在服务端允许的上限内。
+
+```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
+# 可选：在测试时降低输出预算，或为本 CLI 尚未识别的模型指定一个值。
+# 省略则使用上述按模型推导出的默认值。
+# max_output_size = 32000
+```
+
+## `openai`
+
+`openai` 对应 OpenAI Chat Completions 协议，也可用来连接任何兼容该协议的第三方服务（自行覆盖 `base_url` 即可）。thinking、视觉、工具调用等能力按模型名自动推断。
+
+- 默认 `base_url`：`https://api.openai.com/v1`
+- 环境变量：`OPENAI_API_KEY`、`OPENAI_BASE_URL`
+
+```toml
+[providers.openai]
+type = "openai"
+base_url = "https://api.openai.com/v1"
+api_key = "sk-xxxxx"
+```
+
+## `openai_responses`
+
+`openai_responses` 对应 OpenAI 较新的 Responses API。它始终以流式方式工作，能力按模型名自动推断。
+
+- 默认 `base_url`：`https://api.openai.com/v1`
+- 环境变量：`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`
+
+`google-genai` 用于直连 Google Gemini API。thinking、视觉及多模态能力按模型名自动推断。
+
+- 环境变量：`GOOGLE_API_KEY`
+
+```toml
+[providers.gemini]
+type = "google-genai"
+api_key = "xxxxx"
+```
+
+## `vertexai`
+
+`vertexai` 与 `google-genai` 共用同一份实现，`type = "vertexai"` 时切换到 Vertex AI 的访问路径。
+
+认证遵循 Google Cloud 的标准流程：通过 `gcloud auth application-default login` 或设置 `GOOGLE_APPLICATION_CREDENTIALS` 指向服务账号 JSON 完成鉴权（这一步是 Google SDK 的通用机制，与 Kimi Code 配置无关）。**项目与区域必须写在 `[providers.vertexai.env]` 子表中**——直接 `export GOOGLE_CLOUD_PROJECT`、`export GOOGLE_CLOUD_LOCATION` 不会被 CLI 读取。`GOOGLE_CLOUD_LOCATION` 缺失时，CLI 会尝试从 `base_url` 自动推断。API 密钥（`VERTEXAI_API_KEY` 或 `GOOGLE_API_KEY`）同样写在子表内。
+
+```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   # 一次性
+kimi
+```
+
+## OAuth 与凭证注入
+
+部分平台（如 Kimi Code 托管服务）使用 OAuth 而非静态 API 密钥。凭证由内置的 kimi-oauth 工具链在运行时注入，登录流程会自动负责写入与刷新，普通配置文件无需手工配置这部分内容。
--- a/docs/zh/customization/agents.md
+++ b/docs/zh/customization/agents.md
@ -0,0 +1,45 @@
+# Agent 与子 Agent
+
+Kimi Code CLI 中的 Agent 是驱动会话的核心。一次会话始终由一个主 Agent 主持，主 Agent 在执行任务过程中可以根据需要派发子 Agent 来处理更聚焦的子任务。
+
+主 Agent 负责理解用户的整体意图、规划步骤、与用户对话、调用工具，并最终汇总结果。它的上下文贯穿整个会话，是用户在终端中直接交互的对象。
+
+子 Agent 则是主 Agent 临时派生出来的"助手"。它接受一份明确的任务描述，在自己的上下文里独立完成工作，再把结论返回给主 Agent。子 Agent 不会与用户直接对话，也不会混入主 Agent 的上下文历史。这种分工特别适合"探索代码库"、"审阅大段实现"、"规划复杂改动"这类边界清晰、需要大量阅读但产物较短的工作。
+
+## 内置子 Agent
+
+Kimi Code CLI 内置了三种子 Agent，分别面向不同的任务形态，开箱即用：
+
+- **`coder`**：默认子 Agent，通用的软件工程助手，可以读写文件、执行命令、搜索代码并落地具体改动。
+- **`explore`**：代码库探索专用，只做只读操作，不会修改任何文件。适合在不修改文件的前提下快速搜索、阅读和总结仓库。
+- **`plan`**：实现规划与架构设计专用，工具集进一步收窄，连 Shell 命令都不提供，专注于"想清楚怎么做"而不是"动手做"。
+
+## 调用方式
+
+子 Agent 由主 Agent 自动调度。主 Agent 会根据任务复杂度、上下文消耗以及子任务的独立性，在需要时自动派发，无需用户手动指定。
+
+每次派发都会在终端中以审批请求的形式呈现（除非命中已有的 allow 规则或处于 YOLO 模式），方便你审视任务描述。你可以在与主 Agent 的对话中直接指定子 Agent 类型，例如"先用 explore 把相关文件梳理一遍再动手"。
+
+子 Agent 也可以放在后台运行，完成后结果会自动回到主 Agent，无需手动轮询。也可以唤回已有的子 Agent 实例继续推进同一任务。
+
+## 上下文隔离与资源开销
+
+每个子 Agent 都拥有完全独立的上下文窗口。它看不到主 Agent 的对话历史，只能看到主 Agent 显式传入的任务描述。子 Agent 自己的中间思考和工具调用记录不会回流到主 Agent，只有最终结果会出现在主 Agent 的上下文里。
+
+这种隔离带来两个好处：一是主 Agent 的上下文保持精炼，长会话中不会被大量探索性日志撑满；二是多个子 Agent 可以并行运行，互不干扰。
+
+需要注意的是，每个子 Agent 都会独立消耗模型 token，因此简单任务上没有必要派发子 Agent，主 Agent 直接处理反而更经济。子 Agent 也不支持继续嵌套调度。
+
+## 权限继承
+
+子 Agent 的权限规则继承自主 Agent：主 Agent 通过 `/permission` 或在审批中接受的"始终允许"规则，会自动覆盖到它派发出的所有子 Agent，子 Agent 不需要重新审批同一类工具调用。`Agent` 工具本身默认放行，因此主 Agent 可以在不打断用户的前提下完成多次委派。
+
+如果你希望某一类工具在子 Agent 中始终不可用，应该收紧主 Agent 的权限规则。
+
+## 会话目录中的存储位置
+
+子 Agent 的运行状态会持久化到当前会话目录的 `agents/` 子目录下，每个子 Agent 实例对应一个独立的子目录，其中包含按时间顺序记录提示词、消息历史与最终状态的 `wire.jsonl` 文件。后台子 Agent 还会通过 `tasks/` 子目录暴露生命周期状态。
+
+::: warning 注意
+会话目录、wire 文件和任务记录都属于本地调试材料，可能包含用户 prompt、命令输出、仓库路径、工具返回内容或凭证痕迹。不要把这些文件直接提交到公开仓库、issue 或聊天记录里；确实需要分享时，请先脱敏。
+:::
--- a/docs/zh/customization/hooks.md
+++ b/docs/zh/customization/hooks.md
@ -0,0 +1,150 @@
+# Hooks
+
+Hooks 让你在 Kimi Code CLI 的关键生命周期点运行本地命令。它适合做轻量的策略检查、审计记录、桌面通知或与本地自动化脚本联动，例如在危险工具调用前拦截，或在后台子 Agent 完成后触发通知。
+
+Hook 命令在本地 Shell 中运行，Kimi Code CLI 会把事件 payload 以 JSON 写入命令的 stdin。命令的 stdout、stderr 和退出码决定 hook 的结果；除明确阻断的情况外，hook 失败时默认放行（fail-open），不会让主流程因为脚本异常而中断。
+
+::: warning 注意
+Hooks 适合做本地提醒和轻量拦截，不应作为唯一安全边界。脚本报错、超时或返回普通非零退出码时会默认放行（fail-open）；高风险工具调用仍应依赖权限审批和人工确认。
+:::
+
+## 配置
+
+在 `~/.kimi-code/config.toml` 中使用 `[[hooks]]` 数组表声明 hook：
+
+```toml
+[[hooks]]
+event = "PreToolUse"
+matcher = "Bash"
+command = "node ~/.kimi-code/hooks/check-bash.mjs"
+timeout = 5
+
+[[hooks]]
+event = "Notification"
+matcher = "task\\.completed"
+command = "terminal-notifier -title Kimi -message 'Background task finished'"
+```
+
+字段含义如下：
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `event` | `string` | 是 | 事件名，取值必须是下文「事件」表中的某一项；其他值会让整份配置加载失败 |
+| `matcher` | `string` | 否 | 用于匹配事件目标的正则表达式；缺省或空字符串表示匹配全部 |
+| `command` | `string` | 是 | 要运行的 Shell 命令，长度不能为零 |
+| `timeout` | `integer` | 否 | 超时时间，单位秒，范围 1–600；未设置时默认为 30 秒 |
+
+每个 `[[hooks]]` 表只允许出现这四个字段，写错或多写字段会导致配置文件解析失败。
+
+同一次事件触发时，命中的多个 hook 会并行运行；如果多个配置项的 `command` 完全相同，只会运行一次。`matcher` 使用 JavaScript 正则表达式语义；非法正则会被静默跳过，等同于不匹配。
+
+Hook 命令通过 Shell 启动（等价于 `sh -c <command>`），子进程的工作目录就是当前会话的 `cwd`。在非 Windows 平台上，子进程会被放入独立的进程组，超时或会话被中断时会先发送 `SIGTERM`、100 毫秒后再发送 `SIGKILL`，确保 hook 内部 fork 出的子进程也能被一并清理。
+
+传给 hook 的 JSON 字段统一使用 snake_case。每个 payload 都包含：
+
+```json
+{
+  "hook_event_name": "PreToolUse",
+  "session_id": "session_abc",
+  "cwd": "/path/to/project"
+}
+```
+
+其余字段由事件类型决定，见下文事件表。
+
+## 返回值
+
+Hook 命令的退出码和 stdout 会被解释为以下结果：
+
+| 结果 | 行为 |
+| --- | --- |
+| 退出码 `0` | 放行；如果 stdout 是 JSON，可从 `message` 或 `hookSpecificOutput.message` 读取文本 |
+| 退出码 `2` | 阻断；stderr 会作为阻断原因 |
+| 其他非零退出码 | 默认放行（fail-open） |
+| 超时或进程异常 | 默认放行（fail-open） |
+
+当 stdout 是 JSON，并且 `hookSpecificOutput.permissionDecision` 为 `deny` 时，也会被视为阻断：
+
+```json
+{
+  "hookSpecificOutput": {
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Use rg instead"
+  }
+}
+```
+
+阻断只对支持控制流的事件生效。例如 `PreToolUse` 可以阻断工具调用，`Stop` 可以让当前轮次追加一次继续消息。观察型事件（例如 `PostToolUse`、`PostToolUseFailure`、`PostCompact`、`SubagentStop`、`StopFailure`、`Notification`）以「即发即忘（fire-and-forget）」方式异步触发，返回值被忽略，不会改变主流程。`PreCompact` 使用 `trigger`（而非 `triggerBlock`）调用，返回值同样被完全忽略，不属于可阻断事件。
+
+阻断生效时，如果脚本未通过 stderr 或 JSON 输出提供原因，CLI 会回退到 `Blocked by <event> hook` 作为占位原因。`PreToolUse` 阻断会作为工具失败结果写回上下文，模型可以根据原因选择替代方案。
+
+## 事件
+
+当前会自动触发的事件如下：
+
+| 事件 | Matcher | 主要 payload | 行为 |
+| --- | --- | --- | --- |
+| `UserPromptSubmit` | 用户提交的文本内容 | `prompt`（`ContentPart[]` 数组） | 仅对真实 User 消息触发。hook 返回的文本会包裹为 hook 结果，写入会话历史用于 transcript/replay，并展示给用户；当前 LLM 轮次会继续，但不会把 hook 结果发给模型；若 hook 阻断，阻断原因会作为 Assistant 消息返回给用户，且不再调用模型；若所有 hook 均无输出，正常 LLM 轮次继续 |
+| `PreToolUse` | 工具名 | `tool_name`、`tool_input`、`tool_call_id` | 在权限检查前触发；阻断后工具不会执行 |
+| `PostToolUse` | 工具名 | `tool_name`、`tool_input`、`tool_call_id`、`tool_output` | 工具成功后触发；`tool_output` 被截断至前 2000 个字符 |
+| `PostToolUseFailure` | 工具名 | `tool_name`、`tool_input`、`tool_call_id`、`error` | 工具失败或被 hook 阻断后触发 |
+| `Stop` | 空字符串 | `stop_hook_active` | 模型准备停止时触发；阻断后会把原因直接作为系统触发的 User 消息追加进上下文，并最多继续一次 |
+| `StopFailure` | 错误类型 | `error_type`、`error_message` | 当前轮次因非取消错误失败后触发 |
+| `SessionStart` | `startup` 或 `resume` | `source` | 新会话主 Agent 创建后，或历史会话恢复完成后触发 |
+| `SessionEnd` | `exit` | `reason` | 会话关闭并 flush 元数据后触发 |
+| `SubagentStart` | 子 Agent 名称 | `agent_name`、`prompt` | 子 Agent 配置完成、真正开始运行前触发；`prompt` 被截断至前 500 个字符 |
+| `SubagentStop` | 子 Agent 名称 | `agent_name`、`response` | 子 Agent 成功完成后异步触发，失败时不触发；`response` 被截断至前 500 个字符 |
+| `PreCompact` | `manual` 或 `auto` | `trigger`、`token_count` | 上下文压缩真正开始前触发；此事件使用 `trigger`（非 `triggerBlock`）调用，返回值被完全忽略，阻断决策不会被读取 |
+| `PostCompact` | `manual` 或 `auto` | `trigger`、`estimated_token_count` | 上下文压缩成功写入后异步触发；阻断结果不会改变主流程 |
+| `Notification` | 通知类型 | `sink`、`notification_type`、`title`、`body`、`severity`、`source_kind`、`source_id` | 当前在后台子 Agent 结果写入上下文时触发；`notification_type` 取值为 `task.completed`、`task.failed`、`task.killed` 或 `task.lost`，sink 为 `context` |
+
+`UserPromptSubmit` 的返回文本会被包裹成一条 hook 结果：
+
+```xml
+<hook_result hook_event="UserPromptSubmit">
+hook response
+</hook_result>
+```
+
+如果多个 `UserPromptSubmit` hook 返回文本，每个结果都会拥有独立的 `<hook_result>` 标签。这条消息会带有 hook 结果来源，用于 transcript/replay，但不会发给模型。模型只看到原始用户输入，当前轮次继续。
+
+如果 `UserPromptSubmit` hook 阻断请求，阻断原因会使用同样格式返回给用户，但本轮不会继续请求模型。
+
+`Stop` 的阻断原因会直接作为系统触发的 User 消息写入上下文，让当前轮次继续：
+
+```text
+continue from hook
+```
+
+## 示例：阻断危险 Shell 命令
+
+下面的 hook 会在 `Bash` 工具调用前读取 stdin 中的 `tool_input.command`。如果命令包含 `rm -rf`，脚本以退出码 `2` 结束并把原因写到 stderr：
+
+::: warning 注意
+这个示例只演示 hook 如何阻断工具调用，不是完整的 Shell 安全解析器。真实策略更适合使用 allowlist，或用专门的 Shell 解析逻辑处理引号、变量展开、别名和多段命令。
+:::
+
+```toml
+[[hooks]]
+event = "PreToolUse"
+matcher = "Bash"
+command = "node ~/.kimi-code/hooks/block-dangerous-bash.mjs"
+timeout = 5
+```
+
+```js
+let input = '';
+process.stdin.on('data', (chunk) => {
+  input += chunk;
+});
+process.stdin.on('end', () => {
+  const payload = JSON.parse(input);
+  const command = payload.tool_input?.command ?? '';
+  if (command.includes('rm -rf')) {
+    console.error('Blocked dangerous shell command');
+    process.exit(2);
+  }
+});
+```
+
+当 hook 阻断工具调用时，Kimi Code CLI 会把阻断原因作为工具失败结果写回上下文，模型可以据此选择更安全的替代方案。
--- a/docs/zh/customization/mcp.md
+++ b/docs/zh/customization/mcp.md
@ -0,0 +1,83 @@
+# Model Context Protocol
+
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 是一个开放协议，让模型可以安全地调用外部进程或服务暴露的工具。Kimi Code CLI 作为 MCP client 接入这些外部工具，并把它们与内置工具（`Read`、`Bash`、`Grep` 等）一起暴露给 Agent 使用。
+
+## 集成范围
+
+Kimi Code CLI 支持通过 stdio（本地子进程）和 HTTP 两种方式接入外部 MCP 服务器。接入的 MCP 工具与内置工具一样，可以被 Agent 调用、受权限规则约束、参与审批流程，行为上没有差异。
+
+## 配置与登录
+
+MCP server 配置写在 `mcp.json` 中，分为两层：
+
+- 用户级：`~/.kimi-code/mcp.json`（或 `$KIMI_CODE_HOME/mcp.json`），跨项目共享
+- 项目级：`.kimi-code/mcp.json`，仅当前仓库
+
+项目级覆盖用户级同名条目。
+
+最方便的入口是在 TUI 中运行 `/mcp-config`，它会引导你新增、编辑或删除 server。要查看当前连接状态，可运行 `/mcp`。
+
+`mcp.json` 的顶层结构如下：
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+    },
+    "linear": {
+      "url": "https://mcp.linear.app/mcp"
+    }
+  }
+}
+```
+
+含 `command` 字段的条目为 stdio server，含 `url` 字段的条目为 HTTP server，通常不需要手写 `transport` 字段。HTTP server 支持通过 `headers` 或 `bearerTokenEnvVar` 提供静态凭证；需要 OAuth 时，可运行 `/mcp-config login <server-name>` 完成浏览器授权。
+
+可选字段：
+
+| 字段 | 类型 | 适用 transport | 说明 |
+| --- | --- | --- | --- |
+| `env` | `Record<string, string>` | stdio | 注入子进程的环境变量 |
+| `cwd` | `string` | stdio | 子进程工作目录 |
+| `headers` | `Record<string, string>` | HTTP | 附加到每次请求的静态请求头 |
+| `enabled` | `boolean` | 两者 | 设为 `false` 可禁用该 server |
+| `startupTimeoutMs` | `number` | 两者 | 连接超时，默认 `30000` |
+| `toolTimeoutMs` | `number` | 两者 | 单次工具调用超时 |
+| `enabledTools` | `string[]` | 两者 | 白名单 |
+| `disabledTools` | `string[]` | 两者 | 黑名单 |
+
+::: warning 注意
+项目级 `.kimi-code/mcp.json` 中的 stdio 条目会在会话启动时执行本地命令，只在你信任的仓库里启用。
+:::
+
+## 工具命名与权限
+
+MCP 工具按 `mcp__<server>__<tool>` 命名。权限匹配支持 `*` 和 `**` 通配，例如 `mcp__github__*` 命中该 server 下所有工具。
+
+未命中权限规则的调用会触发审批请求；在审批弹窗中选择 "Approve for this session" 后，后续同类调用将自动放行。
+
+也可以在 `config.toml` 的 `[[permission.rules]]` 中预置永久规则：
+
+```toml
+[[permission.rules]]
+decision = "allow"
+pattern = "mcp__github__*"
+
+[[permission.rules]]
+decision = "deny"
+pattern = "mcp__filesystem__write_file"
+```
+
+`pattern` 的完整语法及 `decision`、`scope` 等字段的取值详见 [配置文件](../configuration/config-files.md#permission)。
+
+## 安全性
+
+- 只接入可信来源的 MCP server
+- 在审批请求中检查工具名与参数是否合理
+- 对高风险工具维持手动审批，避免宽泛的 `mcp__*` 通配放行
+
+::: warning 注意
+在 YOLO 模式下，MCP 工具调用会被自动批准。仅在完全信任所接入的 MCP server 时使用此模式。
+:::
--- a/docs/zh/customization/skills.md
+++ b/docs/zh/customization/skills.md
@ -0,0 +1,127 @@
+# Agent Skills
+
+Agent Skills 是 Kimi Code CLI 用来扩展模型能力的轻量机制。一个 Skill 就是一份带 YAML frontmatter 的 Markdown 文档，描述某项专业知识或工作流程。Kimi Code CLI 在启动时自动扫描已知目录，把发现的 Skill 注入到系统提示词中，让 Agent 知道当前会话里有哪些可用的 Skill。
+
+相比把同样的指引每次都粘到提示词里，Skill 的好处在于：内容沉淀在文件里、可以跨项目和团队复用、可以通过斜杠命令一键加载，也可以让模型在需要时自动调用。常见用法是把代码风格、提交规范、审查流程等固化为 Skill。
+
+## 创建 Skill
+
+Skill 文件需要放在 [已知的扫描目录](#skill-存放位置) 中。一个 Skill 可以使用两种文件结构：
+
+- **目录形式（推荐）**：在 Skills 目录下创建一个子目录，主文件命名为 `SKILL.md`，必要时可在同目录下放置脚本、参考资料等辅助文件。如果同一目录下同时存在 `<name>/SKILL.md` 和同名的 `<name>.md`，以子目录为准。
+- **扁平形式**：直接使用单个 `.md` 文件，Skill 名称取文件名（去掉 `.md`）。
+
+### 文件格式
+
+`SKILL.md` 由 YAML frontmatter 和 Markdown 正文两部分组成。
+
+```markdown
+---
+name: code-style
+description: 项目代码风格规范，定义命名、缩进、注释和文件组织
+type: prompt
+whenToUse: 当用户让我编写、修改或审查项目源代码时
+disableModelInvocation: false
+arguments:
+  - target
+  - mode
+---
+
+请按下述规范处理代码：
+
+- 缩进使用 2 空格
+- 变量名使用 `camelCase`，类型名使用 `PascalCase`
+- 公开函数必须带 TSDoc 注释
+- 单行不超过 100 字符
+```
+
+### Frontmatter 字段
+
+| 字段 | 说明 |
+| --- | --- |
+| `name` | Skill 名称。目录型 `SKILL.md` 中为必填；扁平 `.md` 文件省略时使用文件名。名称大小写不敏感。 |
+| `description` | 一行总结。模型用它来判断何时使用这个 Skill。目录型 `SKILL.md` 中为必填；扁平 `.md` 文件省略时回退到正文第一行非空内容（截到 240 字符）。 |
+| `type` | Skill 类型。可选 `prompt`（默认）、`inline`（与 `prompt` 语义相同）、`flow`（仅支持手动调用，不支持模型自动调用）。其它值会被跳过。 |
+| `whenToUse` | 触发场景描述。也接受 `when-to-use`、`when_to_use` 写法。 |
+| `disableModelInvocation` | 设为 `true` 禁止模型自动调用此 Skill。也接受 `disable-model-invocation`、`disable_model_invocation` 写法。 |
+| `arguments` | 命名参数列表，可写成字符串数组或空白分隔的字符串（如 `arguments: target mode`）。声明后，正文可用 `$<name>` 读取参数；纯数字或空字符串会被忽略。 |
+
+::: warning 注意
+目录型 `SKILL.md` 中 `name` 和 `description` **必须**显式填写，省略任意一项均会导致解析失败。
+:::
+
+### 正文占位符
+
+正文在发送给模型前会展开少量占位符：
+
+- `$ARGUMENTS`：调用时附带的完整原始参数字符串
+- `$ARGUMENTS[0]`、`$ARGUMENTS[1]` 及简写 `$0`、`$1`：按空白分词后的位置参数（从 0 开始）
+- `$<name>`：`arguments` 中声明的命名参数
+- `${KIMI_SKILL_DIR}`：当前 Skill 文件所在目录
+
+位置参数支持单双引号包裹，如 `/skill:commit "fix login" patch` 中 `$0` 展开为 `fix login`。若正文不含任何参数占位符，调用时附带的文本会以 `\n\nARGUMENTS: <文本>` 的形式追加到正文末尾。
+
+## Skill 存放位置
+
+Kimi Code CLI 按作用域分四档扫描，越具体的作用域优先级越高：
+
+**Project > User > Extra > Built-in**
+
+用户级：
+
+- `~/.kimi-code/skills/`
+- `~/.agents/skills/`
+
+项目级（项目根 = 工作目录向上最近的包含 `.git` 的目录）：
+
+- `.kimi-code/skills/`
+- `.agents/skills/`
+
+额外目录通过 `config.toml` 顶层的 `extra_skill_dirs` 字段声明：
+
+```toml
+extra_skill_dirs = ["~/team-skills", ".agents/team-skills"]
+```
+
+内置 Skills 随 CLI 一起分发，优先级最低。
+
+## 调用 Skill
+
+用户可以通过斜杠命令主动调用：
+
+```
+/skill:code-style
+/skill:git-commits 修复登录接口的并发问题
+```
+
+模型也可以根据 `description` 和 `whenToUse` 自动调用 Skill（除非 `disableModelInvocation` 设为 `true` 或 `type` 为 `flow`）。模型调用时，正文先展开占位符，再注入到系统提示中。Skill 调用时最多允许嵌套 3 层，超过后会被终止。
+
+## 完整示例
+
+```markdown
+---
+name: review-pr
+description: 按团队标准审查一个 Pull Request，输出结构化的 review 报告
+type: prompt
+whenToUse: 当用户让我审查 PR、检查代码变更或评估提交质量时
+arguments:
+  - pr_ref
+---
+
+请按照以下流程审查用户指定的 PR：$pr_ref
+
+1. 拉取并阅读 `$pr_ref` 的全部 diff。
+2. 对照以下检查项逐条核对：
+   - 是否包含对应的测试用例
+   - 公开 API 是否有文档更新
+   - 是否引入了新的依赖；若有，说明引入理由
+   - 错误处理是否覆盖了边界情况
+3. 参考同目录下的检查清单：`references/checklist.md`
+4. 输出一份 review 报告，包含：
+   - 总体结论（approve / request changes / comment）
+   - 必须修改项（blocking）
+   - 建议改进项（non-blocking）
+   - 值得肯定的地方
+```
+
+保存为 `~/.kimi-code/skills/review-pr/SKILL.md`，检查清单放在同目录的 `references/checklist.md`，然后重开会话，即可通过 `/skill:review-pr #1234` 调用，其中 `#1234` 会展开到 `$pr_ref`。
--- a/docs/zh/faq.md
+++ b/docs/zh/faq.md
@ -0,0 +1,3 @@
+# 常见问题
+
+本页汇总新用户最常遇到的问题与简短回答。如果某一项需要更完整的解释，会在答案末尾给出相应文档的链接。
--- a/docs/zh/guides/getting-started.md
+++ b/docs/zh/guides/getting-started.md
@ -0,0 +1,135 @@
+# 开始使用
+
+## Kimi Code CLI 是什么
+
+Kimi Code CLI 是一个运行在终端中的 AI Agent，帮助你完成软件开发任务和日常的终端操作。它能阅读和编辑代码、执行 Shell 命令、搜索文件与抓取网页，并在执行过程中根据反馈自主规划和调整下一步行动。
+
+它适用于以下场景：
+
+- **编写和修改代码**：实现新功能、修复 bug、完成重构
+- **理解项目**：探索陌生的代码库，解答架构和实现层面的问题
+- **自动化任务**：批量处理文件、运行构建与测试、串联多个脚本
+
+整套 CLI 以 TypeScript 编写，通过 npm 分发，运行在 Node.js 之上。
+
+## 安装
+
+### 脚本安装（推荐）
+
+最快的安装方式是使用官方安装脚本，无需预装 Node.js：
+
+- **macOS / Linux**：
+
+```sh
+curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash
+```
+
+- **Windows（PowerShell）**：
+
+```powershell
+irm https://code.kimi.com/kimi-code/install.ps1 | iex
+```
+
+脚本会自动下载最新版本、校验 checksum，并把 `kimi` 可执行文件放到你的 `PATH` 中。
+
+### npm 安装
+
+如果你更习惯通过 npm 安装，需要 Node.js 24.15.0 或更高版本：
+
+```sh
+node --version
+```
+
+包名是 `@moonshot-ai/kimi-code`：
+
+```sh
+npm install -g @moonshot-ai/kimi-code
+```
+
+或用 pnpm：
+
+```sh
+pnpm add -g @moonshot-ai/kimi-code
+```
+
+## 升级与卸载
+
+安装完成后，验证可执行文件是否就绪：
+
+```sh
+kimi --version
+```
+
+**升级**：脚本安装的用户重新运行脚本即可；npm 安装的用户执行：
+
+```sh
+npm install -g @moonshot-ai/kimi-code@latest
+```
+
+**卸载**：脚本安装的用户删除 `kimi` 可执行文件即可；npm 安装的用户执行：
+
+```sh
+npm uninstall -g @moonshot-ai/kimi-code
+```
+
+## 第一次启动
+
+进入你想要工作的项目目录，直接运行 `kimi` 启动交互界面：
+
+```sh
+cd your-project
+kimi
+```
+
+如果只想执行一条指令而不进入交互界面，可以使用 `-p` 选项：
+
+```sh
+kimi -p "帮我看一下这个项目的目录结构"
+```
+
+如需继续上一次会话，添加 `-C` 选项即可：
+
+```sh
+kimi -C
+```
+
+首次启动时，Kimi Code CLI 尚未配置任何凭证，需要配置 API 来源才能开始对话。在交互界面中输入斜杠命令 `/login` 进入登录流程：
+
+```
+/login
+```
+
+`/login` 会弹出平台选择器，支持：
+
+- **Kimi Code** — OAuth 验证码流程，在任意设备打开链接、登录并输入验证码即可授权
+- **Moonshot AI Open Platform** — 直接输入 API key 登录
+
+需要退出登录时，输入 `/logout` 即可清除当前凭证。
+
+::: tip 提示
+如果你想使用 Anthropic、OpenAI、Google 等其他供应商，需要直接编辑 `config.toml` 配置 API 密钥，详见 [平台与模型](../configuration/providers.md)。模型、供应商等运行时配置也写入 `config.toml`。配置项说明见 [配置文件](../configuration/config-files.md)、[环境变量](../configuration/env-vars.md) 和 [配置覆盖](../configuration/overrides.md)。
+:::
+
+## 第一个对话
+
+登录完成后，你就可以直接用自然语言向 Kimi Code CLI 描述任务。例如，让它先帮你熟悉一下当前项目：
+
+```
+帮我看一下这个项目的目录结构，简单介绍一下每个目录是做什么的
+```
+
+Kimi Code CLI 会自动调用文件读取、搜索和网页抓取工具，浏览相关内容之后再给出回答（读取文件、搜索网页等只读操作默认自动执行，无需确认）。对于会修改文件或执行 Shell 命令的操作，它默认会在执行前征求你的确认，你可以根据需要批准或拒绝。
+
+也可以让它做一些更具体的事，比如：
+
+```
+在 src/utils 里新增一个函数，用来把任意字符串转成 kebab-case，并补一个单元测试
+```
+
+Kimi Code CLI 会规划步骤、修改代码、运行测试，并在每一步告诉你它做了什么。
+
+在交互界面中，输入 `/help` 可以查看所有可用的 [斜杠命令](../reference/slash-commands.md)，以及常用的快捷键提示。如果想退出 Kimi Code CLI，可以输入 `/exit`；也可以按 `Ctrl-C`，界面会先清空输入框并提示再按一次，再次按下即退出；还可以在输入框为空时连按两次 `Ctrl-D` 退出。
+
+## 数据存放在哪里
+
+Kimi Code CLI 的本地数据默认保存在 `~/.kimi-code/` 目录下，包含配置文件、会话记录、日志和更新缓存等。如果你想改到别的位置，可以通过环境变量 `KIMI_CODE_HOME` 指定一个新的根目录。完整的目录结构和环境变量说明见 [数据路径](../configuration/data-locations.md) 和 [环境变量](../configuration/env-vars.md)。
--- a/docs/zh/guides/interaction.md
+++ b/docs/zh/guides/interaction.md
@ -0,0 +1,67 @@
+# 交互与输入
+
+Kimi Code CLI 以交互式 TUI 运行在终端中，核心是一个输入框、对话视图和状态栏。本节介绍输入操作、模式切换、审批流程和常用快捷键，完整清单可通过 `/help` 查看。
+
+## 输入框基本操作
+
+输入框接受自由文本，按 `Enter` 发送，`Shift-Enter` 换行。输入框为空时按 `↑` / `↓` 可以浏览当前工作目录的输入历史。
+
+按 `Ctrl-D` 两次退出 CLI。`Ctrl-C` 在流式输出中会中断当前轮次，空闲状态下连按两次退出。`Esc` 关闭弹窗，流式输出中也会中断轮次。
+
+## 斜杠命令与 `@` 提及
+
+以 `/` 开头的内容会识别为斜杠命令，涵盖会话管理、模式切换、配置等场景，如 `/help`、`/new`、`/sessions`、`/model` 等。完整清单见 [斜杠命令参考](../reference/slash-commands.md)。
+
+输入 `/` 后会弹出命令补全菜单，也包括来自 [Agent Skills](../customization/skills.md) 的命令。若 skill 与内置命令重名，需要用完整形式 `/skill:<name>` 调用。按 `Esc` 关闭菜单。
+
+部分命令仅在 Agent 空闲时可用，流式输出中需先中断才能调用。`/yolo`、`/plan`、`/help` 等模式切换类命令则始终可用。
+
+键入 `@` 触发文件路径补全，选中后插入相对路径，Agent 可直接读取对应文件。以点开头的目录默认隐藏，如需可显式写成 `@.github/`。
+
+## Plan 模式
+
+Plan 模式下，Agent 会先把计划写清楚再动手。按 `Shift-Tab` 或 `/plan` 切换；`/plan clear` 清除当前计划文件（仅限空闲状态）。
+
+Agent 会先输出方案等待确认，不会直接修改项目文件。计划完成后会展示内容供你审批，可选择拒绝（保持 Plan 模式）或要求修改。退出 Plan 模式仍需你确认，即使开启了 YOLO 模式也如此。
+
+## YOLO 模式
+
+YOLO 模式自动批准大多数工具调用，跳过审批确认。输入 `/yolo`（或 `/yes`）切换，空闲或流式状态下都可用。
+
+::: warning 注意
+YOLO 模式跳过普通审批，但不会跳过 Plan 模式的退出审批。
+:::
+
+## 审批流程
+
+Agent 调用可能产生副作用的工具（如修改文件、执行命令）时，会弹出审批面板让你确认。YOLO 模式和 Plan 模式下的计划文件写入除外。
+
+使用方向键选择选项，`Enter` 确认；按数字键 `1`/`2`/`3` 可直接选择对应位置。`Esc`、`Ctrl-C`、`Ctrl-D` 等同于拒绝。面板中通常有「Approve for this session」选项，选择后同类调用将自动放行。
+
+## 流式输出期间的操作
+
+Agent 思考或调用工具（流式输出）时，输入框仍可用：
+
+- `Esc` — 中断当前轮次。
+- `Ctrl-C` — 同样可以中断；空闲状态下连按两次退出 CLI。
+- `Ctrl-S` — 把输入框中的内容作为追加消息插入当前轮次。
+- `Ctrl-O` — 全局切换工具输出的折叠状态。
+
+## 外部编辑器
+
+按 `Ctrl-G` 把当前输入交给外部编辑器处理，保存后内容回填到输入框。
+
+编辑器优先级：`/editor` 配置 > `$VISUAL` > `$EDITOR`。未配置时可先运行 `/editor` 选择默认编辑器。
+
+## 粘贴图片与视频
+
+支持在输入框中直接粘贴剪贴板里的图片或视频，交给多模态模型处理：
+
+- Unix（macOS / Linux）：`Ctrl-V`
+- Windows：`Alt-V`
+
+粘贴后输入框中会出现占位符，可像普通文本一样编辑，发送时自动替换为实际内容。纯文本剪贴板会回退到普通粘贴。媒体附件仅保留在当前会话中。
+
+## 查看完整快捷键
+
+输入 `/help` 弹出包含全部快捷键和斜杠命令的面板。`↑` / `↓` 滚动，`PageUp` / `PageDown` 翻页，`Esc` / `Enter` / `q` 关闭。
--- a/docs/zh/guides/migration.md
+++ b/docs/zh/guides/migration.md
@ -0,0 +1,37 @@
+# 从 kimi-cli 迁移
+
+Kimi Code CLI 是新一代的终端 Agent，也是一个全新的起点。如果你一直在使用上一代的 kimi-cli，不必从头开始——一条命令就能把配置、MCP server 与会话历史一起迁移到新版本。
+
+## 为什么迁移
+
+kimi-code 基于 Node.js 重写，不再依赖 Python 或 `uv` 工具链，安装和升级更简单，也提供开箱即用的原生二进制。
+
+终端界面重新设计，启动更快，运行更轻量。
+
+kimi-cli 会逐步过渡到 kimi-code，迁移后你可以继续使用已有的配置和会话历史。
+
+## 如何迁移
+
+迁移有两种方式。
+
+装好 kimi-code 之后**第一次运行 `kimi`** 时，它会自动检测 `~/.kimi/` 下是否存在 kimi-cli 的数据。一旦检测到，就会弹出迁移提示，你可以选择立即迁移、稍后再说，或不再提示。
+
+你也可以**随时手动运行**：
+
+```sh
+kimi migrate
+```
+
+你可以选择是否同时迁移聊天会话。如果暂时不需要历史记录，选 **Config only**；否则选 **Config + N sessions** 一并迁移。结束后会显示结果摘要。
+
+## 迁移会发生什么
+
+**会被迁移的内容**：配置（`config.toml`）、MCP 服务配置、输入历史，以及你选择迁移的聊天会话。
+
+**不会被迁移的内容**：OAuth 登录凭证和 MCP 服务的授权都不会被复制，迁移后需要在 kimi-code 里重新执行 `/login` 和重新授权 MCP 服务。kimi-cli 的插件也不在迁移范围内。
+
+::: tip 提示
+迁移**不会改动或删除** `~/.kimi/` 下的任何旧数据。kimi-cli 仍可照常使用，两者互不影响。迁移也可以重复运行，已经迁移过的会话不会被重复导入。
+:::
+
+迁移完成后，从 kimi-cli 导入的会话会带上 `[imported]` 标记，方便你与新建的会话区分。
--- a/docs/zh/guides/sessions.md
+++ b/docs/zh/guides/sessions.md
@ -0,0 +1,110 @@
+# 会话与上下文
+
+Kimi Code CLI 把每次对话持久化为一个「会话」，保留消息历史和元数据，可以随时关闭终端后再回来继续。本节介绍恢复会话、上下文压缩和 TUI 内的管理方法。
+
+## 会话存储
+
+所有会话保存在 `$KIMI_CODE_HOME/sessions/` 下（默认 `~/.kimi-code/sessions/`），按工作目录分组存放：
+
+```text
+~/.kimi-code/
+├── config.toml
+├── session_index.jsonl
+└── sessions/
+    └── <workDirKey>/
+        └── <sessionId>/
+            ├── state.json
+            └── agents/
+                ├── main/
+                │   └── wire.jsonl
+                └── <subagentId>/
+                    └── wire.jsonl
+```
+
+- `state.json` — 会话标题、元数据等。
+- `agents/*/wire.jsonl` — Agent 事件流。
+
+::: warning 注意
+`sessions/` 目录下的文件手动修改后可能导致会话无法恢复，建议不要手工编辑。
+:::
+
+## 启动与恢复会话
+
+默认每次执行 `kimi` 都会创建新会话。如果想接着上一次继续：
+
+**继续当前目录最近的会话：**
+
+```sh
+kimi --continue
+```
+
+**恢复指定会话：**
+
+```sh
+kimi --session abc123
+```
+
+也可以带 `-r` / `--resume`，效果相同。
+
+**交互式选择：**
+
+```sh
+kimi --session
+```
+
+::: warning 注意
+`--continue` 与 `--session` 互斥；`--yolo` 和 `--plan` 也不能与它们共用。
+:::
+
+## 在 TUI 中切换会话
+
+- `/new`（`/clear`）：切换到新会话。
+- `/sessions`（`/resume`）：浏览并恢复历史会话。
+- `/fork`：派生当前会话（详见下文）。
+- `/title <text>`（`/rename`）：设置会话标题，方便识别。不带参数时显示当前标题。
+
+`/sessions` 在流式输出期间也能浏览，但切换前需先按 `Esc` 或 `Ctrl-C` 中断。`/new`、`/fork`、`/compact` 仅在空闲时可用。
+
+## 上下文压缩
+
+对话变长时，Kimi Code CLI 会在上下文接近窗口上限时自动压缩历史消息。你也可以手动触发：
+
+```text
+/compact
+```
+
+带上自定义指引，告诉模型压缩时优先保留哪些信息：
+
+```text
+/compact 保留与数据库迁移相关的讨论
+```
+
+## 派生会话
+
+想在不破坏当前对话的前提下尝试新思路，使用 `/fork`：
+
+```text
+/fork
+```
+
+派生后的会话彼此独立，不影响原会话，你随时可以切回。
+
+## 导出会话
+
+用 `kimi export` 打包会话为 ZIP：
+
+```sh
+kimi export <sessionId>
+```
+
+不传 `sessionId` 时导出当前目录最近的会话（会交互式确认，加 `-y` 跳过）。用 `-o` 指定输出路径：
+
+```sh
+kimi export <sessionId> -o ~/Desktop/my-session.zip
+```
+
+未指定 `-o` 时，ZIP 写入当前工作目录。会话目录里的诊断日志会一并打包；此外，全局诊断日志 `$KIMI_CODE_HOME/logs/kimi-code.log`（记录 TUI 启动、登录等不属于任何会话的事件）默认也会包含进来，不需要时加 `--no-include-global-log` 跳过。
+
+::: tip 提示
+导出文件可能包含敏感信息，分享前请确认内容。
+:::
--- a/docs/zh/guides/use-cases.md
+++ b/docs/zh/guides/use-cases.md
@ -0,0 +1,118 @@
+# 常见使用案例
+
+以下是 Kimi Code CLI 的典型使用场景和 prompt 示例。
+
+## 理解陌生项目
+
+接手陌生仓库时，用 `kimi --plan` 或按 `Shift-Tab` 进入 Plan 模式，让 Agent 先输出调研计划：
+
+```
+帮我梳理这个仓库的整体架构。重点说清楚：
+1. 入口在哪里，启动后做了什么
+2. 主要模块之间的依赖关系
+3. 配置和数据的加载流程
+最后画一张简单的模块关系图。
+```
+
+聚焦问题直接问：
+
+```
+src/runtime 下的 event loop 是怎么工作的？事件从哪里产生、又被谁消费？
+```
+
+```
+这个项目里「权限审批」是怎么实现的？涉及哪些文件，关键类型是什么？
+```
+
+大型调研可以让主 Agent 派生 **子 Agent** 并行处理子任务，详见 [Agents](../customization/agents.md)。
+
+## 实现新功能
+
+描述清楚需求和验收标准即可。复杂需求建议先用 Plan 模式生成方案。
+
+```
+在 src/utils 下新增一个 retry 工具：
+- 函数签名 retry<T>(fn: () => Promise<T>, options): Promise<T>
+- 支持 maxAttempts、initialDelayMs、backoffFactor 三个选项
+- 失败时抛出最后一次的错误
+- 并补一组单元测试覆盖成功、重试后成功、全部失败三种情况
+```
+
+如不满意，直接告诉助手即可，无需手动编辑：
+
+```
+backoff 算了一个固定值，我希望加一点抖动，避免雷击效应。改一下并更新测试。
+```
+
+## 修复 bug
+
+把现象、复现条件和期望行为一次性说清楚：
+
+```
+跑 npm test 时偶发地报这个错：
+
+  TypeError: Cannot read properties of undefined (reading 'id')
+      at SessionStore.update (src/session/store.ts:142:18)
+
+只在并发触发多个 update 的用例里出现。帮我定位原因并修复，最后跑一次完整测试确认。
+```
+
+不确定原因时，让它先调查：
+
+```
+用户反馈：登录成功后第一次刷新页面会回到登录页，再刷一次就正常了。先帮我排查可能的原因，列出几个最可疑的位置，等我确认方向后再动手改。
+```
+
+纯机械任务直接放手：
+
+```
+跑一遍测试，失败的用例都修掉，跑完再跑一次确认全绿。
+```
+
+## 写测试与重构
+
+边界清晰、验收标准明确的任务特别适合交给 Agent：
+
+```
+src/parser/markdown.ts 目前几乎没有测试。请补一组单元测试，覆盖正常段落、嵌套列表、代码块、表格、引用块和混合场景。用项目里已有的测试风格。
+```
+
+```
+把 src/handlers 下重复的「读 body → 校验 → 写日志 → 返回」逻辑抽成一个中间件。改完跑一遍测试，保证现有行为不变。
+```
+
+多文件重构建议先用 Plan 模式确认方案，可用 `/fork` 试探替代方案。
+
+## 一次性脚本与自动化任务
+
+批量改文件、跑统计、调研对比等任务用一段 prompt 就能完成：
+
+```
+把 src 目录下所有 .js 文件里的 var 声明改成 const 或 let，能用 const 的优先用 const。改完跑一次 lint 确认。
+```
+
+```
+分析 logs/ 下最近 7 天的访问日志，按接口路径统计调用次数、p50 和 p99 响应时间，结果输出成一个 markdown 表格。
+```
+
+```
+帮我调研一下 TypeScript 里几种主流的依赖注入方案（tsyringe、inversify、awilix），从 API 风格、装饰器依赖、运行时开销三个维度对比，给一份不超过一页的建议。
+```
+
+用 `--yolo` 或 `/yolo` 跳过审批，或用 [permission 配置](../configuration/config-files.md#permission) 给特定工具加白名单。
+
+## 生成与维护文档
+
+```
+我刚改了 src/auth/login.ts 的接口签名，把对应的 JSDoc、README 里的示例代码、还有 docs/zh/guides 下提到这个接口的段落都同步更新一遍。
+```
+
+```
+src/api 下所有公开函数里，凡是没有 docstring 的都补上文档注释，风格参考已有的注释。
+```
+
+```
+根据 src/cli 下的命令实现，生成一份命令参考的草稿，列出每个子命令、参数和默认值，放到 docs/zh/reference 下我后续审阅。
+```
+
+需要留档或复盘时，用 `kimi export <sessionId>` 打包为 ZIP。
--- a/docs/zh/index.md
+++ b/docs/zh/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: 开始使用
+      link: guides/getting-started
+    - theme: alt
+      text: GitHub
+      link: https://github.com/MoonshotAI/kimi-code
+---
--- a/docs/zh/reference/keyboard.md
+++ b/docs/zh/reference/keyboard.md
@ -0,0 +1,112 @@
+# 键盘快捷键
+
+Kimi Code CLI 的 TUI 交互模式支持以下键盘快捷键。键位主要在输入框中生效，部分键位在弹窗（如 `/help` 帮助面板、审批面板）或流式输出（streaming）期间有不同的行为。
+
+在 TUI 中输入 `/help` 可以随时打开内置的快捷键清单。
+
+## 通用快捷键
+
+下列键位在输入框中始终可用：
+
+
+| 快捷键           | 功能                                          |
+| ------------- | ------------------------------------------- |
+| `Enter`       | 提交当前输入                                      |
+| `Shift-Enter` | 在输入中插入换行                                    |
+| `↑` / `↓`     | 浏览输入历史                                      |
+| `Esc`         | 关闭弹窗 / 取消补全 / 中断流式输出或正在进行的上下文压缩（compaction） |
+| `Ctrl-C`      | 中断当前流式输出，或清空输入框                             |
+| `Ctrl-D`      | 在输入框为空时退出 Kimi Code CLI                     |
+
+
+**流式输出期间**按 `Ctrl-C` 会立即取消，无需二次确认。
+
+**退出程序**（输入框为空时按 `Ctrl-C`，或按 `Ctrl-D`）使用「双击确认」机制：第一次按下时，状态栏会显示提示（例如 `Press Ctrl+C again to exit`），再按一次相同的键才会真正退出。如果中途按了其他键，确认状态会自动清除。
+
+## 模式切换
+
+
+| 快捷键         | 功能         |
+| ----------- | ---------- |
+| `Shift-Tab` | 切换 Plan 模式 |
+
+
+按 `Shift-Tab` 可以开启或关闭 Plan 模式。开启后，Agent 会优先使用只读工具进行研究和规划，并可以写入当前计划文件；必要时也能调用 `Bash`，它会按当前权限模式和普通规则处理，不会因为处于 Plan 模式而额外发起独立审批。单纯切换模式不会创建空计划文件。再次按 `Shift-Tab` 即可退出 Plan 模式。
+
+## 输入与编辑
+
+
+| 快捷键      | 功能                                      |
+| -------- | --------------------------------------- |
+| `Ctrl-G` | 在外部编辑器中编辑当前输入                           |
+| `Ctrl-V` | 粘贴剪贴板中的图片或视频（Unix / macOS）              |
+| `Alt-V`  | 粘贴剪贴板中的图片或视频（Windows）                   |
+| `Ctrl-E` | 展开或折叠 Plan 卡片（无 Plan 卡片时按系统默认行为将光标移到行尾） |
+| `Ctrl--` | 撤销（Undo）                                |
+
+
+按 `Ctrl-G` 会打开外部编辑器，编辑当前输入内容。编辑器按以下优先级选择：
+
+1. `/editor` 命令配置的编辑器
+2. `$VISUAL` 环境变量
+3. `$EDITOR` 环境变量
+
+保存并退出编辑器后，编辑后的内容会替换输入框中的内容；不保存退出则保持原样。
+
+粘贴图片或视频时，会在输入框中显示为占位符，实际媒体数据在提交时一并发送给模型。粘贴的优先来源是系统剪贴板里的图片或文件路径；Linux 上 Wayland 与 X11 都会被尝试，WSL 下还会通过 PowerShell 兜底读取 Windows 剪贴板。
+
+## 流式输出期间
+
+流式输出（streaming）期间，输入框依然可以接收输入，并支持以下额外操作：
+
+
+| 快捷键      | 功能                     |
+| -------- | ---------------------- |
+| `Ctrl-S` | Steer：将当前输入立即注入正在运行的轮次 |
+| `Esc`    | 中断当前流式输出               |
+| `Ctrl-C` | 中断当前流式输出               |
+
+
+按 `Ctrl-S` 时，模型会在下一个可中断的时机立刻看到你的消息，无需等待当前轮次结束。
+
+## 工具输出
+
+
+| 快捷键      | 功能        |
+| -------- | --------- |
+| `Ctrl-O` | 展开或折叠工具输出 |
+
+
+当历史中存在折叠的工具调用结果时，按 `Ctrl-O` 可以在折叠和展开之间切换，便于查看完整的工具输出。
+
+## 审批面板
+
+当 Agent 发起需要确认的工具调用时，TUI 会弹出审批面板。详细的审批流程见 [交互与输入](../guides/interaction.md#审批流程)，下表给出面板内可用的键位：
+
+
+| 快捷键                         | 功能                            |
+| --------------------------- | ----------------------------- |
+| `↑` / `↓`                   | 在候选选项之间移动光标                   |
+| `Enter`                     | 确认当前选中的选项                     |
+| `1` ~ `9`                   | 直接选择对应序号的选项                   |
+| `Esc` / `Ctrl-C` / `Ctrl-D` | 拒绝当前请求                        |
+| `Ctrl-E`                    | 当面板包含 diff 或文件内容预览时，展开或折叠完整内容 |
+| `Ctrl-O`                    | 切换其他工具输出的折叠状态                 |
+
+
+需要附带反馈的选项（例如「Reject」「Revise」）会在确认后切换到反馈输入态：直接输入反馈文本，按 `Enter` 提交；按 `Esc` 退出反馈输入并回到候选列表。
+
+## 弹窗模式
+
+输入 `/help` 打开帮助面板后，可使用以下键位浏览和关闭面板：
+
+
+| 快捷键                   | 功能         |
+| --------------------- | ---------- |
+| `↑` / `↓`             | 单行滚动       |
+| `PageUp` / `PageDown` | 每次滚动 10 行 |
+| `Esc`                 | 关闭面板       |
+| `Enter`               | 关闭面板       |
+| `q` / `Q`             | 关闭面板       |
+
+
--- a/docs/zh/reference/kimi-command.md
+++ b/docs/zh/reference/kimi-command.md
@ -0,0 +1,154 @@
+# kimi 命令
+
+`kimi` 是 Kimi Code CLI 的主命令，用于在终端中启动一次交互式会话。不带任何参数运行时，它会在当前工作目录下开启一个新会话；配合不同的 flag，可以续上历史会话、跳过审批、从 Plan 模式开始，或者指定自定义的 Skills 目录。
+
+```sh
+kimi [options]
+kimi <subcommand> [options]
+```
+
+## 主命令选项
+
+下表列出 `kimi` 主命令支持的全部选项。所有 flag 都是可选的，直接运行 `kimi` 即可进入交互式会话。
+
+| 选项 | 简写 | 说明 |
+| --- | --- | --- |
+| `--version` | `-V` | 打印版本号并退出。 |
+| `--help` | `-h` | 显示帮助信息并退出。 |
+| `--session [id]` | `-S` | 恢复一个会话。带 ID 时直接打开指定会话；不带 ID 时进入交互式选择器，从历史会话中挑选。 |
+| `--continue` | `-C` | 继续当前工作目录下最近一次的会话，无需手动指定 ID。 |
+| `--model <model>` | `-m` | 为本次启动指定模型别名。省略时，新会话使用配置文件中的 `default_model`，恢复会话使用会话当前模型。 |
+| `--prompt <prompt>` | `-p` | 非交互执行单次 prompt，并把 Assistant 输出流式写到 stdout。该模式会使用 `auto` 权限处理工具调用，不会打开 TUI。 |
+| `--output-format <format>` | | 设置非交互输出格式，支持 `text` 与 `stream-json`。仅可与 `--prompt` 一起使用，默认 `text`。 |
+| `--yolo` | `-y` | 自动批准普通工具调用，跳过审批请求；Plan 模式中的 `Bash` 审批和退出审批不会被跳过。 |
+| `--plan` | | 以 Plan 模式启动新会话，AI 会优先使用只读工具进行探索和规划，可以写入当前计划文件；Plan 模式中的 `Bash` 按权限模式单独处理。 |
+| `--skills-dir <dir>` | | 从指定目录加载 Skills，替换自动发现的用户和项目目录。可重复传入以叠加多个目录。详见下文 [自定义 Skills 目录](#自定义-skills-目录)。 |
+
+`-r` / `--resume` 是 `--session` 的隐藏别名；`--yes` 和 `--auto-approve` 是 `--yolo` 的隐藏别名。它们在帮助信息中不会显示，行为与对应的官方 flag 完全一致。
+
+::: warning 注意
+`--yolo` 会跳过普通工具调用的人工确认，包括文件写入和 Shell 命令执行。请只在受信任的工作目录下使用。Plan 模式的退出审批不会被 `--yolo` 跳过；Plan 模式下的 `Bash` 也按 `--yolo` 的普通放行规则处理。
+:::
+
+### flag 冲突规则
+
+以下组合会在启动时被拒绝：
+
+- `--continue` 与 `--session` 互斥：两者都表示"恢复历史会话"，含义重叠。
+- `--yolo` 不能与 `--continue` 或 `--session` 同时使用：恢复会话时会沿用原会话的审批设置。此规则仅适用于交互式模式；在 `--prompt` 模式下，`--yolo` 已因与 `--prompt` 互斥而被更早拦截。
+- `--plan` 不能与 `--continue` 或 `--session` 同时使用：Plan 模式只对新会话生效。
+- `--prompt` 不能与 `--yolo` 或 `--plan` 同时使用：非交互模式固定使用 `auto` 权限，并且不进入 Plan 模式。
+- `--prompt` 可以与 `--continue` 或带 ID 的 `--session <id>` 一起使用；不带 ID 的 `--session` 会尝试打开选择器，因此不能用于非交互模式。
+- `--output-format` 只能与 `--prompt` 一起使用；交互式 TUI 不支持把完整事件流写成 stdout JSONL。
+
+如果需要在恢复会话时强制使用 YOLO 或 Plan 模式，请改在交互式会话内通过斜杠命令切换。
+
+## 典型用法
+
+最常见的入口是直接运行 `kimi`，在当前目录开启一次全新的会话：
+
+```sh
+kimi
+```
+
+如果上一次会话被打断（关闭终端、网络断开等），想从断点继续，使用 `--continue`：
+
+```sh
+kimi --continue
+```
+
+它会自动找到当前工作目录下时间最近的那个会话并恢复。若想挑选其他历史会话，运行 `kimi --session` 进入交互式选择器，或者直接传入已知的 session ID：
+
+```sh
+kimi --session 01HZ...XYZ
+```
+
+当任务比较琐碎，不希望被频繁的审批请求打断时，可以加上 `--yolo`：
+
+```sh
+kimi --yolo
+```
+
+需要先让 AI 阅读代码、产出实现计划，而不是立刻动手修改文件时，使用 `--plan` 进入 Plan 模式：
+
+```sh
+kimi --plan
+```
+
+### 自定义 Skills 目录
+
+如果需要加载自定义的 Skills 目录，可以通过两种方式指定：
+
+- **CLI flag `--skills-dir <dir>`**：可重复传入，会**替换**自动发现的用户和项目目录，适合临时切换或在脚本中使用。例如同时挂载两个目录：
+
+  ```sh
+  kimi --skills-dir /path/to/team-skills --skills-dir ./local-skills
+  ```
+
+- **`config.toml` 的 `extra_skill_dirs`**：在配置文件中追加额外目录，与自动发现的目录**叠加**生效，适合长期配置团队共享 Skills（详见 [Agent Skills](../customization/skills.md)）。
+
+## 非交互执行
+
+需要在脚本或 CI 中运行单次 prompt 时，使用 `-p`：
+
+```sh
+kimi -p "Summarize the current repository status"
+```
+
+输出采用 transcript 样式：thinking 内容和 Assistant 正文都会以 `• ` 开头，换行后使用两个空格缩进。Assistant 正文会输出到 stdout；thinking、工具进度和 `To resume this session: kimi -r <id>` 提示输出到 stderr。`-p` 模式不会请求人工审批，普通工具调用、Plan 审批和 Agent 提问都会按 `auto` 权限策略处理。静态 deny 规则仍然会阻止匹配的工具调用。
+
+需要临时切换模型时，加上 `-m`：
+
+```sh
+kimi -m kimi-code/kimi-for-coding -p "Explain the latest diff"
+```
+
+如果脚本需要结构化读取输出，可以使用 JSONL：
+
+```sh
+kimi -p "List changed files" --output-format stream-json
+```
+
+`stream-json` 模式下，stdout 每行都是一个 JSON 对象。普通回复会输出 Assistant 消息；如果模型调用工具，会先输出带 `tool_calls` 的 Assistant 消息，再输出对应的 Tool 消息，最后继续输出后续 Assistant 消息。thinking 内容不会写入 JSONL；工具进度和恢复会话提示仍然写到 stderr。
+
+## 子命令
+
+### `kimi export`
+
+把一个会话打包成 ZIP 文件，便于分享、归档或者提交问题反馈。导出的压缩包包含会话目录下的所有文件，例如上下文记录、状态文件和会话诊断日志（如果该会话已经产生 `logs/kimi-code.log`）。
+
+```sh
+kimi export [sessionId] [options]
+```
+
+| 参数 / 选项 | 简写 | 说明 |
+| --- | --- | --- |
+| `sessionId` | | 要导出的会话 ID。省略时会自动选择当前工作目录下最近一次的会话，并要求确认。 |
+| `--output <path>` | `-o` | 输出 ZIP 文件路径。省略时写入当前目录下的默认文件名。 |
+| `--yes` | `-y` | 跳过默认会话的确认提示，直接导出。 |
+| `--no-include-global-log` | | 不打包当前活动的全局诊断日志，即 `~/.kimi-code/logs/kimi-code.log`。默认包含。 |
+
+默认导出包含目标会话目录内的文件；如果会话目录里有 `logs/kimi-code.log`，会一并出现在 ZIP 的 `logs/kimi-code.log`。全局诊断日志 `~/.kimi-code/logs/kimi-code.log` 默认也会打包，因为它可能包含其它会话或其它项目的事件，如果不想分享可以加 `--no-include-global-log`。加上后，ZIP 内路径是 `logs/global/kimi-code.log`，不会包含轮转出来的 `kimi-code.log.1` 等旧文件。
+
+省略 `sessionId` 时，命令会先打印待导出的会话信息并请求确认；用 `-y` 可以跳过确认，适合在脚本里使用：
+
+```sh
+# 导出当前工作目录最近一次会话，跳过确认
+kimi export -y
+
+# 导出指定会话到自定义路径
+kimi export 01HZ...XYZ -o ./bug-report.zip
+
+# 排除全局诊断日志，避免分享其它会话的事件
+kimi export 01HZ...XYZ -o ./bug-report.zip --no-include-global-log
+```
+
+### `kimi migrate`
+
+将旧版 kimi-cli 的本地数据迁移到 kimi-code。该命令无任何 flag，纯交互式运行，会引导你完成数据迁移的全流程。
+
+```sh
+kimi migrate
+```
+
+如果你之前使用过旧版 kimi-cli，可以运行此命令将历史会话、配置等数据迁移到 kimi-code 中，避免数据丢失。完整的迁移流程、迁移内容与注意事项见 [从 kimi-cli 迁移](../guides/migration.md)。
--- a/docs/zh/reference/slash-commands.md
+++ b/docs/zh/reference/slash-commands.md
@ -0,0 +1,86 @@
+# 斜杠命令
+
+斜杠命令是 Kimi Code CLI 在交互式 TUI 中提供的内置控制命令，用于切换模式、管理会话、查看状态等。在输入框中输入 `/` 即可触发命令补全，候选列表会随后续字符实时过滤；命令的别名（alias）也会一并参与匹配。
+
+输入完整命令名（如 `/help`）后按 `Enter` 即可执行。如果输入的 `/` 开头内容不匹配任何内置或 Skill 命令，则按普通消息发送给 Agent。
+
+::: tip 提示
+部分命令仅在空闲（idle）状态下可用。会话正在流式输出或正在压缩上下文时执行这些命令会被拦截，并提示先按 `Esc` 或 `Ctrl-C` 中断当前操作。下表的 「随时可用」 列标注了在流式输出 / 上下文压缩期间也可用的命令。
+:::
+
+## 账号与配置
+
+| 命令 | 别名 | 说明 | 随时可用 |
+| --- | --- | --- | --- |
+| `/login` | — | 选择账号或平台并登录：Kimi Code 走 OAuth device code 流程，Moonshot AI 开放平台通过 API 密钥登录。 | 否 |
+| `/logout` | — | 清除当前所选账号的凭据（Kimi Code OAuth 凭据，或对应开放平台的供应商配置）。 | 否 |
+| `/model` | — | 切换当前会话使用的 LLM 模型。 | 是 |
+| `/settings` | `/config` | 打开 TUI 内的设置面板。 | 是 |
+| `/permission` | — | 选择权限模式（permission mode）。 | 是 |
+| `/editor` | — | 配置 `Ctrl-G` 调起的外部编辑器。 | 是 |
+| `/theme` | — | 切换终端 UI 配色主题。 | 是 |
+
+## 会话管理
+
+| 命令 | 别名 | 说明 | 随时可用 |
+| --- | --- | --- | --- |
+| `/new` | `/clear` | 开启一个全新会话，丢弃当前上下文。 | 否 |
+| `/sessions` | `/resume` | 浏览历史会话并切换/恢复。 | 是 |
+| `/tasks` | `/task` | 浏览后台任务列表。 | 是 |
+| `/fork` | — | 基于当前会话 fork 一份新会话，保留完整对话历史。 | 否 |
+| `/title [<text>]` | `/rename` | 不带参数时显示当前会话标题；带参数时将其设置为新标题（最长 200 个字符）。 | 是 |
+| `/compact [<instruction>]` | — | 压缩当前对话上下文，释放 token 占用；可选附带一段自定义指令，提示模型在压缩时保留哪些信息。 | 否 |
+| `/init` | — | 分析当前代码库并生成 `AGENTS.md`。 | 否 |
+
+## 模式与运行控制
+
+| 命令 | 别名 | 说明 | 随时可用 |
+| --- | --- | --- | --- |
+| `/yolo [on\|off]` | `/yes` | 切换自动批准模式（auto-approve）。不带参数时按当前状态翻转；显式传 `on`/`off` 时强制设为对应状态。开启后跳过普通工具调用审批；Plan 模式的退出审批不会被跳过。 | 是 |
+| `/plan [on\|off]` | — | 切换 Plan 模式。不带参数时按当前状态翻转；显式传 `on`/`off` 时强制设为对应状态。单纯切换不会创建空计划文件。 | 是 |
+| `/plan clear` | — | 清除当前 plan 方案。 | 否 |
+
+::: warning 注意
+`/yolo` 会跳过普通工具调用的审批确认，使用前请确保了解可能的风险。Plan 模式的退出审批不会被 `/yolo` 跳过；Plan 模式下的 `Bash` 也按 `/yolo` 的普通放行规则处理。
+:::
+
+## 信息与状态
+
+| 命令 | 别名 | 说明 | 随时可用 |
+| --- | --- | --- | --- |
+| `/help` | `/h`、`/?` | 显示快捷键和所有可用命令。 | 是 |
+| `/usage` | — | 显示 token 用量、上下文占用以及配额信息。 | 是 |
+| `/status` | — | 显示当前会话运行时状态，包括版本、模型、工作目录和权限模式等。 | 是 |
+| `/mcp` | — | 列出当前会话中的 MCP server 及其连接状态。 | 是 |
+| `/version` | — | 显示 Kimi Code CLI 版本号。 | 是 |
+| `/feedback` | — | 提交反馈以改进 Kimi Code CLI。 | 是 |
+
+## 退出
+
+| 命令 | 别名 | 说明 | 随时可用 |
+| --- | --- | --- | --- |
+| `/exit` | `/quit`、`/q` | 退出 Kimi Code CLI。 | 否 |
+
+## Skill 动态命令
+
+除内置命令外，用户可激活的 Skill 会自动注册为斜杠命令，统一以 `skill:` 作为命名空间前缀：
+
+```
+/skill:<name> [附加文本]
+```
+
+例如 `/skill:code-style` 会加载名为 `code-style` 的 Skill 内容并发送给 Agent；命令后附带的文本会拼接到 Skill 提示词之后，例如 `/skill:git-commits 修复登录失败的问题`。
+
+为方便输入，Skill 命令同时支持省略 `skill:` 前缀的简写形式 `/<name>`，前提是该名称未被内置命令占用。也就是说，`/code-style` 会回退匹配到 `/skill:code-style`。
+
+Kimi Code CLI 随包内置了 `mcp-config` Skill，用于配置 MCP server 和处理 MCP OAuth 登录。它在补全和帮助里仍属于 Skill 命名空间（`/skill:mcp-config`），也可以直接输入 `/mcp-config` 调用。
+
+可作为斜杠命令暴露的 Skill 类型包括 `prompt`、`inline`、`flow` 以及未显式声明类型的 Skill。Skill 的安装与编写详见 [Agent Skills](../customization/skills.md)。
+
+::: info 说明
+所有 Skill 命令仅在空闲状态下可用，流式输出或上下文压缩期间需先按 `Esc` 或 `Ctrl-C` 中断当前操作。
+:::
+
+::: info 说明
+Flow 类型的 Skill 同样通过 `/skill:<name>` 暴露，没有独立的 `/flow:` 命名空间。
+:::
--- a/docs/zh/reference/tools.md
+++ b/docs/zh/reference/tools.md
@ -0,0 +1,104 @@
+# 内置工具
+
+内置工具是 Kimi Code CLI 随核心引擎一起提供的工具集，无需安装 MCP server 即可使用。Agent 在每次对话中会根据任务需要自动选择并调用这些工具；用户也可以通过权限审批界面查看每次工具调用的细节。
+
+与 MCP 工具相比，内置工具由运行时直接管理，生命周期与会话绑定，无需外部进程。两者都遵循统一的审批机制：**只读类工具**（如 `Read`、`Grep`、`Glob`、`WebSearch` 等）默认自动放行，**写入与执行类工具**（如 `Write`、`Edit`、`Bash`、`TaskStop`）默认需要用户审批。在 YOLO 模式下，普通工具调用的审批会被跳过，但 Plan 模式下的退出审批不受影响。
+
+## 文件类
+
+文件类工具负责读取、写入、搜索本地文件系统，是代码分析和修改任务的基础工具。
+
+| 工具 | 默认审批 | 说明 |
+| --- | --- | --- |
+| `Read` | 自动放行 | 读取文本文件内容 |
+| `Write` | 需审批 | 创建或覆盖文件 |
+| `Edit` | 需审批 | 精确字符串替换 |
+| `Grep` | 自动放行 | 基于 ripgrep 的全文搜索 |
+| `Glob` | 自动放行 | 按 glob 模式查找文件 |
+| `ReadMediaFile` | 自动放行 | 读取图片或视频文件 |
+
+**`Read`** 接受文件路径（`path`）以及可选的 `line_offset`（起始行号，支持负数从末尾倒数）和 `n_lines`（读取行数上限）。单次最多返回 1000 行或 100 KB，超出部分会附带截断提示。如果文件是图片或视频，工具会提示改用 `ReadMediaFile`。
+
+**`Write`** 接受 `path`、`content` 和可选的 `mode`（`overwrite` 或 `append`，默认覆盖）。父目录必须已存在；`append` 模式将内容追加到文件末尾，不自动添加换行。
+
+**`Edit`** 接受 `path`、`old_string`（要替换的精确文本）和 `new_string`（替换后的文本）。默认只替换唯一一处匹配，若文件中存在多处相同内容会报错并提示使用 `replace_all: true`。`old_string` 与 `new_string` 不能相同。
+
+**`Grep`** 调用 ripgrep 搜索文件内容，支持正则表达式（`pattern`）、搜索路径（`path`）、文件类型过滤（`type`，如 `ts`、`py`）、glob 过滤（`glob`）和输出模式（`output_mode`：`files_with_matches` / `content` / `count_matches`，默认 `files_with_matches`）。`content` 模式支持 `-A`、`-B`、`-C` 上下文行参数与 `-i`（忽略大小写）、`-n`（行号，默认 true）、`multiline`（跨行匹配）。所有模式均支持 `offset` + `head_limit` 分页，`head_limit` 默认 250、传 0 表示不限。`files_with_matches` 模式的结果按文件最近修改时间倒序排列；其他模式保持 ripgrep 原始输出顺序。`.env`、私钥、`.aws/credentials`、`.gcp/credentials` 等敏感文件会被自动过滤；`include_ignored=true` 可同时搜索被 `.gitignore` 等忽略的文件，但敏感文件仍保持过滤。
+
+**`Glob`** 按 glob 模式（`pattern`）在指定目录（`path`，默认为工作目录）中匹配文件，结果按修改时间倒序排列，最多返回 1000 条。可选参数 `include_dirs`（默认 true）控制是否返回目录条目。纯通配符模式（如 `**`、`**/*`）会被拒绝并提示添加字面锚点；包含花括号扩展（`{a,b,c}`）的模式同样会被拒绝——底层 glob 引擎把 `{`、`}` 当字面量处理，这类模式会静默匹配 0 个文件。
+
+**`ReadMediaFile`** 将图片或视频文件以多模态内容发送给模型，仅接受 `path`。文件大小上限为 100 MB。工具是否可用取决于当前模型的视觉能力（`image_in` / `video_in`）。
+
+## Shell
+
+| 工具 | 默认审批 | 说明 |
+| --- | --- | --- |
+| `Bash` | 需审批 | 执行 Shell 命令 |
+
+**`Bash`** 是最通用也是权限要求最严格的工具。它接受 `command`（必填）以及可选的 `cwd`（工作目录）、`timeout`（毫秒）、`description`（后台任务描述，`run_in_background=true` 时必填）、`run_in_background`（是否以后台任务运行）和 `disable_timeout`（后台任务是否取消超时）。前台 `timeout` 默认 60 秒、最长 5 分钟；后台 `timeout` 默认 10 分钟、最长 10 分钟。
+
+前台模式下 `Bash` 会阻塞当前轮次，直到命令结束或超时；后台模式会立即返回任务 ID。后台任务默认 10 分钟后超时；如果确实需要让任务不受超时限制，可以设置 `disable_timeout=true`。任务结束、失败或被停止时会自动通知 Agent 继续处理，过程中也可通过 `TaskOutput` 主动查看结果。stdin 始终被关闭，交互式命令会立即收到 EOF。两阶段终止策略（SIGTERM → 5 秒宽限期 → SIGKILL）确保超时后进程能可靠结束。Windows 平台下默认使用 Git Bash 作为 shell。
+
+## 网络类
+
+| 工具 | 默认审批 | 说明 |
+| --- | --- | --- |
+| `WebSearch` | 自动放行 | 网络搜索 |
+| `FetchURL` | 自动放行 | 获取指定 URL 的内容 |
+
+**`WebSearch`** 接受 `query`（搜索词）和可选的 `limit`（返回结果数，1–20，默认 5）及 `include_content`（是否返回网页正文，默认 false，开启后消耗 token 较多）。该工具需要宿主提供搜索实现，未注入实现时不会出现在工具列表中。
+
+**`FetchURL`** 接受单个 `url` 参数，返回页面内容。对于 HTML 页面，宿主会提取正文文章（`extracted`）而非返回完整 HTML；纯文本或 Markdown 页面则直接透传（`passthrough`）。同样需要宿主注入实现。
+
+## Plan 模式
+
+| 工具 | 默认审批 | 说明 |
+| --- | --- | --- |
+| `EnterPlanMode` | 自动放行 | 进入 Plan 模式 |
+| `ExitPlanMode` | 自动放行（需用户确认计划） | 退出 Plan 模式并提交计划 |
+
+Plan 模式是一种受约束的工作状态：进入后 `Write` 与 `Edit` 工具被收紧——只允许写入当前的计划文件，其它路径会被阻断；`TaskStop` 也被完全拦截。其余工具（包括 `Bash`）仍按当前权限规则处理，因此通过 `Bash` 调用的命令理论上仍可能修改文件，是否放行取决于当前的审批策略。
+
+**`EnterPlanMode`** 不接受任何参数，进入成功后返回工作流指引，包括计划文件路径（如果宿主提供了的话）。
+
+**`ExitPlanMode`** 读取当前计划文件内容，将计划呈现给用户审批后退出 Plan 模式。可选参数 `options` 允许 Agent 提供 1–3 个备选方案（每项含 `label` 与 `description`，`label` 最长 80 字符），供用户在审批时选择；标签需互不重复，且不能使用 `Approve`、`Reject`、`Reject and Exit`、`Revise` 这些保留词（系统用它们标记审批结果）。用户批准后，所有工具重新可用；若用户要求修改，Agent 将继续留在 Plan 模式中。
+
+## 状态管理
+
+| 工具 | 默认审批 | 说明 |
+| --- | --- | --- |
+| `TodoList` | 自动放行 | 管理任务待办列表 |
+
+**`TodoList`** 用于在多步骤操作中维护一份可见的子任务列表，状态存储在 Agent 会话内。`todos` 参数接受一个数组，每项含 `title`（标题）和 `status`（`pending` / `in_progress` / `done`）；省略 `todos` 则仅查询当前列表，传入空数组则清空列表。
+
+## 协作类
+
+协作类工具负责 Agent 间协作、用户交互和 Skill 调用。
+
+| 工具 | 默认审批 | 说明 |
+| --- | --- | --- |
+| `Agent` | 自动放行 | 派生子 Agent 执行子任务 |
+| `AskUserQuestion` | 自动放行 | 向用户提问以获取结构化输入 |
+| `Skill` | 自动放行 | 调用已注册的 inline Skill |
+
+**`Agent`** 用于将子任务委托给子 Agent 执行。必填参数为 `prompt`（完整任务描述）和 `description`（3–5 个词的简短说明，用于 UI 展示）。可选参数包括 `subagent_type`（Agent 类型，默认 `coder`）、`resume`（恢复已有 Agent 的 ID）、`run_in_background`（是否后台运行，默认 false）和 `timeout`（超时秒数，30–3600）。`subagent_type` 与 `resume` 互斥：恢复已有 Agent 时只通过 ID 寻址。前台 `timeout` 缺省表示不超时，子 Agent 运行至完成；后台 `timeout` 缺省时回落到 `config.toml` 的 `[background] agent_task_timeout_s`，该字段也未设置则无时间上限。前台模式下父 Agent 会等待子 Agent 完成再继续；后台模式立即返回任务 ID，完成时通过合成 user 消息自动回到主 Agent，无需轮询。子 Agent 体系细节参见 [子 Agent](../customization/agents.md)。
+
+**`AskUserQuestion`** 以结构化多选题的形式向用户提问，适用于需要用户消歧或选择方案的场景。`questions` 参数接受 1–4 道题，每道题需提供 `question`（问题文本，以 `?` 结尾）、`options`（2–4 个选项，每项含 `label` 和 `description`）以及可选的 `header`（最多 12 字符的短分类标签，如 `Auth`、`Style`）和 `multi_select`（是否多选，默认 false）。系统会自动附加「其他」选项，无需在 `options` 中手工提供。若宿主未实现交互式提问能力，本工具会返回失败提示，Agent 应改为直接在文本回复中向用户提问。
+
+**`Skill`** 允许 Agent 主动调用已注册的 inline 类型 Skill。接受 `skill`（Skill 名称）和可选的 `args`（附加参数文本）。只有 `type = "inline"` 的 Skill 能通过此工具调用；其他类型（如 `prompt`、`flow`）以及在 frontmatter 中设置了 `disableModelInvocation: true` 的 Skill 会被拒绝。为防止递归死循环，Skill 嵌套调用深度上限为 3 层。Skill 体系细节参见 [Skills](../customization/skills.md)。
+
+## 后台任务
+
+后台任务工具用于管理通过 `Bash` 或 `Agent` 启动的后台任务。后台任务进入完成、失败、停止或丢失等终止状态时，会把状态和末尾输出自动送回 Agent；如果只想提前检查进度，再使用 `TaskOutput`。
+
+| 工具 | 默认审批 | 说明 |
+| --- | --- | --- |
+| `TaskList` | 自动放行 | 列出后台任务 |
+| `TaskOutput` | 自动放行 | 查看后台任务的输出 |
+| `TaskStop` | 需审批 | 停止正在运行的后台任务 |
+
+**`TaskList`** 返回后台任务列表，每条记录包含任务 ID、状态、命令、描述和 PID。可选参数 `active_only`（默认 true，仅列出运行中的任务）和 `limit`（最多返回条数，默认 20，取值范围 1–100）。已进入终止状态的任务还会附带 `exit_code`，被 `TaskStop` 显式终止的任务会附带 `reason`。
+
+**`TaskOutput`** 根据 `task_id` 返回指定任务的状态与输出。内联预览最多包含最近 32 KB 的内容；完整日志保存在磁盘上，工具会一并返回 `output_path` 并提示通过 `Read` 分页读取（建议每页约 300 行）。可选 `block`（默认 false）和 `timeout`（等待秒数，默认 30，取值范围 0–3600）参数可用于等待任务完成后再返回。返回结构中 `retrieval_status` 取 `success` / `timeout` / `not_ready`；任务因超时被外部 deadline 中止时会附带 `timed_out: true` 与 `terminal_reason: timed_out`，被 `TaskStop` 显式终止时会附带 `stop_reason` 与 `terminal_reason: stopped`。
+
+**`TaskStop`** 接受 `task_id` 和可选的 `reason`（停止原因，默认 `Stopped by TaskStop`）。对已处于终止状态的任务也能安全调用，会直接返回当前状态而不报错。
--- a/docs/zh/release-notes/changelog.md
+++ b/docs/zh/release-notes/changelog.md
@ -0,0 +1,5 @@
+# 变更记录
+
+::: info 说明
+本页将随首个正式版本同步发布详细变更记录。
+:::