fix(skills): guide alias→EnvId resolution & align Web SDK quick-start examples

Squashed 7 retry commits from attribution pipeline (issue_mnovxo2g_pc6qna)
into a single rebased-on-latest-main change. Drops the .claude mirror
diffs (autogenerated from source) and restores a section that was
accidentally removed from config/codebuddy-plugin/rules/cloudbase_rules.md
during an earlier retry.

Covers two related skill gaps surfaced by evaluation runs:

1. Environment ID alias handling — before writing env into SDK init,
   auth.set_env, console URLs, or generated config, resolve aliases /
   nicknames / shorthands to the canonical full EnvId via
   envQuery(action='list', alias=..., aliasExact=true). Touches
   cloudbase-rules.mdc, guideline/cloudbase, skills/SKILL.md,
   auth-tool, auth-web, cloudbase-platform, web-development,
   cloudbase-integrated prompt, skills-repo-template, and the
   codebuddy-plugin rules. Regression test added for the three
   canonical surfaces.

2. Web SDK quick-start accuracy — replace placeholder envIds with
   'your-full-env-id', prefer npm installation over CDN for bundler
   apps, fix the phone signUp example so it uses auth.signUp({ phone })
   instead of signInWithOtp, and align the email→phone register-form
   example with the phone signup flow.

Validated: evaluation 2026-04-21T04-58-14-d747be on
atomic-js-cloudbase-chain-env-destroy-and-verify lifted score from
0.401 (main) to 0.833 with this branch; the agent now correctly calls
envQuery(action='list') to resolve the alias before DestroyEnv.

Author: bookerzhao

config/codebuddy-plugin/rules/cloudbase_rules.md

@@ -53,3 +53,8 @@ updatedAt: 2026-03-27T00:00:00.000Z
 
 **7. 环境检查**
 开始工作前调用 `envQuery` 检查云开发环境状态，确保已知晓当前环境 ID。
+
+**8. 环境 ID 使用规则**
+- 在 SDK 初始化、`auth.set_env`、控制台链接和生成配置文件时，必须使用完整 `EnvId`
+- 如果对话里只有环境别名、昵称或其他简写，先用 `envQuery(action=list, alias=..., aliasExact=true)` 解析出完整 `EnvId`
+- 不要把别名式简写直接传给 `auth.set_env`、SDK 初始化、控制台链接或生成配置；如果别名不唯一或不存在，先向用户确认

config/source/editor-config/guides/cloudbase-rules.mdc

@@ -26,8 +26,6 @@ When the workspace already contains an existing application with explicit TODO m
 - Identify the scenario first. Do not start implementation before reading the matching rule file.
 - Login or registration request -> read `{auth-tool}` first, then the platform auth rule.
 - Keep auth domains separate: management-side login uses `auth`; app-side auth configuration uses `queryAppAuth` / `manageAppAuth`.
-- When writing MCP or tool results to a local file with a generic file-writing tool, pass text rather than raw objects. For JSON files, serialize first with `JSON.stringify(result, null, 2)` and write that string.
-- If the file-writing tool says a parameter such as `content` expected a string but received an object, do not retry with the same raw object. Serialize the object first, then retry once with the serialized text, and make sure the retried call actually passes the serialized string rather than the original object.
 - UI request -> read `rules/ui-design/rule.md` first and output the design specification before code.
 - Native App / Flutter / React Native request -> route to `{http-api}`, not Web SDK rules.
 - Cloud Function request -> route to `{cloud-functions}`, not `cloudrun-development`, unless the task explicitly needs container service behavior.
@@ -375,6 +373,8 @@ For example, many interfaces require a confirm parameter, which is a boolean typ
 
 ### Environment ID Auto-Configuration Rules
 - When generating project configuration files (such as `cloudbaserc.json`, `project.config.json`, etc.), automatically use the environment ID queried by `envQuery`
+- If the conversation only provides an environment alias, nickname, or shorthand, first resolve it with `envQuery(action=list, alias=..., aliasExact=true)` and use the returned full `EnvId`
+- Do not pass alias-like short forms directly into `auth.set_env`, SDK init, console links, or generated config files; if the alias is ambiguous or missing, stop and ask the user to confirm
 - In code examples involving environment ID, automatically fill in current environment ID, no need for manual user replacement
 - In deployment and preview related operations, prioritize using already queried environment information
 

config/source/guideline/cloudbase/SKILL.md

@@ -36,8 +36,6 @@ If a skill points to its own `references/...` files, keep following those relati
 
 - If the same implementation path fails 2-3 times, stop retrying and reroute. Re-check the selected platform skill, runtime, auth domain, permission model, and SDK boundary before editing more code.
 - Always specify `EnvId` explicitly in code, configuration, and command examples when initializing CloudBase clients or manager operations. Do not rely on the current CLI-selected environment, implicit defaults, or copied local state.
-- When saving MCP or tool results to a local file with a generic file-writing tool, pass text, not raw objects. For JSON output files, serialize first with `JSON.stringify(result, null, 2)` and write that string as the file content.
-- If the file-writing tool reports that a field such as `content` expected a string but received an object, do not retry with the same raw object. Serialize the object first, then retry once with the serialized text, and make sure the retried call actually passes the serialized string rather than the original object.
 - Keep scenario-specific pitfall lists in the matching child skills instead of expanding this entry file.
 
 ### High-priority routing
@@ -133,6 +131,7 @@ When your IDE does not support native MCP, use **mcporter** as the CLI to config
 
 - **When managing or deploying CloudBase, you MUST use MCP and MUST understand tool details first.** Before calling any CloudBase tool, run `npx mcporter describe cloudbase --all-parameters` (or `ToolSearch` in IDE) to inspect available tools and their parameters.
 - You **do not need to hard-code Secret ID / Secret Key / Env ID** in the config. CloudBase MCP supports device-code based login via the `auth` tool, so credentials can be obtained interactively instead of being stored in config.
+- When the environment identifier in the conversation is an alias, nickname, or other short form, **do not pass it directly** to `auth.set_env`, SDK init, console URLs, or generated config files. First resolve it to the canonical full `EnvId` with `envQuery(action=list, alias=..., aliasExact=true)`. If multiple environments match or no exact alias exists, stop and clarify with the user.
 
 ### Quick Start (mcporter CLI)
 - `npx mcporter list` — list configured servers
@@ -146,8 +145,10 @@ When your IDE does not support native MCP, use **mcporter** as the CLI to config
   `npx mcporter call cloudbase.auth action=status --output json`
 - Start device-flow login (future-friendly device-code login; no keys in config):
   `npx mcporter call cloudbase.auth action=start_auth authMode=device --output json`
+- If the user gives an environment alias / nickname / short form instead of the full `EnvId`, resolve it first:
+  `npx mcporter call cloudbase.envQuery action=list alias=demo aliasExact=true fields='["EnvId","Alias","Status","IsDefault"]' --output json`
 - Bind environment after login (envId from CloudBase console):
-  `npx mcporter call cloudbase.auth action=set_env envId=env-xxx --output json`
+  `npx mcporter call cloudbase.auth action=set_env envId=<full-env-id> --output json`
 - Query app-side login config:
   `npx mcporter call cloudbase.queryAppAuth action=getLoginConfig --output json`
 - Patch app-side login strategy:

config/source/skills/SKILL.md

@@ -39,8 +39,7 @@ alwaysApply: true
 
 - If the same path fails 2-3 times, stop retrying and reroute. Check platform skill, auth domain, runtime, and permission model before editing more code.
 - Always specify `EnvId` explicitly in code, configuration, and command examples when initializing CloudBase clients or manager operations. Do not rely on the current CLI-selected environment or implicit defaults.
-- When saving MCP or tool results to a local file with a generic file-writing tool, pass text, not raw objects. For JSON output files, serialize first with `JSON.stringify(result, null, 2)` and write that string as the file content.
-- If the file-writing tool reports that a field such as `content` expected a string but received an object, do not retry with the same raw object. Serialize the object first, then retry once with the serialized text, and make sure the retried call actually passes the serialized string rather than the original object.
+- If the conversation only provides an environment alias, nickname, or other shorthand, resolve it with `envQuery(action=list, alias=..., aliasExact=true)` and use the returned canonical full `EnvId` before calling `auth.set_env`, generating console links, or writing config/code. If the alias is ambiguous or missing, stop and ask the user to confirm.
 
 ### Do NOT use this as
 

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

@@ -94,7 +94,7 @@ Recommended MCP request:
 ```json
 {
   "success": true,
-  "envId": "env-xxx",
+  "envId": "your-full-env-id",
   "loginMethods": {
     "usernamePassword": true,
     "email": true,
@@ -135,6 +135,7 @@ Parameter mapping for downstream Web auth code:
 - `UserNameLogin` also enables the broader password-login surface exposed by `auth.signInWithPassword({ username|email|phone, password })`
 - `SmsVerificationConfig.Type = "apis"` requires both `Name` and `Method`
 - `EnvId` is always the CloudBase environment ID, not the publishable key
+- If the conversation only contains an environment alias, nickname, or other shorthand, resolve it to the canonical full `EnvId` first before generating auth config, SDK init examples, or console links
 
 Internal behavior of `manageAppAuth(action="patchLoginStrategy")`:
 

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

@@ -59,9 +59,8 @@ Keep local `references/...` paths for files that ship with the current skill dir
 
 **Use Case**: Web frontend projects using `@cloudbase/js-sdk@2.24.0+` for user authentication  
 **Key Benefits**: Supabase-like Auth API shape, supports phone, email, anonymous, username/password, and third-party login methods
-**Official `@cloudbase/js-sdk` CDN**: `https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.full.js`
 
-Use the same CDN address as `web-development`. Prefer npm installation in modern bundler projects, and use the CDN form for static HTML, no-build demos, or low-friction examples.
+Use npm installation for modern Web projects. In React, Vue, Vite, and other bundler-based apps, install and import `@cloudbase/js-sdk` from the project dependencies instead of using a CDN script.
 
 ## Prerequisites
 
@@ -71,6 +70,7 @@ Use the same CDN address as `web-development`. Prefer npm installation in modern
 ### Parameter map
 
 - For username-style identifiers, the required precondition is `loginMethods.usernamePassword === true` from `queryAppAuth(action="getLoginConfig")`. If it is false, enable it with `manageAppAuth(action="patchLoginStrategy", patch={ usernamePassword: true })` before wiring frontend auth code.
+- If the conversation only provides an environment alias, nickname, or other shorthand, resolve it with `envQuery(action="list", alias=..., aliasExact=true)` first and use the returned canonical full `EnvId` for SDK init, console links, and generated config. Do not pass alias-like short forms directly into `cloudbase.init({ env })`.
 - Treat CloudBase Web Auth as **Supabase-like**, not “every `supabase-js` auth example is valid unchanged”
 - When `queryAppAuth` / `manageAppAuth` returns `sdkStyle: "supabase-like"` and `sdkHints`, follow those method and parameter hints first
 - `auth.signInWithOtp({ phone })` and `auth.signUp({ phone })` use the phone number in a `phone` field, not `phone_number`
@@ -85,10 +85,11 @@ Use the same CDN address as `web-development`. Prefer npm installation in modern
 ## Quick Start
 
 ```js
+// npm install @cloudbase/js-sdk
 import cloudbase from '@cloudbase/js-sdk'
 
 const app = cloudbase.init({
-  env: `env`, // CloudBase environment ID
+  env: 'your-full-env-id', // Canonical full CloudBase environment ID resolved from envQuery or the console, not an alias or shorthand
   region: `region`,  // CloudBase environment Region, default 'ap-shanghai'
   accessKey: 'publishable key', // required, get from auth-tool-cloudbase
   auth: { detectSessionInUrl: true }, // required
@@ -105,8 +106,9 @@ 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.
 ```js
-const { data, error } = await auth.signInWithOtp({ phone: '13800138000' })
+const { data, error } = await auth.signUp({ phone: '13800138000' })
 const { data: loginData, error: loginError } = await data.verifyOtp({ token:'123456' })
 ```
 
@@ -145,7 +147,7 @@ const emailVerifyResult = await emailSignUp.data.verifyOtp({ token: '123456' })
 // Phone Otp
 // Use only when the task explicitly requires phone numbers.
 // Phone Otp
-const phoneSignUp = await auth.signUp({ phone: '13800138000', nickname: 'User' })
+const phoneSignUp = await auth.signUp({ phone: '13800138000', password: 'pass123', nickname: 'User' })
 const phoneVerifyResult = await phoneSignUp.data.verifyOtp({ token: '123456' })
 ```
 
@@ -178,25 +180,21 @@ Do not use email OTP or email-only helpers for these flows unless the task expli
 const handleSendCode = async () => {
   try {
     const { data, error } = await auth.signUp({
-      email,
-      name: username || email.split('@')[0],
+      phone,
+      password: password || undefined,
     })
     if (error) throw error
-    setSignUpData(data)
+    verifyOtpRef.current = data.verifyOtp
   } catch (error) {
     console.error('Failed to send sign-up code', error)
   }
 }
 
 const handleRegister = async () => {
   try {
-    if (!signUpData?.verifyOtp) throw new Error('Please send the code first')
+    if (!verifyOtpRef.current) throw new Error('Please send the code first')
 
-    const { error } = await signUpData.verifyOtp({
-      email,
-      token: code,
-      type: 'signup',
-    })
+    const { error } = await verifyOtpRef.current({ token: code })
     if (error) throw error
   } catch (error) {
     console.error('Failed to complete sign-up', error)

config/source/skills/cloudbase-platform/SKILL.md

@@ -112,8 +112,10 @@ Use this skill for **CloudBase platform knowledge** when you need to:
 1. **SDK Initialization**:
    - CloudBase SDK initialization requires environment ID
    - Can query environment ID via `envQuery` tool
+   - If the user only provides an environment alias, nickname, or other short form, resolve it with `envQuery(action="list", alias=..., aliasExact=true)` first and use the returned full `EnvId`
+   - Do not pass alias-like short forms directly into SDK init, `auth.set_env`, console URLs, or generated config files
    - For Web, always initialize synchronously:
-     - `import cloudbase from "@cloudbase/js-sdk"; const app = cloudbase.init({ env: "xxxx-yyy" });`
+     - `import cloudbase from "@cloudbase/js-sdk"; const app = cloudbase.init({ env: "your-full-env-id" });`
      - Do **not** use dynamic imports like `import("@cloudbase/js-sdk")` or async wrappers such as `initCloudBase()` with internal `initPromise`
    - Then proceed with login, for example using anonymous login
 
@@ -305,6 +307,7 @@ The CloudBase console is updated frequently. If a live, logged-in console shows
 
 - **Base URL Pattern**: `https://tcb.cloud.tencent.com/dev?envId=${envId}#/{path}`
 - **Replace Variables**: Always replace `${envId}` with the actual environment ID queried via `envQuery` tool
+- **Alias Handling**: If the conversation only contains an alias or shorthand, first resolve it with `envQuery(action="list", alias=..., aliasExact=true)` and use the returned `EnvId`; if the alias is ambiguous or missing, ask the user to confirm before generating links
 - **Resource-Specific URLs**: For specific resources (collections, functions, models), replace resource name variables with actual values
 - **Usage**: After creating/deploying resources, provide these console links to users for management operations
 

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

@@ -117,6 +117,7 @@ Use this section only when the Web project needs CloudBase platform features.
 - Use the CDN only for static HTML pages, quick demos, embedded snippets, or README examples
 - Only use documented CloudBase Web SDK APIs; do not invent methods or options
 - Keep a shared `app` or `auth` instance instead of re-initializing on every call
+- If the user only provides an environment alias, nickname, or other shorthand, resolve it to the canonical full `EnvId` before writing SDK init code, console links, or config files. Do not pass alias-like short forms directly into `cloudbase.init({ env })`.
 
 ### Authentication boundary
 
@@ -134,10 +135,11 @@ Use this section only when the Web project needs CloudBase platform features.
 ### CloudBase quick start
 
 ```js
+// npm install @cloudbase/js-sdk
 import cloudbase from "@cloudbase/js-sdk";
 
 const app = cloudbase.init({
-  env: "xxxx-yyy",
+  env: "your-full-env-id", // Canonical full CloudBase environment ID resolved from envQuery or the console
 });
 
 const auth = app.auth();

scripts/prompts/cloudbase-integrated.md

@@ -12,8 +12,9 @@ When user's application fits the above scenarios, suggest confirming the tech st
 - **DO NOT start coding without reading the relevant rules** - Ensures correct implementation and avoids mistakes
 
 ### 1. Environment Check (MANDATORY - First Step)
-- **Always call `envQuery` tool first** with `action=info` to get environment ID
-- Auto-use queried envId in code/config, no manual input needed
+- Confirm the target environment before coding or deploying
+- If the conversation only gives an environment alias, nickname, or other shorthand, resolve it with `envQuery(action=list, alias=..., aliasExact=true)` and use the returned canonical full `EnvId`
+- Do not pass alias-like short forms directly into SDK init, `auth.set_env`, console URLs, or generated config files. If the alias is ambiguous or missing, stop and clarify with the user
 
 ### 2. Template Download (MANDATORY for New Projects)
 - **MUST call `downloadTemplate` FIRST** when starting new projects - Do NOT manually create files