Merge pull request #694 from TencentCloudBase/feat/improve-docs-and-star-prompt

feat(docs): 📚 improve documentation clarity and tool descriptions

Author: binggg

README-EN.md

@@ -21,6 +21,8 @@ The bridge that connects your AI IDE (Cursor, Copilot, etc.) directly to Tencent
 [![][cnb-shield]][cnb-link]
 [![][deepwiki-shield]][deepwiki-link]
 
+⭐ Like this project? Star it to get notified when new versions are released!
+
 **Found a game-changer for AI coding: one-click deploy from prompt to production**
 
 [![][share-x-shield]][share-x-link]

README.md

@@ -26,6 +26,8 @@
 [![][deepwiki-shield]][deepwiki-link]
 [![MCP Badge](https://lobehub.com/badge/mcp/tencentcloudbase-cloudbase-ai-toolkit)](https://lobehub.com/mcp/tencentcloudbase-cloudbase-ai-toolkit)
 
+⭐ 喜欢这个项目？点个 Star，新版本发布时你会收到通知～
+
 **发现了一个让 AI 编程一键上线的神器，推荐给正在用 AI 编程的朋友**
 
 [![][share-x-shield]][share-x-link]

config/source/skills/auth-web/SKILL.md

@@ -107,10 +107,11 @@ If the current task has not retrieved a real Publishable Key, omit `accessKey` i
 
 **1. Phone OTP (Recommended)**
 - Automatically use `auth-tool-cloudbase` to turn on `SMS Login` through `manageAppAuth`
-- For phone registration, send the phone number to `auth.signUp({ phone, ... })` first, then call the returned `verifyOtp({ token })`. Do not swap the order.
+- Send the phone number to `auth.signInWithOtp({ phone, ... })`, then call the returned `verifyOtp({ token })`.
+- `signInWithOtp` can automatically create a new user if the user does not exist; control this via `shouldCreateUser` parameter (default `true`).
 ```js
-const { data, error } = await auth.signUp({ phone: '13800138000' })
-const { data: loginData, error: loginError } = await data.verifyOtp({ token:'123456' })
+const { data, error } = await auth.signInWithOtp({ phone: '13800138000' })
+const { data: loginData, error: loginError } = await data.verifyOtp({ token: '123456' })
 ```
 
 **2. Email OTP**

doc/components/TutorialsGrid.tsx

@@ -1,5 +1,5 @@
 import Link from '@docusaurus/Link';
-import React, { useMemo, useState } from 'react';
+import { useMemo, useState } from 'react';
 import styles from './TutorialsGrid.module.css';
 
 interface Tutorial {
@@ -388,17 +388,6 @@ const tutorials: Tutorial[] = [
     devToolTags: ['Cursor', 'Figma'],
   },
   // 视频
-  {
-    id: 'video-vibecoding-compare-coze-cloudbase',
-    title: 'vibecoding托管平台对比 扣子 vs cloudbase',
-    description: '君黎的折腾日常',
-    category: '视频教程',
-    url: 'https://www.bilibili.com/video/BV1vGXEBrERj/',
-    type: 'video',
-    thumbnail: 'https://7463-tcb-advanced-a656fc-1257967285.tcb.qcloud.la/video-thumbnails/BV1vGXEBrERj.jpg',
-    terminalTags: ['Web'],
-    appTypeTags: ['工具/效率'],
-  },
   {
     id: 'video-figma-codebuddy-miniprogram',
     title: 'Figma + CodeBuddy + CloudBase 实战：完整开发一个微信小程序',

doc/index.mdx

@@ -20,16 +20,14 @@ AI 负责代码生成和问题修复，CloudBase 提供运行环境。两者结
 
 先选择你正在使用的 AI 开发工具，**点击下方图标进入对应安装文档**，按文档完成 MCP 安装或配置。
 
-> **注意**：这里的图标列表是安装入口，不是展示列表。请先点进去完成对应工具的接入，再继续下面的 Skills 和提示词。
+> 可点击下方图标完成对应工具的接入
 
 <IDEIconGrid />
 
 ## 第 2 步：按需安装 CloudBase AI Skill（可选）
 
 将云开发最佳实践打包成「技能包」，与 MCP 搭配使用：MCP 负责连接与权限，Skills 负责规范与直觉，让 AI 既有权又懂规矩。
 
-> **这一步不是安装 MCP。** 如果你还没完成上一步，请先点击上方图标查看对应 IDE 的 MCP 安装指引。
-
 ```bash
 npx skills add tencentcloudbase/cloudbase-skills
 ```

doc/mcp-tools.md

@@ -147,7 +147,7 @@ If the current task has not retrieved a real Publishable Key, omit `accessKey` i
 - `signInWithOtp` can automatically create a new user if the user does not exist; control this via `shouldCreateUser` parameter (default `true`).
 ```js
 const { data, error } = await auth.signInWithOtp({ phone: '13800138000' })
-const { data: loginData, error: loginError } = await data.verifyOtp({ token:'123456' })
+const { data: loginData, error: loginError } = await data.verifyOtp({ token: '123456' })
 ```
 
 **2. Email OTP**

doc/prompts/auth-web.mdx

@@ -86,6 +86,9 @@ Keep local `references/...` paths for files that ship with the current skill dir
 - Staying here after the correct implementation skill is already clear.
 - Mixing platform overview with platform-specific API shapes or SDK details.
 - Using this overview skill as a detour in an existing application where the active auth, storage, and data files are already obvious.
+- **Confusing security domains with custom domains**: These are two completely different tools for different purposes:
+  - `envDomainManagement` (action: create/delete) = Security domains (安全域名) for CORS/request source validation - used for browser upload whitelisting. Does NOT accept certificateId.
+  - `manageGateway(action="bindCustomDomain")` = Custom domains (自定义域名) for public HTTPS access with SSL certificates - requires domain and certificateId parameters.
 
 ## When to use this skill
 
@@ -131,6 +134,45 @@ Use this skill for **CloudBase platform knowledge** when you need to:
 
 # CloudBase Platform Knowledge
 
+### Domain Management Tools: Clear Distinction
+
+When working with domain-related tasks, use the correct tool based on the requirement:
+
+| Requirement | Tool | Parameters | Purpose |
+|-------------|------|------------|---------|
+| **Security Domain (安全域名)** | `envDomainManagement` | `action`, `domains` (array of host:port strings) | CORS/request source validation for browser uploads. No certificate involved. |
+| **Custom Domain (自定义域名)** | `manageGateway(action="bindCustomDomain")` | `domain` (string), `certificateId` (string) | Public HTTPS access with SSL certificate. Requires certId from SSL console. |
+| **Delete Custom Domain** | `manageGateway(action="deleteCustomDomain")` | `domain` (string) | Remove custom domain binding. |
+
+**Key indicators for choosing the right tool:**
+- Task mentions "certificate ID" or "SSL" → Use `manageGateway(action="bindCustomDomain")`
+- Task mentions "浏览器上传" or "CORS" or "安全域名" → Use `envDomainManagement`
+- Task mentions "public access" or "HTTPS" with domain → Use `manageGateway`
+
+### Recording Operation Results
+
+When a task explicitly requires recording operation steps or results to a file (e.g., `RESULT.json`):
+
+1. Perform the tool calls first to get actual results
+2. Collect all operation steps with their success/failure status
+3. Write the complete record to the specified file in the required format
+4. Include both successful operations and failed attempts with error messages
+
+Example structure for operation recording:
+```json
+{
+  "steps": [
+    {"action": "listDomains", "success": true, "message": "Found 3 domains"},
+    {"action": "bindDomain", "success": false, "message": "Certificate not found"}
+  ],
+  "summary": {
+    "totalAttempted": 2,
+    "succeeded": 1,
+    "failed": 1
+  }
+}
+```
+
 ## Storage and Hosting
 
 1. **Static Hosting vs Cloud Storage**:
@@ -229,6 +271,69 @@ Compatibility note:
 5. **Cross-Collection Operations**:
    - If user has no special requirements, operations involving cross-database collections must be implemented via cloud functions
 
+## Role Management (MCP)
+
+CloudBase MCP provides role management capabilities through the `queryPermissions` and `managePermissions` tools. These are equivalent to the CLI `tcb role` commands.
+
+**⚠️ CRITICAL: Role policies and resource permissions are two independent systems with NO automatic synchronization.**
+
+- Resource permissions (security rules) control access to specific resources (tables, collections, functions, storage)
+- Roles (identity dimension) control policy bundles and member assignments
+
+### Available Actions
+
+**Query Operations** (via `queryPermissions`):
+| Action | Description |
+|--------|-------------|
+| `listRoles` | List all roles (system and custom) |
+| `getRole` | Get detailed role information by roleId/roleIdentity/roleName |
+
+**Management Operations** (via `managePermissions`):
+| Action | Description |
+|--------|-------------|
+| `createRole` | Create a new custom role |
+| `updateRole` | Update an existing role (add/remove policies or members) |
+| `deleteRoles` | Delete one or more custom roles |
+| `addRoleMembers` | Add members to a role |
+| `removeRoleMembers` | Remove members from a role |
+| `addRolePolicies` | Add policies to a role |
+| `removeRolePolicies` | Remove policies from a role |
+
+### Usage Examples
+
+**List all roles:**
+```
+queryPermissions(action="listRoles")
+```
+
+**Get specific role details:**
+```
+queryPermissions(action="getRole", roleId="role-xxx")
+# or by identity
+queryPermissions(action="getRole", roleIdentity="dev_role")
+# or by name
+queryPermissions(action="getRole", roleName="Developer")
+```
+
+**Delete a custom role:**
+```
+managePermissions(action="deleteRoles", roleIds=["role-xxx"])
+```
+
+**Create a custom role:**
+```
+managePermissions(action="createRole", roleName="Developer", roleIdentity="developer", policies=["FunctionsAccess"], memberUids=["user-uid-1"])
+```
+
+**Update a role (add policies):**
+```
+managePermissions(action="updateRole", roleId="role-xxx", addPolicies=["StoragesAccess"])
+```
+
+> ⚠️ Note: Only custom roles can be deleted. System roles are read-only.
+
+See also: CLI equivalent commands in `cloudbase-cli/references/permission.md`
+
 3. **Cloud Function Optimization**:
    - If involving cloud functions, while ensuring security, can minimize the number of cloud functions as much as possible
    - For example: implement one cloud function for client-side requests, implement one cloud function for data initialization

doc/prompts/cloudbase-platform.mdx

@@ -77,6 +77,21 @@ Keep local `references/...` paths for files that ship with the current skill dir
 - SQL / MySQL database operations.
 - Pure resource-permission administration with no browser SDK code.
 
+### SDK Code vs MCP Tools
+
+**When to write SDK code (use this skill):**
+- The task explicitly asks to "modify code" or "use SDK"
+- The task asks to implement app/frontend logic
+- The task mentions specific SDK methods like `db.collection().add()`, `.get()`, `.update()`
+- The context shows an existing Web project with SDK initialization (e.g., `index.js` already has `cloudbase.init()`)
+
+**When to use MCP tools instead:**
+- The task asks to manage CloudBase resources (create collection, set permissions, etc.)
+- The task involves admin/management operations without writing app code
+- The task mentions tools like `writeNoSqlDatabaseContent`, `managePermissions`, etc.
+
+**Key distinction:** If the user says "使用 JS SDK 执行 XX 操作" (use JS SDK to perform XX operation) or "修改代码" (modify code), write SDK code in the project files. Do not use MCP database write tools for app-level data operations.
+
 ### Common mistakes / gotchas
 
 - Querying before the user is signed in when the collection rules require identity.