Add files using upload-large-folder tool

.changeset/README.md

@@ -0,0 +1,154 @@
+# Changesets
+
+This repository uses [changesets](https://github.com/changesets/changesets) to manage npm package versions and releases.
+
+## Package Publishing Strategy
+
+This repository uses an **independent, manually-selected publishing** strategy. When generating a changeset, only select the publishable packages that this change actually affects. The repository's `.changeset/config.json` already filters out internal workspace packages via `ignore`, so only the publishable packages listed below should appear in the `pnpm changeset` prompt.
+
+Current publishable packages:
+
+| Package | Directory | Description |
+| --- | --- | --- |
+| `@moonshot-ai/kimi-code` | `apps/kimi-code` | CLI / TUI application — provides the `kimi` command after install |
+| `@moonshot-ai/kimi-code-sdk` | `packages/node-sdk` | Public TypeScript SDK |
+
+All other workspace packages are private internal packages, are not published to npm, and are excluded via `ignore` in `.changeset/config.json`:
+
+- `@moonshot-ai/kaos`
+- `@moonshot-ai/kimi-code-oauth`
+- `@moonshot-ai/kimi-telemetry`
+- `@moonshot-ai/kosong`
+- `@moonshot-ai/migration-legacy`
+- `@moonshot-ai/vis`
+- `@moonshot-ai/vis-server`
+- `@moonshot-ai/vis-web`
+
+Version impact from internal dependencies must be judged manually. The published artifacts for CLI and SDK bundle internal workspace packages into the artifact itself; runtime `dependencies` of published packages must not include any `@moonshot-ai/*` internal workspace packages.
+
+The repository's `.changeset/config.json` sets `updateInternalDependencies: "patch"`. Because internal packages are not published, you still need to manually select all affected publishable packages in the changeset — do not rely solely on automatic dependency bumps to express user-visible changes.
+
+Example scenarios:
+
+| Change | Changeset selection |
+| --- | --- |
+| Only modifies TUI behavior in `@moonshot-ai/kimi-code` | Add `patch` / `minor` / `major` to `@moonshot-ai/kimi-code` |
+| Only modifies internal packages, no user-visible change in SDK / CLI | Usually no changeset needed |
+| Internal package fix changes the CLI user experience | Add a changeset to `@moonshot-ai/kimi-code` describing the user-visible fix |
+| Internal package adds a new capability exposed by the SDK | Add a changeset to `@moonshot-ai/kimi-code-sdk` |
+| SDK behavior change affects CLI user experience | Add changesets to both `@moonshot-ai/kimi-code-sdk` and `@moonshot-ai/kimi-code` |
+| Provider abstraction change affects SDK / CLI | Add changesets to the affected `@moonshot-ai/kimi-code-sdk` and/or `@moonshot-ai/kimi-code` |
+| Test-only, internal refactor, docs, or private debug tooling changes | Usually no changeset needed |
+| Bundled official plugin change under `plugins/` (e.g. `kimi-datasource`) | No changeset — the plugin is versioned via its own `kimi.plugin.json` / `plugins/marketplace.json` and shipped through the marketplace CDN, not the npm package |
+
+## Prerequisite: NPM Trusted Publishing (OIDC)
+
+This repository uses npm's **Trusted Publishing** (OIDC-based) for publishing — no `NPM_TOKEN` is required.
+
+### Configuration steps
+
+1. Open each publishable package's page on the npm website, e.g. `https://www.npmjs.com/package/@moonshot-ai/kimi-code`.
+2. Go to **Settings** -> **Publishing access**.
+3. Find **Automate publishing with GitHub Actions** or **Add trusted publisher**.
+4. Click **Add a new trusted publisher**.
+
+Fill in the following:
+
+| Field | Value |
+| --- | --- |
+| GitHub Organization | `MoonshotAI` |
+| GitHub Repository | `kimi-code` |
+| GitHub Workflow | `release.yml` |
+| Environment | leave empty |
+
+Each publishable package needs its Trusted Publisher configured once. The current GitHub Actions workflow lives at `.github/workflows/release.yml` and already has `id-token: write` configured.
+
+## Development Workflow
+
+### 1. Implement the feature or fix
+
+Complete code, tests, and documentation changes as usual. A changeset is required when the change affects user-visible behavior, public API, dependency ranges, or release artifacts of a publishable package.
+
+### 2. Generate a changeset
+
+From the repository root:
+
+```sh
+pnpm changeset
+```
+
+Follow the prompts to choose:
+
+- Which publishable packages this change affects;
+- The version bump level:
+  - `patch`: bug fixes, small changes, follow-up dependency updates;
+  - `minor`: backward-compatible new features;
+  - `major`: breaking changes;
+- A user-facing description of the change.
+
+The command creates a `.changeset/*.md` file that must be committed alongside the code.
+
+### 3. Commit the changeset
+
+```sh
+git add .changeset/
+git commit -m "chore: add changeset for package release"
+git push
+```
+
+Commit messages must follow Conventional Commit style. Do not include any author/agent identity in the commit message.
+
+### 4. CI generates the release PR
+
+Once the changeset file is merged into `main`, `.github/workflows/release.yml` uses `changesets/action@v1` to create or update a release PR.
+
+The release PR runs:
+
+- `pnpm changeset version`: bumps publishable package versions and updates changelogs;
+- Deletes the consumed `.changeset/*.md` files;
+- Uses the title `[CI]: Release packages`.
+
+### 5. Merge the release PR
+
+Once the release PR is merged into `main`, the same workflow runs:
+
+- `pnpm install --frozen-lockfile`
+- `pnpm build`
+- `pnpm changeset publish`
+
+The packages are then published via npm Trusted Publishing, and a GitHub Release is created.
+
+## Manual Publishing (Not Recommended)
+
+Only publish manually when CI is unavailable. Before publishing manually, make sure you are logged into npm locally and using the Node.js and pnpm versions required by the repository.
+
+```sh
+pnpm run version
+pnpm run publish
+```
+
+The underlying changesets commands are:
+
+```sh
+pnpm changeset version
+pnpm changeset publish
+```
+
+The root-level `pnpm run publish` first runs typecheck, lint, sherif, test, build, and package lint, then runs `changeset publish`.
+
+## Notes
+
+- Every PR that affects publishable-package behavior or public API should include a corresponding changeset.
+- Changes under `plugins/` (the bundled official plugins such as `kimi-datasource`) do **not** need a changeset: each plugin carries its own version in `kimi.plugin.json` and `plugins/marketplace.json` and is distributed via the marketplace CDN, separately from the `@moonshot-ai/kimi-code` npm package.
+- Changeset files must be committed to the repository — release PRs are only triggered after they're merged.
+- Release PRs require human review and merge; they will not publish automatically.
+- Do not add release changesets for private internal packages; only select `@moonshot-ai/kimi-code` and `@moonshot-ai/kimi-code-sdk`.
+- If a change in an underlying internal package alters user-visible behavior or public API of a publishable package, add a changeset to the affected publishable package. For example, when a bug fixed in `@moonshot-ai/kosong` resolves an issue CLI users encounter, add a changeset to `@moonshot-ai/kimi-code` describing the user-visible fix.
+- `@moonshot-ai/kimi-code` is the official CLI package name; after a global install it provides the `kimi` command.
+- Make sure each publishable package on npm has a Trusted Publisher configured.
+
+## References
+
+- [Changesets documentation](https://github.com/changesets/changesets)
+- [Changesets GitHub Action](https://github.com/changesets/action)
+- [npm Trusted Publishing documentation](https://docs.npmjs.com/trusted-publishers)

.changeset/abort-error-escape.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Fix an occasional crash when a running turn is canceled.

.changeset/config.json

@@ -0,0 +1,19 @@
+{
+  "changelog": ["@changesets/changelog-github", { "repo": "MoonshotAI/kimi-code" }],
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": [
+    "@moonshot-ai/vis",
+    "@moonshot-ai/vis-server",
+    "@moonshot-ai/vis-web",
+    "@moonshot-ai/kimi-inspect"
+  ],
+  "snapshot": {
+    "useCalculatedVersion": true,
+    "prereleaseTemplate": "{tag}-{commit}"
+  }
+}

.changeset/diff-fence-palette-colors.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Highlight diff code blocks.

.changeset/fix-steer-message-duplicates.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Fix duplicate user messages when steering an ongoing conversation.

.changeset/fix-steered-file-attachments-reload.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Fix files attached while steering an ongoing conversation appearing only after a reload.

.changeset/fix-steered-slash-command-missing.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Fix slash commands sent while steering an ongoing conversation missing from the transcript.

.changeset/fix-undo-transcript.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Fix missing and reappearing chat messages after undoing a steered message.

.changeset/fix-usage-sessionless-message.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Fix /usage showing a wrong error message when no session has been created yet.

.changeset/kimi-image-upload-references.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Images sent to Kimi models are uploaded as file references instead of inline data, and a warning is shown when media are dropped from a retried request.

.changeset/lazy-subagent-scope-eviction.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Limit memory growth from finished subagents.

.changeset/manager-stopped-subagents-report-cancelled.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Report background subagents that time out or are stopped as cancelled instead of failed.

.changeset/media-request-budget.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+When accumulated images and videos exceed the request size budget, the oldest media are omitted from requests with a warning instead of failing.

.changeset/propagate-user-cancellation-to-tools.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Report tools and subagents interrupted by the user as cancelled instead of aborted or failed.

.changeset/rename-webbridge-display-name.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+The built-in browser plugin now appears as "Kimi Browser Extension" in the plugins panel, marketplace catalog, and docs, matching the product rename.

.changeset/survey-kfc-model-id.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Feedback surveys now appear at better times in long conversations.

.changeset/tower-rework-subagent-card.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Fix tower worker cards wrongly showing "completed" during rework.

.changeset/windows-short-path-watch.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Fix a Windows crash when a project or config folder is opened through a short 8.3 path.

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

.gitattributes

@@ -1,35 +1,10 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+# Enforce LF line endings in the working tree on every platform so that
+# raw-imported text (e.g. `*.md?raw` templates) is byte-identical on Windows
+# and POSIX. Without this, Git for Windows' default `core.autocrlf=true`
+# checks text files out as CRLF, which shifts token-count snapshots.
+* text=auto eol=lf
+
+# Binary assets — never normalize line endings.
+*.gif binary
+*.ico binary
+*.png binary

.gitignore

@@ -0,0 +1,45 @@
+node_modules/
+dist/
+dist-single/
+dist-native/
+.tmp-api-extractor/
+.contract-types-tmp/
+.local/
+coverage/
+*.tsbuildinfo
+.vitest-results/
+.vite/
+.DS_Store
+.playwright-mcp/
+.claude
+.conductor
+.kimi-stash-dir
+plugins/cdn/
+.worktrees/
+.kimi-code/local.toml
+.kimi-sandbox/
+.vscode/
+!apps/vscode/.vscode/
+!apps/vscode/.vscode/*.json
+apps/vscode/artifacts/
+
+Dockerfile
+docker-compose.yml
+.dockerignore
+
+docs/superpowers/
+reports/
+.superpowers/
+/plan/
+
+# Agent scratch / throwaway files - do not commit
+.tmp/
+HANDOVER*.md
+HANDOFF*.md
+handoff.md
+handover.md
+*-designs.html
+*-design.html
+*-mockup.html
+*-demo.html
+*-demos.html

.husky/install.mjs

@@ -0,0 +1,18 @@
+import { existsSync } from 'node:fs';
+
+if (
+  process.env.NODE_ENV === 'production' ||
+  process.env.CI === 'true' ||
+  process.env.npm_config_production === 'true' ||
+  !existsSync('.git')
+) {
+  process.exit(0);
+}
+
+try {
+  const husky = (await import('husky')).default;
+  console.log(husky());
+} catch (error) {
+  if (error && error.code === 'ERR_MODULE_NOT_FOUND') process.exit(0);
+  throw error;
+}

.husky/pre-commit

@@ -0,0 +1,4 @@
+set -e
+
+node scripts/check-no-comments.mjs
+pnpm lint-staged

.npmrc

@@ -0,0 +1,3 @@
+auto-install-peers=true
+engine-strict=true
+strict-peer-dependencies=false

.nvmrc

@@ -0,0 +1 @@
+24.15.0

.oxfmtrc.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "endOfLine": "lf",
+  "sortImports": {
+    "groups": ["builtin", "external", "internal", ["parent", "sibling", "index"], "unknown"],
+    "newlinesBetween": true,
+    "order": "asc"
+  },
+  "sortPackageJson": true,
+  "ignorePatterns": ["dist/", "coverage/", "pnpm-lock.yaml", "*.generated.ts"]
+}

.oxlintrc.json

@@ -0,0 +1,181 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "categories": {
+    "correctness": "error",
+    "suspicious": "warn",
+    "pedantic": "warn",
+    "perf": "warn"
+  },
+  "plugins": ["typescript", "import", "unicorn", "promise", "node"],
+  "rules": {
+    "eslint/no-useless-return": "off",
+    "eslint/no-shadow": "off",
+    "eslint/eqeqeq": "error",
+    "eslint/no-throw-literal": "off",
+    "eslint/no-control-regex": "off",
+    "typescript/no-misused-promises": "error",
+    "typescript/return-await": "error",
+    "typescript/only-throw-error": "error",
+    "import/no-cycle": "error",
+    "import/no-self-import": "error",
+    "import/no-unassigned-import": "off",
+    "unicorn/prefer-node-protocol": "error",
+    "unicorn/no-useless-undefined": "off",
+    "unicorn/no-lonely-if": "off",
+    "unicorn/no-array-callback-reference": "off",
+    "typescript/prefer-promise-reject-errors": "off",
+    "typescript/no-unsafe-function-type": "off",
+    "typescript/no-unsafe-argument": "off",
+    "typescript/no-unsafe-assignment": "off",
+    "typescript/no-unsafe-call": "off",
+    "typescript/no-unsafe-member-access": "off",
+    "typescript/no-unsafe-return": "off",
+
+    "eslint/no-console": "warn",
+    "typescript/no-explicit-any": "off",
+    "typescript/no-non-null-assertion": "off",
+    "typescript/use-unknown-in-catch-callback-variable": "off",
+    "typescript/consistent-type-imports": "off",
+    "typescript/ban-types": "off",
+    "import/first": "warn",
+    "import/extensions": [
+      "error",
+      "ignorePackages",
+      {
+        "js": "never",
+        "ts": "never",
+        "tsx": "never"
+      }
+    ],
+    "import/no-duplicates": "warn",
+    "import/no-mutable-exports": "warn",
+    "unicorn/error-message": "warn",
+    "unicorn/throw-new-error": "warn",
+    "unicorn/catch-error-name": "warn",
+    "unicorn/prefer-add-event-listener": "off",
+    "node/no-new-require": "warn",
+    "node/no-path-concat": "warn",
+
+    "promise/no-callback-in-promise": "warn",
+    "promise/valid-params": "warn",
+    "promise/no-return-in-finally": "warn",
+    "promise/always-return": "off",
+
+    "eslint/max-classes-per-file": "off",
+    "eslint/max-depth": "off",
+    "eslint/max-lines": "off",
+    "eslint/max-lines-per-function": "off",
+    "eslint/max-nested-callbacks": "off",
+    "eslint/no-warning-comments": "off",
+    "eslint/no-inline-comments": "off",
+    "eslint/no-negated-condition": "off",
+    "eslint/no-await-in-loop": "off",
+    "eslint/require-await": "off",
+    "typescript/require-await": "off",
+    "eslint/sort-vars": "off",
+    "eslint/radix": "off",
+    "eslint/symbol-description": "off",
+    "typescript/consistent-return": "off",
+    "unicorn/consistent-function-scoping": "off",
+    "typescript/no-deprecated": "off",
+    "typescript/no-unsafe-type-assertion": "off",
+    "typescript/strict-boolean-expressions": "off",
+    "typescript/no-duplicate-type-constituents": "off",
+    "import/max-dependencies": "off"
+  },
+  "overrides": [
+    {
+      "files": ["**/examples/**/*.ts", "**/examples/**/*.tsx"],
+      "rules": {
+        "eslint/no-console": "off"
+      }
+    },
+    {
+      // The worker closures: these modules (and everything
+      // packages/minidb/src/worker/ and
+      // packages/kap-server/src/search/worker/ pull in) are loaded by a bare
+      // node:worker_threads Worker under Node's native type stripping with
+      // `execArgv: ['--experimental-transform-types']`, which requires
+      // explicit `.ts` import specifiers (the strip loader does not remap
+      // `.js` -> `.ts`). Keep the exception scoped to exactly those closures.
+      "files": [
+        "packages/minidb/src/worker/**/*.ts",
+        "packages/minidb/src/codec.ts",
+        "packages/minidb/src/crc32.ts",
+        "packages/minidb/src/trigram.ts",
+        "packages/minidb/src/text-postings.ts",
+        "packages/minidb/src/text-index/tokenize.ts",
+        "packages/minidb/src/gen-codec.ts",
+        "packages/kap-server/src/search/worker/**/*.ts",
+        "packages/kap-server/src/search/indexCore.ts",
+        "packages/kap-server/src/search/match.ts"
+      ],
+      "rules": {
+        "import/extensions": "off"
+      }
+    },
+    {
+      "files": ["packages/kosong/src/providers/**/*.ts"],
+      "rules": {
+        "typescript/no-unsafe-argument": "off",
+        "typescript/no-unsafe-assignment": "off",
+        "typescript/no-unsafe-call": "off",
+        "typescript/no-unsafe-member-access": "off",
+        "typescript/no-unsafe-return": "off"
+      }
+    },
+    {
+      "files": [
+        "**/*.test.ts",
+        "**/*.test.tsx",
+        "**/*.spec.ts",
+        "**/*.spec.tsx",
+        "**/test/**/*.ts",
+        "**/test/**/*.tsx"
+      ],
+      "plugins": ["vitest"],
+      "rules": {
+        "typescript/no-explicit-any": "off",
+        "typescript/no-unsafe-assignment": "off",
+        "typescript/no-unsafe-argument": "off",
+        "typescript/no-non-null-assertion": "off",
+        "typescript/unbound-method": "off",
+        "typescript/no-redundant-type-constituents": "off",
+        "eslint/no-console": "off",
+        "eslint/no-promise-executor-return": "off",
+        "typescript/no-unsafe-member-access": "off",
+        "vitest/require-mock-type-parameters": "off",
+        "eslint/no-shadow": "off",
+        "unicorn/prefer-event-target": "off",
+        "jest/no-disabled-tests": "off",
+        "vitest/no-disabled-tests": "off",
+        "eslint/no-control-regex": "off",
+        "eslint/no-unused-vars": "off",
+        "eslint/no-unsafe-optional-chaining": "off",
+        "jest/valid-expect": "off",
+        "unicorn/no-useless-spread": "off",
+        "import/no-cycle": "off",
+        "typescript/no-meaningless-void-operator": "off",
+        "typescript/require-array-sort-compare": "off",
+        "vitest/expect-expect": "error",
+        "vitest/no-conditional-tests": "error",
+        "vitest/no-focused-tests": "error",
+        "vitest/no-identical-title": "error",
+        "vitest/valid-expect": "off",
+        "vitest/valid-describe-callback": "error",
+        "vitest/no-standalone-expect": "error",
+        "vitest/warn-todo": "off"
+      }
+    }
+  ],
+  "ignorePatterns": [
+    "dist/",
+    "dist-web/",
+    "coverage/",
+    "node_modules/",
+    "apps/*/scripts/",
+    "docs/smoke-archive/",
+    "packages/pi-tui/",
+    "*.generated.ts"
+  ]
+}

AGENTS.md

@@ -0,0 +1,93 @@
+# Repository-level Agent Guide
+
+Reply in the same language as the user.
+
+This is a TypeScript monorepo built for agent-assisted development. Keep the root `AGENTS.md` limited to hot-path rules: the project map, hard constraints, and workflow requirements — things every task needs to know.
+
+## Working Principles
+
+- Think from first principles. Start from real requirements, code facts, and verification results; if the goal is unclear, discuss it with the user first.
+- Treat code, not documentation, as the source of truth. Unless the user explicitly says otherwise, do not read ordinary Markdown just to understand the implementation.
+- Before making code changes, read the relevant code and the most recent constraints, and follow the nearest `AGENTS.md` in the directory tree.
+- Keep changes focused. Do not slip in unrelated refactors along the way.
+- When committing, do not add any co-author attribution, and do not reveal the identity of the agent in commit messages, PR descriptions, or any explanatory text.
+
+## Project Map
+
+- `apps/kimi-code`: the CLI / TUI application. It consumes core capabilities through `@moonshot-ai/kimi-code-sdk` and must not depend directly on engine packages. When writing or modifying its terminal UI, use the `write-tui` skill (`.agents/skills/write-tui/SKILL.md`).
+- the browser web UI: **its source no longer lives in this repo.** It is developed in the code-app repo (`apps/web`) and shipped as the committed, prebuilt bundle `apps/kimi-code/dist-web` (gitignored, force-added), synced from code-app with `KIMI_CODE_REPO=<this checkout> pnpm run sync:web` — sync and commit the bundle in the same change whenever the web UI should ship differently. `apps/kimi-code/scripts/check-web-assets.mjs` guards packaging against a missing bundle. To hack on the web UI against this repo's server, run `pnpm dev:server` here and point code-app's `pnpm dev:web` at it via `KIMI_SERVER_URL`.
+- `apps/vis`, `apps/vis/server`, `apps/vis/web`: visual debugging tools for sessions and replays.
+- `apps/kimi-inspect`: web inspector for the kap-server `/api/v1/debug` RPC surface — workspace/session browser, per-session transcript chat, per-scope Service panels, and the DI unit inspection view. See `apps/kimi-inspect/AGENTS.md`.
+- `packages/agent-core-v2`: the DI × Scope agent engine (the v2 port behind kap-server). Four `LifecycleScope` tiers — `App` / `Workspace` / `Session` / `Agent` (`app/scopes.ts`) — plus the L3 unit layer (`Service`/`Fiber` units, collection contribution points, the Feature seam in `src/features/`); there is no App-level session lifecycle facade — callers compose `ISessionIndex` → `IWorkspaceLifecycleService.handlerFor` → the handler.
+- `packages/node-sdk`: the public TypeScript SDK and harness.
+- `packages/kosong`: the LLM / provider abstraction layer.
+- `packages/kaos`: the execution environment and file/process abstractions.
+- `packages/oauth`: Kimi OAuth and managed auth utilities.
+- `packages/telemetry`: shared client-side telemetry infrastructure.
+- `packages/transcript`: the isomorphic transcript rendering data layer — L1 agent-granular store, L2 idempotent operations, L3 `off/turn/block/delta` subscription granularity, L4 framework-free view registry, plus turn-cursor pagination. Pure TypeScript (browser-safe, no engine imports); the sole owner of the transcript contract types (`src/contract/`) and the op-batch sequencing contract.
+- `packages/kap-server`: the Kimi Code server, backed by `@moonshot-ai/agent-core-v2`; exposes sessions over REST + WebSocket (`/api/v1` + `/api/v1/ws`), plus the `/api/v1/debug/*` reflection RPC surface (`--debug-endpoints`, loopback bind + bearer auth).
+- `packages/remote-control`: the Kimi Remote Control tunnel client — registers this machine with the relay and forwards HTTP/WebSocket traffic to the local server, with a machine-wide single-instance lock; consumed by kap-server (the `/api/v1/remote-control` toggle) and by the CLI (`kimi web --remote-control`).
+- `packages/klient`: the client SDK — a contract-driven facade over agent-core-v2 (`global.*` / `session(id).*` / `agent(id).*`, zod-validated); transport via subpath entry (`@moonshot-ai/klient/ipc|memory`, both return the same `Klient`); also hosts the e2e suites. See `packages/klient/AGENTS.md`.
+- `packages/tree-sitter-bash`: a pure-TypeScript bash parser (no runtime deps, no wasm); `parse(source, { timeoutMs, maxNodes })` runs under a deterministic budget and returns a discriminated `ParseResult` — callers must treat aborted/hasError trees as "cannot analyze" and degrade. Parser only, no safety judgments; see the package README's "Known differences" section.
+- `packages/minidb`: the embedded JSON document store (`MiniDb`) behind kap-server's search index — snapshot + WAL persistence with an exclusive write lock, a larger-than-RAM full-text layer, and persistent index generations. See `packages/minidb/AGENTS.md`.
+
+## Environment Requirements
+
+- **Node.js**: `>=24.15.0` (from the root `package.json` `engines`; `.nvmrc` is `24.15.0`, used by nvm / fnm / mise to pick the minimum recommended version).
+- **pnpm**: `10.33.0` (from the root `package.json` `packageManager`).
+- `pnpm install` will fail when the Node version is not satisfied, because `.npmrc` sets `engine-strict=true`.
+
+## Monorepo Workspace Maintenance
+
+- `pnpm-workspace.yaml` is the source of truth for workspace membership, but `flake.nix` also contains **hardcoded** `workspacePaths` and `workspaceNames` lists.
+- **Whenever you add or remove a workspace package, you MUST update both `pnpm-workspace.yaml` and `flake.nix` — for every package, including leaf / test / e2e packages that nothing depends on.**
+  - `pnpm-workspace.yaml` uses globs (`packages/*`, `apps/*`), so most packages land there automatically; `flake.nix` is fully manual and is where omissions happen.
+  - Missing a path in `flake.nix`'s `workspacePaths` will silently drop files from the Nix build's `src` fileset.
+  - Missing a name in `flake.nix`'s `workspaceNames` will break `pnpmConfigHook` because dependencies for that workspace will not be fetched.
+- The automated "Check flake.nix workspace sync" (`scripts/check-nix-workspace.mjs`) only validates the transitive dependency **closure of `@moonshot-ai/kimi-code`**. A leaf package outside that closure (e.g. an e2e package nobody imports) slips through even when it is missing from `flake.nix`. A green check is therefore NOT proof that `flake.nix` is fully in sync — keep it updated by hand on every add/remove, do not rely on the check to catch omissions.
+
+## General Coding Rules
+
+- `packages/agent-core-v2`, `packages/kap-server`, and `packages/transcript` are comment-free zones: no comments of any kind — no line/block comments, no JSDoc (not even on exported symbols); the only exception is load-bearing lint-suppression directives (`oxlint-disable` / `eslint-disable`), while other tooling directives (`@ts-expect-error`, …) stay banned. Enforced by `scripts/check-no-comments.mjs` over `.ts`/`.tsx`/`.mts`/`.mjs` under `src/`/`test/`/`scripts/`, which runs as part of `pnpm lint`.
+- For optional object properties, pass `undefined` directly instead of using conditional spread.
+  - YES: `{ user }`
+  - NO: `{ ...(user ? { user } : undefined) }`
+- Optional object properties do not need to additionally allow `undefined` in the type.
+  - YES: `interface Options { user?: User }`
+  - NO: `interface Options { user?: User | undefined }`
+- Internal methods with only a single parameter should not be turned into options objects just for stylistic uniformity.
+- Split functions only along abstraction levels: each function reads as one level of narrative (Step-down Rule), and a wrapper that adds no new abstraction level — especially one with a single call site — is inlined instead of extracted.
+- Except for a package's `index.ts`, other `index.ts` files should prefer `export * from './module';`.
+- When writing or updating tests, follow the `tdd` skill (`.agents/skills/tdd/SKILL.md`).
+- Do not add too many new test files. Prefer adding tests to the existing test file of the corresponding component or module.
+- When a test fails because of a user modification, default to fixing the test first; do not change the implementation to satisfy an old test unless the implementation truly has a bug.
+- Do not sacrifice code quality for external compatibility unless the user explicitly asks for it. Breaking changes go through changesets and a `major` bump, gated by the rule below.
+
+## Experimental Features
+
+- Gate a not-yet-public feature behind an experimental flag. Flags are env-driven and default off: `KIMI_CODE_EXPERIMENTAL_<NAME>` toggles one, `KIMI_CODE_EXPERIMENTAL_FLAG` enables all. Precedence is per-flag env > `[experimental]` config > master env > the flag's `default`. Release by flipping the entry's `default` to `true`.
+  - `packages/agent-core-v2` and kap-server modules: there is no central catalog — declare the flag in the owning domain via `registerFlagDefinition` at import time, then check it with `IFlagService.enabled(id)`.
+
+## Where to Update Instructions
+
+- Hard rules that affect almost every task: update the root `AGENTS.md`.
+- Rules that only affect a specific directory: update the nearest sub-directory `AGENTS.md`.
+- Project-map entries stay at 1–2 sentences; deep package docs live in the package's own `AGENTS.md`.
+- Keep instruction updates focused and supported by code facts.
+
+## Workflow Requirements
+
+- Prefer `rg` / `rg --files` when reading code.
+- When designing changes, follow existing boundaries and local patterns first.
+- In public text and test data, replace real internal identifiers with neutral placeholders such as `example.com`, `example.test`, and `YOUR_API_KEY`. Before opening a PR, ask a read-only agent to audit the diff for context-specific internal identifiers.
+- When creating a PR, the PR title must follow Conventional Commit style, e.g. `chore: remove legacy format commands`.
+- When an AI agent opens or updates a PR, fill in `.github/pull_request_template.md` — link the related issue or explain the problem, then describe what changed. Do not leave placeholder text or submit a generic summary of the diff.
+- Do not submit vague AI-generated PR text. The human author must understand the change well enough to explain the code, edge cases, and why the approach fits this repository.
+- After finishing a task and before submitting a PR, you must run the `gen-changesets` skill (see `.agents/skills/gen-changesets/SKILL.md`) and generate a changeset under `.changeset/` according to its rules.
+- Changesets must strictly follow the rules in `.agents/skills/gen-changesets/SKILL.md`: write one short user-facing sentence that states only what changed, and skip any change users cannot perceive.
+- When generating a changeset, **never** decide on a `major` bump on your own — stop, explain, and get explicit user confirmation first; default to `minor`, fall back to `patch`. See `.agents/skills/gen-changesets/SKILL.md`.
+- Prefer importing via `import ... from '#/...'`, which serves the same purpose as `import ... from '@/...'`.
+- Do not commit throwaway scratch or exploratory files. Never stage:
+  - Agent working notes or handoff/summary documents (e.g. `HANDOVER-*.md`, `HANDOFF-*.md`, `handoff.md`).
+  - Throwaway UI/UX prototypes or design mockups (e.g. `*-designs.html`, `*-mockup.html`, `*-demo(s).html`) at the repo root or under a `design/` folder. The only tracked `.html` files should be Vite `index.html` entrypoints.
+  Before committing or opening a PR, run `git status` and `git diff --staged --stat` and remove anything matching these patterns. Put scratch work under `.tmp/` (gitignored) instead of the repo root or the source tree.

CLAUDE.md

@@ -0,0 +1,93 @@
+# Repository-level Agent Guide
+
+Reply in the same language as the user.
+
+This is a TypeScript monorepo built for agent-assisted development. Keep the root `AGENTS.md` limited to hot-path rules: the project map, hard constraints, and workflow requirements — things every task needs to know.
+
+## Working Principles
+
+- Think from first principles. Start from real requirements, code facts, and verification results; if the goal is unclear, discuss it with the user first.
+- Treat code, not documentation, as the source of truth. Unless the user explicitly says otherwise, do not read ordinary Markdown just to understand the implementation.
+- Before making code changes, read the relevant code and the most recent constraints, and follow the nearest `AGENTS.md` in the directory tree.
+- Keep changes focused. Do not slip in unrelated refactors along the way.
+- When committing, do not add any co-author attribution, and do not reveal the identity of the agent in commit messages, PR descriptions, or any explanatory text.
+
+## Project Map
+
+- `apps/kimi-code`: the CLI / TUI application. It consumes core capabilities through `@moonshot-ai/kimi-code-sdk` and must not depend directly on engine packages. When writing or modifying its terminal UI, use the `write-tui` skill (`.agents/skills/write-tui/SKILL.md`).
+- the browser web UI: **its source no longer lives in this repo.** It is developed in the code-app repo (`apps/web`) and shipped as the committed, prebuilt bundle `apps/kimi-code/dist-web` (gitignored, force-added), synced from code-app with `KIMI_CODE_REPO=<this checkout> pnpm run sync:web` — sync and commit the bundle in the same change whenever the web UI should ship differently. `apps/kimi-code/scripts/check-web-assets.mjs` guards packaging against a missing bundle. To hack on the web UI against this repo's server, run `pnpm dev:server` here and point code-app's `pnpm dev:web` at it via `KIMI_SERVER_URL`.
+- `apps/vis`, `apps/vis/server`, `apps/vis/web`: visual debugging tools for sessions and replays.
+- `apps/kimi-inspect`: web inspector for the kap-server `/api/v1/debug` RPC surface — workspace/session browser, per-session transcript chat, per-scope Service panels, and the DI unit inspection view. See `apps/kimi-inspect/AGENTS.md`.
+- `packages/agent-core-v2`: the DI × Scope agent engine (the v2 port behind kap-server). Four `LifecycleScope` tiers — `App` / `Workspace` / `Session` / `Agent` (`app/scopes.ts`) — plus the L3 unit layer (`Service`/`Fiber` units, collection contribution points, the Feature seam in `src/features/`); there is no App-level session lifecycle facade — callers compose `ISessionIndex` → `IWorkspaceLifecycleService.handlerFor` → the handler.
+- `packages/node-sdk`: the public TypeScript SDK and harness.
+- `packages/kosong`: the LLM / provider abstraction layer.
+- `packages/kaos`: the execution environment and file/process abstractions.
+- `packages/oauth`: Kimi OAuth and managed auth utilities.
+- `packages/telemetry`: shared client-side telemetry infrastructure.
+- `packages/transcript`: the isomorphic transcript rendering data layer — L1 agent-granular store, L2 idempotent operations, L3 `off/turn/block/delta` subscription granularity, L4 framework-free view registry, plus turn-cursor pagination. Pure TypeScript (browser-safe, no engine imports); the sole owner of the transcript contract types (`src/contract/`) and the op-batch sequencing contract.
+- `packages/kap-server`: the Kimi Code server, backed by `@moonshot-ai/agent-core-v2`; exposes sessions over REST + WebSocket (`/api/v1` + `/api/v1/ws`), plus the `/api/v1/debug/*` reflection RPC surface (`--debug-endpoints`, loopback bind + bearer auth).
+- `packages/remote-control`: the Kimi Remote Control tunnel client — registers this machine with the relay and forwards HTTP/WebSocket traffic to the local server, with a machine-wide single-instance lock; consumed by kap-server (the `/api/v1/remote-control` toggle) and by the CLI (`kimi web --remote-control`).
+- `packages/klient`: the client SDK — a contract-driven facade over agent-core-v2 (`global.*` / `session(id).*` / `agent(id).*`, zod-validated); transport via subpath entry (`@moonshot-ai/klient/ipc|memory`, both return the same `Klient`); also hosts the e2e suites. See `packages/klient/AGENTS.md`.
+- `packages/tree-sitter-bash`: a pure-TypeScript bash parser (no runtime deps, no wasm); `parse(source, { timeoutMs, maxNodes })` runs under a deterministic budget and returns a discriminated `ParseResult` — callers must treat aborted/hasError trees as "cannot analyze" and degrade. Parser only, no safety judgments; see the package README's "Known differences" section.
+- `packages/minidb`: the embedded JSON document store (`MiniDb`) behind kap-server's search index — snapshot + WAL persistence with an exclusive write lock, a larger-than-RAM full-text layer, and persistent index generations. See `packages/minidb/AGENTS.md`.
+
+## Environment Requirements
+
+- **Node.js**: `>=24.15.0` (from the root `package.json` `engines`; `.nvmrc` is `24.15.0`, used by nvm / fnm / mise to pick the minimum recommended version).
+- **pnpm**: `10.33.0` (from the root `package.json` `packageManager`).
+- `pnpm install` will fail when the Node version is not satisfied, because `.npmrc` sets `engine-strict=true`.
+
+## Monorepo Workspace Maintenance
+
+- `pnpm-workspace.yaml` is the source of truth for workspace membership, but `flake.nix` also contains **hardcoded** `workspacePaths` and `workspaceNames` lists.
+- **Whenever you add or remove a workspace package, you MUST update both `pnpm-workspace.yaml` and `flake.nix` — for every package, including leaf / test / e2e packages that nothing depends on.**
+  - `pnpm-workspace.yaml` uses globs (`packages/*`, `apps/*`), so most packages land there automatically; `flake.nix` is fully manual and is where omissions happen.
+  - Missing a path in `flake.nix`'s `workspacePaths` will silently drop files from the Nix build's `src` fileset.
+  - Missing a name in `flake.nix`'s `workspaceNames` will break `pnpmConfigHook` because dependencies for that workspace will not be fetched.
+- The automated "Check flake.nix workspace sync" (`scripts/check-nix-workspace.mjs`) only validates the transitive dependency **closure of `@moonshot-ai/kimi-code`**. A leaf package outside that closure (e.g. an e2e package nobody imports) slips through even when it is missing from `flake.nix`. A green check is therefore NOT proof that `flake.nix` is fully in sync — keep it updated by hand on every add/remove, do not rely on the check to catch omissions.
+
+## General Coding Rules
+
+- `packages/agent-core-v2`, `packages/kap-server`, and `packages/transcript` are comment-free zones: no comments of any kind — no line/block comments, no JSDoc (not even on exported symbols); the only exception is load-bearing lint-suppression directives (`oxlint-disable` / `eslint-disable`), while other tooling directives (`@ts-expect-error`, …) stay banned. Enforced by `scripts/check-no-comments.mjs` over `.ts`/`.tsx`/`.mts`/`.mjs` under `src/`/`test/`/`scripts/`, which runs as part of `pnpm lint`.
+- For optional object properties, pass `undefined` directly instead of using conditional spread.
+  - YES: `{ user }`
+  - NO: `{ ...(user ? { user } : undefined) }`
+- Optional object properties do not need to additionally allow `undefined` in the type.
+  - YES: `interface Options { user?: User }`
+  - NO: `interface Options { user?: User | undefined }`
+- Internal methods with only a single parameter should not be turned into options objects just for stylistic uniformity.
+- Split functions only along abstraction levels: each function reads as one level of narrative (Step-down Rule), and a wrapper that adds no new abstraction level — especially one with a single call site — is inlined instead of extracted.
+- Except for a package's `index.ts`, other `index.ts` files should prefer `export * from './module';`.
+- When writing or updating tests, follow the `tdd` skill (`.agents/skills/tdd/SKILL.md`).
+- Do not add too many new test files. Prefer adding tests to the existing test file of the corresponding component or module.
+- When a test fails because of a user modification, default to fixing the test first; do not change the implementation to satisfy an old test unless the implementation truly has a bug.
+- Do not sacrifice code quality for external compatibility unless the user explicitly asks for it. Breaking changes go through changesets and a `major` bump, gated by the rule below.
+
+## Experimental Features
+
+- Gate a not-yet-public feature behind an experimental flag. Flags are env-driven and default off: `KIMI_CODE_EXPERIMENTAL_<NAME>` toggles one, `KIMI_CODE_EXPERIMENTAL_FLAG` enables all. Precedence is per-flag env > `[experimental]` config > master env > the flag's `default`. Release by flipping the entry's `default` to `true`.
+  - `packages/agent-core-v2` and kap-server modules: there is no central catalog — declare the flag in the owning domain via `registerFlagDefinition` at import time, then check it with `IFlagService.enabled(id)`.
+
+## Where to Update Instructions
+
+- Hard rules that affect almost every task: update the root `AGENTS.md`.
+- Rules that only affect a specific directory: update the nearest sub-directory `AGENTS.md`.
+- Project-map entries stay at 1–2 sentences; deep package docs live in the package's own `AGENTS.md`.
+- Keep instruction updates focused and supported by code facts.
+
+## Workflow Requirements
+
+- Prefer `rg` / `rg --files` when reading code.
+- When designing changes, follow existing boundaries and local patterns first.
+- In public text and test data, replace real internal identifiers with neutral placeholders such as `example.com`, `example.test`, and `YOUR_API_KEY`. Before opening a PR, ask a read-only agent to audit the diff for context-specific internal identifiers.
+- When creating a PR, the PR title must follow Conventional Commit style, e.g. `chore: remove legacy format commands`.
+- When an AI agent opens or updates a PR, fill in `.github/pull_request_template.md` — link the related issue or explain the problem, then describe what changed. Do not leave placeholder text or submit a generic summary of the diff.
+- Do not submit vague AI-generated PR text. The human author must understand the change well enough to explain the code, edge cases, and why the approach fits this repository.
+- After finishing a task and before submitting a PR, you must run the `gen-changesets` skill (see `.agents/skills/gen-changesets/SKILL.md`) and generate a changeset under `.changeset/` according to its rules.
+- Changesets must strictly follow the rules in `.agents/skills/gen-changesets/SKILL.md`: write one short user-facing sentence that states only what changed, and skip any change users cannot perceive.
+- When generating a changeset, **never** decide on a `major` bump on your own — stop, explain, and get explicit user confirmation first; default to `minor`, fall back to `patch`. See `.agents/skills/gen-changesets/SKILL.md`.
+- Prefer importing via `import ... from '#/...'`, which serves the same purpose as `import ... from '@/...'`.
+- Do not commit throwaway scratch or exploratory files. Never stage:
+  - Agent working notes or handoff/summary documents (e.g. `HANDOVER-*.md`, `HANDOFF-*.md`, `handoff.md`).
+  - Throwaway UI/UX prototypes or design mockups (e.g. `*-designs.html`, `*-mockup.html`, `*-demo(s).html`) at the repo root or under a `design/` folder. The only tracked `.html` files should be Vite `index.html` entrypoints.
+  Before committing or opening a PR, run `git status` and `git diff --staged --stat` and remove anything matching these patterns. Put scratch work under `.tmp/` (gitignored) instead of the repo root or the source tree.

CONTRIBUTING.md

@@ -0,0 +1,102 @@
+# Contributing to kimi-code
+
+[中文版](CONTRIBUTING.zh-CN.md)
+
+Thanks for taking the time to contribute! This project moves quickly, and thoughtful contributions from the community are what keep it sharp. The guide below walks you through how we work so your PR has the best chance of landing smoothly.
+
+## Before You Start
+
+Kimi Code already has opinions on CLI/TUI behavior, agent workflows, and public APIs. If your change shifts that direction, open an issue first so we can align before you invest time in a PR.
+
+We hold AI-assisted contributions to the same standard as hand-written ones. **You should understand what you submit** — what changed, how it behaves at the edges, and why it fits this codebase. If you cannot explain that, the PR is not ready for review.
+
+We only merge PRs aligned with the roadmap. Drive-by refactors without context are unlikely to land.
+
+**External PRs are accepted for approved bug fixes only.** Open an issue first and wait for a maintainer to approve it with an `/approve` comment, then link that issue in your PR. PRs without an approved linked issue may be closed without review; once the issue is approved, ask a maintainer to reopen your PR.
+
+**Discuss first** — open an issue before coding:
+
+- Bug fixes, including small or typo-level ones: open a bug issue and wait for a maintainer's `/approve` before opening the PR
+- New features or user-visible behavior changes (regardless of size): external feature PRs are not accepted — features are discussed and decided in issues, and accepted features are implemented by the team or by explicit maintainer invitation
+- Refactors or other changes larger than ~100 lines
+- Public API or compatibility changes
+
+## Project Layout
+
+This is a pnpm monorepo. The most relevant entry points are:
+
+- `apps/kimi-code` — CLI / TUI
+- `apps/vscode` — VS Code extension
+- `apps/vis` — session debug visualizer
+- `packages/node-sdk` — public TypeScript SDK (`@moonshot-ai/kimi-code-sdk`)
+- `packages/agent-core-v2` — the agent engine (v2, DI Scope architecture); `packages/agent-core` is v1 and being phased out
+- `packages/klient`, `kap-server`, `protocol`, `transcript`, `kosong`, `kaos`, `oauth`, `telemetry` — internal engine packages
+- `docs/` — VitePress bilingual docs site
+
+For the full project map, see [AGENTS.md](AGENTS.md).
+
+## Development Setup
+
+Prerequisites: Node.js >= 24.15.0, pnpm 10.33.0, Git.
+
+```sh
+git clone https://github.com/MoonshotAI/kimi-code.git
+cd kimi-code
+pnpm install
+```
+
+Useful scripts:
+
+- `pnpm dev:cli` — run the CLI in dev mode
+- `pnpm test` — run tests (vitest)
+- `pnpm typecheck` — TypeScript check (note: builds packages first)
+- `pnpm lint` — oxlint
+- `pnpm lint:fix` — oxlint with auto-fix
+- `pnpm build` — build all packages
+
+## Commit Convention
+
+All commits and PR titles must follow [Conventional Commits](https://www.conventionalcommits.org/).
+
+| Type     | Use for                                     | Example                                   |
+|----------|---------------------------------------------|-------------------------------------------|
+| feat     | A new feature                               | feat(agent-core-v2): add tool dedup       |
+| fix      | A bug fix                                   | fix(tui): correct status bar alignment    |
+| docs     | Documentation only                          | docs: clarify install instructions        |
+| chore    | Tooling / housekeeping                      | chore: bump dependencies                  |
+| refactor | Internal refactor without behavior change   | refactor(kosong): extract retry helper    |
+| test     | Adding or improving tests                   | test(agent-core-v2): cover skill resolver |
+| ci       | CI / build pipeline changes                 | ci: cache pnpm store                      |
+| build    | Build system / artifact changes             | build(native): add win32-arm64 target     |
+| perf     | Performance improvement                     | perf(session): batch event flushes        |
+| style    | Formatting only (no logic)                  | style: apply oxlint --fix                 |
+
+PR titles are enforced by the `pr-title-checker` workflow — a non-conforming title will block merge.
+
+## Changesets
+
+This repo uses [changesets](https://github.com/changesets/changesets) to manage versioning and releases.
+
+- Every PR that affects release artifacts (code, behavior, public API) **must** include a changeset.
+- Docs-only, test-only, or CI-only PRs may skip changesets.
+- Generate one with `pnpm changeset` and follow the prompts (which packages are touched, which bump level).
+- For repo-specific conventions on package selection and bump levels, see `.changeset/README.md`. When working in this repo with coding agents, use the `gen-changesets` skill.
+
+## Pull Requests
+
+Every PR opens with the [PR template](.github/pull_request_template.md). PR titles must follow [Conventional Commits](#commit-convention); CI runs `pnpm lint`, `pnpm typecheck`, and `pnpm test` on every PR. Update user-facing docs in `docs/` when behavior changes — use the `gen-docs` skill when working with coding agents.
+
+## Code Style
+
+- TypeScript across the codebase.
+- Linting via `oxlint` (config in `.oxlintrc.json`).
+- Auto-formatting via `pnpm lint:fix`.
+- Follow existing local patterns when the lint rules do not cover a style choice.
+
+## Reporting Security Issues
+
+Found a security issue? Please see [SECURITY.md](SECURITY.md) instead of opening a public issue.
+
+## License
+
+By contributing to this repository, you agree that your contributions will be licensed under the [MIT License](LICENSE).

CONTRIBUTING.zh-CN.md

@@ -0,0 +1,102 @@
+# 为 kimi-code 贡献代码
+
+[English version](CONTRIBUTING.md)
+
+感谢你花时间参与贡献！这个项目迭代很快，离不开社区认真的贡献。下面的指南介绍我们的工作方式，帮助你的 PR 顺利合入。
+
+## 开始之前
+
+Kimi Code 对 CLI/TUI 行为、agent 工作流和公开 API 已有自己的主张。如果你的改动会改变这些方向，请先开 issue 对齐，再投入时间写 PR。
+
+我们对 AI 辅助贡献与手写代码一视同仁。**你应该理解自己提交的内容**——改了什么、边界情况下表现如何、为什么适合这个代码库。如果你解释不清楚，这个 PR 就还没准备好接受评审。
+
+我们只合入与路线图一致的 PR。缺乏上下文背景的顺手重构很难被接受。
+
+**外部 PR 仅接受获批准的 bug 修复。** 先开 issue，等待维护者以 `/approve` 评论明确批准，然后在 PR 中链接该 issue。没有已批准关联 issue 的 PR 可能会不经评审直接关闭；issue 获批后，可联系维护者重开你的 PR。
+
+**先讨论**——写代码前先开 issue：
+
+- bug 修复（包括小的、错别字级别的）：先开 bug issue，等待维护者 `/approve` 后再提 PR
+- 新功能或用户可见的行为变更（无论大小）：不接受外部 feature PR——功能在 issue 中讨论和决定，被接受的功能由团队实现，或由维护者明确邀请你贡献
+- 重构或其他超过约 100 行的改动
+- 公开 API 或兼容性变更
+
+## 项目结构
+
+本仓库是 pnpm monorepo，最常用的入口：
+
+- `apps/kimi-code` — CLI / TUI
+- `apps/vscode` — VS Code 插件
+- `apps/vis` — 会话调试可视化工具
+- `packages/node-sdk` — 公开 TypeScript SDK（`@moonshot-ai/kimi-code-sdk`）
+- `packages/agent-core-v2` — 当前的 agent 引擎（v2，DI Scope 架构）；`packages/agent-core` 为 v1，正在逐步废弃
+- `packages/klient`、`kap-server`、`protocol`、`transcript`、`kosong`、`kaos`、`oauth`、`telemetry` — 内部引擎包
+- `docs/` — VitePress 双语文档站
+
+完整项目地图见 [AGENTS.md](AGENTS.md)。
+
+## 开发环境
+
+前置要求：Node.js >= 24.15.0、pnpm 10.33.0、Git。
+
+```sh
+git clone https://github.com/MoonshotAI/kimi-code.git
+cd kimi-code
+pnpm install
+```
+
+常用脚本：
+
+- `pnpm dev:cli` — 开发模式运行 CLI
+- `pnpm test` — 运行测试（vitest）
+- `pnpm typecheck` — TypeScript 检查（注意：会先构建各包）
+- `pnpm lint` — oxlint
+- `pnpm lint:fix` — oxlint 自动修复
+- `pnpm build` — 构建全部包
+
+## 提交规范
+
+所有 commit 和 PR 标题必须遵循 [Conventional Commits](https://www.conventionalcommits.org/)。
+
+| 类型     | 用途                                     | 示例                                   |
+|----------|------------------------------------------|----------------------------------------|
+| feat     | 新功能                                   | feat(agent-core-v2): add tool dedup       |
+| fix      | bug 修复                                 | fix(tui): correct status bar alignment |
+| docs     | 仅文档                                   | docs: clarify install instructions     |
+| chore    | 工具 / 杂务                              | chore: bump dependencies               |
+| refactor | 无行为变更的内部重构                     | refactor(kosong): extract retry helper |
+| test     | 新增或改进测试                           | test(agent-core-v2): cover skill resolver |
+| ci       | CI / 构建流水线变更                      | ci: cache pnpm store                   |
+| build    | 构建系统 / 产物变更                      | build(native): add win32-arm64 target  |
+| perf     | 性能优化                                 | perf(session): batch event flushes     |
+| style    | 仅格式化（无逻辑变更）                   | style: apply oxlint --fix              |
+
+PR 标题由 `pr-title-checker` 工作流强制校验——不合规的标题会阻止合并。
+
+## Changesets
+
+本仓库使用 [changesets](https://github.com/changesets/changesets) 管理版本与发布。
+
+- 每个影响发布产物（代码、行为、公开 API）的 PR **必须**包含 changeset。
+- 仅文档、仅测试或仅 CI 的 PR 可以不加。
+- 用 `pnpm changeset` 生成并按提示操作（涉及哪些包、什么 bump 级别）。
+- 包选择与 bump 级别的仓库约定见 `.changeset/README.md`。在本仓库使用编程 agent 时，使用 `gen-changesets` 技能。
+
+## Pull Requests
+
+PR 会自动套用 [PR 模板](.github/pull_request_template.md)。PR 标题必须遵循 [Conventional Commits](#提交规范)；每个 PR 的 CI 会运行 `pnpm lint`、`pnpm typecheck` 和 `pnpm test`。行为变更时请同步更新 `docs/` 下的用户文档——使用编程 agent 时使用 `gen-docs` 技能。
+
+## 代码风格
+
+- 全仓库 TypeScript。
+- 使用 `oxlint`（配置见 `.oxlintrc.json`）。
+- 用 `pnpm lint:fix` 自动格式化。
+- lint 规则未覆盖的风格选择，跟随周边现有写法。
+
+## 报告安全问题
+
+发现安全问题？请查看 [SECURITY.md](SECURITY.md)，不要开公开 issue。
+
+## 许可证
+
+向本仓库贡献即表示你同意你的贡献按 [MIT 许可证](LICENSE) 授权。

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moonshot AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,67 @@
+.PHONY: prepare build typecheck lint lint-fix lint-pkg sherif test test-watch test-coverage clean changeset version publish release dev vis
+
+## Setup
+
+prepare:
+	pnpm install
+
+## Build
+
+build:
+	pnpm run build
+
+## Quality
+
+typecheck:
+	pnpm run typecheck
+
+lint:
+	pnpm run lint
+
+lint-fix:
+	pnpm run lint:fix
+
+sherif:
+	pnpm run sherif
+
+lint-pkg:
+	pnpm run lint:pkg
+
+## Test
+
+test:
+	pnpm run test
+
+test-watch:
+	pnpm run test:watch
+
+test-coverage:
+	pnpm run test:coverage
+
+## Clean
+
+clean:
+	pnpm run clean
+
+## Release
+
+changeset:
+	pnpm run changeset
+
+version:
+	pnpm run version
+
+publish:
+	pnpm run publish
+
+release: version publish
+
+## Development
+
+dev:
+	pnpm run dev:cli
+
+## vis
+
+vis:
+	pnpm run vis

README.md

@@ -0,0 +1,138 @@
+---
+license: mit
+tags:
+  - agent
+  - coding-agent
+  - cli
+  - llm
+  - tool-use
+---
+
+> **This is a source mirror.** This Hugging Face repository is not a model checkpoint — it's a read-only mirror of the [`MoonshotAI/kimi-code`](https://github.com/MoonshotAI/kimi-code) GitHub repository, Moonshot AI's terminal coding agent. It is hosted here for visibility on the Hub; the canonical repository, issue tracker, and pull requests all live on GitHub. Please file issues and contribute there, not here.
+
+# Kimi Code CLI
+
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE) [![Docs](https://img.shields.io/badge/docs-online-blue)](https://moonshotai.github.io/kimi-code/en/) <br>
+[Documentation](https://moonshotai.github.io/kimi-code/en/) · [Issues](https://github.com/MoonshotAI/kimi-code/issues) · [中文](README.zh-CN.md)
+
+![Demo of using Kimi Code](./docs/media/intro.gif)
+
+## What is Kimi Code CLI
+
+Kimi Code CLI is an AI coding agent that runs in your terminal — it can read and edit code, run shell commands, search files, fetch web pages, and choose the next step based on the feedback it receives. It works out of the box with Moonshot AI’s Kimi models and can also be configured to use other compatible providers.
+
+## Install
+
+Install with the official script. No Node.js required.
+
+- **macOS or 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
+```
+
+> On Windows, install [Git for Windows](https://gitforwindows.org/) before first launch because Kimi Code CLI uses the bundled Git Bash as its shell environment. If Git Bash is installed in a custom location, set `KIMI_SHELL_PATH` to the absolute path of `bash.exe`.
+
+Then, run it with a new shell session:
+
+```sh
+kimi --version
+```
+
+For npm install, upgrade, uninstall, see [Getting Started](https://moonshotai.github.io/kimi-code/en/guides/getting-started).
+
+## Quick Start
+
+Open a project and start the interactive UI:
+
+```sh
+cd your-project
+kimi
+```
+
+On first launch, run `/login` inside Kimi Code CLI and choose either Kimi Code OAuth or a Moonshot AI Open Platform API key. After login, try your first task:
+
+```
+Take a look at this project and explain its main directories.
+```
+
+## Key Features
+
+- **Single-binary distribution.** Install with one command: no Node.js setup, PATH gymnastics, or global module conflicts.
+- **Blazing-fast startup.** The TUI is ready in milliseconds, so starting a session never feels heavy.
+- **Purpose-built TUI.** A carefully tuned interface, optimized end to end for long, focused agent sessions.
+- **Video input.** Drop a screen recording or demo clip into the chat and let the agent watch what is hard to describe in words — turn a reference clip into a LUT, a long video into a short, a screen recording into working code, and more.
+- **AI-native MCP configuration.** Add, edit, and authenticate Model Context Protocol servers conversationally with `/mcp-config`, without hand-editing JSON.
+- **Rich plugin ecosystem.** Install skills, MCP servers, and data sources from the marketplace or any GitHub repo, with each install's trust level surfaced up front.
+- **Subagents for focused, parallel work.** Dispatch built-in `coder`, `explore`, and `plan` subagents in isolated contexts while keeping the main conversation clean.
+- **Lifecycle hooks.** Run local commands at key points to gate risky tool calls, audit decisions, trigger desktop notifications, or connect to your own automation.
+- **Editor & IDE integration (ACP).** Drive a Kimi Code CLI session straight from Zed, JetBrains, or any [Agent Client Protocol](https://agentclientprotocol.com/) client with `kimi acp`.
+
+## Use it in your editor (ACP)
+
+Kimi Code CLI speaks the [Agent Client Protocol](https://agentclientprotocol.com/), so ACP-compatible editors and IDEs (Zed, JetBrains, …) can drive a session over stdio. Log in once, then point your editor at the `kimi acp` subcommand — no extra login needed.
+
+For Zed, add this to `~/.config/zed/settings.json`:
+
+```json
+{
+  "agent_servers": {
+    "Kimi Code CLI": {
+      "type": "custom",
+      "command": "kimi",
+      "args": ["acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+Then open a new conversation in Zed's Agent panel. See [Using in IDEs](https://moonshotai.github.io/kimi-code/en/guides/ides) for JetBrains setup and troubleshooting, and the [`kimi acp` reference](https://moonshotai.github.io/kimi-code/en/reference/kimi-acp) for the full capability matrix.
+
+## Docs
+
+- [Getting Started](https://moonshotai.github.io/kimi-code/en/guides/getting-started)
+- [Interaction and approvals](https://moonshotai.github.io/kimi-code/en/guides/interaction)
+- [Sessions](https://moonshotai.github.io/kimi-code/en/guides/sessions)
+- [Using in IDEs (ACP)](https://moonshotai.github.io/kimi-code/en/guides/ides)
+- [Configuration](https://moonshotai.github.io/kimi-code/en/configuration/config-files)
+- [Command reference](https://moonshotai.github.io/kimi-code/en/reference/kimi-command)
+
+## Develop
+
+Requirements: Node.js ≥ 24.15.0, pnpm 10.33.0.
+
+```sh
+git clone https://github.com/MoonshotAI/kimi-code.git
+cd kimi-code
+pnpm install
+```
+
+```sh
+pnpm dev:cli    # run the CLI in dev mode
+pnpm test       # run tests
+pnpm typecheck  # TypeScript check
+pnpm lint       # oxlint
+pnpm build      # build all packages
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contribution guide.
+
+## Community
+
+- [Issues](https://github.com/MoonshotAI/kimi-code/issues)
+- For security vulnerabilities, see [SECURITY.md](SECURITY.md).
+
+## Acknowledgements
+
+Our TUI is built on top of [`pi-tui`](https://github.com/earendil-works/pi-mono/tree/main/packages/tui). We thank the authors of `pi-tui` for their valuable work.
+
+## License
+
+Released under the [MIT License](LICENSE).

README.zh-CN.md

@@ -0,0 +1,130 @@
+# Kimi Code CLI
+
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE) [![Docs](https://img.shields.io/badge/docs-online-blue)](https://moonshotai.github.io/kimi-code/zh/)
+
+[Documentation](https://moonshotai.github.io/kimi-code/zh/) · [Issues](https://github.com/MoonshotAI/kimi-code/issues) · [English](README.md)
+
+
+![Kimi Code 的使用演示](./docs/media/intro.gif)
+
+
+## 什么是 Kimi Code CLI
+
+Kimi Code CLI 是一个运行在终端里的 AI 编程 agent，可以帮你读写代码、执行 shell 命令、检索文件、抓取网页，并根据反馈自主决定下一步动作。开箱即用对接 Moonshot AI 的 Kimi 模型，也可指向其他兼容厂商。
+
+## 安装
+
+推荐使用官方安装脚本，不需要提前安装 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
+```
+
+> Windows 用户首次启动前还需要安装 [Git for Windows](https://gitforwindows.org/)，Kimi Code CLI 会使用其中的 Git Bash 作为 Shell 环境。如果 Git Bash 安装在非标准路径，请把 `KIMI_SHELL_PATH` 设为 `bash.exe` 的绝对路径。
+
+随后在新的终端会话中运行：
+
+```sh
+kimi --version
+```
+
+npm 安装、升级、卸载方式，见[快速上手](https://moonshotai.github.io/kimi-code/zh/guides/getting-started)。
+
+## 快速开始
+
+进入项目目录并启动交互界面：
+
+```sh
+cd your-project
+kimi
+```
+
+首次启动时，在 Kimi Code CLI 里输入 `/login`，选择 Kimi Code OAuth 或 Moonshot AI Open Platform API 密钥登录。登录完成后，可以先让它熟悉项目：
+
+```
+帮我看一下这个项目的目录结构，简单介绍一下每个目录是做什么的
+```
+
+## 核心特性
+
+- **二进制发行，零环境依赖** 一行命令安装，不需要预装 Node.js，不用折腾 PATH，也不会和全局模块冲突。
+- **极速启动** TUI 在毫秒级就绪，开一个新会话没有任何心智负担。
+- **精致的 TUI 体验** 端到端打磨的交互界面，专为长时间、专注的 Agent 会话优化。
+- **视频也能输入** 把屏幕录像、演示视频拖进对话，让 Agent 看那些难以用文字描述的东西——把参考片段做成 LUT、把长视频剪成短视频、把录屏变成代码，等等。
+- **AI-native 的 MCP 配置** 通过 `/mcp-config` 对话式添加、编辑、认证 MCP 服务器，无需手写 JSON。
+- **丰富的插件生态** 从插件市场或任意 GitHub 仓库安装 skills、MCP 服务器和数据源，每次安装都会标明来源的信任级别。
+- **子 Agent 聚焦并行工作** 内置 `coder`、`explore`、`plan` 子 Agent 在隔离上下文中处理子任务，主对话保持清爽。
+- **生命周期 hooks** 在关键节点执行本地命令：拦截高风险工具调用、审计决策、发送桌面通知，或对接你自己的自动化脚本。
+- **编辑器 / IDE 集成（ACP）** 用 `kimi acp` 让 Zed、JetBrains 等任意 [Agent Client Protocol](https://agentclientprotocol.com/) 客户端直接驱动会话。
+
+
+## 在编辑器里使用（ACP）
+
+Kimi Code CLI 支持 [Agent Client Protocol](https://agentclientprotocol.com/)，ACP 兼容的编辑器 / IDE（Zed、JetBrains……）可以通过 stdio 直接驱动会话。登录一次后，把编辑器指向 `kimi acp` 子命令即可，无需重复登录。
+
+以 Zed 为例，在 `~/.config/zed/settings.json` 中加入：
+
+```json
+{
+  "agent_servers": {
+    "Kimi Code CLI": {
+      "type": "custom",
+      "command": "kimi",
+      "args": ["acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+随后在 Zed 的 Agent 面板新建对话即可。JetBrains 配置与排障见[在 IDE 中使用](https://moonshotai.github.io/kimi-code/zh/guides/ides)，完整能力矩阵见 [`kimi acp` 参考](https://moonshotai.github.io/kimi-code/zh/reference/kimi-acp)。
+
+## 文档
+
+- [快速上手](https://moonshotai.github.io/kimi-code/zh/guides/getting-started)
+- [交互与审批](https://moonshotai.github.io/kimi-code/zh/guides/interaction)
+- [会话](https://moonshotai.github.io/kimi-code/zh/guides/sessions)
+- [在 IDE 中使用（ACP）](https://moonshotai.github.io/kimi-code/zh/guides/ides)
+- [配置](https://moonshotai.github.io/kimi-code/zh/configuration/config-files)
+- [命令参考](https://moonshotai.github.io/kimi-code/zh/reference/kimi-command)
+
+## 本地开发
+
+环境要求：Node.js ≥ 24.15.0，pnpm 10.33.0。
+
+```sh
+git clone https://github.com/MoonshotAI/kimi-code.git
+cd kimi-code
+pnpm install
+```
+
+```sh
+pnpm dev:cli    # 以开发模式运行 CLI
+pnpm test       # 运行测试
+pnpm typecheck  # TypeScript 检查
+pnpm lint       # 运行 oxlint
+pnpm build      # 构建所有包
+```
+
+完整贡献流程见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+## 社区
+
+- [Issues](https://github.com/MoonshotAI/kimi-code/issues)
+- 安全漏洞反馈，请见 [SECURITY.md](SECURITY.md)。
+
+## 致谢
+
+我们的 TUI 构建在 [`pi-tui`](https://github.com/earendil-works/pi-mono/tree/main/packages/tui) 之上。我们衷心感谢 `pi-tui` 作者的工作。
+
+## 许可证
+
+基于 [MIT](LICENSE) 协议发布。

SECURITY.md

@@ -0,0 +1,33 @@
+# Security Policy
+
+## Supported Versions
+
+Currently, Kimi Code only provides security support for the latest released version.
+
+## Reporting a Vulnerability
+
+We take security seriously. **Please do not open a public issue for security vulnerabilities.**
+
+Preferred channel:
+
+- GitHub Security Advisories — https://github.com/MoonshotAI/kimi-code/security/advisories/new
+  (private disclosure, tracked with the codebase)
+
+Alternative channel:
+
+- Email: code@moonshot.ai (please include "[security]" in the subject)
+
+## What to Include
+
+- Affected version (output of `kimi --version`)
+- Reproduction steps
+- Impact assessment
+- Any suggested mitigation
+
+## Our Response
+
+We will acknowledge your report and provide an initial assessment as soon as we can.
+
+## Public Disclosure
+
+We will coordinate with you on disclosure timing once a fix is ready.

docs/.gitignore

@@ -0,0 +1,4 @@
+node_modules
+.vitepress/dist
+.vitepress/cache
+.vitepress/.temp

docs/AGENTS.md

@@ -0,0 +1,328 @@
+# 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, plugins, datasource, agents, hooks
+  - Configuration: config-files, providers, overrides, env-vars, data-locations
+  - Reference: kimi-command, tools, slash-commands, keyboard
+  - 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 is the exception because it is generated from release history.
+- For other pages: edit either locale, then update its mirror in the same change.
+
+Before rewriting a page, always: (1) understand why the original is structured the way it is, (2) identify what the reader genuinely needs to know, (3) sketch the section structure, then (4) fill in the content. Skip step 1–3 and you will lose content while rearranging format.
+
+## Readers
+
+Kimi Code documentation serves two overlapping audiences. Write for both simultaneously.
+
+**Technical users** — familiar with the terminal, config files, API keys, and environment variables. Give them commands and paths directly; do not explain basics.
+
+**Non-technical AI users** — product managers, designers, operators — who use AI tools but are unfamiliar with terms like "stdin", "exit code", or "regex". They primarily interact through VS Code or config files rather than writing scripts.
+
+Both groups share the same behavior: they arrive with a specific goal, scan headings and first sentences before reading further, execute steps in order, and copy-paste code blocks directly. They abandon pages when they hit unexplained jargon.
+
+**Writing targets:**
+- Technical users: complete a task in under 5 minutes, no filler.
+- Non-technical users: copy-paste their way to a working setup and roughly understand what it does, without needing to understand the underlying mechanics.
+
+**Jargon rule:** On first use, add a plain-English gloss in parentheses. Use the term normally afterwards.
+
+> Example: `stdin` (the channel a program reads input from), `exit code` (the status number a program returns when it finishes; 0 means success).
+
+## 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", "Thinking mode", and the permission mode names "Always Ask", "Ask When Needed", and "Never Ask" 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 |
+| main agent | main agent | no | no |
+| subagent | subagent | no | no |
+| Shell | shell | yes | no |
+| Plan 模式 | Plan mode | yes | yes (Plan mode) |
+| 始终询问 | Always Ask | yes | yes |
+| 必要时询问 | Ask When Needed | yes | yes |
+| 完全自动 | Never Ask | yes | yes |
+| 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 |
+
+### Kimi platform rules
+
+Two distinct platforms exist and must never be mixed:
+
+| | Kimi Code platform | Kimi Open Platform |
+|---|---|---|
+| Audience | Individual developers, subscription-based | Enterprise / product integration, pay-per-token |
+| OpenAI-compatible base URL | `https://api.kimi.com/coding/v1` | `https://api.moonshot.cn/v1` |
+| Anthropic-compatible base URL | `https://api.kimi.com/coding/` | Not supported |
+| API key entry | [Kimi Code console](https://www.kimi.com/code/console) | [platform.kimi.com](https://platform.kimi.com) |
+
+Rules:
+- When documenting Kimi Code CLI or VS Code: always use `api.kimi.com/coding/…`. Never write `api.moonshot.cn` in this context.
+- When documenting Open Platform integration: use `api.moonshot.cn/v1`.
+- Distinguish context explicitly: "in Kimi Code CLI / VS Code" vs "in third-party tools / your own product".
+- Product full names: **Kimi Code CLI** and **Kimi Code for VS Code**. Do not abbreviate to "Kimi CLI".
+
+## 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 `部分 \`.agents\` 资源不受 \`KIMI_CODE_HOME\` 影响。...`
+  - ✗ `::: warning 不影响 .agents` (title too long, should be in content)
+  - ✗ `::: tip .agents 路径独立于 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)
+- **Callout syntax**: Use `:::` for standalone callouts. `::::` is valid only as the outer fence of a nested container and must be correctly closed; an unclosed or mismatched `::::` breaks page rendering. When nesting is not needed, use a `>` blockquote inside a callout for secondary notes instead.
+
+## 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. This applies to narrative content — explanations, motivations, and sequential reasoning that flow as connected prose.
+- **Global perspective**: "Getting Started" introduces core concepts only; detailed usage belongs in later pages.
+- **Progressive depth**: Guides → Customization → Configuration → Reference, information deepens gradually.
+- **No nav tip blocks**: VitePress provides automatic prev/next navigation; don't add `::: tip 接下来` blocks at page end. A `## Next steps` section is appropriate when there are closely related follow-on pages — see [Page structure](#page-structure).
+- **One idea per paragraph**: Each paragraph makes one point. 3–4 sentences is the target; split when a paragraph exceeds 5 sentences.
+- **Map before detail**: Every page and every major section should open with one "map" sentence — what this section covers and how it relates to what came before — before expanding into details. Readers should know where they are before they dive in.
+
+  > ❌ Jump straight to detail: "Credential resolution has three steps: first read `api_key`…"
+  >
+  > ✓ Map then detail: "Provider credentials follow a separate resolution path from ordinary runtime parameters — the CLI reads only from `config.toml` and never falls back to shell environment variables. The priority order is:…"
+
+- **Parallel content needs formatting**: This is the counterpart to "avoid fragmentation" — the distinction is what kind of content you have. Multiple items of the same kind (file descriptions, config field explanations, caveats) written as separate paragraphs with no visual distinction force readers to parse shape instead of meaning. Fix:
+  - Each item is "name + one sentence": use an unordered list: `- **Name**: description`
+  - Multiple dimensions (name + type + description): use a table
+  - Each item is longer than two sentences: use a `###` subheading
+
+### 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)
+```
+
+## Format decisions
+
+Choose the format that matches the content's structure, not the one that looks most thorough.
+
+**Ordered list** — steps that must happen in sequence (installation, configuration, migration). Do not nest sub-lists inside steps.
+
+**Unordered list** — parallel items with no ordering dependency. Format: `- **Name**: one-sentence description`.
+
+**Table** — reference content with multiple dimensions to compare or look up (config fields with name + type + required + description; keyboard shortcuts; platform comparison). Avoid tables when cell content would need to wrap to be readable.
+
+**Prose** — explanations, motivations, caveats, anything that flows naturally as connected sentences. Do not convert prose into bullets just to add visual structure.
+
+## Cross-references
+
+Readers never read just one page. A complete understanding is usually spread across several pages. Add links wherever they help.
+
+**Always link when:**
+1. A concept mentioned on this page has a full explanation on another page — link to it on first mention, not the second or third. Prefer anchors (`#section`) over page-top links when the relevant content is in a specific section.
+2. This page gives a brief summary while another page has the full field reference or example — link the summary to the detail.
+3. A later section on this page depends on a concept defined earlier on this page — back-link with `[term](#anchor)` so readers don't have to scroll.
+
+**Do not write:**
+- "See related documentation" — which one? Readers skip this.
+- Link only in a "Next steps" list at the bottom — readers who hit a blocker mid-page won't scroll to the end to find the link.
+- First mention without a link, linked on second or third mention — the first mention is when the reader most wants to click.
+
+**Inline links vs "Next steps":** Inline links serve readers who need supplemental information mid-page. A closing "Next steps" section serves readers who finished the page and want natural follow-on reading. Both have a place; neither replaces the other.
+
+## Page structure
+
+```
+# Title (noun phrase, no period)
+
+Opening sentence or two + plain-English summary (only when the concept has a learning curve)
+
+> blockquote (optional: Beta notice, prerequisites)
+
+Supplementary context / use-case list (optional)
+
+Diagram (optional)
+
+::: warning Banner (deprecation, breaking change, security notice — after opening content, before first ##)
+
+## First section
+
+Body…
+
+## Next steps (optional, only when related pages exist)
+- [Page name](/path) — one sentence describing what the reader can do there
+```
+
+**Banner placement rule:** Banners must appear after all opening content (opening sentences, blockquote, diagram) and before the first `##`. A banner must never be the first thing on the page.
+
+## Content completeness
+
+**Default position: keep everything.** When editing a page, every block of original content needs an explicit destination — either retained or consciously removed with a stated reason.
+
+**Valid reasons to omit content:**
+- Too low-level / pure implementation detail that users never need to act on
+- Already covered more completely on another page that is linked from here
+- Content is ambiguous or suspected outdated — flag it rather than silently dropping it
+
+**Not valid reasons:**
+- "Seems unimportant" — that is a guess, not a reason
+- "I'm not sure about this" — research it rather than omitting it
+- "The page is getting long" — restructure, do not cut
+
+If content is omitted, note it explicitly in the PR description or commit message. Do not write omission notices inside the document itself.
+
+## Checklist
+
+Run through this before marking any doc change ready for review.
+
+### Format
+
+| Problem | Fix |
+|---|---|
+| `::::` unclosed or mismatched | Close the fence or replace with `:::` if nesting is not needed |
+| Nested callout containers | Change inner one to `>` blockquote |
+| Banner before first `##` but also before opening content | Move to after opening sentences / blockquote / diagram |
+| Steps written as unordered list | Change to ordered list |
+| Multi-dimension comparison written as prose | Convert to table |
+| Technical term used without explanation on first occurrence | Add plain-English gloss in parentheses |
+| Cross-reference written as "see …" with no link | Add inline link; prefer anchor to section, not just page top |
+| Concept depends on earlier definition but no back-link | Add `[term](#anchor)` |
+| Changed zh without changing en (or vice versa) | Update both locales |
+| Code block has no language tag | Add language (e.g., `sh`, `toml`, `json`); exception: natural-language prompt examples may omit the tag |
+
+### Kimi-specific consistency
+
+Before shipping, verify these values match the rest of the docs:
+
+- **Base URL**: matches the [Kimi platform rules](#kimi-platform-rules) table above
+- **Upgrade command**: matches `guides/getting-started.md`
+- **Model ID**: use `kimi-for-coding`, not a versioned model name
+- **Login command**: `/login`, not `/setup`
+- **Product full name**: **Kimi Code CLI** or **Kimi Code for VS Code** — never "Kimi CLI"
+- **Platform URLs**: `api.kimi.com/coding/…` for Kimi Code platform; `api.moonshot.cn/v1` for Open Platform — never mix the two
+
+## 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.

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>

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.15.0",
+    "vitepress-plugin-llms": "^1.10.0",
+    "vitepress-plugin-mermaid": "^2.0.17"
+  }
+}

flake.lock

@@ -0,0 +1,27 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1779102034,
+        "narHash": "sha256-vZJZjLo513IeI8hjzHFc6TDezUd4uCE2Eq4SNO3DNNg=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "687f05a9184cad4eaf905c48b63649e3a86f5433",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-25.11",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,261 @@
+{
+  description = "Kimi Code CLI";
+
+  inputs = {
+    # Pinned to the 25.11 release channel because nixpkgs-unstable currently
+    # ships nodejs_24 = 24.14.1, which trips the >= 24.15.0 floor that the
+    # native SEA build enforces (see apps/kimi-code/scripts/native/build.mjs).
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
+  };
+
+  outputs =
+    { self, nixpkgs }:
+    let
+      lib = nixpkgs.lib;
+
+      systems = [
+        "x86_64-linux"
+        "aarch64-linux"
+        "x86_64-darwin"
+        "aarch64-darwin"
+      ];
+
+      forAllSystems =
+        f:
+        lib.genAttrs systems (
+          system:
+          f (import nixpkgs {
+            inherit system;
+          })
+        );
+
+      minNodeVersion = "24.15.0";
+
+      # Hardcode to Node.js 24.x; fail the evaluation if the pinned nixpkgs
+      # does not offer a new enough 24.x.
+      nodejsFor =
+        pkgs:
+        let
+          node = pkgs.nodejs_24;
+        in
+        if lib.versionAtLeast node.version minNodeVersion then
+          node
+        else
+          throw ''
+            Kimi Code requires Node.js >= ${minNodeVersion},
+            but nixpkgs only offers ${node.version}.
+            Pin a newer nixpkgs revision or update minNodeVersion in flake.nix.
+          '';
+
+      pnpmFor =
+        pkgs:
+        pkgs.pnpm_10.override {
+          nodejs = nodejsFor pkgs;
+        };
+
+      # -------------------------------------------------------------------
+      # Workspace members (kept in sync with pnpm-workspace.yaml).
+      #
+      # HARD REQUIREMENT: whenever you add or remove a workspace package,
+      # you MUST update both lists below. Missing a path will break the Nix
+      # build (src fileset silently drops files); missing a name will break
+      # pnpmConfigHook (dependencies for that workspace won't be fetched).
+      # -------------------------------------------------------------------
+      workspacePaths = [
+        ./packages/acp-server
+        ./packages/agent-core-v2
+        ./packages/kap-server
+        ./packages/kaos
+        ./packages/klient
+        ./packages/kosong
+        ./packages/migration-legacy
+        ./packages/minidb
+        ./packages/node-sdk
+        ./packages/oauth
+        ./packages/pi-tui
+        ./packages/remote-control
+        ./packages/telemetry
+        ./packages/transcript
+        ./packages/tree-sitter-bash
+        ./apps/kimi-code
+        ./apps/vscode
+        ./apps/kimi-inspect
+        ./apps/vis
+        ./apps/vis/server
+        ./apps/vis/web
+        ./docs
+      ];
+
+      workspaceNames = [
+        "@moonshot-ai/acp-server"
+        "@moonshot-ai/agent-core-v2"
+        "@moonshot-ai/kap-server"
+        "@moonshot-ai/kaos"
+        "@moonshot-ai/kosong"
+        "@moonshot-ai/migration-legacy"
+        "@moonshot-ai/minidb"
+        "@moonshot-ai/kimi-code-sdk"
+        "@moonshot-ai/kimi-code-oauth"
+        "@moonshot-ai/klient"
+        "@moonshot-ai/pi-tui"
+        "@moonshot-ai/remote-control"
+        "@moonshot-ai/kimi-telemetry"
+        "@moonshot-ai/transcript"
+        "@moonshot-ai/tree-sitter-bash"
+        "@moonshot-ai/kimi-code"
+        "kimi-code"
+        "@moonshot-ai/kimi-inspect"
+        "@moonshot-ai/vis"
+        "@moonshot-ai/vis-server"
+        "@moonshot-ai/vis-web"
+        "kimi-code-docs"
+      ];
+    in
+    {
+      packages = forAllSystems (
+        pkgs:
+        let
+          nodejs = nodejsFor pkgs;
+          pnpm = pnpmFor pkgs;
+          appPackageJson = builtins.fromJSON (builtins.readFile ./apps/kimi-code/package.json);
+          nativeTarget =
+            if pkgs.stdenv.hostPlatform.isLinux && pkgs.stdenv.hostPlatform.isAarch64 then
+              "linux-arm64"
+            else if pkgs.stdenv.hostPlatform.isLinux then
+              "linux-x64"
+            else if pkgs.stdenv.hostPlatform.isDarwin && pkgs.stdenv.hostPlatform.isAarch64 then
+              "darwin-arm64"
+            else if pkgs.stdenv.hostPlatform.isDarwin then
+              "darwin-x64"
+            else
+              throw "Unsupported Kimi Code native target for ${pkgs.stdenv.hostPlatform.system}";
+
+          kimi-code = pkgs.stdenv.mkDerivation (finalAttrs: {
+            pname = "kimi-code";
+            version = appPackageJson.version;
+
+            src = lib.fileset.toSource {
+              root = ./.;
+              fileset = lib.fileset.unions (
+                [
+                  ./build
+                  ./.npmrc
+                  ./.nvmrc
+                  ./package.json
+                  ./pnpm-lock.yaml
+                  ./pnpm-workspace.yaml
+                  ./tsconfig.json
+                  ./vitest.config.ts
+                  ./LICENSE
+                ]
+                ++ workspacePaths
+              );
+            };
+
+            pnpmWorkspaces = [ "." ] ++ workspaceNames;
+
+            pnpmDeps = pkgs.fetchPnpmDeps {
+              inherit (finalAttrs) pname version src pnpmWorkspaces;
+              inherit pnpm;
+              fetcherVersion = 3;
+              hash = "sha256-LWpsB1Z9nAIFF2/sHv30F2Y9n+87wmg+ypiMFwOQ6M0=";
+            };
+
+            nativeBuildInputs = [
+              nodejs
+              pnpm
+              (pkgs.pnpmConfigHook.override { inherit pnpm; })
+              pkgs.makeWrapper
+            ]
+            # The SEA inject step (postject) invalidates the macOS code
+            # signature on the copied Node executable; build.mjs then re-applies
+            # an ad-hoc signature via `codesign`. The Nix darwin sandbox does
+            # not expose /usr/bin/codesign, so we supply nixpkgs' ad-hoc-only
+            # replacement instead.
+            ++ lib.optionals pkgs.stdenv.hostPlatform.isDarwin [
+              pkgs.darwin.sigtool
+            ];
+
+            # The SEA binary is produced by `postject`-injecting a blob into a
+            # plain Node executable. Stripping rewrites section tables and can
+            # invalidate the injected blob's offsets, so leave the binary
+            # untouched after the build.
+            dontStrip = true;
+
+            buildPhase = ''
+              runHook preBuild
+              export KIMI_CODE_BUILD_TARGET=${nativeTarget}
+              ${lib.optionalString pkgs.stdenv.hostPlatform.isDarwin ''
+                # pkgs.darwin.sigtool's codesign supports `--sign -` (ad-hoc)
+                # but not the inspection mode (`-dv`) that 05-verify.mjs runs
+                # afterwards. Disable the verify step for the Nix build; the
+                # release CI keeps it via the unmodified script.
+                substituteInPlace apps/kimi-code/scripts/native/build.mjs \
+                  --replace-fail \
+                    "await runVerifyStep({ requireGatekeeper: false });" \
+                    "// runVerifyStep skipped in nix sandbox (sigtool lacks -dv)"
+              ''}
+              # The SEA blob step (scripts/native/02-sea-blob.mjs) embeds the
+              # Kimi web assets from apps/kimi-code/dist-web and fails if that
+              # directory is missing. The bundle is committed (synced from the
+              # code-app repo) — verify it is in place before producing the
+              # native executable.
+              node apps/kimi-code/scripts/check-web-assets.mjs
+              pnpm --filter=@moonshot-ai/kimi-code run build:native:sea
+              runHook postBuild
+            '';
+
+            installPhase = ''
+              runHook preInstall
+
+              install -Dm755 \
+                "apps/kimi-code/dist-native/bin/${nativeTarget}/kimi" \
+                "$out/bin/kimi"
+
+              runHook postInstall
+            '';
+
+            postInstall = ''
+              wrapProgram $out/bin/kimi --prefix PATH : ${lib.makeBinPath [ pkgs.ripgrep pkgs.fd ]}
+            '';
+
+            meta = {
+              description = "Kimi Code CLI";
+              homepage = "https://github.com/MoonshotAI/kimi-code";
+              license = lib.licenses.mit;
+              mainProgram = "kimi";
+              platforms = systems;
+            };
+          });
+        in
+        {
+          inherit kimi-code;
+          default = kimi-code;
+        }
+      );
+
+      apps = forAllSystems (pkgs: {
+        kimi-code = {
+          type = "app";
+          program = "${self.packages.${pkgs.system}.kimi-code}/bin/kimi";
+        };
+        default = self.apps.${pkgs.system}.kimi-code;
+      });
+
+      devShells = forAllSystems (pkgs: {
+        default =
+          let
+            nodejs = nodejsFor pkgs;
+            pnpm = pnpmFor pkgs;
+          in
+          pkgs.mkShell {
+            packages = [
+              nodejs
+              pnpm
+              pkgs.ripgrep
+              pkgs.fd
+            ];
+          };
+      });
+    };
+}

package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@moonshot-ai/monorepo",
+  "version": "0.1.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "postinstall": "node scripts/fix-node-pty-perms.mjs",
+    "build": "pnpm -r run build",
+    "build:packages": "pnpm -r --filter './packages/*' run build",
+    "dev:cli": "pnpm -C apps/kimi-code run dev",
+    "dev:cli:marketplace": "KIMI_CODE_DEV_MARKETPLACE_URL=https://code.kimi.com/kimi-code/plugins/marketplace.json pnpm -C apps/kimi-code run dev",
+    "dev:server": "pnpm -C apps/kimi-code run dev:server",
+    "dev:kap-server": "pnpm -C apps/kimi-code run dev:kap-server",
+    "dev:v2": "pnpm -C apps/kimi-code run dev:kap-server:multi",
+    "build:plugin-marketplace": "pnpm -C apps/kimi-code run build:plugin-marketplace",
+    "vis": "pnpm -C apps/vis run dev",
+    "dev:docs": "pnpm -C docs install --ignore-workspace && pnpm -C docs run dev",
+    "typecheck": "pnpm run build:packages && pnpm -r --filter './packages/*' run typecheck && pnpm --filter @moonshot-ai/kimi-code run typecheck && pnpm --filter kimi-code run typecheck && pnpm --filter @moonshot-ai/vis-server run typecheck && pnpm --filter @moonshot-ai/vis-web run typecheck",
+    "lint": "node scripts/check-no-comments.mjs && oxlint --type-aware",
+    "lint:fix": "pnpm run lint --fix",
+    "lint:pkg": "pnpm --filter @moonshot-ai/kimi-code exec publint && npm_config_cache=${TMPDIR:-/tmp}/kimi-code-npm-cache pnpm --filter @moonshot-ai/kimi-code exec attw --pack . --profile node16",
+    "sherif": "sherif -i @agentclientprotocol/sdk",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "clean": "pnpm -r run clean",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "version:release": "changeset version",
+    "publish": "pnpm run typecheck && pnpm run lint && pnpm run sherif && pnpm run test && pnpm run build && pnpm run lint:pkg && changeset publish",
+    "prepare": "node .husky/install.mjs"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.2",
+    "@changesets/changelog-github": "0.7.0",
+    "@changesets/cli": "2.30.0",
+    "@microsoft/api-extractor": "7.58.7",
+    "@types/node": "^22.15.3",
+    "@vitest/coverage-v8": "4.1.4",
+    "husky": "^9.1.7",
+    "lint-staged": "16.4.0",
+    "oxlint": "1.59.0",
+    "oxlint-tsgolint": "0.20.0",
+    "pkg-pr-new": "0.0.75",
+    "publint": "0.3.18",
+    "sherif": "1.11.1",
+    "tsdown": "0.22.0",
+    "tsx": "^4.21.0",
+    "typescript": "6.0.2",
+    "vitest": "4.1.4"
+  },
+  "lint-staged": {
+    "*.{js,jsx,ts,tsx,mjs,cjs,mts,cts}": [
+      "oxlint --fix --quiet",
+      "oxlint --type-aware --quiet"
+    ]
+  },
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "packageManager": "pnpm@10.33.0"
+}

plugins/marketplace.json

@@ -0,0 +1,60 @@
+{
+  "version": "1",
+  "plugins": [
+    {
+      "id": "kimi-datasource",
+      "tier": "official",
+      "displayName": "Kimi Datasource",
+      "version": "3.4.0",
+      "description": "Stocks and financials from Wind, S&P Capital IQ, SEC EDGAR, etc.; news from Caixin, Xinhua Finance; macro from World Bank, IMF, FRED, NBS; corporate, academic, legal data, and more",
+      "keywords": ["data", "mcp"],
+      "source": "./official/kimi-datasource"
+    },
+    {
+      "id": "kimi-webbridge",
+      "tier": "official",
+      "displayName": "Kimi Browser Extension",
+      "version": "1.11.4",
+      "description": "Control your real browser from Kimi Code.",
+      "keywords": ["browser", "automation", "webbridge"],
+      "source": "./official/kimi-webbridge"
+    },
+    {
+      "id": "superpowers",
+      "tier": "curated",
+      "displayName": "Superpowers",
+      "description": "Planning, TDD, debugging, and delivery workflows for coding agents.",
+      "homepage": "https://github.com/obra/superpowers",
+      "keywords": ["skills", "planning", "tdd", "debugging", "code-review"],
+      "source": "https://github.com/obra/superpowers"
+    },
+    {
+      "id": "vercel-plugin",
+      "tier": "curated",
+      "displayName": "Vercel Plugin",
+      "description": "Comprehensive Vercel ecosystem plugin — skills, agents, and conventions for the Vercel platform.",
+      "homepage": "https://vercel.com/docs/agent-resources/vercel-plugin",
+      "keywords": ["vercel", "deployment", "nextjs", "skills", "agents"],
+      "source": "https://github.com/vercel/vercel-plugin"
+    },
+    {
+      "id": "modern-web-guidance",
+      "tier": "curated",
+      "displayName": "Modern Web Guidance",
+      "description": "Modern web platform expertise, best practices, and browser compatibility data for coding agents, from the Google Chrome team.",
+      "homepage": "https://github.com/GoogleChrome/modern-web-guidance",
+      "keywords": ["web", "css", "browser", "frontend", "skills"],
+      "source": "https://github.com/GoogleChrome/modern-web-guidance"
+    },
+    {
+      "id": "cloudbase",
+      "tier": "curated",
+      "displayName": "Tencent CloudBase",
+      "version": "0.2.0",
+      "description": "Build, deploy, and manage Tencent CloudBase apps — databases, cloud functions, storage, auth, and hosting, powered by cloudbase-mcp.",
+      "homepage": "https://github.com/TencentCloudBase/CloudBase-AI-Toolkit",
+      "keywords": ["cloudbase", "tencent-cloud", "baas", "database", "cloud-function", "mcp"],
+      "source": "https://github.com/TencentCloudBase/CloudBase-AI-Toolkit/releases/latest/download/cloudbase-kimi.zip"
+    }
+  ]
+}

pnpm-workspace.yaml

@@ -0,0 +1,15 @@
+packages:
+  - packages/*
+  - apps/*
+  - apps/vis/server
+  - apps/vis/web
+  - docs
+
+catalog:
+  zod: 4.3.6
+
+overrides:
+  "kimi-code>@tailwindcss/vite": "4.1.18"
+  "ssh2@1.17.0>cpu-features": "-"
+  "ssh2@1.17.0>nan": "-"
+  "kimi-code>tailwindcss": "4.1.18"

scripts/check-service-naming.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Enforce the VS Code-style service naming convention finalized in
+ * Phase 5 of the 2026.06.07 services-alignment plan:
+ *
+ *   - packages/services/src/<domain>/<domain>.ts (+ <domain>Service.ts)
+ *   - packages/kap-server/src/services/<domain>/<domain>.ts (+ <domain>Service.ts)
+ *
+ * Domain dirs and service-related .ts files must be camelCase — never
+ * kebab-case (no `-` in the name). Anything outside these two roots is
+ * ignored (test fixtures, etc.).
+ *
+ * Exit code 0 if clean, 1 with an actionable report otherwise.
+ */
+
+import { readdirSync, statSync, existsSync } from "node:fs";
+import { resolve, join, relative } from "node:path";
+
+const ROOT = resolve(import.meta.dirname, "..");
+const SERVICES_SRC = join(ROOT, "packages/services/src");
+const SERVER_SERVICES_SRC = join(ROOT, "packages/kap-server/src/services");
+
+/** @type {Array<{ kind: string, path: string }>} */
+const violations = [];
+
+function isKebab(name) {
+  return name.includes("-");
+}
+
+function report(kind, absPath) {
+  violations.push({ kind, path: relative(ROOT, absPath) });
+}
+
+/**
+ * Both roots are organised as <domain>/<files>.ts plus a few top-level files
+ * (index.ts, module.ts, pinoLoggerService.ts). Flag kebab in dir names and in
+ * any .ts file directly under a domain dir.
+ */
+function scanServicesSrc(srcRoot = SERVICES_SRC) {
+  if (!existsSync(srcRoot)) return;
+  for (const entry of readdirSync(srcRoot)) {
+    const abs = join(srcRoot, entry);
+    const st = statSync(abs);
+    if (st.isDirectory()) {
+      if (isKebab(entry)) report("kebab-dir", abs);
+      for (const f of readdirSync(abs)) {
+        if (!f.endsWith(".ts")) continue;
+        if (isKebab(f)) report("kebab-file", join(abs, f));
+      }
+    } else if (entry.endsWith(".ts") && isKebab(entry)) {
+      report("kebab-file", abs);
+    }
+  }
+}
+
+scanServicesSrc();
+scanServicesSrc(SERVER_SERVICES_SRC);
+
+if (violations.length > 0) {
+  console.error(
+    "Service naming violations (no kebab-case allowed for service files/dirs):"
+  );
+  for (const v of violations) console.error(`  [${v.kind}] ${v.path}`);
+  console.error(
+    "\nRename to camelCase per VS Code convention: <domain>.ts + <domain>Service.ts."
+  );
+  process.exit(1);
+}
+
+console.log("Service naming check passed.");

scripts/fix-node-pty-perms.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * Restore the executable bit on node-pty's `spawn-helper` prebuilt binaries.
+ *
+ * Why: on macOS/Linux node-pty launches the shell through a tiny `spawn-helper`
+ * executable shipped under `prebuilds/<platform-arch>/`. pnpm's content-
+ * addressable store does not preserve the +x mode on these non-bin prebuild
+ * assets, so after `pnpm install` the helper lands as 0644 and any PTY spawn
+ * fails with "posix_spawnp failed". npm/yarn (and the published tarball) keep
+ * the bit, so this is a pnpm-dev-only fixup.
+ *
+ * Idempotent and never fails the install: any error is logged and ignored.
+ */
+import { chmodSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+function nodePtyRoot() {
+  const require = createRequire(import.meta.url);
+  // Resolve from packages/services (where node-pty is declared) so we find the
+  // workspace's hoisted copy regardless of where this script runs.
+  const entry = require.resolve('node-pty', {
+    paths: [join(process.cwd(), 'packages/services'), process.cwd()],
+  });
+  // .../node-pty/lib/index.js -> .../node-pty
+  return dirname(dirname(entry));
+}
+
+try {
+  const root = nodePtyRoot();
+  const prebuilds = join(root, 'prebuilds');
+  if (!existsSync(prebuilds)) process.exit(0);
+  let fixed = 0;
+  for (const arch of readdirSync(prebuilds)) {
+    const helper = join(prebuilds, arch, 'spawn-helper');
+    if (!existsSync(helper)) continue;
+    const mode = statSync(helper).mode;
+    if ((mode & 0o111) === 0o111) continue; // already executable
+    chmodSync(helper, 0o755);
+    fixed++;
+  }
+  if (fixed > 0) console.log(`[fix-node-pty-perms] made ${fixed} spawn-helper binary(ies) executable`);
+} catch (err) {
+  console.warn('[fix-node-pty-perms] skipped:', err instanceof Error ? err.message : String(err));
+}
+process.exit(0);

tsconfig.json

@@ -0,0 +1,46 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "module": "preserve",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "lib": ["ES2023"],
+    "jsx": "react-jsx",
+    "jsxImportSource": "react",
+
+    "strict": true,
+    "isolatedModules": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "verbatimModuleSyntax": true,
+    "experimentalDecorators": true,
+
+    "declaration": true,
+    "sourceMap": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+
+    "types": ["node"]
+  },
+  "include": [
+    "packages/*/src/**/*.ts",
+    "packages/*/src/**/*.tsx",
+    "packages/*/test/**/*.ts",
+    "packages/*/test/**/*.tsx",
+    "apps/*/src/**/*.ts",
+    "apps/*/src/**/*.tsx",
+    "apps/*/test/**/*.ts",
+    "apps/*/test/**/*.tsx"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "coverage",
+    "packages/kosong/test/type-safety-negative.ts",
+    "**/*.disabled/**",
+    "**/*.disabled"
+  ]
+}

vitest.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from 'vitest/config';
+import { vscodeProjects } from './apps/vscode/vitest.projects';
+
+export default defineConfig({
+  test: {
+    projects: [
+      'packages/*',
+      '!packages/minidb',
+      'apps/kimi-code',
+      'apps/vis/server',
+      'apps/vis/web',
+      ...vscodeProjects,
+    ],
+    coverage: {
+      provider: 'v8',
+      include: [
+        'packages/*/src/**/*.ts',
+        'apps/*/src/**/*.ts',
+        'apps/vis/*/src/**/*.{ts,tsx}',
+      ],
+      exclude: ['**/*.test.ts', '**/*.spec.ts', '**/dist/**'],
+      reporter: ['text', 'html'],
+    },
+  },
+});