diff --git a/skills/vefaas-cli/SKILL.md b/skills/vefaas-cli/SKILL.md
new file mode 100644
index 00000000..610fb3c4
--- /dev/null
+++ b/skills/vefaas-cli/SKILL.md
@@ -0,0 +1,82 @@
+---
+name: vefaas
+description: Deploy and manage serverless applications on Volcengine veFaaS. Use when the user wants to deploy web apps, manage functions (pull code, upload and deploy), configure environment variables, or work with veFaaS services.
+allowed-tools: Bash(vefaas:*)
+---
+
+# vefaas: Volcengine FaaS CLI
+
+**vefaas** is the command-line tool for Volcengine Function Service (veFaaS). It enables serverless application deployment, function management, and configuration through a streamlined workflow.
+
+## Installation
+
+```bash
+npm i -g https://vefaas-cli.tos-cn-beijing.volces.com/volcengine-vefaas-latest.tgz
+```
+
+Verify installation:
+```bash
+vefaas --version
+```
+
+## Core Workflow
+
+The typical deployment pattern:
+
+1. **Check Node.js**: `node --version` (requires >= 18, recommended 20+)
+   - If version is too low, switch using nvm (`nvm use 20`) or fnm (`fnm use 20`), or manually install a newer version
+2. **Check CLI**: `vefaas --version` to verify installation
+3. **Check Auth**: `vefaas login --check` to verify login status
+   - If not logged in, run `vefaas login --sso` (opens browser, auto-completes when user authorizes - no manual input needed)
+4. **Deploy**: `vefaas deploy --newApp <name> --gatewayName $(vefaas run listgateways --first) --yes`
+5. **Access**: `vefaas domains` to view URLs
+
+## Quick Commands
+
+| Purpose | Command |
+|---------|---------|
+| Check auth | `vefaas login --check` |
+| Login (SSO) | `vefaas login --sso` (non-interactive: opens browser, auto-completes when authorized, **recommended**) |
+| Login (AK/SK) | `vefaas login --accessKey <AK> --secretKey <SK>` |
+| Init from template | `vefaas init --template <name>` |
+| Deploy new app | `vefaas deploy --newApp <name> --gatewayName $(vefaas run listgateways --first) --yes` |
+| Deploy existing | `vefaas deploy --app <name> --yes` |
+| List gateways | `vefaas run listgateways --first` |
+| View URLs | `vefaas domains` |
+| Set env var | `vefaas env set KEY VALUE` |
+| View config | `vefaas config list` |
+| Pull code | `vefaas pull --func <name>` |
+| Inspect project | `vefaas inspect` |
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `-d, --debug` | Enable debug mode for troubleshooting |
+| `--yes` | Non-interactive mode (required for CI/AI coding) |
+| `--region` | Region override (e.g., cn-beijing) |
+
+## Cookbooks
+
+Step-by-step guides for common scenarios:
+
+- **[Template Quickstart](cookbooks/template-quickstart.md)** - Create and deploy from official templates
+- **[Deploy Existing Code](cookbooks/deploy-existing-code.md)** - Deploy your existing project
+- **[Manage Functions](cookbooks/manage-functions.md)** - Manage functions (pull code, upload and deploy)
+
+## References
+
+Detailed documentation on specific topics:
+
+- **[Authentication](references/authentication.md)** - Login methods and credentials
+- **[Configuration](references/configuration.md)** - Config files and settings
+- **[Environment Variables](references/environment-variables.md)** - Managing env vars
+- **[Framework Detection](references/framework-detection.md)** - Supported frameworks and auto-detection
+- **[Troubleshooting](references/troubleshooting.md)** - Debug mode, common issues, and solutions
+
+## Important Notes
+
+- Always use `--yes` for non-interactive mode in CI/CD and AI coding scenarios
+- Use `$(vefaas run listgateways --first)` to get an available gateway
+- Config is stored in `.vefaas/config.json` after linking
+- Use `--debug` or `-d` to troubleshoot issues
diff --git a/skills/vefaas-cli/cookbooks/deploy-existing-code.md b/skills/vefaas-cli/cookbooks/deploy-existing-code.md
new file mode 100644
index 00000000..11dd2464
--- /dev/null
+++ b/skills/vefaas-cli/cookbooks/deploy-existing-code.md
@@ -0,0 +1,144 @@
+# Cookbook: Deploy Existing Code
+
+Deploy your existing project to veFaaS with automatic framework detection.
+
+## Prerequisites
+
+- vefaas CLI installed
+- Valid credentials (AKSK/SSO)
+- Existing project with supported framework
+
+## Scenario A: Simple Deployment (No Env Dependencies)
+
+For projects without database or external service dependencies.
+
+### One-liner Deployment
+
+```bash
+cd your-project
+
+# Deploy with auto-detection
+vefaas deploy --newApp my-app --gatewayName $(vefaas run listgateways --first) --yes
+```
+
+The CLI will:
+1. Auto-detect framework (Next.js, Nuxt, FastAPI, etc.)
+2. Configure build command and output path
+3. Run local build
+4. Package and upload
+5. Deploy and return access URL
+
+> [!NOTE]
+> - **Static sites**: Auto-detected static projects (Vite, Vitepress, etc.) will be served via auto-generated Caddyfile
+> - **Server apps**: If your app requires server logic, ensure it listens on port **8000** by default
+
+### Verify Detection
+
+```bash
+# Check what vefaas detected
+vefaas inspect
+
+# Output:
+# > Detected Settings:
+# > - Build Command: npm run build
+# > - Output Directory: .next
+# > - Start Command: node server.js
+# > - Port: 3000
+# > - Runtime: native-node20/v1
+# > - Framework: next.js
+```
+
+## Scenario B: With Environment Dependencies
+
+For projects requiring database connections, API keys, etc.
+
+### Step 1: Link Without Deploying
+
+```bash
+cd your-project
+
+# Create app and link, but don't deploy yet
+vefaas link --newApp my-app --gatewayName $(vefaas run listgateways --first) --yes
+```
+
+### Step 2: Configure Environment Variables
+
+```bash
+# Set individual variables
+vefaas env set DATABASE_URL "postgres://user:pass@host:5432/db"
+vefaas env set API_KEY "your-api-key"
+
+# Or import from .env file
+vefaas env import ./.env.prod
+```
+
+Example `.env.prod` file:
+```
+PGHOST=db.volces.com
+PGDATABASE=mydb
+PGUSER=admin
+PGPASSWORD=secret
+API_KEY="your-api-key"
+```
+
+### Step 3: Deploy
+
+```bash
+vefaas deploy
+```
+
+## Scenario C: Custom Build Configuration
+
+When auto-detection doesn't match your setup.
+
+### Override via Command Line
+
+```bash
+vefaas deploy \
+  --newApp my-app \
+  --gatewayName $(vefaas run listgateways --first) \
+  --buildCommand "npm run build" \
+  --outputPath dist \
+  --command "node dist/index.js" \
+  --port 3000 \
+  --yes
+```
+
+### Or Configure Persistently
+
+```bash
+# Set config first
+vefaas config --buildCommand "npm run build" --outputPath dist --command "node dist/index.js" --port 3000
+
+# Then deploy
+vefaas deploy --newApp my-app --gatewayName $(vefaas run listgateways --first) --yes
+```
+
+## Scenario D: Deploy to Existing Application
+
+When you already have a veFaaS application.
+
+```bash
+# By app name
+vefaas deploy --app my-existing-app --yes
+
+# By app ID
+vefaas deploy --appId app-xxxxx --yes
+```
+
+## Supported Frameworks
+
+| Framework | Runtime | Auto-detected |
+|-----------|---------|---------------|
+| FastAPI | native-python3.12/v1 | Yes |
+| Django | native-python3.12/v1 | Yes |
+| Flask | native-python3.12/v1 | Yes |
+| Express | native-node20/v1 | Yes |
+| Next.js | native-node20/v1 | Yes |
+| Nuxt | native-node20/v1 | Yes |
+| NestJS | native-node20/v1 | Yes |
+| Remix | native-node20/v1 | Yes |
+| Vite | native-node20/v1 | Yes |
+| Astro | native-node20/v1 | Yes |
+| Vitepress | native-node20/v1 | Yes |
+| Angular | native-node20/v1 | Yes |
diff --git a/skills/vefaas-cli/cookbooks/manage-functions.md b/skills/vefaas-cli/cookbooks/manage-functions.md
new file mode 100644
index 00000000..00a98977
--- /dev/null
+++ b/skills/vefaas-cli/cookbooks/manage-functions.md
@@ -0,0 +1,162 @@
+# Cookbook: Manage Functions
+
+Pull, modify, and redeploy existing veFaaS functions.
+
+## Prerequisites
+
+- vefaas CLI installe
+- Valid credentials (AKSK/SSO)
+- Existing function in veFaaS console
+
+## Scenario A: Pull and Modify Function Code
+
+### Step 1: Pull Function Code
+
+```bash
+# By function name
+vefaas pull --func my-function-name
+
+# By function ID
+vefaas pull --funcId func-xxxxx
+```
+
+This creates a directory with the function code:
+```
+my-function-name/
+├── app.py (or index.js)
+├── requirements.txt (or package.json)
+├── run.sh
+└── .vefaas/
+    └── config.json
+```
+
+### Step 2: Modify Code
+
+```bash
+cd my-function-name
+# Edit your code
+```
+
+### Step 3: Redeploy
+
+```bash
+vefaas deploy
+# or with explicit function reference
+vefaas deploy --func my-function-name --yes
+```
+
+## Scenario B: Push Code to Existing Function
+
+> [!NOTE]
+> `push` only uploads code without triggering deployment. For most cases, use `deploy` instead.
+
+```bash
+# Push code only (no deployment)
+vefaas push --func my-function-name --yes
+```
+
+## Scenario C: Manage Environment Variables
+
+### List Variables
+
+```bash
+vefaas env list
+# Output:
+# > Environment Variables:
+# DATABASE_URL=postgres://...
+# API_KEY=xxx
+```
+
+### Get Single Variable
+
+```bash
+vefaas env get DATABASE_URL
+```
+
+### Set Variables
+
+```bash
+# Set single variable
+vefaas env set NEW_KEY "new-value"
+
+# Update existing variable
+vefaas env set DATABASE_URL "new-connection-string"
+```
+
+### Import from File
+
+```bash
+vefaas env import .env
+```
+
+## Scenario D: View and Update Configuration
+
+### View Current Config
+
+```bash
+vefaas config list
+
+# Output:
+# > Config Summary:
+# - Application ID: app-xxxxx
+# - Function ID: func-xxxxx
+# - Region: cn-beijing
+# - Gateway ID: gw-xxxxx
+# - System URL: https://xxx.apigateway-cn-beijing.volceapi.com/
+#
+# > Remote Function Settings:
+# - Build Command: npm run build
+# - Output Directory: dist
+# - Start Command: node dist/index.js
+# - Port: 3000
+```
+
+### Pull Config from Cloud
+
+```bash
+# By app name
+vefaas config pull --app my-app
+
+# By function name
+vefaas config pull --func my-function
+```
+
+### Update Settings
+
+```bash
+vefaas config --buildCommand "npm run build:prod" --port 8080
+```
+
+## Scenario E: Debug Issues
+
+### Enable Debug Mode
+
+```bash
+vefaas --debug deploy
+# or
+vefaas -d inspect
+```
+
+### View Debug Logs
+
+```bash
+# Logs are saved to ~/.vefaas/logs/
+ls -lt ~/.vefaas/logs/ | head -5
+
+# View latest log
+cat ~/.vefaas/logs/$(ls -t ~/.vefaas/logs/ | head -1)
+```
+
+### Common Issues
+
+**Authentication Failed:**
+```bash
+vefaas login --check
+vefaas login  # Re-authenticate
+```
+
+**Framework Not Detected:**
+```bash
+vefaas inspect  # Check detection
+vefaas deploy --buildCommand "..." --command "..." --port 8000 --yes
+```
diff --git a/skills/vefaas-cli/cookbooks/template-quickstart.md b/skills/vefaas-cli/cookbooks/template-quickstart.md
new file mode 100644
index 00000000..fb901518
--- /dev/null
+++ b/skills/vefaas-cli/cookbooks/template-quickstart.md
@@ -0,0 +1,97 @@
+# Cookbook: Template Quickstart
+
+Create and deploy a serverless application from official templates.
+
+## Prerequisites
+
+- vefaas CLI installed
+- Valid credentials (AKSK/SSO)
+
+## Scenario: Create a FastAPI Application
+
+### Step 1: Login
+
+```bash
+# Interactive login
+vefaas login
+
+# Or non-interactive
+vefaas login --accessKey YOUR_AK --secretKey YOUR_SK
+
+# Or via environment variables (recommended for CI)
+export VOLC_ACCESS_KEY_ID="YOUR_AK"
+export VOLC_SECRET_ACCESS_KEY="YOUR_SK"
+```
+
+### Step 2: Initialize from Template
+
+```bash
+# Interactive - shows template list
+vefaas init
+
+# Non-interactive - specify template name
+vefaas init --template FastAPI
+
+# With auto dependency install
+vefaas init --template FastAPI --installDeps
+```
+
+Available templates include:
+- **FastAPI** - Python web framework for APIs
+- **Express** - Node.js web framework
+- **Vitepress** - Static documentation generator
+- **Next.js** - React framework
+- **Nuxt** - Vue framework
+
+### Step 3: Deploy
+
+```bash
+cd <project-directory>
+
+# One-liner deployment
+vefaas deploy --newApp my-fastapi-app --gatewayName $(vefaas run listgateways --first) --yes
+```
+
+### Step 4: Access Your Application
+
+```bash
+vefaas domains
+# Output:
+# > Access URL: https://xxxxxxx.apigateway-cn-beijing.volceapi.com/
+```
+
+## Complete Example
+
+```bash
+# Full workflow
+vefaas login --check
+
+vefaas init --template FastAPI
+cd fastapi
+
+vefaas deploy --newApp fastapi-demo --gatewayName $(vefaas run listgateways --first) --yes
+
+vefaas domains
+```
+
+## Local Development
+
+After initialization, develop locally before redeploying:
+
+**Python (FastAPI/Django/Flask):**
+```bash
+pip install -r requirements.txt
+python main.py
+# or: uvicorn app:app --reload
+```
+
+**Node.js (Express/Next.js/Nuxt):**
+```bash
+npm install
+npm run dev
+```
+
+Then redeploy changes:
+```bash
+vefaas deploy
+```
diff --git a/skills/vefaas-cli/references/authentication.md b/skills/vefaas-cli/references/authentication.md
new file mode 100644
index 00000000..bfb35946
--- /dev/null
+++ b/skills/vefaas-cli/references/authentication.md
@@ -0,0 +1,92 @@
+# Authentication Reference
+
+## Authentication Methods
+
+### 1. Interactive Login
+
+```bash
+vefaas login
+```
+
+Prompts for:
+- Access Key ID (AK)
+- Secret Access Key (SK)
+
+Credentials are saved to `~/.vefaas/auth.json`.
+
+### 2. Non-Interactive Login
+
+```bash
+vefaas login --accessKey YOUR_AK --secretKey YOUR_SK
+
+# With STS session token (optional)
+vefaas login --accessKey YOUR_AK --secretKey YOUR_SK --sessionToken YOUR_TOKEN
+```
+
+### 3. Environment Variables (Recommended for CI/CD)
+
+```bash
+export VOLC_ACCESS_KEY_ID="YOUR_AK"
+export VOLC_SECRET_ACCESS_KEY="YOUR_SK"
+
+# Optional: STS token
+export VOLC_SESSION_TOKEN="YOUR_STS_TOKEN"
+```
+
+When env vars are set, CLI uses them automatically without requiring `vefaas login`.
+
+### 4. OAuth/OIDC Token
+
+```bash
+vefaas login --token YOUR_OAUTH_TOKEN
+```
+
+### 5. SSO Login
+
+```bash
+vefaas login --sso
+```
+
+Opens browser for SSO authentication. Useful for organizations with centralized identity management.
+
+## Credential Management
+
+### Check Current Status
+
+```bash
+vefaas login --check
+```
+
+### Logout
+
+```bash
+vefaas logout
+```
+
+Clears stored credentials from `~/.vefaas/auth.json`.
+
+## Obtaining Credentials
+
+1. Log in to [Volcengine Console](https://console.volcengine.com)
+2. Navigate to **IAM** > **Access Key Management**
+3. Create new AK/SK pair
+4. Ensure account has **veFaaSFullAccess** policy
+
+## CI/CD Configuration
+
+### GitHub Actions
+
+```yaml
+env:
+  VOLC_ACCESS_KEY_ID: ${{ secrets.VOLC_ACCESS_KEY_ID }}
+  VOLC_SECRET_ACCESS_KEY: ${{ secrets.VOLC_SECRET_ACCESS_KEY }}
+```
+
+## Troubleshooting
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `InvalidAccessKey` | Wrong AK | Verify AK in IAM console |
+| `SignatureDoesNotMatch` | Wrong SK | Re-check SK value |
+| `Request failed with status code 401` | Expired or invalid | Run `vefaas login` again |
+| `No valid credentials found` | Not logged in | Run `vefaas login` |
diff --git a/skills/vefaas-cli/references/configuration.md b/skills/vefaas-cli/references/configuration.md
new file mode 100644
index 00000000..217ba6ac
--- /dev/null
+++ b/skills/vefaas-cli/references/configuration.md
@@ -0,0 +1,120 @@
+# Configuration Reference
+
+## Config File Location
+
+After linking, config is stored in `.vefaas/config.json` in your project root.
+
+## Config File Structure
+
+```json
+{
+  "version": "1.0",
+  "function": {
+    "id": "func-xxxxx",
+    "runtime": "native-node20/v1",
+    "region": "cn-beijing",
+    "application_id": "app-xxxxx"
+  },
+  "triggers": {
+    "type": "apig",
+    "system_url": "https://xxx.apigateway-cn-beijing.volceapi.com/",
+    "id": "gw-xxxxx"
+  }
+}
+```
+
+## Field Reference
+
+| Field | Description |
+|-------|-------------|
+| `version` | Config file version (currently `1.0`) |
+| `function.id` | Function ID |
+| `function.runtime` | Runtime (e.g., `native-node20/v1`, `native-python3.12/v1`) |
+| `function.region` | Deployment region (e.g., `cn-beijing`) |
+| `function.application_id` | Application ID |
+| `triggers.type` | Trigger type (`apig` for HTTP) |
+| `triggers.system_url` | Public access URL |
+| `triggers.inner_url` | Internal VPC URL |
+| `triggers.id` | API Gateway instance ID |
+
+## Commands
+
+### View Config
+
+```bash
+vefaas config list
+```
+
+### Pull Config from Cloud
+
+```bash
+# By app name
+vefaas config pull --app my-app
+
+# By app ID
+vefaas config pull --id app-xxxxx
+
+# By function name
+vefaas config pull --func my-function
+
+# By function ID
+vefaas config pull --funcId func-xxxxx
+```
+
+### Update Settings
+
+```bash
+vefaas config --buildCommand "npm run build" --outputPath dist --command "node dist/index.js" --port 8000
+```
+
+### Available Settings
+
+| Option | Description |
+|--------|-------------|
+| `--buildCommand` | Local build command |
+| `--outputPath` | Build output directory |
+| `--command` | Remote start command |
+| `--port` | Listening port |
+| `--runtime` | Runtime override |
+
+## Configuration Priority
+
+From highest to lowest:
+
+1. **Command line flags** (`--buildCommand`, `--port`, etc.)
+2. **Cloud function config** (synced via `config pull` or `deploy`)
+3. **Local detection** (via `vefaas inspect`)
+4. **Default values**
+
+## Ignore Files
+
+### .vefaasignore
+
+Controls which files are excluded from upload. Format is similar to `.gitignore`:
+
+```
+# Local config
+*.local
+.env.local
+
+# Dependencies
+node_modules/
+__pycache__/
+.venv/
+
+# Build cache
+.next/
+dist/
+```
+
+### Default Ignore Rules
+
+These are always ignored (no config needed):
+
+| Category | Patterns |
+|----------|----------|
+| Version control | `.git/`, `.svn/`, `.hg/` |
+| Python | `.venv/`, `site-packages/`, `__pycache__/` |
+| IDE | `.idea/`, `.vscode/`, `*.swp` |
+| System | `.DS_Store`, `Thumbs.db` |
+| CLI | `.vefaas/` |
diff --git a/skills/vefaas-cli/references/environment-variables.md b/skills/vefaas-cli/references/environment-variables.md
new file mode 100644
index 00000000..9eafe264
--- /dev/null
+++ b/skills/vefaas-cli/references/environment-variables.md
@@ -0,0 +1,134 @@
+# Environment Variables Reference
+
+## Overview
+
+Environment variables are managed remotely on the function and can be accessed in code via:
+- **Node.js**: `process.env.KEY`
+- **Python**: `os.environ.get('KEY')`
+
+## Commands
+
+### List All Variables
+
+```bash
+vefaas env list
+
+# Output:
+# > Environment Variables:
+# DATABASE_URL=postgres://user:pass@host:5432/db
+# API_KEY=your-api-key
+# NODE_ENV=production
+```
+
+### Get Single Variable
+
+```bash
+vefaas env get DATABASE_URL
+# Output: postgres://user:pass@host:5432/db
+```
+
+### Set Variable
+
+```bash
+vefaas env set KEY VALUE
+
+# Examples:
+vefaas env set DATABASE_URL "postgres://user:pass@host:5432/db"
+vefaas env set API_KEY "your-api-key"
+vefaas env set NODE_ENV "production"
+```
+
+### Import from File
+
+```bash
+vefaas env import ./env.prod
+```
+
+## File Format
+
+The import command supports `.env` file format:
+
+```bash
+# Comments are ignored
+KEY=VALUE
+
+# Quoted values
+API_KEY="your-api-key"
+SECRET='single-quoted'
+
+# With export prefix
+export NODE_ENV=production
+
+# Database configuration
+PGHOST=db.volces.com
+PGDATABASE=mydb
+PGUSER=admin
+PGPASSWORD=secret123
+```
+
+Supported formats:
+- `KEY=VALUE` - Basic format
+- `KEY="VALUE"` or `KEY='VALUE'` - Quoted values
+- `export KEY=VALUE` - With export prefix
+- `# comment` - Lines starting with `#` are ignored
+
+## Usage in Code
+
+### Node.js
+
+```javascript
+const dbUrl = process.env.DATABASE_URL;
+const apiKey = process.env.API_KEY;
+
+// With default value
+const port = process.env.PORT || 3000;
+```
+
+### Python
+
+```python
+import os
+
+db_url = os.environ.get('DATABASE_URL')
+api_key = os.environ.get('API_KEY')
+
+# With default value
+port = int(os.environ.get('PORT', 8000))
+```
+
+## Common Patterns
+
+### Database Connection
+
+```bash
+vefaas env set PGHOST "db.volces.com"
+vefaas env set PGDATABASE "mydb"
+vefaas env set PGUSER "admin"
+vefaas env set PGPASSWORD "secret"
+vefaas env set PGPORT "5432"
+```
+
+### API Keys
+
+```bash
+vefaas env set API_KEY "your-api-key"
+vefaas env set JWT_SECRET "your-jwt-secret"
+```
+
+### Feature Flags
+
+```bash
+vefaas env set NODE_ENV "production"
+vefaas env set DEBUG "false"
+```
+
+## Best Practices
+
+1. **Never commit secrets** - Use `vefaas env` instead of config files
+2. **Use separate env files** - `env.dev`, `env.staging`, `env.prod`
+3. **Import before deploy** - For apps with dependencies:
+   ```bash
+   vefaas link --newApp my-app --gatewayName $(vefaas run listgateways --first) --yes
+   vefaas env import ./env.prod
+   vefaas deploy
+   ```
diff --git a/skills/vefaas-cli/references/framework-detection.md b/skills/vefaas-cli/references/framework-detection.md
new file mode 100644
index 00000000..01c91636
--- /dev/null
+++ b/skills/vefaas-cli/references/framework-detection.md
@@ -0,0 +1,137 @@
+# Framework Detection Reference
+
+## Overview
+
+vefaas automatically detects project frameworks and configures:
+- Build command
+- Output directory
+- Start command
+- Port
+- Runtime
+
+Use `vefaas inspect` to see detected settings.
+
+## Inspect Command
+
+```bash
+vefaas inspect
+
+# Output:
+# > Detected Settings:
+# > - Install Command: npm ci
+# > - Build Command: npm run build
+# > - Output Directory: .next
+# > - Start Command: node server.js
+# > - Port: 3000
+# > - Runtime: native-node20/v1
+# > - Framework: next.js
+```
+
+JSON output:
+```bash
+vefaas inspect --json
+```
+
+## Supported Frameworks
+
+### Python
+
+| Framework | Runtime | Build Command | Start Command |
+|-----------|---------|---------------|---------------|
+| FastAPI | native-python3.12/v1 | `./build.sh` | `./run.sh` |
+| Django | native-python3.12/v1 | `./build.sh` | `./run.sh` |
+| Flask | native-python3.12/v1 | `./build.sh` | `./run.sh` |
+
+### Node.js
+
+| Framework | Runtime | Build Command | Start Command |
+|-----------|---------|---------------|---------------|
+| Express | native-node20/v1 | - | `node index.js` |
+| Next.js | native-node20/v1 | `npm run build` | `node server.js` |
+| Nuxt | native-node20/v1 | `npm run build` | `node .output/server/index.mjs` |
+| NestJS | native-node20/v1 | `npm run build` | `node dist/main.js` |
+| Remix | native-node20/v1 | `npm run build` | `npm start` |
+| Vite | native-node20/v1 | `npm run build` | Static serve |
+| Astro | native-node20/v1 | `npm run build` | Depends on mode |
+
+### Static Sites
+
+| Framework | Runtime | Build Command | Start Command |
+|-----------|---------|---------------|---------------|
+| Vitepress | native-node20/v1 | `npx vitepress build` | Caddy serve |
+| Rspress | native-node20/v1 | `npm run build` | Caddy serve |
+| Create React App | native-node20/v1 | `npm run build` | Caddy serve |
+| Angular | native-node20/v1 | `ng build` | Caddy serve |
+
+Static sites use Caddy as the web server. The Caddyfile is auto-generated.
+
+## Override Detection
+
+When auto-detection doesn't match your setup:
+
+### Via Command Line
+
+```bash
+vefaas deploy \
+  --buildCommand "npm run build:prod" \
+  --outputPath dist \
+  --command "node dist/server.js" \
+  --port 8080 \
+  --yes
+```
+
+### Via Config
+
+```bash
+vefaas config \
+  --buildCommand "npm run build:prod" \
+  --outputPath dist \
+  --command "node dist/server.js" \
+  --port 8080
+```
+
+## Detection Files
+
+The CLI looks for these files to detect frameworks:
+
+| File | Indicates |
+|------|-----------|
+| `package.json` | Node.js project |
+| `requirements.txt` | Python project |
+| `pyproject.toml` | Python project |
+| `next.config.js` | Next.js |
+| `nuxt.config.ts` | Nuxt |
+| `vite.config.ts` | Vite-based |
+| `angular.json` | Angular |
+| `.vitepress/` | Vitepress |
+
+## Build Environment
+
+Current behavior:
+- **Node.js**: Build runs locally, output is packaged and uploaded
+- **Python**: Code is uploaded, dependencies installed remotely via `requirements.txt`
+
+## Troubleshooting
+
+**Framework not detected:**
+```bash
+# Check what's detected
+vefaas --debug inspect
+
+# Manually specify
+vefaas deploy --buildCommand "..." --command "..." --port 8000 --yes
+```
+
+**Wrong build command:**
+```bash
+# Override in config
+vefaas config --buildCommand "npm run build:production"
+```
+
+**Missing dependencies:**
+```bash
+# Ensure package.json or requirements.txt exists
+# For Node.js, run npm install first
+npm install
+vefaas deploy
+```
diff --git a/skills/vefaas-cli/references/troubleshooting.md b/skills/vefaas-cli/references/troubleshooting.md
new file mode 100644
index 00000000..582ee7dd
--- /dev/null
+++ b/skills/vefaas-cli/references/troubleshooting.md
@@ -0,0 +1,152 @@
+# Troubleshooting Reference
+
+## Enable Debug Mode
+
+When encountering issues, first enable debug mode with `--debug` or `-d`:
+
+```bash
+vefaas --debug deploy
+# or
+vefaas -d inspect
+```
+
+Debug mode outputs:
+- **Framework detection**: Detected framework, runtime, build command
+- **Shell execution**: Commands, working directory, exit codes
+- **Packaging**: Ignore rules, file count, package size
+- **HTTP requests/responses**: API call parameters and results
+
+## Debug Log Files
+
+Debug logs are automatically saved to files:
+
+```bash
+# Log file location
+~/.vefaas/logs/YYYYMMDD-HHMMSS.txt
+
+# View recent logs
+ls -lt ~/.vefaas/logs/ | head -5
+
+# View latest log
+cat ~/.vefaas/logs/$(ls -t ~/.vefaas/logs/ | head -1)
+```
+
+Log files contain full JSON response data (terminal shows preview only).
+
+## Common Issues
+
+### 1. Authentication Failed
+
+**Symptoms**: `InvalidAccessKey` or `SignatureDoesNotMatch` error
+
+**Steps**:
+```bash
+# Check credential status
+vefaas login --check
+
+# Re-login
+vefaas login
+```
+
+**Common causes**:
+- Incorrect AK/SK
+- Expired credentials
+- Sub-account missing `veFaaSFullAccess` policy
+
+### 2. Framework Detection Failed
+
+**Symptoms**: Incorrect build command or runtime
+
+**Steps**:
+```bash
+vefaas --debug inspect
+```
+
+**Common causes**:
+- Missing `package.json` or `requirements.txt`
+- Non-standard project structure
+
+**Solution**: Manually specify configuration:
+```bash
+vefaas deploy --buildCommand "npm run build" --outputPath dist --command "node dist/index.js" --port 3000
+```
+
+### 3. Build Failed
+
+**Symptoms**: `command exited with code X` error
+
+**Steps**:
+```bash
+# View full error with debug mode
+vefaas --debug deploy
+
+# Test build command locally
+npm run build
+```
+
+**Common causes**:
+- Dependencies not installed (run `npm install` first)
+- Node.js version incompatible
+- Missing environment variables
+
+### 4. Deploy Timeout
+
+**Symptoms**: `dependency install timeout` error
+
+**Steps**:
+```bash
+vefaas --debug deploy
+```
+
+**Common causes**:
+- Too many Python dependencies or large packages
+- Network issues causing slow downloads
+
+**Solution**: Reduce unnecessary dependencies, or pin versions in `requirements.txt`.
+
+### 5. Gateway Not Found
+
+**Symptoms**: `No running gateways found` error
+
+**Steps**:
+```bash
+vefaas run listgateways
+```
+
+**Solution**: Create an API Gateway instance in the [API Gateway console](https://console.volcengine.com/veapig).
+
+## --app vs --func
+
+| Flag | Description | Use Case |
+|------|-------------|----------|
+| `--app` | Includes web access integration and related resources | Projects created via `vefaas init` or applications in console |
+| `--func` | Direct function management | Existing functions, standalone function updates |
+
+- Use `--app` for application-level operations (includes triggers, domains)
+- Use `--func` or `--funcId` for function-level operations (code updates only)
+
+Find function name/ID in the function details page, then use `pull` and `deploy` to manage.
+
+## Submit Feedback
+
+If issues persist, collect this information:
+
+```bash
+# 1. CLI version
+vefaas --version
+
+# 2. Debug log
+vefaas --debug <command> 2>&1 | tee debug.log
+
+# 3. Latest log file
+cat ~/.vefaas/logs/$(ls -t ~/.vefaas/logs/ | head -1)
+
+# 4. Environment info
+node -v
+uname -a
+```
+
+Include:
+- Operating system version
+- Node.js version
+- Project framework type