chore(release): v0.8.0-preview.1

fix prompts denpendence

.github/CODEOWNERS

@@ -0,0 +1,3 @@
+* @tanzhenxin @DennisYu07 @gwinthis @LaZzyMan @pomelo-nwu @Mingholy
+# SDK TypeScript package changes require review from Mingholy
+packages/sdk-typescript/** @Mingholy

.github/workflows/e2e.yml

@@ -18,8 +18,6 @@ jobs:
           - 'sandbox:docker'
         node-version:
           - '20.x'
-          - '22.x'
-          - '24.x'
     steps:
       - name: 'Checkout'
         uses: 'actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8' # ratchet:actions/checkout@v5
@@ -67,10 +65,13 @@ jobs:
           OPENAI_BASE_URL: '${{ secrets.OPENAI_BASE_URL }}'
           OPENAI_MODEL: '${{ secrets.OPENAI_MODEL }}'
           KEEP_OUTPUT: 'true'
-          SANDBOX: '${{ matrix.sandbox }}'
           VERBOSE: 'true'
         run: |-
-          npm run "test:integration:${SANDBOX}"
+          if [[ "${{ matrix.sandbox }}" == "sandbox:docker" ]]; then
+            npm run test:integration:sandbox:docker
+          else
+            npm run test:integration:sandbox:none
+          fi
 
   e2e-test-macos:
     name: 'E2E Test - macOS'

.github/workflows/release-sdk.yml

@@ -33,6 +33,10 @@ on:
         type: 'boolean'
         default: false
 
+concurrency:
+  group: '${{ github.workflow }}'
+  cancel-in-progress: false
+
 jobs:
   release-sdk:
     runs-on: 'ubuntu-latest'
@@ -46,6 +50,7 @@ jobs:
       packages: 'write'
       id-token: 'write'
       issues: 'write'
+      pull-requests: 'write'
     outputs:
       RELEASE_TAG: '${{ steps.version.outputs.RELEASE_TAG }}'
 
@@ -86,6 +91,8 @@ jobs:
         with:
           node-version-file: '.nvmrc'
           cache: 'npm'
+          registry-url: 'https://registry.npmjs.org'
+          scope: '@qwen-code'
 
       - name: 'Install Dependencies'
         run: |-
@@ -121,6 +128,19 @@ jobs:
           IS_PREVIEW: '${{ steps.vars.outputs.is_preview }}'
           MANUAL_VERSION: '${{ inputs.version }}'
 
+      - name: 'Set SDK package version (local only)'
+        env:
+          RELEASE_VERSION: '${{ steps.version.outputs.RELEASE_VERSION }}'
+        run: |-
+          # Ensure the package version matches the computed release version.
+          # This is required for nightly/preview because npm does not allow re-publishing the same version.
+          npm version -w @qwen-code/sdk "${RELEASE_VERSION}" --no-git-tag-version --allow-same-version
+
+      - name: 'Build CLI Bundle'
+        run: |
+          npm run build
+          npm run bundle
+
       - name: 'Run Tests'
         if: |-
           ${{ github.event.inputs.force_skip_tests != 'true' }}
@@ -132,13 +152,6 @@ jobs:
           OPENAI_BASE_URL: '${{ secrets.OPENAI_BASE_URL }}'
           OPENAI_MODEL: '${{ secrets.OPENAI_MODEL }}'
 
-      - name: 'Build CLI for Integration Tests'
-        if: |-
-          ${{ github.event.inputs.force_skip_tests != 'true' }}
-        run: |
-          npm run build
-          npm run bundle
-
       - name: 'Run SDK Integration Tests'
         if: |-
           ${{ github.event.inputs.force_skip_tests != 'true' }}
@@ -155,7 +168,21 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
 
+      - name: 'Build SDK'
+        working-directory: 'packages/sdk-typescript'
+        run: |-
+          npm run build
+
+      - name: 'Publish @qwen-code/sdk'
+        working-directory: 'packages/sdk-typescript'
+        run: |-
+          npm publish --access public --tag=${{ steps.version.outputs.NPM_TAG }} ${{ steps.vars.outputs.is_dry_run == 'true' && '--dry-run' || '' }}
+        env:
+          NODE_AUTH_TOKEN: '${{ secrets.NPM_TOKEN }}'
+
       - name: 'Create and switch to a release branch'
+        if: |-
+          ${{ steps.vars.outputs.is_dry_run == 'false' && steps.vars.outputs.is_nightly == 'false' && steps.vars.outputs.is_preview == 'false' }}
         id: 'release_branch'
         env:
           RELEASE_TAG: '${{ steps.version.outputs.RELEASE_TAG }}'
@@ -164,50 +191,22 @@ jobs:
           git switch -c "${BRANCH_NAME}"
           echo "BRANCH_NAME=${BRANCH_NAME}" >> "${GITHUB_OUTPUT}"
 
-      - name: 'Update package version'
-        working-directory: 'packages/sdk-typescript'
-        env:
-          RELEASE_VERSION: '${{ steps.version.outputs.RELEASE_VERSION }}'
-        run: |-
-          npm version "${RELEASE_VERSION}" --no-git-tag-version --allow-same-version
-
-      - name: 'Commit and Conditionally Push package version'
+      - name: 'Commit and Push package version (stable only)'
+        if: |-
+          ${{ steps.vars.outputs.is_dry_run == 'false' && steps.vars.outputs.is_nightly == 'false' && steps.vars.outputs.is_preview == 'false' }}
         env:
           BRANCH_NAME: '${{ steps.release_branch.outputs.BRANCH_NAME }}'
-          IS_DRY_RUN: '${{ steps.vars.outputs.is_dry_run }}'
           RELEASE_TAG: '${{ steps.version.outputs.RELEASE_TAG }}'
         run: |-
-          git add packages/sdk-typescript/package.json
+          # Only persist version bumps after a successful publish.
+          git add packages/sdk-typescript/package.json package-lock.json
           if git diff --staged --quiet; then
             echo "No version changes to commit"
           else
             git commit -m "chore(release): sdk-typescript ${RELEASE_TAG}"
           fi
-          if [[ "${IS_DRY_RUN}" == "false" ]]; then
-            echo "Pushing release branch to remote..."
-            git push --set-upstream origin "${BRANCH_NAME}" --follow-tags
-          else
-            echo "Dry run enabled. Skipping push."
-          fi
-
-      - name: 'Build SDK'
-        working-directory: 'packages/sdk-typescript'
-        run: |-
-          npm run build
-
-      - name: 'Configure npm for publishing'
-        uses: 'actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020' # ratchet:actions/setup-node@v4
-        with:
-          node-version-file: '.nvmrc'
-          registry-url: 'https://registry.npmjs.org'
-          scope: '@qwen-code'
-
-      - name: 'Publish @qwen-code/sdk'
-        working-directory: 'packages/sdk-typescript'
-        run: |-
-          npm publish --access public --tag=${{ steps.version.outputs.NPM_TAG }} ${{ steps.vars.outputs.is_dry_run == 'true' && '--dry-run' || '' }}
-        env:
-          NODE_AUTH_TOKEN: '${{ secrets.NPM_TOKEN }}'
+          echo "Pushing release branch to remote..."
+          git push --set-upstream origin "${BRANCH_NAME}" --follow-tags
 
       - name: 'Create GitHub Release and Tag'
         if: |-
@@ -217,12 +216,57 @@ jobs:
           RELEASE_BRANCH: '${{ steps.release_branch.outputs.BRANCH_NAME }}'
           RELEASE_TAG: '${{ steps.version.outputs.RELEASE_TAG }}'
           PREVIOUS_RELEASE_TAG: '${{ steps.version.outputs.PREVIOUS_RELEASE_TAG }}'
+          IS_NIGHTLY: '${{ steps.vars.outputs.is_nightly }}'
+          IS_PREVIEW: '${{ steps.vars.outputs.is_preview }}'
+          REF: '${{ github.event.inputs.ref || github.sha }}'
         run: |-
+          # For stable releases, use the release branch; for nightly/preview, use the current ref
+          if [[ "${IS_NIGHTLY}" == "true" || "${IS_PREVIEW}" == "true" ]]; then
+            TARGET="${REF}"
+            PRERELEASE_FLAG="--prerelease"
+          else
+            TARGET="${RELEASE_BRANCH}"
+            PRERELEASE_FLAG=""
+          fi
+
           gh release create "sdk-typescript-${RELEASE_TAG}" \
-            --target "$RELEASE_BRANCH" \
+            --target "${TARGET}" \
             --title "SDK TypeScript Release ${RELEASE_TAG}" \
             --notes-start-tag "sdk-typescript-${PREVIOUS_RELEASE_TAG}" \
-            --generate-notes
+            --generate-notes \
+            ${PRERELEASE_FLAG}
+
+      - name: 'Create PR to merge release branch into main'
+        if: |-
+          ${{ steps.vars.outputs.is_dry_run == 'false' && steps.vars.outputs.is_nightly == 'false' && steps.vars.outputs.is_preview == 'false' }}
+        id: 'pr'
+        env:
+          GITHUB_TOKEN: '${{ secrets.CI_BOT_PAT }}'
+          RELEASE_BRANCH: '${{ steps.release_branch.outputs.BRANCH_NAME }}'
+          RELEASE_TAG: '${{ steps.version.outputs.RELEASE_TAG }}'
+        run: |-
+          set -euo pipefail
+
+          pr_url="$(gh pr list --head "${RELEASE_BRANCH}" --base main --json url --jq '.[0].url')"
+          if [[ -z "${pr_url}" ]]; then
+            pr_url="$(gh pr create \
+              --base main \
+              --head "${RELEASE_BRANCH}" \
+              --title "chore(release): sdk-typescript ${RELEASE_TAG}" \
+              --body "Automated release PR for sdk-typescript ${RELEASE_TAG}.")"
+          fi
+
+          echo "PR_URL=${pr_url}" >> "${GITHUB_OUTPUT}"
+
+      - name: 'Enable auto-merge for release PR'
+        if: |-
+          ${{ steps.vars.outputs.is_dry_run == 'false' && steps.vars.outputs.is_nightly == 'false' && steps.vars.outputs.is_preview == 'false' }}
+        env:
+          GITHUB_TOKEN: '${{ secrets.CI_BOT_PAT }}'
+          PR_URL: '${{ steps.pr.outputs.PR_URL }}'
+        run: |-
+          set -euo pipefail
+          gh pr merge "${PR_URL}" --merge --auto --delete-branch
 
       - name: 'Create Issue on Failure'
         if: |-

.github/workflows/release.yml

@@ -133,8 +133,8 @@ jobs:
           ${{ github.event.inputs.force_skip_tests != 'true' }}
         run: |
           npm run preflight
-          npm run test:integration:sandbox:none
-          npm run test:integration:sandbox:docker
+          npm run test:integration:cli:sandbox:none
+          npm run test:integration:cli:sandbox:docker
         env:
           OPENAI_API_KEY: '${{ secrets.OPENAI_API_KEY }}'
           OPENAI_BASE_URL: '${{ secrets.OPENAI_BASE_URL }}'

.gitignore

@@ -23,6 +23,7 @@ package-lock.json
 .idea
 *.iml
 .cursor
+.qoder
 
 # OS metadata
 .DS_Store

CONTRIBUTING.md

@@ -2,27 +2,6 @@
 
 We would love to accept your patches and contributions to this project.
 
-## Before you begin
-
-### Sign our Contributor License Agreement
-
-Contributions to this project must be accompanied by a
-[Contributor License Agreement](https://cla.developers.google.com/about) (CLA).
-You (or your employer) retain the copyright to your contribution; this simply
-gives us permission to use and redistribute your contributions as part of the
-project.
-
-If you or your current employer have already signed the Google CLA (even if it
-was for a different project), you probably don't need to do it again.
-
-Visit <https://cla.developers.google.com/> to see your current agreements or to
-sign a new one.
-
-### Review our Community Guidelines
-
-This project follows [Google's Open Source Community
-Guidelines](https://opensource.google/conduct/).
-
 ## Contribution Process
 
 ### Code Reviews
@@ -74,12 +53,6 @@ Your PR should have a clear, descriptive title and a detailed description of the
 
 In the PR description, explain the "why" behind your changes and link to the relevant issue (e.g., `Fixes #123`).
 
-## Forking
-
-If you are forking the repository you will be able to run the Build, Test and Integration test workflows. However in order to make the integration tests run you'll need to add a [GitHub Repository Secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) with a value of `GEMINI_API_KEY` and set that to a valid API key that you have available. Your key and secret are private to your repo; no one without access can see your key and you cannot see any secrets related to this repo.
-
-Additionally you will need to click on the `Actions` tab and enable workflows for your repository, you'll find it's the large blue button in the center of the screen.
-
 ## Development Setup and Workflow
 
 This section guides contributors on how to build, modify, and understand the development setup of this project.
@@ -98,8 +71,8 @@ This section guides contributors on how to build, modify, and understand the dev
 To clone the repository:
 
 ```bash
-git clone https://github.com/google-gemini/gemini-cli.git # Or your fork's URL
-cd gemini-cli
+git clone https://github.com/QwenLM/qwen-code.git # Or your fork's URL
+cd qwen-code
 ```
 
 To install dependencies defined in `package.json` as well as root dependencies:
@@ -118,9 +91,9 @@ This command typically compiles TypeScript to JavaScript, bundles assets, and pr
 
 ### Enabling Sandboxing
 
-[Sandboxing](#sandboxing) is highly recommended and requires, at a minimum, setting `GEMINI_SANDBOX=true` in your `~/.env` and ensuring a sandboxing provider (e.g. `macOS Seatbelt`, `docker`, or `podman`) is available. See [Sandboxing](#sandboxing) for details.
+[Sandboxing](#sandboxing) is highly recommended and requires, at a minimum, setting `QWEN_SANDBOX=true` in your `~/.env` and ensuring a sandboxing provider (e.g. `macOS Seatbelt`, `docker`, or `podman`) is available. See [Sandboxing](#sandboxing) for details.
 
-To build both the `gemini` CLI utility and the sandbox container, run `build:all` from the root directory:
+To build both the `qwen-code` CLI utility and the sandbox container, run `build:all` from the root directory:
 
 ```bash
 npm run build:all
@@ -130,13 +103,13 @@ To skip building the sandbox container, you can use `npm run build` instead.
 
 ### Running
 
-To start the Gemini CLI from the source code (after building), run the following command from the root directory:
+To start the Qwen Code application from the source code (after building), run the following command from the root directory:
 
 ```bash
 npm start
 ```
 
-If you'd like to run the source build outside of the gemini-cli folder, you can utilize `npm link path/to/gemini-cli/packages/cli` (see: [docs](https://docs.npmjs.com/cli/v9/commands/npm-link)) or `alias gemini="node path/to/gemini-cli/packages/cli"` to run with `gemini`
+If you'd like to run the source build outside of the qwen-code folder, you can utilize `npm link path/to/qwen-code/packages/cli` (see: [docs](https://docs.npmjs.com/cli/v9/commands/npm-link)) to run with `qwen-code`
 
 ### Running Tests
 
@@ -154,7 +127,7 @@ This will run tests located in the `packages/core` and `packages/cli` directorie
 
 #### Integration Tests
 
-The integration tests are designed to validate the end-to-end functionality of the Gemini CLI. They are not run as part of the default `npm run test` command.
+The integration tests are designed to validate the end-to-end functionality of Qwen Code. They are not run as part of the default `npm run test` command.
 
 To run the integration tests, use the following command:
 
@@ -209,19 +182,61 @@ npm run lint
 ### Coding Conventions
 
 - Please adhere to the coding style, patterns, and conventions used throughout the existing codebase.
-- Consult [QWEN.md](https://github.com/QwenLM/qwen-code/blob/main/QWEN.md) (typically found in the project root) for specific instructions related to AI-assisted development, including conventions for React, comments, and Git usage.
 - **Imports:** Pay special attention to import paths. The project uses ESLint to enforce restrictions on relative imports between packages.
 
 ### Project Structure
 
 - `packages/`: Contains the individual sub-packages of the project.
   - `cli/`: The command-line interface.
-  - `core/`: The core backend logic for the Gemini CLI.
+  - `core/`: The core backend logic for Qwen Code.
 - `docs/`: Contains all project documentation.
 - `scripts/`: Utility scripts for building, testing, and development tasks.
 
 For more detailed architecture, see `docs/architecture.md`.
 
+## Documentation Development
+
+This section describes how to develop and preview the documentation locally.
+
+### Prerequisites
+
+1. Ensure you have Node.js (version 18+) installed
+2. Have npm or yarn available
+
+### Setup Documentation Site Locally
+
+To work on the documentation and preview changes locally:
+
+1. Navigate to the `docs-site` directory:
+
+   ```bash
+   cd docs-site
+   ```
+
+2. Install dependencies:
+
+   ```bash
+   npm install
+   ```
+
+3. Link the documentation content from the main `docs` directory:
+
+   ```bash
+   npm run link
+   ```
+
+   This creates a symbolic link from `../docs` to `content` in the docs-site project, allowing the documentation content to be served by the Next.js site.
+
+4. Start the development server:
+
+   ```bash
+   npm run dev
+   ```
+
+5. Open [http://localhost:3000](http://localhost:3000) in your browser to see the documentation site with live updates as you make changes.
+
+Any changes made to the documentation files in the main `docs` directory will be reflected immediately in the documentation site.
+
 ## Debugging
 
 ### VS Code:
@@ -231,7 +246,7 @@ For more detailed architecture, see `docs/architecture.md`.
     ```bash
     npm run debug
     ```
-    This command runs `node --inspect-brk dist/gemini.js` within the `packages/cli` directory, pausing execution until a debugger attaches. You can then open `chrome://inspect` in your Chrome browser to connect to the debugger.
+    This command runs `node --inspect-brk dist/index.js` within the `packages/cli` directory, pausing execution until a debugger attaches. You can then open `chrome://inspect` in your Chrome browser to connect to the debugger.
 2.  In VS Code, use the "Attach" launch configuration (found in `.vscode/launch.json`).
 
 Alternatively, you can use the "Launch Program" configuration in VS Code if you prefer to launch the currently open file directly, but 'F5' is generally recommended.
@@ -239,16 +254,16 @@ Alternatively, you can use the "Launch Program" configuration in VS Code if you
 To hit a breakpoint inside the sandbox container run:
 
 ```bash
-DEBUG=1 gemini
+DEBUG=1 qwen-code
 ```
 
-**Note:** If you have `DEBUG=true` in a project's `.env` file, it won't affect gemini-cli due to automatic exclusion. Use `.gemini/.env` files for gemini-cli specific debug settings.
+**Note:** If you have `DEBUG=true` in a project's `.env` file, it won't affect qwen-code due to automatic exclusion. Use `.qwen-code/.env` files for qwen-code specific debug settings.
 
 ### React DevTools
 
 To debug the CLI's React-based UI, you can use React DevTools. Ink, the library used for the CLI's interface, is compatible with React DevTools version 4.x.
 
-1.  **Start the Gemini CLI in development mode:**
+1.  **Start the Qwen Code application in development mode:**
 
     ```bash
     DEV=true npm start
@@ -270,23 +285,10 @@ To debug the CLI's React-based UI, you can use React DevTools. Ink, the library
     ```
 
     Your running CLI application should then connect to React DevTools.
-    ![](/docs/assets/connected_devtools.png)
 
 ## Sandboxing
 
-### macOS Seatbelt
-
-On macOS, `qwen` uses Seatbelt (`sandbox-exec`) under a `permissive-open` profile (see `packages/cli/src/utils/sandbox-macos-permissive-open.sb`) that restricts writes to the project folder but otherwise allows all other operations and outbound network traffic ("open") by default. You can switch to a `restrictive-closed` profile (see `packages/cli/src/utils/sandbox-macos-restrictive-closed.sb`) that declines all operations and outbound network traffic ("closed") by default by setting `SEATBELT_PROFILE=restrictive-closed` in your environment or `.env` file. Available built-in profiles are `{permissive,restrictive}-{open,closed,proxied}` (see below for proxied networking). You can also switch to a custom profile `SEATBELT_PROFILE=<profile>` if you also create a file `.qwen/sandbox-macos-<profile>.sb` under your project settings directory `.qwen`.
-
-### Container-based Sandboxing (All Platforms)
-
-For stronger container-based sandboxing on macOS or other platforms, you can set `GEMINI_SANDBOX=true|docker|podman|<command>` in your environment or `.env` file. The specified command (or if `true` then either `docker` or `podman`) must be installed on the host machine. Once enabled, `npm run build:all` will build a minimal container ("sandbox") image and `npm start` will launch inside a fresh instance of that container. The first build can take 20-30s (mostly due to downloading of the base image) but after that both build and start overhead should be minimal. Default builds (`npm run build`) will not rebuild the sandbox.
-
-Container-based sandboxing mounts the project directory (and system temp directory) with read-write access and is started/stopped/removed automatically as you start/stop Gemini CLI. Files created within the sandbox should be automatically mapped to your user/group on host machine. You can easily specify additional mounts, ports, or environment variables by setting `SANDBOX_{MOUNTS,PORTS,ENV}` as needed. You can also fully customize the sandbox for your projects by creating the files `.qwen/sandbox.Dockerfile` and/or `.qwen/sandbox.bashrc` under your project settings directory (`.qwen`) and running `qwen` with `BUILD_SANDBOX=1` to trigger building of your custom sandbox.
-
-#### Proxied Networking
-
-All sandboxing methods, including macOS Seatbelt using `*-proxied` profiles, support restricting outbound network traffic through a custom proxy server that can be specified as `GEMINI_SANDBOX_PROXY_COMMAND=<command>`, where `<command>` must start a proxy server that listens on `:::8877` for relevant requests. See `docs/examples/proxy-script.md` for a minimal proxy that only allows `HTTPS` connections to `example.com:443` (e.g. `curl https://example.com`) and declines all other requests. The proxy is started and stopped automatically alongside the sandbox.
+> TBD
 
 ## Manual Publish
 

Makefile

@@ -1,9 +1,9 @@
-# Makefile for gemini-cli
+# Makefile for qwen-code
 
 .PHONY: help install build build-sandbox build-all test lint format preflight clean start debug release run-npx create-alias
 
 help:
-	@echo "Makefile for gemini-cli"
+	@echo "Makefile for qwen-code"
 	@echo ""
 	@echo "Usage:"
 	@echo "  make install          - Install npm dependencies"
@@ -14,11 +14,11 @@ help:
 	@echo "  make format           - Format the code"
 	@echo "  make preflight        - Run formatting, linting, and tests"
 	@echo "  make clean            - Remove generated files"
-	@echo "  make start            - Start the Gemini CLI"
-	@echo "  make debug            - Start the Gemini CLI in debug mode"
+	@echo "  make start            - Start the Qwen Code CLI"
+	@echo "  make debug            - Start the Qwen Code CLI in debug mode"
 	@echo ""
 	@echo "  make run-npx          - Run the CLI using npx (for testing the published package)"
-	@echo "  make create-alias     - Create a 'gemini' alias for your shell"
+	@echo "  make create-alias     - Create a 'qwen' alias for your shell"
 
 install:
 	npm install

README.md

@@ -1,382 +1,153 @@
-# Qwen Code
-
 <div align="center">
 
-![Qwen Code Screenshot](./docs/assets/qwen-screenshot.png)
-
 [![npm version](https://img.shields.io/npm/v/@qwen-code/qwen-code.svg)](https://www.npmjs.com/package/@qwen-code/qwen-code)
 [![License](https://img.shields.io/github/license/QwenLM/qwen-code.svg)](./LICENSE)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)
 [![Downloads](https://img.shields.io/npm/dm/@qwen-code/qwen-code.svg)](https://www.npmjs.com/package/@qwen-code/qwen-code)
 
-**AI-powered command-line workflow tool for developers**
+**An open-source AI agent that lives in your terminal.**
 
-[Installation](#installation) • [Quick Start](#quick-start) • [Features](#key-features) • [Documentation](./docs/) • [Contributing](./CONTRIBUTING.md)
+<a href="https://qwenlm.github.io/qwen-code-docs/zh/users/overview">中文</a> |
+<a href="https://qwenlm.github.io/qwen-code-docs/de/users/overview">Deutsch</a> |
+<a href="https://qwenlm.github.io/qwen-code-docs/fr/users/overview">français</a> |
+<a href="https://qwenlm.github.io/qwen-code-docs/ja/users/overview">日本語</a> |
+<a href="https://qwenlm.github.io/qwen-code-docs/ru/users/overview">Русский</a> |
+<a href="https://qwenlm.github.io/qwen-code-docs/pt-BR/users/overview">Português (Brasil)</a>
 
 </div>
 
-<div align="center">
-  
-  <a href="https://qwenlm.github.io/qwen-code-docs/de/">Deutsch</a> | 
-  <a href="https://qwenlm.github.io/qwen-code-docs/fr">français</a> | 
-  <a href="https://qwenlm.github.io/qwen-code-docs/ja/">日本語</a> | 
-  <a href="https://qwenlm.github.io/qwen-code-docs/ru">Русский</a> | 
-  <a href="https://qwenlm.github.io/qwen-code-docs/zh/">中文</a>
-  
-</div>
+Qwen Code is an open-source AI agent for the terminal, optimized for [Qwen3-Coder](https://github.com/QwenLM/Qwen3-Coder). It helps you understand large codebases, automate tedious work, and ship faster.
 
-Qwen Code is a powerful command-line AI workflow tool adapted from [**Gemini CLI**](https://github.com/google-gemini/gemini-cli), specifically optimized for [Qwen3-Coder](https://github.com/QwenLM/Qwen3-Coder) models. It enhances your development workflow with advanced code understanding, automated tasks, and intelligent assistance.
+![](https://gw.alicdn.com/imgextra/i1/O1CN01D2DviS1wwtEtMwIzJ_!!6000000006373-2-tps-1600-900.png)
 
-## 💡 Free Options Available
+## Why Qwen Code?
 
-Get started with Qwen Code at no cost using any of these free options:
-
-### 🔥 Qwen OAuth (Recommended)
-
-- **2,000 requests per day** with no token limits
-- **60 requests per minute** rate limit
-- Simply run `qwen` and authenticate with your qwen.ai account
-- Automatic credential management and refresh
-- Use `/auth` command to switch to Qwen OAuth if you have initialized with OpenAI compatible mode
-
-### 🌏 Regional Free Tiers
-
-- **Mainland China**: ModelScope offers **2,000 free API calls per day**
-- **International**: OpenRouter provides **up to 1,000 free API calls per day** worldwide
-
-For detailed setup instructions, see [Authorization](#authorization).
-
-> [!WARNING]
-> **Token Usage Notice**: Qwen Code may issue multiple API calls per cycle, resulting in higher token usage (similar to Claude Code). We're actively optimizing API efficiency.
-
-## Key Features
-
-- **Code Understanding & Editing** - Query and edit large codebases beyond traditional context window limits
-- **Workflow Automation** - Automate operational tasks like handling pull requests and complex rebases
-- **Enhanced Parser** - Adapted parser specifically optimized for Qwen-Coder models
-- **Vision Model Support** - Automatically detect images in your input and seamlessly switch to vision-capable models for multimodal analysis
+- **OpenAI-compatible, OAuth free tier**: use an OpenAI-compatible API, or sign in with Qwen OAuth to get 2,000 free requests/day.
+- **Open-source, co-evolving**: both the framework and the Qwen3-Coder model are open-source—and they ship and evolve together.
+- **Agentic workflow, feature-rich**: rich built-in tools (Skills, SubAgents, Plan Mode) for a full agentic workflow and a Claude Code-like experience.
+- **Terminal-first, IDE-friendly**: built for developers who live in the command line, with optional integration for VS Code, Zed, and JetBrains IDEs.
 
 ## Installation
 
-### Prerequisites
-
-Ensure you have [Node.js version 20](https://nodejs.org/en/download) or higher installed.
+#### Prerequisites
 
 ```bash
+# Node.js 20+
 curl -qL https://www.npmjs.com/install.sh | sh
 ```
 
-### Install from npm
+#### NPM (recommended)
 
 ```bash
 npm install -g @qwen-code/qwen-code@latest
-qwen --version
 ```
 
-### Install from source
-
-```bash
-git clone https://github.com/QwenLM/qwen-code.git
-cd qwen-code
-npm install
-npm install -g .
-```
-
-### Install globally with Homebrew (macOS/Linux)
+#### Homebrew (macOS, Linux)
 
 ```bash
 brew install qwen-code
 ```
 
-## VS Code Extension
-
-In addition to the CLI tool, Qwen Code also provides a **VS Code extension** that brings AI-powered coding assistance directly into your editor with features like file system operations, native diffing, interactive chat, and more.
-
-> 📦 The extension is currently in development. For installation, features, and development guide, see the [VS Code Extension README](./packages/vscode-ide-companion/README.md).
-
 ## Quick Start
 
 ```bash
-# Start Qwen Code
+# Start Qwen Code (interactive)
 qwen
 
-# Example commands
-> Explain this codebase structure
-> Help me refactor this function
-> Generate unit tests for this module
+# Then, in the session:
+/help
+/auth
 ```
 
-### Session Management
+On first use, you'll be prompted to sign in. You can run `/auth` anytime to switch authentication methods.
 
-Control your token usage with configurable session limits to optimize costs and performance.
+Example prompts:
 
-#### Configure Session Token Limit
-
-Create or edit `.qwen/settings.json` in your home directory:
-
-```json
-{
-  "sessionTokenLimit": 32000
-}
+```text
+What does this project do?
+Explain the codebase structure.
+Help me refactor this function.
+Generate unit tests for this module.
 ```
 
-#### Session Commands
-
-- **`/compress`** - Compress conversation history to continue within token limits
-- **`/clear`** - Clear all conversation history and start fresh
-- **`/stats`** - Check current token usage and limits
-
-> 📝 **Note**: Session token limit applies to a single conversation, not cumulative API calls.
-
-### Vision Model Configuration
-
-Qwen Code includes intelligent vision model auto-switching that detects images in your input and can automatically switch to vision-capable models for multimodal analysis. **This feature is enabled by default** - when you include images in your queries, you'll see a dialog asking how you'd like to handle the vision model switch.
-
-#### Skip the Switch Dialog (Optional)
-
-If you don't want to see the interactive dialog each time, configure the default behavior in your `.qwen/settings.json`:
-
-```json
-{
-  "experimental": {
-    "vlmSwitchMode": "once"
-  }
-}
-```
-
-**Available modes:**
-
-- **`"once"`** - Switch to vision model for this query only, then revert
-- **`"session"`** - Switch to vision model for the entire session
-- **`"persist"`** - Continue with current model (no switching)
-- **Not set** - Show interactive dialog each time (default)
-
-#### Command Line Override
-
-You can also set the behavior via command line:
-
-```bash
-# Switch once per query
-qwen --vlm-switch-mode once
-
-# Switch for entire session
-qwen --vlm-switch-mode session
-
-# Never switch automatically
-qwen --vlm-switch-mode persist
-```
-
-#### Disable Vision Models (Optional)
-
-To completely disable vision model support, add to your `.qwen/settings.json`:
-
-```json
-{
-  "experimental": {
-    "visionModelPreview": false
-  }
-}
-```
-
-> 💡 **Tip**: In YOLO mode (`--yolo`), vision switching happens automatically without prompts when images are detected.
-
-### Authorization
-
-Choose your preferred authentication method based on your needs:
-
-#### 1. Qwen OAuth (🚀 Recommended - Start in 30 seconds)
-
-The easiest way to get started - completely free with generous quotas:
-
-```bash
-# Just run this command and follow the browser authentication
-qwen
-```
-
-**What happens:**
-
-1. **Instant Setup**: CLI opens your browser automatically
-2. **One-Click Login**: Authenticate with your qwen.ai account
-3. **Automatic Management**: Credentials cached locally for future use
-4. **No Configuration**: Zero setup required - just start coding!
-
-**Free Tier Benefits:**
-
-- ✅ **2,000 requests/day** (no token counting needed)
-- ✅ **60 requests/minute** rate limit
-- ✅ **Automatic credential refresh**
-- ✅ **Zero cost** for individual users
-- ℹ️ **Note**: Model fallback may occur to maintain service quality
-
-#### 2. OpenAI-Compatible API
-
-Use API keys for OpenAI or other compatible providers:
-
-**Configuration Methods:**
-
-1. **Environment Variables**
-
-   ```bash
-   export OPENAI_API_KEY="your_api_key_here"
-   export OPENAI_BASE_URL="your_api_endpoint"
-   export OPENAI_MODEL="your_model_choice"
-   ```
-
-2. **Project `.env` File**
-   Create a `.env` file in your project root:
-   ```env
-   OPENAI_API_KEY=your_api_key_here
-   OPENAI_BASE_URL=your_api_endpoint
-   OPENAI_MODEL=your_model_choice
-   ```
-
-**API Provider Options**
-
-> ⚠️ **Regional Notice:**
->
-> - **Mainland China**: Use Alibaba Cloud Bailian or ModelScope
-> - **International**: Use Alibaba Cloud ModelStudio or OpenRouter
-
 <details>
-<summary><b>🇨🇳 For Users in Mainland China</b></summary>
+<summary>Click to watch a demo video</summary>
 
-**Option 1: Alibaba Cloud Bailian** ([Apply for API Key](https://bailian.console.aliyun.com/))
-
-```bash
-export OPENAI_API_KEY="your_api_key_here"
-export OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
-export OPENAI_MODEL="qwen3-coder-plus"
-```
-
-**Option 2: ModelScope (Free Tier)** ([Apply for API Key](https://modelscope.cn/docs/model-service/API-Inference/intro))
-
-- ✅ **2,000 free API calls per day**
-- ⚠️ Connect your Aliyun account to avoid authentication errors
-
-```bash
-export OPENAI_API_KEY="your_api_key_here"
-export OPENAI_BASE_URL="https://api-inference.modelscope.cn/v1"
-export OPENAI_MODEL="Qwen/Qwen3-Coder-480B-A35B-Instruct"
-```
+<video src="https://cloud.video.taobao.com/vod/HLfyppnCHplRV9Qhz2xSqeazHeRzYtG-EYJnHAqtzkQ.mp4" controls>
+Your browser does not support the video tag.
+</video>
 
 </details>
 
-<details>
-<summary><b>🌍 For International Users</b></summary>
+## Authentication
 
-**Option 1: Alibaba Cloud ModelStudio** ([Apply for API Key](https://modelstudio.console.alibabacloud.com/))
+Qwen Code supports two authentication methods:
+
+- **Qwen OAuth (recommended & free)**: sign in with your `qwen.ai` account in a browser.
+- **OpenAI-compatible API**: use `OPENAI_API_KEY` (and optionally a custom base URL / model).
+
+#### Qwen OAuth (recommended)
+
+Start `qwen`, then run:
 
 ```bash
-export OPENAI_API_KEY="your_api_key_here"
-export OPENAI_BASE_URL="https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
-export OPENAI_MODEL="qwen3-coder-plus"
+/auth
 ```
 
-**Option 2: OpenRouter (Free Tier Available)** ([Apply for API Key](https://openrouter.ai/))
+Choose **Qwen OAuth** and complete the browser flow. Your credentials are cached locally so you usually won't need to log in again.
+
+#### OpenAI-compatible API (API key)
+
+Environment variables (recommended for CI / headless environments):
 
 ```bash
-export OPENAI_API_KEY="your_api_key_here"
-export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
-export OPENAI_MODEL="qwen/qwen3-coder:free"
+export OPENAI_API_KEY="your-api-key-here"
+export OPENAI_BASE_URL="https://api.openai.com/v1"  # optional
+export OPENAI_MODEL="gpt-4o"                        # optional
 ```
 
-</details>
+For details (including `.qwen/.env` loading and security notes), see the [authentication guide](https://qwenlm.github.io/qwen-code-docs/en/users/configuration/auth/).
 
-## Usage Examples
+## Usage
 
-### 🔍 Explore Codebases
+As an open-source terminal agent, you can use Qwen Code in four primary ways:
+
+1. Interactive mode (terminal UI)
+2. Headless mode (scripts, CI)
+3. IDE integration (VS Code, Zed)
+4. TypeScript SDK
+
+#### Interactive mode
 
 ```bash
 cd your-project/
 qwen
-
-# Architecture analysis
-> Describe the main pieces of this system's architecture
-> What are the key dependencies and how do they interact?
-> Find all API endpoints and their authentication methods
 ```
 
-### 💻 Code Development
+Run `qwen` in your project folder to launch the interactive terminal UI. Use `@` to reference local files (for example `@src/main.ts`).
+
+#### Headless mode
 
 ```bash
-# Refactoring
-> Refactor this function to improve readability and performance
-> Convert this class to use dependency injection
-> Split this large module into smaller, focused components
-
-# Code generation
-> Create a REST API endpoint for user management
-> Generate unit tests for the authentication module
-> Add error handling to all database operations
+cd your-project/
+qwen -p "your question"
 ```
 
-### 🔄 Automate Workflows
+Use `-p` to run Qwen Code without the interactive UI—ideal for scripts, automation, and CI/CD. Learn more: [Headless mode](https://qwenlm.github.io/qwen-code-docs/en/users/features/headless).
 
-```bash
-# Git automation
-> Analyze git commits from the last 7 days, grouped by feature
-> Create a changelog from recent commits
-> Find all TODO comments and create GitHub issues
+#### IDE integration
 
-# File operations
-> Convert all images in this directory to PNG format
-> Rename all test files to follow the *.test.ts pattern
-> Find and remove all console.log statements
-```
+Use Qwen Code inside your editor (VS Code, Zed, and JetBrains IDEs):
 
-### 🐛 Debugging & Analysis
+- [Use in VS Code](https://qwenlm.github.io/qwen-code-docs/en/users/integration-vscode/)
+- [Use in Zed](https://qwenlm.github.io/qwen-code-docs/en/users/integration-zed/)
+- [Use in JetBrains IDEs](https://qwenlm.github.io/qwen-code-docs/en/users/integration-jetbrains/)
 
-```bash
-# Performance analysis
-> Identify performance bottlenecks in this React component
-> Find all N+1 query problems in the codebase
+#### TypeScript SDK
 
-# Security audit
-> Check for potential SQL injection vulnerabilities
-> Find all hardcoded credentials or API keys
-```
+Build on top of Qwen Code with the TypeScript SDK:
 
-## Popular Tasks
-
-### 📚 Understand New Codebases
-
-```text
-> What are the core business logic components?
-> What security mechanisms are in place?
-> How does the data flow through the system?
-> What are the main design patterns used?
-> Generate a dependency graph for this module
-```
-
-### 🔨 Code Refactoring & Optimization
-
-```text
-> What parts of this module can be optimized?
-> Help me refactor this class to follow SOLID principles
-> Add proper error handling and logging
-> Convert callbacks to async/await pattern
-> Implement caching for expensive operations
-```
-
-### 📝 Documentation & Testing
-
-```text
-> Generate comprehensive JSDoc comments for all public APIs
-> Write unit tests with edge cases for this component
-> Create API documentation in OpenAPI format
-> Add inline comments explaining complex algorithms
-> Generate a README for this module
-```
-
-### 🚀 Development Acceleration
-
-```text
-> Set up a new Express server with authentication
-> Create a React component with TypeScript and tests
-> Implement a rate limiter middleware
-> Add database migrations for new schema
-> Configure CI/CD pipeline for this project
-```
+- [Use the Qwen Code SDK](./packages/sdk-typescript/README.md)
 
 ## Commands & Shortcuts
 
@@ -386,6 +157,7 @@ qwen
 - `/clear` - Clear conversation history
 - `/compress` - Compress history to save tokens
 - `/stats` - Show current session information
+- `/bug` - Submit a bug report
 - `/exit` or `/quit` - Exit Qwen Code
 
 ### Keyboard Shortcuts
@@ -394,6 +166,19 @@ qwen
 - `Ctrl+D` - Exit (on empty line)
 - `Up/Down` - Navigate command history
 
+> Learn more about [Commands](https://qwenlm.github.io/qwen-code-docs/en/users/features/commands/)
+>
+> **Tip**: In YOLO mode (`--yolo`), vision switching happens automatically without prompts when images are detected. Learn more about [Approval Mode](https://qwenlm.github.io/qwen-code-docs/en/users/features/approval-mode/)
+
+## Configuration
+
+Qwen Code can be configured via `settings.json`, environment variables, and CLI flags.
+
+- **User settings**: `~/.qwen/settings.json`
+- **Project settings**: `.qwen/settings.json`
+
+See [settings](https://qwenlm.github.io/qwen-code-docs/en/users/configuration/settings/) for available options and precedence.
+
 ## Benchmark Results
 
 ### Terminal-Bench Performance
@@ -403,24 +188,24 @@ qwen
 | Qwen Code | Qwen3-Coder-480A35 | 37.5%    |
 | Qwen Code | Qwen3-Coder-30BA3B | 31.3%    |
 
-## Development & Contributing
+## Ecosystem
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) to learn how to contribute to the project.
+Looking for a graphical interface?
 
-For detailed authentication setup, see the [authentication guide](./docs/cli/authentication.md).
+- [**AionUi**](https://github.com/iOfficeAI/AionUi) A modern GUI for command-line AI tools including Qwen Code
+- [**Gemini CLI Desktop**](https://github.com/Piebald-AI/gemini-cli-desktop) A cross-platform desktop/web/mobile UI for Qwen Code
 
 ## Troubleshooting
 
-If you encounter issues, check the [troubleshooting guide](docs/troubleshooting.md).
+If you encounter issues, check the [troubleshooting guide](https://qwenlm.github.io/qwen-code-docs/en/users/support/troubleshooting/).
+
+To report a bug from within the CLI, run `/bug` and include a short title and repro steps.
+
+## Connect with Us
+
+- Discord: https://discord.gg/ycKBjdNd
+- Dingtalk: https://qr.dingtalk.com/action/joingroup?code=v1,k1,+FX6Gf/ZDlTahTIRi8AEQhIaBlqykA0j+eBKKdhLeAE=&_dt_no_comment=1&origin=1
 
 ## Acknowledgments
 
 This project is based on [Google Gemini CLI](https://github.com/google-gemini/gemini-cli). We acknowledge and appreciate the excellent work of the Gemini CLI team. Our main contribution focuses on parser-level adaptations to better support Qwen-Coder models.
-
-## License
-
-[LICENSE](./LICENSE)
-
-## Star History
-
-[![Star History Chart](https://api.star-history.com/svg?repos=QwenLM/qwen-code&type=Date)](https://www.star-history.com/#QwenLM/qwen-code&Date)

docs/developers/_meta.ts

@@ -11,6 +11,7 @@ export default {
     type: 'separator',
   },
   'sdk-typescript': 'Typescript SDK',
+  'sdk-java': 'Java SDK(alpha)',
   'Dive Into Qwen Code': {
     title: 'Dive Into Qwen Code',
     type: 'separator',
@@ -18,9 +19,6 @@ export default {
 
   tools: 'Tools',
 
-  extensions: {
-    display: 'hidden',
-  },
   examples: {
     display: 'hidden',
   },

docs/developers/development/npm.md

@@ -202,7 +202,7 @@ This is the most critical stage where files are moved and transformed into their
       - Copies README.md and LICENSE to dist/
       - Copies locales folder for internationalization
       - Creates a clean package.json for distribution with only necessary dependencies
-      - Includes runtime dependencies like tiktoken
+      - Keeps distribution dependencies minimal (no bundled runtime deps)
       - Maintains optional dependencies for node-pty
 
 2.  The JavaScript Bundle is Created:

docs/developers/extensions/extension.md

@@ -1,158 +0,0 @@
-# Qwen Code Extensions
-
-Qwen Code extensions package prompts, MCP servers, and custom commands into a familiar and user-friendly format. With extensions, you can expand the capabilities of Qwen Code and share those capabilities with others. They are designed to be easily installable and shareable.
-
-## Extension management
-
-We offer a suite of extension management tools using `qwen extensions` commands.
-
-Note that these commands are not supported from within the CLI, although you can list installed extensions using the `/extensions list` subcommand.
-
-Note that all of these commands will only be reflected in active CLI sessions on restart.
-
-### Installing an extension
-
-You can install an extension using `qwen extensions install` with either a GitHub URL or a local path`.
-
-Note that we create a copy of the installed extension, so you will need to run `qwen extensions update` to pull in changes from both locally-defined extensions and those on GitHub.
-
-```
-qwen extensions install https://github.com/qwen-cli-extensions/security
-```
-
-This will install the Qwen Code Security extension, which offers support for a `/security:analyze` command.
-
-### Uninstalling an extension
-
-To uninstall, run `qwen extensions uninstall extension-name`, so, in the case of the install example:
-
-```
-qwen extensions uninstall qwen-cli-security
-```
-
-### Disabling an extension
-
-Extensions are, by default, enabled across all workspaces. You can disable an extension entirely or for specific workspace.
-
-For example, `qwen extensions disable extension-name` will disable the extension at the user level, so it will be disabled everywhere. `qwen extensions disable extension-name --scope=workspace` will only disable the extension in the current workspace.
-
-### Enabling an extension
-
-You can enable extensions using `qwen extensions enable extension-name`. You can also enable an extension for a specific workspace using `qwen extensions enable extension-name --scope=workspace` from within that workspace.
-
-This is useful if you have an extension disabled at the top-level and only enabled in specific places.
-
-### Updating an extension
-
-For extensions installed from a local path or a git repository, you can explicitly update to the latest version (as reflected in the `qwen-extension.json` `version` field) with `qwen extensions update extension-name`.
-
-You can update all extensions with:
-
-```
-qwen extensions update --all
-```
-
-## Extension creation
-
-We offer commands to make extension development easier.
-
-### Create a boilerplate extension
-
-We offer several example extensions `context`, `custom-commands`, `exclude-tools` and `mcp-server`. You can view these examples [here](https://github.com/QwenLM/qwen-code/tree/main/packages/cli/src/commands/extensions/examples).
-
-To copy one of these examples into a development directory using the type of your choosing, run:
-
-```
-qwen extensions new path/to/directory custom-commands
-```
-
-### Link a local extension
-
-The `qwen extensions link` command will create a symbolic link from the extension installation directory to the development path.
-
-This is useful so you don't have to run `qwen extensions update` every time you make changes you'd like to test.
-
-```
-qwen extensions link path/to/directory
-```
-
-## How it works
-
-On startup, Qwen Code looks for extensions in `<home>/.qwen/extensions`
-
-Extensions exist as a directory that contains a `qwen-extension.json` file. For example:
-
-`<home>/.qwen/extensions/my-extension/qwen-extension.json`
-
-### `qwen-extension.json`
-
-The `qwen-extension.json` file contains the configuration for the extension. The file has the following structure:
-
-```json
-{
-  "name": "my-extension",
-  "version": "1.0.0",
-  "mcpServers": {
-    "my-server": {
-      "command": "node my-server.js"
-    }
-  },
-  "contextFileName": "QWEN.md",
-  "excludeTools": ["run_shell_command"]
-}
-```
-
-- `name`: The name of the extension. This is used to uniquely identify the extension and for conflict resolution when extension commands have the same name as user or project commands. The name should be lowercase or numbers and use dashes instead of underscores or spaces. This is how users will refer to your extension in the CLI. Note that we expect this name to match the extension directory name.
-- `version`: The version of the extension.
-- `mcpServers`: A map of MCP servers to configure. The key is the name of the server, and the value is the server configuration. These servers will be loaded on startup just like MCP servers configured in a [`settings.json` file](./cli/configuration.md). If both an extension and a `settings.json` file configure an MCP server with the same name, the server defined in the `settings.json` file takes precedence.
-  - Note that all MCP server configuration options are supported except for `trust`.
-- `contextFileName`: The name of the file that contains the context for the extension. This will be used to load the context from the extension directory. If this property is not used but a `QWEN.md` file is present in your extension directory, then that file will be loaded.
-- `excludeTools`: An array of tool names to exclude from the model. You can also specify command-specific restrictions for tools that support it, like the `run_shell_command` tool. For example, `"excludeTools": ["run_shell_command(rm -rf)"]` will block the `rm -rf` command. Note that this differs from the MCP server `excludeTools` functionality, which can be listed in the MCP server config. **Important:** Tools specified in `excludeTools` will be disabled for the entire conversation context and will affect all subsequent queries in the current session.
-
-When Qwen Code starts, it loads all the extensions and merges their configurations. If there are any conflicts, the workspace configuration takes precedence.
-
-### Custom commands
-
-Extensions can provide [custom commands](./cli/commands.md#custom-commands) by placing TOML files in a `commands/` subdirectory within the extension directory. These commands follow the same format as user and project custom commands and use standard naming conventions.
-
-**Example**
-
-An extension named `gcp` with the following structure:
-
-```
-.qwen/extensions/gcp/
-├── qwen-extension.json
-└── commands/
-    ├── deploy.toml
-    └── gcs/
-        └── sync.toml
-```
-
-Would provide these commands:
-
-- `/deploy` - Shows as `[gcp] Custom command from deploy.toml` in help
-- `/gcs:sync` - Shows as `[gcp] Custom command from sync.toml` in help
-
-### Conflict resolution
-
-Extension commands have the lowest precedence. When a conflict occurs with user or project commands:
-
-1. **No conflict**: Extension command uses its natural name (e.g., `/deploy`)
-2. **With conflict**: Extension command is renamed with the extension prefix (e.g., `/gcp.deploy`)
-
-For example, if both a user and the `gcp` extension define a `deploy` command:
-
-- `/deploy` - Executes the user's deploy command
-- `/gcp.deploy` - Executes the extension's deploy command (marked with `[gcp]` tag)
-
-## Variables
-
-Qwen Code extensions allow variable substitution in `qwen-extension.json`. This can be useful if e.g., you need the current directory to run an MCP server using `"cwd": "${extensionPath}${/}run.ts"`.
-
-**Supported variables:**
-
-| variable                   | description                                                                                                                                                   |
-| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `${extensionPath}`         | The fully-qualified path of the extension in the user's filesystem e.g., '/Users/username/.qwen/extensions/example-extension'. This will not unwrap symlinks. |
-| `${workspacePath}`         | The fully-qualified path of the current workspace.                                                                                                            |
-| `${/} or ${pathSeparator}` | The path separator (differs per OS).                                                                                                                          |

docs/developers/sdk-java.md

@@ -0,0 +1,312 @@
+# Qwen Code Java SDK
+
+The Qwen Code Java SDK is a minimum experimental SDK for programmatic access to Qwen Code functionality. It provides a Java interface to interact with the Qwen Code CLI, allowing developers to integrate Qwen Code capabilities into their Java applications.
+
+## Requirements
+
+- Java >= 1.8
+- Maven >= 3.6.0 (for building from source)
+- qwen-code >= 0.5.0
+
+### Dependencies
+
+- **Logging**: ch.qos.logback:logback-classic
+- **Utilities**: org.apache.commons:commons-lang3
+- **JSON Processing**: com.alibaba.fastjson2:fastjson2
+- **Testing**: JUnit 5 (org.junit.jupiter:junit-jupiter)
+
+## Installation
+
+Add the following dependency to your Maven `pom.xml`:
+
+```xml
+<dependency>
+    <groupId>com.alibaba</groupId>
+    <artifactId>qwencode-sdk</artifactId>
+    <version>{$version}</version>
+</dependency>
+```
+
+Or if using Gradle, add to your `build.gradle`:
+
+```gradle
+implementation 'com.alibaba:qwencode-sdk:{$version}'
+```
+
+## Building and Running
+
+### Build Commands
+
+```bash
+# Compile the project
+mvn compile
+
+# Run tests
+mvn test
+
+# Package the JAR
+mvn package
+
+# Install to local repository
+mvn install
+```
+
+## Quick Start
+
+The simplest way to use the SDK is through the `QwenCodeCli.simpleQuery()` method:
+
+```java
+public static void runSimpleExample() {
+    List<String> result = QwenCodeCli.simpleQuery("hello world");
+    result.forEach(logger::info);
+}
+```
+
+For more advanced usage with custom transport options:
+
+```java
+public static void runTransportOptionsExample() {
+    TransportOptions options = new TransportOptions()
+            .setModel("qwen3-coder-flash")
+            .setPermissionMode(PermissionMode.AUTO_EDIT)
+            .setCwd("./")
+            .setEnv(new HashMap<String, String>() {{put("CUSTOM_VAR", "value");}})
+            .setIncludePartialMessages(true)
+            .setTurnTimeout(new Timeout(120L, TimeUnit.SECONDS))
+            .setMessageTimeout(new Timeout(90L, TimeUnit.SECONDS))
+            .setAllowedTools(Arrays.asList("read_file", "write_file", "list_directory"));
+
+    List<String> result = QwenCodeCli.simpleQuery("who are you, what are your capabilities?", options);
+    result.forEach(logger::info);
+}
+```
+
+For streaming content handling with custom content consumers:
+
+```java
+public static void runStreamingExample() {
+    QwenCodeCli.simpleQuery("who are you, what are your capabilities?",
+            new TransportOptions().setMessageTimeout(new Timeout(10L, TimeUnit.SECONDS)), new AssistantContentSimpleConsumers() {
+
+                @Override
+                public void onText(Session session, TextAssistantContent textAssistantContent) {
+                    logger.info("Text content received: {}", textAssistantContent.getText());
+                }
+
+                @Override
+                public void onThinking(Session session, ThingkingAssistantContent thingkingAssistantContent) {
+                    logger.info("Thinking content received: {}", thingkingAssistantContent.getThinking());
+                }
+
+                @Override
+                public void onToolUse(Session session, ToolUseAssistantContent toolUseContent) {
+                    logger.info("Tool use content received: {} with arguments: {}",
+                            toolUseContent, toolUseContent.getInput());
+                }
+
+                @Override
+                public void onToolResult(Session session, ToolResultAssistantContent toolResultContent) {
+                    logger.info("Tool result content received: {}", toolResultContent.getContent());
+                }
+
+                @Override
+                public void onOtherContent(Session session, AssistantContent<?> other) {
+                    logger.info("Other content received: {}", other);
+                }
+
+                @Override
+                public void onUsage(Session session, AssistantUsage assistantUsage) {
+                    logger.info("Usage information received: Input tokens: {}, Output tokens: {}",
+                            assistantUsage.getUsage().getInputTokens(), assistantUsage.getUsage().getOutputTokens());
+                }
+            }.setDefaultPermissionOperation(Operation.allow));
+    logger.info("Streaming example completed.");
+}
+```
+
+other examples see src/test/java/com/alibaba/qwen/code/cli/example
+
+## Architecture
+
+The SDK follows a layered architecture:
+
+- **API Layer**: Provides the main entry points through `QwenCodeCli` class with simple static methods for basic usage
+- **Session Layer**: Manages communication sessions with the Qwen Code CLI through the `Session` class
+- **Transport Layer**: Handles the communication mechanism between the SDK and CLI process (currently using process transport via `ProcessTransport`)
+- **Protocol Layer**: Defines data structures for communication based on the CLI protocol
+- **Utils**: Common utilities for concurrent execution, timeout handling, and error management
+
+## Key Features
+
+### Permission Modes
+
+The SDK supports different permission modes for controlling tool execution:
+
+- **`default`**: Write tools are denied unless approved via `canUseTool` callback or in `allowedTools`. Read-only tools execute without confirmation.
+- **`plan`**: Blocks all write tools, instructing AI to present a plan first.
+- **`auto-edit`**: Auto-approve edit tools (edit, write_file) while other tools require confirmation.
+- **`yolo`**: All tools execute automatically without confirmation.
+
+### Session Event Consumers and Assistant Content Consumers
+
+The SDK provides two key interfaces for handling events and content from the CLI:
+
+#### SessionEventConsumers Interface
+
+The `SessionEventConsumers` interface provides callbacks for different types of messages during a session:
+
+- `onSystemMessage`: Handles system messages from the CLI (receives Session and SDKSystemMessage)
+- `onResultMessage`: Handles result messages from the CLI (receives Session and SDKResultMessage)
+- `onAssistantMessage`: Handles assistant messages (AI responses) (receives Session and SDKAssistantMessage)
+- `onPartialAssistantMessage`: Handles partial assistant messages during streaming (receives Session and SDKPartialAssistantMessage)
+- `onUserMessage`: Handles user messages (receives Session and SDKUserMessage)
+- `onOtherMessage`: Handles other types of messages (receives Session and String message)
+- `onControlResponse`: Handles control responses (receives Session and CLIControlResponse)
+- `onControlRequest`: Handles control requests (receives Session and CLIControlRequest, returns CLIControlResponse)
+- `onPermissionRequest`: Handles permission requests (receives Session and CLIControlRequest<CLIControlPermissionRequest>, returns Behavior)
+
+#### AssistantContentConsumers Interface
+
+The `AssistantContentConsumers` interface handles different types of content within assistant messages:
+
+- `onText`: Handles text content (receives Session and TextAssistantContent)
+- `onThinking`: Handles thinking content (receives Session and ThingkingAssistantContent)
+- `onToolUse`: Handles tool use content (receives Session and ToolUseAssistantContent)
+- `onToolResult`: Handles tool result content (receives Session and ToolResultAssistantContent)
+- `onOtherContent`: Handles other content types (receives Session and AssistantContent)
+- `onUsage`: Handles usage information (receives Session and AssistantUsage)
+- `onPermissionRequest`: Handles permission requests (receives Session and CLIControlPermissionRequest, returns Behavior)
+- `onOtherControlRequest`: Handles other control requests (receives Session and ControlRequestPayload, returns ControlResponsePayload)
+
+#### Relationship Between the Interfaces
+
+**Important Note on Event Hierarchy:**
+
+- `SessionEventConsumers` is the **high-level** event processor that handles different message types (system, assistant, user, etc.)
+- `AssistantContentConsumers` is the **low-level** content processor that handles different types of content within assistant messages (text, tools, thinking, etc.)
+
+**Processor Relationship:**
+
+- `SessionEventConsumers` → `AssistantContentConsumers` (SessionEventConsumers uses AssistantContentConsumers to process content within assistant messages)
+
+**Event Derivation Relationships:**
+
+- `onAssistantMessage` → `onText`, `onThinking`, `onToolUse`, `onToolResult`, `onOtherContent`, `onUsage`
+- `onPartialAssistantMessage` → `onText`, `onThinking`, `onToolUse`, `onToolResult`, `onOtherContent`
+- `onControlRequest` → `onPermissionRequest`, `onOtherControlRequest`
+
+**Event Timeout Relationships:**
+
+Each event handler method has a corresponding timeout method that allows customizing the timeout behavior for that specific event:
+
+- `onSystemMessage` ↔ `onSystemMessageTimeout`
+- `onResultMessage` ↔ `onResultMessageTimeout`
+- `onAssistantMessage` ↔ `onAssistantMessageTimeout`
+- `onPartialAssistantMessage` ↔ `onPartialAssistantMessageTimeout`
+- `onUserMessage` ↔ `onUserMessageTimeout`
+- `onOtherMessage` ↔ `onOtherMessageTimeout`
+- `onControlResponse` ↔ `onControlResponseTimeout`
+- `onControlRequest` ↔ `onControlRequestTimeout`
+
+For AssistantContentConsumers timeout methods:
+
+- `onText` ↔ `onTextTimeout`
+- `onThinking` ↔ `onThinkingTimeout`
+- `onToolUse` ↔ `onToolUseTimeout`
+- `onToolResult` ↔ `onToolResultTimeout`
+- `onOtherContent` ↔ `onOtherContentTimeout`
+- `onPermissionRequest` ↔ `onPermissionRequestTimeout`
+- `onOtherControlRequest` ↔ `onOtherControlRequestTimeout`
+
+**Default Timeout Values:**
+
+- `SessionEventSimpleConsumers` default timeout: 180 seconds (Timeout.TIMEOUT_180_SECONDS)
+- `AssistantContentSimpleConsumers` default timeout: 60 seconds (Timeout.TIMEOUT_60_SECONDS)
+
+**Timeout Hierarchy Requirements:**
+
+For proper operation, the following timeout relationships should be maintained:
+
+- `onAssistantMessageTimeout` return value should be greater than `onTextTimeout`, `onThinkingTimeout`, `onToolUseTimeout`, `onToolResultTimeout`, and `onOtherContentTimeout` return values
+- `onControlRequestTimeout` return value should be greater than `onPermissionRequestTimeout` and `onOtherControlRequestTimeout` return values
+
+### Transport Options
+
+The `TransportOptions` class allows configuration of how the SDK communicates with the Qwen Code CLI:
+
+- `pathToQwenExecutable`: Path to the Qwen Code CLI executable
+- `cwd`: Working directory for the CLI process
+- `model`: AI model to use for the session
+- `permissionMode`: Permission mode that controls tool execution
+- `env`: Environment variables to pass to the CLI process
+- `maxSessionTurns`: Limits the number of conversation turns in a session
+- `coreTools`: List of core tools that should be available to the AI
+- `excludeTools`: List of tools to exclude from being available to the AI
+- `allowedTools`: List of tools that are pre-approved for use without additional confirmation
+- `authType`: Authentication type to use for the session
+- `includePartialMessages`: Enables receiving partial messages during streaming responses
+- `skillsEnable`: Enables or disables skills functionality for the session
+- `turnTimeout`: Timeout for a complete turn of conversation
+- `messageTimeout`: Timeout for individual messages within a turn
+- `resumeSessionId`: ID of a previous session to resume
+- `otherOptions`: Additional command-line options to pass to the CLI
+
+### Session Control Features
+
+- **Session creation**: Use `QwenCodeCli.newSession()` to create a new session with custom options
+- **Session management**: The `Session` class provides methods to send prompts, handle responses, and manage session state
+- **Session cleanup**: Always close sessions using `session.close()` to properly terminate the CLI process
+- **Session resumption**: Use `setResumeSessionId()` in `TransportOptions` to resume a previous session
+- **Session interruption**: Use `session.interrupt()` to interrupt a currently running prompt
+- **Dynamic model switching**: Use `session.setModel()` to change the model during a session
+- **Dynamic permission mode switching**: Use `session.setPermissionMode()` to change the permission mode during a session
+
+### Thread Pool Configuration
+
+The SDK uses a thread pool for managing concurrent operations with the following default configuration:
+
+- **Core Pool Size**: 30 threads
+- **Maximum Pool Size**: 100 threads
+- **Keep-Alive Time**: 60 seconds
+- **Queue Capacity**: 300 tasks (using LinkedBlockingQueue)
+- **Thread Naming**: "qwen_code_cli-pool-{number}"
+- **Daemon Threads**: false
+- **Rejected Execution Handler**: CallerRunsPolicy
+
+## Error Handling
+
+The SDK provides specific exception types for different error scenarios:
+
+- `SessionControlException`: Thrown when there's an issue with session control (creation, initialization, etc.)
+- `SessionSendPromptException`: Thrown when there's an issue sending a prompt or receiving a response
+- `SessionClosedException`: Thrown when attempting to use a closed session
+
+## FAQ / Troubleshooting
+
+### Q: Do I need to install the Qwen CLI separately?
+
+A: yes, requires Qwen CLI 0.5.5 or higher.
+
+### Q: What Java versions are supported?
+
+A: The SDK requires Java 1.8 or higher.
+
+### Q: How do I handle long-running requests?
+
+A: The SDK includes timeout utilities. You can configure timeouts using the `Timeout` class in `TransportOptions`.
+
+### Q: Why are some tools not executing?
+
+A: This is likely due to permission modes. Check your permission mode settings and consider using `allowedTools` to pre-approve certain tools.
+
+### Q: How do I resume a previous session?
+
+A: Use the `setResumeSessionId()` method in `TransportOptions` to resume a previous session.
+
+### Q: Can I customize the environment for the CLI process?
+
+A: Yes, use the `setEnv()` method in `TransportOptions` to pass environment variables to the CLI process.
+
+## License
+
+Apache-2.0 - see [LICENSE](./LICENSE) for details.

docs/developers/tools/_meta.ts

@@ -10,4 +10,5 @@ export default {
   'web-search': 'Web Search',
   memory: 'Memory',
   'mcp-server': 'MCP Servers',
+  sandbox: 'Sandboxing',
 };

docs/developers/tools/mcp-server.md

@@ -627,7 +627,12 @@ The MCP integration tracks several states:
 
 ### Schema Compatibility
 
-- **Property stripping:** The system automatically removes certain schema properties (`$schema`, `additionalProperties`) for Qwen API compatibility
+- **Schema compliance mode:** By default (`schemaCompliance: "auto"`), tool schemas are passed through as-is. Set `"model": { "generationConfig": { "schemaCompliance": "openapi_30" } }` in your `settings.json` to convert models to Strict OpenAPI 3.0 format.
+- **OpenAPI 3.0 transformations:** When `openapi_30` mode is enabled, the system handles:
+  - Nullable types: `["string", "null"]` -> `type: "string", nullable: true`
+  - Const values: `const: "foo"` -> `enum: ["foo"]`
+  - Exclusive limits: numeric `exclusiveMinimum` -> boolean form with `minimum`
+  - Keyword removal: `$schema`, `$id`, `dependencies`, `patternProperties`
 - **Name sanitization:** Tool names are automatically sanitized to meet API requirements
 - **Conflict resolution:** Tool name conflicts between servers are resolved through automatic prefixing
 

docs/developers/tools/sandbox.md

@@ -0,0 +1,90 @@
+## Customizing the sandbox environment (Docker/Podman)
+
+### Currently, the project does not support the use of the BUILD_SANDBOX function after installation through the npm package
+
+1. To build a custom sandbox, you need to access the build scripts (scripts/build_sandbox.js) in the source code repository.
+2. These build scripts are not included in the packages released by npm.
+3. The code contains hard-coded path checks that explicitly reject build requests from non-source code environments.
+
+If you need extra tools inside the container (e.g., `git`, `python`, `rg`), create a custom Dockerfile, The specific operation is as follows
+
+#### 1、Clone qwen code project first, https://github.com/QwenLM/qwen-code.git
+
+#### 2、Make sure you perform the following operation in the source code repository directory
+
+```bash
+# 1. First, install the dependencies of the project
+npm install
+
+# 2. Build the Qwen Code project
+npm run build
+
+# 3. Verify that the dist directory has been generated
+ls -la packages/cli/dist/
+
+# 4. Create a global link in the CLI package directory
+cd packages/cli
+npm link
+
+# 5. Verification link (it should now point to the source code)
+which qwen
+# Expected output: /xxx/xxx/.nvm/versions/node/v24.11.1/bin/qwen
+# Or similar paths, but it should be a symbolic link
+
+# 6. For details of the symbolic link, you can see the specific source code path
+ls -la $(dirname $(which qwen))/../lib/node_modules/@qwen-code/qwen-code
+# It should show that this is a symbolic link pointing to your source code directory
+
+# 7.Test the version of qwen
+qwen -v
+# npm link will overwrite the global qwen. To avoid being unable to distinguish the same version number, you can uninstall the global CLI first
+```
+
+#### 3、Create your sandbox Dockerfile under the root directory of your own project
+
+- Path: `.qwen/sandbox.Dockerfile`
+
+- Official mirror image address:https://github.com/QwenLM/qwen-code/pkgs/container/qwen-code
+
+```bash
+# Based on the official Qwen sandbox image (It is recommended to explicitly specify the version)
+FROM ghcr.io/qwenlm/qwen-code:sha-570ec43
+# Add your extra tools here
+RUN apt-get update && apt-get install -y \
+    git \
+    python3 \
+    ripgrep
+```
+
+#### 4、Create the first sandbox image under the root directory of your project
+
+```bash
+GEMINI_SANDBOX=docker BUILD_SANDBOX=1 qwen -s
+# Observe whether the sandbox version of the tool you launched is consistent with the version of your custom image. If they are consistent, the startup will be successful
+```
+
+This builds a project-specific image based on the default sandbox image.
+
+#### Remove npm link
+
+- If you want to restore the official CLI of qwen, please remove the npm link
+
+```bash
+# Method 1: Unlink globally
+npm unlink -g @qwen-code/qwen-code
+
+# Method 2: Remove it in the packages/cli directory
+cd packages/cli
+npm unlink
+
+# Verification has been lifted
+which qwen
+# It should display "qwen not found"
+
+# Reinstall the global version if necessary
+npm install -g @qwen-code/qwen-code
+
+# Verification Recovery
+which qwen
+qwen --version
+```

docs/index.md

@@ -14,7 +14,7 @@ Learn how to use Qwen Code as an end user. This section covers:
 - Configuration options
 - Troubleshooting
 
-### [Developer Guide](./developers/contributing)
+### [Developer Guide](./developers/architecture)
 
 Learn how to contribute to and develop Qwen Code. This section covers:
 

docs/users/_meta.ts

@@ -12,6 +12,7 @@ export default {
   },
   'integration-vscode': 'Visual Studio Code',
   'integration-zed': 'Zed IDE',
+  'integration-jetbrains': 'JetBrains IDEs',
   'integration-github-action': 'Github Actions',
   'Code with Qwen Code': {
     type: 'separator',
@@ -19,6 +20,7 @@ export default {
   },
   features: 'Features',
   configuration: 'Configuration',
+  extension: 'Extension',
   reference: 'Reference',
   support: 'Support',
   // need refine

docs/users/common-workflow.md

@@ -189,8 +189,8 @@ Then select "create" and follow the prompts to define:
 > - Create project-specific subagents in `.qwen/agents/` for team sharing
 > - Use descriptive `description` fields to enable automatic delegation
 > - Limit tool access to what each subagent actually needs
-> - Know more about [Sub Agents](/users/features/sub-agents)
-> - Know more about [Approval Mode](/users/features/approval-mode)
+> - Know more about [Sub Agents](./features/sub-agents)
+> - Know more about [Approval Mode](./features/approval-mode)
 
 ## Work with tests
 
@@ -318,7 +318,7 @@ This provides a directory listing with file information.
 Show me the data from @github: repos/owner/repo/issues
 ```
 
-This fetches data from connected MCP servers using the format @server: resource. See [MCP](/users/features/mcp) for details.
+This fetches data from connected MCP servers using the format @server: resource. See [MCP](./features/mcp) for details.
 
 > [!tip]
 >

docs/users/configuration/auth.md

@@ -5,11 +5,13 @@ Qwen Code supports two authentication methods. Pick the one that matches how you
 - **Qwen OAuth (recommended)**: sign in with your `qwen.ai` account in a browser.
 - **OpenAI-compatible API**: use an API key (OpenAI or any OpenAI-compatible provider / endpoint).
 
+![](https://img.alicdn.com/imgextra/i2/O1CN01IxI1bt1sNO543AVTT_!!6000000005754-0-tps-1958-822.jpg)
+
 ## Option 1: Qwen OAuth (recommended & free) 👍
 
-Use this if you want the simplest setup and you’re using Qwen models.
+Use this if you want the simplest setup and you're using Qwen models.
 
-- **How it works**: on first start, Qwen Code opens a browser login page. After you finish, credentials are cached locally so you usually won’t need to log in again.
+- **How it works**: on first start, Qwen Code opens a browser login page. After you finish, credentials are cached locally so you usually won't need to log in again.
 - **Requirements**: a `qwen.ai` account + internet access (at least for the first login).
 - **Benefits**: no API key management, automatic credential refresh.
 - **Cost & quota**: free, with a quota of **60 requests/minute** and **2,000 requests/day**.
@@ -24,15 +26,54 @@ qwen
 
 Use this if you want to use OpenAI models or any provider that exposes an OpenAI-compatible API (e.g. OpenAI, Azure OpenAI, OpenRouter, ModelScope, Alibaba Cloud Bailian, or a self-hosted compatible endpoint).
 
-### Quick start (interactive, recommended for local use)
+### Recommended: Coding Plan (subscription-based) 🚀
 
-When you choose the OpenAI-compatible option in the CLI, it will prompt you for:
+Use this if you want predictable costs with higher usage quotas for the qwen3-coder-plus model.
 
-- **API key**
-- **Base URL** (default: `https://api.openai.com/v1`)
-- **Model** (default: `gpt-4o`)
+> [!IMPORTANT]
+>
+> Coding Plan is only available for users in China mainland (Beijing region).
 
-> **Note:** the CLI may display the key in plain text for verification. Make sure your terminal is not being recorded or shared.
+- **How it works**: subscribe to the Coding Plan with a fixed monthly fee, then configure Qwen Code to use the dedicated endpoint and your subscription API key.
+- **Requirements**: an active Coding Plan subscription from [Alibaba Cloud Bailian](https://bailian.console.aliyun.com/cn-beijing/?tab=globalset#/efm/coding_plan).
+- **Benefits**: higher usage quotas, predictable monthly costs, access to latest qwen3-coder-plus model.
+- **Cost & quota**: varies by plan (see table below).
+
+#### Coding Plan Pricing & Quotas
+
+| Feature             | Lite Basic Plan       | Pro Advanced Plan     |
+| :------------------ | :-------------------- | :-------------------- |
+| **Price**           | ¥40/month             | ¥200/month            |
+| **5-Hour Limit**    | Up to 1,200 requests  | Up to 6,000 requests  |
+| **Weekly Limit**    | Up to 9,000 requests  | Up to 45,000 requests |
+| **Monthly Limit**   | Up to 18,000 requests | Up to 90,000 requests |
+| **Supported Model** | qwen3-coder-plus      | qwen3-coder-plus      |
+
+#### Quick Setup for Coding Plan
+
+When you select the OpenAI-compatible option in the CLI, enter these values:
+
+- **API key**: `sk-sp-xxxxx`
+- **Base URL**: `https://coding.dashscope.aliyuncs.com/v1`
+- **Model**: `qwen3-coder-plus`
+
+> **Note**: Coding Plan API keys have the format `sk-sp-xxxxx`, which is different from standard Alibaba Cloud API keys.
+
+#### Configure via Environment Variables
+
+Set these environment variables to use Coding Plan:
+
+```bash
+export OPENAI_API_KEY="your-coding-plan-api-key"  # Format: sk-sp-xxxxx
+export OPENAI_BASE_URL="https://coding.dashscope.aliyuncs.com/v1"
+export OPENAI_MODEL="qwen3-coder-plus"
+```
+
+For more details about Coding Plan, including subscription options and troubleshooting, see the [full Coding Plan documentation](https://bailian.console.aliyun.com/cn-beijing/?tab=doc#/doc/?type=model&url=3005961).
+
+### Other OpenAI-compatible Providers
+
+If you are using other providers (OpenAI, Azure, local LLMs, etc.), use the following configuration methods.
 
 ### Configure via command-line arguments
 

docs/users/configuration/qwen-ignore.md

@@ -6,7 +6,7 @@ Qwen Code includes the ability to automatically ignore files, similar to `.gitig
 
 ## How it works
 
-When you add a path to your `.qwenignore` file, tools that respect this file will exclude matching files and directories from their operations. For example, when you use the [`read_many_files`](/developers/tools/multi-file) command, any paths in your `.qwenignore` file will be automatically excluded.
+When you add a path to your `.qwenignore` file, tools that respect this file will exclude matching files and directories from their operations. For example, when you use the [`read_many_files`](../../developers/tools/multi-file) command, any paths in your `.qwenignore` file will be automatically excluded.
 
 For the most part, `.qwenignore` follows the conventions of `.gitignore` files:
 

docs/users/configuration/settings.md

@@ -2,7 +2,7 @@
 
 > [!tip]
 >
-> **Authentication / API keys:** Authentication (Qwen OAuth vs OpenAI-compatible API) and auth-related environment variables (like `OPENAI_API_KEY`) are documented in **[Authentication](/users/configuration/auth)**.
+> **Authentication / API keys:** Authentication (Qwen OAuth vs OpenAI-compatible API) and auth-related environment variables (like `OPENAI_API_KEY`) are documented in **[Authentication](../configuration/auth)**.
 
 > [!note]
 >
@@ -42,7 +42,8 @@ Qwen Code uses JSON settings files for persistent configuration. There are four
 
 In addition to a project settings file, a project's `.qwen` directory can contain other project-specific files related to Qwen Code's operation, such as:
 
-- [Custom sandbox profiles](/users/features/sandbox) (e.g. `.qwen/sandbox-macos-custom.sb`, `.qwen/sandbox.Dockerfile`).
+- [Custom sandbox profiles](../features/sandbox) (e.g. `.qwen/sandbox-macos-custom.sb`, `.qwen/sandbox.Dockerfile`).
+- [Agent Skills](../features/skills) (experimental) under `.qwen/skills/` (each Skill is a directory containing a `SKILL.md`).
 
 ### Available settings in `settings.json`
 
@@ -69,13 +70,10 @@ Settings are organized into categories. All settings should be placed within the
 
 | Setting                                  | Type             | Description                                                                                                                                                                                                                                                                                                                                                                                                         | Default     |
 | ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
-| `ui.theme`                               | string           | The color theme for the UI. See [Themes](/users/configuration/themes) for available options.                                                                                                                                                                                                                                                                                                                        | `undefined` |
+| `ui.theme`                               | string           | The color theme for the UI. See [Themes](../configuration/themes) for available options.                                                                                                                                                                                                                                                                                                                            | `undefined` |
 | `ui.customThemes`                        | object           | Custom theme definitions.                                                                                                                                                                                                                                                                                                                                                                                           | `{}`        |
 | `ui.hideWindowTitle`                     | boolean          | Hide the window title bar.                                                                                                                                                                                                                                                                                                                                                                                          | `false`     |
 | `ui.hideTips`                            | boolean          | Hide helpful tips in the UI.                                                                                                                                                                                                                                                                                                                                                                                        | `false`     |
-| `ui.hideBanner`                          | boolean          | Hide the application banner.                                                                                                                                                                                                                                                                                                                                                                                        | `false`     |
-| `ui.hideFooter`                          | boolean          | Hide the footer from the UI.                                                                                                                                                                                                                                                                                                                                                                                        | `false`     |
-| `ui.showMemoryUsage`                     | boolean          | Display memory usage information in the UI.                                                                                                                                                                                                                                                                                                                                                                         | `false`     |
 | `ui.showLineNumbers`                     | boolean          | Show line numbers in code blocks in the CLI output.                                                                                                                                                                                                                                                                                                                                                                 | `true`      |
 | `ui.showCitations`                       | boolean          | Show citations for generated text in the chat.                                                                                                                                                                                                                                                                                                                                                                      | `true`      |
 | `enableWelcomeBack`                      | boolean          | Show welcome back dialog when returning to a project with conversation history. When enabled, Qwen Code will automatically detect if you're returning to a project with a previously generated project summary (`.qwen/PROJECT_SUMMARY.md`) and show a dialog allowing you to continue your previous conversation or start fresh. This feature integrates with the `/summary` command and quit confirmation dialog. | `true`      |
@@ -103,7 +101,7 @@ Settings are organized into categories. All settings should be placed within the
 | `model.name`                                       | string  | The Qwen model to use for conversations.                                                                                                                                                                                                                                                                                                                               | `undefined` |
 | `model.maxSessionTurns`                            | number  | Maximum number of user/model/tool turns to keep in a session. -1 means unlimited.                                                                                                                                                                                                                                                                                      | `-1`        |
 | `model.summarizeToolOutput`                        | object  | Enables or disables the summarization of tool output. You can specify the token budget for the summarization using the `tokenBudget` setting. Note: Currently only the `run_shell_command` tool is supported. For example `{"run_shell_command": {"tokenBudget": 2000}}`                                                                                               | `undefined` |
-| `model.generationConfig`                           | object  | Advanced overrides passed to the underlying content generator. Supports request controls such as `timeout`, `maxRetries`, and `disableCacheControl`, along with fine-tuning knobs under `samplingParams` (for example `temperature`, `top_p`, `max_tokens`). Leave unset to rely on provider defaults.                                                                 | `undefined` |
+| `model.generationConfig`                           | object  | Advanced overrides passed to the underlying content generator. Supports request controls such as `timeout`, `maxRetries`, `disableCacheControl`, and `customHeaders` (custom HTTP headers for API requests), along with fine-tuning knobs under `samplingParams` (for example `temperature`, `top_p`, `max_tokens`). Leave unset to rely on provider defaults.         | `undefined` |
 | `model.chatCompression.contextPercentageThreshold` | number  | Sets the threshold for chat history compression as a percentage of the model's total token limit. This is a value between 0 and 1 that applies to both automatic compression and the manual `/compress` command. For example, a value of `0.6` will trigger compression when the chat history exceeds 60% of the token limit. Use `0` to disable compression entirely. | `0.7`       |
 | `model.skipNextSpeakerCheck`                       | boolean | Skip the next speaker check.                                                                                                                                                                                                                                                                                                                                           | `false`     |
 | `model.skipLoopDetection`                          | boolean | Disables loop detection checks. Loop detection prevents infinite loops in AI responses but can generate false positives that interrupt legitimate workflows. Enable this option if you experience frequent false positive loop detection interruptions.                                                                                                                | `false`     |
@@ -113,12 +111,16 @@ Settings are organized into categories. All settings should be placed within the
 
 **Example model.generationConfig:**
 
-```
+```json
 {
   "model": {
     "generationConfig": {
       "timeout": 60000,
       "disableCacheControl": false,
+      "customHeaders": {
+        "X-Request-ID": "req-123",
+        "X-User-ID": "user-456"
+      },
       "samplingParams": {
         "temperature": 0.2,
         "top_p": 0.8,
@@ -129,19 +131,113 @@ Settings are organized into categories. All settings should be placed within the
 }
 ```
 
+The `customHeaders` field allows you to add custom HTTP headers to all API requests. This is useful for request tracing, monitoring, API gateway routing, or when different models require different headers. If `customHeaders` is defined in `modelProviders[].generationConfig.customHeaders`, it will be used directly; otherwise, headers from `model.generationConfig.customHeaders` will be used. No merging occurs between the two levels.
+
 **model.openAILoggingDir examples:**
 
 - `"~/qwen-logs"` - Logs to `~/qwen-logs` directory
 - `"./custom-logs"` - Logs to `./custom-logs` relative to current directory
 - `"/tmp/openai-logs"` - Logs to absolute path `/tmp/openai-logs`
 
+#### modelProviders
+
+Use `modelProviders` to declare curated model lists per auth type that the `/model` picker can switch between. Keys must be valid auth types (`openai`, `anthropic`, `gemini`, `vertex-ai`, etc.). Each entry requires an `id` and **must include `envKey`**, with optional `name`, `description`, `baseUrl`, and `generationConfig`. Credentials are never persisted in settings; the runtime reads them from `process.env[envKey]`. Qwen OAuth models remain hard-coded and cannot be overridden.
+
+##### Example
+
+```json
+{
+  "modelProviders": {
+    "openai": [
+      {
+        "id": "gpt-4o",
+        "name": "GPT-4o",
+        "envKey": "OPENAI_API_KEY",
+        "baseUrl": "https://api.openai.com/v1",
+        "generationConfig": {
+          "timeout": 60000,
+          "maxRetries": 3,
+          "customHeaders": {
+            "X-Model-Version": "v1.0",
+            "X-Request-Priority": "high"
+          },
+          "samplingParams": { "temperature": 0.2 }
+        }
+      }
+    ],
+    "anthropic": [
+      {
+        "id": "claude-3-5-sonnet",
+        "envKey": "ANTHROPIC_API_KEY",
+        "baseUrl": "https://api.anthropic.com/v1"
+      }
+    ],
+    "gemini": [
+      {
+        "id": "gemini-2.0-flash",
+        "name": "Gemini 2.0 Flash",
+        "envKey": "GEMINI_API_KEY",
+        "baseUrl": "https://generativelanguage.googleapis.com"
+      }
+    ],
+    "vertex-ai": [
+      {
+        "id": "gemini-1.5-pro-vertex",
+        "envKey": "GOOGLE_API_KEY",
+        "baseUrl": "https://generativelanguage.googleapis.com"
+      }
+    ]
+  }
+}
+```
+
+> [!note]
+> Only the `/model` command exposes non-default auth types. Anthropic, Gemini, Vertex AI, etc., must be defined via `modelProviders`. The `/auth` command intentionally lists only the built-in Qwen OAuth and OpenAI flows.
+
+##### Resolution layers and atomicity
+
+The effective auth/model/credential values are chosen per field using the following precedence (first present wins). You can combine `--auth-type` with `--model` to point directly at a provider entry; these CLI flags run before other layers.
+
+| Layer (highest → lowest)   | authType                            | model                                           | apiKey                                              | baseUrl                                              | apiKeyEnvKey           | proxy                             |
+| -------------------------- | ----------------------------------- | ----------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------- | ---------------------- | --------------------------------- |
+| Programmatic overrides     | `/auth `                            | `/auth` input                                   | `/auth` input                                       | `/auth` input                                        | —                      | —                                 |
+| Model provider selection   | —                                   | `modelProvider.id`                              | `env[modelProvider.envKey]`                         | `modelProvider.baseUrl`                              | `modelProvider.envKey` | —                                 |
+| CLI arguments              | `--auth-type`                       | `--model`                                       | `--openaiApiKey` (or provider-specific equivalents) | `--openaiBaseUrl` (or provider-specific equivalents) | —                      | —                                 |
+| Environment variables      | —                                   | Provider-specific mapping (e.g. `OPENAI_MODEL`) | Provider-specific mapping (e.g. `OPENAI_API_KEY`)   | Provider-specific mapping (e.g. `OPENAI_BASE_URL`)   | —                      | —                                 |
+| Settings (`settings.json`) | `security.auth.selectedType`        | `model.name`                                    | `security.auth.apiKey`                              | `security.auth.baseUrl`                              | —                      | —                                 |
+| Default / computed         | Falls back to `AuthType.QWEN_OAUTH` | Built-in default (OpenAI ⇒ `qwen3-coder-plus`)  | —                                                   | —                                                    | —                      | `Config.getProxy()` if configured |
+
+\*When present, CLI auth flags override settings. Otherwise, `security.auth.selectedType` or the implicit default determine the auth type. Qwen OAuth and OpenAI are the only auth types surfaced without extra configuration.
+
+Model-provider sourced values are applied atomically: once a provider model is active, every field it defines is protected from lower layers until you manually clear credentials via `/auth`. The final `generationConfig` is the projection across all layers—lower layers only fill gaps left by higher ones, and the provider layer remains impenetrable.
+
+The merge strategy for `modelProviders` is REPLACE: the entire `modelProviders` from project settings will override the corresponding section in user settings, rather than merging the two.
+
+##### Generation config layering
+
+Per-field precedence for `generationConfig`:
+
+1. Programmatic overrides (e.g. runtime `/model`, `/auth` changes)
+2. `modelProviders[authType][].generationConfig`
+3. `settings.model.generationConfig`
+4. Content-generator defaults (`getDefaultGenerationConfig` for OpenAI, `getParameterValue` for Gemini, etc.)
+
+`samplingParams` and `customHeaders` are both treated atomically; provider values replace the entire object. If `modelProviders[].generationConfig` defines these fields, they are used directly; otherwise, values from `model.generationConfig` are used. No merging occurs between provider and global configuration levels. Defaults from the content generator apply last so each provider retains its tuned baseline.
+
+##### Selection persistence and recommendations
+
+> [!important]
+> Define `modelProviders` in the user-scope `~/.qwen/settings.json` whenever possible and avoid persisting credential overrides in any scope. Keeping the provider catalog in user settings prevents merge/override conflicts between project and user scopes and ensures `/auth` and `/model` updates always write back to a consistent scope.
+
+- `/model` and `/auth` persist `model.name` (where applicable) and `security.auth.selectedType` to the closest writable scope that already defines `modelProviders`; otherwise they fall back to the user scope. This keeps workspace/user files in sync with the active provider catalog.
+- Without `modelProviders`, the resolver mixes CLI/env/settings layers, which is fine for single-provider setups but cumbersome when frequently switching. Define provider catalogs whenever multi-model workflows are common so that switches stay atomic, source-attributed, and debuggable.
+
 #### context
 
 | Setting                                           | Type                       | Description                                                                                                                                                                                                                                                                                                                                                           | Default     |
 | ------------------------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
 | `context.fileName`                                | string or array of strings | The name of the context file(s).                                                                                                                                                                                                                                                                                                                                      | `undefined` |
 | `context.importFormat`                            | string                     | The format to use when importing memory.                                                                                                                                                                                                                                                                                                                              | `undefined` |
-| `context.discoveryMaxDirs`                        | number                     | Maximum number of directories to search for memory.                                                                                                                                                                                                                                                                                                                   | `200`       |
 | `context.includeDirectories`                      | array                      | Additional directories to include in the workspace context. Specifies an array of additional absolute or relative paths to include in the workspace context. Missing directories will be skipped with a warning by default. Paths can use `~` to refer to the user's home directory. This setting can be combined with the `--include-directories` command-line flag. | `[]`        |
 | `context.loadFromIncludeDirectories`              | boolean                    | Controls the behavior of the `/memory refresh` command. If set to `true`, `QWEN.md` files should be loaded from all directories that are added. If set to `false`, `QWEN.md` should only be loaded from the current directory.                                                                                                                                        | `false`     |
 | `context.fileFiltering.respectGitIgnore`          | boolean                    | Respect .gitignore files when searching.                                                                                                                                                                                                                                                                                                                              | `true`      |
@@ -174,7 +270,6 @@ If you are experiencing performance issues with file searching (e.g., with `@` c
 | `tools.enableToolOutputTruncation`   | boolean           | Enable truncation of large tool outputs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `true`      | Requires restart: Yes                                                                                                                                                                                                                                |
 | `tools.truncateToolOutputThreshold`  | number            | Truncate tool output if it is larger than this many characters. Applies to Shell, Grep, Glob, ReadFile and ReadManyFiles tools.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `25000`     | Requires restart: Yes                                                                                                                                                                                                                                |
 | `tools.truncateToolOutputLines`      | number            | Maximum lines or entries kept when truncating tool output. Applies to Shell, Grep, Glob, ReadFile and ReadManyFiles tools.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `1000`      | Requires restart: Yes                                                                                                                                                                                                                                |
-| `tools.autoAccept`                   | boolean           | Controls whether the CLI automatically accepts and executes tool calls that are considered safe (e.g., read-only operations) without explicit user confirmation. If set to `true`, the CLI will bypass the confirmation prompt for tools deemed safe.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `false`     |                                                                                                                                                                                                                                                      |
 
 #### mcp
 
@@ -211,6 +306,12 @@ If you are experiencing performance issues with file searching (e.g., with `@` c
 >
 > **Note about advanced.tavilyApiKey:** This is a legacy configuration format. For Qwen OAuth users, DashScope provider is automatically available without any configuration. For other authentication types, configure Tavily or Google providers using the new `webSearch` configuration format.
 
+#### experimental
+
+| Setting               | Type    | Description                      | Default |
+| --------------------- | ------- | -------------------------------- | ------- |
+| `experimental.skills` | boolean | Enable experimental Agent Skills | `false` |
+
 #### mcpServers
 
 Configures connections to one or more Model-Context Protocol (MCP) servers for discovering and using custom tools. Qwen Code attempts to connect to each configured MCP server to discover available tools. If multiple MCP servers expose a tool with the same name, the tool names will be prefixed with the server alias you defined in the configuration (e.g., `serverAlias__actualToolName`) to avoid conflicts. Note that the system might strip certain schema properties from MCP tool definitions for compatibility. At least one of `command`, `url`, or `httpUrl` must be provided. If multiple are specified, the order of precedence is `httpUrl`, then `url`, then `command`.
@@ -256,7 +357,6 @@ Here is an example of a `settings.json` file with the nested structure, new as o
   },
   "ui": {
     "theme": "GitHub",
-    "hideBanner": true,
     "hideTips": false,
     "customWittyPhrases": [
       "You forget a thousand things every day. Make sure this is one of 'em",
@@ -326,7 +426,7 @@ The CLI keeps a history of shell commands you run. To avoid conflicts between di
 Environment variables are a common way to configure applications, especially for sensitive information (like tokens) or for settings that might change between environments.
 
 Qwen Code can automatically load environment variables from `.env` files.
-For authentication-related variables (like `OPENAI_*`) and the recommended `.qwen/.env` approach, see **[Authentication](/users/configuration/auth)**.
+For authentication-related variables (like `OPENAI_*`) and the recommended `.qwen/.env` approach, see **[Authentication](../configuration/auth)**.
 
 > [!tip]
 >
@@ -357,38 +457,40 @@ Arguments passed directly when running the CLI can override other configurations
 
 ### Command-Line Arguments Table
 
-| Argument                     | Alias | Description                                                                                                                                                                             | Possible Values                        | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| ---------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--model`                    | `-m`  | Specifies the Qwen model to use for this session.                                                                                                                                       | Model name                             | Example: `npm start -- --model qwen3-coder-plus`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `--prompt`                   | `-p`  | Used to pass a prompt directly to the command. This invokes Qwen Code in a non-interactive mode.                                                                                        | Your prompt text                       | For scripting examples, use the `--output-format json` flag to get structured output.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `--prompt-interactive`       | `-i`  | Starts an interactive session with the provided prompt as the initial input.                                                                                                            | Your prompt text                       | The prompt is processed within the interactive session, not before it. Cannot be used when piping input from stdin. Example: `qwen -i "explain this code"`                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `--output-format`            | `-o`  | Specifies the format of the CLI output for non-interactive mode.                                                                                                                        | `text`, `json`, `stream-json`          | `text`: (Default) The standard human-readable output. `json`: A machine-readable JSON output emitted at the end of execution. `stream-json`: Streaming JSON messages emitted as they occur during execution. For structured output and scripting, use the `--output-format json` or `--output-format stream-json` flag. See [Headless Mode](/users/features/headless) for detailed information.                                                                                                                                                                     |
-| `--input-format`             |       | Specifies the format consumed from standard input.                                                                                                                                      | `text`, `stream-json`                  | `text`: (Default) Standard text input from stdin or command-line arguments. `stream-json`: JSON message protocol via stdin for bidirectional communication. Requirement: `--input-format stream-json` requires `--output-format stream-json` to be set. When using `stream-json`, stdin is reserved for protocol messages. See [Headless Mode](/users/features/headless) for detailed information.                                                                                                                                                                  |
-| `--include-partial-messages` |       | Include partial assistant messages when using `stream-json` output format. When enabled, emits stream events (message_start, content_block_delta, etc.) as they occur during streaming. |                                        | Default: `false`. Requirement: Requires `--output-format stream-json` to be set. See [Headless Mode](/users/features/headless) for detailed information about stream events.                                                                                                                                                                                                                                                                                                                                                                                        |
-| `--sandbox`                  | `-s`  | Enables sandbox mode for this session.                                                                                                                                                  |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `--sandbox-image`            |       | Sets the sandbox image URI.                                                                                                                                                             |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `--debug`                    | `-d`  | Enables debug mode for this session, providing more verbose output.                                                                                                                     |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `--all-files`                | `-a`  | If set, recursively includes all files within the current directory as context for the prompt.                                                                                          |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `--help`                     | `-h`  | Displays help information about command-line arguments.                                                                                                                                 |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `--show-memory-usage`        |       | Displays the current memory usage.                                                                                                                                                      |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `--yolo`                     |       | Enables YOLO mode, which automatically approves all tool calls.                                                                                                                         |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `--approval-mode`            |       | Sets the approval mode for tool calls.                                                                                                                                                  | `plan`, `default`, `auto-edit`, `yolo` | Supported modes: `plan`: Analyze only—do not modify files or execute commands. `default`: Require approval for file edits or shell commands (default behavior). `auto-edit`: Automatically approve edit tools (edit, write_file) while prompting for others. `yolo`: Automatically approve all tool calls (equivalent to `--yolo`). Cannot be used together with `--yolo`. Use `--approval-mode=yolo` instead of `--yolo` for the new unified approach. Example: `qwen --approval-mode auto-edit`<br>See more about [Approval Mode](/users/features/approval-mode). |
-| `--allowed-tools`            |       | A comma-separated list of tool names that will bypass the confirmation dialog.                                                                                                          | Tool names                             | Example: `qwen --allowed-tools "Shell(git status)"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `--telemetry`                |       | Enables [telemetry](/developers/development/telemetry).                                                                                                                                 |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `--telemetry-target`         |       | Sets the telemetry target.                                                                                                                                                              |                                        | See [telemetry](/developers/development/telemetry) for more information.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `--telemetry-otlp-endpoint`  |       | Sets the OTLP endpoint for telemetry.                                                                                                                                                   |                                        | See [telemetry](/developers/development/telemetry) for more information.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `--telemetry-otlp-protocol`  |       | Sets the OTLP protocol for telemetry (`grpc` or `http`).                                                                                                                                |                                        | Defaults to `grpc`. See [telemetry](/developers/development/telemetry) for more information.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `--telemetry-log-prompts`    |       | Enables logging of prompts for telemetry.                                                                                                                                               |                                        | See [telemetry](/developers/development/telemetry) for more information.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `--checkpointing`            |       | Enables [checkpointing](/users/features/checkpointing).                                                                                                                                 |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `--extensions`               | `-e`  | Specifies a list of extensions to use for the session.                                                                                                                                  | Extension names                        | If not provided, all available extensions are used. Use the special term `qwen -e none` to disable all extensions. Example: `qwen -e my-extension -e my-other-extension`                                                                                                                                                                                                                                                                                                                                                                                            |
-| `--list-extensions`          | `-l`  | Lists all available extensions and exits.                                                                                                                                               |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `--proxy`                    |       | Sets the proxy for the CLI.                                                                                                                                                             | Proxy URL                              | Example: `--proxy http://localhost:7890`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `--include-directories`      |       | Includes additional directories in the workspace for multi-directory support.                                                                                                           | Directory paths                        | Can be specified multiple times or as comma-separated values. 5 directories can be added at maximum. Example: `--include-directories /path/to/project1,/path/to/project2` or `--include-directories /path/to/project1 --include-directories /path/to/project2`                                                                                                                                                                                                                                                                                                      |
-| `--screen-reader`            |       | Enables screen reader mode, which adjusts the TUI for better compatibility with screen readers.                                                                                         |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `--version`                  |       | Displays the version of the CLI.                                                                                                                                                        |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `--openai-logging`           |       | Enables logging of OpenAI API calls for debugging and analysis.                                                                                                                         |                                        | This flag overrides the `enableOpenAILogging` setting in `settings.json`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `--openai-logging-dir`       |       | Sets a custom directory path for OpenAI API logs.                                                                                                                                       | Directory path                         | This flag overrides the `openAILoggingDir` setting in `settings.json`. Supports absolute paths, relative paths, and `~` expansion. Example: `qwen --openai-logging-dir "~/qwen-logs" --openai-logging`                                                                                                                                                                                                                                                                                                                                                              |
-| `--tavily-api-key`           |       | Sets the Tavily API key for web search functionality for this session.                                                                                                                  | API key                                | Example: `qwen --tavily-api-key tvly-your-api-key-here`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Argument                     | Alias | Description                                                                                                                                                                             | Possible Values                        | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ---------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--model`                    | `-m`  | Specifies the Qwen model to use for this session.                                                                                                                                       | Model name                             | Example: `npm start -- --model qwen3-coder-plus`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `--prompt`                   | `-p`  | Used to pass a prompt directly to the command. This invokes Qwen Code in a non-interactive mode.                                                                                        | Your prompt text                       | For scripting examples, use the `--output-format json` flag to get structured output.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `--prompt-interactive`       | `-i`  | Starts an interactive session with the provided prompt as the initial input.                                                                                                            | Your prompt text                       | The prompt is processed within the interactive session, not before it. Cannot be used when piping input from stdin. Example: `qwen -i "explain this code"`                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `--output-format`            | `-o`  | Specifies the format of the CLI output for non-interactive mode.                                                                                                                        | `text`, `json`, `stream-json`          | `text`: (Default) The standard human-readable output. `json`: A machine-readable JSON output emitted at the end of execution. `stream-json`: Streaming JSON messages emitted as they occur during execution. For structured output and scripting, use the `--output-format json` or `--output-format stream-json` flag. See [Headless Mode](../features/headless) for detailed information.                                                                                                                                                                     |
+| `--input-format`             |       | Specifies the format consumed from standard input.                                                                                                                                      | `text`, `stream-json`                  | `text`: (Default) Standard text input from stdin or command-line arguments. `stream-json`: JSON message protocol via stdin for bidirectional communication. Requirement: `--input-format stream-json` requires `--output-format stream-json` to be set. When using `stream-json`, stdin is reserved for protocol messages. See [Headless Mode](../features/headless) for detailed information.                                                                                                                                                                  |
+| `--include-partial-messages` |       | Include partial assistant messages when using `stream-json` output format. When enabled, emits stream events (message_start, content_block_delta, etc.) as they occur during streaming. |                                        | Default: `false`. Requirement: Requires `--output-format stream-json` to be set. See [Headless Mode](../features/headless) for detailed information about stream events.                                                                                                                                                                                                                                                                                                                                                                                        |
+| `--sandbox`                  | `-s`  | Enables sandbox mode for this session.                                                                                                                                                  |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `--sandbox-image`            |       | Sets the sandbox image URI.                                                                                                                                                             |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `--debug`                    | `-d`  | Enables debug mode for this session, providing more verbose output.                                                                                                                     |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `--all-files`                | `-a`  | If set, recursively includes all files within the current directory as context for the prompt.                                                                                          |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `--help`                     | `-h`  | Displays help information about command-line arguments.                                                                                                                                 |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `--show-memory-usage`        |       | Displays the current memory usage.                                                                                                                                                      |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `--yolo`                     |       | Enables YOLO mode, which automatically approves all tool calls.                                                                                                                         |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `--approval-mode`            |       | Sets the approval mode for tool calls.                                                                                                                                                  | `plan`, `default`, `auto-edit`, `yolo` | Supported modes: `plan`: Analyze only—do not modify files or execute commands. `default`: Require approval for file edits or shell commands (default behavior). `auto-edit`: Automatically approve edit tools (edit, write_file) while prompting for others. `yolo`: Automatically approve all tool calls (equivalent to `--yolo`). Cannot be used together with `--yolo`. Use `--approval-mode=yolo` instead of `--yolo` for the new unified approach. Example: `qwen --approval-mode auto-edit`<br>See more about [Approval Mode](../features/approval-mode). |
+| `--allowed-tools`            |       | A comma-separated list of tool names that will bypass the confirmation dialog.                                                                                                          | Tool names                             | Example: `qwen --allowed-tools "Shell(git status)"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `--telemetry`                |       | Enables [telemetry](/developers/development/telemetry).                                                                                                                                 |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `--telemetry-target`         |       | Sets the telemetry target.                                                                                                                                                              |                                        | See [telemetry](/developers/development/telemetry) for more information.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `--telemetry-otlp-endpoint`  |       | Sets the OTLP endpoint for telemetry.                                                                                                                                                   |                                        | See [telemetry](../../developers/development/telemetry) for more information.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `--telemetry-otlp-protocol`  |       | Sets the OTLP protocol for telemetry (`grpc` or `http`).                                                                                                                                |                                        | Defaults to `grpc`. See [telemetry](../../developers/development/telemetry) for more information.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `--telemetry-log-prompts`    |       | Enables logging of prompts for telemetry.                                                                                                                                               |                                        | See [telemetry](../../developers/development/telemetry) for more information.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `--checkpointing`            |       | Enables [checkpointing](../features/checkpointing).                                                                                                                                     |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `--acp`                      |       | Enables ACP mode (Agent Client Protocol). Useful for IDE/editor integrations like [Zed](../integration-zed).                                                                            |                                        | Stable. Replaces the deprecated `--experimental-acp` flag.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `--experimental-skills`      |       | Enables experimental [Agent Skills](../features/skills) (registers the `skill` tool and loads Skills from `.qwen/skills/` and `~/.qwen/skills/`).                                       |                                        | Experimental.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `--extensions`               | `-e`  | Specifies a list of extensions to use for the session.                                                                                                                                  | Extension names                        | If not provided, all available extensions are used. Use the special term `qwen -e none` to disable all extensions. Example: `qwen -e my-extension -e my-other-extension`                                                                                                                                                                                                                                                                                                                                                                                        |
+| `--list-extensions`          | `-l`  | Lists all available extensions and exits.                                                                                                                                               |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `--proxy`                    |       | Sets the proxy for the CLI.                                                                                                                                                             | Proxy URL                              | Example: `--proxy http://localhost:7890`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `--include-directories`      |       | Includes additional directories in the workspace for multi-directory support.                                                                                                           | Directory paths                        | Can be specified multiple times or as comma-separated values. 5 directories can be added at maximum. Example: `--include-directories /path/to/project1,/path/to/project2` or `--include-directories /path/to/project1 --include-directories /path/to/project2`                                                                                                                                                                                                                                                                                                  |
+| `--screen-reader`            |       | Enables screen reader mode, which adjusts the TUI for better compatibility with screen readers.                                                                                         |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `--version`                  |       | Displays the version of the CLI.                                                                                                                                                        |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `--openai-logging`           |       | Enables logging of OpenAI API calls for debugging and analysis.                                                                                                                         |                                        | This flag overrides the `enableOpenAILogging` setting in `settings.json`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `--openai-logging-dir`       |       | Sets a custom directory path for OpenAI API logs.                                                                                                                                       | Directory path                         | This flag overrides the `openAILoggingDir` setting in `settings.json`. Supports absolute paths, relative paths, and `~` expansion. Example: `qwen --openai-logging-dir "~/qwen-logs" --openai-logging`                                                                                                                                                                                                                                                                                                                                                          |
+| `--tavily-api-key`           |       | Sets the Tavily API key for web search functionality for this session.                                                                                                                  | API key                                | Example: `qwen --tavily-api-key tvly-your-api-key-here`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 
 ## Context Files (Hierarchical Instructional Context)
 
@@ -427,22 +529,19 @@ Here's a conceptual example of what a context file at the root of a TypeScript p
 
 This example demonstrates how you can provide general project context, specific coding conventions, and even notes about particular files or components. The more relevant and precise your context files are, the better the AI can assist you. Project-specific context files are highly encouraged to establish conventions and context.
 
-- **Hierarchical Loading and Precedence:** The CLI implements a sophisticated hierarchical memory system by loading context files (e.g., `QWEN.md`) from several locations. Content from files lower in this list (more specific) typically overrides or supplements content from files higher up (more general). The exact concatenation order and final context can be inspected using the `/memory show` command. The typical loading order is:
+- **Hierarchical Loading and Precedence:** The CLI implements a hierarchical memory system by loading context files (e.g., `QWEN.md`) from several locations. Content from files lower in this list (more specific) typically overrides or supplements content from files higher up (more general). The exact concatenation order and final context can be inspected using the `/memory show` command. The typical loading order is:
   1. **Global Context File:**
      - Location: `~/.qwen/<configured-context-filename>` (e.g., `~/.qwen/QWEN.md` in your user home directory).
      - Scope: Provides default instructions for all your projects.
   2. **Project Root & Ancestors Context Files:**
      - Location: The CLI searches for the configured context file in the current working directory and then in each parent directory up to either the project root (identified by a `.git` folder) or your home directory.
      - Scope: Provides context relevant to the entire project or a significant portion of it.
-  3. **Sub-directory Context Files (Contextual/Local):**
-     - Location: The CLI also scans for the configured context file in subdirectories _below_ the current working directory (respecting common ignore patterns like `node_modules`, `.git`, etc.). The breadth of this search is limited to 200 directories by default, but can be configured with the `context.discoveryMaxDirs` setting in your `settings.json` file.
-     - Scope: Allows for highly specific instructions relevant to a particular component, module, or subsection of your project.
 - **Concatenation & UI Indication:** The contents of all found context files are concatenated (with separators indicating their origin and path) and provided as part of the system prompt. The CLI footer displays the count of loaded context files, giving you a quick visual cue about the active instructional context.
-- **Importing Content:** You can modularize your context files by importing other Markdown files using the `@path/to/file.md` syntax. For more details, see the [Memory Import Processor documentation](/users/configuration/memory).
+- **Importing Content:** You can modularize your context files by importing other Markdown files using the `@path/to/file.md` syntax. For more details, see the [Memory Import Processor documentation](../configuration/memory).
 - **Commands for Memory Management:**
   - Use `/memory refresh` to force a re-scan and reload of all context files from all configured locations. This updates the AI's instructional context.
   - Use `/memory show` to display the combined instructional context currently loaded, allowing you to verify the hierarchy and content being used by the AI.
-  - See the [Commands documentation](/users/reference/cli-reference) for full details on the `/memory` command and its sub-commands (`show` and `refresh`).
+  - See the [Commands documentation](../features/commands) for full details on the `/memory` command and its sub-commands (`show` and `refresh`).
 
 By understanding and utilizing these configuration layers and the hierarchical nature of context files, you can effectively manage the AI's memory and tailor Qwen Code's responses to your specific needs and projects.
 
@@ -450,7 +549,7 @@ By understanding and utilizing these configuration layers and the hierarchical n
 
 Qwen Code can execute potentially unsafe operations (like shell commands and file modifications) within a sandboxed environment to protect your system.
 
-[Sandbox](/users/features/sandbox) is disabled by default, but you can enable it in a few ways:
+[Sandbox](../features/sandbox) is disabled by default, but you can enable it in a few ways:
 
 - Using `--sandbox` or `-s` flag.
 - Setting `GEMINI_SANDBOX` environment variable.

docs/users/configuration/themes.md

@@ -32,7 +32,7 @@ Qwen Code comes with a selection of pre-defined themes, which you can list using
 
 ### Theme Persistence
 
-Selected themes are saved in Qwen Code's [configuration](./configuration.md) so your preference is remembered across sessions.
+Selected themes are saved in Qwen Code's [configuration](../configuration/settings) so your preference is remembered across sessions.
 
 ---
 
@@ -146,7 +146,7 @@ The theme file must be a valid JSON file that follows the same structure as a cu
 
 - Select your custom theme using the `/theme` command in Qwen Code. Your custom theme will appear in the theme selection dialog.
 - Or, set it as the default by adding `"theme": "MyCustomTheme"` to the `ui` object in your `settings.json`.
-- Custom themes can be set at the user, project, or system level, and follow the same [configuration precedence](./configuration.md) as other settings.
+- Custom themes can be set at the user, project, or system level, and follow the same [configuration precedence](../configuration/settings) as other settings.
 
 ## Themes Preview
 

docs/users/configuration/trusted-folders.md

@@ -56,6 +56,6 @@ If you need to change a decision or see all your settings, you have a couple of
 
 For advanced users, it's helpful to know the exact order of operations for how trust is determined:
 
-1.  **IDE Trust Signal**: If you are using the [IDE Integration](/users/ide-integration/ide-integration), the CLI first asks the IDE if the workspace is trusted. The IDE's response takes highest priority.
+1.  **IDE Trust Signal**: If you are using the [IDE Integration](../ide-integration/ide-integration), the CLI first asks the IDE if the workspace is trusted. The IDE's response takes highest priority.
 
 2.  **Local Trust File**: If the IDE is not connected, the CLI checks the central `~/.qwen/trustedFolders.json` file.

docs/users/extension/_meta.ts

@@ -0,0 +1,9 @@
+export default {
+  introduction: 'Introduction',
+  'getting-start-extensions': {
+    display: 'hidden',
+  },
+  'extension-releasing': {
+    display: 'hidden',
+  },
+};

docs/users/extension/getting-started-extensions.md

@@ -148,22 +148,107 @@ Custom commands provide a way to create shortcuts for complex prompts. Let's add
     mkdir -p commands/fs
     ```
 
-2.  Create a file named `commands/fs/grep-code.toml`:
+2.  Create a file named `commands/fs/grep-code.md`:
+
+    ```markdown
+    ---
+    description: Search for a pattern in code and summarize findings
+    ---
 
-    ```toml
-    prompt = """
     Please summarize the findings for the pattern `{{args}}`.
 
     Search Results:
     !{grep -r {{args}} .}
-    """
     ```
 
     This command, `/fs:grep-code`, will take an argument, run the `grep` shell command with it, and pipe the results into a prompt for summarization.
 
+> **Note:** Commands use Markdown format with optional YAML frontmatter. TOML format is deprecated but still supported for backwards compatibility.
+
 After saving the file, restart the Qwen Code. You can now run `/fs:grep-code "some pattern"` to use your new command.
 
-## Step 5: Add a Custom `QWEN.md`
+## Step 5: Add Custom Skills and Subagents (Optional)
+
+Extensions can also provide custom skills and subagents to extend Qwen Code's capabilities.
+
+### Adding a Custom Skill
+
+Skills are model-invoked capabilities that the AI can automatically use when relevant.
+
+1.  Create a `skills` directory with a skill subdirectory:
+
+    ```bash
+    mkdir -p skills/code-analyzer
+    ```
+
+2.  Create a `skills/code-analyzer/SKILL.md` file:
+
+    ```markdown
+    ---
+    name: code-analyzer
+    description: Analyzes code structure and provides insights about complexity, dependencies, and potential improvements
+    ---
+
+    # Code Analyzer
+
+    ## Instructions
+
+    When analyzing code, focus on:
+
+    - Code complexity and maintainability
+    - Dependencies and coupling
+    - Potential performance issues
+    - Suggestions for improvements
+
+    ## Examples
+
+    - "Analyze the complexity of this function"
+    - "What are the dependencies of this module?"
+    ```
+
+### Adding a Custom Subagent
+
+Subagents are specialized AI assistants for specific tasks.
+
+1.  Create an `agents` directory:
+
+    ```bash
+    mkdir -p agents
+    ```
+
+2.  Create an `agents/refactoring-expert.md` file:
+
+    ```markdown
+    ---
+    name: refactoring-expert
+    description: Specialized in code refactoring, improving code structure and maintainability
+    tools:
+      - read_file
+      - write_file
+      - read_many_files
+    ---
+
+    You are a refactoring specialist focused on improving code quality.
+
+    Your expertise includes:
+
+    - Identifying code smells and anti-patterns
+    - Applying SOLID principles
+    - Improving code readability and maintainability
+    - Safe refactoring with minimal risk
+
+    For each refactoring task:
+
+    1. Analyze the current code structure
+    2. Identify areas for improvement
+    3. Propose refactoring steps
+    4. Implement changes incrementally
+    5. Verify functionality is preserved
+    ```
+
+After restarting Qwen Code, your custom skills will be available via `/skills` and subagents via `/agents manage`.
+
+## Step 6: Add a Custom `QWEN.md`
 
 You can provide persistent context to the model by adding a `QWEN.md` file to your extension. This is useful for giving the model instructions on how to behave or information about your extension's tools. Note that you may not always need this for extensions built to expose commands and prompts.
 
@@ -194,7 +279,7 @@ You can provide persistent context to the model by adding a `QWEN.md` file to yo
 
 Restart the CLI again. The model will now have the context from your `QWEN.md` file in every session where the extension is active.
 
-## Step 6: Releasing Your Extension
+## Step 7: Releasing Your Extension
 
 Once you are happy with your extension, you can share it with others. The two primary ways of releasing extensions are via a Git repository or through GitHub Releases. Using a public Git repository is the simplest method.
 
@@ -207,6 +292,7 @@ You've successfully created a Qwen Code extension! You learned how to:
 - Bootstrap a new extension from a template.
 - Add custom tools with an MCP server.
 - Create convenient custom commands.
+- Add custom skills and subagents.
 - Provide persistent context to the model.
 - Link your extension for local development.
 

docs/users/extension/introduction.md

@@ -0,0 +1,290 @@
+# Qwen Code Extensions
+
+Qwen Code extensions package prompts, MCP servers, and custom commands into a familiar and user-friendly format. With extensions, you can expand the capabilities of Qwen Code and share those capabilities with others. They are designed to be easily installable and shareable.
+
+This cross-platform compatibility gives you access to a rich ecosystem of extensions and plugins, dramatically expanding Qwen Code's capabilities without requiring extension authors to maintain separate versions.
+
+## Extension management
+
+We offer a suite of extension management tools using both `qwen extensions` CLI commands and `/extensions` slash commands within the interactive CLI.
+
+### Runtime Extension Management (Slash Commands)
+
+You can manage extensions at runtime within the interactive CLI using `/extensions` slash commands. These commands support hot-reloading, meaning changes take effect immediately without restarting the application.
+
+| Command                                                | Description                                                       |
+| ------------------------------------------------------ | ----------------------------------------------------------------- |
+| `/extensions` or `/extensions list`                    | List all installed extensions with their status                   |
+| `/extensions install <source>`                         | Install an extension from a git URL, local path, or marketplace   |
+| `/extensions uninstall <name>`                         | Uninstall an extension                                            |
+| `/extensions enable <name> --scope <user\|workspace>`  | Enable an extension                                               |
+| `/extensions disable <name> --scope <user\|workspace>` | Disable an extension                                              |
+| `/extensions update <name>`                            | Update a specific extension                                       |
+| `/extensions update --all`                             | Update all extensions with available updates                      |
+| `/extensions explore [source]`                         | Open extensions source page(Gemini or ClaudeCode) in your browser |
+
+### CLI Extension Management
+
+You can also manage extensions using `qwen extensions` CLI commands. Note that changes made via CLI commands will be reflected in active CLI sessions on restart.
+
+### Installing an extension
+
+You can install an extension using `qwen extensions install` from multiple sources:
+
+#### From Gemini CLI Extensions Marketplace
+
+Qwen Code fully supports extensions from the [Gemini CLI Extensions Marketplace](https://geminicli.com/extensions/). Simply install them using the git URL:
+
+```bash
+qwen extensions install <gemini-cli-extension-url>
+```
+
+Gemini extensions are automatically converted to Qwen Code format during installation:
+
+- `gemini-extension.json` is converted to `qwen-extension.json`
+- TOML command files are automatically migrated to Markdown format
+- MCP servers, context files, and settings are preserved
+
+#### From Claude Code Marketplace
+
+Qwen Code also supports plugins from the [Claude Code Marketplace](https://claudemarketplaces.com/). Install them using the marketplace URL format:
+
+```bash
+qwen extensions install <claude-code-marketplace-url>:<plugin-name>
+```
+
+Claude plugins are automatically converted to Qwen Code format during installation:
+
+- `claude-plugin.json` is converted to `qwen-extension.json`
+- Agent configurations are converted to Qwen subagent format
+- Skill configurations are converted to Qwen skill format
+- Tool mappings are automatically handled
+
+> **Cross-Platform Compatibility**: This allows you to leverage the rich extension ecosystems from both Gemini CLI and Claude Code, dramatically expanding the available functionality for Qwen Code users.
+
+#### From Git Repository
+
+```bash
+qwen extensions install https://github.com/github/github-mcp-server
+```
+
+This will install the github mcp server extension.
+
+#### From Local Path
+
+```bash
+qwen extensions install /path/to/your/extension
+```
+
+Note that we create a copy of the installed extension, so you will need to run `qwen extensions update` to pull in changes from both locally-defined extensions and those on GitHub.
+
+### Uninstalling an extension
+
+To uninstall, run `qwen extensions uninstall extension-name`, so, in the case of the install example:
+
+```
+qwen extensions uninstall qwen-cli-security
+```
+
+### Disabling an extension
+
+Extensions are, by default, enabled across all workspaces. You can disable an extension entirely or for specific workspace.
+
+For example, `qwen extensions disable extension-name` will disable the extension at the user level, so it will be disabled everywhere. `qwen extensions disable extension-name --scope=workspace` will only disable the extension in the current workspace.
+
+### Enabling an extension
+
+You can enable extensions using `qwen extensions enable extension-name`. You can also enable an extension for a specific workspace using `qwen extensions enable extension-name --scope=workspace` from within that workspace.
+
+This is useful if you have an extension disabled at the top-level and only enabled in specific places.
+
+### Updating an extension
+
+For extensions installed from a local path or a git repository, you can explicitly update to the latest version (as reflected in the `qwen-extension.json` `version` field) with `qwen extensions update extension-name`.
+
+You can update all extensions with:
+
+```
+qwen extensions update --all
+```
+
+### Exploring Extension Marketplaces
+
+You can quickly browse available extensions from different marketplaces using the `/extensions explore` command:
+
+```bash
+# Open Gemini CLI Extensions marketplace
+/extensions explore Gemini
+
+# Open Claude Code marketplace
+/extensions explore ClaudeCode
+```
+
+This command opens the respective marketplace in your default browser, allowing you to discover new extensions to enhance your Qwen Code experience.
+
+## How it works
+
+On startup, Qwen Code looks for extensions in `<home>/.qwen/extensions`
+
+Extensions exist as a directory that contains a `qwen-extension.json` file. For example:
+
+`<home>/.qwen/extensions/my-extension/qwen-extension.json`
+
+### `qwen-extension.json`
+
+The `qwen-extension.json` file contains the configuration for the extension. The file has the following structure:
+
+```json
+{
+  "name": "my-extension",
+  "version": "1.0.0",
+  "mcpServers": {
+    "my-server": {
+      "command": "node my-server.js"
+    }
+  },
+  "contextFileName": "QWEN.md",
+  "commands": "commands",
+  "skills": "skills",
+  "agents": "agents",
+  "settings": [
+    {
+      "name": "API Key",
+      "description": "Your API key for the service",
+      "envVar": "MY_API_KEY",
+      "sensitive": true
+    }
+  ]
+}
+```
+
+- `name`: The name of the extension. This is used to uniquely identify the extension and for conflict resolution when extension commands have the same name as user or project commands. The name should be lowercase or numbers and use dashes instead of underscores or spaces. This is how users will refer to your extension in the CLI. Note that we expect this name to match the extension directory name.
+- `version`: The version of the extension.
+- `mcpServers`: A map of MCP servers to configure. The key is the name of the server, and the value is the server configuration. These servers will be loaded on startup just like MCP servers configured in a [`settings.json` file](./cli/configuration.md). If both an extension and a `settings.json` file configure an MCP server with the same name, the server defined in the `settings.json` file takes precedence.
+  - Note that all MCP server configuration options are supported except for `trust`.
+- `contextFileName`: The name of the file that contains the context for the extension. This will be used to load the context from the extension directory. If this property is not used but a `QWEN.md` file is present in your extension directory, then that file will be loaded.
+- `commands`: The directory containing custom commands (default: `commands`). Commands are `.md` files that define prompts.
+- `skills`: The directory containing custom skills (default: `skills`). Skills are discovered automatically and become available via the `/skills` command.
+- `agents`: The directory containing custom subagents (default: `agents`). Subagents are `.yaml` or `.md` files that define specialized AI assistants.
+- `settings`: An array of settings that the extension requires. When installing, users will be prompted to provide values for these settings. The values are stored securely and passed to MCP servers as environment variables.
+  - Each setting has the following properties:
+    - `name`: Display name for the setting
+    - `description`: A description of what this setting is used for
+    - `envVar`: The environment variable name that will be set
+    - `sensitive`: Boolean indicating if the value should be hidden (e.g., API keys, passwords)
+
+### Managing Extension Settings
+
+Extensions can require configuration through settings (such as API keys or credentials). These settings can be managed using the `qwen extensions settings` CLI command:
+
+**Set a setting value:**
+
+```bash
+qwen extensions settings set <extension-name> <setting-name> [--scope user|workspace]
+```
+
+**List all settings for an extension:**
+
+```bash
+qwen extensions settings list <extension-name>
+```
+
+**View current values (user and workspace):**
+
+```bash
+qwen extensions settings show <extension-name> <setting-name>
+```
+
+**Remove a setting value:**
+
+```bash
+qwen extensions settings unset <extension-name> <setting-name> [--scope user|workspace]
+```
+
+Settings can be configured at two levels:
+
+- **User level** (default): Settings apply across all projects (`~/.qwen/.env`)
+- **Workspace level**: Settings apply only to the current project (`.qwen/.env`)
+
+Workspace settings take precedence over user settings. Sensitive settings are stored securely and never displayed in plain text.
+
+When Qwen Code starts, it loads all the extensions and merges their configurations. If there are any conflicts, the workspace configuration takes precedence.
+
+### Custom commands
+
+Extensions can provide [custom commands](./cli/commands.md#custom-commands) by placing Markdown files in a `commands/` subdirectory within the extension directory. These commands follow the same format as user and project custom commands and use standard naming conventions.
+
+> **Note:** The command format has been updated from TOML to Markdown. TOML files are deprecated but still supported. You can migrate existing TOML commands using the automatic migration prompt that appears when TOML files are detected.
+
+**Example**
+
+An extension named `gcp` with the following structure:
+
+```
+.qwen/extensions/gcp/
+├── qwen-extension.json
+└── commands/
+    ├── deploy.md
+    └── gcs/
+        └── sync.md
+```
+
+Would provide these commands:
+
+- `/deploy` - Shows as `[gcp] Custom command from deploy.md` in help
+- `/gcs:sync` - Shows as `[gcp] Custom command from sync.md` in help
+
+### Custom skills
+
+Extensions can provide custom skills by placing skill files in a `skills/` subdirectory within the extension directory. Each skill should have a `SKILL.md` file with YAML frontmatter defining the skill's name and description.
+
+**Example**
+
+```
+.qwen/extensions/my-extension/
+├── qwen-extension.json
+└── skills/
+    └── pdf-processor/
+        └── SKILL.md
+```
+
+The skill will be available via the `/skills` command when the extension is active.
+
+### Custom subagents
+
+Extensions can provide custom subagents by placing agent configuration files in an `agents/` subdirectory within the extension directory. Agents are defined using YAML or Markdown files.
+
+**Example**
+
+```
+.qwen/extensions/my-extension/
+├── qwen-extension.json
+└── agents/
+    └── testing-expert.yaml
+```
+
+Extension subagents appear in the subagent manager dialog under "Extension Agents" section.
+
+### Conflict resolution
+
+Extension commands have the lowest precedence. When a conflict occurs with user or project commands:
+
+1. **No conflict**: Extension command uses its natural name (e.g., `/deploy`)
+2. **With conflict**: Extension command is renamed with the extension prefix (e.g., `/gcp.deploy`)
+
+For example, if both a user and the `gcp` extension define a `deploy` command:
+
+- `/deploy` - Executes the user's deploy command
+- `/gcp.deploy` - Executes the extension's deploy command (marked with `[gcp]` tag)
+
+## Variables
+
+Qwen Code extensions allow variable substitution in `qwen-extension.json`. This can be useful if e.g., you need the current directory to run an MCP server using `"cwd": "${extensionPath}${/}run.ts"`.
+
+**Supported variables:**
+
+| variable                   | description                                                                                                                                                   |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `${extensionPath}`         | The fully-qualified path of the extension in the user's filesystem e.g., '/Users/username/.qwen/extensions/example-extension'. This will not unwrap symlinks. |
+| `${workspacePath}`         | The fully-qualified path of the current workspace.                                                                                                            |
+| `${/} or ${pathSeparator}` | The path separator (differs per OS).                                                                                                                          |

docs/users/features/_meta.ts

@@ -1,6 +1,7 @@
 export default {
   commands: 'Commands',
   'sub-agents': 'SubAgents',
+  skills: 'Skills (Experimental)',
   headless: 'Headless Mode',
   checkpointing: {
     display: 'hidden',
@@ -9,4 +10,5 @@ export default {
   mcp: 'MCP',
   'token-caching': 'Token Caching',
   sandbox: 'Sandboxing',
+  language: 'i18n',
 };

docs/users/features/approval-mode.md

@@ -1,3 +1,5 @@
+# Approval Mode
+
 Qwen Code offers three distinct permission modes that allow you to flexibly control how AI interacts with your code and system based on task complexity and risk level.
 
 ## Permission Modes Comparison

docs/users/features/commands.md

@@ -20,10 +20,11 @@ These commands help you save, restore, and summarize work progress.
 
 | Command     | Description                                               | Usage Examples                       |
 | ----------- | --------------------------------------------------------- | ------------------------------------ |
+| `/init`     | Analyze current directory and create initial context file | `/init`                              |
 | `/summary`  | Generate project summary based on conversation history    | `/summary`                           |
 | `/compress` | Replace chat history with summary to save Tokens          | `/compress`                          |
+| `/resume`   | Resume a previous conversation session                    | `/resume`                            |
 | `/restore`  | Restore files to state before tool execution              | `/restore` (list) or `/restore <ID>` |
-| `/init`     | Analyze current directory and create initial context file | `/init`                              |
 
 ### 1.2 Interface and Workspace Control
 
@@ -47,7 +48,7 @@ Commands specifically for controlling interface and output language.
 | → `ui [language]`     | Set UI interface language        | `/language ui zh-CN`       |
 | → `output [language]` | Set LLM output language          | `/language output Chinese` |
 
-- Available UI languages: `zh-CN` (Simplified Chinese), `en-US` (English)
+- Available built-in UI languages: `zh-CN` (Simplified Chinese), `en-US` (English), `ru-RU` (Russian), `de-DE` (German)
 - Output language examples: `Chinese`, `English`, `Japanese`, etc.
 
 ### 1.4 Tool and Model Management
@@ -58,6 +59,7 @@ Commands for managing AI tools and models.
 | ---------------- | --------------------------------------------- | --------------------------------------------- |
 | `/mcp`           | List configured MCP servers and tools         | `/mcp`, `/mcp desc`                           |
 | `/tools`         | Display currently available tool list         | `/tools`, `/tools desc`                       |
+| `/skills`        | List and run available skills (experimental)  | `/skills`, `/skills <name>`                   |
 | `/approval-mode` | Change approval mode for tool usage           | `/approval-mode <mode (auto-edit)> --project` |
 | →`plan`          | Analysis only, no execution                   | Secure review                                 |
 | →`default`       | Require approval for edits                    | Daily use                                     |
@@ -71,17 +73,16 @@ Commands for managing AI tools and models.
 
 Commands for obtaining information and performing system settings.
 
-| Command         | Description                                     | Usage Examples                                   |
-| --------------- | ----------------------------------------------- | ------------------------------------------------ |
-| `/help`         | Display help information for available commands | `/help` or `/?`                                  |
-| `/about`        | Display version information                     | `/about`                                         |
-| `/stats`        | Display detailed statistics for current session | `/stats`                                         |
-| `/settings`     | Open settings editor                            | `/settings`                                      |
-| `/auth`         | Change authentication method                    | `/auth`                                          |
-| `/bug`          | Submit issue about Qwen Code                    | `/bug Button click unresponsive`                 |
-| `/copy`         | Copy last output content to clipboard           | `/copy`                                          |
-| `/quit-confirm` | Show confirmation dialog before quitting        | `/quit-confirm` (shortcut: press `Ctrl+C` twice) |
-| `/quit`         | Exit Qwen Code immediately                      | `/quit` or `/exit`                               |
+| Command     | Description                                     | Usage Examples                   |
+| ----------- | ----------------------------------------------- | -------------------------------- |
+| `/help`     | Display help information for available commands | `/help` or `/?`                  |
+| `/about`    | Display version information                     | `/about`                         |
+| `/stats`    | Display detailed statistics for current session | `/stats`                         |
+| `/settings` | Open settings editor                            | `/settings`                      |
+| `/auth`     | Change authentication method                    | `/auth`                          |
+| `/bug`      | Submit issue about Qwen Code                    | `/bug Button click unresponsive` |
+| `/copy`     | Copy last output content to clipboard           | `/copy`                          |
+| `/quit`     | Exit Qwen Code immediately                      | `/quit` or `/exit`               |
 
 ### 1.6 Common Shortcuts
 
@@ -120,6 +121,8 @@ Environment Variables: Commands executed via `!` will set the `QWEN_CODE=1` envi
 
 Save frequently used prompts as shortcut commands to improve work efficiency and ensure consistency.
 
+> **Note:** Custom commands now use Markdown format with optional YAML frontmatter. TOML format is deprecated but still supported for backwards compatibility. When TOML files are detected, an automatic migration prompt will be displayed.
+
 ### Quick Overview
 
 | Function         | Description                                | Advantages                             | Priority | Applicable Scenarios                                 |
@@ -134,14 +137,34 @@ Priority Rules: Project commands > User commands (project command used when name
 
 #### File Path to Command Name Mapping Table
 
-| File Location                | Generated Command | Example Call          |
-| ---------------------------- | ----------------- | --------------------- |
-| `~/.qwen/commands/test.toml` | `/test`           | `/test Parameter`     |
-| `<project>/git/commit.toml`  | `/git:commit`     | `/git:commit Message` |
+| File Location              | Generated Command | Example Call          |
+| -------------------------- | ----------------- | --------------------- |
+| `~/.qwen/commands/test.md` | `/test`           | `/test Parameter`     |
+| `<project>/git/commit.md`  | `/git:commit`     | `/git:commit Message` |
 
 Naming Rules: Path separator (`/` or `\`) converted to colon (`:`)
 
-### TOML File Format Specification
+### Markdown File Format Specification (Recommended)
+
+Custom commands use Markdown files with optional YAML frontmatter:
+
+```markdown
+---
+description: Optional description (displayed in /help)
+---
+
+Your prompt content here.
+Use {{args}} for parameter injection.
+```
+
+| Field         | Required | Description                              | Example                                    |
+| ------------- | -------- | ---------------------------------------- | ------------------------------------------ |
+| `description` | Optional | Command description (displayed in /help) | `description: Code analysis tool`          |
+| Prompt body   | Required | Prompt content sent to model             | Any Markdown content after the frontmatter |
+
+### TOML File Format (Deprecated)
+
+> **Deprecated:** TOML format is still supported but will be removed in a future version. Please migrate to Markdown format.
 
 | Field         | Required | Description                              | Example                                    |
 | ------------- | -------- | ---------------------------------------- | ------------------------------------------ |
@@ -190,15 +213,19 @@ Naming Rules: Path separator (`/` or `\`) converted to colon (`:`)
 
 Example: Git Commit Message Generation
 
-```
-# git/commit.toml
-description = "Generate Commit message based on staged changes"
-prompt = """
+````markdown
+---
+description: Generate Commit message based on staged changes
+---
+
 Please generate a Commit message based on the following diff:
-diff
+
+```diff
 !{git diff --staged}
-"""
 ```
+````
+
+````
 
 #### 4. File Content Injection (`@{...}`)
 
@@ -211,36 +238,38 @@ diff
 
 Example: Code Review Command
 
-```
-# review.toml
-description = "Code review based on best practices"
-prompt = """
+```markdown
+---
+description: Code review based on best practices
+---
+
 Review {{args}}, reference standards:
 
 @{docs/code-standards.md}
-"""
-```
+````
 
 ### Practical Creation Example
 
 #### "Pure Function Refactoring" Command Creation Steps Table
 
-| Operation                     | Command/Code                                |
-| ----------------------------- | ------------------------------------------- |
-| 1. Create directory structure | `mkdir -p ~/.qwen/commands/refactor`        |
-| 2. Create command file        | `touch ~/.qwen/commands/refactor/pure.toml` |
-| 3. Edit command content       | Refer to the complete code below.           |
-| 4. Test command               | `@file.js` → `/refactor:pure`               |
+| Operation                     | Command/Code                              |
+| ----------------------------- | ----------------------------------------- |
+| 1. Create directory structure | `mkdir -p ~/.qwen/commands/refactor`      |
+| 2. Create command file        | `touch ~/.qwen/commands/refactor/pure.md` |
+| 3. Edit command content       | Refer to the complete code below.         |
+| 4. Test command               | `@file.js` → `/refactor:pure`             |
 
-```# ~/.qwen/commands/refactor/pure.toml
-description = "Refactor code to pure function"
-prompt = """
-	Please analyze code in current context, refactor to pure function.
-	Requirements:
-		1. Provide refactored code
-		2. Explain key changes and pure function characteristic implementation
-		3. Maintain function unchanged
-	"""
+```markdown
+---
+description: Refactor code to pure function
+---
+
+Please analyze code in current context, refactor to pure function.
+Requirements:
+
+1. Provide refactored code
+2. Explain key changes and pure function characteristic implementation
+3. Maintain function unchanged
 ```
 
 ### Custom Command Best Practices Summary

docs/users/features/headless.md

@@ -189,21 +189,22 @@ qwen -p "Write code" --output-format stream-json --include-partial-messages | jq
 
 Key command-line options for headless usage:
 
-| Option                       | Description                                         | Example                                                                  |
-| ---------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------ |
-| `--prompt`, `-p`             | Run in headless mode                                | `qwen -p "query"`                                                        |
-| `--output-format`, `-o`      | Specify output format (text, json, stream-json)     | `qwen -p "query" --output-format json`                                   |
-| `--input-format`             | Specify input format (text, stream-json)            | `qwen --input-format text --output-format stream-json`                   |
-| `--include-partial-messages` | Include partial messages in stream-json output      | `qwen -p "query" --output-format stream-json --include-partial-messages` |
-| `--debug`, `-d`              | Enable debug mode                                   | `qwen -p "query" --debug`                                                |
-| `--all-files`, `-a`          | Include all files in context                        | `qwen -p "query" --all-files`                                            |
-| `--include-directories`      | Include additional directories                      | `qwen -p "query" --include-directories src,docs`                         |
-| `--yolo`, `-y`               | Auto-approve all actions                            | `qwen -p "query" --yolo`                                                 |
-| `--approval-mode`            | Set approval mode                                   | `qwen -p "query" --approval-mode auto_edit`                              |
-| `--continue`                 | Resume the most recent session for this project     | `qwen --continue -p "Pick up where we left off"`                         |
-| `--resume [sessionId]`       | Resume a specific session (or choose interactively) | `qwen --resume 123e... -p "Finish the refactor"`                         |
+| Option                       | Description                                             | Example                                                                  |
+| ---------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `--prompt`, `-p`             | Run in headless mode                                    | `qwen -p "query"`                                                        |
+| `--output-format`, `-o`      | Specify output format (text, json, stream-json)         | `qwen -p "query" --output-format json`                                   |
+| `--input-format`             | Specify input format (text, stream-json)                | `qwen --input-format text --output-format stream-json`                   |
+| `--include-partial-messages` | Include partial messages in stream-json output          | `qwen -p "query" --output-format stream-json --include-partial-messages` |
+| `--debug`, `-d`              | Enable debug mode                                       | `qwen -p "query" --debug`                                                |
+| `--all-files`, `-a`          | Include all files in context                            | `qwen -p "query" --all-files`                                            |
+| `--include-directories`      | Include additional directories                          | `qwen -p "query" --include-directories src,docs`                         |
+| `--yolo`, `-y`               | Auto-approve all actions                                | `qwen -p "query" --yolo`                                                 |
+| `--approval-mode`            | Set approval mode                                       | `qwen -p "query" --approval-mode auto_edit`                              |
+| `--continue`                 | Resume the most recent session for this project         | `qwen --continue -p "Pick up where we left off"`                         |
+| `--resume [sessionId]`       | Resume a specific session (or choose interactively)     | `qwen --resume 123e... -p "Finish the refactor"`                         |
+| `--experimental-skills`      | Enable experimental Skills (registers the `skill` tool) | `qwen --experimental-skills -p "What Skills are available?"`             |
 
-For complete details on all available configuration options, settings files, and environment variables, see the [Configuration Guide](/users/configuration/settings).
+For complete details on all available configuration options, settings files, and environment variables, see the [Configuration Guide](../configuration/settings).
 
 ## Examples
 
@@ -276,7 +277,7 @@ tail -5 usage.log
 
 ## Resources
 
-- [CLI Configuration](/users/configuration/settings#command-line-arguments) - Complete configuration guide
-- [Authentication](/users/configuration/settings#environment-variables-for-api-access) - Setup authentication
-- [Commands](/users/reference/cli-reference) - Interactive commands reference
-- [Tutorials](/users/quickstart) - Step-by-step automation guides
+- [CLI Configuration](../configuration/settings#command-line-arguments) - Complete configuration guide
+- [Authentication](../configuration/settings#environment-variables-for-api-access) - Setup authentication
+- [Commands](../features/commands) - Interactive commands reference
+- [Tutorials](../quickstart) - Step-by-step automation guides

docs/users/features/language.md

@@ -0,0 +1,136 @@
+# Internationalization (i18n) & Language
+
+Qwen Code is built for multilingual workflows: it supports UI localization (i18n/l10n) in the CLI, lets you choose the assistant output language, and allows custom UI language packs.
+
+## Overview
+
+From a user point of view, Qwen Code’s “internationalization” spans multiple layers:
+
+| Capability / Setting     | What it controls                                                       | Where stored                 |
+| ------------------------ | ---------------------------------------------------------------------- | ---------------------------- |
+| `/language ui`           | Terminal UI text (menus, system messages, prompts)                     | `~/.qwen/settings.json`      |
+| `/language output`       | Language the AI responds in (an output preference, not UI translation) | `~/.qwen/output-language.md` |
+| Custom UI language packs | Overrides/extends built-in UI translations                             | `~/.qwen/locales/*.js`       |
+
+## UI Language
+
+This is the CLI’s UI localization layer (i18n/l10n): it controls the language of menus, prompts, and system messages.
+
+### Setting the UI Language
+
+Use the `/language ui` command:
+
+```bash
+/language ui zh-CN    # Chinese
+/language ui en-US    # English
+/language ui ru-RU    # Russian
+/language ui de-DE    # German
+```
+
+Aliases are also supported:
+
+```bash
+/language ui zh       # Chinese
+/language ui en       # English
+/language ui ru       # Russian
+/language ui de       # German
+```
+
+### Auto-detection
+
+On first startup, Qwen Code detects your system locale and sets the UI language automatically.
+
+Detection priority:
+
+1. `QWEN_CODE_LANG` environment variable
+2. `LANG` environment variable
+3. System locale via JavaScript Intl API
+4. Default: English
+
+## LLM Output Language
+
+The LLM output language controls what language the AI assistant responds in, regardless of what language you type your questions in.
+
+### How It Works
+
+The LLM output language is controlled by a rule file at `~/.qwen/output-language.md`. This file is automatically included in the LLM's context during startup, instructing it to respond in the specified language.
+
+### Auto-detection
+
+On first startup, if no `output-language.md` file exists, Qwen Code automatically creates one based on your system locale. For example:
+
+- System locale `zh` creates a rule for Chinese responses
+- System locale `en` creates a rule for English responses
+- System locale `ru` creates a rule for Russian responses
+- System locale `de` creates a rule for German responses
+
+### Manual Setting
+
+Use `/language output <language>` to change:
+
+```bash
+/language output Chinese
+/language output English
+/language output Japanese
+/language output German
+```
+
+Any language name works. The LLM will be instructed to respond in that language.
+
+> [!note]
+>
+> After changing the output language, restart Qwen Code for the change to take effect.
+
+### File Location
+
+```
+~/.qwen/output-language.md
+```
+
+## Configuration
+
+### Via Settings Dialog
+
+1. Run `/settings`
+2. Find "Language" under General
+3. Select your preferred UI language
+
+### Via Environment Variable
+
+```bash
+export QWEN_CODE_LANG=zh
+```
+
+This influences auto-detection on first startup (if you haven’t set a UI language and no `output-language.md` file exists yet).
+
+## Custom Language Packs
+
+For UI translations, you can create custom language packs in `~/.qwen/locales/`:
+
+- Example: `~/.qwen/locales/es.js` for Spanish
+- Example: `~/.qwen/locales/fr.js` for French
+
+User directory takes precedence over built-in translations.
+
+> [!tip]
+>
+> Contributions are welcome! If you’d like to improve built-in translations or add new languages.
+> For a concrete example, see [PR #1238: feat(i18n): add Russian language support](https://github.com/QwenLM/qwen-code/pull/1238).
+
+### Language Pack Format
+
+```javascript
+// ~/.qwen/locales/es.js
+export default {
+  Hello: 'Hola',
+  Settings: 'Configuracion',
+  // ... more translations
+};
+```
+
+## Related Commands
+
+- `/language` - Show current language settings
+- `/language ui [lang]` - Set UI language
+- `/language output <language>` - Set LLM output language
+- `/settings` - Open settings dialog

docs/users/features/mcp.md

@@ -12,6 +12,7 @@ With MCP servers connected, you can ask Qwen Code to:
 - Automate workflows (repeatable tasks exposed as tools/prompts)
 
 > [!tip]
+>
 > If you’re looking for the “one command to get started”, jump to [Quick start](#quick-start).
 
 ## Quick start
@@ -51,7 +52,8 @@ qwen mcp add --scope user --transport http my-server http://localhost:3000/mcp
 ```
 
 > [!tip]
-> For advanced configuration layers (system defaults/system settings and precedence rules), see [Settings](/users/configuration/settings).
+>
+> For advanced configuration layers (system defaults/system settings and precedence rules), see [Settings](../configuration/settings).
 
 ## Configure servers
 
@@ -64,6 +66,7 @@ qwen mcp add --scope user --transport http my-server http://localhost:3000/mcp
 | `stdio`   | Local process (scripts, CLIs, Docker) on your machine             | `command`, `args` (+ optional `cwd`, `env`) |
 
 > [!note]
+>
 > If a server supports both, prefer **HTTP** over **SSE**.
 
 ### Configure via `settings.json` vs `qwen mcp add`

docs/users/features/sandbox.md

@@ -49,6 +49,8 @@ Cross-platform sandboxing with complete process isolation.
 
 By default, Qwen Code uses a published sandbox image (configured in the CLI package) and will pull it as needed.
 
+The container sandbox mounts your workspace and your `~/.qwen` directory into the container so auth and settings persist between runs.
+
 **Best for**: Strong isolation on any OS, consistent tooling inside a known image.
 
 ### Choosing a method
@@ -157,22 +159,13 @@ For a working allowlist-style proxy example, see: [Example Proxy Script](/develo
 
 ## Linux UID/GID handling
 
-The sandbox automatically handles user permissions on Linux. Override these permissions with:
+On Linux, Qwen Code defaults to enabling UID/GID mapping so the sandbox runs as your user (and reuses the mounted `~/.qwen`). Override with:
 
 ```bash
 export SANDBOX_SET_UID_GID=true   # Force host UID/GID
 export SANDBOX_SET_UID_GID=false  # Disable UID/GID mapping
 ```
 
-## Customizing the sandbox environment (Docker/Podman)
-
-If you need extra tools inside the container (e.g., `git`, `python`, `rg`), create a custom Dockerfile:
-
-- Path: `.qwen/sandbox.Dockerfile`
-- Then run with: `BUILD_SANDBOX=1 qwen -s ...`
-
-This builds a project-specific image based on the default sandbox image.
-
 ## Troubleshooting
 
 ### Common issues
@@ -220,6 +213,6 @@ qwen -s -p "run shell command: mount | grep workspace"
 
 ## Related documentation
 
-- [Configuration](/users/configuration/settings): Full configuration options.
-- [Commands](/users/reference/cli-reference): Available commands.
-- [Troubleshooting](/users/support/troubleshooting): General troubleshooting.
+- [Configuration](../configuration/settings): Full configuration options.
+- [Commands](../features/commands): Available commands.
+- [Troubleshooting](../support/troubleshooting): General troubleshooting.

docs/users/features/skills.md

@@ -0,0 +1,319 @@
+# Agent Skills (Experimental)
+
+> Create, manage, and share Skills to extend Qwen Code’s capabilities.
+
+This guide shows you how to create, use, and manage Agent Skills in **Qwen Code**. Skills are modular capabilities that extend the model’s effectiveness through organized folders containing instructions (and optionally scripts/resources).
+
+> [!note]
+>
+> Skills are currently **experimental** and must be enabled with `--experimental-skills`.
+
+## Prerequisites
+
+- Qwen Code (recent version)
+
+## How to enable
+
+### Via CLI flag
+
+```bash
+qwen --experimental-skills
+```
+
+### Via settings.json
+
+Add to your `~/.qwen/settings.json` or project's `.qwen/settings.json`:
+
+```json
+{
+  "tools": {
+    "experimental": {
+      "skills": true
+    }
+  }
+}
+```
+
+- Basic familiarity with Qwen Code ([Quickstart](../quickstart.md))
+
+## What are Agent Skills?
+
+Agent Skills package expertise into discoverable capabilities. Each Skill consists of a `SKILL.md` file with instructions that the model can load when relevant, plus optional supporting files like scripts and templates.
+
+### How Skills are invoked
+
+Skills are **model-invoked** — the model autonomously decides when to use them based on your request and the Skill’s description. This is different from slash commands, which are **user-invoked** (you explicitly type `/command`).
+
+If you want to invoke a Skill explicitly, use the `/skills` slash command:
+
+```bash
+/skills <skill-name>
+```
+
+The `/skills` command is only available when you run with `--experimental-skills`. Use autocomplete to browse available Skills and descriptions.
+
+### Benefits
+
+- Extend Qwen Code for your workflows
+- Share expertise across your team via git
+- Reduce repetitive prompting
+- Compose multiple Skills for complex tasks
+
+## Create a Skill
+
+Skills are stored as directories containing a `SKILL.md` file.
+
+### Personal Skills
+
+Personal Skills are available across all your projects. Store them in `~/.qwen/skills/`:
+
+```bash
+mkdir -p ~/.qwen/skills/my-skill-name
+```
+
+Use personal Skills for:
+
+- Your individual workflows and preferences
+- Experimental Skills you’re developing
+- Personal productivity helpers
+
+### Project Skills
+
+Project Skills are shared with your team. Store them in `.qwen/skills/` within your project:
+
+```bash
+mkdir -p .qwen/skills/my-skill-name
+```
+
+Use project Skills for:
+
+- Team workflows and conventions
+- Project-specific expertise
+- Shared utilities and scripts
+
+Project Skills can be checked into git and automatically become available to teammates.
+
+## Write `SKILL.md`
+
+Create a `SKILL.md` file with YAML frontmatter and Markdown content:
+
+```yaml
+---
+name: your-skill-name
+description: Brief description of what this Skill does and when to use it
+---
+
+# Your Skill Name
+
+## Instructions
+Provide clear, step-by-step guidance for Qwen Code.
+
+## Examples
+Show concrete examples of using this Skill.
+```
+
+### Field requirements
+
+Qwen Code currently validates that:
+
+- `name` is a non-empty string
+- `description` is a non-empty string
+
+Recommended conventions (not strictly enforced yet):
+
+- Use lowercase letters, numbers, and hyphens in `name`
+- Make `description` specific: include both **what** the Skill does and **when** to use it (key words users will naturally mention)
+
+## Add supporting files
+
+Create additional files alongside `SKILL.md`:
+
+```text
+my-skill/
+├── SKILL.md (required)
+├── reference.md (optional documentation)
+├── examples.md (optional examples)
+├── scripts/
+│   └── helper.py (optional utility)
+└── templates/
+    └── template.txt (optional template)
+```
+
+Reference these files from `SKILL.md`:
+
+````markdown
+For advanced usage, see [reference.md](reference.md).
+
+Run the helper script:
+
+```bash
+python scripts/helper.py input.txt
+```
+````
+
+## View available Skills
+
+When `--experimental-skills` is enabled, Qwen Code discovers Skills from:
+
+- Personal Skills: `~/.qwen/skills/`
+- Project Skills: `.qwen/skills/`
+- Extension Skills: Skills provided by installed extensions
+
+### Extension Skills
+
+Extensions can provide custom skills that become available when the extension is enabled. These skills are stored in the extension's `skills/` directory and follow the same format as personal and project skills.
+
+Extension skills are automatically discovered and loaded when:
+
+- The extension is installed and enabled
+- The `--experimental-skills` flag is enabled
+
+To see which extensions provide skills, check the extension's `qwen-extension.json` file for a `skills` field.
+
+To view available Skills, ask Qwen Code directly:
+
+```text
+What Skills are available?
+```
+
+Or inspect the filesystem:
+
+```bash
+# List personal Skills
+ls ~/.qwen/skills/
+
+# List project Skills (if in a project directory)
+ls .qwen/skills/
+
+# View a specific Skill’s content
+cat ~/.qwen/skills/my-skill/SKILL.md
+```
+
+## Test a Skill
+
+After creating a Skill, test it by asking questions that match your description.
+
+Example: if your description mentions “PDF files”:
+
+```text
+Can you help me extract text from this PDF?
+```
+
+The model autonomously decides to use your Skill if it matches the request — you don’t need to explicitly invoke it.
+
+## Debug a Skill
+
+If Qwen Code doesn’t use your Skill, check these common issues:
+
+### Make the description specific
+
+Too vague:
+
+```yaml
+description: Helps with documents
+```
+
+Specific:
+
+```yaml
+description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDFs, forms, or document extraction.
+```
+
+### Verify file path
+
+- Personal Skills: `~/.qwen/skills/<skill-name>/SKILL.md`
+- Project Skills: `.qwen/skills/<skill-name>/SKILL.md`
+
+```bash
+# Personal
+ls ~/.qwen/skills/my-skill/SKILL.md
+
+# Project
+ls .qwen/skills/my-skill/SKILL.md
+```
+
+### Check YAML syntax
+
+Invalid YAML prevents the Skill metadata from loading correctly.
+
+```bash
+cat SKILL.md | head -n 15
+```
+
+Ensure:
+
+- Opening `---` on line 1
+- Closing `---` before Markdown content
+- Valid YAML syntax (no tabs, correct indentation)
+
+### View errors
+
+Run Qwen Code with debug mode to see Skill loading errors:
+
+```bash
+qwen --experimental-skills --debug
+```
+
+## Share Skills with your team
+
+You can share Skills through project repositories:
+
+1. Add the Skill under `.qwen/skills/`
+2. Commit and push
+3. Teammates pull the changes and run with `--experimental-skills`
+
+```bash
+git add .qwen/skills/
+git commit -m "Add team Skill for PDF processing"
+git push
+```
+
+## Update a Skill
+
+Edit `SKILL.md` directly:
+
+```bash
+# Personal Skill
+code ~/.qwen/skills/my-skill/SKILL.md
+
+# Project Skill
+code .qwen/skills/my-skill/SKILL.md
+```
+
+Changes take effect the next time you start Qwen Code. If Qwen Code is already running, restart it to load the updates.
+
+## Remove a Skill
+
+Delete the Skill directory:
+
+```bash
+# Personal
+rm -rf ~/.qwen/skills/my-skill
+
+# Project
+rm -rf .qwen/skills/my-skill
+git commit -m "Remove unused Skill"
+```
+
+## Best practices
+
+### Keep Skills focused
+
+One Skill should address one capability:
+
+- Focused: “PDF form filling”, “Excel analysis”, “Git commit messages”
+- Too broad: “Document processing” (split into smaller Skills)
+
+### Write clear descriptions
+
+Help the model discover when to use Skills by including specific triggers:
+
+```yaml
+description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or .xlsx data.
+```
+
+### Test with your team
+
+- Does the Skill activate when expected?
+- Are the instructions clear?
+- Are there missing examples or edge cases?

docs/users/features/sub-agents.md

@@ -6,11 +6,11 @@ Subagents are specialized AI assistants that handle specific types of tasks with
 
 Subagents are independent AI assistants that:
 
-- **Specialize in specific tasks** - Each Subagent is configured with a focused system prompt for particular types of work
-- **Have separate context** - They maintain their own conversation history, separate from your main chat
-- **Use controlled tools** - You can configure which tools each Subagent has access to
-- **Work autonomously** - Once given a task, they work independently until completion or failure
-- **Provide detailed feedback** - You can see their progress, tool usage, and execution statistics in real-time
+- **Specialize in specific tasks** - Each Subagent is configured with a focused system prompt for particular types of work
+- **Have separate context** - They maintain their own conversation history, separate from your main chat
+- **Use controlled tools** - You can configure which tools each Subagent has access to
+- **Work autonomously** - Once given a task, they work independently until completion or failure
+- **Provide detailed feedback** - You can see their progress, tool usage, and execution statistics in real-time
 
 ## Key Benefits
 
@@ -59,7 +59,7 @@ AI: I'll delegate this to your testing specialist Subagents.
 
 ### CLI Commands
 
-Subagents are managed through the `/agents` slash command and its subcommands:
+Subagents are managed through the `/agents` slash command and its subcommands:
 
 **Usage:**：`/agents create`。Creates a new Subagent through a guided step wizard.
 
@@ -67,12 +67,26 @@ Subagents are managed through the `/agents` slash command and its subcommands:
 
 ### Storage Locations
 
-Subagents are stored as Markdown files in two locations:
+Subagents are stored as Markdown files in multiple locations:
 
-- **Project-level**: `.qwen/agents/` (takes precedence)
-- **User-level**: `~/.qwen/agents/` (fallback)
+- **Project-level**: `.qwen/agents/` (highest precedence)
+- **User-level**: `~/.qwen/agents/` (fallback)
+- **Extension-level**: Provided by installed extensions
 
-This allows you to have both project-specific agents and personal agents that work across all projects.
+This allows you to have project-specific agents, personal agents that work across all projects, and extension-provided agents that add specialized capabilities.
+
+### Extension Subagents
+
+Extensions can provide custom subagents that become available when the extension is enabled. These agents are stored in the extension's `agents/` directory and follow the same format as personal and project agents.
+
+Extension subagents:
+
+- Are automatically discovered when the extension is enabled
+- Appear in the `/agents manage` dialog under "Extension Agents" section
+- Cannot be edited directly (edit the extension source instead)
+- Follow the same configuration format as user-defined agents
+
+To see which extensions provide subagents, check the extension's `qwen-extension.json` file for an `agents` field.
 
 ### File Format
 
@@ -398,7 +412,7 @@ description: Helps with testing, documentation, code review, and deployment
 ---
 ```
 
-**Why:** Focused agents produce better results and are easier to maintain.
+**Why:** Focused agents produce better results and are easier to maintain.
 
 #### Clear Specialization
 
@@ -422,7 +436,7 @@ description: Works on frontend development tasks
 ---
 ```
 
-**Why:** Specific expertise leads to more targeted and effective assistance.
+**Why:** Specific expertise leads to more targeted and effective assistance.
 
 #### Actionable Descriptions
 
@@ -440,7 +454,7 @@ description: Reviews code for security vulnerabilities, performance issues, and
 description: A helpful code reviewer
 ```
 
-**Why:** Clear descriptions help the main AI choose the right agent for each task.
+**Why:** Clear descriptions help the main AI choose the right agent for each task.
 
 ### Configuration Best Practices
 

docs/users/ide-integration/ide-companion-spec.md

@@ -16,16 +16,15 @@ The plugin **MUST** run a local HTTP server that implements the **Model Context
 - **Endpoint:** The server should expose a single endpoint (e.g., `/mcp`) for all MCP communication.
 - **Port:** The server **MUST** listen on a dynamically assigned port (i.e., listen on port `0`).
 
-### 2. Discovery Mechanism: The Port File
+### 2. Discovery Mechanism: The Lock File
 
-For Qwen Code to connect, it needs to discover which IDE instance it's running in and what port your server is using. The plugin **MUST** facilitate this by creating a "discovery file."
+For Qwen Code to connect, it needs to discover what port your server is using. The plugin **MUST** facilitate this by creating a "lock file" and setting the port environment variable.
 
-- **How the CLI Finds the File:** The CLI determines the Process ID (PID) of the IDE it's running in by traversing the process tree. It then looks for a discovery file that contains this PID in its name.
-- **File Location:** The file must be created in a specific directory: `os.tmpdir()/qwen/ide/`. Your plugin must create this directory if it doesn't exist.
+- **How the CLI Finds the File:** The CLI reads the port from `QWEN_CODE_IDE_SERVER_PORT`, then reads `~/.qwen/ide/<PORT>.lock`. (Legacy fallbacks exist for older extensions; see note below.)
+- **File Location:** The file must be created in a specific directory: `~/.qwen/ide/`. Your plugin must create this directory if it doesn't exist.
 - **File Naming Convention:** The filename is critical and **MUST** follow the pattern:
-  `qwen-code-ide-server-${PID}-${PORT}.json`
-  - `${PID}`: The process ID of the parent IDE process. Your plugin must determine this PID and include it in the filename.
-  - `${PORT}`: The port your MCP server is listening on.
+  `<PORT>.lock`
+  - `<PORT>`: The port your MCP server is listening on.
 - **File Content & Workspace Validation:** The file **MUST** contain a JSON object with the following structure:
 
   ```json
@@ -33,21 +32,20 @@ For Qwen Code to connect, it needs to discover which IDE instance it's running i
     "port": 12345,
     "workspacePath": "/path/to/project1:/path/to/project2",
     "authToken": "a-very-secret-token",
-    "ideInfo": {
-      "name": "vscode",
-      "displayName": "VS Code"
-    }
+    "ppid": 1234,
+    "ideName": "VS Code"
   }
   ```
   - `port` (number, required): The port of the MCP server.
   - `workspacePath` (string, required): A list of all open workspace root paths, delimited by the OS-specific path separator (`:` for Linux/macOS, `;` for Windows). The CLI uses this path to ensure it's running in the same project folder that's open in the IDE. If the CLI's current working directory is not a sub-directory of `workspacePath`, the connection will be rejected. Your plugin **MUST** provide the correct, absolute path(s) to the root of the open workspace(s).
   - `authToken` (string, required): A secret token for securing the connection. The CLI will include this token in an `Authorization: Bearer <token>` header on all requests.
-  - `ideInfo` (object, required): Information about the IDE.
-    - `name` (string, required): A short, lowercase identifier for the IDE (e.g., `vscode`, `jetbrains`).
-    - `displayName` (string, required): A user-friendly name for the IDE (e.g., `VS Code`, `JetBrains IDE`).
+  - `ppid` (number, required): The parent process ID of the IDE process.
+  - `ideName` (string, required): A user-friendly name for the IDE (e.g., `VS Code`, `JetBrains IDE`).
 
 - **Authentication:** To secure the connection, the plugin **MUST** generate a unique, secret token and include it in the discovery file. The CLI will then include this token in the `Authorization` header for all requests to the MCP server (e.g., `Authorization: Bearer a-very-secret-token`). Your server **MUST** validate this token on every request and reject any that are unauthorized.
-- **Tie-Breaking with Environment Variables (Recommended):** For the most reliable experience, your plugin **SHOULD** both create the discovery file and set the `QWEN_CODE_IDE_SERVER_PORT` environment variable in the integrated terminal. The file serves as the primary discovery mechanism, but the environment variable is crucial for tie-breaking. If a user has multiple IDE windows open for the same workspace, the CLI uses the `QWEN_CODE_IDE_SERVER_PORT` variable to identify and connect to the correct window's server.
+- **Environment Variables (Required):** Your plugin **MUST** set `QWEN_CODE_IDE_SERVER_PORT` in the integrated terminal so the CLI can locate the correct `<PORT>.lock` file.
+
+**Legacy note:** For extensions older than v0.5.1, Qwen Code may fall back to reading JSON files in the system temp directory named `qwen-code-ide-server-<PID>.json` or `qwen-code-ide-server-<PORT>.json`. New integrations should not rely on these legacy files.
 
 ## II. The Context Interface
 

docs/users/ide-integration/ide-integration.md

@@ -2,7 +2,7 @@
 
 Qwen Code can integrate with your IDE to provide a more seamless and context-aware experience. This integration allows the CLI to understand your workspace better and enables powerful features like native in-editor diffing.
 
-Currently, the only supported IDE is [Visual Studio Code](https://code.visualstudio.com/) and other editors that support VS Code extensions. To build support for other editors, see the [IDE Companion Extension Spec](/users/ide-integration/ide-companion-spec).
+Currently, the only supported IDE is [Visual Studio Code](https://code.visualstudio.com/) and other editors that support VS Code extensions. To build support for other editors, see the [IDE Companion Extension Spec](../ide-integration/ide-companion-spec).
 
 ## Features
 

docs/users/integration-github-action.md

@@ -6,41 +6,14 @@
 
 Use it to perform GitHub pull request reviews, triage issues, perform code analysis and modification, and more using [Qwen Code] conversationally (e.g., `@qwencoder fix this issue`) directly inside your GitHub repositories.
 
-- [qwen-code-action](#qwen-code-action)
-  - [Overview](#overview)
-  - [Features](#features)
-  - [Quick Start](#quick-start)
-    - [1. Get a Qwen API Key](#1-get-a-qwen-api-key)
-    - [2. Add it as a GitHub Secret](#2-add-it-as-a-github-secret)
-    - [3. Update your .gitignore](#3-update-your-gitignore)
-    - [4. Choose a Workflow](#4-choose-a-workflow)
-    - [5. Try it out](#5-try-it-out)
-  - [Workflows](#workflows)
-    - [Qwen Code Dispatch](#qwen-code-dispatch)
-    - [Issue Triage](#issue-triage)
-    - [Pull Request Review](#pull-request-review)
-    - [Qwen Code CLI Assistant](#qwen-code-cli-assistant)
-  - [Configuration](#configuration)
-    - [Inputs](#inputs)
-    - [Outputs](#outputs)
-    - [Repository Variables](#repository-variables)
-    - [Secrets](#secrets)
-  - [Authentication](#authentication)
-    - [GitHub Authentication](#github-authentication)
-  - [Extensions](#extensions)
-  - [Best Practices](#best-practices)
-  - [Customization](#customization)
-  - [Contributing](#contributing)
-
 ## Features
 
 - **Automation**: Trigger workflows based on events (e.g. issue opening) or schedules (e.g. nightly).
 - **On-demand Collaboration**: Trigger workflows in issue and pull request
-  comments by mentioning the [Qwen Code CLI] (e.g., `@qwencoder /review`).
-- **Extensible with Tools**: Leverage [Qwen Code] models' tool-calling capabilities to
-  interact with other CLIs like the [GitHub CLI] (`gh`).
+  comments by mentioning the [Qwen Code CLI](./features/commands) (e.g., `@qwencoder /review`).
+- **Extensible with Tools**: Leverage [Qwen Code](../developers/tools/introduction.md) models' tool-calling capabilities to interact with other CLIs like the [GitHub CLI] (`gh`).
 - **Customizable**: Use a `QWEN.md` file in your repository to provide
-  project-specific instructions and context to [Qwen Code CLI].
+  project-specific instructions and context to [Qwen Code CLI](./features/commands).
 
 ## Quick Start
 
@@ -48,7 +21,7 @@ Get started with Qwen Code CLI in your repository in just a few minutes:
 
 ### 1. Get a Qwen API Key
 
-Obtain your API key from [DashScope] (Alibaba Cloud's AI platform)
+Obtain your API key from [DashScope](https://help.aliyun.com/zh/model-studio/qwen-code) (Alibaba Cloud's AI platform)
 
 ### 2. Add it as a GitHub Secret
 
@@ -90,7 +63,7 @@ You have two options to set up a workflow:
 
 **Option B: Manually copy workflows**
 
-1. Copy the pre-built workflows from the [`examples/workflows`](./examples/workflows) directory to your repository's `.github/workflows` directory. Note: the `qwen-dispatch.yml` workflow must also be copied, which triggers the workflows to run.
+1. Copy the pre-built workflows from the [`examples/workflows`](./common-workflow) directory to your repository's `.github/workflows` directory. Note: the `qwen-dispatch.yml` workflow must also be copied, which triggers the workflows to run.
 
 ### 5. Try it out
 
@@ -119,30 +92,19 @@ This action provides several pre-built workflows for different use cases. Each w
 
 ### Qwen Code Dispatch
 
-This workflow acts as a central dispatcher for Qwen Code CLI, routing requests to
-the appropriate workflow based on the triggering event and the command provided
-in the comment. For a detailed guide on how to set up the dispatch workflow, go
-to the
-[Qwen Code Dispatch workflow documentation](./examples/workflows/qwen-dispatch).
+This workflow acts as a central dispatcher for Qwen Code CLI, routing requests to the appropriate workflow based on the triggering event and the command provided in the comment. For a detailed guide on how to set up the dispatch workflow, go to the [Qwen Code Dispatch workflow documentation](./common-workflow).
 
 ### Issue Triage
 
-This action can be used to triage GitHub Issues automatically or on a schedule.
-For a detailed guide on how to set up the issue triage system, go to the
-[GitHub Issue Triage workflow documentation](./examples/workflows/issue-triage).
+This action can be used to triage GitHub Issues automatically or on a schedule. For a detailed guide on how to set up the issue triage system, go to the [GitHub Issue Triage workflow documentation](./examples/workflows/issue-triage).
 
 ### Pull Request Review
 
-This action can be used to automatically review pull requests when they are
-opened. For a detailed guide on how to set up the pull request review system,
-go to the [GitHub PR Review workflow documentation](./examples/workflows/pr-review).
+This action can be used to automatically review pull requests when they are opened. For a detailed guide on how to set up the pull request review system, go to the [GitHub PR Review workflow documentation](./common-workflow).
 
 ### Qwen Code CLI Assistant
 
-This type of action can be used to invoke a general-purpose, conversational Qwen Code
-AI assistant within the pull requests and issues to perform a wide range of
-tasks. For a detailed guide on how to set up the general-purpose Qwen Code CLI workflow,
-go to the [Qwen Code Assistant workflow documentation](./examples/workflows/qwen-assistant).
+This type of action can be used to invoke a general-purpose, conversational Qwen Code AI assistant within the pull requests and issues to perform a wide range of tasks. For a detailed guide on how to set up the general-purpose Qwen Code CLI workflow, go to the [Qwen Code Assistant workflow documentation](./common-workflow).
 
 ## Configuration
 
@@ -222,8 +184,7 @@ To add a secret:
 2. Enter the secret name and value.
 3. Save.
 
-For more information, refer to the
-[official GitHub documentation on creating and using encrypted secrets][secrets].
+For more information, refer to the [official GitHub documentation on creating and using encrypted secrets][secrets].
 
 ## Authentication
 
@@ -239,7 +200,7 @@ You can authenticate with GitHub in two ways:
    authentication, we recommend creating a custom GitHub App.
 
 For detailed setup instructions for both Qwen and GitHub authentication, go to the
-[**Authentication documentation**](./docs/authentication.md).
+[**Authentication documentation**](./configuration/auth).
 
 ## Extensions
 
@@ -247,7 +208,7 @@ The Qwen Code CLI can be extended with additional functionality through extensio
 These extensions are installed from source from their GitHub repositories.
 
 For detailed instructions on how to set up and configure extensions, go to the
-[Extensions documentation](./docs/extensions.md).
+[Extensions documentation](../developers/extensions/extension).
 
 ## Best Practices
 
@@ -258,20 +219,18 @@ Key recommendations include:
 - **Securing Your Repository:** Implementing branch and tag protection, and restricting pull request approvers.
 - **Monitoring and Auditing:** Regularly reviewing action logs and enabling OpenTelemetry for deeper insights into performance and behavior.
 
-For a comprehensive guide on securing your repository and workflows, please refer to our [**Best Practices documentation**](./docs/best-practices.md).
+For a comprehensive guide on securing your repository and workflows, please refer to our [**Best Practices documentation**](./common-workflow).
 
 ## Customization
 
-Create a [QWEN.md] file in the root of your repository to provide
-project-specific context and instructions to [Qwen Code CLI]. This is useful for defining
+Create a QWEN.md file in the root of your repository to provide
+project-specific context and instructions to [Qwen Code CLI](./common-workflow). This is useful for defining
 coding conventions, architectural patterns, or other guidelines the model should
 follow for a given repository.
 
 ## Contributing
 
-Contributions are welcome! Check out the Qwen Code CLI
-[**Contributing Guide**](./CONTRIBUTING.md) for more details on how to get
-started.
+Contributions are welcome! Check out the Qwen Code CLI **Contributing Guide** for more details on how to get started.
 
 [secrets]: https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions
 [Qwen Code]: https://github.com/QwenLM/qwen-code

docs/users/integration-jetbrains.md

@@ -0,0 +1,57 @@
+# JetBrains IDEs
+
+> JetBrains IDEs provide native support for AI coding assistants through the Agent Client Protocol (ACP). This integration allows you to use Qwen Code directly within your JetBrains IDE with real-time code suggestions.
+
+### Features
+
+- **Native agent experience**: Integrated AI assistant panel within your JetBrains IDE
+- **Agent Client Protocol**: Full support for ACP enabling advanced IDE interactions
+- **Symbol management**: #-mention files to add them to the conversation context
+- **Conversation history**: Access to past conversations within the IDE
+
+### Requirements
+
+- JetBrains IDE with ACP support (IntelliJ IDEA, WebStorm, PyCharm, etc.)
+- Qwen Code CLI installed
+
+### Installation
+
+1. Install Qwen Code CLI:
+
+   ```bash
+   npm install -g @qwen-code/qwen-code
+   ```
+
+2. Open your JetBrains IDE and navigate to AI Chat tool window.
+
+3. Click the 3-dot menu in the upper-right corner and select **Configure ACP Agent** and configure Qwen Code with the following settings:
+
+```json
+{
+  "agent_servers": {
+    "qwen": {
+      "command": "/path/to/qwen",
+      "args": ["--acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+4. The Qwen Code agent should now be available in the AI Assistant panel
+
+![Qwen Code in JetBrains AI Chat](https://img.alicdn.com/imgextra/i3/O1CN01ZxYel21y433Ci6eg0_!!6000000006524-2-tps-2774-1494.png)
+
+## Troubleshooting
+
+### Agent not appearing
+
+- Run `qwen --version` in terminal to verify installation
+- Ensure your JetBrains IDE version supports ACP
+- Restart your JetBrains IDE
+
+### Qwen Code not responding
+
+- Check your internet connection
+- Verify CLI works by running `qwen` in terminal
+- [File an issue on GitHub](https://github.com/qwenlm/qwen-code/issues) if the problem persists

docs/users/integration-vscode.md

@@ -4,7 +4,7 @@
 
 <br/>
 
-<video src="https://cloud.video.taobao.com/vod/JnvYMhUia2EKFAaiuErqNpzWE9mz3odG76vArAHNg94.mp4" controls width="800">
+<video src="https://cloud.video.taobao.com/vod/IKKwfM-kqNI3OJjM_U8uMCSMAoeEcJhs6VNCQmZxUfk.mp4" controls width="800">
   Your browser does not support the video tag.
 </video>
 
@@ -18,23 +18,17 @@
 
 ### Requirements
 
-- VS Code 1.98.0 or higher
+- VS Code 1.85.0 or higher
 
 ### Installation
 
-1. Install Qwen Code CLI:
-
-   ```bash
-   npm install -g qwen-code
-   ```
-
-2. Download and install the extension from the [Visual Studio Code Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=qwenlm.qwen-code-vscode-ide-companion).
+Download and install the extension from the [Visual Studio Code Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=qwenlm.qwen-code-vscode-ide-companion).
 
 ## Troubleshooting
 
 ### Extension not installing
 
-- Ensure you have VS Code 1.98.0 or higher
+- Ensure you have VS Code 1.85.0 or higher
 - Check that VS Code has permission to install extensions
 - Try installing directly from the Marketplace website
 

docs/users/integration-zed.md

@@ -1,13 +1,13 @@
 # Zed Editor
 
-> Zed Editor provides native support for AI coding assistants through the Agent Control Protocol (ACP). This integration allows you to use Qwen Code directly within Zed's interface with real-time code suggestions.
+> Zed Editor provides native support for AI coding assistants through the Agent Client Protocol (ACP). This integration allows you to use Qwen Code directly within Zed's interface with real-time code suggestions.
 
 ![Zed Editor Overview](https://img.alicdn.com/imgextra/i1/O1CN01aAhU311GwEoNh27FP_!!6000000000686-2-tps-3024-1898.png)
 
 ### Features
 
 - **Native agent experience**: Integrated AI assistant panel within Zed's interface
-- **Agent Control Protocol**: Full support for ACP enabling advanced IDE interactions
+- **Agent Client Protocol**: Full support for ACP enabling advanced IDE interactions
 - **File management**: @-mention files to add them to the conversation context
 - **Conversation history**: Access to past conversations within Zed
 
@@ -20,9 +20,9 @@
 
 1. Install Qwen Code CLI:
 
-   ```bash
-   npm install -g qwen-code
-   ```
+```bash
+npm install -g @qwen-code/qwen-code
+```
 
 2. Download and install [Zed Editor](https://zed.dev/)
 
@@ -32,7 +32,7 @@
 "Qwen Code": {
   "type": "custom",
   "command": "qwen",
-  "args": ["--experimental-acp"],
+  "args": ["--acp"],
   "env": {}
 }
 ```

docs/users/overview.md

@@ -1,5 +1,8 @@
 # Qwen Code overview
 
+[![@qwen-code/qwen-code downloads](https://img.shields.io/npm/dw/@qwen-code/qwen-code.svg)](https://npm-compare.com/@qwen-code/qwen-code)
+[![@qwen-code/qwen-code version](https://img.shields.io/npm/v/@qwen-code/qwen-code.svg)](https://www.npmjs.com/package/@qwen-code/qwen-code)
+
 > Learn about Qwen Code, Qwen's agentic coding tool that lives in your terminal and helps you turn ideas into code faster than ever before.
 
 ## Get started in 30 seconds
@@ -36,27 +39,27 @@ Select **Qwen OAuth (Free)** authentication and follow the prompts to log in. Th
 what does this project do?
 ```
 
-![](https://gw.alicdn.com/imgextra/i2/O1CN01XoPbZm1CrsZzvMQ6m_!!6000000000135-1-tps-772-646.gif)
+![](https://cloud.video.taobao.com/vod/j7-QtQScn8UEAaEdiv619fSkk5p-t17orpDbSqKVL5A.mp4)
 
-You'll be prompted to log in on first use. That's it! [Continue with Quickstart (5 mins) →](/users/quickstart)
+You'll be prompted to log in on first use. That's it! [Continue with Quickstart (5 mins) →](./quickstart)
 
 > [!tip]
 >
-> See [troubleshooting](/users/support/troubleshooting) if you hit issues.
+> See [troubleshooting](./support/troubleshooting) if you hit issues.
 
 > [!note]
 >
-> **New VS Code Extension (Beta)**: Prefer a graphical interface? Our new **VS Code extension** provides an easy-to-use native IDE experience without requiring terminal familiarity. Simply install from the marketplace and start coding with Qwen Code directly in your sidebar. You can search for **Qwen Code** in the VS Code Marketplace and download it.
+> **New VS Code Extension (Beta)**: Prefer a graphical interface? Our new **VS Code extension** provides an easy-to-use native IDE experience without requiring terminal familiarity. Simply install from the marketplace and start coding with Qwen Code directly in your sidebar. Download and install the [Qwen Code Companion](https://marketplace.visualstudio.com/items?itemName=qwenlm.qwen-code-vscode-ide-companion) now.
 
 ## What Qwen Code does for you
 
 - **Build features from descriptions**: Tell Qwen Code what you want to build in plain language. It will make a plan, write the code, and ensure it works.
 - **Debug and fix issues**: Describe a bug or paste an error message. Qwen Code will analyze your codebase, identify the problem, and implement a fix.
-- **Navigate any codebase**: Ask anything about your team's codebase, and get a thoughtful answer back. Qwen Code maintains awareness of your entire project structure, can find up-to-date information from the web, and with [MCP](/users/features/mcp) can pull from external datasources like Google Drive, Figma, and Slack.
+- **Navigate any codebase**: Ask anything about your team's codebase, and get a thoughtful answer back. Qwen Code maintains awareness of your entire project structure, can find up-to-date information from the web, and with [MCP](./features/mcp) can pull from external datasources like Google Drive, Figma, and Slack.
 - **Automate tedious tasks**: Fix fiddly lint issues, resolve merge conflicts, and write release notes. Do all this in a single command from your developer machines, or automatically in CI.
 
 ## Why developers love Qwen Code
 
 - **Works in your terminal**: Not another chat window. Not another IDE. Qwen Code meets you where you already work, with the tools you already love.
-- **Takes action**: Qwen Code can directly edit files, run commands, and create commits. Need more? [MCP](/users/features/mcp) lets Qwen Code read your design docs in Google Drive, update your tickets in Jira, or use _your_ custom developer tooling.
+- **Takes action**: Qwen Code can directly edit files, run commands, and create commits. Need more? [MCP](./features/mcp) lets Qwen Code read your design docs in Google Drive, update your tickets in Jira, or use _your_ custom developer tooling.
 - **Unix philosophy**: Qwen Code is composable and scriptable. `tail -f app.log | qwen -p "Slack me if you see any anomalies appear in this log stream"` _works_. Your CI can run `qwen -p "If there are new text strings, translate them into French and raise a PR for @lang-fr-team to review"`.

docs/users/quickstart.md

@@ -159,7 +159,7 @@ Qwen Code will:
 
 ### Test out other common workflows
 
-There are a number of ways to work with Claude:
+There are a number of ways to work with Qwen Code:
 
 **Refactor code**
 
@@ -206,7 +206,7 @@ Here are the most important commands for daily use:
 | → `output [language]` | Set LLM output language                          | `/language output Chinese`    |
 | `/quit`               | Exit Qwen Code immediately                       | `/quit` or `/exit`            |
 
-See the [CLI reference](/users/reference/cli-reference) for a complete list of commands.
+See the [CLI reference](./features/commands) for a complete list of commands.
 
 ## Pro tips for beginners
 
@@ -225,9 +225,9 @@ See the [CLI reference](/users/reference/cli-reference) for a complete list of c
 3. build a webpage that allows users to see and edit their information
 ```
 
-**Let Claude explore first**
+**Let Qwen Code explore first**
 
-- Before making changes, let Claude understand your code:
+- Before making changes, let Qwen Code understand your code:
 
 ```
 analyze the database schema

docs/users/reference/keyboard-shortcuts.md

@@ -20,6 +20,7 @@ This document lists the available keyboard shortcuts in Qwen Code.
 | Shortcut                                           | Description                                                                                                                         |
 | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
 | `!`                                                | Toggle shell mode when the input is empty.                                                                                          |
+| `?`                                                | Toggle keyboard shortcuts display when the input is empty.                                                                          |
 | `\` (at end of line) + `Enter`                     | Insert a newline.                                                                                                                   |
 | `Down Arrow`                                       | Navigate down through the input history.                                                                                            |
 | `Enter`                                            | Submit the current prompt.                                                                                                          |
@@ -38,6 +39,7 @@ This document lists the available keyboard shortcuts in Qwen Code.
 | `Ctrl+Left Arrow` / `Meta+Left Arrow` / `Meta+B`   | Move the cursor one word to the left.                                                                                               |
 | `Ctrl+N`                                           | Navigate down through the input history.                                                                                            |
 | `Ctrl+P`                                           | Navigate up through the input history.                                                                                              |
+| `Ctrl+R`                                           | Reverse search through input/shell history.                                                                                         |
 | `Ctrl+Right Arrow` / `Meta+Right Arrow` / `Meta+F` | Move the cursor one word to the right.                                                                                              |
 | `Ctrl+U`                                           | Delete from the cursor to the beginning of the line.                                                                                |
 | `Ctrl+V`                                           | Paste clipboard content. If the clipboard contains an image, it will be saved and a reference to it will be inserted in the prompt. |

docs/users/support/tos-privacy.md

@@ -23,7 +23,7 @@ When you authenticate using your qwen.ai account, these Terms of Service and Pri
 - **Terms of Service:** Your use is governed by the [Qwen Terms of Service](https://qwen.ai/termsservice).
 - **Privacy Notice:** The collection and use of your data is described in the [Qwen Privacy Policy](https://qwen.ai/privacypolicy).
 
-For details about authentication setup, quotas, and supported features, see [Authentication Setup](/users/configuration/settings).
+For details about authentication setup, quotas, and supported features, see [Authentication Setup](../configuration/settings).
 
 ## 2. If you are using OpenAI-Compatible API Authentication
 
@@ -37,7 +37,7 @@ Qwen Code supports various OpenAI-compatible providers. Please refer to your spe
 
 ## Usage Statistics and Telemetry
 
-Qwen Code may collect anonymous usage statistics and [telemetry](/developers/development/telemetry) data to improve the user experience and product quality. This data collection is optional and can be controlled through configuration settings.
+Qwen Code may collect anonymous usage statistics and [telemetry](../../developers/development/telemetry) data to improve the user experience and product quality. This data collection is optional and can be controlled through configuration settings.
 
 ### What Data is Collected
 
@@ -91,4 +91,4 @@ You can switch between Qwen OAuth and OpenAI-compatible API authentication at an
 2. **Within the CLI**: Use the `/auth` command to reconfigure your authentication method
 3. **Environment variables**: Set up `.env` files for automatic OpenAI-compatible API authentication
 
-For detailed instructions, see the [Authentication Setup](/users/configuration/settings#environment-variables-for-api-access) documentation.
+For detailed instructions, see the [Authentication Setup](../configuration/settings#environment-variables-for-api-access) documentation.

docs/users/support/troubleshooting.md

@@ -9,11 +9,18 @@ This guide provides solutions to common issues and debugging tips, including top
 
 ## Authentication or login errors
 
-- **Error: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` or `unable to get local issuer certificate`**
+- **Error: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, `UNABLE_TO_VERIFY_LEAF_SIGNATURE`, or `unable to get local issuer certificate`**
   - **Cause:** You may be on a corporate network with a firewall that intercepts and inspects SSL/TLS traffic. This often requires a custom root CA certificate to be trusted by Node.js.
   - **Solution:** Set the `NODE_EXTRA_CA_CERTS` environment variable to the absolute path of your corporate root CA certificate file.
     - Example: `export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt`
 
+- **Error: `Device authorization flow failed: fetch failed`**
+  - **Cause:** Node.js could not reach Qwen OAuth endpoints (often a proxy or SSL/TLS trust issue). When available, Qwen Code will also print the underlying error cause (for example: `UNABLE_TO_VERIFY_LEAF_SIGNATURE`).
+  - **Solution:**
+    - Confirm you can access `https://chat.qwen.ai` from the same machine/network.
+    - If you are behind a proxy, set it via `qwen --proxy <url>` (or the `proxy` setting in `settings.json`).
+    - If your network uses a corporate TLS inspection CA, set `NODE_EXTRA_CA_CERTS` as described above.
+
 - **Issue: Unable to display UI after authentication failure**
   - **Cause:** If authentication fails after selecting an authentication type, the `security.auth.selectedType` setting may be persisted in `settings.json`. On restart, the CLI may get stuck trying to authenticate with the failed auth type and fail to display the UI.
   - **Solution:** Clear the `security.auth.selectedType` configuration item in your `settings.json` file:
@@ -31,7 +38,7 @@ This guide provides solutions to common issues and debugging tips, including top
     1. In your home directory: `~/.qwen/settings.json`.
     2. In your project's root directory: `./.qwen/settings.json`.
 
-    Refer to [Qwen Code Configuration](/users/configuration/settings) for more details.
+    Refer to [Qwen Code Configuration](../configuration/settings) for more details.
 
 - **Q: Why don't I see cached token counts in my stats output?**
   - A: Cached token information is only displayed when cached tokens are being used. This feature is available for API key users (Qwen API key or Google Cloud Vertex AI) but not for OAuth users (such as Google Personal/Enterprise accounts like Google Gmail or Google Workspace, respectively). This is because the Qwen Code Assist API does not support cached content creation. You can still view your total token usage using the `/stats` command.
@@ -59,7 +66,7 @@ This guide provides solutions to common issues and debugging tips, including top
 
 - **Error: "Operation not permitted", "Permission denied", or similar.**
   - **Cause:** When sandboxing is enabled, Qwen Code may attempt operations that are restricted by your sandbox configuration, such as writing outside the project directory or system temp directory.
-  - **Solution:** Refer to the [Configuration: Sandboxing](/users/features/sandbox) documentation for more information, including how to customize your sandbox configuration.
+  - **Solution:** Refer to the [Configuration: Sandboxing](../features/sandbox) documentation for more information, including how to customize your sandbox configuration.
 
 - **Qwen Code is not running in interactive mode in "CI" environments**
   - **Issue:** Qwen Code does not enter interactive mode (no prompt appears) if an environment variable starting with `CI_` (e.g. `CI_TOKEN`) is set. This is because the `is-in-ci` package, used by the underlying UI framework, detects these variables and assumes a non-interactive CI environment.

esbuild.config.js

@@ -33,7 +33,6 @@ const external = [
   '@lydell/node-pty-linux-x64',
   '@lydell/node-pty-win32-arm64',
   '@lydell/node-pty-win32-x64',
-  'tiktoken',
 ];
 
 esbuild

eslint.config.js

@@ -24,6 +24,8 @@ export default tseslint.config(
       '.integration-tests/**',
       'packages/**/.integration-test/**',
       'dist/**',
+      'docs-site/.next/**',
+      'docs-site/out/**',
     ],
   },
   eslint.configs.recommended,

integration-tests/acp-integration.test.ts

@@ -80,10 +80,11 @@ type PermissionHandler = (
 
 /**
  * Sets up an ACP test environment with all necessary utilities.
+ * @param useNewFlag - If true, uses --acp; if false, uses --experimental-acp (for backward compatibility testing)
  */
 function setupAcpTest(
   rig: TestRig,
-  options?: { permissionHandler?: PermissionHandler },
+  options?: { permissionHandler?: PermissionHandler; useNewFlag?: boolean },
 ) {
   const pending = new Map<number, PendingRequest>();
   let nextRequestId = 1;
@@ -95,9 +96,13 @@ function setupAcpTest(
   const permissionHandler =
     options?.permissionHandler ?? (() => ({ optionId: 'proceed_once' }));
 
+  // Use --acp by default, but allow testing with --experimental-acp for backward compatibility
+  const acpFlag =
+    options?.useNewFlag !== false ? '--acp' : '--experimental-acp';
+
   const agent = spawn(
     'node',
-    [rig.bundlePath, '--experimental-acp', '--no-chat-recording'],
+    [rig.bundlePath, acpFlag, '--no-chat-recording'],
     {
       cwd: rig.testDir!,
       stdio: ['pipe', 'pipe', 'pipe'],
@@ -306,9 +311,9 @@ function setupAcpTest(
     }
   });
 
-  it('returns modes on initialize and allows setting approval mode', async () => {
+  it('returns modes on initialize and allows setting mode and model', async () => {
     const rig = new TestRig();
-    rig.setup('acp approval mode');
+    rig.setup('acp mode and model');
 
     const { sendRequest, cleanup, stderr } = setupAcpTest(rig);
 
@@ -361,8 +366,14 @@ function setupAcpTest(
       const newSession = (await sendRequest('session/new', {
         cwd: rig.testDir!,
         mcpServers: [],
-      })) as { sessionId: string };
+      })) as {
+        sessionId: string;
+        models: {
+          availableModels: Array<{ modelId: string }>;
+        };
+      };
       expect(newSession.sessionId).toBeTruthy();
+      expect(newSession.models.availableModels.length).toBeGreaterThan(0);
 
       // Test 4: Set approval mode to 'yolo'
       const setModeResult = (await sendRequest('session/set_mode', {
@@ -387,6 +398,15 @@ function setupAcpTest(
       })) as { modeId: string };
       expect(setModeResult3).toBeDefined();
       expect(setModeResult3.modeId).toBe('default');
+
+      // Test 7: Set model using first available model
+      const firstModel = newSession.models.availableModels[0];
+      const setModelResult = (await sendRequest('session/set_model', {
+        sessionId: newSession.sessionId,
+        modelId: firstModel.modelId,
+      })) as { modelId: string };
+      expect(setModelResult).toBeDefined();
+      expect(setModelResult.modelId).toBeTruthy();
     } catch (e) {
       if (stderr.length) {
         console.error('Agent stderr:', stderr.join(''));
@@ -621,3 +641,99 @@ function setupAcpTest(
     }
   });
 });
+
+(IS_SANDBOX ? describe.skip : describe)(
+  'acp flag backward compatibility',
+  () => {
+    it('should work with deprecated --experimental-acp flag and show warning', async () => {
+      const rig = new TestRig();
+      rig.setup('acp backward compatibility');
+
+      const { sendRequest, cleanup, stderr } = setupAcpTest(rig, {
+        useNewFlag: false,
+      });
+
+      try {
+        const initResult = await sendRequest('initialize', {
+          protocolVersion: 1,
+          clientCapabilities: {
+            fs: { readTextFile: true, writeTextFile: true },
+          },
+        });
+        expect(initResult).toBeDefined();
+
+        // Verify deprecation warning is shown
+        const stderrOutput = stderr.join('');
+        expect(stderrOutput).toContain('--experimental-acp is deprecated');
+        expect(stderrOutput).toContain('Please use --acp instead');
+
+        await sendRequest('authenticate', { methodId: 'openai' });
+
+        const newSession = (await sendRequest('session/new', {
+          cwd: rig.testDir!,
+          mcpServers: [],
+        })) as { sessionId: string };
+        expect(newSession.sessionId).toBeTruthy();
+
+        // Verify functionality still works
+        const promptResult = await sendRequest('session/prompt', {
+          sessionId: newSession.sessionId,
+          prompt: [{ type: 'text', text: 'Say hello.' }],
+        });
+        expect(promptResult).toBeDefined();
+      } catch (e) {
+        if (stderr.length) {
+          console.error('Agent stderr:', stderr.join(''));
+        }
+        throw e;
+      } finally {
+        await cleanup();
+      }
+    });
+
+    it('should work with new --acp flag without warnings', async () => {
+      const rig = new TestRig();
+      rig.setup('acp new flag');
+
+      const { sendRequest, cleanup, stderr } = setupAcpTest(rig, {
+        useNewFlag: true,
+      });
+
+      try {
+        const initResult = await sendRequest('initialize', {
+          protocolVersion: 1,
+          clientCapabilities: {
+            fs: { readTextFile: true, writeTextFile: true },
+          },
+        });
+        expect(initResult).toBeDefined();
+
+        // Verify no deprecation warning is shown
+        const stderrOutput = stderr.join('');
+        expect(stderrOutput).not.toContain('--experimental-acp is deprecated');
+
+        await sendRequest('authenticate', { methodId: 'openai' });
+
+        const newSession = (await sendRequest('session/new', {
+          cwd: rig.testDir!,
+          mcpServers: [],
+        })) as { sessionId: string };
+        expect(newSession.sessionId).toBeTruthy();
+
+        // Verify functionality works
+        const promptResult = await sendRequest('session/prompt', {
+          sessionId: newSession.sessionId,
+          prompt: [{ type: 'text', text: 'Say hello.' }],
+        });
+        expect(promptResult).toBeDefined();
+      } catch (e) {
+        if (stderr.length) {
+          console.error('Agent stderr:', stderr.join(''));
+        }
+        throw e;
+      } finally {
+        await cleanup();
+      }
+    });
+  },
+);

integration-tests/file-system.test.ts

@@ -5,8 +5,6 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { existsSync } from 'node:fs';
-import * as path from 'node:path';
 import { TestRig, printDebugInfo, validateModelOutput } from './test-helper.js';
 
 describe('file-system', () => {
@@ -202,8 +200,8 @@ describe('file-system', () => {
     const readAttempt = toolLogs.find(
       (log) => log.toolRequest.name === 'read_file',
     );
-    const writeAttempt = toolLogs.find(
-      (log) => log.toolRequest.name === 'write_file',
+    const editAttempt = toolLogs.find(
+      (log) => log.toolRequest.name === 'edit_file',
     );
     const successfulReplace = toolLogs.find(
       (log) => log.toolRequest.name === 'replace' && log.toolRequest.success,
@@ -226,15 +224,15 @@ describe('file-system', () => {
 
     // CRITICAL: Verify that no matter what the model did, it never successfully
     // wrote or replaced anything.
-    if (writeAttempt) {
+    if (editAttempt) {
       console.error(
-        'A write_file attempt was made when no file should be written.',
+        'A edit_file attempt was made when no file should be written.',
       );
       printDebugInfo(rig, result);
     }
     expect(
-      writeAttempt,
-      'write_file should not have been called',
+      editAttempt,
+      'edit_file should not have been called',
     ).toBeUndefined();
 
     if (successfulReplace) {
@@ -245,12 +243,5 @@ describe('file-system', () => {
       successfulReplace,
       'A successful replace should not have occurred',
     ).toBeUndefined();
-
-    // Final verification: ensure the file was not created.
-    const filePath = path.join(rig.testDir!, fileName);
-    const fileExists = existsSync(filePath);
-    expect(fileExists, 'The non-existent file should not be created').toBe(
-      false,
-    );
   });
 });

integration-tests/sdk-typescript/permission-control.test.ts

@@ -831,7 +831,7 @@ describe('Permission Control (E2E)', () => {
         TEST_TIMEOUT,
       );
 
-      it(
+      it.skip(
         'should execute dangerous commands without confirmation',
         async () => {
           const q = query({
@@ -952,7 +952,8 @@ describe('Permission Control (E2E)', () => {
         TEST_TIMEOUT,
       );
 
-      it(
+      // FIXME: This test is flaky and sometimes fails with no tool calls.
+      it.skip(
         'should allow read-only tools without restrictions',
         async () => {
           // Create test files for the model to read

integration-tests/sdk-typescript/system-control.test.ts

@@ -314,4 +314,88 @@ describe('System Control (E2E)', () => {
       );
     });
   });
+
+  describe('supportedCommands API', () => {
+    it('should return list of supported slash commands', async () => {
+      const sessionId = crypto.randomUUID();
+      const generator = (async function* () {
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: { role: 'user', content: 'Hello' },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+      })();
+
+      const q = query({
+        prompt: generator,
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          model: 'qwen3-max',
+          debug: false,
+        },
+      });
+
+      try {
+        const result = await q.supportedCommands();
+        // Start consuming messages to trigger initialization
+        const messageConsumer = (async () => {
+          try {
+            for await (const _message of q) {
+              // Just consume messages
+            }
+          } catch (error) {
+            // Ignore errors from query being closed
+            if (error instanceof Error && error.message !== 'Query is closed') {
+              throw error;
+            }
+          }
+        })();
+
+        // Verify result structure
+        expect(result).toBeDefined();
+        expect(result).toHaveProperty('commands');
+        expect(Array.isArray(result?.['commands'])).toBe(true);
+
+        const commands = result?.['commands'] as string[];
+
+        // Verify default allowed built-in commands are present
+        expect(commands).toContain('init');
+        expect(commands).toContain('summary');
+        expect(commands).toContain('compress');
+
+        // Verify commands are sorted
+        const sortedCommands = [...commands].sort();
+        expect(commands).toEqual(sortedCommands);
+
+        // Verify all commands are strings
+        commands.forEach((cmd) => {
+          expect(typeof cmd).toBe('string');
+          expect(cmd.length).toBeGreaterThan(0);
+        });
+
+        await q.close();
+        await messageConsumer;
+      } catch (error) {
+        await q.close();
+        throw error;
+      }
+    });
+
+    it('should throw error when supportedCommands is called on closed query', async () => {
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          model: 'qwen3-max',
+        },
+      });
+
+      await q.close();
+
+      await expect(q.supportedCommands()).rejects.toThrow('Query is closed');
+    });
+  });
 });

integration-tests/utf-bom-encoding.test.ts

@@ -5,8 +5,8 @@
  */
 
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { writeFileSync, readFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { TestRig } from './test-helper.js';
 
 // Windows skip (Option A: avoid infra scope)
@@ -121,21 +121,4 @@ d('BOM end-to-end integration', () => {
       'BOM_OK UTF-32BE',
     );
   });
-
-  it('Can describe a PNG file', async () => {
-    const imagePath = resolve(
-      process.cwd(),
-      'docs/assets/gemini-screenshot.png',
-    );
-    const imageContent = readFileSync(imagePath);
-    const filename = 'gemini-screenshot.png';
-    writeFileSync(join(dir, filename), imageContent);
-    const prompt = `What is shown in the image ${filename}?`;
-    const output = await rig.run(prompt);
-    await rig.waitForToolCall('read_file');
-    const lower = output.toLowerCase();
-    // The response is non-deterministic, so we just check for some
-    // keywords that are very likely to be in the response.
-    expect(lower.includes('gemini')).toBeTruthy();
-  });
 });

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qwen-code/qwen-code",
-  "version": "0.5.1",
+  "version": "0.8.0-preview.1",
   "engines": {
     "node": ">=20.0.0"
   },
@@ -13,14 +13,11 @@
     "url": "git+https://github.com/QwenLM/qwen-code.git"
   },
   "config": {
-    "sandboxImageUri": "ghcr.io/qwenlm/qwen-code:0.5.1"
+    "sandboxImageUri": "ghcr.io/qwenlm/qwen-code:0.8.0-preview.1"
   },
   "scripts": {
     "start": "cross-env node scripts/start.js",
     "debug": "cross-env DEBUG=1 node --inspect-brk scripts/start.js",
-    "auth:npm": "npx google-artifactregistry-auth",
-    "auth:docker": "gcloud auth configure-docker us-west1-docker.pkg.dev",
-    "auth": "npm run auth:npm && npm run auth:docker",
     "generate": "node scripts/generate-git-commit-info.js",
     "build": "node scripts/build.js",
     "build-and-start": "npm run build && npm run start",
@@ -95,7 +92,6 @@
     "eslint-plugin-react-hooks": "^5.2.0",
     "glob": "^10.5.0",
     "globals": "^16.0.0",
-    "google-artifactregistry-auth": "^3.4.0",
     "husky": "^9.1.7",
     "json": "^11.0.0",
     "lint-staged": "^16.1.6",

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qwen-code/qwen-code",
-  "version": "0.5.1",
+  "version": "0.8.0-preview.1",
   "description": "Qwen Code",
   "repository": {
     "type": "git",
@@ -33,13 +33,13 @@
     "dist"
   ],
   "config": {
-    "sandboxImageUri": "ghcr.io/qwenlm/qwen-code:0.5.1"
+    "sandboxImageUri": "ghcr.io/qwenlm/qwen-code:0.8.0-preview.1"
   },
   "dependencies": {
-    "@google/genai": "1.16.0",
+    "@google/genai": "1.30.0",
     "@iarna/toml": "^2.2.5",
+    "@modelcontextprotocol/sdk": "^1.25.1",
     "@qwen-code/qwen-code-core": "file:../core",
-    "@modelcontextprotocol/sdk": "^1.15.1",
     "@types/update-notifier": "^6.0.8",
     "ansi-regex": "^6.2.2",
     "command-exists": "^1.2.9",
@@ -63,9 +63,7 @@
     "string-width": "^7.1.0",
     "strip-ansi": "^7.1.0",
     "strip-json-comments": "^3.1.1",
-    "tar": "^7.5.2",
-    "undici": "^7.10.0",
-    "extract-zip": "^2.0.1",
+    "undici": "^6.22.0",
     "update-notifier": "^7.3.1",
     "wrap-ansi": "9.0.2",
     "yargs": "^17.7.2",
@@ -74,6 +72,7 @@
   "devDependencies": {
     "@babel/runtime": "^7.27.6",
     "@google/gemini-cli-test-utils": "file:../test-utils",
+    "@qwen-code/qwen-code-test-utils": "file:../test-utils",
     "@testing-library/react": "^16.3.0",
     "@types/archiver": "^6.0.3",
     "@types/command-exists": "^1.2.3",
@@ -84,7 +83,6 @@
     "@types/react-dom": "^19.1.6",
     "@types/semver": "^7.7.0",
     "@types/shell-quote": "^1.7.5",
-    "@types/tar": "^6.1.13",
     "@types/yargs": "^17.0.32",
     "archiver": "^7.0.1",
     "ink-testing-library": "^4.0.0",
@@ -92,8 +90,7 @@
     "pretty-format": "^30.0.2",
     "react-dom": "^19.1.0",
     "typescript": "^5.3.3",
-    "vitest": "^3.1.1",
-    "@qwen-code/qwen-code-test-utils": "file:../test-utils"
+    "vitest": "^3.1.1"
   },
   "engines": {
     "node": ">=20"

packages/cli/src/acp-integration/acp.ts

@@ -8,6 +8,7 @@
 
 import { z } from 'zod';
 import * as schema from './schema.js';
+import { ACP_ERROR_CODES } from './errorCodes.js';
 export * from './schema.js';
 
 import type { WritableStream, ReadableStream } from 'node:stream/web';
@@ -70,6 +71,13 @@ export class AgentSideConnection implements Client {
           const validatedParams = schema.setModeRequestSchema.parse(params);
           return agent.setMode(validatedParams);
         }
+        case schema.AGENT_METHODS.session_set_model: {
+          if (!agent.setModel) {
+            throw RequestError.methodNotFound();
+          }
+          const validatedParams = schema.setModelRequestSchema.parse(params);
+          return agent.setModel(validatedParams);
+        }
         default:
           throw RequestError.methodNotFound(method);
       }
@@ -98,6 +106,14 @@ export class AgentSideConnection implements Client {
     );
   }
 
+  /**
+   * Sends a custom notification to the client.
+   * Used for extension-specific notifications that are not part of the core ACP protocol.
+   */
+  async sendCustomNotification<T>(method: string, params: T): Promise<void> {
+    return await this.#connection.sendNotification(method, params);
+  }
+
   /**
    * Request permission before running a tool
    *
@@ -334,27 +350,51 @@ export class RequestError extends Error {
   }
 
   static parseError(details?: string): RequestError {
-    return new RequestError(-32700, 'Parse error', details);
+    return new RequestError(
+      ACP_ERROR_CODES.PARSE_ERROR,
+      'Parse error',
+      details,
+    );
   }
 
   static invalidRequest(details?: string): RequestError {
-    return new RequestError(-32600, 'Invalid request', details);
+    return new RequestError(
+      ACP_ERROR_CODES.INVALID_REQUEST,
+      'Invalid request',
+      details,
+    );
   }
 
   static methodNotFound(details?: string): RequestError {
-    return new RequestError(-32601, 'Method not found', details);
+    return new RequestError(
+      ACP_ERROR_CODES.METHOD_NOT_FOUND,
+      'Method not found',
+      details,
+    );
   }
 
   static invalidParams(details?: string): RequestError {
-    return new RequestError(-32602, 'Invalid params', details);
+    return new RequestError(
+      ACP_ERROR_CODES.INVALID_PARAMS,
+      'Invalid params',
+      details,
+    );
   }
 
   static internalError(details?: string): RequestError {
-    return new RequestError(-32603, 'Internal error', details);
+    return new RequestError(
+      ACP_ERROR_CODES.INTERNAL_ERROR,
+      'Internal error',
+      details,
+    );
   }
 
   static authRequired(details?: string): RequestError {
-    return new RequestError(-32000, 'Authentication required', details);
+    return new RequestError(
+      ACP_ERROR_CODES.AUTH_REQUIRED,
+      'Authentication required',
+      details,
+    );
   }
 
   toResult<T>(): Result<T> {
@@ -374,6 +414,7 @@ export interface Client {
   ): Promise<schema.RequestPermissionResponse>;
   sessionUpdate(params: schema.SessionNotification): Promise<void>;
   authenticateUpdate(params: schema.AuthenticateUpdate): Promise<void>;
+  sendCustomNotification<T>(method: string, params: T): Promise<void>;
   writeTextFile(
     params: schema.WriteTextFileRequest,
   ): Promise<schema.WriteTextFileResponse>;
@@ -399,4 +440,5 @@ export interface Agent {
   prompt(params: schema.PromptRequest): Promise<schema.PromptResponse>;
   cancel(params: schema.CancelNotification): Promise<void>;
   setMode?(params: schema.SetModeRequest): Promise<schema.SetModeResponse>;
+  setModel?(params: schema.SetModelRequest): Promise<schema.SetModelResponse>;
 }

packages/cli/src/acp-integration/acpAgent.ts

@@ -15,10 +15,10 @@ import {
   qwenOAuth2Events,
   MCPServerConfig,
   SessionService,
-  buildApiHistoryFromConversation,
   type Config,
   type ConversationRecord,
   type DeviceAuthorizationData,
+  tokenLimit,
 } from '@qwen-code/qwen-code-core';
 import type { ApprovalModeValue } from './schema.js';
 import * as acp from './acp.js';
@@ -27,10 +27,8 @@ import { Readable, Writable } from 'node:stream';
 import type { LoadedSettings } from '../config/settings.js';
 import { SettingScope } from '../config/settings.js';
 import { z } from 'zod';
-import { ExtensionStorage, type Extension } from '../config/extension.js';
 import type { CliArgs } from '../config/config.js';
 import { loadCliConfig } from '../config/config.js';
-import { ExtensionEnablementManager } from '../config/extensions/extensionEnablement.js';
 
 // Import the modular Session class
 import { Session } from './session/Session.js';
@@ -38,7 +36,6 @@ import { Session } from './session/Session.js';
 export async function runAcpAgent(
   config: Config,
   settings: LoadedSettings,
-  extensions: Extension[],
   argv: CliArgs,
 ) {
   const stdout = Writable.toWeb(process.stdout) as WritableStream;
@@ -51,8 +48,7 @@ export async function runAcpAgent(
   console.debug = console.error;
 
   new acp.AgentSideConnection(
-    (client: acp.Client) =>
-      new GeminiAgent(config, settings, extensions, argv, client),
+    (client: acp.Client) => new GeminiAgent(config, settings, argv, client),
     stdout,
     stdin,
   );
@@ -65,7 +61,6 @@ class GeminiAgent {
   constructor(
     private config: Config,
     private settings: LoadedSettings,
-    private extensions: Extension[],
     private argv: CliArgs,
     private client: acp.Client,
   ) {}
@@ -165,9 +160,11 @@ class GeminiAgent {
     this.setupFileSystem(config);
 
     const session = await this.createAndStoreSession(config);
+    const availableModels = this.buildAvailableModels(config);
 
     return {
       sessionId: session.getId(),
+      models: availableModels,
     };
   }
 
@@ -194,16 +191,7 @@ class GeminiAgent {
       continue: false,
     };
 
-    const config = await loadCliConfig(
-      settings,
-      this.extensions,
-      new ExtensionEnablementManager(
-        ExtensionStorage.getUserExtensionsDir(),
-        this.argv.extensions,
-      ),
-      argvForSession,
-      cwd,
-    );
+    const config = await loadCliConfig(settings, argvForSession, cwd);
 
     await config.initialize();
     return config;
@@ -284,15 +272,29 @@ class GeminiAgent {
   async setMode(params: acp.SetModeRequest): Promise<acp.SetModeResponse> {
     const session = this.sessions.get(params.sessionId);
     if (!session) {
-      throw new Error(`Session not found: ${params.sessionId}`);
+      throw acp.RequestError.invalidParams(
+        `Session not found for id: ${params.sessionId}`,
+      );
     }
     return session.setMode(params);
   }
 
+  async setModel(params: acp.SetModelRequest): Promise<acp.SetModelResponse> {
+    const session = this.sessions.get(params.sessionId);
+    if (!session) {
+      throw acp.RequestError.invalidParams(
+        `Session not found for id: ${params.sessionId}`,
+      );
+    }
+    return session.setModel(params);
+  }
+
   private async ensureAuthenticated(config: Config): Promise<void> {
     const selectedType = this.settings.merged.security?.auth?.selectedType;
     if (!selectedType) {
-      throw acp.RequestError.authRequired('No Selected Type');
+      throw acp.RequestError.authRequired(
+        'Use Qwen Code CLI to authenticate first.',
+      );
     }
 
     try {
@@ -327,12 +329,20 @@ class GeminiAgent {
     const sessionId = config.getSessionId();
     const geminiClient = config.getGeminiClient();
 
-    const history = conversation
-      ? buildApiHistoryFromConversation(conversation)
-      : undefined;
-    const chat = history
-      ? await geminiClient.startChat(history)
-      : await geminiClient.startChat();
+    // Use GeminiClient to manage chat lifecycle properly
+    // This ensures geminiClient.chat is in sync with the session's chat
+    //
+    // Note: When loading a session, config.initialize() has already been called
+    // in newSessionConfig(), which in turn calls geminiClient.initialize().
+    // The GeminiClient.initialize() method checks config.getResumedSessionData()
+    // and automatically loads the conversation history into the chat instance.
+    // So we only need to initialize if it hasn't been done yet.
+    if (!geminiClient.isInitialized()) {
+      await geminiClient.initialize();
+    }
+
+    // Now get the chat instance that's managed by GeminiClient
+    const chat = geminiClient.getChat();
 
     const session = new Session(
       sessionId,
@@ -353,4 +363,43 @@ class GeminiAgent {
 
     return session;
   }
+
+  private buildAvailableModels(
+    config: Config,
+  ): acp.NewSessionResponse['models'] {
+    const currentModelId = (
+      config.getModel() ||
+      this.config.getModel() ||
+      ''
+    ).trim();
+    const availableModels = config.getAvailableModels();
+
+    const mappedAvailableModels = availableModels.map((model) => ({
+      modelId: model.id,
+      name: model.label,
+      description: model.description ?? null,
+      _meta: {
+        contextLimit: tokenLimit(model.id),
+      },
+    }));
+
+    if (
+      currentModelId &&
+      !mappedAvailableModels.some((model) => model.modelId === currentModelId)
+    ) {
+      mappedAvailableModels.unshift({
+        modelId: currentModelId,
+        name: currentModelId,
+        description: null,
+        _meta: {
+          contextLimit: tokenLimit(currentModelId),
+        },
+      });
+    }
+
+    return {
+      currentModelId,
+      availableModels: mappedAvailableModels,
+    };
+  }
 }

packages/cli/src/acp-integration/errorCodes.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export const ACP_ERROR_CODES = {
+  // Parse error: invalid JSON received by server.
+  PARSE_ERROR: -32700,
+  // Invalid request: JSON is not a valid Request object.
+  INVALID_REQUEST: -32600,
+  // Method not found: method does not exist or is unavailable.
+  METHOD_NOT_FOUND: -32601,
+  // Invalid params: invalid method parameter(s).
+  INVALID_PARAMS: -32602,
+  // Internal error: implementation-defined server error.
+  INTERNAL_ERROR: -32603,
+  // Authentication required: must authenticate before operation.
+  AUTH_REQUIRED: -32000,
+  // Resource not found: e.g. missing file.
+  RESOURCE_NOT_FOUND: -32002,
+} as const;
+
+export type AcpErrorCode =
+  (typeof ACP_ERROR_CODES)[keyof typeof ACP_ERROR_CODES];

packages/cli/src/acp-integration/schema.ts

@@ -15,6 +15,7 @@ export const AGENT_METHODS = {
   session_prompt: 'session/prompt',
   session_list: 'session/list',
   session_set_mode: 'session/set_mode',
+  session_set_model: 'session/set_model',
 };
 
 export const CLIENT_METHODS = {
@@ -93,6 +94,7 @@ export type ModeInfo = z.infer<typeof modeInfoSchema>;
 export type ModesData = z.infer<typeof modesDataSchema>;
 
 export type AgentInfo = z.infer<typeof agentInfoSchema>;
+export type ModelInfo = z.infer<typeof modelInfoSchema>;
 
 export type PromptCapabilities = z.infer<typeof promptCapabilitiesSchema>;
 
@@ -254,8 +256,38 @@ export const authenticateUpdateSchema = z.object({
 
 export type AuthenticateUpdate = z.infer<typeof authenticateUpdateSchema>;
 
+export const acpMetaSchema = z.record(z.unknown()).nullable().optional();
+
+export const modelIdSchema = z.string();
+
+export const modelInfoSchema = z.object({
+  _meta: acpMetaSchema,
+  description: z.string().nullable().optional(),
+  modelId: modelIdSchema,
+  name: z.string(),
+});
+
+export const setModelRequestSchema = z.object({
+  sessionId: z.string(),
+  modelId: z.string(),
+});
+
+export const setModelResponseSchema = z.object({
+  modelId: z.string(),
+});
+
+export type SetModelRequest = z.infer<typeof setModelRequestSchema>;
+export type SetModelResponse = z.infer<typeof setModelResponseSchema>;
+
+export const sessionModelStateSchema = z.object({
+  _meta: acpMetaSchema,
+  availableModels: z.array(modelInfoSchema),
+  currentModelId: modelIdSchema,
+});
+
 export const newSessionResponseSchema = z.object({
   sessionId: z.string(),
+  models: sessionModelStateSchema,
 });
 
 export const loadSessionResponseSchema = z.null();
@@ -514,6 +546,13 @@ export const currentModeUpdateSchema = z.object({
 
 export type CurrentModeUpdate = z.infer<typeof currentModeUpdateSchema>;
 
+export const currentModelUpdateSchema = z.object({
+  sessionUpdate: z.literal('current_model_update'),
+  model: modelInfoSchema,
+});
+
+export type CurrentModelUpdate = z.infer<typeof currentModelUpdateSchema>;
+
 export const sessionUpdateSchema = z.union([
   z.object({
     content: contentBlockSchema,
@@ -555,6 +594,7 @@ export const sessionUpdateSchema = z.union([
     sessionUpdate: z.literal('plan'),
   }),
   currentModeUpdateSchema,
+  currentModelUpdateSchema,
   availableCommandsUpdateSchema,
 ]);
 
@@ -565,6 +605,7 @@ export const agentResponseSchema = z.union([
   promptResponseSchema,
   listSessionsResponseSchema,
   setModeResponseSchema,
+  setModelResponseSchema,
 ]);
 
 export const requestPermissionRequestSchema = z.object({
@@ -597,6 +638,7 @@ export const agentRequestSchema = z.union([
   promptRequestSchema,
   listSessionsRequestSchema,
   setModeRequestSchema,
+  setModelRequestSchema,
 ]);
 
 export const agentNotificationSchema = sessionNotificationSchema;

packages/cli/src/acp-integration/service/filesystem.test.ts

@@ -7,6 +7,7 @@
 import { describe, expect, it, vi } from 'vitest';
 import type { FileSystemService } from '@qwen-code/qwen-code-core';
 import { AcpFileSystemService } from './filesystem.js';
+import { ACP_ERROR_CODES } from '../errorCodes.js';
 
 const createFallback = (): FileSystemService => ({
   readTextFile: vi.fn(),
@@ -16,11 +17,13 @@ const createFallback = (): FileSystemService => ({
 
 describe('AcpFileSystemService', () => {
   describe('readTextFile ENOENT handling', () => {
-    it('parses path from ACP ENOENT message (quoted)', async () => {
+    it('converts RESOURCE_NOT_FOUND error to ENOENT', async () => {
+      const resourceNotFoundError = {
+        code: ACP_ERROR_CODES.RESOURCE_NOT_FOUND,
+        message: 'File not found',
+      };
       const client = {
-        readTextFile: vi
-          .fn()
-          .mockResolvedValue({ content: 'ERROR: ENOENT: "/remote/file.txt"' }),
+        readTextFile: vi.fn().mockRejectedValue(resourceNotFoundError),
       } as unknown as import('../acp.js').Client;
 
       const svc = new AcpFileSystemService(
@@ -30,15 +33,20 @@ describe('AcpFileSystemService', () => {
         createFallback(),
       );
 
-      await expect(svc.readTextFile('/local/file.txt')).rejects.toMatchObject({
+      await expect(svc.readTextFile('/some/file.txt')).rejects.toMatchObject({
         code: 'ENOENT',
-        path: '/remote/file.txt',
+        errno: -2,
+        path: '/some/file.txt',
       });
     });
 
-    it('falls back to requested path when none provided', async () => {
+    it('re-throws other errors unchanged', async () => {
+      const otherError = {
+        code: ACP_ERROR_CODES.INTERNAL_ERROR,
+        message: 'Internal error',
+      };
       const client = {
-        readTextFile: vi.fn().mockResolvedValue({ content: 'ERROR: ENOENT:' }),
+        readTextFile: vi.fn().mockRejectedValue(otherError),
       } as unknown as import('../acp.js').Client;
 
       const svc = new AcpFileSystemService(
@@ -48,12 +56,34 @@ describe('AcpFileSystemService', () => {
         createFallback(),
       );
 
-      await expect(
-        svc.readTextFile('/fallback/path.txt'),
-      ).rejects.toMatchObject({
-        code: 'ENOENT',
-        path: '/fallback/path.txt',
+      await expect(svc.readTextFile('/some/file.txt')).rejects.toMatchObject({
+        code: ACP_ERROR_CODES.INTERNAL_ERROR,
+        message: 'Internal error',
       });
     });
+
+    it('uses fallback when readTextFile capability is disabled', async () => {
+      const client = {
+        readTextFile: vi.fn(),
+      } as unknown as import('../acp.js').Client;
+
+      const fallback = createFallback();
+      (fallback.readTextFile as ReturnType<typeof vi.fn>).mockResolvedValue(
+        'fallback content',
+      );
+
+      const svc = new AcpFileSystemService(
+        client,
+        'session-3',
+        { readTextFile: false, writeTextFile: true },
+        fallback,
+      );
+
+      const result = await svc.readTextFile('/some/file.txt');
+
+      expect(result).toBe('fallback content');
+      expect(fallback.readTextFile).toHaveBeenCalledWith('/some/file.txt');
+      expect(client.readTextFile).not.toHaveBeenCalled();
+    });
   });
 });

packages/cli/src/acp-integration/service/filesystem.ts

@@ -6,6 +6,7 @@
 
 import type { FileSystemService } from '@qwen-code/qwen-code-core';
 import type * as acp from '../acp.js';
+import { ACP_ERROR_CODES } from '../errorCodes.js';
 
 /**
  * ACP client-based implementation of FileSystemService
@@ -23,25 +24,31 @@ export class AcpFileSystemService implements FileSystemService {
       return this.fallback.readTextFile(filePath);
     }
 
-    const response = await this.client.readTextFile({
-      path: filePath,
-      sessionId: this.sessionId,
-      line: null,
-      limit: null,
-    });
+    let response: { content: string };
+    try {
+      response = await this.client.readTextFile({
+        path: filePath,
+        sessionId: this.sessionId,
+        line: null,
+        limit: null,
+      });
+    } catch (error) {
+      const errorCode =
+        typeof error === 'object' && error !== null && 'code' in error
+          ? (error as { code?: unknown }).code
+          : undefined;
 
-    if (response.content.startsWith('ERROR: ENOENT:')) {
-      // Treat ACP error strings as structured ENOENT errors without
-      // assuming a specific platform format.
-      const match = /^ERROR:\s*ENOENT:\s*(?<path>.*)$/i.exec(response.content);
-      const err = new Error(response.content) as NodeJS.ErrnoException;
-      err.code = 'ENOENT';
-      err.errno = -2;
-      const rawPath = match?.groups?.['path']?.trim();
-      err['path'] = rawPath
-        ? rawPath.replace(/^['"]|['"]$/g, '') || filePath
-        : filePath;
-      throw err;
+      if (errorCode === ACP_ERROR_CODES.RESOURCE_NOT_FOUND) {
+        const err = new Error(
+          `File not found: ${filePath}`,
+        ) as NodeJS.ErrnoException;
+        err.code = 'ENOENT';
+        err.errno = -2;
+        err.path = filePath;
+        throw err;
+      }
+
+      throw error;
     }
 
     return response.content;

packages/cli/src/acp-integration/session/Session.test.ts

@@ -0,0 +1,174 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Session } from './Session.js';
+import type { Config, GeminiChat } from '@qwen-code/qwen-code-core';
+import { ApprovalMode } from '@qwen-code/qwen-code-core';
+import type * as acp from '../acp.js';
+import type { LoadedSettings } from '../../config/settings.js';
+import * as nonInteractiveCliCommands from '../../nonInteractiveCliCommands.js';
+
+vi.mock('../../nonInteractiveCliCommands.js', () => ({
+  getAvailableCommands: vi.fn(),
+  handleSlashCommand: vi.fn(),
+}));
+
+describe('Session', () => {
+  let mockChat: GeminiChat;
+  let mockConfig: Config;
+  let mockClient: acp.Client;
+  let mockSettings: LoadedSettings;
+  let session: Session;
+  let currentModel: string;
+  let setModelSpy: ReturnType<typeof vi.fn>;
+  let getAvailableCommandsSpy: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    currentModel = 'qwen3-code-plus';
+    setModelSpy = vi.fn().mockImplementation(async (modelId: string) => {
+      currentModel = modelId;
+    });
+
+    mockChat = {
+      sendMessageStream: vi.fn(),
+      addHistory: vi.fn(),
+    } as unknown as GeminiChat;
+
+    mockConfig = {
+      setApprovalMode: vi.fn(),
+      setModel: setModelSpy,
+      getModel: vi.fn().mockImplementation(() => currentModel),
+    } as unknown as Config;
+
+    mockClient = {
+      sessionUpdate: vi.fn().mockResolvedValue(undefined),
+      requestPermission: vi.fn().mockResolvedValue({
+        outcome: { outcome: 'selected', optionId: 'proceed_once' },
+      }),
+      sendCustomNotification: vi.fn().mockResolvedValue(undefined),
+    } as unknown as acp.Client;
+
+    mockSettings = {
+      merged: {},
+    } as LoadedSettings;
+
+    getAvailableCommandsSpy = vi.mocked(nonInteractiveCliCommands)
+      .getAvailableCommands as unknown as ReturnType<typeof vi.fn>;
+    getAvailableCommandsSpy.mockResolvedValue([]);
+
+    session = new Session(
+      'test-session-id',
+      mockChat,
+      mockConfig,
+      mockClient,
+      mockSettings,
+    );
+  });
+
+  describe('setMode', () => {
+    it.each([
+      ['plan', ApprovalMode.PLAN],
+      ['default', ApprovalMode.DEFAULT],
+      ['auto-edit', ApprovalMode.AUTO_EDIT],
+      ['yolo', ApprovalMode.YOLO],
+    ] as const)('maps %s mode', async (modeId, expected) => {
+      const result = await session.setMode({
+        sessionId: 'test-session-id',
+        modeId,
+      });
+
+      expect(mockConfig.setApprovalMode).toHaveBeenCalledWith(expected);
+      expect(result).toEqual({ modeId });
+    });
+  });
+
+  describe('setModel', () => {
+    it('sets model via config and returns current model', async () => {
+      const result = await session.setModel({
+        sessionId: 'test-session-id',
+        modelId: '  qwen3-coder-plus  ',
+      });
+
+      expect(mockConfig.setModel).toHaveBeenCalledWith('qwen3-coder-plus', {
+        reason: 'user_request_acp',
+        context: 'session/set_model',
+      });
+      expect(mockConfig.getModel).toHaveBeenCalled();
+      expect(result).toEqual({ modelId: 'qwen3-coder-plus' });
+    });
+
+    it('rejects empty/whitespace model IDs', async () => {
+      await expect(
+        session.setModel({
+          sessionId: 'test-session-id',
+          modelId: '   ',
+        }),
+      ).rejects.toThrow('Invalid params');
+
+      expect(mockConfig.setModel).not.toHaveBeenCalled();
+    });
+
+    it('propagates errors from config.setModel', async () => {
+      const configError = new Error('Invalid model');
+      setModelSpy.mockRejectedValueOnce(configError);
+
+      await expect(
+        session.setModel({
+          sessionId: 'test-session-id',
+          modelId: 'invalid-model',
+        }),
+      ).rejects.toThrow('Invalid model');
+    });
+  });
+
+  describe('sendAvailableCommandsUpdate', () => {
+    it('sends available_commands_update from getAvailableCommands()', async () => {
+      getAvailableCommandsSpy.mockResolvedValueOnce([
+        {
+          name: 'init',
+          description: 'Initialize project context',
+        },
+      ]);
+
+      await session.sendAvailableCommandsUpdate();
+
+      expect(getAvailableCommandsSpy).toHaveBeenCalledWith(
+        mockConfig,
+        expect.any(AbortSignal),
+      );
+      expect(mockClient.sessionUpdate).toHaveBeenCalledWith({
+        sessionId: 'test-session-id',
+        update: {
+          sessionUpdate: 'available_commands_update',
+          availableCommands: [
+            {
+              name: 'init',
+              description: 'Initialize project context',
+              input: null,
+            },
+          ],
+        },
+      });
+    });
+
+    it('swallows errors and does not throw', async () => {
+      const consoleErrorSpy = vi
+        .spyOn(console, 'error')
+        .mockImplementation(() => undefined);
+      getAvailableCommandsSpy.mockRejectedValueOnce(
+        new Error('Command discovery failed'),
+      );
+
+      await expect(
+        session.sendAvailableCommandsUpdate(),
+      ).resolves.toBeUndefined();
+      expect(mockClient.sessionUpdate).not.toHaveBeenCalled();
+      expect(consoleErrorSpy).toHaveBeenCalled();
+      consoleErrorSpy.mockRestore();
+    });
+  });
+});

packages/cli/src/acp-integration/session/Session.ts

@@ -41,15 +41,19 @@ import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { z } from 'zod';
 import { getErrorMessage } from '../../utils/errors.js';
+import { normalizePartList } from '../../utils/nonInteractiveHelpers.js';
 import {
   handleSlashCommand,
   getAvailableCommands,
+  type NonInteractiveSlashCommandResult,
 } from '../../nonInteractiveCliCommands.js';
 import type {
   AvailableCommand,
   AvailableCommandsUpdate,
   SetModeRequest,
   SetModeResponse,
+  SetModelRequest,
+  SetModelResponse,
   ApprovalModeValue,
   CurrentModeUpdate,
 } from '../schema.js';
@@ -63,12 +67,6 @@ import { PlanEmitter } from './emitters/PlanEmitter.js';
 import { MessageEmitter } from './emitters/MessageEmitter.js';
 import { SubAgentTracker } from './SubAgentTracker.js';
 
-/**
- * Built-in commands that are allowed in ACP integration mode.
- * Only safe, read-only commands that don't require interactive UI.
- */
-export const ALLOWED_BUILTIN_COMMANDS_FOR_ACP = ['init'];
-
 /**
  * Session represents an active conversation session with the AI model.
  * It uses modular components for consistent event emission:
@@ -167,24 +165,26 @@ export class Session implements SessionContext {
     const firstTextBlock = params.prompt.find((block) => block.type === 'text');
     const inputText = firstTextBlock?.text || '';
 
-    let parts: Part[];
+    let parts: Part[] | null;
 
     if (isSlashCommand(inputText)) {
-      // Handle slash command - allow specific built-in commands for ACP integration
+      // Handle slash command - uses default allowed commands (init, summary, compress)
       const slashCommandResult = await handleSlashCommand(
         inputText,
         pendingSend,
         this.config,
         this.settings,
-        ALLOWED_BUILTIN_COMMANDS_FOR_ACP,
       );
 
-      if (slashCommandResult) {
-        // Use the result from the slash command
-        parts = slashCommandResult as Part[];
-      } else {
-        // Slash command didn't return a prompt, continue with normal processing
-        parts = await this.#resolvePrompt(params.prompt, pendingSend.signal);
+      parts = await this.#processSlashCommandResult(
+        slashCommandResult,
+        params.prompt,
+      );
+
+      // If parts is null, the command was fully handled (e.g., /summary completed)
+      // Return early without sending to the model
+      if (parts === null) {
+        return { stopReason: 'end_turn' };
       }
     } else {
       // Normal processing for non-slash commands
@@ -295,11 +295,10 @@ export class Session implements SessionContext {
   async sendAvailableCommandsUpdate(): Promise<void> {
     const abortController = new AbortController();
     try {
+      // Use default allowed commands from getAvailableCommands
       const slashCommands = await getAvailableCommands(
         this.config,
-        this.settings,
         abortController.signal,
-        ALLOWED_BUILTIN_COMMANDS_FOR_ACP,
       );
 
       // Convert SlashCommand[] to AvailableCommand[] format for ACP protocol
@@ -351,6 +350,31 @@ export class Session implements SessionContext {
     return { modeId: params.modeId };
   }
 
+  /**
+   * Sets the model for the current session.
+   * Validates the model ID and switches the model via Config.
+   */
+  async setModel(params: SetModelRequest): Promise<SetModelResponse> {
+    const modelId = params.modelId.trim();
+
+    if (!modelId) {
+      throw acp.RequestError.invalidParams('modelId cannot be empty');
+    }
+
+    // Attempt to set the model using config
+    await this.config.setModel(modelId, {
+      reason: 'user_request_acp',
+      context: 'session/set_model',
+    });
+
+    // Get updated model info
+    const currentModel = this.config.getModel();
+
+    return {
+      modelId: currentModel,
+    };
+  }
+
   /**
    * Sends a current_mode_update notification to the client.
    * Called after the agent switches modes (e.g., from exit_plan_mode tool).
@@ -647,6 +671,103 @@ export class Session implements SessionContext {
     }
   }
 
+  /**
+   * Processes the result of a slash command execution.
+   *
+   * Supported result types in ACP mode:
+   * - submit_prompt: Submits content to the model
+   * - stream_messages: Streams multiple messages to the client (ACP-specific)
+   * - unsupported: Command cannot be executed in ACP mode
+   * - no_command: No command was found, use original prompt
+   *
+   * Note: 'message' type is not supported in ACP mode - commands should use
+   * 'stream_messages' instead for consistent async handling.
+   *
+   * @param result The result from handleSlashCommand
+   * @param originalPrompt The original prompt blocks
+   * @returns Parts to use for the prompt, or null if command was handled without needing model interaction
+   */
+  async #processSlashCommandResult(
+    result: NonInteractiveSlashCommandResult,
+    originalPrompt: acp.ContentBlock[],
+  ): Promise<Part[] | null> {
+    switch (result.type) {
+      case 'submit_prompt':
+        // Command wants to submit a prompt to the model
+        // Convert PartListUnion to Part[]
+        return normalizePartList(result.content);
+
+      case 'message': {
+        // 'message' type is not ideal for ACP mode, but we handle it for compatibility
+        // by converting it to a stream_messages-like notification
+        await this.client.sendCustomNotification('_qwencode/slash_command', {
+          sessionId: this.sessionId,
+          command: originalPrompt
+            .filter((block) => block.type === 'text')
+            .map((block) => (block.type === 'text' ? block.text : ''))
+            .join(' '),
+          messageType: result.messageType,
+          message: result.content || '',
+        });
+
+        if (result.messageType === 'error') {
+          // Throw error to stop execution
+          throw new Error(result.content || 'Slash command failed.');
+        }
+        // For info messages, return null to indicate command was handled
+        return null;
+      }
+
+      case 'stream_messages': {
+        // Command returns multiple messages via async generator (ACP-preferred)
+        const command = originalPrompt
+          .filter((block) => block.type === 'text')
+          .map((block) => (block.type === 'text' ? block.text : ''))
+          .join(' ');
+
+        // Stream all messages to the client
+        for await (const msg of result.messages) {
+          await this.client.sendCustomNotification('_qwencode/slash_command', {
+            sessionId: this.sessionId,
+            command,
+            messageType: msg.messageType,
+            message: msg.content,
+          });
+
+          // If we encounter an error message, throw after sending
+          if (msg.messageType === 'error') {
+            throw new Error(msg.content || 'Slash command failed.');
+          }
+        }
+
+        // All messages sent successfully, return null to indicate command was handled
+        return null;
+      }
+
+      case 'unsupported': {
+        // Command returned an unsupported result type
+        const unsupportedError = `Slash command not supported in ACP integration: ${result.reason}`;
+        throw new Error(unsupportedError);
+      }
+
+      case 'no_command':
+        // No command was found or executed, use original prompt
+        return originalPrompt.map((block) => {
+          if (block.type === 'text') {
+            return { text: block.text };
+          }
+          throw new Error(`Unsupported block type: ${block.type}`);
+        });
+
+      default: {
+        // Exhaustiveness check
+        const _exhaustive: never = result;
+        const unknownError = `Unknown slash command result type: ${(_exhaustive as NonInteractiveSlashCommandResult).type}`;
+        throw new Error(unknownError);
+      }
+    }
+  }
+
   async #resolvePrompt(
     message: acp.ContentBlock[],
     abortSignal: AbortSignal,

packages/cli/src/commands/extensions.test.tsx

@@ -0,0 +1,106 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import { extensionsCommand } from './extensions.js';
+import { updateCommand } from './extensions/update.js';
+import { disableCommand } from './extensions/disable.js';
+import { enableCommand } from './extensions/enable.js';
+import { linkCommand } from './extensions/link.js';
+import { newCommand } from './extensions/new.js';
+import yargs from 'yargs';
+
+describe('extensions command', () => {
+  it('should have correct command name', () => {
+    expect(extensionsCommand.command).toBe('extensions <command>');
+  });
+
+  it('should have a description', () => {
+    expect(extensionsCommand.describe).toBe('Manage Qwen Code extensions.');
+  });
+
+  it('should require a subcommand', () => {
+    const parser = yargs([])
+      .command(extensionsCommand)
+      .fail(false)
+      .locale('en');
+
+    expect(() => parser.parse('extensions')).toThrow();
+  });
+
+  it('should register install subcommand', () => {
+    const parser = yargs([])
+      .command(extensionsCommand)
+      .fail(false)
+      .locale('en');
+
+    // This should throw as 'install' requires a source argument
+    expect(() => parser.parse('extensions install')).toThrow(
+      'Not enough non-option arguments',
+    );
+  });
+
+  it('should register uninstall subcommand', () => {
+    const parser = yargs([])
+      .command(extensionsCommand)
+      .fail(false)
+      .locale('en');
+
+    expect(() => parser.parse('extensions uninstall')).toThrow(
+      'Not enough non-option arguments',
+    );
+  });
+
+  it('should register list subcommand', () => {
+    const parser = yargs([])
+      .command(extensionsCommand)
+      .fail(false)
+      .locale('en');
+
+    // list doesn't require arguments, so it should not throw
+    expect(() => parser.parse('extensions list')).not.toThrow();
+  });
+
+  it('should register update subcommand', () => {
+    const parser = yargs([]).command(updateCommand).fail(false).locale('en');
+
+    expect(() => parser.parse('update')).toThrow(
+      'Either an extension name or --all must be provided',
+    );
+  });
+
+  it('should register disable subcommand', () => {
+    const parser = yargs([]).command(disableCommand).fail(false).locale('en');
+
+    expect(() => parser.parse('disable')).toThrow(
+      'Not enough non-option arguments',
+    );
+  });
+
+  it('should register enable subcommand', () => {
+    const parser = yargs([]).command(enableCommand).fail(false).locale('en');
+
+    expect(() => parser.parse('enable')).toThrow(
+      'Not enough non-option arguments',
+    );
+  });
+
+  it('should register link subcommand', () => {
+    const parser = yargs([]).command(linkCommand).fail(false).locale('en');
+
+    expect(() => parser.parse('link')).toThrow(
+      'Not enough non-option arguments',
+    );
+  });
+
+  it('should register new subcommand', async () => {
+    const parser = yargs([]).command(newCommand).fail(false).locale('en');
+
+    await expect(parser.parseAsync('new')).rejects.toThrow(
+      'Not enough non-option arguments',
+    );
+  });
+});

packages/cli/src/commands/extensions.tsx

@@ -13,6 +13,7 @@ import { disableCommand } from './extensions/disable.js';
 import { enableCommand } from './extensions/enable.js';
 import { linkCommand } from './extensions/link.js';
 import { newCommand } from './extensions/new.js';
+import { settingsCommand } from './extensions/settings.js';
 
 export const extensionsCommand: CommandModule = {
   command: 'extensions <command>',
@@ -27,6 +28,7 @@ export const extensionsCommand: CommandModule = {
       .command(enableCommand)
       .command(linkCommand)
       .command(newCommand)
+      .command(settingsCommand)
       .demandCommand(1, 'You need at least one command before continuing.')
       .version(false),
   handler: () => {

packages/cli/src/commands/extensions/consent.test.ts

@@ -0,0 +1,243 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { extensionConsentString, requestConsentOrFail } from './consent.js';
+import type { ExtensionConfig } from '@qwen-code/qwen-code-core';
+
+vi.mock('../../i18n/index.js', () => ({
+  t: vi.fn((str: string, params?: Record<string, string>) => {
+    if (params) {
+      return Object.entries(params).reduce(
+        (acc, [key, value]) => acc.replace(`{{${key}}}`, value),
+        str,
+      );
+    }
+    return str;
+  }),
+}));
+
+describe('extensionConsentString', () => {
+  it('should include extension name', () => {
+    const config: ExtensionConfig = {
+      name: 'test-extension',
+      version: '1.0.0',
+    };
+
+    const result = extensionConsentString(config);
+
+    expect(result).toContain('Installing extension "test-extension".');
+  });
+
+  it('should include warning message', () => {
+    const config: ExtensionConfig = {
+      name: 'test-extension',
+      version: '1.0.0',
+    };
+
+    const result = extensionConsentString(config);
+
+    expect(result).toContain('Extensions may introduce unexpected behavior');
+  });
+
+  it('should include MCP servers when present', () => {
+    const config: ExtensionConfig = {
+      name: 'test-extension',
+      version: '1.0.0',
+      mcpServers: {
+        'test-server': {
+          command: 'node',
+          args: ['server.js'],
+        },
+      },
+    };
+
+    const result = extensionConsentString(config);
+
+    expect(result).toContain(
+      'This extension will run the following MCP servers',
+    );
+    expect(result).toContain('test-server');
+    expect(result).toContain('local');
+    expect(result).toContain('node server.js');
+  });
+
+  it('should include remote MCP servers', () => {
+    const config: ExtensionConfig = {
+      name: 'test-extension',
+      version: '1.0.0',
+      mcpServers: {
+        'remote-server': {
+          httpUrl: 'https://example.com/mcp',
+        },
+      },
+    };
+
+    const result = extensionConsentString(config);
+
+    expect(result).toContain('remote');
+    expect(result).toContain('https://example.com/mcp');
+  });
+
+  it('should include commands when present', () => {
+    const config: ExtensionConfig = {
+      name: 'test-extension',
+      version: '1.0.0',
+    };
+
+    const result = extensionConsentString(config, ['command1', 'command2']);
+
+    expect(result).toContain('This extension will add the following commands');
+    expect(result).toContain('command1, command2');
+  });
+
+  it('should include context file name when present (string)', () => {
+    const config: ExtensionConfig = {
+      name: 'test-extension',
+      version: '1.0.0',
+      contextFileName: 'CUSTOM.md',
+    };
+
+    const result = extensionConsentString(config);
+
+    expect(result).toContain('CUSTOM.md');
+  });
+
+  it('should include context file name when present (array)', () => {
+    const config: ExtensionConfig = {
+      name: 'test-extension',
+      version: '1.0.0',
+      contextFileName: ['FILE1.md', 'FILE2.md'],
+    };
+
+    const result = extensionConsentString(config);
+
+    expect(result).toContain('FILE1.md, FILE2.md');
+  });
+
+  it('should include skills when present', () => {
+    const config: ExtensionConfig = {
+      name: 'test-extension',
+      version: '1.0.0',
+    };
+
+    const result = extensionConsentString(
+      config,
+      [],
+      [
+        {
+          name: 'skill1',
+          description: 'Skill 1 description',
+          level: 'extension',
+          filePath: '/test/skill1',
+          body: 'skill body',
+        },
+        {
+          name: 'skill2',
+          description: 'Skill 2 description',
+          level: 'extension',
+          filePath: '/test/skill2',
+          body: 'skill body',
+        },
+      ],
+    );
+
+    expect(result).toContain(
+      'This extension will install the following skills',
+    );
+    expect(result).toContain('skill1');
+    expect(result).toContain('Skill 1 description');
+  });
+
+  it('should include subagents when present', () => {
+    const config: ExtensionConfig = {
+      name: 'test-extension',
+      version: '1.0.0',
+    };
+
+    const result = extensionConsentString(
+      config,
+      [],
+      [],
+      [
+        {
+          name: 'agent1',
+          description: 'Agent 1 description',
+          systemPrompt: 'You are agent1',
+          level: 'extension',
+        },
+      ],
+    );
+
+    expect(result).toContain(
+      'This extension will install the following subagents',
+    );
+    expect(result).toContain('agent1');
+    expect(result).toContain('Agent 1 description');
+  });
+});
+
+describe('requestConsentOrFail', () => {
+  let mockRequestConsent: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    mockRequestConsent = vi.fn();
+    vi.clearAllMocks();
+  });
+
+  it('should do nothing when options is undefined', async () => {
+    await requestConsentOrFail(mockRequestConsent, undefined);
+
+    expect(mockRequestConsent).not.toHaveBeenCalled();
+  });
+
+  it('should request consent for new extension', async () => {
+    mockRequestConsent.mockResolvedValueOnce(true);
+
+    await requestConsentOrFail(mockRequestConsent, {
+      extensionConfig: { name: 'test-extension', version: '1.0.0' },
+    });
+
+    expect(mockRequestConsent).toHaveBeenCalled();
+  });
+
+  it('should throw error when user declines consent', async () => {
+    mockRequestConsent.mockResolvedValueOnce(false);
+
+    await expect(
+      requestConsentOrFail(mockRequestConsent, {
+        extensionConfig: { name: 'test-extension', version: '1.0.0' },
+      }),
+    ).rejects.toThrow('Installation cancelled for "test-extension".');
+  });
+
+  it('should skip consent when consent string is unchanged', async () => {
+    const extensionConfig: ExtensionConfig = {
+      name: 'test-extension',
+      version: '1.0.0',
+    };
+
+    await requestConsentOrFail(mockRequestConsent, {
+      extensionConfig,
+      previousExtensionConfig: extensionConfig,
+    });
+
+    expect(mockRequestConsent).not.toHaveBeenCalled();
+  });
+
+  it('should request consent when commands change', async () => {
+    mockRequestConsent.mockResolvedValueOnce(true);
+
+    await requestConsentOrFail(mockRequestConsent, {
+      extensionConfig: { name: 'test-extension', version: '1.0.0' },
+      commands: ['command1'],
+      previousExtensionConfig: { name: 'test-extension', version: '1.0.0' },
+      previousCommands: [],
+    });
+
+    expect(mockRequestConsent).toHaveBeenCalled();
+  });
+});

packages/cli/src/commands/extensions/consent.ts

@@ -0,0 +1,211 @@
+import type {
+  ExtensionConfig,
+  ExtensionRequestOptions,
+  SkillConfig,
+  SubagentConfig,
+} from '@qwen-code/qwen-code-core';
+import type { ConfirmationRequest } from '../../ui/types.js';
+import chalk from 'chalk';
+import { t } from '../../i18n/index.js';
+
+/**
+ * Requests consent from the user to perform an action, by reading a Y/n
+ * character from stdin.
+ *
+ * This should not be called from interactive mode as it will break the CLI.
+ *
+ * @param consentDescription The description of the thing they will be consenting to.
+ * @returns boolean, whether they consented or not.
+ */
+export async function requestConsentNonInteractive(
+  consentDescription: string,
+): Promise<boolean> {
+  console.info(consentDescription);
+  const result = await promptForConsentNonInteractive(
+    t('Do you want to continue? [Y/n]: '),
+  );
+  return result;
+}
+
+/**
+ * Requests consent from the user to perform an action, in interactive mode.
+ *
+ * This should not be called from non-interactive mode as it will not work.
+ *
+ * @param consentDescription The description of the thing they will be consenting to.
+ * @param addExtensionUpdateConfirmationRequest A function to actually add a prompt to the UI.
+ * @returns boolean, whether they consented or not.
+ */
+export async function requestConsentInteractive(
+  consentDescription: string,
+  addExtensionUpdateConfirmationRequest: (value: ConfirmationRequest) => void,
+): Promise<boolean> {
+  return promptForConsentInteractive(
+    consentDescription + '\n\n' + t('Do you want to continue?'),
+    addExtensionUpdateConfirmationRequest,
+  );
+}
+
+/**
+ * Asks users a prompt and awaits for a y/n response on stdin.
+ *
+ * This should not be called from interactive mode as it will break the CLI.
+ *
+ * @param prompt A yes/no prompt to ask the user
+ * @returns Whether or not the user answers 'y' (yes). Defaults to 'yes' on enter.
+ */
+async function promptForConsentNonInteractive(
+  prompt: string,
+): Promise<boolean> {
+  const readline = await import('node:readline');
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => {
+      rl.close();
+      resolve(['y', ''].includes(answer.trim().toLowerCase()));
+    });
+  });
+}
+
+/**
+ * Asks users an interactive yes/no prompt.
+ *
+ * This should not be called from non-interactive mode as it will break the CLI.
+ *
+ * @param prompt A markdown prompt to ask the user
+ * @param addExtensionUpdateConfirmationRequest Function to update the UI state with the confirmation request.
+ * @returns Whether or not the user answers yes.
+ */
+async function promptForConsentInteractive(
+  prompt: string,
+  addExtensionUpdateConfirmationRequest: (value: ConfirmationRequest) => void,
+): Promise<boolean> {
+  return new Promise<boolean>((resolve) => {
+    addExtensionUpdateConfirmationRequest({
+      prompt,
+      onConfirm: (resolvedConfirmed) => {
+        resolve(resolvedConfirmed);
+      },
+    });
+  });
+}
+
+/**
+ * Builds a consent string for installing an extension based on it's
+ * extensionConfig.
+ */
+export function extensionConsentString(
+  extensionConfig: ExtensionConfig,
+  commands: string[] = [],
+  skills: SkillConfig[] = [],
+  subagents: SubagentConfig[] = [],
+): string {
+  const output: string[] = [];
+  const mcpServerEntries = Object.entries(extensionConfig.mcpServers || {});
+  output.push(
+    t('Installing extension "{{name}}".', { name: extensionConfig.name }),
+  );
+  output.push(
+    t(
+      '**Extensions may introduce unexpected behavior. Ensure you have investigated the extension source and trust the author.**',
+    ),
+  );
+
+  if (mcpServerEntries.length) {
+    output.push(t('This extension will run the following MCP servers:'));
+    for (const [key, mcpServer] of mcpServerEntries) {
+      const isLocal = !!mcpServer.command;
+      const source =
+        mcpServer.httpUrl ??
+        `${mcpServer.command || ''}${mcpServer.args ? ' ' + mcpServer.args.join(' ') : ''}`;
+      output.push(
+        `  * ${key} (${isLocal ? t('local') : t('remote')}): ${source}`,
+      );
+    }
+  }
+  if (commands && commands.length > 0) {
+    output.push(
+      t('This extension will add the following commands: {{commands}}.', {
+        commands: commands.join(', '),
+      }),
+    );
+  }
+  if (extensionConfig.contextFileName) {
+    const fileName = Array.isArray(extensionConfig.contextFileName)
+      ? extensionConfig.contextFileName.join(', ')
+      : extensionConfig.contextFileName;
+    output.push(
+      t(
+        'This extension will append info to your QWEN.md context using {{fileName}}',
+        { fileName },
+      ),
+    );
+  }
+  if (skills.length > 0) {
+    output.push(t('This extension will install the following skills:'));
+    for (const skill of skills) {
+      output.push(`  * ${chalk.bold(skill.name)}: ${skill.description}`);
+    }
+  }
+  if (subagents.length > 0) {
+    output.push(t('This extension will install the following subagents:'));
+    for (const subagent of subagents) {
+      output.push(`  * ${chalk.bold(subagent.name)}: ${subagent.description}`);
+    }
+  }
+  return output.join('\n');
+}
+
+/**
+ * Requests consent from the user to install an extension (extensionConfig), if
+ * there is any difference between the consent string for `extensionConfig` and
+ * `previousExtensionConfig`.
+ *
+ * Always requests consent if previousExtensionConfig is null.
+ *
+ * Throws if the user does not consent.
+ */
+export const requestConsentOrFail = async (
+  requestConsent: (consent: string) => Promise<boolean>,
+  options?: ExtensionRequestOptions,
+) => {
+  if (!options) return;
+  const {
+    extensionConfig,
+    commands = [],
+    skills = [],
+    subagents = [],
+    previousExtensionConfig,
+    previousCommands = [],
+    previousSkills = [],
+    previousSubagents = [],
+  } = options;
+  const extensionConsent = extensionConsentString(
+    extensionConfig,
+    commands,
+    skills,
+    subagents,
+  );
+  if (previousExtensionConfig) {
+    const previousExtensionConsent = extensionConsentString(
+      previousExtensionConfig,
+      previousCommands,
+      previousSkills,
+      previousSubagents,
+    );
+    if (previousExtensionConsent === extensionConsent) {
+      return;
+    }
+  }
+  if (!(await requestConsent(extensionConsent))) {
+    throw new Error(
+      t('Installation cancelled for "{{name}}".', {
+        name: extensionConfig.name,
+      }),
+    );
+  }
+};

packages/cli/src/commands/extensions/disable.test.ts

@@ -0,0 +1,129 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeEach,
+  type MockInstance,
+} from 'vitest';
+import { disableCommand, handleDisable } from './disable.js';
+import yargs from 'yargs';
+import { SettingScope } from '../../config/settings.js';
+
+const mockDisableExtension = vi.hoisted(() => vi.fn());
+
+vi.mock('./utils.js', () => ({
+  getExtensionManager: vi.fn().mockResolvedValue({
+    disableExtension: mockDisableExtension,
+  }),
+}));
+
+vi.mock('../../utils/errors.js', () => ({
+  getErrorMessage: vi.fn((error: Error) => error.message),
+}));
+
+describe('extensions disable command', () => {
+  it('should fail if no name is provided', () => {
+    const validationParser = yargs([])
+      .command(disableCommand)
+      .fail(false)
+      .locale('en');
+    expect(() => validationParser.parse('disable')).toThrow(
+      'Not enough non-option arguments: got 0, need at least 1',
+    );
+  });
+
+  it('should fail if invalid scope is provided', () => {
+    const validationParser = yargs([])
+      .command(disableCommand)
+      .fail(false)
+      .locale('en');
+    expect(() =>
+      validationParser.parse('disable test-extension --scope=invalid'),
+    ).toThrow(/Invalid scope: invalid/);
+  });
+
+  it('should accept valid scope values', () => {
+    const parser = yargs([]).command(disableCommand).fail(false).locale('en');
+    // Just check that the scope option is recognized, actual execution needs name first
+    expect(() =>
+      parser.parse('disable my-extension --scope=user'),
+    ).not.toThrow();
+  });
+});
+
+describe('handleDisable', () => {
+  let consoleLogSpy: MockInstance;
+  let consoleErrorSpy: MockInstance;
+  let processExitSpy: MockInstance;
+
+  beforeEach(() => {
+    consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    processExitSpy = vi
+      .spyOn(process, 'exit')
+      .mockImplementation(() => undefined as never);
+    vi.clearAllMocks();
+  });
+
+  it('should disable an extension with user scope', async () => {
+    await handleDisable({
+      name: 'test-extension',
+      scope: 'user',
+    });
+
+    expect(mockDisableExtension).toHaveBeenCalledWith(
+      'test-extension',
+      SettingScope.User,
+    );
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      'Extension "test-extension" successfully disabled for scope "user".',
+    );
+  });
+
+  it('should disable an extension with workspace scope', async () => {
+    await handleDisable({
+      name: 'test-extension',
+      scope: 'workspace',
+    });
+
+    expect(mockDisableExtension).toHaveBeenCalledWith(
+      'test-extension',
+      SettingScope.Workspace,
+    );
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      'Extension "test-extension" successfully disabled for scope "workspace".',
+    );
+  });
+
+  it('should default to user scope when no scope is provided', async () => {
+    await handleDisable({
+      name: 'test-extension',
+    });
+
+    expect(mockDisableExtension).toHaveBeenCalledWith(
+      'test-extension',
+      SettingScope.User,
+    );
+  });
+
+  it('should handle errors and exit with code 1', async () => {
+    mockDisableExtension.mockImplementationOnce(() => {
+      throw new Error('Disable failed');
+    });
+
+    await handleDisable({
+      name: 'test-extension',
+      scope: 'user',
+    });
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith('Disable failed');
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+  });
+});

packages/cli/src/commands/extensions/disable.ts

@@ -5,24 +5,29 @@
  */
 
 import { type CommandModule } from 'yargs';
-import { disableExtension } from '../../config/extension.js';
 import { SettingScope } from '../../config/settings.js';
 import { getErrorMessage } from '../../utils/errors.js';
+import { getExtensionManager } from './utils.js';
+import { t } from '../../i18n/index.js';
 
 interface DisableArgs {
   name: string;
   scope?: string;
 }
 
-export function handleDisable(args: DisableArgs) {
+export async function handleDisable(args: DisableArgs) {
+  const extensionManager = await getExtensionManager();
   try {
     if (args.scope?.toLowerCase() === 'workspace') {
-      disableExtension(args.name, SettingScope.Workspace);
+      extensionManager.disableExtension(args.name, SettingScope.Workspace);
     } else {
-      disableExtension(args.name, SettingScope.User);
+      extensionManager.disableExtension(args.name, SettingScope.User);
     }
     console.log(
-      `Extension "${args.name}" successfully disabled for scope "${args.scope}".`,
+      t('Extension "{{name}}" successfully disabled for scope "{{scope}}".', {
+        name: args.name,
+        scope: args.scope || SettingScope.User,
+      }),
     );
   } catch (error) {
     console.error(getErrorMessage(error));
@@ -32,15 +37,15 @@ export function handleDisable(args: DisableArgs) {
 
 export const disableCommand: CommandModule = {
   command: 'disable [--scope] <name>',
-  describe: 'Disables an extension.',
+  describe: t('Disables an extension.'),
   builder: (yargs) =>
     yargs
       .positional('name', {
-        describe: 'The name of the extension to disable.',
+        describe: t('The name of the extension to disable.'),
         type: 'string',
       })
       .option('scope', {
-        describe: 'The scope to disable the extenison in.',
+        describe: t('The scope to disable the extenison in.'),
         type: 'string',
         default: SettingScope.User,
       })
@@ -52,17 +57,18 @@ export const disableCommand: CommandModule = {
             .includes((argv.scope as string).toLowerCase())
         ) {
           throw new Error(
-            `Invalid scope: ${argv.scope}. Please use one of ${Object.values(
-              SettingScope,
-            )
-              .map((s) => s.toLowerCase())
-              .join(', ')}.`,
+            t('Invalid scope: {{scope}}. Please use one of {{scopes}}.', {
+              scope: argv.scope as string,
+              scopes: Object.values(SettingScope)
+                .map((s) => s.toLowerCase())
+                .join(', '),
+            }),
           );
         }
         return true;
       }),
-  handler: (argv) => {
-    handleDisable({
+  handler: async (argv) => {
+    await handleDisable({
       name: argv['name'] as string,
       scope: argv['scope'] as string,
     });

packages/cli/src/commands/extensions/enable.test.ts

@@ -0,0 +1,136 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeEach,
+  type MockInstance,
+} from 'vitest';
+import { enableCommand, handleEnable } from './enable.js';
+import yargs from 'yargs';
+import { SettingScope } from '../../config/settings.js';
+
+const mockEnableExtension = vi.hoisted(() => vi.fn());
+
+vi.mock('./utils.js', () => ({
+  getExtensionManager: vi.fn().mockResolvedValue({
+    enableExtension: mockEnableExtension,
+  }),
+}));
+
+vi.mock('@qwen-code/qwen-code-core', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@qwen-code/qwen-code-core')>();
+  return {
+    ...actual,
+    FatalConfigError: class FatalConfigError extends Error {
+      constructor(message: string) {
+        super(message);
+        this.name = 'FatalConfigError';
+      }
+    },
+    getErrorMessage: (error: Error) => error.message,
+  };
+});
+
+describe('extensions enable command', () => {
+  it('should fail if no name is provided', () => {
+    const validationParser = yargs([])
+      .command(enableCommand)
+      .fail(false)
+      .locale('en');
+    expect(() => validationParser.parse('enable')).toThrow(
+      'Not enough non-option arguments: got 0, need at least 1',
+    );
+  });
+
+  it('should fail if invalid scope is provided', () => {
+    const validationParser = yargs([])
+      .command(enableCommand)
+      .fail(false)
+      .locale('en');
+    expect(() =>
+      validationParser.parse('enable test-extension --scope=invalid'),
+    ).toThrow(/Invalid scope: invalid/);
+  });
+
+  it('should accept valid scope values', () => {
+    const parser = yargs([]).command(enableCommand).fail(false).locale('en');
+    // Just check that the scope option is recognized, actual execution needs name first
+    expect(() =>
+      parser.parse('enable my-extension --scope=user'),
+    ).not.toThrow();
+  });
+});
+
+describe('handleEnable', () => {
+  let consoleLogSpy: MockInstance;
+
+  beforeEach(() => {
+    consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    vi.clearAllMocks();
+  });
+
+  it('should enable an extension with user scope', async () => {
+    await handleEnable({
+      name: 'test-extension',
+      scope: 'user',
+    });
+
+    expect(mockEnableExtension).toHaveBeenCalledWith(
+      'test-extension',
+      SettingScope.User,
+    );
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      'Extension "test-extension" successfully enabled for scope "user".',
+    );
+  });
+
+  it('should enable an extension with workspace scope', async () => {
+    await handleEnable({
+      name: 'test-extension',
+      scope: 'workspace',
+    });
+
+    expect(mockEnableExtension).toHaveBeenCalledWith(
+      'test-extension',
+      SettingScope.Workspace,
+    );
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      'Extension "test-extension" successfully enabled for scope "workspace".',
+    );
+  });
+
+  it('should default to user scope when no scope is provided', async () => {
+    await handleEnable({
+      name: 'test-extension',
+    });
+
+    expect(mockEnableExtension).toHaveBeenCalledWith(
+      'test-extension',
+      SettingScope.User,
+    );
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      'Extension "test-extension" successfully enabled in all scopes.',
+    );
+  });
+
+  it('should throw FatalConfigError when enable fails', async () => {
+    mockEnableExtension.mockImplementationOnce(() => {
+      throw new Error('Enable failed');
+    });
+
+    await expect(
+      handleEnable({
+        name: 'test-extension',
+        scope: 'user',
+      }),
+    ).rejects.toThrow('Enable failed');
+  });
+});

packages/cli/src/commands/extensions/enable.ts

@@ -6,28 +6,36 @@
 
 import { type CommandModule } from 'yargs';
 import { FatalConfigError, getErrorMessage } from '@qwen-code/qwen-code-core';
-import { enableExtension } from '../../config/extension.js';
 import { SettingScope } from '../../config/settings.js';
+import { getExtensionManager } from './utils.js';
+import { t } from '../../i18n/index.js';
 
 interface EnableArgs {
   name: string;
   scope?: string;
 }
 
-export function handleEnable(args: EnableArgs) {
+export async function handleEnable(args: EnableArgs) {
+  const extensionManager = await getExtensionManager();
+
   try {
     if (args.scope?.toLowerCase() === 'workspace') {
-      enableExtension(args.name, SettingScope.Workspace);
+      extensionManager.enableExtension(args.name, SettingScope.Workspace);
     } else {
-      enableExtension(args.name, SettingScope.User);
+      extensionManager.enableExtension(args.name, SettingScope.User);
     }
     if (args.scope) {
       console.log(
-        `Extension "${args.name}" successfully enabled for scope "${args.scope}".`,
+        t('Extension "{{name}}" successfully enabled for scope "{{scope}}".', {
+          name: args.name,
+          scope: args.scope,
+        }),
       );
     } else {
       console.log(
-        `Extension "${args.name}" successfully enabled in all scopes.`,
+        t('Extension "{{name}}" successfully enabled in all scopes.', {
+          name: args.name,
+        }),
       );
     }
   } catch (error) {
@@ -37,16 +45,17 @@ export function handleEnable(args: EnableArgs) {
 
 export const enableCommand: CommandModule = {
   command: 'enable [--scope] <name>',
-  describe: 'Enables an extension.',
+  describe: t('Enables an extension.'),
   builder: (yargs) =>
     yargs
       .positional('name', {
-        describe: 'The name of the extension to enable.',
+        describe: t('The name of the extension to enable.'),
         type: 'string',
       })
       .option('scope', {
-        describe:
+        describe: t(
           'The scope to enable the extenison in. If not set, will be enabled in all scopes.',
+        ),
         type: 'string',
       })
       .check((argv) => {
@@ -57,17 +66,18 @@ export const enableCommand: CommandModule = {
             .includes((argv.scope as string).toLowerCase())
         ) {
           throw new Error(
-            `Invalid scope: ${argv.scope}. Please use one of ${Object.values(
-              SettingScope,
-            )
-              .map((s) => s.toLowerCase())
-              .join(', ')}.`,
+            t('Invalid scope: {{scope}}. Please use one of {{scopes}}.', {
+              scope: argv.scope as string,
+              scopes: Object.values(SettingScope)
+                .map((s) => s.toLowerCase())
+                .join(', '),
+            }),
           );
         }
         return true;
       }),
-  handler: (argv) => {
-    handleEnable({
+  handler: async (argv) => {
+    await handleEnable({
       name: argv['name'] as string,
       scope: argv['scope'] as string,
     });

packages/cli/src/commands/extensions/examples/agent/agents/diary.md

@@ -0,0 +1,87 @@
+---
+name: diary-writer
+description: generate a diary for user
+color: yellow
+tools:
+  - Glob
+  - Grep
+  - ListFiles
+  - ReadFile
+  - ReadManyFiles
+  - NotebookRead
+  - WebFetch
+  - TodoWrite
+  - WebSearch
+modelConfig:
+  model: qwen3-coder-plus
+---
+
+You are a personal diary writing assistant who helps users capture their daily experiences, thoughts, and reflections in meaningful journal entries.
+
+## Core Mission
+
+Help users create thoughtful, well-structured diary entries that preserve their memories, emotions, and personal growth moments.
+
+## Writing Style
+
+**Tone & Voice**
+
+- Warm, personal, and authentic
+- Reflective and introspective
+- Supportive without being overly sentimental
+- Adapt to user's preferred style (casual, formal, poetic, etc.)
+
+**Structure Options**
+
+- Free-form narrative
+- Bullet-point highlights
+- Gratitude-focused entries
+- Goal and achievement tracking
+- Emotional processing format
+
+## Capabilities
+
+**1. Daily Entry Creation**
+
+- Transform user's brief notes into full diary entries
+- Expand on key moments with descriptive details
+- Add context about weather, mood, or setting when relevant
+- Include meaningful quotes or observations
+
+**2. Reflection Prompts**
+
+- Ask thoughtful questions to deepen entries
+- Suggest areas worth exploring further
+- Help identify patterns in thoughts and behaviors
+- Encourage gratitude and positive reflection
+
+**3. Memory Enhancement**
+
+- Help recall specific details from the day
+- Connect current events to past experiences
+- Highlight personal growth and progress
+- Preserve important conversations or interactions
+
+**4. Organization**
+
+- Suggest tags or themes for entries
+- Create summaries for weekly/monthly reviews
+- Track recurring topics or goals
+- Maintain consistency in formatting
+
+## Guidelines
+
+- **Privacy First**: Treat all content as deeply personal and confidential
+- **User's Voice**: Write in a way that sounds like the user, not generic
+- **No Judgment**: Accept all emotions and experiences without criticism
+- **Encourage Honesty**: Create a safe space for authentic expression
+- **Balance**: Mix facts with feelings, events with reflections
+
+## Output Format
+
+When creating a diary entry, include:
+
+1. **Date & Title** (optional creative title)
+2. **Main Content** - The narrative or bullet points
+3. **Reflection** - A brief closing thought or takeaway
+4. **Tags** (optional) - For organization and future reference

packages/cli/src/commands/extensions/examples/agent/qwen-extension.json

@@ -0,0 +1,4 @@
+{
+  "name": "agent-example",
+  "version": "1.0.0"
+}

packages/cli/src/commands/extensions/examples/commands/commands/fs/grep-code.md

@@ -1,6 +1,3 @@
-prompt = """
 Please summarize the findings for the pattern `{{args}}`.
 
 Search Results:
-!{grep -r {{args}} .}
-"""

packages/cli/src/commands/extensions/examples/commands/qwen-extension.json

@@ -0,0 +1,4 @@
+{
+  "name": "commands-example",
+  "version": "1.0.0"
+}

packages/cli/src/commands/extensions/examples/custom-commands/qwen-extension.json

@@ -1,4 +0,0 @@
-{
-  "name": "custom-commands",
-  "version": "1.0.0"
-}

packages/cli/src/commands/extensions/examples/exclude-tools/qwen-extension.json

@@ -1,5 +0,0 @@
-{
-  "name": "excludeTools",
-  "version": "1.0.0",
-  "excludeTools": ["run_shell_command(rm -rf)"]
-}

packages/cli/src/commands/extensions/examples/mcp-server/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-server-example",
   "version": "1.0.0",
-  "description": "Example MCP Server for Gemini CLI Extension",
+  "description": "Example MCP Server for Qwen Code Extension",
   "type": "module",
   "main": "example.js",
   "scripts": {

packages/cli/src/commands/extensions/examples/skills/qwen-extension.json

@@ -0,0 +1,4 @@
+{
+  "name": "skills-example",
+  "version": "1.0.0"
+}

packages/cli/src/commands/extensions/examples/skills/skills/synonyms/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: synonyms
+description: Generate synonyms for words or phrases. Use this skill when the user needs alternative words with similar meanings, wants to expand vocabulary, or seeks varied expressions for writing.
+license: Complete terms in LICENSE.txt
+---
+
+This skill helps generate synonyms and alternative expressions for given words or phrases. It provides contextually appropriate alternatives to enhance vocabulary and improve writing variety.
+
+The user provides a word, phrase, or sentence where they need synonym suggestions. They may specify the context, tone, or formality level desired.
+
+## Synonym Generation Guidelines
+
+When generating synonyms, consider:
+
+- **Context**: The specific domain or situation where the word will be used
+- **Tone**: Formal, informal, neutral, academic, conversational, etc.
+- **Nuance**: Subtle differences in meaning between similar words
+- **Register**: Appropriate level of formality for the intended audience
+
+## Output Format
+
+For each input word or phrase, provide:
+
+1. **Direct Synonyms**: Words with nearly identical meanings
+2. **Related Alternatives**: Words with similar but slightly different connotations
+3. **Context Examples**: Brief usage examples when helpful
+
+## Best Practices
+
+- Prioritize commonly used synonyms over obscure alternatives
+- Note any subtle differences in meaning or usage
+- Consider regional variations when relevant
+- Indicate formality levels (formal/informal/neutral)
+- Provide multiple options to give users choices
+
+## Example
+
+**Input**: "happy"
+
+**Synonyms**:
+
+- **Direct**: joyful, cheerful, delighted, pleased, content
+- **Informal**: thrilled, stoked, over the moon
+- **Formal**: elated, gratified, blissful
+- **Subtle variations**:
+  - _content_ - peaceful satisfaction
+  - _ecstatic_ - intense, overwhelming happiness
+  - _cheerful_ - outwardly expressing happiness

packages/cli/src/commands/extensions/install.test.ts

@@ -4,30 +4,51 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect, vi, type MockInstance } from 'vitest';
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeEach,
+  afterEach,
+  type MockInstance,
+} from 'vitest';
 import { handleInstall, installCommand } from './install.js';
 import yargs from 'yargs';
 
 const mockInstallExtension = vi.hoisted(() => vi.fn());
+const mockRefreshCache = vi.hoisted(() => vi.fn());
+const mockParseInstallSource = vi.hoisted(() => vi.fn());
 const mockRequestConsentNonInteractive = vi.hoisted(() => vi.fn());
-const mockStat = vi.hoisted(() => vi.fn());
+const mockRequestConsentOrFail = vi.hoisted(() => vi.fn());
+const mockIsWorkspaceTrusted = vi.hoisted(() => vi.fn());
+const mockLoadSettings = vi.hoisted(() => vi.fn());
 
-vi.mock('../../config/extension.js', () => ({
-  installExtension: mockInstallExtension,
+vi.mock('@qwen-code/qwen-code-core', () => ({
+  ExtensionManager: vi.fn().mockImplementation(() => ({
+    installExtension: mockInstallExtension,
+    refreshCache: mockRefreshCache,
+  })),
+  parseInstallSource: mockParseInstallSource,
+}));
+
+vi.mock('./consent.js', () => ({
   requestConsentNonInteractive: mockRequestConsentNonInteractive,
+  requestConsentOrFail: mockRequestConsentOrFail,
+}));
+
+vi.mock('../../config/trustedFolders.js', () => ({
+  isWorkspaceTrusted: mockIsWorkspaceTrusted,
+}));
+
+vi.mock('../../config/settings.js', () => ({
+  loadSettings: mockLoadSettings,
 }));
 
 vi.mock('../../utils/errors.js', () => ({
   getErrorMessage: vi.fn((error: Error) => error.message),
 }));
 
-vi.mock('node:fs/promises', () => ({
-  stat: mockStat,
-  default: {
-    stat: mockStat,
-  },
-}));
-
 describe('extensions install command', () => {
   it('should fail if no source is provided', () => {
     const validationParser = yargs([])
@@ -51,17 +72,21 @@ describe('handleInstall', () => {
     processSpy = vi
       .spyOn(process, 'exit')
       .mockImplementation(() => undefined as never);
+    mockRefreshCache.mockResolvedValue(undefined);
+    mockLoadSettings.mockReturnValue({ merged: {} });
+    mockIsWorkspaceTrusted.mockReturnValue(true);
   });
 
   afterEach(() => {
-    mockInstallExtension.mockClear();
-    mockRequestConsentNonInteractive.mockClear();
-    mockStat.mockClear();
-    vi.resetAllMocks();
+    vi.clearAllMocks();
   });
 
   it('should install an extension from a http source', async () => {
-    mockInstallExtension.mockResolvedValue('http-extension');
+    mockParseInstallSource.mockResolvedValue({
+      type: 'http',
+      url: 'http://google.com',
+    });
+    mockInstallExtension.mockResolvedValue({ name: 'http-extension' });
 
     await handleInstall({
       source: 'http://google.com',
@@ -73,7 +98,11 @@ describe('handleInstall', () => {
   });
 
   it('should install an extension from a https source', async () => {
-    mockInstallExtension.mockResolvedValue('https-extension');
+    mockParseInstallSource.mockResolvedValue({
+      type: 'https',
+      url: 'https://google.com',
+    });
+    mockInstallExtension.mockResolvedValue({ name: 'https-extension' });
 
     await handleInstall({
       source: 'https://google.com',
@@ -85,7 +114,11 @@ describe('handleInstall', () => {
   });
 
   it('should install an extension from a git source', async () => {
-    mockInstallExtension.mockResolvedValue('git-extension');
+    mockParseInstallSource.mockResolvedValue({
+      type: 'git',
+      url: 'git@some-url',
+    });
+    mockInstallExtension.mockResolvedValue({ name: 'git-extension' });
 
     await handleInstall({
       source: 'git@some-url',
@@ -97,7 +130,9 @@ describe('handleInstall', () => {
   });
 
   it('throws an error from an unknown source', async () => {
-    mockStat.mockRejectedValue(new Error('ENOENT: no such file or directory'));
+    mockParseInstallSource.mockRejectedValue(
+      new Error('Install source not found.'),
+    );
     await handleInstall({
       source: 'test://google.com',
     });
@@ -107,7 +142,11 @@ describe('handleInstall', () => {
   });
 
   it('should install an extension from a sso source', async () => {
-    mockInstallExtension.mockResolvedValue('sso-extension');
+    mockParseInstallSource.mockResolvedValue({
+      type: 'sso',
+      url: 'sso://google.com',
+    });
+    mockInstallExtension.mockResolvedValue({ name: 'sso-extension' });
 
     await handleInstall({
       source: 'sso://google.com',
@@ -119,8 +158,12 @@ describe('handleInstall', () => {
   });
 
   it('should install an extension from a local path', async () => {
-    mockInstallExtension.mockResolvedValue('local-extension');
-    mockStat.mockResolvedValue({});
+    mockParseInstallSource.mockResolvedValue({
+      type: 'local',
+      path: '/some/path',
+    });
+    mockInstallExtension.mockResolvedValue({ name: 'local-extension' });
+
     await handleInstall({
       source: '/some/path',
     });
@@ -131,6 +174,10 @@ describe('handleInstall', () => {
   });
 
   it('should throw an error if install extension fails', async () => {
+    mockParseInstallSource.mockResolvedValue({
+      type: 'git',
+      url: 'git@some-url',
+    });
     mockInstallExtension.mockRejectedValue(
       new Error('Install extension failed'),
     );

packages/cli/src/commands/extensions/install.ts

@@ -5,58 +5,72 @@
  */
 
 import type { CommandModule } from 'yargs';
+
 import {
-  installExtension,
-  requestConsentNonInteractive,
-} from '../../config/extension.js';
-import type { ExtensionInstallMetadata } from '@qwen-code/qwen-code-core';
+  ExtensionManager,
+  parseInstallSource,
+} from '@qwen-code/qwen-code-core';
 import { getErrorMessage } from '../../utils/errors.js';
-import { stat } from 'node:fs/promises';
+import { isWorkspaceTrusted } from '../../config/trustedFolders.js';
+import { loadSettings } from '../../config/settings.js';
+import {
+  requestConsentOrFail,
+  requestConsentNonInteractive,
+} from './consent.js';
+import { t } from '../../i18n/index.js';
 
 interface InstallArgs {
   source: string;
   ref?: string;
   autoUpdate?: boolean;
+  allowPreRelease?: boolean;
+  consent?: boolean;
 }
 
 export async function handleInstall(args: InstallArgs) {
   try {
-    let installMetadata: ExtensionInstallMetadata;
-    const { source } = args;
+    const installMetadata = await parseInstallSource(args.source);
+
     if (
-      source.startsWith('http://') ||
-      source.startsWith('https://') ||
-      source.startsWith('git@') ||
-      source.startsWith('sso://')
+      installMetadata.type !== 'git' &&
+      installMetadata.type !== 'github-release'
     ) {
-      installMetadata = {
-        source,
-        type: 'git',
-        ref: args.ref,
-        autoUpdate: args.autoUpdate,
-      };
-    } else {
       if (args.ref || args.autoUpdate) {
         throw new Error(
-          '--ref and --auto-update are not applicable for local extensions.',
+          t(
+            '--ref and --auto-update are not applicable for marketplace extensions.',
+          ),
         );
       }
-      try {
-        await stat(source);
-        installMetadata = {
-          source,
-          type: 'local',
-        };
-      } catch {
-        throw new Error('Install source not found.');
-      }
     }
 
-    const name = await installExtension(
-      installMetadata,
-      requestConsentNonInteractive,
+    const requestConsent = args.consent
+      ? () => Promise.resolve()
+      : requestConsentOrFail.bind(null, requestConsentNonInteractive);
+    const workspaceDir = process.cwd();
+    const extensionManager = new ExtensionManager({
+      workspaceDir,
+      isWorkspaceTrusted: !!isWorkspaceTrusted(
+        loadSettings(workspaceDir).merged,
+      ),
+      requestConsent,
+    });
+    await extensionManager.refreshCache();
+
+    const extension = await extensionManager.installExtension(
+      {
+        ...installMetadata,
+        ref: args.ref,
+        autoUpdate: args.autoUpdate,
+        allowPreRelease: args.allowPreRelease,
+      },
+      requestConsent,
+    );
+    console.log(
+      t('Extension "{{name}}" installed successfully and enabled.', {
+        name: extension.name,
+      }),
     );
-    console.log(`Extension "${name}" installed successfully and enabled.`);
   } catch (error) {
     console.error(getErrorMessage(error));
     process.exit(1);
@@ -65,25 +79,40 @@ export async function handleInstall(args: InstallArgs) {
 
 export const installCommand: CommandModule = {
   command: 'install <source>',
-  describe: 'Installs an extension from a git repository URL or a local path.',
+  describe: t(
+    'Installs an extension from a git repository URL, local path, or claude marketplace (marketplace-url:plugin-name).',
+  ),
   builder: (yargs) =>
     yargs
       .positional('source', {
-        describe: 'The github URL or local path of the extension to install.',
+        describe: t(
+          'The github URL, local path, or marketplace source (marketplace-url:plugin-name) of the extension to install.',
+        ),
         type: 'string',
         demandOption: true,
       })
       .option('ref', {
-        describe: 'The git ref to install from.',
+        describe: t('The git ref to install from.'),
         type: 'string',
       })
       .option('auto-update', {
-        describe: 'Enable auto-update for this extension.',
+        describe: t('Enable auto-update for this extension.'),
         type: 'boolean',
       })
+      .option('pre-release', {
+        describe: t('Enable pre-release versions for this extension.'),
+        type: 'boolean',
+      })
+      .option('consent', {
+        describe: t(
+          'Acknowledge the security risks of installing an extension and skip the confirmation prompt.',
+        ),
+        type: 'boolean',
+        default: false,
+      })
       .check((argv) => {
         if (!argv.source) {
-          throw new Error('The source argument must be provided.');
+          throw new Error(t('The source argument must be provided.'));
         }
         return true;
       }),
@@ -92,6 +121,8 @@ export const installCommand: CommandModule = {
       source: argv['source'] as string,
       ref: argv['ref'] as string | undefined,
       autoUpdate: argv['auto-update'] as boolean | undefined,
+      allowPreRelease: argv['pre-release'] as boolean | undefined,
+      consent: argv['consent'] as boolean | undefined,
     });
   },
 };

packages/cli/src/commands/extensions/link.test.ts

@@ -0,0 +1,95 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeEach,
+  type MockInstance,
+} from 'vitest';
+import { linkCommand, handleLink } from './link.js';
+import yargs from 'yargs';
+
+const mockInstallExtension = vi.hoisted(() => vi.fn());
+
+vi.mock('./utils.js', () => ({
+  getExtensionManager: vi.fn().mockResolvedValue({
+    installExtension: mockInstallExtension,
+  }),
+}));
+
+vi.mock('./consent.js', () => ({
+  requestConsentNonInteractive: vi.fn().mockResolvedValue(true),
+  requestConsentOrFail: vi.fn(),
+}));
+
+vi.mock('../../utils/errors.js', () => ({
+  getErrorMessage: vi.fn((error: Error) => error.message),
+}));
+
+describe('extensions link command', () => {
+  it('should fail if no path is provided', () => {
+    const validationParser = yargs([])
+      .command(linkCommand)
+      .fail(false)
+      .locale('en');
+    expect(() => validationParser.parse('link')).toThrow(
+      'Not enough non-option arguments: got 0, need at least 1',
+    );
+  });
+
+  it('should accept a path argument', () => {
+    const parser = yargs([]).command(linkCommand).fail(false).locale('en');
+    expect(() => parser.parse('link /some/path')).not.toThrow();
+  });
+});
+
+describe('handleLink', () => {
+  let consoleLogSpy: MockInstance;
+  let consoleErrorSpy: MockInstance;
+  let processExitSpy: MockInstance;
+
+  beforeEach(() => {
+    consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    processExitSpy = vi
+      .spyOn(process, 'exit')
+      .mockImplementation(() => undefined as never);
+    vi.clearAllMocks();
+  });
+
+  it('should link an extension from a local path', async () => {
+    mockInstallExtension.mockResolvedValueOnce({ name: 'linked-extension' });
+
+    await handleLink({
+      path: '/some/local/path',
+    });
+
+    expect(mockInstallExtension).toHaveBeenCalledWith(
+      {
+        source: '/some/local/path',
+        type: 'link',
+      },
+      expect.any(Function),
+    );
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      'Extension "linked-extension" linked successfully and enabled.',
+    );
+  });
+
+  it('should handle errors and exit with code 1', async () => {
+    mockInstallExtension.mockRejectedValueOnce(new Error('Link failed'));
+
+    await handleLink({
+      path: '/some/local/path',
+    });
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith('Link failed');
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+  });
+});

packages/cli/src/commands/extensions/link.ts

@@ -5,13 +5,14 @@
  */
 
 import type { CommandModule } from 'yargs';
-import {
-  installExtension,
-  requestConsentNonInteractive,
-} from '../../config/extension.js';
-import type { ExtensionInstallMetadata } from '@qwen-code/qwen-code-core';
-
+import { type ExtensionInstallMetadata } from '@qwen-code/qwen-code-core';
 import { getErrorMessage } from '../../utils/errors.js';
+import {
+  requestConsentNonInteractive,
+  requestConsentOrFail,
+} from './consent.js';
+import { getExtensionManager } from './utils.js';
+import { t } from '../../i18n/index.js';
 
 interface InstallArgs {
   path: string;
@@ -23,12 +24,20 @@ export async function handleLink(args: InstallArgs) {
       source: args.path,
       type: 'link',
     };
-    const extensionName = await installExtension(
+    const extensionManager = await getExtensionManager();
+
+    const extension = await extensionManager.installExtension(
       installMetadata,
-      requestConsentNonInteractive,
+      requestConsentOrFail.bind(null, requestConsentNonInteractive),
     );
+    if (!extension) {
+      console.log(t('Link extension failed to install.'));
+      return;
+    }
     console.log(
-      `Extension "${extensionName}" linked successfully and enabled.`,
+      t('Extension "{{name}}" linked successfully and enabled.', {
+        name: extension.name,
+      }),
     );
   } catch (error) {
     console.error(getErrorMessage(error));
@@ -38,12 +47,13 @@ export async function handleLink(args: InstallArgs) {
 
 export const linkCommand: CommandModule = {
   command: 'link <path>',
-  describe:
+  describe: t(
     'Links an extension from a local path. Updates made to the local path will always be reflected.',
+  ),
   builder: (yargs) =>
     yargs
       .positional('path', {
-        describe: 'The name of the extension to link.',
+        describe: t('The name of the extension to link.'),
         type: 'string',
       })
       .check((_) => true),

packages/cli/src/commands/extensions/list.test.ts

@@ -0,0 +1,91 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeEach,
+  type MockInstance,
+} from 'vitest';
+import { listCommand, handleList } from './list.js';
+import yargs from 'yargs';
+
+const mockGetLoadedExtensions = vi.hoisted(() => vi.fn());
+const mockToOutputString = vi.hoisted(() => vi.fn());
+
+vi.mock('./utils.js', () => ({
+  getExtensionManager: vi.fn().mockResolvedValue({
+    getLoadedExtensions: mockGetLoadedExtensions,
+    toOutputString: mockToOutputString,
+  }),
+  extensionToOutputString: mockToOutputString,
+}));
+
+vi.mock('../../utils/errors.js', () => ({
+  getErrorMessage: vi.fn((error: Error) => error.message),
+}));
+
+describe('extensions list command', () => {
+  it('should parse the list command', () => {
+    const parser = yargs([]).command(listCommand).fail(false).locale('en');
+    expect(() => parser.parse('list')).not.toThrow();
+  });
+});
+
+describe('handleList', () => {
+  let consoleLogSpy: MockInstance;
+  let consoleErrorSpy: MockInstance;
+  let processExitSpy: MockInstance;
+
+  beforeEach(() => {
+    consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    processExitSpy = vi
+      .spyOn(process, 'exit')
+      .mockImplementation(() => undefined as never);
+    vi.clearAllMocks();
+  });
+
+  it('should display message when no extensions are installed', async () => {
+    mockGetLoadedExtensions.mockReturnValueOnce([]);
+
+    await handleList();
+
+    expect(consoleLogSpy).toHaveBeenCalledWith('No extensions installed.');
+  });
+
+  it('should list installed extensions', async () => {
+    const mockExtensions = [
+      { name: 'extension-1', version: '1.0.0' },
+      { name: 'extension-2', version: '2.0.0' },
+    ];
+    mockGetLoadedExtensions.mockReturnValueOnce(mockExtensions);
+    mockToOutputString.mockImplementation(
+      (ext) => `${ext.name} (${ext.version})`,
+    );
+
+    await handleList();
+
+    expect(mockGetLoadedExtensions).toHaveBeenCalled();
+    expect(mockToOutputString).toHaveBeenCalledTimes(2);
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      'extension-1 (1.0.0)\n\nextension-2 (2.0.0)',
+    );
+  });
+
+  it('should handle errors and exit with code 1', async () => {
+    mockGetLoadedExtensions.mockImplementationOnce(() => {
+      throw new Error('List failed');
+    });
+
+    await handleList();
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith('List failed');
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+  });
+});

packages/cli/src/commands/extensions/list.ts

@@ -5,19 +5,24 @@
  */
 
 import type { CommandModule } from 'yargs';
-import { loadUserExtensions, toOutputString } from '../../config/extension.js';
 import { getErrorMessage } from '../../utils/errors.js';
+import { extensionToOutputString, getExtensionManager } from './utils.js';
+import { t } from '../../i18n/index.js';
 
 export async function handleList() {
   try {
-    const extensions = loadUserExtensions();
-    if (extensions.length === 0) {
-      console.log('No extensions installed.');
+    const extensionManager = await getExtensionManager();
+    const extensions = extensionManager.getLoadedExtensions();
+
+    if (!extensions || extensions.length === 0) {
+      console.log(t('No extensions installed.'));
       return;
     }
     console.log(
       extensions
-        .map((extension, _): string => toOutputString(extension, process.cwd()))
+        .map((extension, _): string =>
+          extensionToOutputString(extension, extensionManager, process.cwd()),
+        )
         .join('\n\n'),
     );
   } catch (error) {
@@ -28,7 +33,7 @@ export async function handleList() {
 
 export const listCommand: CommandModule = {
   command: 'list',
-  describe: 'Lists installed extensions.',
+  describe: t('Lists installed extensions.'),
   builder: (yargs) => yargs,
   handler: async () => {
     await handleList();

packages/cli/src/commands/extensions/settings.test.ts

@@ -0,0 +1,345 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeEach,
+  type MockInstance,
+} from 'vitest';
+import { settingsCommand } from './settings.js';
+import yargs from 'yargs';
+
+const mockGetLoadedExtensions = vi.hoisted(() => vi.fn());
+const mockGetScopedEnvContents = vi.hoisted(() => vi.fn());
+const mockUpdateSetting = vi.hoisted(() => vi.fn());
+const mockPromptForSetting = vi.hoisted(() => vi.fn());
+
+vi.mock('./utils.js', () => ({
+  getExtensionManager: vi.fn().mockResolvedValue({
+    getLoadedExtensions: mockGetLoadedExtensions,
+  }),
+}));
+
+vi.mock('@qwen-code/qwen-code-core', () => ({
+  ExtensionSettingScope: {
+    USER: 'user',
+    WORKSPACE: 'workspace',
+  },
+  getScopedEnvContents: mockGetScopedEnvContents,
+  promptForSetting: mockPromptForSetting,
+  updateSetting: mockUpdateSetting,
+}));
+
+describe('extensions settings command', () => {
+  it('should fail if no subcommand is provided', () => {
+    const validationParser = yargs([])
+      .command(settingsCommand)
+      .fail(false)
+      .locale('en');
+    expect(() => validationParser.parse('settings')).toThrow(
+      'Not enough non-option arguments: got 0, need at least 1',
+    );
+  });
+
+  it('should register set subcommand', () => {
+    const parser = yargs([]).command(settingsCommand).fail(false).locale('en');
+    expect(() => parser.parse('settings set')).toThrow(
+      'Not enough non-option arguments',
+    );
+  });
+
+  it('should register list subcommand', () => {
+    const parser = yargs([]).command(settingsCommand).fail(false).locale('en');
+    expect(() => parser.parse('settings list')).toThrow(
+      'Not enough non-option arguments',
+    );
+  });
+
+  it('should accept set command with name and setting', () => {
+    const parser = yargs([]).command(settingsCommand).fail(false).locale('en');
+    expect(() =>
+      parser.parse('settings set my-extension API_KEY'),
+    ).not.toThrow();
+  });
+
+  it('should accept set command with scope option', () => {
+    const parser = yargs([]).command(settingsCommand).fail(false).locale('en');
+    expect(() =>
+      parser.parse('settings set my-extension API_KEY --scope=workspace'),
+    ).not.toThrow();
+  });
+
+  it('should fail set command with invalid scope', () => {
+    const parser = yargs([]).command(settingsCommand).fail(false).locale('en');
+    expect(() =>
+      parser.parse('settings set my-extension API_KEY --scope=invalid'),
+    ).toThrow();
+  });
+
+  it('should accept list command with name', () => {
+    const parser = yargs([]).command(settingsCommand).fail(false).locale('en');
+    expect(() => parser.parse('settings list my-extension')).not.toThrow();
+  });
+});
+
+describe('settings set handler', () => {
+  let consoleLogSpy: MockInstance;
+
+  beforeEach(() => {
+    consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    vi.clearAllMocks();
+  });
+
+  it('should return early if extension manager is not available', async () => {
+    const { getExtensionManager } = await import('./utils.js');
+    vi.mocked(getExtensionManager).mockResolvedValueOnce(null as never);
+
+    const parser = yargs([]).command(settingsCommand);
+    await parser.parseAsync('settings set my-extension API_KEY');
+
+    expect(mockUpdateSetting).not.toHaveBeenCalled();
+  });
+
+  it('should return early if no extensions are loaded', async () => {
+    mockGetLoadedExtensions.mockReturnValueOnce([]);
+
+    const parser = yargs([]).command(settingsCommand);
+    await parser.parseAsync('settings set my-extension API_KEY');
+
+    expect(mockUpdateSetting).not.toHaveBeenCalled();
+  });
+
+  it('should log error if extension is not found', async () => {
+    mockGetLoadedExtensions.mockReturnValueOnce([
+      { name: 'other-extension', id: 'other-id', config: {} },
+    ]);
+
+    const parser = yargs([]).command(settingsCommand);
+    await parser.parseAsync('settings set my-extension API_KEY');
+
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      'Extension "my-extension" not found.',
+    );
+    expect(mockUpdateSetting).not.toHaveBeenCalled();
+  });
+
+  it('should call updateSetting with correct arguments for user scope', async () => {
+    const mockExtension = {
+      name: 'my-extension',
+      id: 'ext-id-123',
+      config: { name: 'my-extension', settings: [] },
+    };
+    mockGetLoadedExtensions.mockReturnValueOnce([mockExtension]);
+
+    const parser = yargs([]).command(settingsCommand);
+    await parser.parseAsync('settings set my-extension API_KEY');
+
+    expect(mockUpdateSetting).toHaveBeenCalledWith(
+      mockExtension.config,
+      mockExtension.id,
+      'API_KEY',
+      mockPromptForSetting,
+      'user',
+    );
+  });
+
+  it('should call updateSetting with workspace scope when specified', async () => {
+    const mockExtension = {
+      name: 'my-extension',
+      id: 'ext-id-123',
+      config: { name: 'my-extension', settings: [] },
+    };
+    mockGetLoadedExtensions.mockReturnValueOnce([mockExtension]);
+
+    const parser = yargs([]).command(settingsCommand);
+    await parser.parseAsync(
+      'settings set my-extension API_KEY --scope=workspace',
+    );
+
+    expect(mockUpdateSetting).toHaveBeenCalledWith(
+      mockExtension.config,
+      mockExtension.id,
+      'API_KEY',
+      mockPromptForSetting,
+      'workspace',
+    );
+  });
+});
+
+describe('settings list handler', () => {
+  let consoleLogSpy: MockInstance;
+
+  beforeEach(() => {
+    consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    vi.clearAllMocks();
+  });
+
+  it('should return early if extension manager is not available', async () => {
+    const { getExtensionManager } = await import('./utils.js');
+    vi.mocked(getExtensionManager).mockResolvedValueOnce(null as never);
+
+    const parser = yargs([]).command(settingsCommand);
+    await parser.parseAsync('settings list my-extension');
+
+    expect(mockGetScopedEnvContents).not.toHaveBeenCalled();
+  });
+
+  it('should return early if no extensions are loaded', async () => {
+    mockGetLoadedExtensions.mockReturnValueOnce([]);
+
+    const parser = yargs([]).command(settingsCommand);
+    await parser.parseAsync('settings list my-extension');
+
+    expect(mockGetScopedEnvContents).not.toHaveBeenCalled();
+  });
+
+  it('should log error if extension is not found', async () => {
+    mockGetLoadedExtensions.mockReturnValueOnce([
+      { name: 'other-extension', id: 'other-id', config: {} },
+    ]);
+
+    const parser = yargs([]).command(settingsCommand);
+    await parser.parseAsync('settings list my-extension');
+
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      'Extension "my-extension" not found.',
+    );
+  });
+
+  it('should log message if extension has no settings', async () => {
+    const mockExtension = {
+      name: 'my-extension',
+      id: 'ext-id-123',
+      config: { name: 'my-extension' },
+      settings: [],
+    };
+    mockGetLoadedExtensions.mockReturnValueOnce([mockExtension]);
+
+    const parser = yargs([]).command(settingsCommand);
+    await parser.parseAsync('settings list my-extension');
+
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      'Extension "my-extension" has no settings to configure.',
+    );
+  });
+
+  it('should list settings with their values', async () => {
+    const mockExtension = {
+      name: 'my-extension',
+      id: 'ext-id-123',
+      config: { name: 'my-extension' },
+      settings: [
+        {
+          name: 'API Key',
+          envVar: 'API_KEY',
+          description: 'Your API key',
+          sensitive: false,
+        },
+        {
+          name: 'Secret Token',
+          envVar: 'SECRET_TOKEN',
+          description: 'A secret token',
+          sensitive: true,
+        },
+      ],
+    };
+    mockGetLoadedExtensions.mockReturnValueOnce([mockExtension]);
+    mockGetScopedEnvContents
+      .mockResolvedValueOnce({ API_KEY: 'my-api-key' }) // user scope
+      .mockResolvedValueOnce({}); // workspace scope
+
+    const parser = yargs([]).command(settingsCommand);
+    await parser.parseAsync('settings list my-extension');
+
+    expect(consoleLogSpy).toHaveBeenCalledWith('Settings for "my-extension":');
+    expect(consoleLogSpy).toHaveBeenCalledWith('\n- API Key (API_KEY)');
+    expect(consoleLogSpy).toHaveBeenCalledWith('  Description: Your API key');
+    expect(consoleLogSpy).toHaveBeenCalledWith('  Value: my-api-key (user)');
+  });
+
+  it('should show workspace scope for workspace-scoped settings', async () => {
+    const mockExtension = {
+      name: 'my-extension',
+      id: 'ext-id-123',
+      config: { name: 'my-extension' },
+      settings: [
+        {
+          name: 'API Key',
+          envVar: 'API_KEY',
+          description: 'Your API key',
+          sensitive: false,
+        },
+      ],
+    };
+    mockGetLoadedExtensions.mockReturnValueOnce([mockExtension]);
+    mockGetScopedEnvContents
+      .mockResolvedValueOnce({ API_KEY: 'user-value' }) // user scope
+      .mockResolvedValueOnce({ API_KEY: 'workspace-value' }); // workspace scope
+
+    const parser = yargs([]).command(settingsCommand);
+    await parser.parseAsync('settings list my-extension');
+
+    // Workspace should override user, and show (workspace) scope
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      '  Value: workspace-value (workspace)',
+    );
+  });
+
+  it('should show [not set] for undefined settings', async () => {
+    const mockExtension = {
+      name: 'my-extension',
+      id: 'ext-id-123',
+      config: { name: 'my-extension' },
+      settings: [
+        {
+          name: 'API Key',
+          envVar: 'API_KEY',
+          description: 'Your API key',
+          sensitive: false,
+        },
+      ],
+    };
+    mockGetLoadedExtensions.mockReturnValueOnce([mockExtension]);
+    mockGetScopedEnvContents
+      .mockResolvedValueOnce({}) // user scope
+      .mockResolvedValueOnce({}); // workspace scope
+
+    const parser = yargs([]).command(settingsCommand);
+    await parser.parseAsync('settings list my-extension');
+
+    expect(consoleLogSpy).toHaveBeenCalledWith('  Value: [not set]');
+  });
+
+  it('should show [value stored in keychain] for sensitive settings', async () => {
+    const mockExtension = {
+      name: 'my-extension',
+      id: 'ext-id-123',
+      config: { name: 'my-extension' },
+      settings: [
+        {
+          name: 'Secret Token',
+          envVar: 'SECRET_TOKEN',
+          description: 'A secret token',
+          sensitive: true,
+        },
+      ],
+    };
+    mockGetLoadedExtensions.mockReturnValueOnce([mockExtension]);
+    mockGetScopedEnvContents
+      .mockResolvedValueOnce({ SECRET_TOKEN: 'secret-value' }) // user scope
+      .mockResolvedValueOnce({}); // workspace scope
+
+    const parser = yargs([]).command(settingsCommand);
+    await parser.parseAsync('settings list my-extension');
+
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      '  Value: [value stored in keychain] (user)',
+    );
+  });
+});

packages/cli/src/commands/extensions/settings.ts

@@ -0,0 +1,151 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { CommandModule } from 'yargs';
+import { getExtensionManager } from './utils.js';
+import {
+  ExtensionSettingScope,
+  getScopedEnvContents,
+  promptForSetting,
+  updateSetting,
+} from '@qwen-code/qwen-code-core';
+import { t } from '../../i18n/index.js';
+
+// --- SET COMMAND ---
+interface SetArgs {
+  name: string;
+  setting: string;
+  scope: string;
+}
+
+const setCommand: CommandModule<object, SetArgs> = {
+  command: 'set [--scope] <name> <setting>',
+  describe: t('Set a specific setting for an extension.'),
+  builder: (yargs) =>
+    yargs
+      .positional('name', {
+        describe: t('Name of the extension to configure.'),
+        type: 'string',
+        demandOption: true,
+      })
+      .positional('setting', {
+        describe: t('The setting to configure (name or env var).'),
+        type: 'string',
+        demandOption: true,
+      })
+      .option('scope', {
+        describe: t('The scope to set the setting in.'),
+        type: 'string',
+        choices: ['user', 'workspace'],
+        default: 'user',
+      }),
+  handler: async (args) => {
+    const { name, setting, scope } = args;
+    const extensionManager = await getExtensionManager();
+    if (!extensionManager) return;
+    const extensions = extensionManager.getLoadedExtensions();
+    if (!extensions || extensions.length === 0) return;
+    const extension = extensions.find((e) => e.name === name);
+    if (!extension) {
+      console.log(t('Extension "{{name}}" not found.', { name }));
+      return;
+    }
+    await updateSetting(
+      extension.config,
+      extension.id,
+      setting,
+      promptForSetting,
+      scope as ExtensionSettingScope,
+    );
+  },
+};
+
+// --- LIST COMMAND ---
+interface ListArgs {
+  name: string;
+}
+
+const listCommand: CommandModule<object, ListArgs> = {
+  command: 'list <name>',
+  describe: t('List all settings for an extension.'),
+  builder: (yargs) =>
+    yargs.positional('name', {
+      describe: t('Name of the extension.'),
+      type: 'string',
+      demandOption: true,
+    }),
+  handler: async (args) => {
+    const { name } = args;
+    const extensionManager = await getExtensionManager();
+    if (!extensionManager) return;
+    const extensions = extensionManager.getLoadedExtensions();
+    if (!extensions || extensions.length === 0) return;
+    const extension = extensions.find((e) => e.name === name);
+    if (!extension) {
+      console.log(t('Extension "{{name}}" not found.', { name }));
+      return;
+    }
+    if (!extension || !extension.settings || extension.settings.length === 0) {
+      console.log(
+        t('Extension "{{name}}" has no settings to configure.', { name }),
+      );
+      return;
+    }
+
+    const userSettings = await getScopedEnvContents(
+      extension.config,
+      extension.id,
+      ExtensionSettingScope.USER,
+    );
+    const workspaceSettings = await getScopedEnvContents(
+      extension.config,
+      extension.id,
+      ExtensionSettingScope.WORKSPACE,
+    );
+    const mergedSettings = { ...userSettings, ...workspaceSettings };
+
+    console.log(t('Settings for "{{name}}":', { name }));
+    for (const setting of extension.settings) {
+      const value = mergedSettings[setting.envVar];
+      let displayValue: string;
+      let scopeInfo = '';
+
+      if (workspaceSettings[setting.envVar] !== undefined) {
+        scopeInfo = ' ' + t('(workspace)');
+      } else if (userSettings[setting.envVar] !== undefined) {
+        scopeInfo = ' ' + t('(user)');
+      }
+
+      if (value === undefined) {
+        displayValue = t('[not set]');
+      } else if (setting.sensitive) {
+        displayValue = t('[value stored in keychain]');
+      } else {
+        displayValue = value;
+      }
+      console.log(`
+- ${setting.name} (${setting.envVar})`);
+      console.log(`  ${t('Description:')} ${setting.description}`);
+      console.log(`  ${t('Value:')} ${displayValue}${scopeInfo}`);
+    }
+  },
+};
+
+// --- SETTINGS COMMAND ---
+export const settingsCommand: CommandModule = {
+  command: 'settings <command>',
+  describe: t('Manage extension settings.'),
+  builder: (yargs) =>
+    yargs
+      .command(setCommand)
+      .command(listCommand)
+      .demandCommand(1, t('You need to specify a command (set or list).'))
+      .version(false),
+  handler: () => {
+    // This handler is not called when a subcommand is provided.
+    // Yargs will show the help menu.
+  },
+};

packages/cli/src/commands/extensions/uninstall.ts

@@ -5,8 +5,15 @@
  */
 
 import type { CommandModule } from 'yargs';
-import { uninstallExtension } from '../../config/extension.js';
 import { getErrorMessage } from '../../utils/errors.js';
+import { ExtensionManager } from '@qwen-code/qwen-code-core';
+import {
+  requestConsentNonInteractive,
+  requestConsentOrFail,
+} from './consent.js';
+import { isWorkspaceTrusted } from '../../config/trustedFolders.js';
+import { loadSettings } from '../../config/settings.js';
+import { t } from '../../i18n/index.js';
 
 interface UninstallArgs {
   name: string; // can be extension name or source URL.
@@ -14,8 +21,22 @@ interface UninstallArgs {
 
 export async function handleUninstall(args: UninstallArgs) {
   try {
-    await uninstallExtension(args.name);
-    console.log(`Extension "${args.name}" successfully uninstalled.`);
+    const workspaceDir = process.cwd();
+    const extensionManager = new ExtensionManager({
+      workspaceDir,
+      requestConsent: requestConsentOrFail.bind(
+        null,
+        requestConsentNonInteractive,
+      ),
+      isWorkspaceTrusted: !!isWorkspaceTrusted(
+        loadSettings(workspaceDir).merged,
+      ),
+    });
+    await extensionManager.refreshCache();
+    await extensionManager.uninstallExtension(args.name, false);
+    console.log(
+      t('Extension "{{name}}" successfully uninstalled.', { name: args.name }),
+    );
   } catch (error) {
     console.error(getErrorMessage(error));
     process.exit(1);
@@ -24,17 +45,19 @@ export async function handleUninstall(args: UninstallArgs) {
 
 export const uninstallCommand: CommandModule = {
   command: 'uninstall <name>',
-  describe: 'Uninstalls an extension.',
+  describe: t('Uninstalls an extension.'),
   builder: (yargs) =>
     yargs
       .positional('name', {
-        describe: 'The name or source path of the extension to uninstall.',
+        describe: t('The name or source path of the extension to uninstall.'),
         type: 'string',
       })
       .check((argv) => {
         if (!argv.name) {
           throw new Error(
-            'Please include the name of the extension to uninstall as a positional argument.',
+            t(
+              'Please include the name of the extension to uninstall as a positional argument.',
+            ),
           );
         }
         return true;

packages/cli/src/commands/extensions/update.test.ts

@@ -0,0 +1,262 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeEach,
+  type MockInstance,
+} from 'vitest';
+import { updateCommand, handleUpdate } from './update.js';
+import yargs from 'yargs';
+import { ExtensionUpdateState } from '../../ui/state/extensions.js';
+
+const mockGetLoadedExtensions = vi.hoisted(() => vi.fn());
+const mockUpdateExtension = vi.hoisted(() => vi.fn());
+const mockCheckForAllExtensionUpdates = vi.hoisted(() => vi.fn());
+const mockUpdateAllUpdatableExtensions = vi.hoisted(() => vi.fn());
+const mockCheckForExtensionUpdate = vi.hoisted(() => vi.fn());
+
+vi.mock('./utils.js', () => ({
+  getExtensionManager: vi.fn().mockResolvedValue({
+    getLoadedExtensions: mockGetLoadedExtensions,
+    updateExtension: mockUpdateExtension,
+    checkForAllExtensionUpdates: mockCheckForAllExtensionUpdates,
+    updateAllUpdatableExtensions: mockUpdateAllUpdatableExtensions,
+  }),
+}));
+
+vi.mock('@qwen-code/qwen-code-core', () => ({
+  checkForExtensionUpdate: mockCheckForExtensionUpdate,
+}));
+
+vi.mock('../../utils/errors.js', () => ({
+  getErrorMessage: vi.fn((error: Error) => error.message),
+}));
+
+vi.mock('../../ui/state/extensions.js', () => ({
+  ExtensionUpdateState: {
+    UPDATE_AVAILABLE: 'update available',
+    UP_TO_DATE: 'up to date',
+    ERROR: 'error',
+  },
+}));
+
+describe('extensions update command', () => {
+  it('should fail if neither name nor --all is provided', () => {
+    const validationParser = yargs([])
+      .command(updateCommand)
+      .fail(false)
+      .locale('en');
+    expect(() => validationParser.parse('update')).toThrow(
+      'Either an extension name or --all must be provided',
+    );
+  });
+
+  it('should fail if both name and --all are provided', () => {
+    const validationParser = yargs([])
+      .command(updateCommand)
+      .fail(false)
+      .locale('en');
+    expect(() => validationParser.parse('update test-extension --all')).toThrow(
+      /Arguments .* are mutually exclusive/,
+    );
+  });
+
+  it('should accept --all flag', () => {
+    const parser = yargs([]).command(updateCommand).fail(false).locale('en');
+    expect(() => parser.parse('update --all')).not.toThrow();
+  });
+
+  it('should accept an extension name', () => {
+    const parser = yargs([]).command(updateCommand).fail(false).locale('en');
+    expect(() => parser.parse('update test-extension')).not.toThrow();
+  });
+});
+
+describe('handleUpdate', () => {
+  let consoleLogSpy: MockInstance;
+  let consoleErrorSpy: MockInstance;
+
+  beforeEach(() => {
+    consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    vi.clearAllMocks();
+  });
+
+  describe('update by name', () => {
+    it('should show message when extension is not found', async () => {
+      mockGetLoadedExtensions.mockReturnValueOnce([]);
+
+      await handleUpdate({ name: 'non-existent-extension' });
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        'Extension "non-existent-extension" not found.',
+      );
+    });
+
+    it('should show message when extension has no install metadata', async () => {
+      mockGetLoadedExtensions.mockReturnValueOnce([
+        { name: 'test-extension', installMetadata: undefined },
+      ]);
+
+      await handleUpdate({ name: 'test-extension' });
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        'Unable to install extension "test-extension" due to missing install metadata',
+      );
+    });
+
+    it('should show message when extension is already up to date', async () => {
+      const mockExtension = {
+        name: 'test-extension',
+        installMetadata: { source: 'test' },
+      };
+      mockGetLoadedExtensions.mockReturnValueOnce([mockExtension]);
+      mockCheckForExtensionUpdate.mockResolvedValueOnce(
+        ExtensionUpdateState.UP_TO_DATE,
+      );
+
+      await handleUpdate({ name: 'test-extension' });
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        'Extension "test-extension" is already up to date.',
+      );
+    });
+
+    it('should update extension when update is available', async () => {
+      const mockExtension = {
+        name: 'test-extension',
+        installMetadata: { source: 'test' },
+      };
+      mockGetLoadedExtensions.mockReturnValueOnce([mockExtension]);
+      mockCheckForExtensionUpdate.mockResolvedValueOnce(
+        ExtensionUpdateState.UPDATE_AVAILABLE,
+      );
+      mockUpdateExtension.mockResolvedValueOnce({
+        name: 'test-extension',
+        originalVersion: '1.0.0',
+        updatedVersion: '2.0.0',
+      });
+
+      await handleUpdate({ name: 'test-extension' });
+
+      expect(mockUpdateExtension).toHaveBeenCalledWith(
+        mockExtension,
+        ExtensionUpdateState.UPDATE_AVAILABLE,
+        expect.any(Function),
+      );
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        'Extension "test-extension" successfully updated: 1.0.0 → 2.0.0.',
+      );
+    });
+
+    it('should show up to date message when versions are the same after update', async () => {
+      const mockExtension = {
+        name: 'test-extension',
+        installMetadata: { source: 'test' },
+      };
+      mockGetLoadedExtensions.mockReturnValueOnce([mockExtension]);
+      mockCheckForExtensionUpdate.mockResolvedValueOnce(
+        ExtensionUpdateState.UPDATE_AVAILABLE,
+      );
+      mockUpdateExtension.mockResolvedValueOnce({
+        name: 'test-extension',
+        originalVersion: '1.0.0',
+        updatedVersion: '1.0.0',
+      });
+
+      await handleUpdate({ name: 'test-extension' });
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        'Extension "test-extension" is already up to date.',
+      );
+    });
+
+    it('should handle errors during update', async () => {
+      const mockExtension = {
+        name: 'test-extension',
+        installMetadata: { source: 'test' },
+      };
+      mockGetLoadedExtensions.mockReturnValueOnce([mockExtension]);
+      mockCheckForExtensionUpdate.mockRejectedValueOnce(
+        new Error('Update check failed'),
+      );
+
+      await handleUpdate({ name: 'test-extension' });
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith('Update check failed');
+    });
+  });
+
+  describe('update all', () => {
+    it('should show message when no extensions to update', async () => {
+      mockCheckForAllExtensionUpdates.mockResolvedValueOnce(undefined);
+      mockUpdateAllUpdatableExtensions.mockResolvedValueOnce([]);
+
+      await handleUpdate({ all: true });
+
+      expect(consoleLogSpy).toHaveBeenCalledWith('No extensions to update.');
+    });
+
+    it('should update all extensions with updates available', async () => {
+      mockCheckForAllExtensionUpdates.mockResolvedValueOnce(undefined);
+      mockUpdateAllUpdatableExtensions.mockResolvedValueOnce([
+        {
+          name: 'extension-1',
+          originalVersion: '1.0.0',
+          updatedVersion: '2.0.0',
+        },
+        {
+          name: 'extension-2',
+          originalVersion: '1.0.0',
+          updatedVersion: '1.5.0',
+        },
+      ]);
+
+      await handleUpdate({ all: true });
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        'Extension "extension-1" successfully updated: 1.0.0 → 2.0.0.\n' +
+          'Extension "extension-2" successfully updated: 1.0.0 → 1.5.0.',
+      );
+    });
+
+    it('should filter out extensions with same version after update', async () => {
+      mockCheckForAllExtensionUpdates.mockResolvedValueOnce(undefined);
+      mockUpdateAllUpdatableExtensions.mockResolvedValueOnce([
+        {
+          name: 'extension-1',
+          originalVersion: '1.0.0',
+          updatedVersion: '2.0.0',
+        },
+        {
+          name: 'extension-2',
+          originalVersion: '1.0.0',
+          updatedVersion: '1.0.0',
+        },
+      ]);
+
+      await handleUpdate({ all: true });
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        'Extension "extension-1" successfully updated: 1.0.0 → 2.0.0.',
+      );
+    });
+
+    it('should handle errors during update all', async () => {
+      mockCheckForAllExtensionUpdates.mockRejectedValueOnce(
+        new Error('Update all failed'),
+      );
+
+      await handleUpdate({ all: true });
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith('Update all failed');
+    });
+  });
+});

packages/cli/src/commands/extensions/update.ts

@@ -5,22 +5,14 @@
  */
 
 import type { CommandModule } from 'yargs';
-import {
-  loadExtensions,
-  annotateActiveExtensions,
-  ExtensionStorage,
-  requestConsentNonInteractive,
-} from '../../config/extension.js';
-import {
-  updateAllUpdatableExtensions,
-  type ExtensionUpdateInfo,
-  checkForAllExtensionUpdates,
-  updateExtension,
-} from '../../config/extensions/update.js';
-import { checkForExtensionUpdate } from '../../config/extensions/github.js';
 import { getErrorMessage } from '../../utils/errors.js';
 import { ExtensionUpdateState } from '../../ui/state/extensions.js';
-import { ExtensionEnablementManager } from '../../config/extensions/extensionEnablement.js';
+import {
+  checkForExtensionUpdate,
+  type ExtensionUpdateInfo,
+} from '@qwen-code/qwen-code-core';
+import { getExtensionManager } from './utils.js';
+import { t } from '../../i18n/index.js';
 
 interface UpdateArgs {
   name?: string;
@@ -28,50 +20,50 @@ interface UpdateArgs {
 }
 
 const updateOutput = (info: ExtensionUpdateInfo) =>
-  `Extension "${info.name}" successfully updated: ${info.originalVersion} → ${info.updatedVersion}.`;
+  t(
+    'Extension "{{name}}" successfully updated: {{oldVersion}} → {{newVersion}}.',
+    {
+      name: info.name,
+      oldVersion: info.originalVersion,
+      newVersion: info.updatedVersion,
+    },
+  );
 
 export async function handleUpdate(args: UpdateArgs) {
-  const workingDir = process.cwd();
-  const extensionEnablementManager = new ExtensionEnablementManager(
-    ExtensionStorage.getUserExtensionsDir(),
-    // Force enable named extensions, otherwise we will only update the enabled
-    // ones.
-    args.name ? [args.name] : [],
-  );
-  const allExtensions = loadExtensions(extensionEnablementManager);
-  const extensions = annotateActiveExtensions(
-    allExtensions,
-    workingDir,
-    extensionEnablementManager,
-  );
+  const extensionManager = await getExtensionManager();
+  const extensions = extensionManager.getLoadedExtensions();
+
   if (args.name) {
     try {
       const extension = extensions.find(
         (extension) => extension.name === args.name,
       );
       if (!extension) {
-        console.log(`Extension "${args.name}" not found.`);
+        console.log(t('Extension "{{name}}" not found.', { name: args.name }));
         return;
       }
-      let updateState: ExtensionUpdateState | undefined;
       if (!extension.installMetadata) {
         console.log(
-          `Unable to install extension "${args.name}" due to missing install metadata`,
+          t(
+            'Unable to install extension "{{name}}" due to missing install metadata',
+            { name: args.name },
+          ),
         );
         return;
       }
-      await checkForExtensionUpdate(extension, (newState) => {
-        updateState = newState;
-      });
+      const updateState = await checkForExtensionUpdate(
+        extension,
+        extensionManager,
+      );
       if (updateState !== ExtensionUpdateState.UPDATE_AVAILABLE) {
-        console.log(`Extension "${args.name}" is already up to date.`);
+        console.log(
+          t('Extension "{{name}}" is already up to date.', { name: args.name }),
+        );
         return;
       }
       // TODO(chrstnb): we should list extensions if the requested extension is not installed.
-      const updatedExtensionInfo = (await updateExtension(
+      const updatedExtensionInfo = (await extensionManager.updateExtension(
         extension,
-        workingDir,
-        requestConsentNonInteractive,
         updateState,
         () => {},
       ))!;
@@ -80,10 +72,19 @@ export async function handleUpdate(args: UpdateArgs) {
         updatedExtensionInfo.updatedVersion
       ) {
         console.log(
-          `Extension "${args.name}" successfully updated: ${updatedExtensionInfo.originalVersion} → ${updatedExtensionInfo.updatedVersion}.`,
+          t(
+            'Extension "{{name}}" successfully updated: {{oldVersion}} → {{newVersion}}.',
+            {
+              name: args.name,
+              oldVersion: updatedExtensionInfo.originalVersion,
+              newVersion: updatedExtensionInfo.updatedVersion,
+            },
+          ),
         );
       } else {
-        console.log(`Extension "${args.name}" is already up to date.`);
+        console.log(
+          t('Extension "{{name}}" is already up to date.', { name: args.name }),
+        );
       }
     } catch (error) {
       console.error(getErrorMessage(error));
@@ -92,18 +93,15 @@ export async function handleUpdate(args: UpdateArgs) {
   if (args.all) {
     try {
       const extensionState = new Map();
-      await checkForAllExtensionUpdates(extensions, (action) => {
-        if (action.type === 'SET_STATE') {
-          extensionState.set(action.payload.name, {
-            status: action.payload.state,
+      await extensionManager.checkForAllExtensionUpdates(
+        (extensionName, state) => {
+          extensionState.set(extensionName, {
+            status: state,
             processed: true, // No need to process as we will force the update.
           });
-        }
-      });
-      let updateInfos = await updateAllUpdatableExtensions(
-        workingDir,
-        requestConsentNonInteractive,
-        extensions,
+        },
+      );
+      let updateInfos = await extensionManager.updateAllUpdatableExtensions(
         extensionState,
         () => {},
       );
@@ -111,7 +109,7 @@ export async function handleUpdate(args: UpdateArgs) {
         (info) => info.originalVersion !== info.updatedVersion,
       );
       if (updateInfos.length === 0) {
-        console.log('No extensions to update.');
+        console.log(t('No extensions to update.'));
         return;
       }
       console.log(updateInfos.map((info) => updateOutput(info)).join('\n'));
@@ -123,22 +121,25 @@ export async function handleUpdate(args: UpdateArgs) {
 
 export const updateCommand: CommandModule = {
   command: 'update [<name>] [--all]',
-  describe:
+  describe: t(
     'Updates all extensions or a named extension to the latest version.',
+  ),
   builder: (yargs) =>
     yargs
       .positional('name', {
-        describe: 'The name of the extension to update.',
+        describe: t('The name of the extension to update.'),
         type: 'string',
       })
       .option('all', {
-        describe: 'Update all extensions.',
+        describe: t('Update all extensions.'),
         type: 'boolean',
       })
       .conflicts('name', 'all')
       .check((argv) => {
         if (!argv.all && !argv.name) {
-          throw new Error('Either an extension name or --all must be provided');
+          throw new Error(
+            t('Either an extension name or --all must be provided'),
+          );
         }
         return true;
       }),

packages/cli/src/commands/extensions/utils.test.ts

@@ -0,0 +1,66 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { getExtensionManager } from './utils.js';
+
+const mockRefreshCache = vi.fn();
+const mockExtensionManagerInstance = {
+  refreshCache: mockRefreshCache,
+};
+
+vi.mock('@qwen-code/qwen-code-core', () => ({
+  ExtensionManager: vi
+    .fn()
+    .mockImplementation(() => mockExtensionManagerInstance),
+}));
+
+vi.mock('../../config/settings.js', () => ({
+  loadSettings: vi.fn().mockReturnValue({
+    merged: {},
+  }),
+}));
+
+vi.mock('../../config/trustedFolders.js', () => ({
+  isWorkspaceTrusted: vi.fn().mockReturnValue({ isTrusted: true }),
+}));
+
+vi.mock('./consent.js', () => ({
+  requestConsentOrFail: vi.fn(),
+  requestConsentNonInteractive: vi.fn(),
+}));
+
+describe('getExtensionManager', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockRefreshCache.mockResolvedValue(undefined);
+  });
+
+  it('should return an ExtensionManager instance', async () => {
+    const manager = await getExtensionManager();
+
+    expect(manager).toBeDefined();
+    expect(manager).toBe(mockExtensionManagerInstance);
+  });
+
+  it('should call refreshCache on the ExtensionManager', async () => {
+    await getExtensionManager();
+
+    expect(mockRefreshCache).toHaveBeenCalled();
+  });
+
+  it('should use current working directory as workspace', async () => {
+    const { ExtensionManager } = await import('@qwen-code/qwen-code-core');
+
+    await getExtensionManager();
+
+    expect(ExtensionManager).toHaveBeenCalledWith(
+      expect.objectContaining({
+        workspaceDir: process.cwd(),
+      }),
+    );
+  });
+});

packages/cli/src/commands/extensions/utils.ts

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ExtensionManager, type Extension } from '@qwen-code/qwen-code-core';
+import { loadSettings } from '../../config/settings.js';
+import {
+  requestConsentOrFail,
+  requestConsentNonInteractive,
+} from './consent.js';
+import { isWorkspaceTrusted } from '../../config/trustedFolders.js';
+import * as os from 'node:os';
+import chalk from 'chalk';
+
+export async function getExtensionManager(): Promise<ExtensionManager> {
+  const workspaceDir = process.cwd();
+  const extensionManager = new ExtensionManager({
+    workspaceDir,
+    requestConsent: requestConsentOrFail.bind(
+      null,
+      requestConsentNonInteractive,
+    ),
+    isWorkspaceTrusted: !!isWorkspaceTrusted(loadSettings(workspaceDir).merged),
+  });
+  await extensionManager.refreshCache();
+  return extensionManager;
+}
+
+export function extensionToOutputString(
+  extension: Extension,
+  extensionManager: ExtensionManager,
+  workspaceDir: string,
+): string {
+  const cwd = workspaceDir;
+  const userEnabled = extensionManager.isEnabled(
+    extension.config.name,
+    os.homedir(),
+  );
+  const workspaceEnabled = extensionManager.isEnabled(
+    extension.config.name,
+    cwd,
+  );
+
+  const status = workspaceEnabled ? chalk.green('✓') : chalk.red('✗');
+  let output = `${status} ${extension.config.name} (${extension.config.version})`;
+  output += `\n Path: ${extension.path}`;
+  if (extension.installMetadata) {
+    output += `\n Source: ${extension.installMetadata.source} (Type: ${extension.installMetadata.type})`;
+    if (extension.installMetadata.ref) {
+      output += `\n Ref: ${extension.installMetadata.ref}`;
+    }
+    if (extension.installMetadata.releaseTag) {
+      output += `\n Release tag: ${extension.installMetadata.releaseTag}`;
+    }
+  }
+  output += `\n Enabled (User): ${userEnabled}`;
+  output += `\n Enabled (Workspace): ${workspaceEnabled}`;
+  if (extension.contextFiles.length > 0) {
+    output += `\n Context files:`;
+    extension.contextFiles.forEach((contextFile) => {
+      output += `\n  ${contextFile}`;
+    });
+  }
+  if (extension.commands && extension.commands.length > 0) {
+    output += `\n Commands:`;
+    extension.commands.forEach((command) => {
+      output += `\n  /${command}`;
+    });
+  }
+  if (extension.config.mcpServers) {
+    output += `\n MCP servers:`;
+    Object.keys(extension.config.mcpServers).forEach((key) => {
+      output += `\n  ${key}`;
+    });
+  }
+  return output;
+}

packages/cli/src/commands/mcp/add.test.ts

@@ -7,11 +7,16 @@
 import yargs from 'yargs';
 import { addCommand } from './add.js';
 import { loadSettings, SettingScope } from '../../config/settings.js';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
 
-vi.mock('fs/promises', () => ({
-  readFile: vi.fn(),
-  writeFile: vi.fn(),
-}));
+vi.mock('fs/promises', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('fs/promises')>();
+  return {
+    ...actual,
+    readFile: vi.fn(),
+    writeFile: vi.fn(),
+  };
+});
 
 vi.mock('os', () => {
   const homedir = vi.fn(() => '/home/user');

packages/cli/src/commands/mcp/list.test.ts

@@ -7,18 +7,15 @@
 import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { listMcpServers } from './list.js';
 import { loadSettings } from '../../config/settings.js';
-import { ExtensionStorage, loadExtensions } from '../../config/extension.js';
-import { createTransport } from '@qwen-code/qwen-code-core';
+import { isWorkspaceTrusted } from '../../config/trustedFolders.js';
+import { createTransport, ExtensionManager } from '@qwen-code/qwen-code-core';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 
 vi.mock('../../config/settings.js', () => ({
   loadSettings: vi.fn(),
 }));
-vi.mock('../../config/extension.js', () => ({
-  loadExtensions: vi.fn(),
-  ExtensionStorage: {
-    getUserExtensionsDir: vi.fn(),
-  },
+vi.mock('../../config/trustedFolders.js', () => ({
+  isWorkspaceTrusted: vi.fn(),
 }));
 vi.mock('@qwen-code/qwen-code-core', () => ({
   createTransport: vi.fn(),
@@ -27,20 +24,15 @@ vi.mock('@qwen-code/qwen-code-core', () => ({
     CONNECTING: 'CONNECTING',
     DISCONNECTED: 'DISCONNECTED',
   },
-  Storage: vi.fn().mockImplementation((_cwd: string) => ({
-    getGlobalSettingsPath: () => '/tmp/qwen/settings.json',
-    getWorkspaceSettingsPath: () => '/tmp/qwen/workspace-settings.json',
-    getProjectTempDir: () => '/test/home/.qwen/tmp/mocked_hash',
-  })),
-  QWEN_CONFIG_DIR: '.qwen',
+  ExtensionManager: vi.fn(),
   getErrorMessage: (e: unknown) => (e instanceof Error ? e.message : String(e)),
 }));
 vi.mock('@modelcontextprotocol/sdk/client/index.js');
 
-const mockedExtensionStorage = ExtensionStorage as vi.Mock;
 const mockedLoadSettings = loadSettings as vi.Mock;
-const mockedLoadExtensions = loadExtensions as vi.Mock;
+const mockedIsWorkspaceTrusted = isWorkspaceTrusted as vi.Mock;
 const mockedCreateTransport = createTransport as vi.Mock;
+const MockedExtensionManager = ExtensionManager as vi.Mock;
 const MockedClient = Client as vi.Mock;
 
 interface MockClient {
@@ -57,6 +49,10 @@ describe('mcp list command', () => {
   let consoleSpy: vi.SpyInstance;
   let mockClient: MockClient;
   let mockTransport: MockTransport;
+  let mockExtensionManager: {
+    refreshCache: vi.Mock;
+    getLoadedExtensions: vi.Mock;
+  };
 
   beforeEach(() => {
     vi.resetAllMocks();
@@ -70,12 +66,15 @@ describe('mcp list command', () => {
       close: vi.fn(),
     };
 
+    mockExtensionManager = {
+      refreshCache: vi.fn().mockResolvedValue(undefined),
+      getLoadedExtensions: vi.fn().mockReturnValue([]),
+    };
+
     MockedClient.mockImplementation(() => mockClient);
     mockedCreateTransport.mockResolvedValue(mockTransport);
-    mockedLoadExtensions.mockReturnValue([]);
-    mockedExtensionStorage.getUserExtensionsDir.mockReturnValue(
-      '/mocked/extensions/dir',
-    );
+    MockedExtensionManager.mockImplementation(() => mockExtensionManager);
+    mockedIsWorkspaceTrusted.mockReturnValue(true);
   });
 
   afterEach(() => {
@@ -151,8 +150,9 @@ describe('mcp list command', () => {
       },
     });
 
-    mockedLoadExtensions.mockReturnValue([
+    mockExtensionManager.getLoadedExtensions.mockReturnValue([
       {
+        isActive: true,
         config: {
           name: 'test-extension',
           mcpServers: { 'extension-server': { command: '/ext/server' } },

packages/cli/src/commands/mcp/list.ts

@@ -8,10 +8,13 @@
 import type { CommandModule } from 'yargs';
 import { loadSettings } from '../../config/settings.js';
 import type { MCPServerConfig } from '@qwen-code/qwen-code-core';
-import { MCPServerStatus, createTransport } from '@qwen-code/qwen-code-core';
+import {
+  MCPServerStatus,
+  createTransport,
+  ExtensionManager,
+} from '@qwen-code/qwen-code-core';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { ExtensionStorage, loadExtensions } from '../../config/extension.js';
-import { ExtensionEnablementManager } from '../../config/extensions/extensionEnablement.js';
+import { isWorkspaceTrusted } from '../../config/trustedFolders.js';
 
 const COLOR_GREEN = '\u001b[32m';
 const COLOR_YELLOW = '\u001b[33m';
@@ -22,22 +25,27 @@ async function getMcpServersFromConfig(): Promise<
   Record<string, MCPServerConfig>
 > {
   const settings = loadSettings();
-  const extensions = loadExtensions(
-    new ExtensionEnablementManager(ExtensionStorage.getUserExtensionsDir()),
-  );
+  const extensionManager = new ExtensionManager({
+    isWorkspaceTrusted: !!isWorkspaceTrusted(settings.merged),
+    telemetrySettings: settings.merged.telemetry,
+  });
+  await extensionManager.refreshCache();
+  const extensions = extensionManager.getLoadedExtensions();
   const mcpServers = { ...(settings.merged.mcpServers || {}) };
   for (const extension of extensions) {
-    Object.entries(extension.config.mcpServers || {}).forEach(
-      ([key, server]) => {
-        if (mcpServers[key]) {
-          return;
-        }
-        mcpServers[key] = {
-          ...server,
-          extensionName: extension.config.name,
-        };
-      },
-    );
+    if (extension.isActive) {
+      Object.entries(extension.config.mcpServers || {}).forEach(
+        ([key, server]) => {
+          if (mcpServers[key]) {
+            return;
+          }
+          mcpServers[key] = {
+            ...server,
+            extensionName: extension.config.name,
+          };
+        },
+      );
+    }
   }
   return mcpServers;
 }

packages/cli/src/commands/mcp/remove.test.ts

@@ -9,10 +9,14 @@ import yargs from 'yargs';
 import { loadSettings, SettingScope } from '../../config/settings.js';
 import { removeCommand } from './remove.js';
 
-vi.mock('fs/promises', () => ({
-  readFile: vi.fn(),
-  writeFile: vi.fn(),
-}));
+vi.mock('fs/promises', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('fs/promises')>();
+  return {
+    ...actual,
+    readFile: vi.fn(),
+    writeFile: vi.fn(),
+  };
+});
 
 vi.mock('../../config/settings.js', async () => {
   const actual = await vi.importActual('../../config/settings.js');

packages/cli/src/config/auth.test.ts

@@ -1,41 +1,112 @@
 /**
  * @license
- * Copyright 2025 Google LLC
+ * Copyright 2025 Qwen Team
  * SPDX-License-Identifier: Apache-2.0
  */
 
 import { AuthType } from '@qwen-code/qwen-code-core';
 import { vi } from 'vitest';
 import { validateAuthMethod } from './auth.js';
+import * as settings from './settings.js';
 
 vi.mock('./settings.js', () => ({
   loadEnvironment: vi.fn(),
   loadSettings: vi.fn().mockReturnValue({
-    merged: vi.fn().mockReturnValue({}),
+    merged: {},
   }),
 }));
 
 describe('validateAuthMethod', () => {
   beforeEach(() => {
     vi.resetModules();
+    // Reset mock to default
+    vi.mocked(settings.loadSettings).mockReturnValue({
+      merged: {},
+    } as ReturnType<typeof settings.loadSettings>);
   });
 
   afterEach(() => {
     vi.unstubAllEnvs();
+    delete process.env['OPENAI_API_KEY'];
+    delete process.env['CUSTOM_API_KEY'];
+    delete process.env['GEMINI_API_KEY'];
+    delete process.env['GEMINI_API_KEY_ALTERED'];
+    delete process.env['ANTHROPIC_API_KEY'];
+    delete process.env['ANTHROPIC_BASE_URL'];
+    delete process.env['GOOGLE_API_KEY'];
   });
 
-  it('should return null for USE_OPENAI', () => {
+  it('should return null for USE_OPENAI with default env key', () => {
     process.env['OPENAI_API_KEY'] = 'fake-key';
     expect(validateAuthMethod(AuthType.USE_OPENAI)).toBeNull();
   });
 
-  it('should return an error message for USE_OPENAI if OPENAI_API_KEY is not set', () => {
-    delete process.env['OPENAI_API_KEY'];
+  it('should return an error message for USE_OPENAI if no API key is available', () => {
     expect(validateAuthMethod(AuthType.USE_OPENAI)).toBe(
-      'OPENAI_API_KEY environment variable not found. You can enter it interactively or add it to your .env file.',
+      "Missing API key for OpenAI-compatible auth. Set settings.security.auth.apiKey, or set the 'OPENAI_API_KEY' environment variable.",
     );
   });
 
+  it('should return null for USE_OPENAI with custom envKey from modelProviders', () => {
+    vi.mocked(settings.loadSettings).mockReturnValue({
+      merged: {
+        model: { name: 'custom-model' },
+        modelProviders: {
+          openai: [{ id: 'custom-model', envKey: 'CUSTOM_API_KEY' }],
+        },
+      },
+    } as unknown as ReturnType<typeof settings.loadSettings>);
+    process.env['CUSTOM_API_KEY'] = 'custom-key';
+
+    expect(validateAuthMethod(AuthType.USE_OPENAI)).toBeNull();
+  });
+
+  it('should return error with custom envKey hint when modelProviders envKey is set but env var is missing', () => {
+    vi.mocked(settings.loadSettings).mockReturnValue({
+      merged: {
+        model: { name: 'custom-model' },
+        modelProviders: {
+          openai: [{ id: 'custom-model', envKey: 'CUSTOM_API_KEY' }],
+        },
+      },
+    } as unknown as ReturnType<typeof settings.loadSettings>);
+
+    const result = validateAuthMethod(AuthType.USE_OPENAI);
+    expect(result).toContain('CUSTOM_API_KEY');
+  });
+
+  it('should return null for USE_GEMINI with custom envKey', () => {
+    vi.mocked(settings.loadSettings).mockReturnValue({
+      merged: {
+        model: { name: 'gemini-1.5-flash' },
+        modelProviders: {
+          gemini: [
+            { id: 'gemini-1.5-flash', envKey: 'GEMINI_API_KEY_ALTERED' },
+          ],
+        },
+      },
+    } as unknown as ReturnType<typeof settings.loadSettings>);
+    process.env['GEMINI_API_KEY_ALTERED'] = 'altered-key';
+
+    expect(validateAuthMethod(AuthType.USE_GEMINI)).toBeNull();
+  });
+
+  it('should return error with custom envKey for USE_GEMINI when env var is missing', () => {
+    vi.mocked(settings.loadSettings).mockReturnValue({
+      merged: {
+        model: { name: 'gemini-1.5-flash' },
+        modelProviders: {
+          gemini: [
+            { id: 'gemini-1.5-flash', envKey: 'GEMINI_API_KEY_ALTERED' },
+          ],
+        },
+      },
+    } as unknown as ReturnType<typeof settings.loadSettings>);
+
+    const result = validateAuthMethod(AuthType.USE_GEMINI);
+    expect(result).toContain('GEMINI_API_KEY_ALTERED');
+  });
+
   it('should return null for QWEN_OAUTH', () => {
     expect(validateAuthMethod(AuthType.QWEN_OAUTH)).toBeNull();
   });
@@ -45,4 +116,115 @@ describe('validateAuthMethod', () => {
       'Invalid auth method selected.',
     );
   });
+
+  it('should return null for USE_ANTHROPIC with custom envKey and baseUrl', () => {
+    vi.mocked(settings.loadSettings).mockReturnValue({
+      merged: {
+        model: { name: 'claude-3' },
+        modelProviders: {
+          anthropic: [
+            {
+              id: 'claude-3',
+              envKey: 'CUSTOM_ANTHROPIC_KEY',
+              baseUrl: 'https://api.anthropic.com',
+            },
+          ],
+        },
+      },
+    } as unknown as ReturnType<typeof settings.loadSettings>);
+    process.env['CUSTOM_ANTHROPIC_KEY'] = 'custom-anthropic-key';
+
+    expect(validateAuthMethod(AuthType.USE_ANTHROPIC)).toBeNull();
+  });
+
+  it('should return error for USE_ANTHROPIC when baseUrl is missing', () => {
+    vi.mocked(settings.loadSettings).mockReturnValue({
+      merged: {
+        model: { name: 'claude-3' },
+        modelProviders: {
+          anthropic: [{ id: 'claude-3', envKey: 'CUSTOM_ANTHROPIC_KEY' }],
+        },
+      },
+    } as unknown as ReturnType<typeof settings.loadSettings>);
+    process.env['CUSTOM_ANTHROPIC_KEY'] = 'custom-key';
+
+    const result = validateAuthMethod(AuthType.USE_ANTHROPIC);
+    expect(result).toContain('modelProviders[].baseUrl');
+  });
+
+  it('should return null for USE_VERTEX_AI with custom envKey', () => {
+    vi.mocked(settings.loadSettings).mockReturnValue({
+      merged: {
+        model: { name: 'vertex-model' },
+        modelProviders: {
+          'vertex-ai': [
+            { id: 'vertex-model', envKey: 'GOOGLE_API_KEY_VERTEX' },
+          ],
+        },
+      },
+    } as unknown as ReturnType<typeof settings.loadSettings>);
+    process.env['GOOGLE_API_KEY_VERTEX'] = 'vertex-key';
+
+    expect(validateAuthMethod(AuthType.USE_VERTEX_AI)).toBeNull();
+  });
+
+  it('should use config.modelsConfig.getModel() when Config is provided', () => {
+    // Settings has a different model
+    vi.mocked(settings.loadSettings).mockReturnValue({
+      merged: {
+        model: { name: 'settings-model' },
+        modelProviders: {
+          openai: [
+            { id: 'settings-model', envKey: 'SETTINGS_API_KEY' },
+            { id: 'cli-model', envKey: 'CLI_API_KEY' },
+          ],
+        },
+      },
+    } as unknown as ReturnType<typeof settings.loadSettings>);
+
+    // Mock Config object that returns a different model (e.g., from CLI args)
+    const mockConfig = {
+      modelsConfig: {
+        getModel: vi.fn().mockReturnValue('cli-model'),
+      },
+    } as unknown as import('@qwen-code/qwen-code-core').Config;
+
+    // Set the env key for the CLI model, not the settings model
+    process.env['CLI_API_KEY'] = 'cli-key';
+
+    // Should use 'cli-model' from config.modelsConfig.getModel(), not 'settings-model'
+    const result = validateAuthMethod(AuthType.USE_OPENAI, mockConfig);
+    expect(result).toBeNull();
+    expect(mockConfig.modelsConfig.getModel).toHaveBeenCalled();
+  });
+
+  it('should fail validation when Config provides different model without matching env key', () => {
+    // Clean up any existing env keys first
+    delete process.env['CLI_API_KEY'];
+    delete process.env['SETTINGS_API_KEY'];
+    delete process.env['OPENAI_API_KEY'];
+
+    vi.mocked(settings.loadSettings).mockReturnValue({
+      merged: {
+        model: { name: 'settings-model' },
+        modelProviders: {
+          openai: [
+            { id: 'settings-model', envKey: 'SETTINGS_API_KEY' },
+            { id: 'cli-model', envKey: 'CLI_API_KEY' },
+          ],
+        },
+      },
+    } as unknown as ReturnType<typeof settings.loadSettings>);
+
+    const mockConfig = {
+      modelsConfig: {
+        getModel: vi.fn().mockReturnValue('cli-model'),
+      },
+    } as unknown as import('@qwen-code/qwen-code-core').Config;
+
+    // Don't set CLI_API_KEY - validation should fail
+    const result = validateAuthMethod(AuthType.USE_OPENAI, mockConfig);
+    expect(result).not.toBeNull();
+    expect(result).toContain('CLI_API_KEY');
+  });
 });