Merge pull request #864 from QwenLM/adjust-docs

chore: Adjusted docs directory structure

docs/_meta.ts

@@ -0,0 +1,10 @@
+export default {
+  index: 'Welcome to Qwen Code',
+  cli: 'CLI',
+  core: 'Core',
+  tools: 'Tools',
+  features: 'Features',
+  'ide-integration': 'IDE Integration',
+  development: 'Development',
+  support: 'Support',
+};

docs/cli/_meta.ts

@@ -0,0 +1,35 @@
+export default {
+  index: 'Introduction',
+  authentication: 'Authentication',
+  'openai-auth': 'OpenAI Authentication',
+  commands: 'Commands',
+  configuration: 'Configuration',
+  'configuration-v1': 'Configuration (v1)',
+  themes: 'Themes',
+  tutorials: 'Tutorials',
+  'keyboard-shortcuts': 'Keyboard Shortcuts',
+  'trusted-folders': 'Trusted Folders',
+  'qwen-ignore': 'Ignoring Files',
+  Uninstall: 'Uninstall',
+};
+
+/**
+ * 
+ *  { "label": "Introduction", "slug": "docs/cli" },
+      { "label": "Authentication", "slug": "docs/cli/authentication" },
+      { "label": "Commands", "slug": "docs/cli/commands" },
+      { "label": "Configuration", "slug": "docs/cli/configuration" },
+      { "label": "Checkpointing", "slug": "docs/checkpointing" },
+      { "label": "Extensions", "slug": "docs/extension" },
+      { "label": "Headless Mode", "slug": "docs/headless" },
+      { "label": "IDE Integration", "slug": "docs/ide-integration" },
+      {
+        "label": "IDE Companion Spec",
+        "slug": "docs/ide-companion-spec"
+      },
+      { "label": "Telemetry", "slug": "docs/telemetry" },
+      { "label": "Themes", "slug": "docs/cli/themes" },
+      { "label": "Token Caching", "slug": "docs/cli/token-caching" },
+      { "label": "Trusted Folders", "slug": "docs/trusted-folders" },
+      { "label": "Tutorials", "slug": "docs/cli/tutorials" }
+ */

docs/cli/index.md

@@ -1,17 +1,14 @@
 # Qwen Code CLI
 
-Within Qwen Code, `packages/cli` is the frontend for users to send and receive prompts with Qwen and other AI models and their associated tools. For a general overview of Qwen Code, see the [main documentation page](../index.md).
+Within Qwen Code, `packages/cli` is the frontend for users to send and receive prompts with Qwen and other AI models and their associated tools. For a general overview of Qwen Code
 
 ## Navigating this section
 
 - **[Authentication](./authentication.md):** A guide to setting up authentication with Qwen OAuth and OpenAI-compatible providers.
 - **[Commands](./commands.md):** A reference for Qwen Code CLI commands (e.g., `/help`, `/tools`, `/theme`).
 - **[Configuration](./configuration.md):** A guide to tailoring Qwen Code CLI behavior using configuration files.
-- **[Headless Mode](../headless.md):** A comprehensive guide to using Qwen Code programmatically for scripting and automation.
-- **[Token Caching](./token-caching.md):** Optimize API costs through token caching.
 - **[Themes](./themes.md)**: A guide to customizing the CLI's appearance with different themes.
 - **[Tutorials](tutorials.md)**: A tutorial showing how to use Qwen Code to automate a development task.
-- **[Welcome Back](./welcome-back.md)**: Learn about the Welcome Back feature that helps you resume work seamlessly across sessions.
 
 ## Non-interactive mode
 

docs/development/_meta.ts

@@ -0,0 +1,8 @@
+export default {
+  architecture: 'Architecture',
+  npm: 'NPM',
+  deployment: 'Deployment',
+  telemetry: 'Telemetry',
+  'integration-tests': 'Integration Tests',
+  'issue-and-pr-automation': 'Issue and PR Automation',
+};

docs/features/_meta.ts

@@ -0,0 +1,8 @@
+export default {
+  subagents: 'Subagents',
+  checkpointing: 'Checkpointing',
+  sandbox: 'Sandbox Support',
+  'headless-mode': 'Headless Mode',
+  'welcome-back': 'Welcome Back',
+  'token-caching': 'Token Caching',
+};

docs/ide-integration/_meta.ts

@@ -0,0 +1,4 @@
+export default {
+  'ide-integration': 'Introduction',
+  'ide-companion-spec': 'IDE Companion Spec',
+};

docs/index.md

@@ -1,42 +1,344 @@
 # Welcome to Qwen Code documentation
 
-This documentation provides a comprehensive guide to installing, using, and developing Qwen Code. This tool lets you interact with AI models through a command-line interface.
+Qwen Code is a powerful command-line AI workflow tool adapted from [**Gemini CLI**](https://github.com/google-gemini/gemini-cli) ([details](./README.gemini.md)), 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.
 
-## Overview
+## 🚀 Why Choose Qwen Code?
 
-Qwen Code brings the capabilities of advanced code models to your terminal in an interactive Read-Eval-Print Loop (REPL) environment. Qwen Code consists of a client-side application (`packages/cli`) that communicates with a local server (`packages/core`). Qwen Code also contains a variety of tools for tasks such as performing file system operations, running shells, and web fetching, which are managed by `packages/core`.
+- 🎯 **Free Tier:** Up to 60 requests/min and 2,000 requests/day with your [QwenChat](https://chat.qwen.ai/) account.
+- 🧠 **Advanced Model:** Specially optimized for [Qwen3-Coder](https://github.com/QwenLM/Qwen3-Coder) for superior code understanding and assistance.
+- 🏆 **Comprehensive Features:** Includes subagents, Plan Mode, TodoWrite, vision model support, and full OpenAI API compatibility—all seamlessly integrated.
+- 🔧 **Built-in & Extensible Tools:** Includes file system operations, shell command execution, web fetch/search, and more—all easily extended via the Model Context Protocol (MCP) for custom integrations.
+- 💻 **Developer-Centric:** Built for terminal-first workflows—perfect for command-line enthusiasts.
+- 🛡️ **Open Source:** Apache 2.0 licensed for maximum freedom and transparency.
 
-## Navigating the documentation
+## Installation
 
-This documentation is organized into the following sections:
+### Prerequisites
 
-- **[Execution and Deployment](./deployment.md):** Information for running Qwen Code.
-- **[Architecture Overview](./architecture.md):** Understand the high-level design of Qwen Code, including its components and how they interact.
-- **CLI Usage:** Documentation for `packages/cli`.
-  - **[CLI Introduction](./cli/index.md):** Overview of the command-line interface.
-  - **[Commands](./cli/commands.md):** Description of available CLI commands.
-  - **[Configuration](./cli/configuration.md):** Information on configuring the CLI.
-  - **[Checkpointing](./checkpointing.md):** Documentation for the checkpointing feature.
-  - **[Extensions](./extension.md):** How to extend the CLI with new functionality.
-  - **[IDE Integration](./ide-integration.md):** Connect the CLI to your editor.
-  - **[IDE Companion Extension Spec](./ide-companion-spec.md):** Spec for building IDE companion extensions.
-  - **[Telemetry](./telemetry.md):** Overview of telemetry in the CLI.
-  - **[Trusted Folders](./trusted-folders.md):** An overview of the Trusted Folders security feature.
-- **Core Details:** Documentation for `packages/core`.
-  - **[Core Introduction](./core/index.md):** Overview of the core component.
-  - **[Tools API](./core/tools-api.md):** Information on how the core manages and exposes tools.
-- **Tools:**
-  - **[Tools Overview](./tools/index.md):** Overview of the available tools.
-  - **[File System Tools](./tools/file-system.md):** Documentation for the `read_file` and `write_file` tools.
-  - **[Multi-File Read Tool](./tools/multi-file.md):** Documentation for the `read_many_files` tool.
-  - **[Shell Tool](./tools/shell.md):** Documentation for the `run_shell_command` tool.
-  - **[Web Fetch Tool](./tools/web-fetch.md):** Documentation for the `web_fetch` tool.
-  - **[Web Search Tool](./tools/web-search.md):** Documentation for the `web_search` tool.
-  - **[Memory Tool](./tools/memory.md):** Documentation for the `save_memory` tool.
-- **[Subagents](./subagents.md):** Specialized AI assistants for focused tasks with comprehensive management, configuration, and usage guidance.
-- **[Contributing & Development Guide](../CONTRIBUTING.md):** Information for contributors and developers, including setup, building, testing, and coding conventions.
-- **[NPM](./npm.md):** Details on how the project's packages are structured
-- **[Troubleshooting Guide](./troubleshooting.md):** Find solutions to common problems and FAQs.
-- **[Terms of Service and Privacy Notice](./tos-privacy.md):** Information on the terms of service and privacy notices applicable to your use of Qwen Code.
+Ensure you have [Node.js version 20](https://nodejs.org/en/download) or higher installed.
 
-We hope this documentation helps you make the most of Qwen Code!
+```bash
+curl -qL https://www.npmjs.com/install.sh | sh
+```
+
+### Install from npm
+
+```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)
+
+```bash
+brew install qwen-code
+```
+
+## Quick Start
+
+```bash
+# Start Qwen Code
+qwen
+
+# Example commands
+> Explain this codebase structure
+> Help me refactor this function
+> Generate unit tests for this module
+```
+
+### Session Management
+
+Control your token usage with configurable session limits to optimize costs and performance.
+
+#### Configure Session Token Limit
+
+Create or edit `.qwen/settings.json` in your home directory:
+
+```json
+{
+  "sessionTokenLimit": 32000
+}
+```
+
+#### 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>
+
+**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"
+```
+
+</details>
+
+<details>
+<summary><b>🌍 For International Users</b></summary>
+
+**Option 1: Alibaba Cloud ModelStudio** ([Apply for API Key](https://modelstudio.console.alibabacloud.com/))
+
+```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"
+```
+
+**Option 2: OpenRouter (Free Tier Available)** ([Apply for API Key](https://openrouter.ai/))
+
+```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"
+```
+
+</details>
+
+## Usage Examples
+
+### 🔍 Explore Codebases
+
+```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
+
+```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
+```
+
+### 🔄 Automate Workflows
+
+```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
+
+# 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
+```
+
+### 🐛 Debugging & Analysis
+
+```bash
+# Performance analysis
+> Identify performance bottlenecks in this React component
+> Find all N+1 query problems in the codebase
+
+# Security audit
+> Check for potential SQL injection vulnerabilities
+> Find all hardcoded credentials or API keys
+```
+
+## 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
+```
+
+## Commands & Shortcuts
+
+### Session Commands
+
+- `/help` - Display available commands
+- `/clear` - Clear conversation history
+- `/compress` - Compress history to save tokens
+- `/stats` - Show current session information
+- `/exit` or `/quit` - Exit Qwen Code
+
+### Keyboard Shortcuts
+
+- `Ctrl+C` - Cancel current operation
+- `Ctrl+D` - Exit (on empty line)
+- `Up/Down` - Navigate command history

docs/support/_meta.ts

@@ -0,0 +1,4 @@
+export default {
+  troubleshooting: 'Troubleshooting',
+  'tos-privacy': 'Terms of Service',
+};

docs/tools/_meta.ts

@@ -0,0 +1,11 @@
+export default {
+  index: 'Introduction',
+  'file-system': 'File System',
+  'multi-file': 'Multi-File Read',
+  shell: 'Shell',
+  'todo-write': 'Todo Write',
+  'web-fetch': 'Web Fetch',
+  'web-search': 'Web Search',
+  memory: 'Memory',
+  'mcp-server': 'MCP Servers',
+};

docs/tools/index.md

@@ -54,4 +54,3 @@ Qwen Code's built-in tools can be broadly categorized as follows:
 Additionally, these tools incorporate:
 
 - **[MCP servers](./mcp-server.md)**: MCP servers act as a bridge between the model and your local environment or other services like APIs.
-- **[Sandboxing](../sandbox.md)**: Sandboxing isolates the model and its changes from your environment to reduce potential risk.