docs: update common workflows for clarity and formatting; remove sub-commands documentation

docs/docs

@@ -0,0 +1 @@
+../docs

docs/users/common-workflow.md

@@ -10,25 +10,25 @@ Each task in this document includes clear instructions, example commands, and be
 
 Suppose you've just joined a new project and need to understand its structure quickly.
 
-1. Navigate to the project root directory
+**1. Navigate to the project root directory**
 
 ```bash
 cd /path/to/project
 ```
 
-2. Start Qwen Code
+**2. Start Qwen Code**
 
 ```bash
 qwen
 ```
 
-3. Ask for a high-level overview
+**3. Ask for a high-level overview**
 
 ```
 give me an overview of this codebase
 ```
 
-4. Dive deeper into specific components
+**4. Dive deeper into specific components**
 
 ```
 explain the main architecture patterns used here
@@ -52,19 +52,19 @@ how is authentication handled?
 
 Suppose you need to locate code related to a specific feature or functionality.
 
-1. Ask Qwen Code to find relevant files
+**1. Ask Qwen Code to find relevant files**
 
 ```
 find the files that handle user authentication
 ```
 
-2. Get context on how components interact
+**2. Get context on how components interact**
 
 ```
 how do these authentication files work together?
 ```
 
-3. Understand the execution flow
+**3. Understand the execution flow**
 
 ```
 trace the login process from front-end to database
@@ -79,19 +79,19 @@ trace the login process from front-end to database
 
 Suppose you've encountered an error message and need to find and fix its source.
 
-1. Share the error with Qwen Code
+**1. Share the error with Qwen Code**
 
 ```
 I'm seeing an error when I run npm test
 ```
 
-2. Ask for fix recommendations
+**2. Ask for fix recommendations**
 
 ```
 suggest a few ways to fix the @ts-ignore in user.ts
 ```
 
-3. Apply the fix
+**3. Apply the fix**
 
 ```
 update user.tsto add the null check you suggested
@@ -107,25 +107,25 @@ update user.tsto add the null check you suggested
 
 Suppose you need to update old code to use modern patterns and practices.
 
-1. Identify legacy code for refactoring
+**1. Identify legacy code for refactoring**
 
 ```
 find deprecated API usage in our codebase
 ```
 
-2. Get refactoring recommendations
+**2. Get refactoring recommendations**
 
 ```
 suggest how to refactor utils.js to use modern JavaScript features
 ```
 
-3. Apply the changes safely
+**3. Apply the changes safely**
 
 ```
 refactor utils.js to use ES 2024 features while maintaining the same behavior
 ```
 
-4. Verify the refactoring
+**4. Verify the refactoring**
 
 ```
 run tests for the refactored code
@@ -141,7 +141,7 @@ run tests for the refactored code
 
 Suppose you want to use specialized AI subagents to handle specific tasks more effectively.
 
-1. View available subagents
+**1. View available subagents**
 
 ```
 /agents
@@ -149,7 +149,7 @@ Suppose you want to use specialized AI subagents to handle specific tasks more e
 
 This shows all available subagents and lets you create new ones.
 
-2. Use subagents automatically
+**2. Use subagents automatically**
 
 Qwen Code automatically delegates appropriate tasks to specialized subagents:
 
@@ -161,7 +161,7 @@ review my recent code changes for security issues
 run all tests and fix any failures
 ```
 
-3. Explicitly request specific subagents
+**3. Explicitly request specific subagents**
 
 ```
 use the code-reviewer subagent to check the auth module
@@ -171,7 +171,7 @@ use the code-reviewer subagent to check the auth module
 have the debugger subagent investigate why users can't log in
 ```
 
-4. Create custom subagents for your workflow
+**4. Create custom subagents for your workflow**
 
 ```
 /agents
@@ -196,25 +196,25 @@ Then select "create" and follow the prompts to define:
 
 Suppose you need to add tests for uncovered code.
 
-1. Identify untested code
+**1. Identify untested code**
 
 ```
 find functions in NotificationsService.swift that are not covered by tests
 ```
 
-2. Generate test scaffolding
+**2. Generate test scaffolding**
 
 ```
 add tests for the notification service
 ```
 
-3. Add meaningful test cases
+**3. Add meaningful test cases**
 
 ```
 add test cases for edge conditions in the notification service
 ```
 
-4. Run and verify tests
+**4. Run and verify tests**
 
 ```
 run the new tests and fix any failures
@@ -228,25 +228,25 @@ For comprehensive coverage, ask Qwen Code to identify edge cases you might have
 
 Suppose you need to create a well-documented pull request for your changes.
 
-1. Summarize your changes
+**1. Summarize your changes**
 
 ```
 summarize the changes I've made to the authentication module
 ```
 
-2. Generate a pull request with Qwen Code
+**2. Generate a pull request with Qwen Code**
 
 ```
 create a pr
 ```
 
-3. Review and refine
+**3. Review and refine**
 
 ```
 enhance the PR description with more context about the security improvements
 ```
 
-4. Add testing details
+**4. Add testing details**
 
 ```
 add information about how these changes were tested
@@ -262,25 +262,25 @@ add information about how these changes were tested
 
 Suppose you need to add or update documentation for your code.
 
-1. Identify undocumented code
+**1. Identify undocumented code**
 
 ```
 find functions without proper JSDoc comments in the auth module
 ```
 
-2. Generate documentation
+**2. Generate documentation**
 
 ```
 add JSDoc comments to the undocumented functions in auth.js
 ```
 
-3. Review and enhance
+**3. Review and enhance**
 
 ```
 improve the generated documentation with more context and examples
 ```
 
-4. Verify documentation
+**4. Verify documentation**
 
 ```
 check if the documentation follows our project standards
@@ -296,7 +296,7 @@ check if the documentation follows our project standards
 
 Use `@` to quickly include files or directories without waiting for Qwen Code to read them.
 
-1. Reference a single file
+**1. Reference a single file**
 
 ```
 Explain the logic in @src/utils/auth.js
@@ -304,7 +304,7 @@ Explain the logic in @src/utils/auth.js
 
 This includes the full content of the file in the conversation.
 
-2. Reference a directory
+**2. Reference a directory**
 
 ```
 What's the structure of @src/components?
@@ -312,7 +312,7 @@ What's the structure of @src/components?
 
 This provides a directory listing with file information.
 
-3. Reference MCP resources
+**3. Reference MCP resources**
 
 ```
 Show me the data from @github: repos/owner/repo/issues
@@ -336,7 +336,7 @@ Qwen Code provides two options for resuming previous conversations:
 - `--continue` to automatically continue the most recent conversation
 - `--resume` to display a conversation picker
 
-1. Continue the most recent conversation
+**1. Continue the most recent conversation**
 
 ```bash
 qwen --continue
@@ -344,7 +344,7 @@ qwen --continue
 
 This immediately resumes your most recent conversation without any prompts.
 
-2. Continue in non-interactive mode
+**2. Continue in non-interactive mode**
 
 ```bash
 qwen --continue --p "Continue with my task"
@@ -352,7 +352,7 @@ qwen --continue --p "Continue with my task"
 
 Use `--print` with `--continue` to resume the most recent conversation in non-interactive mode, perfect for scripts or automation.
 
-3. Show conversation picker
+**3. Show conversation picker**
 
 ```bash
 qwen --resume
@@ -500,7 +500,7 @@ cat build-error.txt | qwen -p 'concisely explain the root cause of this build er
 
 Suppose you need Qwen Code's output in a specific format, especially when integrating Qwen Code into scripts or other tools.
 
-1. **Use text format (default)**
+**1. Use text format (default)**
 
 ```bash
 cat data.txt | qwen -p 'summarize this data' --output-format text > summary.txt
@@ -508,7 +508,7 @@ cat data.txt | qwen -p 'summarize this data' --output-format text > summary.txt
 
 This outputs just Qwen Code's plain text response (default behavior).
 
-2. **Use JSON format**
+**2. Use JSON format**
 
 ```bash
 cat code.py | qwen -p 'analyze this code for bugs' --output-format json > analysis.json
@@ -516,7 +516,7 @@ cat code.py | qwen -p 'analyze this code for bugs' --output-format json > analys
 
 This outputs a JSON array of messages with metadata including cost and duration.
 
-3. **Use streaming JSON format**
+**3. Use streaming JSON format**
 
 ```bash
 cat log.txt | qwen -p 'parse this log file for errors' --output-format stream-json

docs/users/features/_meta.ts

@@ -1,6 +1,5 @@
 export default {
   'sub-agents': 'Sub Agents',
-  'sub-commands': 'Sub Commands',
   checkpointing: {
     display: 'hidden',
   },

docs/users/features/sub-agents.md

@@ -1,7 +1,11 @@
 # Sub Agents
+
 Sub Agents are specialized AI assistants that handle specific types of tasks within Qwen Code. They allow you to delegate focused work to AI agents that are configured with task-specific prompts, tools, and behaviors.
+
 ## What are Sub Agents?
+
 Sub Agents are independent AI assistants that:
+
 - **Specialize in specific tasks** - Each Sub Agents 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 Sub Agents has access to
@@ -9,6 +13,7 @@ Sub Agents are independent AI assistants that:
 - **Provide detailed feedback** - You can see their progress, tool usage, and execution statistics in real-time
 
 ## Key Benefits
+
 - **Task Specialization**: Create agents optimized for specific workflows (testing, documentation, refactoring, etc.)
 - **Context Isolation**: Keep specialized work separate from your main conversation
 - **Reusability**: Save and reuse agent configurations across projects and sessions
@@ -16,13 +21,16 @@ Sub Agents are independent AI assistants that:
 - **Progress Visibility**: Monitor agent execution with real-time progress updates
 
 ## How Sub Agents Work
+
 1. **Configuration**: You create Sub Agents configurations that define their behavior, tools, and system prompts
 2. **Delegation**: The main AI can automatically delegate tasks to appropriate Sub Agents
 3. **Execution**: Sub Agents work independently, using their configured tools to complete tasks
 4. **Results**: They return results and execution summaries back to the main conversation
 
 ## Getting Started
+
 ### Quick Start
+
 1. **Create your first Sub Agents**:
 
    `/agents create`
@@ -38,6 +46,7 @@ Sub Agents are independent AI assistants that:
 3. **Use Sub Agents automatically**: Simply ask the main AI to perform tasks that match your Sub Agents’ specializations. The AI will automatically delegate appropriate work.
 
 ### Example Usage
+
 ```
 User: "Please write comprehensive tests for the authentication module"
 AI: I'll delegate this to your testing specialist Sub Agents.
@@ -45,26 +54,32 @@ AI: I'll delegate this to your testing specialist Sub Agents.
 [Shows real-time progress of test creation]
 [Returns with completed test files and execution summary]`
 ```
+
 ## Management
+
 ### CLI Commands
+
 Sub Agents are managed through the `/agents` slash command and its subcommands:
-#### /agents create
+
-Creates a new Sub Agents through a guided step wizard.
+**Usage:**：`/agents create`。Creates a new Sub Agents through a guided step wizard.
-**Usage:**
+
-`/agents create`
+**Usage:**：`/agents manage`。Opens an interactive management dialog for viewing and managing existing Sub Agents.
-#### /agents manage
+
-Opens an interactive management dialog for viewing and managing existing Sub Agents.
-**Usage:**
-`/agents manage`
 ### Storage Locations
+
 Sub Agents are stored as Markdown files in two locations:
+
 - **Project-level**: `.qwen/agents/` (takes precedence)
 - **User-level**: `~/.qwen/agents/` (fallback)
 
 This allows you to have both project-specific agents and personal agents that work across all projects.
+
 ### File Format
+
 Sub Agents are configured using Markdown files with YAML frontmatter. This format is human-readable and easy to edit with any text editor.
+
 #### Basic Structure
+
 ```
 ---
 name: agent-name
@@ -79,7 +94,9 @@ System prompt content goes here.
 Multiple paragraphs are supported.
 You can use ${variable} templating for dynamic content.
 ```
+
 #### Example Usage
+
 ```
 ---
 name: project-documenter
@@ -96,25 +113,37 @@ Generated on: ${timestamp}
 Focus on creating clear, comprehensive documentation that helps both
 new contributors and end users understand the project.
 ```
+
 ## Using Sub Agents Effectively
+
 ### Automatic Delegation
+
 Qwen Code proactively delegates tasks based on:
+
 - The task description in your request
 - The description field in Sub Agents configurations
 - Current context and available tools
 
 To encourage more proactive Sub Agents use, include phrases like “use PROACTIVELY” or “MUST BE USED” in your description field.
+
 ### Explicit Invocation
+
 Request a specific Sub Agents by mentioning it in your command:
+
 ```
 Let the testing-expert Sub Agents create unit tests for the payment module
 Have the documentation-writer Sub Agents update the API reference
 Get the react-specialist Sub Agents to optimize this component's performance
 ```
+
 ## Examples
+
 ### Development Workflow Agents
+
 #### Testing Specialist
+
 Perfect for comprehensive test creation and test-driven development.
+
 ```
 ---
 name: testing-expert
@@ -150,12 +179,15 @@ Focus on both positive and negative test cases.
 ```
 
 **Use Cases:**
+
 - “Write unit tests for the authentication service”
 - “Create integration tests for the payment processing workflow”
 - “Add test coverage for edge cases in the data validation module”
 
 #### Documentation Writer
+
 Specialized in creating clear, comprehensive documentation.
+
 ```
 ---
 name: documentation-writer
@@ -200,12 +232,15 @@ the actual implementation. Use clear headings, bullet points, and examples.
 ```
 
 **Use Cases:**
+
 - “Create API documentation for the user management endpoints”
 - “Write a comprehensive README for this project”
 - “Document the deployment process with troubleshooting steps”
 
 #### Code Reviewer
+
 Focused on code quality, security, and best practices.
+
 ```
 ---
 name: code-reviewer
@@ -239,13 +274,17 @@ Prioritize issues by impact and provide rationale for recommendations.
 ```
 
 **Use Cases:**
+
 - “Review this authentication implementation for security issues”
 - “Check the performance implications of this database query logic”
 - “Evaluate the code structure and suggest improvements”
 
 ### Technology-Specific Agents
+
 #### React Specialist
+
 Optimized for React development, hooks, and component patterns.
+
 ```
 ---
 name: react-specialist
@@ -282,12 +321,15 @@ Focus on accessibility and user experience considerations.
 ```
 
 **Use Cases:**
+
 - “Create a reusable data table component with sorting and filtering”
 - “Implement a custom hook for API data fetching with caching”
 - “Refactor this class component to use modern React patterns”
 
 #### Python Expert
+
 Specialized in Python development, frameworks, and best practices.
+
 ```
 ---
 name: python-expert
@@ -325,60 +367,87 @@ Focus on writing clean, maintainable Python code that follows community standard
 ```
 
 **Use Cases:**
+
 - “Create a FastAPI service for user authentication with JWT tokens”
 - “Implement a data processing pipeline with pandas and error handling”
 - “Write a CLI tool using argparse with comprehensive help documentation”
 
 ## Best Practices
+
 ### Design Principles
+
 #### Single Responsibility Principle
+
 Each Sub Agents should have a clear, focused purpose.
+
 **✅ Good:**
+
 ```
 ---
 name: testing-expert
 description: Writes comprehensive unit tests and integration tests
 ---
 ```
+
 **❌ Avoid:**
+
 ```
 ---
 name: general-helper
 description: Helps with testing, documentation, code review, and deployment
 ---
 ```
+
 **Why:** Focused agents produce better results and are easier to maintain.
+
 #### Clear Specialization
+
 Define specific expertise areas rather than broad capabilities.
+
 **✅ Good:**
+
 ```
 ---
 name: react-performance-optimizer
 description: Optimizes React applications for performance using profiling and best practices
 ---
 ```
+
 **❌ Avoid:**
+
 ```
 ---
 name: frontend-developer
 description: Works on frontend development tasks
 ---
 ```
+
 **Why:** Specific expertise leads to more targeted and effective assistance.
+
 #### Actionable Descriptions
+
 Write descriptions that clearly indicate when to use the agent.
+
 **✅ Good:**
+
 ```
 description: Reviews code for security vulnerabilities, performance issues, and maintainability concerns
 ```
+
 **❌ Avoid:**
+
 ```
 description: A helpful code reviewer
 ```
+
 **Why:** Clear descriptions help the main AI choose the right agent for each task.
+
 ### Configuration Best Practices
+
 #### System Prompt Guidelines
+
 **Be Specific About Expertise:**
+
 ```
 You are a Python testing specialist with expertise in:
 
@@ -389,6 +458,7 @@ You are a Python testing specialist with expertise in:
 ```
 
 **Include Step-by-Step Approaches:**
+
 ```
 For each testing task:
 
@@ -400,6 +470,7 @@ For each testing task:
 ```
 
 **Specify Output Standards:**
+
 ```
 Always follow these standards:
 
@@ -410,6 +481,7 @@ Always follow these standards:
 ```
 
 ## Security Considerations
+
 - **Tool Restrictions**: Sub Agents only have access to their configured tools
 - **Sandboxing**: All tool execution follows the same security model as direct tool use
 - **Audit Trail**: All Sub Agents actions are logged and visible in real-time

docs/users/quickstart.md

@@ -86,6 +86,7 @@ what can Qwen Code do?
 ```
 
 > [!note]
+>
 > Qwen Code reads your files as needed - you don't have to manually add context. Qwen Code also has access to its own documentation and can answer questions about its features and capabilities.
 
 ### Make your first code change
@@ -104,6 +105,7 @@ Qwen Code will:
 4. Make the edit
 
 > [!note]
+>
 > Qwen Code always asks for permission before modifying files. You can approve individual changes or enable "Accept all" mode for a session.
 
 ### Use Git with Qwen Code
@@ -184,6 +186,7 @@ review my changes and suggest improvements
 ```
 
 > [!tip]
+>
 > **Remember**: Qwen Code is your AI pair programmer. Talk to it like you would a helpful colleague - describe what you want to achieve, and it will help you get there.
 
 ## Essential commands
@@ -208,18 +211,23 @@ See the [CLI reference](/users/reference/cli-reference) for a complete list of c
 
 ## Pro tips for beginners
 
-- Be specific with your requests
+**Be specific with your requests**
+
 - Instead of: "fix the bug"
 - Try: "fix the login bug where users see a blank screen after entering wrong credentials"
-- Use step-by-step instructions
+
+**Use step-by-step instructions**
+
 - Break complex tasks into steps:
+
 ```
 1. create a new database table for user profiles
 2. create an API endpoint to get and update user profiles
 3. build a webpage that allows users to see and edit their information
 ```
 
-- Let Claude explore first
+**Let Claude explore first**
+
 - Before making changes, let Claude understand your code:
 
 ```
@@ -230,7 +238,8 @@ See the [CLI reference](/users/reference/cli-reference) for a complete list of c
 build a dashboard showing products that are most frequently returned by our UK customers
 ```
 
-- Save time with shortcuts
+**Save time with shortcuts**
+
 - Press `?` to see all available keyboard shortcuts
 - Use Tab for command completion
 - Press ↑ for command history