chore(release): v1.0.43 (#1161)

Two issues caught in review of #1132 that the existing tests missed because
they constructed RuntimeContext/CliConfig directly, bypassing the credential
edge where the bug lives.

P1 — Lang dropped at credential boundary
  credential.Account had no Lang field, so AccountFromCliConfig and
  ToCliConfig silently dropped cfg.Lang. The production Factory builds
  CliConfig via acct.ToCliConfig() (factory_default.go Phase 3), which
  meant RuntimeContext.Lang() always returned "" in production and
  shortcuts/mail/mail_signature.go always fell back to zh_cn — defeating
  the whole point of persisting --lang.

  Fix: add Lang i18n.Lang to Account and copy it in both directions.

  Regression test: TestFullChain_LangSurvivesProductionPath walks the
  real path (SaveMultiAppConfig -> DefaultAccountProvider.ResolveAccount
  -> ToCliConfig) and asserts Lang survives, so any future field added
  to CliConfig forces the same audit.

P2 — priorLang ignored CurrentApp in multi-profile workspaces
  priorLang scanned all Apps and returned the first non-empty Lang. If a
  user had multiple profiles and the active one disagreed with Apps[0],
  a re-bind without --lang would silently inherit the wrong profile's
  preference.

  Fix: read multi.CurrentAppConfig("").Lang instead.

  Regression tests cover CurrentApp wins over Apps[0], single-app
  fallback, and malformed bytes.

Change-Id: If7a276605f84f398cec329c2c942b471b4c32749

.github/pull_request_template.md

@@ -9,7 +9,7 @@
 ## Test Plan
 <!-- Describe how this change was verified. -->
 - [ ] Unit tests pass
-- [ ] Manual local verification confirms the `lark xxx` command works as expected
+- [ ] Manual local verification confirms the `lark-cli <domain> <command>` flow works as expected
 
 ## Related Issues
 <!-- Link related issues. Use Closes/Fixes to close them automatically. -->

.gitignore

@@ -1,5 +1,5 @@
 # Build output
-/lark-cli
+/lark-cli*
 .cache/
 dist/
 bin/

CHANGELOG.md

@@ -2,6 +2,79 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.43] - 2026-05-28
+
+### Features
+
+- **event**: Support `note` generated event (#1159)
+- **config**: Decouple `--lang` preference from TUI display language (#1132)
+- **mail**: Add HTML lint library with Larksuite-native autofix for `lark-mail` (#1019)
+
+### Bug Fixes
+
+- **config**: Propagate `Lang` across credential boundary; respect `CurrentApp` in priorLang (#1157)
+- **config**: Allow lark-channel bind source override (#1154)
+- **im**: Clarify `messages-send` dry-run chat membership (#1150)
+- **base**: Include `log_id` in attachment media errors (#1133)
+
+### Performance
+
+- **im**: Parallelize reactions, thread_replies, and merge_forward fetches (#1146)
+
+### Documentation
+
+- **im**: Update IM skill urgent APIs (#1153)
+
+## [v1.0.42] - 2026-05-27
+
+### Features
+
+- **mail**: Add `+draft-send` shortcut for batch draft sending (#1017)
+- **im**: Enrich messages with reactions and output `update_time` (#1095)
+- **schema**: Output JSON spec envelope for all API commands (#1048)
+- **event**: Support `vc` / `note` / `minute` events (#1113)
+- **drive**: Add secure label shortcuts (#985)
+- **affordance**: Use description and command in affordance example schema (#1126)
+
+### Bug Fixes
+
+- **docs**: Remove unsupported `fetch` text format (#1109)
+
+### Refactor
+
+- **auth**: Drop duplicate top-level user fields in `status` (#1128)
+
+### Documentation
+
+- **doc**: Document block anchor URLs in `lark-doc` skill (#1120)
+- **whiteboard**: Improve SVG/Mermaid instructions (#1097)
+
+## [v1.0.41] - 2026-05-26
+
+### Features
+
+- **minutes**: Add minutes edit shortcuts (#1036)
+- **minutes**: Get minutes keywords (#1079)
+- **slides**: Support importing pptx as slides (#1068)
+- **config**: Add `keychain-downgrade` subcommand (macOS) (#1085)
+- **errors**: Add structured CLI error contract (#984)
+- **apps**: Replace `+html-publish` cwd hard-reject with credential-file scan (#1072)
+
+### Bug Fixes
+
+- **drive**: Support doubao drive inspect URL variants (#1106)
+- **skills**: Sync skills incrementally during update (#1042)
+- **apps**: Read app object from `data.app` for `+create` and `+update` (#1087)
+- **common**: Escape special chars in multipart form filenames (#1037)
+- **auth**: Remove fenced code block guidance from auth URL output hints (#1088)
+
+### Documentation
+
+- **skills**: Fix agent routing for doubao.com URLs (#1082)
+- **task**: Require `--complete=false` for pending standup summaries (#1101)
+- **base**: Document UI-only field settings (#1078)
+- **contributing**: Clarify contributor guidance (#1096)
+
 ## [v1.0.40] - 2026-05-25
 
 ### Features
@@ -860,6 +933,9 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.43]: https://github.com/larksuite/cli/releases/tag/v1.0.43
+[v1.0.42]: https://github.com/larksuite/cli/releases/tag/v1.0.42
+[v1.0.41]: https://github.com/larksuite/cli/releases/tag/v1.0.41
 [v1.0.40]: https://github.com/larksuite/cli/releases/tag/v1.0.40
 [v1.0.39]: https://github.com/larksuite/cli/releases/tag/v1.0.39
 [v1.0.38]: https://github.com/larksuite/cli/releases/tag/v1.0.38

README.md

@@ -279,6 +279,8 @@ Community contributions are welcome! If you find a bug or have feature suggestio
 
 For major changes, we recommend discussing with us first via an Issue.
 
+Before opening a PR, see [AGENTS.md](./AGENTS.md) for the local build, test, and PR checklist used by contributors and AI agents.
+
 ## License
 
 This project is licensed under the **MIT License**.

README.zh.md

@@ -280,6 +280,8 @@ lark-cli schema im.messages.delete
 
 对于较大的改动，建议先通过 Issue 与我们讨论。
 
+提交 PR 前，请先阅读 [AGENTS.md](./AGENTS.md)，其中列出了贡献者和 AI Agent 使用的本地构建、测试和 PR 检查清单。
+
 ## 许可证
 
 本项目基于 **MIT 许可证** 开源。

cmd/api/api.go

@@ -238,7 +238,11 @@ func apiRun(opts *APIOptions) error {
 
 	resp, err := ac.DoAPI(opts.Ctx, request)
 	if err != nil {
-		return output.MarkRaw(client.WrapDoAPIError(err))
+		// MarkRaw tells the dispatcher to skip enrichPermissionError so the
+		// raw API error detail (log_id, troubleshooter, permission_violations)
+		// stays on the wire — `lark-cli api` callers explicitly want the raw
+		// envelope.
+		return output.MarkRaw(err)
 	}
 	err = client.HandleResponse(resp, client.ResponseOptions{
 		OutputPath:  opts.Output,
@@ -248,9 +252,15 @@ func apiRun(opts *APIOptions) error {
 		ErrOut:      f.IOStreams.ErrOut,
 		FileIO:      f.ResolveFileIO(opts.Ctx),
 		CommandPath: opts.Cmd.CommandPath(),
+		Identity:    opts.As,
+		// Stage 1: CheckResponse emits the legacy *output.ExitError envelope.
+		// Per-domain migration in stage 2+ will route through
+		// errclass.BuildAPIError to populate identity-aware fields
+		// (PermissionError.ConsoleURL needs Brand+AppID from the client).
+		CheckError: ac.CheckResponse,
 	})
-	// MarkRaw tells root error handler to skip enrichPermissionError,
-	// preserving the original API error detail (log_id, troubleshooter, etc.).
+	// MarkRaw: see comment above on the DoAPI path. Applies equally to
+	// HandleResponse failures so the raw API error survives to the wire.
 	if err != nil {
 		return output.MarkRaw(err)
 	}
@@ -262,9 +272,12 @@ func apiDryRun(f *cmdutil.Factory, request client.RawApiRequest, config *core.Cl
 }
 
 func apiPaginate(ctx context.Context, ac *client.APIClient, request client.RawApiRequest, format output.Format, jqExpr string, out, errOut io.Writer, pagOpts client.PaginationOptions) error {
+	if pagOpts.Identity == "" {
+		pagOpts.Identity = request.As
+	}
 	// When jq is set, always aggregate all pages then filter.
 	if jqExpr != "" {
-		if err := client.PaginateWithJq(ctx, ac, request, jqExpr, out, pagOpts, client.CheckLarkResponse); err != nil {
+		if err := client.PaginateWithJq(ctx, ac, request, jqExpr, out, pagOpts, ac.CheckResponse); err != nil {
 			return output.MarkRaw(err)
 		}
 		return nil
@@ -277,9 +290,9 @@ func apiPaginate(ctx context.Context, ac *client.APIClient, request client.RawAp
 			pf.FormatPage(items)
 		}, pagOpts)
 		if err != nil {
-			return output.MarkRaw(output.ErrNetwork("API call failed: %v", err))
+			return output.MarkRaw(err)
 		}
-		if apiErr := client.CheckLarkResponse(result); apiErr != nil {
+		if apiErr := ac.CheckResponse(result, pagOpts.Identity); apiErr != nil {
 			output.FormatValue(out, result, output.FormatJSON)
 			return output.MarkRaw(apiErr)
 		}
@@ -291,9 +304,9 @@ func apiPaginate(ctx context.Context, ac *client.APIClient, request client.RawAp
 	default:
 		result, err := ac.PaginateAll(ctx, request, pagOpts)
 		if err != nil {
-			return output.MarkRaw(output.ErrNetwork("API call failed: %v", err))
+			return output.MarkRaw(err)
 		}
-		if apiErr := client.CheckLarkResponse(result); apiErr != nil {
+		if apiErr := ac.CheckResponse(result, pagOpts.Identity); apiErr != nil {
 			output.FormatValue(out, result, output.FormatJSON)
 			return output.MarkRaw(apiErr)
 		}

cmd/api/api_test.go

@@ -4,7 +4,6 @@
 package api
 
 import (
-	"errors"
 	"os"
 	"sort"
 	"strings"
@@ -13,7 +12,6 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/spf13/cobra"
 )
 
@@ -399,154 +397,6 @@ func TestNormalisePath_StripsQueryAndFragment(t *testing.T) {
 	}
 }
 
-func TestApiCmd_APIError_IsRaw(t *testing.T) {
-	f, _, stderr, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app-raw", AppSecret: "test-secret-raw", Brand: core.BrandFeishu,
-	})
-
-	// Return a permission error from the API
-	reg.Register(&httpmock.Stub{
-		URL: "/open-apis/test/perm",
-		Body: map[string]interface{}{
-			"code": 99991672,
-			"msg":  "scope not enabled for this app",
-			"error": map[string]interface{}{
-				"permission_violations": []interface{}{
-					map[string]interface{}{"subject": "calendar:calendar:readonly"},
-				},
-			},
-		},
-	})
-
-	cmd := NewCmdApi(f, nil)
-	cmd.SetArgs([]string{"GET", "/open-apis/test/perm", "--as", "bot"})
-	err := cmd.Execute()
-	if err == nil {
-		t.Fatal("expected error for permission denied API response")
-	}
-
-	// Error should be marked Raw
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T", err)
-	}
-	if !exitErr.Raw {
-		t.Error("expected API error from api command to be marked Raw")
-	}
-
-	// Note: stderr envelope output is tested at the root level (TestHandleRootError_*)
-	// since WriteErrorEnvelope is called by handleRootError, not by cobra's Execute.
-	_ = stderr
-}
-
-func TestApiCmd_APIError_PreservesOriginalMessage(t *testing.T) {
-	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app-origmsg", AppSecret: "test-secret-origmsg", Brand: core.BrandFeishu,
-	})
-
-	reg.Register(&httpmock.Stub{
-		URL: "/open-apis/test/origmsg",
-		Body: map[string]interface{}{
-			"code": 99991672,
-			"msg":  "scope not enabled for this app",
-			"error": map[string]interface{}{
-				"permission_violations": []interface{}{
-					map[string]interface{}{"subject": "im:message:readonly"},
-				},
-			},
-		},
-	})
-
-	cmd := NewCmdApi(f, nil)
-	cmd.SetArgs([]string{"GET", "/open-apis/test/origmsg", "--as", "bot"})
-	err := cmd.Execute()
-	if err == nil {
-		t.Fatal("expected error")
-	}
-
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T", err)
-	}
-	// The message should NOT have been enriched (no "App scope not enabled" replacement)
-	if strings.Contains(exitErr.Error(), "App scope not enabled") {
-		t.Error("expected original message, not enriched message")
-	}
-	// Detail should still contain the raw API error detail
-	if exitErr.Detail == nil {
-		t.Fatal("expected non-nil Detail")
-	}
-	if exitErr.Detail.Detail == nil {
-		t.Error("expected raw Detail.Detail to be preserved (not cleared by enrichment)")
-	}
-}
-
-func TestApiCmd_InvalidJSONResponse_ShowsDiagnostic(t *testing.T) {
-	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app-invalidjson", AppSecret: "test-secret-invalidjson", Brand: core.BrandFeishu,
-	})
-
-	reg.Register(&httpmock.Stub{
-		URL:         "/open-apis/test/invalidjson",
-		RawBody:     []byte{},
-		ContentType: "application/json",
-	})
-
-	cmd := NewCmdApi(f, nil)
-	cmd.SetArgs([]string{"GET", "/open-apis/test/invalidjson", "--as", "bot"})
-	err := cmd.Execute()
-	if err == nil {
-		t.Fatal("expected error")
-	}
-
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T", err)
-	}
-	if exitErr.Code != output.ExitAPI {
-		t.Fatalf("expected ExitAPI, got %d", exitErr.Code)
-	}
-	if exitErr.Detail == nil {
-		t.Fatal("expected detail on exit error")
-	}
-	if !strings.Contains(exitErr.Detail.Message, "invalid JSON response") &&
-		!strings.Contains(exitErr.Detail.Message, "empty JSON response body") {
-		t.Fatalf("expected JSON diagnostic, got %q", exitErr.Detail.Message)
-	}
-	if !strings.Contains(exitErr.Detail.Hint, "--output") {
-		t.Fatalf("expected hint to mention --output, got %q", exitErr.Detail.Hint)
-	}
-}
-
-func TestApiCmd_PageAll_APIError_IsRaw(t *testing.T) {
-	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app-rawpage", AppSecret: "test-secret-rawpage", Brand: core.BrandFeishu,
-	})
-
-	reg.Register(&httpmock.Stub{
-		URL: "/open-apis/test/rawpage",
-		Body: map[string]interface{}{
-			"code": 99991672,
-			"msg":  "scope not enabled",
-		},
-	})
-
-	cmd := NewCmdApi(f, nil)
-	cmd.SetArgs([]string{"GET", "/open-apis/test/rawpage", "--as", "bot", "--page-all"})
-	err := cmd.Execute()
-	if err == nil {
-		t.Fatal("expected error")
-	}
-
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T", err)
-	}
-	if !exitErr.Raw {
-		t.Error("expected paginated API error to be marked Raw")
-	}
-}
-
 func TestApiCmd_JqFlag_Parsing(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,

cmd/auth/login.go

@@ -16,6 +16,7 @@ import (
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/registry"
 	"github.com/larksuite/cli/shortcuts"
@@ -121,7 +122,7 @@ func authLoginRun(opts *LoginOptions) error {
 	}
 
 	// Determine UI language from saved config
-	lang := "zh"
+	var lang i18n.Lang
 	if multi, _ := core.LoadMultiAppConfig(); multi != nil {
 		if app := multi.FindApp(config.ProfileName); app != nil {
 			lang = app.Lang
@@ -177,7 +178,7 @@ func authLoginRun(opts *LoginOptions) error {
 
 	if !hasAnyOption {
 		if !opts.JSON && f.IOStreams.IsTerminal {
-			result, err := runInteractiveLogin(f.IOStreams, lang, msg, config.Brand)
+			result, err := runInteractiveLogin(f.IOStreams, lang.Base(), msg, config.Brand)
 			if err != nil {
 				return err
 			}
@@ -276,7 +277,7 @@ func authLoginRun(opts *LoginOptions) error {
 			"verification_url": authResp.VerificationUriComplete,
 			"device_code":      authResp.DeviceCode,
 			"expires_in":       authResp.ExpiresIn,
-			"hint":             fmt.Sprintf("**MUST generate QR code AND display it:** You MUST call lark-cli auth qrcode to convert verification_url into a QR code. This is a required step, do NOT skip it. Prefer PNG QR code (--output); use ASCII (--ascii) only when the user explicitly requests it.**CRITICAL: You MUST include the QR image in your response.** Generating the file alone is NOT enough—use image tags, inline images, or file attachments to display it.**Display order:** Output the URL first, then place the QR code image below the URL so the user can either scan or copy the link.**URL Output Rules:** Treat verification_url as an opaque string that cannot be modified. Do NOT URL-encode/decode or add spaces/punctuation. Prefer a fenced code block containing only the raw URL. For agent harnesses that only deliver final turn messages, make the QR code image (or URL) the final message of the turn and return control to the user; do not block on --device-code in the same turn. After the user confirms authorization in a later step, run: lark-cli auth login --device-code %s", authResp.DeviceCode),
+			"hint":             fmt.Sprintf("**MUST generate QR code AND display it:** You MUST call lark-cli auth qrcode to convert verification_url into a QR code. This is a required step, do NOT skip it. Prefer PNG QR code (--output); use ASCII (--ascii) only when the user explicitly requests it.**CRITICAL: You MUST include the QR image in your response.** Generating the file alone is NOT enough—use image tags, inline images, or file attachments to display it.**Display order:** Output the URL first, then place the QR code image below the URL.**URL Output Rules:** Treat verification_url as an opaque string that cannot be modified. Do NOT URL-encode/decode or add spaces/punctuation. For agent harnesses that only deliver final turn messages, make the QR code image (or URL) the final message of the turn and return control to the user; do not block on --device-code in the same turn. After the user confirms authorization in a later step, run: lark-cli auth login --device-code %s", authResp.DeviceCode),
 		}
 		encoder := json.NewEncoder(f.IOStreams.Out)
 		encoder.SetEscapeHTML(false)

cmd/auth/login_messages.go

@@ -3,6 +3,8 @@
 
 package auth
 
+import "github.com/larksuite/cli/internal/i18n"
+
 type loginMsg struct {
 	// Interactive UI (login_interactive.go)
 	SelectDomains   string
@@ -59,7 +61,7 @@ var loginMsgZh = &loginMsg{
 
 	OpenURL:            "在浏览器中打开以下链接进行认证:\n\n",
 	WaitingAuth:        "等待用户授权...",
-	AgentTimeoutHint:   "[AI agent] 此命令最长阻塞约 10 分钟，等待用户在浏览器内完成授权。请确保 runner 的 timeout >= 600s。若你的 harness 或 agent 工具只会把最终回复发给用户，请改用 \"lark-cli auth login --no-wait --json\" 拿到 device_code 和 verification_url，把 verification_url 作为本轮最终消息发给用户并结束本轮；等用户回复已完成授权后，再在后续步骤运行 \"lark-cli auth login --device-code <code>\" 续上轮询。**不要在同一轮里展示 URL 后立刻阻塞执行 --device-code**，也不要短 timeout 反复重试；每次重启会作废上一轮的 device code，导致用户授权链接失效。**必须生成二维码并展示**: 你必须调用 lark-cli auth qrcode 将 verification_url 转为二维码，这是必须步骤，不要跳过。优先生成 PNG 二维码（--output）；仅当用户明确要求时才使用 ASCII（--ascii）。**关键：生成后必须在回复中展示图片**，仅生成文件不算完成，须用 image 标签或内联图片等方式将图片包含在回复中。**展示顺序**: 先输出 URL，再将二维码图片置于 URL 下方完整展示，确保用户可扫码或复制链接。**URL 输出规则**: 将 verification_url 视为不可修改的 opaque string，不要做任何修改（包括 URL 编码/解码、添加空格或标点），建议用仅包含该 URL 的代码块单独输出。",
+	AgentTimeoutHint:   "[AI agent] 此命令最长阻塞约 10 分钟，等待用户在浏览器内完成授权。请确保 runner 的 timeout >= 600s。若你的 harness 或 agent 工具只会把最终回复发给用户，请改用 \"lark-cli auth login --no-wait --json\" 拿到 device_code 和 verification_url，把 verification_url 作为本轮最终消息发给用户并结束本轮；等用户回复已完成授权后，再在后续步骤运行 \"lark-cli auth login --device-code <code>\" 续上轮询。**不要在同一轮里展示 URL 后立刻阻塞执行 --device-code**，也不要短 timeout 反复重试；每次重启会作废上一轮的 device code，导致用户授权链接失效。**必须生成二维码并展示**: 你必须调用 lark-cli auth qrcode 将 verification_url 转为二维码，这是必须步骤，不要跳过。优先生成 PNG 二维码（--output）；仅当用户明确要求时才使用 ASCII（--ascii）。**关键：生成后必须在回复中展示图片**，仅生成文件不算完成，须用 image 标签或内联图片等方式将图片包含在回复中。**展示顺序**: 先输出 URL，再将二维码图片置于 URL 下方完整展示。**URL 输出规则**: 将 verification_url 视为不可修改的 opaque string，不要做任何修改（包括 URL 编码/解码、添加空格或标点）。",
 	AuthSuccess:        "已收到授权确认，正在获取用户信息并校验授权结果...",
 	LoginSuccess:       "授权成功! 用户: %s (%s)",
 	AuthorizedUser:     "当前授权账号: %s (%s)",
@@ -95,7 +97,7 @@ var loginMsgEn = &loginMsg{
 
 	OpenURL:            "Open this URL in your browser to authenticate:\n\n",
 	WaitingAuth:        "Waiting for user authorization...",
-	AgentTimeoutHint:   "[AI agent] This command blocks for up to ~10 minutes while waiting for the user to authorize in their browser. Make sure your runner's timeout is >= 600s. If your harness or agent tool only delivers final turn messages, use \"lark-cli auth login --no-wait --json\" to get device_code and verification_url, present verification_url to the user exactly as the final message of this turn, then end the turn; after the user replies that they authorized, run \"lark-cli auth login --device-code <code>\" in a later step to resume polling. **Do NOT show the URL and then immediately block on --device-code in the same turn**, and do not retry with a short timeout; each restart invalidates the previous device code and makes the earlier authorization URL useless.**MUST generate QR code AND display it:** You MUST call lark-cli auth qrcode to convert verification_url into a QR code. This is a required step, do NOT skip it. Prefer PNG QR code (--output); use ASCII (--ascii) only when the user explicitly requests it.**CRITICAL: You MUST include the QR image in your response.** Generating the file alone is NOT enough—use image tags, inline images, or file attachments to display it.**Display order:** Output the URL first, then place the QR code image below the URL so the user can either scan or copy the link.**URL Output Rules:** Treat verification_url as an opaque string that cannot be modified. Do NOT URL-encode/decode or add spaces/punctuation. Prefer a fenced code block containing only the raw URL.",
+	AgentTimeoutHint:   "[AI agent] This command blocks for up to ~10 minutes while waiting for the user to authorize in their browser. Make sure your runner's timeout is >= 600s. If your harness or agent tool only delivers final turn messages, use \"lark-cli auth login --no-wait --json\" to get device_code and verification_url, present verification_url to the user exactly as the final message of this turn, then end the turn; after the user replies that they authorized, run \"lark-cli auth login --device-code <code>\" in a later step to resume polling. **Do NOT show the URL and then immediately block on --device-code in the same turn**, and do not retry with a short timeout; each restart invalidates the previous device code and makes the earlier authorization URL useless.**MUST generate QR code AND display it:** You MUST call lark-cli auth qrcode to convert verification_url into a QR code. This is a required step, do NOT skip it. Prefer PNG QR code (--output); use ASCII (--ascii) only when the user explicitly requests it.**CRITICAL: You MUST include the QR image in your response.** Generating the file alone is NOT enough—use image tags, inline images, or file attachments to display it.**Display order:** Output the URL first, then place the QR code image below the URL.**URL Output Rules:** Treat verification_url as an opaque string that cannot be modified. Do NOT URL-encode/decode or add spaces/punctuation.",
 	AuthSuccess:        "Authorization confirmed, fetching user info and validating granted scopes...",
 	LoginSuccess:       "Authorization successful! User: %s (%s)",
 	AuthorizedUser:     "Authorized account: %s (%s)",
@@ -115,8 +117,8 @@ var loginMsgEn = &loginMsg{
 }
 
 // getLoginMsg returns the login message bundle for the given language.
-func getLoginMsg(lang string) *loginMsg {
-	if lang == "en" {
+func getLoginMsg(lang i18n.Lang) *loginMsg {
+	if lang.IsEnglish() {
 		return loginMsgEn
 	}
 	return loginMsgZh

cmd/auth/login_messages_test.go

@@ -8,6 +8,8 @@ import (
 	"reflect"
 	"strings"
 	"testing"
+
+	"github.com/larksuite/cli/internal/i18n"
 )
 
 func TestGetLoginMsg_Zh(t *testing.T) {
@@ -31,7 +33,7 @@ func TestGetLoginMsg_En(t *testing.T) {
 }
 
 func TestGetLoginMsg_DefaultsToZh(t *testing.T) {
-	for _, lang := range []string{"", "fr", "ja", "unknown"} {
+	for _, lang := range []i18n.Lang{"", "fr_fr", "ja_jp", "unknown"} {
 		msg := getLoginMsg(lang)
 		if msg != loginMsgZh {
 			t.Errorf("getLoginMsg(%q) should default to zh", lang)
@@ -61,7 +63,7 @@ func assertLoginMsgAllFieldsNonEmpty(t *testing.T, msg *loginMsg, label string)
 }
 
 func TestLoginMsg_FormatStrings(t *testing.T) {
-	for _, lang := range []string{"zh", "en"} {
+	for _, lang := range []i18n.Lang{i18n.LangZhCN, i18n.LangEnUS} {
 		msg := getLoginMsg(lang)
 
 		// LoginSuccess should contain two %s placeholders (userName, openId)
@@ -102,10 +104,10 @@ func TestLoginMsg_FormatStrings(t *testing.T) {
 // --device-code split-flow, and (c) non-streaming harnesses must end the turn
 // after presenting the URL instead of blocking in the same turn.
 func TestAgentTimeoutHint_CarriesKeyInfo(t *testing.T) {
-	for _, lang := range []string{"zh", "en"} {
+	for _, lang := range []i18n.Lang{i18n.LangZhCN, i18n.LangEnUS} {
 		hint := getLoginMsg(lang).AgentTimeoutHint
 		for _, want := range []string{"--no-wait", "--device-code", "turn"} {
-			if lang == "zh" && want == "turn" {
+			if lang == i18n.LangZhCN && want == "turn" {
 				want = "本轮"
 			}
 			if !strings.Contains(hint, want) {

cmd/auth/login_result.go

@@ -176,6 +176,11 @@ func handleLoginScopeIssue(opts *LoginOptions, msg *loginMsg, f *cmdutil.Factory
 			"granted":   issue.Summary.Granted,
 			"missing":   issue.Summary.Missing,
 		}
+		// Legacy *output.ExitError producer: this literal predates the typed
+		// error contract introduced by errs/. New code MUST NOT construct
+		// *output.ExitError directly — missing-scope signals should move to
+		// *errs.PermissionError (with MissingScopes/ConsoleURL as typed
+		// extension fields) when the login flow migrates to typed errors.
 		return &output.ExitError{
 			Code: output.ExitAuth,
 			Detail: &output.ErrDetail{

cmd/auth/login_test.go

@@ -958,7 +958,6 @@ func TestAuthLoginRun_NoWaitJSONHintIncludesRawURLGuidance(t *testing.T) {
 		"place the QR code image below the URL",
 		"opaque string",
 		"cannot be modified",
-		"Prefer a fenced code block",
 		"final message of the turn",
 		"return control to the user",
 		"do not block on --device-code in the same turn",
@@ -1073,7 +1072,6 @@ func TestAuthLoginRun_JSONDeviceAuthorizationAgentHintIncludesRawURLGuidance(t *
 		"URL 输出规则",
 		"opaque string",
 		"不要做任何修改",
-		"仅包含该 URL 的代码块",
 	} {
 		if !strings.Contains(hint, want) {
 			t.Fatalf("agent_hint missing %q, got:\n%s", want, hint)

cmd/auth/status.go

@@ -61,7 +61,6 @@ func authStatusRun(opts *StatusOptions) error {
 	diagnostics := identitydiag.Diagnose(context.Background(), f, config, opts.Verify)
 	result["identities"] = diagnostics
 	result["identity"] = effectiveIdentity(diagnostics)
-	addLegacyUserFields(result, diagnostics.User)
 	addEffectiveVerification(result, diagnostics)
 	addStatusNote(result, diagnostics)
 
@@ -86,29 +85,6 @@ func effectiveIdentity(d identitydiag.Result) string {
 	}
 }
 
-func addLegacyUserFields(result map[string]interface{}, user identitydiag.Identity) {
-	if user.OpenID == "" {
-		return
-	}
-	result["userName"] = user.UserName
-	result["userOpenId"] = user.OpenID
-	if user.TokenStatus != "" {
-		result["tokenStatus"] = user.TokenStatus
-	}
-	if user.Scope != "" {
-		result["scope"] = user.Scope
-	}
-	if user.ExpiresAt != "" {
-		result["expiresAt"] = user.ExpiresAt
-	}
-	if user.RefreshExpiresAt != "" {
-		result["refreshExpiresAt"] = user.RefreshExpiresAt
-	}
-	if user.GrantedAt != "" {
-		result["grantedAt"] = user.GrantedAt
-	}
-}
-
 func addEffectiveVerification(result map[string]interface{}, d identitydiag.Result) {
 	switch result["identity"] {
 	case identityUser:

cmd/config/bind.go

@@ -14,6 +14,7 @@ import (
 
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
@@ -37,8 +38,10 @@ type BindOptions struct {
 	// this flag because its own prompts already require human confirmation.
 	Force bool
 
-	Lang         string
-	langExplicit bool // true when --lang was explicitly passed
+	Lang         string // raw --lang (string for cobra); normalized to canonical/"" in validateBindFlags
+	langExplicit bool   // true when --lang was explicitly passed
+
+	UILang i18n.Lang // TUI display language (picker-only); intentionally separate from --lang
 
 	// Brand holds the resolved Lark product brand ("feishu" | "lark") for
 	// the account being bound. Populated after resolveAccount; TUI stages
@@ -55,7 +58,7 @@ type BindOptions struct {
 
 // NewCmdConfigBind creates the config bind subcommand.
 func NewCmdConfigBind(f *cmdutil.Factory, runF func(*BindOptions) error) *cobra.Command {
-	opts := &BindOptions{Factory: f}
+	opts := &BindOptions{Factory: f, UILang: i18n.LangZhCN}
 
 	cmd := &cobra.Command{
 		Use:   "bind",
@@ -102,7 +105,7 @@ Interactive terminal use: run with no flags to enter the TUI form.`,
 	cmd.Flags().StringVar(&opts.AppID, "app-id", "", "App ID to bind (required for OpenClaw multi-account)")
 	cmd.Flags().StringVar(&opts.Identity, "identity", "", "identity preset (bot-only|user-default); defaults to bot-only in flag mode (safer: no impersonation)")
 	cmd.Flags().BoolVar(&opts.Force, "force", false, "confirm a risky transition (currently: bot-only → user-default identity change in flag mode)")
-	cmd.Flags().StringVar(&opts.Lang, "lang", "zh", "language for interactive prompts (zh|en)")
+	cmd.Flags().StringVar(&opts.Lang, "lang", "", "language preference (e.g. zh or zh_cn)")
 	cmdutil.SetRisk(cmd, "write")
 
 	return cmd
@@ -147,7 +150,7 @@ func configBindRun(opts *BindOptions) error {
 	if err := warnIdentityEscalation(opts, existing.ConfigBytes); err != nil {
 		return err
 	}
-	applyPreferences(appConfig, opts)
+	applyPreferences(appConfig, opts, priorLang(existing.ConfigBytes))
 	noticeUserDefaultRisk(opts)
 
 	return commitBinding(opts, appConfig, existing.ConfigBytes, source, targetConfigPath)
@@ -202,16 +205,18 @@ func finalizeSource(opts *BindOptions) (string, error) {
 
 	// TUI: prompt for language before any downstream prompts. The source
 	// selection itself may still be skipped entirely if --source or the
-	// env already pinned it.
+	// env already pinned it. Picker offers 2 options (中文 / English) and
+	// drives BOTH opts.Lang (preference) and opts.UILang (TUI rendering).
 	if opts.IsTUI && !opts.langExplicit {
-		lang, err := promptLangSelection("")
+		lang, err := promptLangSelection()
 		if err != nil {
 			if err == huh.ErrUserAborted {
 				return "", output.ErrBare(1)
 			}
-			return "", err
+			return "", output.Errorf(output.ExitInternal, "internal", "language selection failed: %v", err)
 		}
-		opts.Lang = lang
+		opts.Lang = string(lang)
+		opts.UILang = lang
 	}
 
 	if explicit != "" {
@@ -245,7 +250,7 @@ func reconcileExistingBinding(opts *BindOptions, source, configPath string) (exi
 			return existingBinding{}, err
 		}
 		if action == "cancel" {
-			msg := getBindMsg(opts.Lang)
+			msg := getBindMsg(opts.UILang)
 			fmt.Fprintln(opts.Factory.IOStreams.ErrOut, msg.ConflictCancelled)
 			return existingBinding{Cancelled: true}, nil
 		}
@@ -329,7 +334,7 @@ func warnIdentityEscalation(opts *BindOptions, previousConfigBytes []byte) error
 	if !hasStrictBotLock(previousConfigBytes) {
 		return nil
 	}
-	msg := getBindMsg(opts.Lang)
+	msg := getBindMsg(opts.UILang)
 	return output.ErrWithHint(output.ExitValidation, "bind",
 		msg.IdentityEscalationMessage, msg.IdentityEscalationHint)
 }
@@ -347,14 +352,23 @@ func noticeUserDefaultRisk(opts *BindOptions) {
 	if opts.IsTUI || opts.Identity != "user-default" {
 		return
 	}
-	msg := getBindMsg(opts.Lang)
+	msg := getBindMsg(opts.UILang)
 	fmt.Fprintln(opts.Factory.IOStreams.ErrOut, "⚠️ "+msg.IdentityEscalationMessage)
 }
 
 // applyPreferences expands the chosen identity preset into the underlying
 // StrictMode + DefaultAs on the AppConfig. Always writes both fields so the
 // profile's intent survives later changes to global strict-mode settings.
-func applyPreferences(appConfig *core.AppConfig, opts *BindOptions) {
+// preferredLang resolves the language to persist: the requested value when set,
+// otherwise the prior one — so an unset --lang never clears a stored preference.
+func preferredLang(requested, prior i18n.Lang) i18n.Lang {
+	if requested != "" {
+		return requested
+	}
+	return prior
+}
+
+func applyPreferences(appConfig *core.AppConfig, opts *BindOptions, prior i18n.Lang) {
 	switch opts.Identity {
 	case "bot-only":
 		sm := core.StrictModeBot
@@ -365,9 +379,23 @@ func applyPreferences(appConfig *core.AppConfig, opts *BindOptions) {
 		appConfig.StrictMode = &sm
 		appConfig.DefaultAs = core.AsUser
 	}
-	if opts.Lang != "" {
-		appConfig.Lang = opts.Lang
+	appConfig.Lang = preferredLang(i18n.Lang(opts.Lang), prior)
+}
+
+// priorLang returns the language preference recorded in a previous config, or
+// "" if there is none / the bytes don't parse. Reads from CurrentApp (or Apps[0]
+// fallback) — scanning all apps for the first non-empty Lang would leak the
+// wrong profile's preference into a re-bind when the workspace holds multiple
+// named profiles and the active one disagrees with Apps[0].
+func priorLang(previousConfigBytes []byte) i18n.Lang {
+	var multi core.MultiAppConfig
+	if json.Unmarshal(previousConfigBytes, &multi) != nil {
+		return ""
 	}
+	if app := multi.CurrentAppConfig(""); app != nil {
+		return app.Lang
+	}
+	return ""
 }
 
 // commitBinding finalizes the bind: atomic write of the new workspace config,
@@ -393,7 +421,10 @@ func commitBinding(opts *BindOptions, appConfig *core.AppConfig, previousConfigB
 	}
 
 	replaced := previousConfigBytes != nil
-	msg := getBindMsg(opts.Lang)
+	// uiMsg renders human-facing TUI text (stderr success banner). Follows
+	// opts.UILang — zh by default; picker can flip it to en. --lang does
+	// not influence the TUI language.
+	uiMsg := getBindMsg(opts.UILang)
 	display := sourceDisplayName(source)
 
 	if replaced {
@@ -401,7 +432,11 @@ func commitBinding(opts *BindOptions, appConfig *core.AppConfig, previousConfigB
 	}
 
 	fmt.Fprintln(opts.Factory.IOStreams.ErrOut,
-		fmt.Sprintf(msg.BindSuccessHeader, display)+"\n"+msg.BindSuccessNotice)
+		fmt.Sprintf(uiMsg.BindSuccessHeader, display)+"\n"+uiMsg.BindSuccessNotice)
+
+	if opts.langExplicit && opts.Lang != "" {
+		fmt.Fprintln(opts.Factory.IOStreams.ErrOut, fmt.Sprintf(uiMsg.LangPreferenceSet, opts.Lang))
+	}
 
 	// TUI mode is a human sitting at a terminal; the BindSuccess notice on
 	// stderr is enough and a machine-readable JSON dump on stdout is just
@@ -419,12 +454,17 @@ func commitBinding(opts *BindOptions, appConfig *core.AppConfig, previousConfigB
 		"replaced":    replaced,
 		"identity":    opts.Identity,
 	}
-	brand := brandDisplay(string(appConfig.Brand), opts.Lang)
+	// JSON "message" follows the effective preference on disk (appConfig.Lang),
+	// not the raw --lang value: when --lang is omitted on re-bind, preferredLang
+	// has already inherited the prior preference into appConfig.Lang, and the
+	// message should respect that inherited choice. stderr above follows UILang.
+	prefMsg := getBindMsg(appConfig.Lang)
+	brand := brandDisplay(string(appConfig.Brand), appConfig.Lang)
 	switch opts.Identity {
 	case "bot-only":
-		envelope["message"] = fmt.Sprintf(msg.MessageBotOnly, appConfig.AppId, display, brand)
+		envelope["message"] = fmt.Sprintf(prefMsg.MessageBotOnly, appConfig.AppId, display, brand)
 	case "user-default":
-		envelope["message"] = fmt.Sprintf(msg.MessageUserDefault, appConfig.AppId, display, display)
+		envelope["message"] = fmt.Sprintf(prefMsg.MessageUserDefault, appConfig.AppId, display, display)
 	}
 
 	resultJSON, _ := json.Marshal(envelope)
@@ -461,7 +501,7 @@ func cleanupKeychainFromData(kc keychain.KeychainAccess, data []byte, keep *core
 
 // tuiSelectSource prompts user to choose bind source.
 func tuiSelectSource(opts *BindOptions) (string, error) {
-	msg := getBindMsg(opts.Lang)
+	msg := getBindMsg(opts.UILang)
 	var source string
 
 	// Pre-select based on detected env signals
@@ -486,7 +526,7 @@ func tuiSelectSource(opts *BindOptions) (string, error) {
 		huh.NewGroup(
 			huh.NewSelect[string]().
 				Title(msg.SelectSource).
-				Description(fmt.Sprintf(msg.SelectSourceDesc, brandDisplay(opts.Brand, opts.Lang))).
+				Description(fmt.Sprintf(msg.SelectSourceDesc, brandDisplay(opts.Brand, opts.UILang))).
 				Options(
 					huh.NewOption(fmt.Sprintf(msg.SourceOpenClaw, openclawPath), "openclaw"),
 					huh.NewOption(fmt.Sprintf(msg.SourceHermes, hermesEnvPath), "hermes"),
@@ -508,7 +548,7 @@ func tuiSelectSource(opts *BindOptions) (string, error) {
 // tuiSelectApp prompts the user to choose from multiple account candidates.
 // Invoked only via selectCandidate's tuiPrompt callback, and only in TUI mode.
 func tuiSelectApp(opts *BindOptions, source string, candidates []Candidate) (*Candidate, error) {
-	msg := getBindMsg(opts.Lang)
+	msg := getBindMsg(opts.UILang)
 	options := make([]huh.Option[int], 0, len(candidates))
 	for i, c := range candidates {
 		label := c.AppID
@@ -522,7 +562,7 @@ func tuiSelectApp(opts *BindOptions, source string, candidates []Candidate) (*Ca
 	form := huh.NewForm(
 		huh.NewGroup(
 			huh.NewSelect[int]().
-				Title(fmt.Sprintf(msg.SelectAccount, sourceDisplayName(source), brandDisplay(opts.Brand, opts.Lang))).
+				Title(fmt.Sprintf(msg.SelectAccount, sourceDisplayName(source), brandDisplay(opts.Brand, opts.UILang))).
 				Options(options...).
 				Value(&selected),
 		),
@@ -539,7 +579,7 @@ func tuiSelectApp(opts *BindOptions, source string, candidates []Candidate) (*Ca
 
 // tuiConflictPrompt shows existing binding and asks user to Force or Cancel.
 func tuiConflictPrompt(opts *BindOptions, source, configPath string) (string, error) {
-	msg := getBindMsg(opts.Lang)
+	msg := getBindMsg(opts.UILang)
 
 	// Build existing binding summary
 	existingSummary := fmt.Sprintf(msg.ConflictDesc, source, "?", "?", configPath)
@@ -591,6 +631,11 @@ func validateBindFlags(opts *BindOptions) error {
 			return output.ErrValidation("invalid --identity %q; valid values: bot-only, user-default", opts.Identity)
 		}
 	}
+	lang, err := cmdutil.ParseLangFlag(opts.Lang)
+	if err != nil {
+		return err
+	}
+	opts.Lang = string(lang)
 	return nil
 }
 
@@ -606,8 +651,8 @@ func validateBindFlags(opts *BindOptions) error {
 // DescriptionFunc approach breaks here because a longer description on
 // hover pushes options out of the field's initial viewport.
 func tuiSelectIdentity(opts *BindOptions) (string, error) {
-	msg := getBindMsg(opts.Lang)
-	brand := brandDisplay(opts.Brand, opts.Lang)
+	msg := getBindMsg(opts.UILang)
+	brand := brandDisplay(opts.Brand, opts.UILang)
 	botLabel := msg.IdentityBotOnly + "\n" + indent(fmt.Sprintf(msg.IdentityBotOnlyDesc, brand))
 	userLabel := msg.IdentityUserDefault + "\n" + indent(fmt.Sprintf(msg.IdentityUserDefaultDesc, brand, brand))
 	var value string

cmd/config/bind_messages.go

@@ -3,6 +3,8 @@
 
 package config
 
+import "github.com/larksuite/cli/internal/i18n"
+
 // bindMsg holds all TUI text for config bind, supporting zh/en via --lang.
 //
 // Brand-aware strings use a %s slot where the UI-friendly product name
@@ -84,6 +86,11 @@ type bindMsg struct {
 	// require in-flow human confirmation.
 	IdentityEscalationMessage string
 	IdentityEscalationHint    string
+
+	// LangPreferenceSet is printed to stderr after a successful bind when the
+	// user explicitly passed --lang. Format: language code. Not printed when
+	// --lang was not explicit (i.e., the cobra default zh stayed in effect).
+	LangPreferenceSet string
 }
 
 var bindMsgZh = &bindMsg{
@@ -116,6 +123,8 @@ var bindMsgZh = &bindMsg{
 
 	IdentityEscalationMessage: "你正在从应用身份切换到用户身份 —— 切换后 AI 将以你的名义在飞书中执行所有操作（读写文档、搜索消息、修改日程等）。⚠️ 请勿将此机器人分享给他人或拉入群聊中使用，以免泄露你的飞书数据。",
 	IdentityEscalationHint:    "若用户确认切换，附加 --force 重新运行：`lark-cli config bind --identity user-default --force`",
+
+	LangPreferenceSet: "语言偏好已设置：%s",
 }
 
 var bindMsgEn = &bindMsg{
@@ -150,10 +159,13 @@ var bindMsgEn = &bindMsg{
 
 	IdentityEscalationMessage: "you are switching from bot-only to user-default — the AI will then act under your Feishu identity for all operations (docs, messages, calendar, etc.). ⚠️ Don't share this bot with others or add it to group chats. It has access to your personal Feishu data.",
 	IdentityEscalationHint:    "if the user confirms the switch, re-run with --force: `lark-cli config bind --identity user-default --force`",
+
+	LangPreferenceSet: "Language preference set to: %s",
 }
 
-func getBindMsg(lang string) *bindMsg {
-	if lang == "en" {
+// getBindMsg picks the zh/en TUI bundle; non-English falls back to zh.
+func getBindMsg(lang i18n.Lang) *bindMsg {
+	if lang.IsEnglish() {
 		return bindMsgEn
 	}
 	return bindMsgZh
@@ -164,11 +176,11 @@ func getBindMsg(lang string) *bindMsg {
 // "feishu" (or empty / unknown) maps to "飞书" in zh and "Feishu" in en —
 // this is the safe default when the brand hasn't been resolved yet (for
 // example, on the pre-binding source-selection screen).
-func brandDisplay(brand, lang string) string {
+func brandDisplay(brand string, lang i18n.Lang) string {
 	if brand == "lark" || brand == "Lark" || brand == "LARK" {
 		return "Lark"
 	}
-	if lang == "en" {
+	if lang.IsEnglish() {
 		return "Feishu"
 	}
 	return "飞书"

cmd/config/bind_test.go

@@ -13,30 +13,46 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/output"
 )
 
-// assertExitError checks the full structured error in one assertion.
+// assertExitError checks the full structured error in one assertion. It
+// accepts both *output.ExitError (used by output.ErrWithHint) and the
+// typed validation error — they normalize to the same wantDetail fields.
 func assertExitError(t *testing.T, err error, wantCode int, wantDetail output.ErrDetail) {
 	t.Helper()
 	if err == nil {
 		t.Fatal("expected error, got nil")
 	}
 	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("error type = %T, want *output.ExitError; error = %v", err, err)
+	if errors.As(err, &exitErr) {
+		if exitErr.Code != wantCode {
+			t.Errorf("exit code = %d, want %d", exitErr.Code, wantCode)
+		}
+		if exitErr.Detail == nil {
+			t.Fatal("expected non-nil error detail")
+		}
+		if !reflect.DeepEqual(*exitErr.Detail, wantDetail) {
+			t.Errorf("error detail mismatch:\n  got:  %+v\n  want: %+v", *exitErr.Detail, wantDetail)
+		}
+		return
 	}
-	if exitErr.Code != wantCode {
-		t.Errorf("exit code = %d, want %d", exitErr.Code, wantCode)
-	}
-	if exitErr.Detail == nil {
-		t.Fatal("expected non-nil error detail")
-	}
-	if !reflect.DeepEqual(*exitErr.Detail, wantDetail) {
-		t.Errorf("error detail mismatch:\n  got:  %+v\n  want: %+v", *exitErr.Detail, wantDetail)
+	var ve *errs.ValidationError
+	if errors.As(err, &ve) {
+		if got := output.ExitCodeOf(err); got != wantCode {
+			t.Errorf("exit code = %d, want %d", got, wantCode)
+		}
+		gotDetail := output.ErrDetail{Type: string(ve.Category), Message: ve.Message, Hint: ve.Hint}
+		if !reflect.DeepEqual(gotDetail, wantDetail) {
+			t.Errorf("validation error mismatch:\n  got:  %+v\n  want: %+v", gotDetail, wantDetail)
+		}
+		return
 	}
+	t.Fatalf("error type = %T, want *output.ExitError or *errs.ValidationError; error = %v", err, err)
 }
 
 // assertEnvelope decodes stdout and checks it matches want exactly — every key
@@ -105,14 +121,229 @@ func TestConfigBindCmd_LangDefault(t *testing.T) {
 	if err := cmd.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	if gotOpts.Lang != "zh" {
-		t.Errorf("Lang = %q, want default %q", gotOpts.Lang, "zh")
+	if gotOpts.Lang != "" {
+		t.Errorf("Lang = %q, want default %q (unset)", gotOpts.Lang, "")
 	}
 	if gotOpts.langExplicit {
 		t.Error("expected langExplicit=false when --lang not passed")
 	}
 }
 
+// TestConfigBindRun_InvalidLang verifies a non-empty --lang is strictly
+// validated: wrong case, typos, and removed codes all exit with
+// ExitValidation (code 2) and a message identifying the offending value.
+// (Empty is not invalid — see TestConfigBindRun_EmptyLangIsNoOp.)
+func TestConfigBindRun_InvalidLang(t *testing.T) {
+	saveWorkspace(t)
+	configDir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", configDir)
+	hermesHome := t.TempDir()
+	t.Setenv("HERMES_HOME", hermesHome)
+	if err := os.WriteFile(filepath.Join(hermesHome, ".env"), []byte("FEISHU_APP_ID=cli_abc\nFEISHU_APP_SECRET=secret\n"), 0600); err != nil {
+		t.Fatalf("write .env: %v", err)
+	}
+
+	cases := []struct {
+		name string
+		lang string
+	}{
+		{"wrong case ZH", "ZH"},
+		{"typo frr", "frr"},
+		{"removed code ar", "ar"},
+		{"unknown xx", "xx"},
+		{"hyphen form zh-CN", "zh-CN"},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			f, _, _, _ := cmdutil.TestFactory(t, nil)
+			err := configBindRun(&BindOptions{
+				Factory:      f,
+				Source:       "hermes",
+				Lang:         tc.lang,
+				langExplicit: true,
+			})
+			if err == nil {
+				t.Fatalf("expected validation error for --lang %q, got nil", tc.lang)
+			}
+			exitErr, ok := err.(*output.ExitError)
+			if !ok {
+				t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+			}
+			if exitErr.Code != output.ExitValidation {
+				t.Errorf("exit code = %d, want %d (validation)", exitErr.Code, output.ExitValidation)
+			}
+			if !strings.Contains(exitErr.Error(), "invalid --lang") {
+				t.Errorf("error message %q does not contain 'invalid --lang'", exitErr.Error())
+			}
+		})
+	}
+}
+
+// TestConfigBindRun_EmptyLangIsNoOp verifies that an empty --lang (omitted or
+// explicit "") is unset: it neither errors nor persists a language, while a
+// non-empty short code or Feishu locale both canonicalize to the same locale.
+func TestConfigBindRun_EmptyLangIsNoOp(t *testing.T) {
+	cases := []struct {
+		name     string
+		lang     string
+		explicit bool
+		wantLang i18n.Lang
+	}{
+		{"omitted", "", false, ""},
+		{"explicit empty", "", true, ""},
+		{"short code", "ja", true, i18n.LangJaJP},
+		{"feishu locale", "ja_jp", true, i18n.LangJaJP},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			saveWorkspace(t)
+			t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+			hermesHome := t.TempDir()
+			t.Setenv("HERMES_HOME", hermesHome)
+			if err := os.WriteFile(filepath.Join(hermesHome, ".env"), []byte("FEISHU_APP_ID=cli_abc\nFEISHU_APP_SECRET=secret\n"), 0600); err != nil {
+				t.Fatalf("write .env: %v", err)
+			}
+
+			f, _, _, _ := cmdutil.TestFactory(t, nil)
+			if err := configBindRun(&BindOptions{
+				Factory:      f,
+				Source:       "hermes",
+				Lang:         tc.lang,
+				langExplicit: tc.explicit,
+			}); err != nil {
+				t.Fatalf("configBindRun(--lang %q) = %v, want nil", tc.lang, err)
+			}
+
+			multi, err := core.LoadMultiAppConfig()
+			if err != nil {
+				t.Fatalf("LoadMultiAppConfig: %v", err)
+			}
+			app := multi.CurrentAppConfig("")
+			if app == nil {
+				t.Fatal("no app persisted")
+			}
+			if app.Lang != tc.wantLang {
+				t.Errorf("persisted Lang = %q, want %q", app.Lang, tc.wantLang)
+			}
+		})
+	}
+}
+
+// TestConfigBindRun_OmitLangPreservesPrior guards against a re-bind without
+// --lang silently dropping a previously stored preference (appConfig is rebuilt
+// fresh, so commitBinding must inherit the prior Lang).
+func TestConfigBindRun_OmitLangPreservesPrior(t *testing.T) {
+	saveWorkspace(t)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	hermesHome := t.TempDir()
+	t.Setenv("HERMES_HOME", hermesHome)
+	if err := os.WriteFile(filepath.Join(hermesHome, ".env"), []byte("FEISHU_APP_ID=cli_abc\nFEISHU_APP_SECRET=secret\n"), 0600); err != nil {
+		t.Fatalf("write .env: %v", err)
+	}
+
+	f1, _, _, _ := cmdutil.TestFactory(t, nil)
+	if err := configBindRun(&BindOptions{Factory: f1, Source: "hermes", Lang: "ja", langExplicit: true}); err != nil {
+		t.Fatalf("first bind (--lang ja): %v", err)
+	}
+	f2, _, _, _ := cmdutil.TestFactory(t, nil)
+	if err := configBindRun(&BindOptions{Factory: f2, Source: "hermes", Lang: "", langExplicit: false}); err != nil {
+		t.Fatalf("re-bind (no --lang): %v", err)
+	}
+
+	multi, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatalf("LoadMultiAppConfig: %v", err)
+	}
+	if app := multi.CurrentAppConfig(""); app == nil || app.Lang != i18n.LangJaJP {
+		t.Errorf("Lang after re-bind = %v, want %q (preserved)", app, i18n.LangJaJP)
+	}
+}
+
+// TestPriorLang_RespectsCurrentApp guards against priorLang scanning all apps
+// and silently returning a non-current profile's Lang. In a multi-profile
+// workspace (set up via `profile add` before a re-bind), the active profile's
+// Lang must win over a sibling profile that happens to sit earlier in the slice.
+func TestPriorLang_RespectsCurrentApp(t *testing.T) {
+	multi := core.MultiAppConfig{
+		CurrentApp: "active",
+		Apps: []core.AppConfig{
+			{Name: "stale", AppId: "cli_stale", Lang: i18n.LangJaJP},
+			{Name: "active", AppId: "cli_active", Lang: i18n.LangEnUS},
+		},
+	}
+	bytes, err := json.Marshal(multi)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	if got := priorLang(bytes); got != i18n.LangEnUS {
+		t.Errorf("priorLang = %q, want %q (must follow CurrentApp, not Apps[0])", got, i18n.LangEnUS)
+	}
+}
+
+// TestPriorLang_FallsBackToFirstAppWhenCurrentUnset covers the legacy
+// single-app shape (no CurrentApp): CurrentAppConfig falls back to Apps[0],
+// so a bind-written config (which always has exactly one app and no
+// CurrentApp field) still inherits its Lang.
+func TestPriorLang_FallsBackToFirstAppWhenCurrentUnset(t *testing.T) {
+	multi := core.MultiAppConfig{
+		Apps: []core.AppConfig{
+			{AppId: "cli_only", Lang: i18n.LangJaJP},
+		},
+	}
+	bytes, err := json.Marshal(multi)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	if got := priorLang(bytes); got != i18n.LangJaJP {
+		t.Errorf("priorLang = %q, want %q", got, i18n.LangJaJP)
+	}
+}
+
+// TestPriorLang_MalformedReturnsEmpty exercises the unparseable-bytes branch.
+func TestPriorLang_MalformedReturnsEmpty(t *testing.T) {
+	if got := priorLang([]byte("not json")); got != "" {
+		t.Errorf("priorLang(malformed) = %q, want \"\"", got)
+	}
+}
+
+// TestConfigBindRun_EnvelopeMessageFollowsInheritedLang guards the JSON envelope
+// "message" field against regressing to opts.Lang: when --lang is omitted on
+// re-bind, the inherited preference (appConfig.Lang) must drive the message
+// language and the embedded brand display — otherwise an AI agent that set
+// English on first bind sees Chinese in every subsequent re-bind envelope.
+func TestConfigBindRun_EnvelopeMessageFollowsInheritedLang(t *testing.T) {
+	saveWorkspace(t)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	hermesHome := t.TempDir()
+	t.Setenv("HERMES_HOME", hermesHome)
+	if err := os.WriteFile(filepath.Join(hermesHome, ".env"), []byte("FEISHU_APP_ID=cli_abc\nFEISHU_APP_SECRET=secret\n"), 0600); err != nil {
+		t.Fatalf("write .env: %v", err)
+	}
+
+	f1, _, _, _ := cmdutil.TestFactory(t, nil)
+	if err := configBindRun(&BindOptions{Factory: f1, Source: "hermes", Lang: "en", langExplicit: true}); err != nil {
+		t.Fatalf("first bind (--lang en): %v", err)
+	}
+
+	f2, stdout, _, _ := cmdutil.TestFactory(t, nil)
+	if err := configBindRun(&BindOptions{Factory: f2, Source: "hermes", Lang: "", langExplicit: false}); err != nil {
+		t.Fatalf("re-bind (no --lang): %v", err)
+	}
+
+	envelope := map[string]any{}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("invalid JSON output: %v", err)
+	}
+	msg, _ := envelope["message"].(string)
+	enMsg := getBindMsg(i18n.LangEnUS)
+	wantMsg := fmt.Sprintf(enMsg.MessageBotOnly, "cli_abc", "Hermes", brandDisplay("feishu", i18n.LangEnUS))
+	if msg != wantMsg {
+		t.Errorf("envelope.message = %q,\nwant %q (must follow inherited appConfig.Lang=en_us, not raw opts.Lang)", msg, wantMsg)
+	}
+}
+
 // ── Run function tests (aligned with TestConfigShowRun pattern) ──
 
 func TestConfigBindRun_InvalidSource(t *testing.T) {
@@ -595,8 +826,10 @@ func TestConfigShowRun_AgentWorkspaceNotBound(t *testing.T) {
 	if !errors.As(err, &cfgErr) {
 		t.Fatalf("error type = %T, want *core.ConfigError", err)
 	}
-	if cfgErr.Code != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", cfgErr.Code, output.ExitValidation)
+	// Config errors share ExitAuth (3); the workspace is detected but no
+	// binding exists yet, which is a config error.
+	if cfgErr.Code != output.ExitAuth {
+		t.Errorf("exit code = %d, want %d (config category → ExitAuth)", cfgErr.Code, output.ExitAuth)
 	}
 	if cfgErr.Type != "openclaw" {
 		t.Errorf("type = %q, want %q", cfgErr.Type, "openclaw")
@@ -1457,10 +1690,14 @@ func TestGetBindMsg_En(t *testing.T) {
 	}
 }
 
-func TestGetBindMsg_UnknownLang_DefaultsToZh(t *testing.T) {
-	msg := getBindMsg("fr")
-	if want := "你想在哪个 Agent 中使用 lark-cli?"; msg.SelectSource != want {
-		t.Errorf("fr (default) SelectSource = %q, want %q", msg.SelectSource, want)
+func TestGetBindMsg_NonEnLang_FallsBackToZh(t *testing.T) {
+	// Only zh and en TUI bundles exist; any non-English language (canonical
+	// locale, short code, or unrecognized value) falls back to zh.
+	for _, lang := range []i18n.Lang{"fr_fr", "ja_jp", "ko", "unknown", ""} {
+		msg := getBindMsg(lang)
+		if want := "你想在哪个 Agent 中使用 lark-cli?"; msg.SelectSource != want {
+			t.Errorf("getBindMsg(%q) SelectSource = %q, want %q (zh fallback)", lang, msg.SelectSource, want)
+		}
 	}
 }
 
@@ -1623,3 +1860,36 @@ func TestHasStrictBotLock(t *testing.T) {
 		})
 	}
 }
+
+// TestConfigBindRun_LangExplicit_PrintsConfirmation covers the flag-mode
+// confirmation line: when --lang is explicit, bind prints "language preference
+// set" to stderr (rendered in the TUI language, embedding the preference value).
+func TestConfigBindRun_LangExplicit_PrintsConfirmation(t *testing.T) {
+	saveWorkspace(t)
+	configDir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", configDir)
+
+	hermesHome := t.TempDir()
+	t.Setenv("HERMES_HOME", hermesHome)
+	if err := os.WriteFile(filepath.Join(hermesHome, ".env"), []byte("FEISHU_APP_ID=cli_abc\nFEISHU_APP_SECRET=secret\n"), 0600); err != nil {
+		t.Fatalf("write .env: %v", err)
+	}
+
+	f, _, stderr, _ := cmdutil.TestFactory(t, nil)
+	err := configBindRun(&BindOptions{
+		Factory:      f,
+		Source:       "hermes",
+		Identity:     "bot-only",
+		Lang:         "en",
+		langExplicit: true,
+	})
+	if err != nil {
+		t.Fatalf("expected success, got error: %v", err)
+	}
+	// The short --lang en is canonicalized to en_us before the confirmation
+	// echoes it back; the TUI language stays zh (flag mode, no picker).
+	want := fmt.Sprintf(getBindMsg(i18n.LangZhCN).LangPreferenceSet, "en_us")
+	if got := stderr.String(); !strings.Contains(got, want) {
+		t.Errorf("stderr = %q, want it to contain confirmation %q", got, want)
+	}
+}

cmd/config/binder.go

@@ -389,10 +389,12 @@ func resolveHermesEnvPath() string {
 }
 
 // resolveLarkChannelConfigPath returns the path to lark-channel-bridge's
-// config.json. Mirrors the bridge's src/config/paths.ts which hardcodes
-// ~/.lark-channel/config.json with no env override — multi-instance is not
-// a supported scenario today.
+// source config. LARK_CHANNEL_CONFIG lets a host point bind at a projected
+// single-account config without changing lark-cli's target config directory.
 func resolveLarkChannelConfigPath() string {
+	if p := os.Getenv("LARK_CHANNEL_CONFIG"); strings.TrimSpace(p) != "" {
+		return expandHome(p)
+	}
 	home, err := vfs.UserHomeDir()
 	if err != nil || home == "" {
 		fmt.Fprintf(os.Stderr, "warning: unable to determine home directory: %v\n", err)

cmd/config/binder_test.go

@@ -4,6 +4,7 @@
 package config
 
 import (
+	"path/filepath"
 	"reflect"
 	"testing"
 
@@ -173,3 +174,27 @@ func TestSelectCandidate_AppIDFlag_WinsOverTUI(t *testing.T) {
 	}
 	assertCandidate(t, got, Candidate{AppID: "cli_b"})
 }
+
+func TestResolveLarkChannelConfigPath_Default(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("LARK_CHANNEL_CONFIG", "")
+
+	got := resolveLarkChannelConfigPath()
+	want := filepath.Join(home, ".lark-channel", "config.json")
+	if got != want {
+		t.Fatalf("resolveLarkChannelConfigPath() = %q, want %q", got, want)
+	}
+}
+
+func TestResolveLarkChannelConfigPath_EnvOverride(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("LARK_CHANNEL_CONFIG", "~/bridge/projection.json")
+
+	got := resolveLarkChannelConfigPath()
+	want := filepath.Join(home, "bridge", "projection.json")
+	if got != want {
+		t.Fatalf("resolveLarkChannelConfigPath() = %q, want %q", got, want)
+	}
+}

cmd/config/config.go

@@ -33,6 +33,7 @@ func NewCmdConfig(f *cmdutil.Factory) *cobra.Command {
 	cmd.AddCommand(NewCmdConfigStrictMode(f))
 	cmd.AddCommand(NewCmdConfigPolicy(f))
 	cmd.AddCommand(NewCmdConfigPlugins(f))
+	cmd.AddCommand(NewCmdConfigKeychainDowngrade(f))
 	return cmd
 }
 

cmd/config/config_test.go

@@ -16,6 +16,7 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/credential"
+	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/output"
 )
@@ -95,8 +96,9 @@ func TestConfigShowRun_NotConfiguredReturnsStructuredError(t *testing.T) {
 	if !errors.As(err, &cfgErr) {
 		t.Fatalf("error type = %T, want *core.ConfigError", err)
 	}
-	if cfgErr.Code != output.ExitValidation {
-		t.Fatalf("exit code = %d, want %d", cfgErr.Code, output.ExitValidation)
+	// Config errors share ExitAuth (3), not ExitValidation.
+	if cfgErr.Code != output.ExitAuth {
+		t.Fatalf("exit code = %d, want %d (config category → ExitAuth)", cfgErr.Code, output.ExitAuth)
 	}
 	if cfgErr.Type != "config" || cfgErr.Message != "not configured" {
 		t.Fatalf("detail = %+v, want config/not configured", cfgErr)
@@ -150,8 +152,9 @@ func TestConfigInitCmd_LangFlag(t *testing.T) {
 	if err := cmd.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	if gotOpts.Lang != "en" {
-		t.Errorf("expected Lang en, got %s", gotOpts.Lang)
+	// --lang en is canonicalized to en_us in RunE before runF captures opts.
+	if gotOpts.Lang != string(i18n.LangEnUS) {
+		t.Errorf("expected Lang en_us, got %s", gotOpts.Lang)
 	}
 	if !gotOpts.langExplicit {
 		t.Error("expected langExplicit=true when --lang is passed")
@@ -172,14 +175,82 @@ func TestConfigInitCmd_LangDefault(t *testing.T) {
 	if err := cmd.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	if gotOpts.Lang != "zh" {
-		t.Errorf("expected default Lang zh, got %s", gotOpts.Lang)
+	if gotOpts.Lang != "" {
+		t.Errorf("expected default Lang to be unset (\"\"), got %q", gotOpts.Lang)
 	}
 	if gotOpts.langExplicit {
 		t.Error("expected langExplicit=false when --lang is not passed")
 	}
 }
 
+// TestSaveInitConfig_OmitLangPreservesPrior guards the single-app replace path:
+// re-running init without --lang must inherit the prior preference, not clear it.
+func TestSaveInitConfig_OmitLangPreservesPrior(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+
+	existing := &core.MultiAppConfig{Apps: []core.AppConfig{
+		{AppId: "cli_x", AppSecret: core.PlainSecret("s"), Brand: core.BrandFeishu, Lang: i18n.LangJaJP},
+	}}
+	if err := core.SaveMultiAppConfig(existing); err != nil {
+		t.Fatalf("seed config: %v", err)
+	}
+
+	if err := saveInitConfig("", existing, f, "cli_x", core.PlainSecret("s2"), core.BrandFeishu, ""); err != nil {
+		t.Fatalf("saveInitConfig (no --lang): %v", err)
+	}
+
+	got, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatalf("LoadMultiAppConfig: %v", err)
+	}
+	if app := got.CurrentAppConfig(""); app == nil || app.Lang != i18n.LangJaJP {
+		t.Errorf("Lang after re-init = %v, want %q (preserved)", app, i18n.LangJaJP)
+	}
+}
+
+// TestConfigInitCmd_InvalidLang verifies a non-empty --lang on config init is
+// strictly validated the same way bind validates: wrong-case / typo / removed
+// codes / hyphen form all exit with ExitValidation. (Empty is a no-op.)
+func TestConfigInitCmd_InvalidLang(t *testing.T) {
+	clearAgentEnv(t)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	cases := []struct {
+		name string
+		lang string
+	}{
+		{"wrong case ZH", "ZH"},
+		{"typo frr", "frr"},
+		{"removed code ar", "ar"},
+		{"unknown xx", "xx"},
+		{"hyphen form zh-CN", "zh-CN"},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			f, _, _, _ := cmdutil.TestFactory(t, nil)
+			cmd := NewCmdConfigInit(f, nil)
+			f.IOStreams.In = strings.NewReader("sec\n")
+			cmd.SetArgs([]string{"--lang", tc.lang, "--app-id", "x", "--app-secret-stdin"})
+			err := cmd.Execute()
+			if err == nil {
+				t.Fatalf("expected validation error for --lang %q, got nil", tc.lang)
+			}
+			exitErr, ok := err.(*output.ExitError)
+			if !ok {
+				t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+			}
+			if exitErr.Code != output.ExitValidation {
+				t.Errorf("exit code = %d, want %d (validation)", exitErr.Code, output.ExitValidation)
+			}
+			if !strings.Contains(exitErr.Error(), "invalid --lang") {
+				t.Errorf("error message %q does not contain 'invalid --lang'", exitErr.Error())
+			}
+		})
+	}
+}
+
 func TestHasAnyNonInteractiveFlag(t *testing.T) {
 	tests := []struct {
 		name string
@@ -411,3 +482,59 @@ func TestConfigBlockedByExternalProvider(t *testing.T) {
 		})
 	}
 }
+
+// TestValidateInitLang covers the --lang contract: empty (omitted or explicit)
+// is a no-op leaving Lang unset; a short code or Feishu locale canonicalizes to
+// the same locale; an unrecognized value errors.
+func TestValidateInitLang(t *testing.T) {
+	t.Run("empty is a no-op", func(t *testing.T) {
+		for _, explicit := range []bool{false, true} {
+			opts := &ConfigInitOptions{Lang: "", langExplicit: explicit}
+			if err := validateInitLang(opts); err != nil {
+				t.Fatalf("explicit=%v: expected nil error, got %v", explicit, err)
+			}
+			if opts.Lang != "" {
+				t.Errorf("explicit=%v: Lang = %q, want \"\" (unset)", explicit, opts.Lang)
+			}
+		}
+	})
+	t.Run("short and locale canonicalize alike", func(t *testing.T) {
+		for _, in := range []string{"ja", "ja_jp"} {
+			opts := &ConfigInitOptions{Lang: in, langExplicit: true}
+			if err := validateInitLang(opts); err != nil {
+				t.Fatalf("--lang %q: unexpected error %v", in, err)
+			}
+			if opts.Lang != string(i18n.LangJaJP) {
+				t.Errorf("--lang %q normalized to %q, want %q", in, opts.Lang, i18n.LangJaJP)
+			}
+		}
+	})
+}
+
+// TestPrintLangPreferenceConfirmation covers the confirmation helper: it prints
+// to stderr only when --lang explicitly set a non-empty preference.
+func TestPrintLangPreferenceConfirmation(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	t.Run("explicit non-empty prints confirmation", func(t *testing.T) {
+		f, _, stderr, _ := cmdutil.TestFactory(t, nil)
+		printLangPreferenceConfirmation(&ConfigInitOptions{Factory: f, Lang: "en_us", UILang: i18n.LangZhCN, langExplicit: true})
+		got := stderr.String()
+		if !strings.Contains(got, "语言偏好") || !strings.Contains(got, "en_us") {
+			t.Errorf("stderr = %q, want confirmation mentioning the preference and en_us", got)
+		}
+	})
+	t.Run("implicit prints nothing", func(t *testing.T) {
+		f, _, stderr, _ := cmdutil.TestFactory(t, nil)
+		printLangPreferenceConfirmation(&ConfigInitOptions{Factory: f, Lang: "en_us", UILang: i18n.LangZhCN, langExplicit: false})
+		if got := stderr.String(); got != "" {
+			t.Errorf("stderr = %q, want empty when --lang is implicit", got)
+		}
+	})
+	t.Run("explicit empty prints nothing", func(t *testing.T) {
+		f, _, stderr, _ := cmdutil.TestFactory(t, nil)
+		printLangPreferenceConfirmation(&ConfigInitOptions{Factory: f, Lang: "", UILang: i18n.LangZhCN, langExplicit: true})
+		if got := stderr.String(); got != "" {
+			t.Errorf("stderr = %q, want empty when --lang is empty", got)
+		}
+	})
+}

cmd/config/init.go

@@ -18,6 +18,7 @@ import (
 	"github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/output"
 )
@@ -31,9 +32,13 @@ type ConfigInitOptions struct {
 	AppSecretStdin bool   // read app-secret from stdin (avoids process list exposure)
 	Brand          string
 	New            bool
-	Lang           string
-	langExplicit   bool   // true when --lang was explicitly passed
-	ProfileName    string // when set, create/update a named profile instead of replacing Apps[0]
+
+	Lang         string // raw --lang (string for cobra); normalized to canonical/"" in validateInitLang
+	langExplicit bool   // true when --lang was explicitly passed
+
+	UILang i18n.Lang // TUI display language (picker-only); intentionally separate from --lang
+
+	ProfileName string // when set, create/update a named profile instead of replacing Apps[0]
 
 	// ForceInit overrides the agent-workspace guard. Without it, running
 	// init under OPENCLAW_HOME / HERMES_HOME refuses and points the caller
@@ -45,7 +50,7 @@ type ConfigInitOptions struct {
 
 // NewCmdConfigInit creates the config init subcommand.
 func NewCmdConfigInit(f *cmdutil.Factory, runF func(*ConfigInitOptions) error) *cobra.Command {
-	opts := &ConfigInitOptions{Factory: f}
+	opts := &ConfigInitOptions{Factory: f, UILang: i18n.LangZhCN}
 
 	cmd := &cobra.Command{
 		Use:   "init",
@@ -63,6 +68,9 @@ if the user explicitly wants a separate app inside the Agent workspace.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.Ctx = cmd.Context()
 			opts.langExplicit = cmd.Flags().Changed("lang")
+			if err := validateInitLang(opts); err != nil {
+				return err
+			}
 			if err := guardAgentWorkspace(opts); err != nil {
 				return err
 			}
@@ -77,7 +85,7 @@ if the user explicitly wants a separate app inside the Agent workspace.`,
 	cmd.Flags().StringVar(&opts.AppID, "app-id", "", "App ID (non-interactive)")
 	cmd.Flags().BoolVar(&opts.AppSecretStdin, "app-secret-stdin", false, "Read App Secret from stdin to avoid process list exposure")
 	cmd.Flags().StringVar(&opts.Brand, "brand", "feishu", "feishu or lark (non-interactive, default feishu)")
-	cmd.Flags().StringVar(&opts.Lang, "lang", "zh", "language for interactive prompts (zh or en)")
+	cmd.Flags().StringVar(&opts.Lang, "lang", "", "language preference (e.g. zh or zh_cn)")
 	cmd.Flags().StringVar(&opts.ProfileName, "name", "", "create or update a named profile (append instead of replace)")
 	cmd.Flags().BoolVar(&opts.ForceInit, "force-init", false, "allow init inside an Agent workspace (OPENCLAW_HOME / HERMES_HOME); use config bind instead unless you really want a separate app")
 	cmdutil.SetRisk(cmd, "write")
@@ -85,6 +93,25 @@ if the user explicitly wants a separate app inside the Agent workspace.`,
 	return cmd
 }
 
+// printLangPreferenceConfirmation echoes the set preference to stderr, only
+// when --lang explicitly set a non-empty value.
+func printLangPreferenceConfirmation(opts *ConfigInitOptions) {
+	if !opts.langExplicit || opts.Lang == "" {
+		return
+	}
+	msg := getInitMsg(opts.UILang)
+	fmt.Fprintln(opts.Factory.IOStreams.ErrOut, fmt.Sprintf(msg.LangPreferenceSet, opts.Lang))
+}
+
+func validateInitLang(opts *ConfigInitOptions) error {
+	lang, err := cmdutil.ParseLangFlag(opts.Lang)
+	if err != nil {
+		return err
+	}
+	opts.Lang = string(lang)
+	return nil
+}
+
 // guardAgentWorkspace refuses 'config init' when run inside an OpenClaw or
 // Hermes Agent context, because the Agent has already provisioned an app
 // and 'config bind' is the right tool for hooking lark-cli into it.
@@ -132,7 +159,7 @@ func cleanupOldConfig(existing *core.MultiAppConfig, f *cmdutil.Factory, skipApp
 func saveAsOnlyApp(appId string, secret core.SecretInput, brand core.LarkBrand, lang string) error {
 	config := &core.MultiAppConfig{
 		Apps: []core.AppConfig{{
-			AppId: appId, AppSecret: secret, Brand: brand, Lang: lang, Users: []core.AppUser{},
+			AppId: appId, AppSecret: secret, Brand: brand, Lang: i18n.Lang(lang), Users: []core.AppUser{},
 		}},
 	}
 	return core.SaveMultiAppConfig(config)
@@ -146,7 +173,13 @@ func saveInitConfig(profileName string, existing *core.MultiAppConfig, f *cmduti
 		return saveAsProfile(existing, f.Keychain, profileName, appId, secret, brand, lang)
 	}
 	cleanupOldConfig(existing, f, appId)
-	return saveAsOnlyApp(appId, secret, brand, lang)
+	var prior i18n.Lang
+	if existing != nil {
+		if app := existing.CurrentAppConfig(""); app != nil {
+			prior = app.Lang
+		}
+	}
+	return saveAsOnlyApp(appId, secret, brand, string(preferredLang(i18n.Lang(lang), prior)))
 }
 
 // saveAsProfile appends or updates a named profile in the config.
@@ -167,11 +200,10 @@ func saveAsProfile(existing *core.MultiAppConfig, kc keychain.KeychainAccess, pr
 			}
 			multi.Apps[idx].Users = []core.AppUser{}
 		}
-		// Update existing profile
 		multi.Apps[idx].AppId = appId
 		multi.Apps[idx].AppSecret = secret
 		multi.Apps[idx].Brand = brand
-		multi.Apps[idx].Lang = lang
+		multi.Apps[idx].Lang = preferredLang(i18n.Lang(lang), multi.Apps[idx].Lang)
 	} else {
 		if findAppIndexByAppID(multi, profileName) >= 0 {
 			return fmt.Errorf("profile name %q conflicts with existing appId", profileName)
@@ -182,7 +214,7 @@ func saveAsProfile(existing *core.MultiAppConfig, kc keychain.KeychainAccess, pr
 			AppId:     appId,
 			AppSecret: secret,
 			Brand:     brand,
-			Lang:      lang,
+			Lang:      i18n.Lang(lang),
 			Users:     []core.AppUser{},
 		})
 	}
@@ -238,7 +270,7 @@ func updateExistingProfileWithoutSecret(existing *core.MultiAppConfig, profileNa
 
 	app.AppId = appID
 	app.Brand = brand
-	app.Lang = lang
+	app.Lang = preferredLang(i18n.Lang(lang), app.Lang)
 	return core.SaveMultiAppConfig(existing)
 }
 
@@ -283,29 +315,27 @@ func configInitRun(opts *ConfigInitOptions) error {
 			return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 		}
 		output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf("Configuration saved to %s", core.GetConfigPath()))
+		printLangPreferenceConfirmation(opts)
 		output.PrintJson(f.IOStreams.Out, map[string]interface{}{"appId": opts.AppID, "appSecret": "****", "brand": brand})
 		return nil
 	}
 
-	// For interactive modes, prompt language selection if --lang was not explicitly set
+	// For interactive modes, prompt language selection if --lang was not explicitly set.
+	// Picker offers 2 options (中文 / English) and drives BOTH opts.Lang
+	// (preference) and opts.UILang (TUI rendering).
 	if f.IOStreams.IsTerminal && !opts.langExplicit && !opts.hasAnyNonInteractiveFlag() {
-		savedLang := ""
-		if existing != nil {
-			if app := existing.CurrentAppConfig(""); app != nil {
-				savedLang = app.Lang
-			}
-		}
-		lang, err := promptLangSelection(savedLang)
+		lang, err := promptLangSelection()
 		if err != nil {
 			if err == huh.ErrUserAborted {
 				return output.ErrBare(1)
 			}
-			return err
+			return output.Errorf(output.ExitInternal, "internal", "language selection failed: %v", err)
 		}
-		opts.Lang = lang
+		opts.Lang = string(lang)
+		opts.UILang = lang
 	}
 
-	msg := getInitMsg(opts.Lang)
+	msg := getInitMsg(opts.UILang)
 
 	// Mode 3: Create new app directly (--new)
 	if opts.New {
@@ -324,6 +354,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 		if err := saveInitConfig(opts.ProfileName, existing, f, result.AppID, secret, result.Brand, opts.Lang); err != nil {
 			return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 		}
+		printLangPreferenceConfirmation(opts)
 		output.PrintJson(f.IOStreams.Out, map[string]interface{}{"appId": result.AppID, "appSecret": "****", "brand": result.Brand})
 		return nil
 	}
@@ -352,6 +383,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 		} else if result.Mode == "existing" && result.AppID != "" {
 			// Existing app with unchanged secret — update app ID and brand only
 			if err := updateExistingProfileWithoutSecret(existing, opts.ProfileName, result.AppID, result.Brand, opts.Lang); err != nil {
+				// Deprecated: legacy *output.ExitError passthrough; removed after typed migration.
 				var exitErr *output.ExitError
 				if errors.As(err, &exitErr) {
 					return err
@@ -365,6 +397,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 		if result.Mode == "existing" {
 			output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf(msg.ConfigSaved, result.AppID))
 		}
+		printLangPreferenceConfirmation(opts)
 		return nil
 	}
 
@@ -451,5 +484,6 @@ func configInitRun(opts *ConfigInitOptions) error {
 		return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 	}
 	output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf("Configuration saved to %s", core.GetConfigPath()))
+	printLangPreferenceConfirmation(opts)
 	return nil
 }

cmd/config/init_messages.go

@@ -7,6 +7,7 @@ import (
 	"github.com/charmbracelet/huh"
 
 	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/i18n"
 )
 
 type initMsg struct {
@@ -26,6 +27,10 @@ type initMsg struct {
 	DetectedLarkTenant   string
 	AppCreated           string
 	ConfigSaved          string
+
+	// LangPreferenceSet is printed to stderr after a successful init when the
+	// user explicitly passed --lang. Format: language code.
+	LangPreferenceSet string
 }
 
 var initMsgZh = &initMsg{
@@ -43,6 +48,7 @@ var initMsgZh = &initMsg{
 	DetectedLarkTenant:   "[lark-cli] 检测到 Lark 租户，切换端点重试...",
 	AppCreated:           "应用配置成功! App ID: %s",
 	ConfigSaved:          "应用配置成功! App ID: %s",
+	LangPreferenceSet:    "语言偏好已设置：%s",
 }
 
 var initMsgEn = &initMsg{
@@ -60,29 +66,27 @@ var initMsgEn = &initMsg{
 	DetectedLarkTenant:   "[lark-cli] Detected Lark tenant, switching endpoint...",
 	AppCreated:           "App configured! App ID: %s",
 	ConfigSaved:          "App configured! App ID: %s",
+	LangPreferenceSet:    "Language preference set to: %s",
 }
 
-func getInitMsg(lang string) *initMsg {
-	if lang == "en" {
+// getInitMsg picks the zh/en TUI bundle; non-English falls back to zh.
+func getInitMsg(lang i18n.Lang) *initMsg {
+	if lang.IsEnglish() {
 		return initMsgEn
 	}
 	return initMsgZh
 }
 
-// promptLangSelection shows an interactive language picker and returns the chosen lang code.
-// savedLang is used as the pre-selected default (from existing config).
-func promptLangSelection(savedLang string) (string, error) {
-	lang := savedLang
-	if lang != "en" {
-		lang = "zh"
-	}
+// promptLangSelection shows the 中文/English picker and returns the chosen locale.
+func promptLangSelection() (i18n.Lang, error) {
+	lang := i18n.LangZhCN
 	form := huh.NewForm(
 		huh.NewGroup(
-			huh.NewSelect[string]().
+			huh.NewSelect[i18n.Lang]().
 				Title("Language / 语言").
 				Options(
-					huh.NewOption("中文", "zh"),
-					huh.NewOption("English", "en"),
+					huh.NewOption("中文", i18n.LangZhCN),
+					huh.NewOption("English", i18n.LangEnUS),
 				).
 				Value(&lang),
 		),

cmd/config/init_messages_test.go

@@ -6,6 +6,8 @@ package config
 import (
 	"fmt"
 	"testing"
+
+	"github.com/larksuite/cli/internal/i18n"
 )
 
 func TestGetInitMsg_Zh(t *testing.T) {
@@ -29,7 +31,7 @@ func TestGetInitMsg_En(t *testing.T) {
 }
 
 func TestGetInitMsg_DefaultsToZh(t *testing.T) {
-	for _, lang := range []string{"", "fr", "ja", "unknown"} {
+	for _, lang := range []i18n.Lang{"", "unknown", "xyz", "invalid"} {
 		msg := getInitMsg(lang)
 		if msg != initMsgZh {
 			t.Errorf("getInitMsg(%q) should default to zh", lang)
@@ -62,6 +64,7 @@ func assertAllFieldsNonEmpty(t *testing.T, msg *initMsg, label string) {
 		"DetectedLarkTenant":   msg.DetectedLarkTenant,
 		"AppCreated":           msg.AppCreated,
 		"ConfigSaved":          msg.ConfigSaved,
+		"LangPreferenceSet":    msg.LangPreferenceSet,
 	}
 	for name, val := range fields {
 		if val == "" {
@@ -71,7 +74,7 @@ func assertAllFieldsNonEmpty(t *testing.T, msg *initMsg, label string) {
 }
 
 func TestInitMsg_FormatStrings(t *testing.T) {
-	for _, lang := range []string{"zh", "en"} {
+	for _, lang := range []i18n.Lang{i18n.LangZhCN, i18n.LangEnUS} {
 		msg := getInitMsg(lang)
 		// AppCreated and ConfigSaved should contain %s for App ID
 		got := fmt.Sprintf(msg.AppCreated, "cli_test123")
@@ -84,3 +87,37 @@ func TestInitMsg_FormatStrings(t *testing.T) {
 		}
 	}
 }
+
+func TestGetInitMsg_BilingualCollapse(t *testing.T) {
+	// The TUI is bilingual (zh + en). Only English-bucket languages return the
+	// English struct — by canonical locale ("en_us") or legacy short ("en").
+	// Everything else (zh, the other codes, invalid, "") returns Chinese.
+	tests := []struct {
+		lang       i18n.Lang
+		shouldBeEn bool
+	}{
+		{i18n.LangZhCN, false},
+		{i18n.LangEnUS, true},
+		{"en", true}, // legacy short value
+		{i18n.LangJaJP, false},
+		{"fr_fr", false},
+		{"invalid", false},
+		{"", false},
+	}
+
+	for _, tt := range tests {
+		t.Run(string(tt.lang), func(t *testing.T) {
+			msg := getInitMsg(tt.lang)
+			if msg == nil {
+				t.Fatal("getInitMsg returned nil")
+			}
+			want := initMsgZh
+			if tt.shouldBeEn {
+				want = initMsgEn
+			}
+			if msg != want {
+				t.Errorf("getInitMsg(%q) returned wrong struct", tt.lang)
+			}
+		})
+	}
+}

cmd/config/keychain_downgrade.go

@@ -0,0 +1,73 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build darwin
+
+package config
+
+import (
+	"fmt"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/keychain"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/spf13/cobra"
+)
+
+// NewCmdConfigKeychainDowngrade creates the macOS-only subcommand that pins
+// the master key to the local file fallback (master.key.file) so subsequent
+// operations bypass the OS Keychain. Useful inside sandboxes like Codex
+// where the system Keychain is unreachable.
+func NewCmdConfigKeychainDowngrade(f *cmdutil.Factory) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "keychain-downgrade",
+		Short: "Downgrade keychain storage to a local file (macOS only)",
+		Long: `Materialize the master key from the macOS system Keychain into a local file
+under ~/Library/Application Support/lark-cli/master.key.file, then pin all
+subsequent reads to that file.
+
+Intended workflow: run this once from an interactive Terminal session on
+macOS (where the system Keychain is reachable). After it finishes,
+sandboxed / automation / CI runs of lark-cli on the same machine will read
+the master key from the local file and no longer need the OS Keychain.
+
+This is the supported fix for environments like the Codex sandbox where the
+system Keychain is blocked. Running keychain-downgrade from inside such a
+sandbox will itself fail with "keychain access blocked" — that is expected;
+run it from an interactive macOS session instead.
+
+The OS Keychain entry is preserved as a cold backup; nothing is deleted there.
+The command is idempotent: re-running it on an already-downgraded install
+reports "already downgraded" and exits 0.`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return configKeychainDowngradeRun(f)
+		},
+	}
+	cmdutil.SetRisk(cmd, "write")
+	return cmd
+}
+
+func configKeychainDowngradeRun(f *cmdutil.Factory) error {
+	service := keychain.LarkCliService
+	keyPath := keychain.MasterKeyFilePath(service)
+
+	result, err := keychain.DowngradeMasterKeyToFile(service)
+	if err != nil {
+		return output.ErrWithHint(
+			output.ExitAPI,
+			"config",
+			fmt.Sprintf("keychain downgrade failed: %v", err),
+			"This command must be run from an interactive macOS session (e.g. Terminal.app or iTerm) where the system Keychain is reachable. Running it from inside a sandbox / automation context that blocks Keychain access cannot succeed by design.",
+		)
+	}
+
+	switch result {
+	case keychain.DowngradeAlreadyDone:
+		output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf("keychain already downgraded; subsequent operations read from %s", keyPath))
+	case keychain.DowngradeUsedKeychainKey:
+		output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf("downgraded: copied master key from system Keychain to %s. Subsequent operations will read from file, bypassing the OS Keychain (useful inside sandboxes like Codex).", keyPath))
+	case keychain.DowngradeCreatedNewKey:
+		output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf("system Keychain was empty; generated a new master key and wrote it to %s. The OS Keychain was not modified.", keyPath))
+	}
+	return nil
+}

cmd/config/keychain_downgrade_other.go

@@ -0,0 +1,28 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build !darwin
+
+package config
+
+import (
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/spf13/cobra"
+)
+
+// NewCmdConfigKeychainDowngrade is registered on all platforms so that
+// `lark-cli config --help` reads the same everywhere. On non-macOS it
+// refuses with a clear message.
+func NewCmdConfigKeychainDowngrade(f *cmdutil.Factory) *cobra.Command {
+	_ = f
+	cmd := &cobra.Command{
+		Use:   "keychain-downgrade",
+		Short: "Downgrade keychain storage to a local file (macOS only)",
+		Long:  `Downgrade keychain storage to a local file. This subcommand is only supported on macOS; on this platform the keychain layer already uses local files.`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return output.ErrValidation("keychain-downgrade is only supported on macOS")
+		},
+	}
+	return cmd
+}

cmd/error_auth_hint.go

@@ -4,9 +4,13 @@
 package cmd
 
 import (
+	"errors"
 	"fmt"
 	"strings"
 
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/errs"
 	internalauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
@@ -14,12 +18,49 @@ import (
 	"github.com/larksuite/cli/internal/registry"
 	"github.com/larksuite/cli/shortcuts"
 	shortcutcommon "github.com/larksuite/cli/shortcuts/common"
-	"github.com/spf13/cobra"
 )
 
-// enrichMissingScopeError preserves the original need_user_authorization
-// message and appends a scope hint when the current command declares the
-// required scopes locally.
+// applyNeedAuthorizationHint augments a typed *errs.AuthenticationError with a
+// "current command requires scope(s): X, Y" hint when the underlying error is
+// a need_user_authorization signal AND the current command declares scopes
+// locally (via shortcut registration or service-method metadata).
+//
+// Stage-1: this typed path is dormant — no production code returns a typed
+// *errs.AuthenticationError. Kept so per-domain stage-2 migrations can plug
+// in without re-architecting. The active stage-1 path is
+// enrichMissingScopeError below, which operates on legacy *output.ExitError.
+func applyNeedAuthorizationHint(f *cmdutil.Factory, err error) {
+	if err == nil || f == nil {
+		return
+	}
+	if !internalauth.IsNeedUserAuthorizationError(err) {
+		return
+	}
+	var authErr *errs.AuthenticationError
+	if !errors.As(err, &authErr) {
+		return
+	}
+	scopes := resolveDeclaredScopesForCurrentCommand(f)
+	if len(scopes) == 0 {
+		return
+	}
+	scopeHint := fmt.Sprintf("current command requires scope(s): %s", strings.Join(scopes, ", "))
+	if authErr.Hint == "" {
+		authErr.Hint = scopeHint
+		return
+	}
+	authErr.Hint += "\n" + scopeHint
+}
+
+// enrichMissingScopeError appends a "current command requires scope(s): X"
+// hint to a legacy *output.ExitError when the underlying error carries the
+// need_user_authorization marker AND the current command declares scopes
+// locally. Matches pre-PR behaviour byte-for-byte; lives on the legacy
+// envelope path until per-domain stage-2 typed migration.
+//
+// Deprecated: stage-1 enrichment for the legacy *output.ExitError surface.
+// Stage-2 typed migration will lift this into AuthenticationError.Hint on
+// the typed envelope via applyNeedAuthorizationHint and remove this helper.
 func enrichMissingScopeError(f *cmdutil.Factory, exitErr *output.ExitError) {
 	if exitErr == nil || exitErr.Detail == nil {
 		return
@@ -27,12 +68,10 @@ func enrichMissingScopeError(f *cmdutil.Factory, exitErr *output.ExitError) {
 	if !internalauth.IsNeedUserAuthorizationError(exitErr) {
 		return
 	}
-
 	scopes := resolveDeclaredScopesForCurrentCommand(f)
 	if len(scopes) == 0 {
 		return
 	}
-
 	scopeHint := fmt.Sprintf("current command requires scope(s): %s", strings.Join(scopes, ", "))
 	if exitErr.Detail.Hint == "" {
 		exitErr.Detail.Hint = scopeHint

cmd/event/runtime.go

@@ -42,7 +42,7 @@ func (r *consumeRuntime) CallAPI(ctx context.Context, method, path string, body
 	if err != nil {
 		return nil, err
 	}
-	if apiErr := client.CheckLarkResponse(result); apiErr != nil {
+	if apiErr := r.client.CheckResponse(result, r.accessIdentity); apiErr != nil {
 		return json.RawMessage(resp.RawBody), apiErr
 	}
 	return json.RawMessage(resp.RawBody), nil

cmd/platform_guards.go

@@ -36,6 +36,13 @@ import (
 // makeErr is called for every guarded dispatch; it must return a fresh
 // *output.ExitError each time (the envelope writer mutates a few fields
 // as it serialises).
+// Deprecated: installFatalGuard accepts a *output.ExitError-producing lambda,
+// which is part of the legacy error surface that predates the typed error
+// contract introduced by errs/. New code MUST NOT add new callers — the
+// platform-extension fatal-guard plumbing will switch to typed errs.* errors
+// when the platform-extension framework migrates. This wrapper is retained
+// only for the existing in-tree call sites; it will be removed once they
+// have moved to the typed surface.
 func installFatalGuard(rootCmd *cobra.Command, makeErr func() *output.ExitError) {
 	// Two cobra subcommands are injected lazily at Execute() time and
 	// would otherwise slip past walkGuard. We pre-register both so
@@ -75,6 +82,12 @@ func installFatalGuard(rootCmd *cobra.Command, makeErr func() *output.ExitError)
 // installPluginInstallErrorGuard surfaces a FailClosed plugin install
 // failure as a structured plugin_install envelope before any command
 // runs.
+// Deprecated: installPluginInstallErrorGuard produces a legacy
+// *output.ExitError via its internal makeErr lambda. New code MUST NOT add
+// such producers — plugin install failures should surface as a typed
+// *errs.XxxError once the platform-extension framework migrates. This
+// helper is retained only while existing call sites are migrated; it will
+// be removed once they have moved to the typed surface.
 func installPluginInstallErrorGuard(rootCmd *cobra.Command, installErr error) {
 	makeErr := func() *output.ExitError {
 		var pi *internalplatform.PluginInstallError
@@ -116,6 +129,12 @@ func installPluginInstallErrorGuard(rootCmd *cobra.Command, installErr error) {
 //   - "plugin_conflict" with reason_code "multiple_restrict_plugins" - multi
 //
 // Either way the CLI must NOT silently continue with a broken policy.
+// Deprecated: installPluginConflictGuard produces a legacy *output.ExitError
+// via its internal makeErr lambda. New code MUST NOT add such producers —
+// plugin conflict failures should surface as a typed *errs.XxxError once the
+// platform-extension framework migrates. This helper is retained only while
+// existing call sites are migrated; it will be removed once they have moved
+// to the typed surface.
 func installPluginConflictGuard(rootCmd *cobra.Command, err error) {
 	makeErr := func() *output.ExitError {
 		envelopeType := "plugin_install"
@@ -143,6 +162,12 @@ func installPluginConflictGuard(rootCmd *cobra.Command, err error) {
 // failure as a plugin_lifecycle envelope. The reason_code splits
 // returned-error vs panic so consumers (audit / on-call) can tell the
 // two failure modes apart.
+// Deprecated: installPluginLifecycleErrorGuard produces a legacy
+// *output.ExitError via its internal makeErr lambda. New code MUST NOT add
+// such producers — plugin lifecycle failures should surface as a typed
+// *errs.XxxError once the platform-extension framework migrates. This
+// helper is retained only while existing call sites are migrated; it will
+// be removed once they have moved to the typed surface.
 func installPluginLifecycleErrorGuard(rootCmd *cobra.Command, err error) {
 	makeErr := func() *output.ExitError {
 		reasonCode := "lifecycle_failed"
@@ -194,6 +219,13 @@ func installPluginLifecycleErrorGuard(rootCmd *cobra.Command, err error) {
 //
 // This way the very first non-nil step in cobra's chain is always our
 // guard, regardless of which leaf the user invoked.
+// Deprecated: walkGuard accepts a *output.ExitError-producing lambda, part
+// of the legacy error surface that predates the typed error contract
+// introduced by errs/. New code MUST NOT add new callers — the platform-
+// extension guard plumbing will switch to typed errs.* errors when the
+// platform-extension framework migrates. This wrapper is retained only for
+// the existing in-tree call sites; it will be removed once they have moved
+// to the typed surface.
 func walkGuard(cmd *cobra.Command, makeErr func() *output.ExitError) {
 	if cmd == nil {
 		return

cmd/profile/add.go

@@ -14,6 +14,7 @@ import (
 
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/output"
 )
 
@@ -40,7 +41,7 @@ func NewCmdProfileAdd(f *cmdutil.Factory) *cobra.Command {
 	cmd.Flags().StringVar(&appID, "app-id", "", "App ID (required)")
 	cmd.Flags().BoolVar(&appSecretStdin, "app-secret-stdin", false, "read App Secret from stdin")
 	cmd.Flags().StringVar(&brand, "brand", "feishu", "feishu or lark")
-	cmd.Flags().StringVar(&lang, "lang", "zh", "language for interactive prompts (zh or en)")
+	cmd.Flags().StringVar(&lang, "lang", "", "language preference (e.g. zh or zh_cn)")
 	cmd.Flags().BoolVar(&use, "use", false, "switch to this profile after adding")
 
 	_ = cmd.MarkFlagRequired("name")
@@ -55,6 +56,12 @@ func profileAddRun(f *cmdutil.Factory, name, appID string, appSecretStdin bool,
 		return output.ErrValidation("%v", err)
 	}
 
+	langPref, err := cmdutil.ParseLangFlag(lang)
+	if err != nil {
+		return err
+	}
+	lang = string(langPref)
+
 	// Read secret from stdin
 	if !appSecretStdin {
 		return output.ErrValidation("app secret must be provided via stdin: use --app-secret-stdin and pipe the secret")
@@ -115,7 +122,7 @@ func profileAddRun(f *cmdutil.Factory, name, appID string, appSecretStdin bool,
 		AppId:     appID,
 		AppSecret: secret,
 		Brand:     parsedBrand,
-		Lang:      lang,
+		Lang:      i18n.Lang(lang),
 		Users:     []core.AppUser{},
 	})
 

cmd/profile/profile_test.go

@@ -13,6 +13,7 @@ import (
 
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/vfs"
 )
@@ -51,6 +52,56 @@ func TestProfileAddRun_InvalidExistingConfigReturnsError(t *testing.T) {
 	}
 }
 
+// TestProfileAddRun_Lang covers the unified --lang contract on profile add:
+// short codes and Feishu locales both canonicalize to the same stored locale,
+// empty stores no preference, and an unrecognized value errors.
+func TestProfileAddRun_Lang(t *testing.T) {
+	t.Run("short and locale canonicalize and persist alike", func(t *testing.T) {
+		for _, in := range []string{"ja", "ja_jp"} {
+			setupProfileConfigDir(t)
+			f, _, _, _ := cmdutil.TestFactory(t, nil)
+			f.IOStreams.In = strings.NewReader("secret\n")
+			if err := profileAddRun(f, "p", "app-p", true, "feishu", in, false); err != nil {
+				t.Fatalf("--lang %q: profileAddRun() error = %v", in, err)
+			}
+			saved, err := core.LoadMultiAppConfig()
+			if err != nil {
+				t.Fatalf("LoadMultiAppConfig() error = %v", err)
+			}
+			if app := saved.FindApp("p"); app == nil || app.Lang != i18n.LangJaJP {
+				t.Errorf("--lang %q: stored Lang = %v, want %q", in, app, i18n.LangJaJP)
+			}
+		}
+	})
+
+	t.Run("empty stores no preference", func(t *testing.T) {
+		setupProfileConfigDir(t)
+		f, _, _, _ := cmdutil.TestFactory(t, nil)
+		f.IOStreams.In = strings.NewReader("secret\n")
+		if err := profileAddRun(f, "p", "app-p", true, "feishu", "", false); err != nil {
+			t.Fatalf("profileAddRun() error = %v", err)
+		}
+		saved, _ := core.LoadMultiAppConfig()
+		if app := saved.FindApp("p"); app == nil || app.Lang != "" {
+			t.Errorf("stored Lang = %v, want \"\" (unset)", app)
+		}
+	})
+
+	t.Run("invalid lang errors", func(t *testing.T) {
+		setupProfileConfigDir(t)
+		f, _, _, _ := cmdutil.TestFactory(t, nil)
+		f.IOStreams.In = strings.NewReader("secret\n")
+		err := profileAddRun(f, "p", "app-p", true, "feishu", "ZH", false)
+		if err == nil {
+			t.Fatal("expected validation error for --lang ZH, got nil")
+		}
+		exitErr, ok := err.(*output.ExitError)
+		if !ok || exitErr.Code != output.ExitValidation {
+			t.Fatalf("expected ExitValidation, got %T: %v", err, err)
+		}
+	})
+}
+
 func TestProfileAddRun_UseAfterUpdatesCurrentAndPrevious(t *testing.T) {
 	setupProfileConfigDir(t)
 	multi := &core.MultiAppConfig{

cmd/prune.go

@@ -105,6 +105,10 @@ func strictModeStubFrom(child *cobra.Command, mode core.StrictMode) *cobra.Comma
 		},
 		RunE: func(c *cobra.Command, _ []string) error {
 			cd := cmdpolicy.CommandDeniedFromDenial(cmdpolicy.CanonicalPath(c), denial)
+			// Legacy *output.ExitError producer: this literal predates the
+			// typed error contract introduced by errs/. New denial sites MUST
+			// NOT construct *output.ExitError directly — they should return a
+			// typed *errs.XxxError once the cmdpolicy framework migrates.
 			return &output.ExitError{
 				Code: output.ExitValidation,
 				Detail: &output.ErrDetail{

cmd/root.go

@@ -15,8 +15,8 @@ import (
 	"strconv"
 	"strings"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/platform"
-	internalauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/build"
 	"github.com/larksuite/cli/internal/cmdpolicy"
 	"github.com/larksuite/cli/internal/cmdutil"
@@ -199,22 +199,52 @@ func configureFlagCompletions(args []string) {
 
 // handleRootError dispatches a command error to the appropriate handler
 // and returns the process exit code.
+//
+// Dispatch order:
+//  1. *errs.SecurityPolicyError: keeps the legacy custom envelope
+//     (type=auth_error, string code, retryable, challenge_url) and exit 1.
+//     Carve-out from the typed taxonomy — wire migration deferred to a later PR.
+//  2. Typed errors from errs/ (e.g. *errs.PermissionError, *errs.APIError):
+//     render via the typed envelope writer, which lifts extension fields
+//     (missing_scopes, console_url, ...) to the top level. Routed by
+//     errs.CategoryOf via ExitCodeOf.
+//  3. *core.ConfigError + Legacy *output.ExitError: asExitError adapts them
+//     to a legacy envelope; written via WriteErrorEnvelope. Stage-1 keeps
+//     this path so existing wire shapes are preserved byte-for-byte until
+//     per-domain typed migration in stage 2+.
+//  4. Cobra errors (required flags, unknown commands, etc.): plain text.
 func handleRootError(f *cmdutil.Factory, err error) int {
 	errOut := f.IOStreams.ErrOut
 
-	// SecurityPolicyError uses a custom envelope format (string codes, challenge_url, retryable)
-	// that differs from the standard ErrDetail, so it's handled separately.
-	var spErr *internalauth.SecurityPolicyError
+	// SecurityPolicyError keeps the legacy custom envelope (string codes,
+	// challenge_url, retryable) and exit code 1 — its wire shape predates the
+	// typed taxonomy and downstream OAuth/policy consumers depend on it.
+	// The taxonomy migration for this category is deferred to a later PR.
+	var spErr *errs.SecurityPolicyError
 	if errors.As(err, &spErr) {
 		writeSecurityPolicyError(errOut, spErr)
 		return 1
 	}
 
-	// All other structured errors normalize to ExitError.
+	// *core.ConfigError flows raw to the legacy envelope path in stage 1
+	// (asExitError → output.ErrWithHint). Typed migration via
+	// errcompat.PromoteConfigError happens in stage 2+.
+
+	// When the typed error is a need_user_authorization signal, fold in the
+	// current command's declared scopes as a Hint so the user/AI sees the
+	// concrete scope(s) to re-auth with. The hint is computed on the fly from
+	// local shortcut/service metadata — it never depends on server state.
+	applyNeedAuthorizationHint(f, err)
+
+	if output.WriteTypedErrorEnvelope(errOut, err, string(f.ResolvedIdentity)) {
+		return output.ExitCodeOf(err)
+	}
+
 	if exitErr := asExitError(err); exitErr != nil {
 		if !exitErr.Raw {
-			// Raw errors (e.g. from `api` command) preserve the original API
-			// error detail; skip enrichment which would clear it.
+			// Raw errors (e.g. from `api` command via output.MarkRaw)
+			// preserve the original API error detail; skip enrichment
+			// which would clear it.
 			enrichMissingScopeError(f, exitErr)
 			enrichPermissionError(f, exitErr)
 		}
@@ -222,35 +252,21 @@ func handleRootError(f *cmdutil.Factory, err error) int {
 		return exitErr.Code
 	}
 
-	// Cobra errors (required flags, unknown commands, etc.)
 	fmt.Fprintln(errOut, "Error:", err)
 	return 1
 }
 
-// asExitError converts known structured error types to *output.ExitError.
-// Returns nil for unrecognized errors (e.g. cobra flag errors).
-func asExitError(err error) *output.ExitError {
-	var cfgErr *core.ConfigError
-	if errors.As(err, &cfgErr) {
-		return output.ErrWithHint(cfgErr.Code, cfgErr.Type, cfgErr.Message, cfgErr.Hint)
-	}
-	var exitErr *output.ExitError
-	if errors.As(err, &exitErr) {
-		return exitErr
-	}
-	return nil
-}
-
-// writeSecurityPolicyError writes the security-policy-specific JSON envelope to w.
-// This format intentionally differs from the standard ErrDetail envelope:
-// it uses string codes ("challenge_required"/"access_denied") and extra fields
-// (retryable, challenge_url) for machine-readable policy error handling.
-func writeSecurityPolicyError(w io.Writer, spErr *internalauth.SecurityPolicyError) {
+// writeSecurityPolicyError writes the security-policy-specific JSON envelope.
+// This wire format intentionally differs from the typed envelope writer: it
+// uses string codes ("challenge_required"/"access_denied"), a "auth_error"
+// type literal, and a top-level "retryable" field — the shape OAuth/policy
+// consumers have been parsing since before the typed taxonomy existed.
+func writeSecurityPolicyError(w io.Writer, spErr *errs.SecurityPolicyError) {
 	var codeStr string
-	switch spErr.Code {
-	case internalauth.LarkErrBlockByPolicyTryAuth:
+	switch spErr.Subtype {
+	case errs.SubtypeChallengeRequired:
 		codeStr = "challenge_required"
-	case internalauth.LarkErrBlockByPolicy:
+	case errs.SubtypeAccessDenied:
 		codeStr = "access_denied"
 	default:
 		codeStr = strconv.Itoa(spErr.Code)
@@ -265,8 +281,8 @@ func writeSecurityPolicyError(w io.Writer, spErr *internalauth.SecurityPolicyErr
 	if spErr.ChallengeURL != "" {
 		errData["challenge_url"] = spErr.ChallengeURL
 	}
-	if spErr.CLIHint != "" {
-		errData["hint"] = spErr.CLIHint
+	if spErr.Hint != "" {
+		errData["hint"] = spErr.Hint
 	}
 
 	env := map[string]interface{}{"ok": false, "error": errData}
@@ -275,15 +291,29 @@ func writeSecurityPolicyError(w io.Writer, spErr *internalauth.SecurityPolicyErr
 	encoder := json.NewEncoder(buffer)
 	encoder.SetEscapeHTML(false)
 	encoder.SetIndent("", "  ")
-	err := encoder.Encode(env)
-
-	if err != nil {
+	if encErr := encoder.Encode(env); encErr != nil {
 		fmt.Fprintln(w, `{"ok":false,"error":{"type":"internal_error","code":"marshal_error","message":"failed to marshal error"}}`)
 		return
 	}
 	fmt.Fprint(w, buffer.String())
 }
 
+// asExitError converts known structured error types to *output.ExitError.
+// Returns nil for unrecognized errors (e.g. cobra flag errors).
+//
+// Deprecated: legacy *output.ExitError bridge; removed after typed migration.
+func asExitError(err error) *output.ExitError {
+	var cfgErr *core.ConfigError
+	if errors.As(err, &cfgErr) {
+		return output.ErrWithHint(cfgErr.Code, cfgErr.Type, cfgErr.Message, cfgErr.Hint)
+	}
+	var exitErr *output.ExitError
+	if errors.As(err, &exitErr) {
+		return exitErr
+	}
+	return nil
+}
+
 // installUnknownSubcommandGuard replaces cobra's silent help fallback on
 // group commands (no Run/RunE) with an unknown_subcommand error.
 //
@@ -306,6 +336,13 @@ func installUnknownSubcommandGuard(cmd *cobra.Command) {
 	}
 }
 
+// Deprecated: unknownSubcommandRunE produces a legacy *output.ExitError that
+// predates the typed error contract introduced by errs/. New code MUST NOT
+// add producers of this shape — unknown-subcommand signals should move to
+// a typed *errs.ValidationError (or a dedicated typed error) carrying the
+// agent-protocol metadata as typed extension fields. This helper is retained
+// only while existing dispatch sites are migrated; it will be removed once
+// they have moved to the typed surface.
 func unknownSubcommandRunE(cmd *cobra.Command, args []string) error {
 	if len(args) == 0 {
 		return cmd.Help()
@@ -380,10 +417,16 @@ func installTipsHelpFunc(root *cobra.Command) {
 	})
 }
 
-// enrichPermissionError adds console_url and improves the hint for permission errors.
-// It differentiates between:
-//   - LarkErrAppScopeNotEnabled (99991672): app has not enabled the API scope → hint to admin console
-//   - LarkErrUserScopeInsufficient (99991679): user has not authorized the scope → hint to auth login --scope
+// enrichPermissionError adds console_url and improves the hint for legacy
+// *output.ExitError permission errors. Differentiates between:
+//   - LarkErrAppScopeNotEnabled (99991672): app has not enabled the scope
+//   - LarkErrUserScopeInsufficient (99991679) / LarkErrUserNotAuthorized:
+//     user has not authorized the scope → hint to auth login
+//   - default: other permission errors → console + auth-login fallback
+//
+// Deprecated: stage-1 enrichment for the legacy *output.ExitError envelope.
+// Stage-2 typed migration will lift this into PermissionError.MissingScopes
+// + ConsoleURL on the typed envelope and remove this helper.
 func enrichPermissionError(f *cmdutil.Factory, exitErr *output.ExitError) {
 	if exitErr.Detail == nil || exitErr.Detail.Type != "permission" {
 		return
@@ -405,15 +448,13 @@ func enrichPermissionError(f *cmdutil.Factory, exitErr *output.ExitError) {
 	// Build admin console URL with the recommended scope
 	consoleURL := registry.BuildConsoleScopeURL(cfg.Brand, cfg.AppID, recommended)
 
-	// Clear raw API detail — useful info is now in message/hint/console_url
+	// Clear raw API detail — useful info is now in message/hint/console_url.
 	exitErr.Detail.Detail = nil
 
 	isBot := f.ResolvedIdentity.IsBot()
-
 	larkCode := exitErr.Detail.Code
 	switch larkCode {
 	case output.LarkErrUserScopeInsufficient, output.LarkErrUserNotAuthorized:
-		// User has not authorized the scope → re-authorize
 		exitErr.Detail.Message = fmt.Sprintf("User not authorized: required scope %s [%d]", recommended, larkCode)
 		if isBot {
 			exitErr.Detail.Hint = "enable the scope in developer console (see console_url)"
@@ -423,13 +464,11 @@ func enrichPermissionError(f *cmdutil.Factory, exitErr *output.ExitError) {
 		exitErr.Detail.ConsoleURL = consoleURL
 
 	case output.LarkErrAppScopeNotEnabled:
-		// App has not enabled the API scope → admin console
 		exitErr.Detail.Message = fmt.Sprintf("App scope not enabled: required scope %s [%d]", recommended, larkCode)
 		exitErr.Detail.Hint = "enable the scope in developer console (see console_url)"
 		exitErr.Detail.ConsoleURL = consoleURL
 
 	default:
-		// Other permission errors (matched by keyword)
 		exitErr.Detail.Message = fmt.Sprintf("Permission denied: required scope %s [%d]", recommended, larkCode)
 		if isBot {
 			exitErr.Detail.Hint = "enable the scope in developer console (see console_url)"

cmd/root_integration_test.go

@@ -161,160 +161,8 @@ func resetBuffers(stdout *bytes.Buffer, stderr *bytes.Buffer) {
 	stderr.Reset()
 }
 
-// --- api command ---
-
-func TestIntegration_Api_BusinessError_OutputsEnvelope(t *testing.T) {
-	f, stdout, stderr, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "e2e-api-err", AppSecret: "secret", Brand: core.BrandFeishu,
-	})
-	reg.Register(&httpmock.Stub{
-		URL: "/open-apis/im/v1/messages",
-		Body: map[string]interface{}{
-			"code": 230002,
-			"msg":  "Bot/User can NOT be out of the chat.",
-			"error": map[string]interface{}{
-				"log_id": "test-log-id-001",
-			},
-		},
-	})
-
-	rootCmd := buildIntegrationRootCmd(t, f)
-	code := executeRootIntegration(t, f, rootCmd, []string{
-		"api", "--as", "bot", "POST", "/open-apis/im/v1/messages",
-		"--params", `{"receive_id_type":"chat_id"}`,
-		"--data", `{"receive_id":"oc_xxx","msg_type":"text","content":"{\"text\":\"test\"}"}`,
-	})
-
-	// api uses MarkRaw: detail preserved, no enrichment
-	assertEnvelope(t, code, output.ExitAPI, stdout, stderr, output.ErrorEnvelope{
-		OK:       false,
-		Identity: "bot",
-		Error: &output.ErrDetail{
-			Type:    "api_error",
-			Code:    230002,
-			Message: "API error: [230002] Bot/User can NOT be out of the chat.",
-			Detail: map[string]interface{}{
-				"log_id": "test-log-id-001",
-			},
-		},
-	})
-}
-
-func TestIntegration_Api_PermissionError_NotEnriched(t *testing.T) {
-	f, stdout, stderr, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "e2e-api-perm", AppSecret: "secret", Brand: core.BrandFeishu,
-	})
-	reg.Register(&httpmock.Stub{
-		URL: "/open-apis/test/perm",
-		Body: map[string]interface{}{
-			"code": 99991672,
-			"msg":  "scope not enabled for this app",
-			"error": map[string]interface{}{
-				"permission_violations": []interface{}{
-					map[string]interface{}{"subject": "calendar:calendar:readonly"},
-				},
-				"log_id": "test-log-id-perm",
-			},
-		},
-	})
-
-	rootCmd := buildIntegrationRootCmd(t, f)
-	code := executeRootIntegration(t, f, rootCmd, []string{
-		"api", "--as", "bot", "GET", "/open-apis/test/perm",
-	})
-
-	// api uses MarkRaw: enrichment skipped, detail preserved, no console_url
-	assertEnvelope(t, code, output.ExitAPI, stdout, stderr, output.ErrorEnvelope{
-		OK:       false,
-		Identity: "bot",
-		Error: &output.ErrDetail{
-			Type:    "permission",
-			Code:    99991672,
-			Message: "Permission denied [99991672]",
-			Hint:    "check app permissions or re-authorize: lark-cli auth login",
-			Detail: map[string]interface{}{
-				"permission_violations": []interface{}{
-					map[string]interface{}{"subject": "calendar:calendar:readonly"},
-				},
-				"log_id": "test-log-id-perm",
-			},
-		},
-	})
-}
-
 // --- service command ---
 
-func TestIntegration_Service_BusinessError_OutputsEnvelope(t *testing.T) {
-	f, stdout, stderr, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "e2e-svc-err", AppSecret: "secret", Brand: core.BrandFeishu,
-	})
-	reg.Register(&httpmock.Stub{
-		URL: "/open-apis/im/v1/chats/oc_fake",
-		Body: map[string]interface{}{
-			"code": 99992356,
-			"msg":  "id not exist",
-			"error": map[string]interface{}{
-				"log_id": "test-log-id-svc",
-			},
-		},
-	})
-
-	rootCmd := buildIntegrationRootCmd(t, f)
-	code := executeRootIntegration(t, f, rootCmd, []string{
-		"im", "chats", "get", "--params", `{"chat_id":"oc_fake"}`, "--as", "bot",
-	})
-
-	// service: no MarkRaw, non-permission error — detail preserved
-	assertEnvelope(t, code, output.ExitAPI, stdout, stderr, output.ErrorEnvelope{
-		OK:       false,
-		Identity: "bot",
-		Error: &output.ErrDetail{
-			Type:    "api_error",
-			Code:    99992356,
-			Message: "API error: [99992356] id not exist",
-			Detail: map[string]interface{}{
-				"log_id": "test-log-id-svc",
-			},
-		},
-	})
-}
-
-func TestIntegration_Service_PermissionError_Enriched(t *testing.T) {
-	f, stdout, stderr, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "e2e-svc-perm", AppSecret: "secret", Brand: core.BrandFeishu,
-	})
-	reg.Register(&httpmock.Stub{
-		URL: "/open-apis/im/v1/chats/oc_test",
-		Body: map[string]interface{}{
-			"code": 99991672,
-			"msg":  "scope not enabled",
-			"error": map[string]interface{}{
-				"permission_violations": []interface{}{
-					map[string]interface{}{"subject": "im:chat:readonly"},
-				},
-			},
-		},
-	})
-
-	rootCmd := buildIntegrationRootCmd(t, f)
-	code := executeRootIntegration(t, f, rootCmd, []string{
-		"im", "chats", "get", "--params", `{"chat_id":"oc_test"}`, "--as", "bot",
-	})
-
-	// service: no MarkRaw — enrichment applied, detail cleared, console_url set
-	assertEnvelope(t, code, output.ExitAPI, stdout, stderr, output.ErrorEnvelope{
-		OK:       false,
-		Identity: "bot",
-		Error: &output.ErrDetail{
-			Type:       "permission",
-			Code:       99991672,
-			Message:    "App scope not enabled: required scope im:chat:readonly [99991672]",
-			Hint:       "enable the scope in developer console (see console_url)",
-			ConsoleURL: "https://open.feishu.cn/page/scope-apply?clientID=e2e-svc-perm&scopes=im%3Achat%3Areadonly",
-		},
-	})
-}
-
 func TestIntegration_StrictModeBot_ProfileOverride_HidesCommandsInHelp(t *testing.T) {
 	f, stdout, stderr := newStrictModeDefaultFactory(t, "target", core.StrictModeBot)
 	rootCmd := buildStrictModeIntegrationRootCmd(t, f)
@@ -524,7 +372,7 @@ func TestIntegration_Shortcut_BusinessError_OutputsEnvelope(t *testing.T) {
 		"im", "+messages-send", "--as", "bot", "--chat-id", "oc_xxx", "--text", "test",
 	})
 
-	// shortcut: no MarkRaw, no HandleResponse — error via DoAPIJSON path
+	// shortcut: typed error via DoAPIJSON path
 	assertEnvelope(t, code, output.ExitAPI, stdout, stderr, output.ErrorEnvelope{
 		OK:       false,
 		Identity: "bot",
@@ -536,11 +384,8 @@ func TestIntegration_Shortcut_BusinessError_OutputsEnvelope(t *testing.T) {
 	})
 }
 
-// TestSetupNotices_ColdStart_NoNotice verifies that a missing stamp
-// produces no skills key in the composed notice. Users who installed
-// skills via `npx skills add` (no stamp) must not see the misleading
-// "not installed" notice — only `lark-cli update` users opt into the
-// drift tracker.
+// TestSetupNotices_ColdStart_NoNotice verifies that missing state
+// produces no skills key in the composed notice.
 func TestSetupNotices_ColdStart_NoNotice(t *testing.T) {
 	clearNoticeEnv(t)
 	dir := t.TempDir()
@@ -571,13 +416,13 @@ func TestSetupNotices_ColdStart_NoNotice(t *testing.T) {
 	}
 }
 
-// TestSetupNotices_InSync verifies that a matching stamp produces no
+// TestSetupNotices_InSync verifies that matching state produces no
 // skills key in the composed notice.
 func TestSetupNotices_InSync(t *testing.T) {
 	clearNoticeEnv(t)
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-	if err := skillscheck.WriteStamp("1.0.21"); err != nil {
+	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.21"}); err != nil {
 		t.Fatal(err)
 	}
 
@@ -604,13 +449,13 @@ func TestSetupNotices_InSync(t *testing.T) {
 	}
 }
 
-// TestSetupNotices_Drift verifies a mismatching stamp produces the
+// TestSetupNotices_Drift verifies mismatching state produces the
 // drift message with both current and target populated.
 func TestSetupNotices_Drift(t *testing.T) {
 	clearNoticeEnv(t)
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-	if err := skillscheck.WriteStamp("1.0.20"); err != nil {
+	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.20"}); err != nil {
 		t.Fatal(err)
 	}
 
@@ -659,7 +504,7 @@ func TestSetupNotices_BothUpdateAndSkills(t *testing.T) {
 	clearNoticeEnv(t)
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-	if err := skillscheck.WriteStamp("1.0.20"); err != nil {
+	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.20"}); err != nil {
 		t.Fatal(err)
 	}
 

cmd/root_test.go

@@ -4,19 +4,23 @@
 package cmd
 
 import (
+	"bytes"
+	"encoding/json"
+	"fmt"
 	"strings"
 	"testing"
 
+	"github.com/spf13/cobra"
+
 	"github.com/larksuite/cli/cmd/api"
 	"github.com/larksuite/cli/cmd/auth"
 	cmdconfig "github.com/larksuite/cli/cmd/config"
 	"github.com/larksuite/cli/cmd/schema"
+	"github.com/larksuite/cli/errs"
 	internalauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/registry"
-	"github.com/spf13/cobra"
 )
 
 // TestPersistentPreRunE_AuthCheckDisabledAnnotations verifies that
@@ -68,273 +72,6 @@ func TestPersistentPreRunE_ConfigSubcommands(t *testing.T) {
 	}
 }
 
-func TestHandleRootError_RawError_SkipsEnrichmentButWritesEnvelope(t *testing.T) {
-	f, _, stderr, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-
-	// Create a permission error (would normally be enriched) and mark it Raw
-	err := output.ErrAPI(output.LarkErrAppScopeNotEnabled, "API error: [99991672] scope not enabled", map[string]interface{}{
-		"permission_violations": []interface{}{
-			map[string]interface{}{"subject": "calendar:calendar:readonly"},
-		},
-	})
-	err.Raw = true
-
-	code := handleRootError(f, err)
-	if code != output.ExitAPI {
-		t.Errorf("expected exit code %d, got %d", output.ExitAPI, code)
-	}
-	// stderr should contain the error envelope
-	if stderr.Len() == 0 {
-		t.Error("expected non-empty stderr for Raw error — WriteErrorEnvelope should always run")
-	}
-	// The message should NOT have been enriched by enrichPermissionError
-	// (ErrAPI sets "Permission denied [code]" but enrichment would replace it with "App scope not enabled: ...")
-	if strings.Contains(err.Error(), "App scope not enabled") {
-		t.Errorf("expected message not enriched, got: %s", err.Error())
-	}
-	// Detail.Detail should be preserved (enrichPermissionError clears it to nil)
-	if err.Detail != nil && err.Detail.Detail == nil {
-		t.Error("expected Detail.Detail to be preserved, but it was cleared")
-	}
-}
-
-func TestHandleRootError_NonRawError_EnrichesAndWritesEnvelope(t *testing.T) {
-	f, _, stderr, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-
-	// Create a permission error without Raw — should be enriched
-	err := output.ErrAPI(output.LarkErrAppScopeNotEnabled, "API error: [99991672] scope not enabled", map[string]interface{}{
-		"permission_violations": []interface{}{
-			map[string]interface{}{"subject": "calendar:calendar:readonly"},
-		},
-	})
-
-	code := handleRootError(f, err)
-	if code != output.ExitAPI {
-		t.Errorf("expected exit code %d, got %d", output.ExitAPI, code)
-	}
-	// stderr should contain the error envelope
-	if stderr.Len() == 0 {
-		t.Error("expected non-empty stderr for non-Raw error")
-	}
-	// The message should have been enriched
-	if !strings.Contains(err.Error(), "App scope not enabled") {
-		t.Errorf("expected enriched message, got: %s", err.Error())
-	}
-}
-
-func TestEnrichPermissionError_SpecialCharsEscaped(t *testing.T) {
-	tests := []struct {
-		name      string
-		appID     string
-		scope     string
-		wantInURL string // substring that must appear in console_url
-		denyInURL string // substring that must NOT appear raw in console_url
-	}{
-		{
-			name:      "ampersand in scope",
-			appID:     "cli_good",
-			scope:     "scope&evil=injected",
-			wantInURL: "scopes=scope%26evil%3Dinjected",
-			denyInURL: "scopes=scope&evil=injected",
-		},
-		{
-			name:      "hash in scope",
-			appID:     "cli_good",
-			scope:     "scope#fragment",
-			wantInURL: "scopes=scope%23fragment",
-			denyInURL: "scopes=scope#fragment",
-		},
-		{
-			name:      "space in scope",
-			appID:     "cli_good",
-			scope:     "scope with spaces",
-			wantInURL: "scopes=scope+with+spaces",
-		},
-		{
-			name:      "special chars in appID",
-			appID:     "app&id=bad",
-			scope:     "calendar:calendar:readonly",
-			wantInURL: "clientID=app%26id%3Dbad",
-			denyInURL: "clientID=app&id=bad",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-				AppID: tt.appID, AppSecret: "test-secret", Brand: core.BrandFeishu,
-			})
-
-			exitErr := output.ErrAPI(output.LarkErrAppScopeNotEnabled, "scope not enabled", map[string]interface{}{
-				"permission_violations": []interface{}{
-					map[string]interface{}{"subject": tt.scope},
-				},
-			})
-
-			handleRootError(f, exitErr)
-
-			consoleURL := exitErr.Detail.ConsoleURL
-			if consoleURL == "" {
-				t.Fatal("expected console_url to be set")
-			}
-			if !strings.Contains(consoleURL, tt.wantInURL) {
-				t.Errorf("console_url missing expected escaped value\n  want substring: %s\n  got url:        %s", tt.wantInURL, consoleURL)
-			}
-			if tt.denyInURL != "" && strings.Contains(consoleURL, tt.denyInURL) {
-				t.Errorf("console_url contains unescaped dangerous value\n  deny substring: %s\n  got url:        %s", tt.denyInURL, consoleURL)
-			}
-		})
-	}
-}
-
-func TestEnrichMissingScopeError_ServiceMethodUsesLocalScopesWhenNoUAT(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-	f.ResolvedIdentity = core.AsUser
-
-	var target registry.CommandEntry
-	for _, entry := range registry.CollectCommandScopes([]string{"calendar"}, "user") {
-		if len(entry.Scopes) == 1 && entry.Scopes[0] == "calendar:calendar.event:create" {
-			target = entry
-			break
-		}
-	}
-	if target.Command == "" {
-		t.Fatal("failed to locate a calendar create command in local registry metadata")
-	}
-	parts := strings.Split(target.Command, " ")
-	if len(parts) != 2 {
-		t.Fatalf("expected resource/method command, got %q", target.Command)
-	}
-
-	root := &cobra.Command{Use: "lark-cli"}
-	serviceCmd := &cobra.Command{Use: "calendar"}
-	resourceCmd := &cobra.Command{Use: parts[0]}
-	methodCmd := &cobra.Command{Use: parts[1]}
-	root.AddCommand(serviceCmd)
-	serviceCmd.AddCommand(resourceCmd)
-	resourceCmd.AddCommand(methodCmd)
-	f.CurrentCommand = methodCmd
-
-	exitErr := output.Errorf(output.ExitAPI, "api_error", "API call failed: %s", &internalauth.NeedAuthorizationError{})
-	enrichMissingScopeError(f, exitErr)
-
-	if exitErr.Code != output.ExitAPI {
-		t.Fatalf("expected exit code %d, got %d", output.ExitAPI, exitErr.Code)
-	}
-	if exitErr.Detail == nil || exitErr.Detail.Type != "api_error" {
-		t.Fatalf("expected api_error detail, got %+v", exitErr.Detail)
-	}
-	if !strings.Contains(exitErr.Detail.Message, "need_user_authorization") {
-		t.Fatalf("expected original need_user_authorization message, got %q", exitErr.Detail.Message)
-	}
-	if !strings.Contains(exitErr.Detail.Hint, "current command requires scope(s): calendar:calendar.event:create") {
-		t.Fatalf("expected scope guidance in hint, got %q", exitErr.Detail.Hint)
-	}
-	if strings.Contains(exitErr.Detail.Hint, "lark-cli auth login --scope") {
-		t.Fatalf("expected hint without auth login command, got %q", exitErr.Detail.Hint)
-	}
-	if exitErr.Detail.Detail != nil {
-		t.Fatalf("expected detail to remain nil, got %#v", exitErr.Detail.Detail)
-	}
-}
-
-func TestEnrichMissingScopeError_ShortcutUsesDeclaredScopesWhenNoUAT(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-	f.ResolvedIdentity = core.AsUser
-
-	root := &cobra.Command{Use: "lark-cli"}
-	serviceCmd := &cobra.Command{Use: "docs"}
-	shortcutCmd := &cobra.Command{Use: "+create"}
-	root.AddCommand(serviceCmd)
-	serviceCmd.AddCommand(shortcutCmd)
-	f.CurrentCommand = shortcutCmd
-
-	exitErr := output.ErrNetwork("API call failed: %s", &internalauth.NeedAuthorizationError{})
-	enrichMissingScopeError(f, exitErr)
-
-	if exitErr.Code != output.ExitNetwork {
-		t.Fatalf("expected exit code %d, got %d", output.ExitNetwork, exitErr.Code)
-	}
-	if exitErr.Detail == nil || exitErr.Detail.Type != "network" {
-		t.Fatalf("expected network detail, got %+v", exitErr.Detail)
-	}
-	if !strings.Contains(exitErr.Detail.Message, "need_user_authorization") {
-		t.Fatalf("expected original need_user_authorization message, got %q", exitErr.Detail.Message)
-	}
-	if !strings.Contains(exitErr.Detail.Hint, "current command requires scope(s): docx:document:create") {
-		t.Fatalf("expected shortcut scope hint, got %q", exitErr.Detail.Hint)
-	}
-	if strings.Contains(exitErr.Detail.Hint, "lark-cli auth login --scope") {
-		t.Fatalf("expected hint without auth login command, got %q", exitErr.Detail.Hint)
-	}
-	if exitErr.Detail.Detail != nil {
-		t.Fatalf("expected detail to remain nil, got %#v", exitErr.Detail.Detail)
-	}
-}
-
-func TestEnrichMissingScopeError_ShortcutIncludesConditionalScopes(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-	f.ResolvedIdentity = core.AsUser
-
-	root := &cobra.Command{Use: "lark-cli"}
-	serviceCmd := &cobra.Command{Use: "drive"}
-	shortcutCmd := &cobra.Command{Use: "+status"}
-	root.AddCommand(serviceCmd)
-	serviceCmd.AddCommand(shortcutCmd)
-	f.CurrentCommand = shortcutCmd
-
-	exitErr := output.ErrNetwork("API call failed: %s", &internalauth.NeedAuthorizationError{})
-	enrichMissingScopeError(f, exitErr)
-
-	if exitErr.Detail == nil {
-		t.Fatal("expected error detail")
-	}
-	if !strings.Contains(exitErr.Detail.Hint, "current command requires scope(s): drive:drive.metadata:readonly, drive:file:download") {
-		t.Fatalf("expected conditional scope hint for drive +status, got %q", exitErr.Detail.Hint)
-	}
-}
-
-func TestEnrichMissingScopeError_AppendsExistingHint(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-	f.ResolvedIdentity = core.AsUser
-
-	root := &cobra.Command{Use: "lark-cli"}
-	serviceCmd := &cobra.Command{Use: "docs"}
-	shortcutCmd := &cobra.Command{Use: "+create"}
-	root.AddCommand(serviceCmd)
-	serviceCmd.AddCommand(shortcutCmd)
-	f.CurrentCommand = shortcutCmd
-
-	exitErr := output.ErrNetwork("API call failed: %s", &internalauth.NeedAuthorizationError{})
-	exitErr.Detail.Hint = "existing hint"
-	enrichMissingScopeError(f, exitErr)
-
-	want := "existing hint\ncurrent command requires scope(s): docx:document:create"
-	if exitErr.Detail.Hint != want {
-		t.Fatalf("expected appended hint %q, got %q", want, exitErr.Detail.Hint)
-	}
-}
-
 func TestRootLong_AgentSkillsLinkTargetsReadmeSection(t *testing.T) {
 	if !strings.Contains(rootLong, "https://github.com/larksuite/cli#agent-skills") {
 		t.Fatalf("root help should link to the README Agent Skills section, got:\n%s", rootLong)
@@ -396,3 +133,227 @@ func TestIsCompletionCommand(t *testing.T) {
 		})
 	}
 }
+
+// TestPromoteConfigError_* lives with the implementation in
+// internal/errcompat/promote_test.go.
+
+// TestHandleRootError_SecurityPolicyKeepsLegacyEnvelope pins the carve-out
+// for *errs.SecurityPolicyError: it does NOT go through the typed envelope
+// writer. Downstream OAuth/policy consumers parse a wire format that
+// predates the typed taxonomy and depend on:
+//   - error.type == "auth_error" (not the Category literal "policy")
+//   - error.code is a string ("challenge_required" / "access_denied"), not a number
+//   - error.retryable is present at the top of the error object
+//   - exit code 1 (not ExitContentSafety 6)
+//
+// Migration of this category to the typed envelope is deferred to a later PR.
+func TestHandleRootError_SecurityPolicyKeepsLegacyEnvelope(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	cases := []struct {
+		name     string
+		subtype  errs.Subtype
+		code     int
+		wantCode string
+	}{
+		{"challenge_required", errs.SubtypeChallengeRequired, 21000, "challenge_required"},
+		{"access_denied", errs.SubtypeAccessDenied, 21001, "access_denied"},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			f, _, _, _ := cmdutil.TestFactory(t, nil)
+			errOut := &bytes.Buffer{}
+			f.IOStreams.ErrOut = errOut
+
+			spErr := &errs.SecurityPolicyError{
+				Problem: errs.Problem{
+					Category: errs.CategoryPolicy,
+					Subtype:  tc.subtype,
+					Code:     tc.code,
+					Message:  "blocked by access policy",
+					Hint:     "complete challenge in your browser",
+				},
+				ChallengeURL: "https://example.com/challenge",
+			}
+
+			gotExit := handleRootError(f, spErr)
+			if gotExit != 1 {
+				t.Errorf("exit code = %d, want 1 (legacy carve-out)", gotExit)
+			}
+
+			var env map[string]any
+			if err := json.Unmarshal(errOut.Bytes(), &env); err != nil {
+				t.Fatalf("envelope is not valid JSON: %v\n%s", err, errOut.String())
+			}
+			errObj, ok := env["error"].(map[string]any)
+			if !ok {
+				t.Fatalf("envelope missing top-level error object: %s", errOut.String())
+			}
+			if got := errObj["type"]; got != "auth_error" {
+				t.Errorf("error.type = %v, want %q", got, "auth_error")
+			}
+			if got := errObj["code"]; got != tc.wantCode {
+				t.Errorf("error.code = %v (%T), want %q (string)", got, got, tc.wantCode)
+			}
+			if got, ok := errObj["retryable"].(bool); !ok || got {
+				t.Errorf("error.retryable = %v (%T), want false (bool)", errObj["retryable"], errObj["retryable"])
+			}
+			if got := errObj["challenge_url"]; got != "https://example.com/challenge" {
+				t.Errorf("error.challenge_url = %v, want challenge url", got)
+			}
+			if got := errObj["hint"]; got != "complete challenge in your browser" {
+				t.Errorf("error.hint = %v, want hint message", got)
+			}
+			// And the typed-only fields must NOT appear on this envelope.
+			for _, leaked := range []string{"subtype", "missing_scopes", "console_url"} {
+				if _, exists := errObj[leaked]; exists {
+					t.Errorf("error.%s leaked into legacy security envelope: %v", leaked, errObj[leaked])
+				}
+			}
+		})
+	}
+}
+
+// newAuthErrorWithNeedAuthMarker builds a typed *errs.AuthenticationError whose Message
+// contains the need_user_authorization marker — the same shape that
+// resolveAccessToken now produces when the credential chain returns
+// *internalauth.NeedAuthorizationError.
+func newAuthErrorWithNeedAuthMarker() *errs.AuthenticationError {
+	cause := &internalauth.NeedAuthorizationError{UserOpenId: "u_xxx"}
+	return &errs.AuthenticationError{
+		Problem: errs.Problem{
+			Category: errs.CategoryAuthentication,
+			Subtype:  errs.SubtypeUnknown,
+			Message:  fmt.Sprintf("API call failed: %s", cause),
+		},
+		Cause: cause,
+	}
+}
+
+// TestApplyNeedAuthorizationHint_ServiceMethodUsesLocalScopesWhenNoUAT pins
+// that a typed AuthenticationError carrying the need_user_authorization marker gets a
+// declared-scopes Hint appended when the current command is a registered
+// service method.
+func TestApplyNeedAuthorizationHint_ServiceMethodUsesLocalScopesWhenNoUAT(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+	f.ResolvedIdentity = core.AsUser
+
+	var target registry.CommandEntry
+	for _, entry := range registry.CollectCommandScopes([]string{"calendar"}, "user") {
+		if len(entry.Scopes) == 1 && entry.Scopes[0] == "calendar:calendar.event:create" {
+			target = entry
+			break
+		}
+	}
+	if target.Command == "" {
+		t.Fatal("failed to locate a calendar create command in local registry metadata")
+	}
+	parts := strings.Split(target.Command, " ")
+	if len(parts) != 2 {
+		t.Fatalf("expected resource/method command, got %q", target.Command)
+	}
+
+	root := &cobra.Command{Use: "lark-cli"}
+	serviceCmd := &cobra.Command{Use: "calendar"}
+	resourceCmd := &cobra.Command{Use: parts[0]}
+	methodCmd := &cobra.Command{Use: parts[1]}
+	root.AddCommand(serviceCmd)
+	serviceCmd.AddCommand(resourceCmd)
+	resourceCmd.AddCommand(methodCmd)
+	f.CurrentCommand = methodCmd
+
+	authErr := newAuthErrorWithNeedAuthMarker()
+	applyNeedAuthorizationHint(f, authErr)
+
+	if authErr.Category != errs.CategoryAuthentication {
+		t.Errorf("Category = %q, want authentication", authErr.Category)
+	}
+	if !strings.Contains(authErr.Message, "need_user_authorization") {
+		t.Errorf("Message should preserve need_user_authorization marker; got %q", authErr.Message)
+	}
+	if !strings.Contains(authErr.Hint, "current command requires scope(s): calendar:calendar.event:create") {
+		t.Errorf("expected declared-scope hint, got %q", authErr.Hint)
+	}
+}
+
+// TestApplyNeedAuthorizationHint_ShortcutUsesDeclaredScopesWhenNoUAT pins the
+// same hint behavior for mounted shortcut commands.
+func TestApplyNeedAuthorizationHint_ShortcutUsesDeclaredScopesWhenNoUAT(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+	f.ResolvedIdentity = core.AsUser
+
+	root := &cobra.Command{Use: "lark-cli"}
+	serviceCmd := &cobra.Command{Use: "docs"}
+	shortcutCmd := &cobra.Command{Use: "+create"}
+	root.AddCommand(serviceCmd)
+	serviceCmd.AddCommand(shortcutCmd)
+	f.CurrentCommand = shortcutCmd
+
+	authErr := newAuthErrorWithNeedAuthMarker()
+	applyNeedAuthorizationHint(f, authErr)
+
+	if !strings.Contains(authErr.Hint, "current command requires scope(s): docx:document:create") {
+		t.Errorf("expected shortcut scope hint, got %q", authErr.Hint)
+	}
+}
+
+// TestApplyNeedAuthorizationHint_ShortcutIncludesConditionalScopes pins that
+// conditional scopes declared on a shortcut surface in the hint.
+func TestApplyNeedAuthorizationHint_ShortcutIncludesConditionalScopes(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+	f.ResolvedIdentity = core.AsUser
+
+	root := &cobra.Command{Use: "lark-cli"}
+	serviceCmd := &cobra.Command{Use: "drive"}
+	shortcutCmd := &cobra.Command{Use: "+status"}
+	root.AddCommand(serviceCmd)
+	serviceCmd.AddCommand(shortcutCmd)
+	f.CurrentCommand = shortcutCmd
+
+	authErr := newAuthErrorWithNeedAuthMarker()
+	applyNeedAuthorizationHint(f, authErr)
+
+	if !strings.Contains(authErr.Hint, "current command requires scope(s): drive:drive.metadata:readonly, drive:file:download") {
+		t.Errorf("expected conditional scope hint for drive +status, got %q", authErr.Hint)
+	}
+}
+
+// TestApplyNeedAuthorizationHint_AppendsExistingHint pins that the
+// declared-scopes guidance is appended (separated by newline) when the typed
+// AuthenticationError already carries a Hint from elsewhere.
+func TestApplyNeedAuthorizationHint_AppendsExistingHint(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+	f.ResolvedIdentity = core.AsUser
+
+	root := &cobra.Command{Use: "lark-cli"}
+	serviceCmd := &cobra.Command{Use: "docs"}
+	shortcutCmd := &cobra.Command{Use: "+create"}
+	root.AddCommand(serviceCmd)
+	serviceCmd.AddCommand(shortcutCmd)
+	f.CurrentCommand = shortcutCmd
+
+	authErr := newAuthErrorWithNeedAuthMarker()
+	authErr.Hint = "existing hint"
+	applyNeedAuthorizationHint(f, authErr)
+
+	want := "existing hint\ncurrent command requires scope(s): docx:document:create"
+	if authErr.Hint != want {
+		t.Errorf("expected appended hint %q, got %q", want, authErr.Hint)
+	}
+}

cmd/schema/schema.go

@@ -14,6 +14,7 @@ import (
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/registry"
+	"github.com/larksuite/cli/internal/schema"
 	"github.com/larksuite/cli/internal/util"
 	"github.com/spf13/cobra"
 )
@@ -24,7 +25,8 @@ type SchemaOptions struct {
 	Ctx     context.Context
 
 	// Positional args
-	Path string
+	Path      string   // first positional, when only one is given
+	ExtraArgs []string // 2nd+ positional args (space-separated form)
 
 	// Flags
 	Format string
@@ -359,13 +361,16 @@ func NewCmdSchema(f *cmdutil.Factory, runF func(*SchemaOptions) error) *cobra.Co
 	opts := &SchemaOptions{Factory: f}
 
 	cmd := &cobra.Command{
-		Use:   "schema [path]",
+		Use:   "schema [path | service resource method]",
 		Short: "View API method parameters, types, and scopes",
-		Args:  cobra.MaximumNArgs(1),
+		Args:  cobra.MaximumNArgs(8),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if len(args) > 0 {
 				opts.Path = args[0]
 			}
+			if len(args) > 1 {
+				opts.ExtraArgs = args[1:]
+			}
 			opts.Ctx = cmd.Context()
 			if runF != nil {
 				return runF(opts)
@@ -380,60 +385,108 @@ func NewCmdSchema(f *cmdutil.Factory, runF func(*SchemaOptions) error) *cobra.Co
 	cmdutil.RegisterFlagCompletion(cmd, "format", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
 		return []string{"json", "pretty"}, cobra.ShellCompDirectiveNoFileComp
 	})
-	cmdutil.SetRisk(cmd, "read")
+	cmdutil.SetRisk(cmd, cmdutil.RiskRead)
 
 	return cmd
 }
 
 // completeSchemaPath provides tab-completion for the schema path argument.
-// It handles dotted resource names (e.g. app.table.fields) by iterating all
-// resources and classifying each as a prefix-match or fully-matched.
+// It handles both legacy dotted resource names (e.g. app.table.fields) and the
+// newer space-separated form (e.g. `schema im messages reply`).
 func completeSchemaPath(f *cmdutil.Factory) func(*cobra.Command, []string, string) ([]string, cobra.ShellCompDirective) {
 	return func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
-		if len(args) > 0 {
-			return nil, cobra.ShellCompDirectiveNoFileComp
-		}
+		mode := f.ResolveStrictMode(cmd.Context())
 
-		parts := strings.Split(toComplete, ".")
-
-		// Level 1: complete service names
-		if len(parts) <= 1 {
-			var completions []string
-			for _, s := range registry.ListFromMetaProjects() {
-				if strings.HasPrefix(s, toComplete) {
-					completions = append(completions, s+".")
+		// Case 1: legacy "single dotted arg" path — no previous args yet
+		if len(args) == 0 {
+			parts := strings.Split(toComplete, ".")
+			if len(parts) <= 1 {
+				var completions []string
+				for _, s := range registry.ListFromMetaProjects() {
+					if strings.HasPrefix(s, toComplete) {
+						completions = append(completions, s+".")
+					}
+				}
+				return completions, cobra.ShellCompDirectiveNoFileComp | cobra.ShellCompDirectiveNoSpace
+			}
+			serviceName := parts[0]
+			spec := registry.LoadFromMeta(serviceName)
+			if spec == nil {
+				return nil, cobra.ShellCompDirectiveNoFileComp
+			}
+			spec = filterSpecByStrictMode(spec, mode)
+			resources, _ := spec["resources"].(map[string]interface{})
+			if resources == nil {
+				return nil, cobra.ShellCompDirectiveNoFileComp
+			}
+			afterService := strings.Join(parts[1:], ".")
+			completions := completeSchemaPathForSpec(serviceName, resources, afterService)
+			allTrailingDot := len(completions) > 0
+			for _, c := range completions {
+				if !strings.HasSuffix(c, ".") {
+					allTrailingDot = false
+					break
 				}
 			}
-			return completions, cobra.ShellCompDirectiveNoFileComp | cobra.ShellCompDirectiveNoSpace
+			directive := cobra.ShellCompDirectiveNoFileComp
+			if allTrailingDot {
+				directive |= cobra.ShellCompDirectiveNoSpace
+			}
+			return completions, directive
 		}
 
-		serviceName := parts[0]
+		// Case 2: space-form, args already has segments
+		// Walk down service -> resource(s) -> method based on existing args
+		serviceName := args[0]
 		spec := registry.LoadFromMeta(serviceName)
 		if spec == nil {
 			return nil, cobra.ShellCompDirectiveNoFileComp
 		}
-		mode := f.ResolveStrictMode(cmd.Context())
 		spec = filterSpecByStrictMode(spec, mode)
 		resources, _ := spec["resources"].(map[string]interface{})
 		if resources == nil {
 			return nil, cobra.ShellCompDirectiveNoFileComp
 		}
 
-		afterService := strings.Join(parts[1:], ".")
-		completions := completeSchemaPathForSpec(serviceName, resources, afterService)
-
-		allTrailingDot := len(completions) > 0
-		for _, c := range completions {
-			if !strings.HasSuffix(c, ".") {
-				allTrailingDot = false
-				break
+		// args[1:] are resource path segments (possibly partial); current
+		// toComplete is the next segment under cursor.
+		consumed := args[1:]
+		resource, _, remaining := findResourceByPath(resources, consumed)
+		if resource == nil {
+			// Suggest top-level resource names that match toComplete
+			var completions []string
+			for resName := range resources {
+				if strings.HasPrefix(resName, toComplete) {
+					completions = append(completions, resName)
+				}
+			}
+			sort.Strings(completions)
+			return completions, cobra.ShellCompDirectiveNoFileComp
+		}
+		if len(remaining) > 0 {
+			// Already typed past the resource — suggest methods
+			methods, _ := resource["methods"].(map[string]interface{})
+			methods = filterMethodsByStrictMode(methods, mode)
+			var completions []string
+			for mName := range methods {
+				if strings.HasPrefix(mName, toComplete) {
+					completions = append(completions, mName)
+				}
+			}
+			sort.Strings(completions)
+			return completions, cobra.ShellCompDirectiveNoFileComp
+		}
+		// Resource matched exactly, suggest methods
+		methods, _ := resource["methods"].(map[string]interface{})
+		methods = filterMethodsByStrictMode(methods, mode)
+		var completions []string
+		for mName := range methods {
+			if strings.HasPrefix(mName, toComplete) {
+				completions = append(completions, mName)
 			}
 		}
-		directive := cobra.ShellCompDirectiveNoFileComp
-		if allTrailingDot {
-			directive |= cobra.ShellCompDirectiveNoSpace
-		}
-		return completions, directive
+		sort.Strings(completions)
+		return completions, cobra.ShellCompDirectiveNoFileComp
 	}
 }
 
@@ -469,94 +522,231 @@ func schemaRun(opts *SchemaOptions) error {
 	out := opts.Factory.IOStreams.Out
 	mode := opts.Factory.ResolveStrictMode(opts.Ctx)
 
-	if opts.Path == "" {
-		printServices(out)
-		return nil
+	// args may have arrived as a single string (legacy single-arg path) or
+	// split into multiple — normalize to a single args slice.
+	var rawArgs []string
+	if opts.Path != "" {
+		rawArgs = []string{opts.Path}
 	}
-
-	parts := strings.Split(opts.Path, ".")
-
-	serviceName := parts[0]
-	spec := registry.LoadFromMeta(serviceName)
-	if spec == nil {
-		return output.ErrWithHint(output.ExitValidation, "validation",
-			fmt.Sprintf("Unknown service: %s", serviceName),
-			fmt.Sprintf("Available: %s", strings.Join(registry.ListFromMetaProjects(), ", ")))
-	}
-
-	if len(parts) == 1 {
-		if opts.Format == "pretty" {
-			printResourceList(out, spec, mode)
+	if len(opts.ExtraArgs) > 0 {
+		if opts.Path != "" {
+			rawArgs = append([]string{opts.Path}, opts.ExtraArgs...)
 		} else {
-			output.PrintJson(out, filterSpecByStrictMode(spec, mode))
+			rawArgs = append([]string(nil), opts.ExtraArgs...)
 		}
-		return nil
 	}
+	parts := schema.ParsePath(rawArgs)
 
+	if opts.Format == "pretty" {
+		return runPrettyMode(out, parts, mode)
+	}
+	return runJSONMode(out, parts, mode)
+}
+
+// runJSONMode dispatches list/single envelope output based on parts.
+// JSON mode uses embedded data only (bypasses remote overlay) so envelope
+// output is deterministic across machines.
+func runJSONMode(out io.Writer, parts []string, mode core.StrictMode) error {
+	filter := strictModeFilter(mode)
+
+	switch len(parts) {
+	case 0:
+		envs := schema.AssembleAll(filter)
+		output.PrintJson(out, envs)
+		return nil
+	case 1:
+		spec := registry.EmbeddedSpec(parts[0])
+		if spec == nil {
+			return errUnknownEmbeddedService(parts[0])
+		}
+		envs := schema.AssembleService(parts[0], spec, filter)
+		output.PrintJson(out, envs)
+		return nil
+	default:
+		return runJSONForPath(out, parts, filter)
+	}
+}
+
+// runJSONForPath handles len(parts) >= 2: try resource match first, fallback
+// to single-method match. Uses embedded data only.
+func runJSONForPath(out io.Writer, parts []string, filter schema.MethodFilter) error {
+	serviceName := parts[0]
+	spec := registry.EmbeddedSpec(serviceName)
+	if spec == nil {
+		return errUnknownEmbeddedService(serviceName)
+	}
 	resources, _ := spec["resources"].(map[string]interface{})
 	resource, resName, remaining := findResourceByPath(resources, parts[1:])
 	if resource == nil {
-		var resNames []string
+		var names []string
 		for k := range resources {
-			resNames = append(resNames, k)
+			names = append(names, k)
 		}
+		sort.Strings(names)
 		return output.ErrWithHint(output.ExitValidation, "validation",
 			fmt.Sprintf("Unknown resource: %s.%s", serviceName, strings.Join(parts[1:], ".")),
-			fmt.Sprintf("Available: %s", strings.Join(resNames, ", ")))
+			fmt.Sprintf("Available: %s", strings.Join(names, ", ")))
 	}
-
 	if len(remaining) == 0 {
-		if opts.Format == "pretty" {
-			fmt.Fprintf(out, "%s%s.%s%s\n\n", output.Bold, serviceName, resName, output.Reset)
-			methods, _ := resource["methods"].(map[string]interface{})
-			methods = filterMethodsByStrictMode(methods, mode)
-			for _, mName := range sortedKeys(methods) {
-				m, _ := methods[mName].(map[string]interface{})
-				httpMethod := registry.GetStrFromMap(m, "httpMethod")
-				desc := registry.GetStrFromMap(m, "description")
-				fmt.Fprintf(out, "  %-7s %s%s%s  %s%s%s\n", httpMethod, output.Bold, mName, output.Reset, output.Dim, desc, output.Reset)
-			}
-			fmt.Fprintf(out, "\n%sUsage: lark-cli schema %s.%s.<method>%s\n", output.Dim, serviceName, resName, output.Reset)
-		} else {
-			// For JSON output, filter methods in a copy to avoid mutating the registry.
-			if mode.IsActive() {
-				filtered := make(map[string]interface{})
-				for k, v := range resource {
-					filtered[k] = v
-				}
-				if methods, ok := resource["methods"].(map[string]interface{}); ok {
-					filtered["methods"] = filterMethodsByStrictMode(methods, mode)
-				}
-				output.PrintJson(out, filtered)
-			} else {
-				output.PrintJson(out, resource)
-			}
-		}
+		// Resource-scoped envelope array
+		envs := assembleResource(serviceName, resName, resource, filter)
+		output.PrintJson(out, envs)
 		return nil
 	}
+	methodName := remaining[0]
+	methods, _ := resource["methods"].(map[string]interface{})
+	method, ok := methods[methodName].(map[string]interface{})
+	if !ok {
+		var names []string
+		for k := range methods {
+			names = append(names, k)
+		}
+		sort.Strings(names)
+		return output.ErrWithHint(output.ExitValidation, "validation",
+			fmt.Sprintf("Unknown method: %s.%s.%s", serviceName, resName, methodName),
+			fmt.Sprintf("Available: %s", strings.Join(names, ", ")))
+	}
+	if len(remaining) > 1 {
+		// Method exists but caller appended extra segments — reject so they
+		// don't silently get this method's schema when they typo'd the path.
+		return output.ErrWithHint(output.ExitValidation, "validation",
+			fmt.Sprintf("Unknown path: %s.%s.%s",
+				serviceName, resName, strings.Join(remaining, ".")),
+			fmt.Sprintf("Method %q exists but the trailing segments %q do not resolve",
+				methodName, strings.Join(remaining[1:], ".")))
+	}
+	if filter != nil && !filter(method) {
+		// Method exists in spec but filtered out by strict mode
+		return output.ErrWithHint(output.ExitValidation, "validation",
+			fmt.Sprintf("Method %s.%s.%s not available in current identity mode", serviceName, resName, methodName),
+			"Use --as user / --as bot to switch")
+	}
+	env := schema.AssembleEnvelope(serviceName, []string{resName}, methodName, method)
+	output.PrintJson(out, env)
+	return nil
+}
 
+func assembleResource(serviceName, resName string, resource map[string]interface{}, filter schema.MethodFilter) []schema.Envelope {
+	methods, _ := resource["methods"].(map[string]interface{})
+	resourcePath := []string{resName}
+	var envs []schema.Envelope
+	for methodName, raw := range methods {
+		method, ok := raw.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		if filter != nil && !filter(method) {
+			continue
+		}
+		envs = append(envs, schema.AssembleEnvelope(serviceName, resourcePath, methodName, method))
+	}
+	sort.Slice(envs, func(i, j int) bool { return envs[i].Name < envs[j].Name })
+	return envs
+}
+
+// runPrettyMode preserves the existing legacy pretty rendering verbatim.
+// All printServices/printResourceList/printMethodDetail calls stay unchanged.
+func runPrettyMode(out io.Writer, parts []string, mode core.StrictMode) error {
+	if len(parts) == 0 {
+		printServices(out)
+		return nil
+	}
+	serviceName := parts[0]
+	spec := registry.LoadFromMeta(serviceName)
+	if spec == nil {
+		return errUnknownService(serviceName)
+	}
+	if len(parts) == 1 {
+		printResourceList(out, spec, mode)
+		return nil
+	}
+	resources, _ := spec["resources"].(map[string]interface{})
+	resource, resName, remaining := findResourceByPath(resources, parts[1:])
+	if resource == nil {
+		var names []string
+		for k := range resources {
+			names = append(names, k)
+		}
+		sort.Strings(names)
+		return output.ErrWithHint(output.ExitValidation, "validation",
+			fmt.Sprintf("Unknown resource: %s.%s", serviceName, strings.Join(parts[1:], ".")),
+			fmt.Sprintf("Available: %s", strings.Join(names, ", ")))
+	}
+	if len(remaining) == 0 {
+		fmt.Fprintf(out, "%s%s.%s%s\n\n", output.Bold, serviceName, resName, output.Reset)
+		methods, _ := resource["methods"].(map[string]interface{})
+		methods = filterMethodsByStrictMode(methods, mode)
+		for _, mName := range sortedKeys(methods) {
+			m, _ := methods[mName].(map[string]interface{})
+			httpMethod := registry.GetStrFromMap(m, "httpMethod")
+			desc := registry.GetStrFromMap(m, "description")
+			fmt.Fprintf(out, "  %-7s %s%s%s  %s%s%s\n", httpMethod, output.Bold, mName, output.Reset, output.Dim, desc, output.Reset)
+		}
+		fmt.Fprintf(out, "\n%sUsage: lark-cli schema %s.%s.<method>%s\n", output.Dim, serviceName, resName, output.Reset)
+		return nil
+	}
 	methodName := remaining[0]
 	methods, _ := resource["methods"].(map[string]interface{})
 	methods = filterMethodsByStrictMode(methods, mode)
 	method, ok := methods[methodName].(map[string]interface{})
 	if !ok {
-		var mNames []string
+		var names []string
 		for k := range methods {
-			mNames = append(mNames, k)
+			names = append(names, k)
 		}
+		sort.Strings(names)
 		return output.ErrWithHint(output.ExitValidation, "validation",
 			fmt.Sprintf("Unknown method: %s.%s.%s", serviceName, resName, methodName),
-			fmt.Sprintf("Available: %s", strings.Join(mNames, ", ")))
+			fmt.Sprintf("Available: %s", strings.Join(names, ", ")))
 	}
-
-	if opts.Format == "pretty" {
-		printMethodDetail(out, spec, resName, methodName, method)
-	} else {
-		output.PrintJson(out, method)
+	if len(remaining) > 1 {
+		return output.ErrWithHint(output.ExitValidation, "validation",
+			fmt.Sprintf("Unknown path: %s.%s.%s",
+				serviceName, resName, strings.Join(remaining, ".")),
+			fmt.Sprintf("Method %q exists but the trailing segments %q do not resolve",
+				methodName, strings.Join(remaining[1:], ".")))
 	}
+	printMethodDetail(out, spec, resName, methodName, method)
 	return nil
 }
 
+// strictModeFilter adapts core.StrictMode into a schema.MethodFilter, or returns
+// nil if strict mode is not active.
+func strictModeFilter(mode core.StrictMode) schema.MethodFilter {
+	if !mode.IsActive() {
+		return nil
+	}
+	token := registry.IdentityToAccessToken(string(mode.ForcedIdentity()))
+	return func(method map[string]interface{}) bool {
+		tokens, _ := method["accessTokens"].([]interface{})
+		if tokens == nil {
+			return true // permissive when meta_data lacks accessTokens
+		}
+		for _, t := range tokens {
+			if s, _ := t.(string); s == token {
+				return true
+			}
+		}
+		return false
+	}
+}
+
+func errUnknownService(name string) error {
+	return output.ErrWithHint(output.ExitValidation, "validation",
+		fmt.Sprintf("Unknown service: %s", name),
+		fmt.Sprintf("Available: %s", strings.Join(registry.ListFromMetaProjects(), ", ")))
+}
+
+// errUnknownEmbeddedService is the JSON-mode variant: it lists only embedded
+// services (no overlay) because JSON mode itself bypasses overlay; suggesting
+// overlay-only services would mislead callers when those services subsequently
+// fail to resolve in envelope output.
+func errUnknownEmbeddedService(name string) error {
+	return output.ErrWithHint(output.ExitValidation, "validation",
+		fmt.Sprintf("Unknown service: %s", name),
+		fmt.Sprintf("Available: %s", strings.Join(registry.EmbeddedServiceNames(), ", ")))
+}
+
 // filterSpecByStrictMode returns a shallow copy of spec with each resource's methods
 // filtered by strict mode. Returns the original spec when strict mode is off.
 func filterSpecByStrictMode(spec map[string]interface{}, mode core.StrictMode) map[string]interface{} {

cmd/schema/schema_test.go

@@ -5,6 +5,7 @@ package schema
 
 import (
 	"bytes"
+	"encoding/json"
 	"strings"
 	"testing"
 
@@ -33,17 +34,165 @@ func TestSchemaCmd_FlagParsing(t *testing.T) {
 	}
 }
 
-func TestSchemaCmd_NoArgs(t *testing.T) {
+func TestSchemaCmd_NoArgs_Pretty(t *testing.T) {
 	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
 
 	cmd := NewCmdSchema(f, nil)
-	cmd.SetArgs([]string{})
-	err := cmd.Execute()
-	if err != nil {
+	cmd.SetArgs([]string{"--format", "pretty"})
+	if err := cmd.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
 	if !strings.Contains(stdout.String(), "Available services") {
-		t.Error("expected service list output")
+		t.Error("expected service list in pretty mode")
+	}
+}
+
+func TestSchemaCmd_NoArgs_JSON_IsArray(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
+
+	cmd := NewCmdSchema(f, nil)
+	cmd.SetArgs([]string{}) // default --format json
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := strings.TrimSpace(stdout.String())
+	if !strings.HasPrefix(out, "[") {
+		head := out
+		if len(head) > 80 {
+			head = head[:80]
+		}
+		t.Errorf("expected JSON array root, first 80 chars:\n%s", head)
+	}
+	var envs []map[string]interface{}
+	if err := json.Unmarshal([]byte(out), &envs); err != nil {
+		t.Fatalf("unmarshal failed: %v", err)
+	}
+	if len(envs) < 193 {
+		t.Errorf("envelopes count = %d, want >= 193", len(envs))
+	}
+}
+
+func TestSchemaCmd_JSONIsEnvelope(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
+
+	cmd := NewCmdSchema(f, nil)
+	cmd.SetArgs([]string{"im.images.create", "--format", "json"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	var env map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("not valid JSON: %v\n%s", err, stdout.String())
+	}
+	if env["name"] != "im images create" {
+		t.Errorf("name = %v, want \"im images create\"", env["name"])
+	}
+	for _, key := range []string{"description", "inputSchema", "outputSchema", "_meta"} {
+		if _, ok := env[key]; !ok {
+			t.Errorf("missing top-level key: %s", key)
+		}
+	}
+	meta, _ := env["_meta"].(map[string]interface{})
+	if meta["envelope_version"] != "1.0" {
+		t.Errorf("envelope_version = %v, want \"1.0\"", meta["envelope_version"])
+	}
+}
+
+func TestSchemaCmd_SpaceSeparatedPath_EqualsDotted(t *testing.T) {
+	f1, out1, _, _ := cmdutil.TestFactory(t, nil)
+	cmd1 := NewCmdSchema(f1, nil)
+	cmd1.SetArgs([]string{"im", "images", "create"})
+	if err := cmd1.Execute(); err != nil {
+		t.Fatalf("space form failed: %v", err)
+	}
+
+	f2, out2, _, _ := cmdutil.TestFactory(t, nil)
+	cmd2 := NewCmdSchema(f2, nil)
+	cmd2.SetArgs([]string{"im.images.create"})
+	if err := cmd2.Execute(); err != nil {
+		t.Fatalf("dotted form failed: %v", err)
+	}
+
+	if out1.String() != out2.String() {
+		t.Errorf("space and dotted forms produced different output")
+	}
+}
+
+func TestSchemaCmd_ServiceListIsArray(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
+
+	cmd := NewCmdSchema(f, nil)
+	cmd.SetArgs([]string{"im"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	var envs []map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &envs); err != nil {
+		t.Fatalf("unmarshal failed: %v\n%s", err, stdout.String())
+	}
+	if len(envs) == 0 {
+		t.Fatal("expected non-empty array for service im")
+	}
+	for _, e := range envs {
+		name, _ := e["name"].(string)
+		if !strings.HasPrefix(name, "im ") {
+			t.Errorf("envelope name %q does not start with \"im \"", name)
+		}
+	}
+}
+
+func TestSchemaCmd_HighRiskYesInjection(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
+
+	cmd := NewCmdSchema(f, nil)
+	cmd.SetArgs([]string{"im.messages.delete"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	var env map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("unmarshal failed: %v", err)
+	}
+	is, _ := env["inputSchema"].(map[string]interface{})
+	props, _ := is["properties"].(map[string]interface{})
+	if _, ok := props["yes"]; !ok {
+		t.Errorf("inputSchema.properties.yes missing for high-risk-write command")
+	}
+}
+
+func TestSchemaCmd_NoYesForReadRisk(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
+
+	cmd := NewCmdSchema(f, nil)
+	cmd.SetArgs([]string{"im.reactions.list"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	var env map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("unmarshal failed: %v", err)
+	}
+	is, _ := env["inputSchema"].(map[string]interface{})
+	props, _ := is["properties"].(map[string]interface{})
+	if _, ok := props["yes"]; ok {
+		t.Errorf("yes property should not appear for risk=read command")
+	}
+}
+
+func TestSchemaCmd_PrettyUnchanged_KeyTextPresent(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
+
+	cmd := NewCmdSchema(f, nil)
+	cmd.SetArgs([]string{"im.images.create", "--format", "pretty"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	// Existing pretty rendering surfaces these markers — they must still appear
+	for _, want := range []string{"Parameters:", "Response:", "Identity:", "Scopes:", "CLI:"} {
+		if !strings.Contains(out, want) {
+			t.Errorf("pretty output missing marker %q", want)
+		}
 	}
 }
 

cmd/service/service.go

@@ -271,6 +271,11 @@ func serviceMethodRun(opts *ServiceMethodOptions) error {
 		fmt.Fprintf(f.IOStreams.ErrOut, "warning: unknown format %q, falling back to json\n", opts.Format)
 	}
 
+	// Stage 1: enrich the 99991679 (LarkErrUserScopeInsufficient) response
+	// with a per-method recommended `--scope` hint, matching the pre-PR
+	// behaviour. Per-domain typed migration in stage 2+ will lift this
+	// into PermissionError.MissingScopes / ConsoleURL on the typed
+	// envelope; until then the legacy ExitError envelope is preserved.
 	checkErr := scopeAwareChecker(scopes, opts.As.IsBot())
 
 	if opts.PageAll {
@@ -280,7 +285,7 @@ func serviceMethodRun(opts *ServiceMethodOptions) error {
 
 	resp, err := ac.DoAPI(opts.Ctx, request)
 	if err != nil {
-		return output.ErrNetwork("API call failed: %s", err)
+		return err
 	}
 	return client.HandleResponse(resp, client.ResponseOptions{
 		OutputPath:  opts.Output,
@@ -290,10 +295,56 @@ func serviceMethodRun(opts *ServiceMethodOptions) error {
 		ErrOut:      f.IOStreams.ErrOut,
 		FileIO:      f.ResolveFileIO(opts.Ctx),
 		CommandPath: opts.Cmd.CommandPath(),
+		Identity:    opts.As,
 		CheckError:  checkErr,
 	})
 }
 
+// scopeAwareChecker returns an error checker that enriches the
+// LarkErrUserScopeInsufficient (99991679) business error with a
+// per-method recommended `--scope` hint. All other non-zero codes fall
+// through to legacy output.ErrAPI (matching pre-PR behaviour). The
+// identity parameter is accepted to match the client.ResponseOptions
+// CheckError signature; isBotMode is captured from the enclosing call so
+// the recommended scope reflects the caller's identity at request time.
+//
+// Deprecated: stage-1 enrichment for the legacy *output.ExitError envelope.
+// Stage-2 typed migration will lift this into PermissionError.MissingScopes
+// + ConsoleURL on the typed envelope and remove this helper.
+func scopeAwareChecker(scopes []interface{}, isBotMode bool) func(interface{}, core.Identity) error {
+	return func(result interface{}, _ core.Identity) error {
+		resultMap, ok := result.(map[string]interface{})
+		if !ok || resultMap == nil {
+			return nil
+		}
+		code, _ := util.ToFloat64(resultMap["code"])
+		if code == 0 {
+			return nil
+		}
+		larkCode := int(code)
+		msg := registry.GetStrFromMap(resultMap, "msg")
+
+		if larkCode == output.LarkErrUserScopeInsufficient && len(scopes) > 0 {
+			identity := "user"
+			if isBotMode {
+				identity = "tenant"
+			}
+			recommended := registry.SelectRecommendedScope(scopes, identity)
+			// Stage-1 carve-out: this restores the pre-PR scope-insufficient
+			// enrichment (recommended scope + auth-login hint) on the legacy
+			// envelope. The typed migration in stage 2+ will lift this into
+			// PermissionError.MissingScopes / ConsoleURL on the typed wire.
+			return output.ErrWithHint(output.ExitAPI, "permission",
+				fmt.Sprintf("insufficient permissions: [%d] %s", larkCode, msg),
+				fmt.Sprintf("run `lark-cli auth login --scope \"%s\"` in the background. It blocks and outputs a verification URL — retrieve the URL and open it in a browser to complete login.", recommended))
+		}
+
+		// Stage-1 carve-out: matches pre-PR behaviour (legacy ExitError +
+		// ClassifyLarkError). Typed migration is stage-2+.
+		return output.ErrAPI(larkCode, fmt.Sprintf("API error: [%d] %s", larkCode, msg), resultMap["error"])
+	}
+}
+
 // checkServiceScopes pre-checks user scopes before making the API call.
 func checkServiceScopes(ctx context.Context, cred *credential.CredentialProvider, identity core.Identity, config *core.CliConfig, method map[string]interface{}, scopes []interface{}) error {
 	if ctx.Err() != nil {
@@ -339,7 +390,7 @@ func checkServiceScopes(ctx context.Context, cred *credential.CredentialProvider
 	recommended := registry.SelectRecommendedScope(scopes, "user")
 	return output.ErrWithHint(output.ExitAPI, "permission",
 		fmt.Sprintf("insufficient permissions (required scope: %s)", recommended),
-		fmt.Sprintf(`run `+"`"+`lark-cli auth login --scope "%s"`+"`"+` in the background. It blocks and outputs a verification URL — retrieve the URL and open it in a browser to complete login.`, recommended))
+		fmt.Sprintf("run `lark-cli auth login --scope \"%s\"` in the background. It blocks and outputs a verification URL — retrieve the URL and open it in a browser to complete login.", recommended))
 }
 
 // buildServiceRequest parses flags, builds the URL with path/query params, and returns a RawApiRequest.
@@ -474,36 +525,10 @@ func serviceDryRun(f *cmdutil.Factory, request client.RawApiRequest, config *cor
 	return cmdutil.PrintDryRun(f.IOStreams.Out, request, config, format)
 }
 
-// scopeAwareChecker returns an error checker that enriches scope-related errors with login hints.
-func scopeAwareChecker(scopes []interface{}, isBotMode bool) func(interface{}) error {
-	return func(result interface{}) error {
-		resultMap, ok := result.(map[string]interface{})
-		if !ok || resultMap == nil {
-			return nil
-		}
-		code, _ := util.ToFloat64(resultMap["code"])
-		if code == 0 {
-			return nil
-		}
-		larkCode := int(code)
-		msg := registry.GetStrFromMap(resultMap, "msg")
-
-		if larkCode == output.LarkErrUserScopeInsufficient && len(scopes) > 0 {
-			identity := "user"
-			if isBotMode {
-				identity = "tenant"
-			}
-			recommended := registry.SelectRecommendedScope(scopes, identity)
-			return output.ErrWithHint(output.ExitAPI, "permission",
-				fmt.Sprintf("insufficient permissions: [%d] %s", larkCode, msg),
-				fmt.Sprintf(`run `+"`"+`lark-cli auth login --scope "%s"`+"`"+` in the background. It blocks and outputs a verification URL — retrieve the URL and open it in a browser to complete login.`, recommended))
-		}
-
-		return output.ErrAPI(larkCode, fmt.Sprintf("API error: [%d] %s", larkCode, msg), resultMap["error"])
+func servicePaginate(ctx context.Context, ac *client.APIClient, request client.RawApiRequest, format output.Format, jqExpr string, out, errOut io.Writer, pagOpts client.PaginationOptions, checkErr func(interface{}, core.Identity) error) error {
+	if pagOpts.Identity == "" {
+		pagOpts.Identity = request.As
 	}
-}
-
-func servicePaginate(ctx context.Context, ac *client.APIClient, request client.RawApiRequest, format output.Format, jqExpr string, out, errOut io.Writer, pagOpts client.PaginationOptions, checkErr func(interface{}) error) error {
 	// When jq is set, always aggregate all pages then filter.
 	if jqExpr != "" {
 		return client.PaginateWithJq(ctx, ac, request, jqExpr, out, pagOpts, checkErr)
@@ -516,9 +541,9 @@ func servicePaginate(ctx context.Context, ac *client.APIClient, request client.R
 			pf.FormatPage(items)
 		}, pagOpts)
 		if err != nil {
-			return output.ErrNetwork("API call failed: %s", err)
+			return err
 		}
-		if apiErr := checkErr(result); apiErr != nil {
+		if apiErr := checkErr(result, pagOpts.Identity); apiErr != nil {
 			return apiErr
 		}
 		if !hasItems {
@@ -529,9 +554,9 @@ func servicePaginate(ctx context.Context, ac *client.APIClient, request client.R
 	default:
 		result, err := ac.PaginateAll(ctx, request, pagOpts)
 		if err != nil {
-			return output.ErrNetwork("API call failed: %s", err)
+			return err
 		}
-		if apiErr := checkErr(result); apiErr != nil {
+		if apiErr := checkErr(result, pagOpts.Identity); apiErr != nil {
 			return apiErr
 		}
 		output.FormatValue(out, result, format)

cmd/service/service_test.go

@@ -11,7 +11,6 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/spf13/cobra"
 )
 
@@ -412,39 +411,6 @@ func TestServiceMethod_BotMode_Success(t *testing.T) {
 	}
 }
 
-func TestServiceMethod_BotMode_APIError(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app-err", AppSecret: "test-secret-err", Brand: core.BrandFeishu,
-	})
-
-	reg.Register(&httpmock.Stub{
-		URL:  "/open-apis/svc/v1/items",
-		Body: map[string]interface{}{"code": 40003, "msg": "invalid token"},
-	})
-
-	spec := map[string]interface{}{"name": "svc", "servicePath": "/open-apis/svc/v1"}
-	method := map[string]interface{}{"path": "items", "httpMethod": "GET", "parameters": map[string]interface{}{}}
-	cmd := NewCmdServiceMethod(f, spec, method, "list", "items", nil)
-	cmd.SetArgs([]string{"--as", "bot"})
-
-	err := cmd.Execute()
-	if err == nil {
-		t.Fatal("expected API error")
-	}
-	var exitErr *output.ExitError
-	if !isExitError(err, &exitErr) {
-		t.Fatalf("expected ExitError, got: %T %v", err, err)
-	}
-	if exitErr.Code != output.ExitAPI {
-		t.Errorf("expected ExitAPI code, got %d", exitErr.Code)
-	}
-	// stdout must be empty on API error — error details belong in stderr envelope only.
-	// This guards against re-introducing duplicate output (see commit 86215a10).
-	if stdout.Len() > 0 {
-		t.Errorf("expected no stdout on API error, got: %s", stdout.String())
-	}
-}
-
 func TestServiceMethod_BotMode_PageAll_JSON(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app-page", AppSecret: "test-secret-page", Brand: core.BrandFeishu,
@@ -662,73 +628,6 @@ func TestServiceMethod_PageAll_WithJq(t *testing.T) {
 	}
 }
 
-// ── scopeAwareChecker ──
-
-func TestScopeAwareChecker_Success(t *testing.T) {
-	checker := scopeAwareChecker(nil, false)
-	err := checker(map[string]interface{}{"code": 0.0, "msg": "ok"})
-	if err != nil {
-		t.Errorf("expected nil error for code=0, got: %v", err)
-	}
-}
-
-func TestScopeAwareChecker_NonMapResult(t *testing.T) {
-	checker := scopeAwareChecker(nil, false)
-	err := checker("not a map")
-	if err != nil {
-		t.Errorf("expected nil for non-map result, got: %v", err)
-	}
-}
-
-func TestScopeAwareChecker_APIError(t *testing.T) {
-	checker := scopeAwareChecker(nil, false)
-	err := checker(map[string]interface{}{"code": 40003.0, "msg": "bad request"})
-	if err == nil {
-		t.Fatal("expected error for non-zero code")
-	}
-	if !strings.Contains(err.Error(), "API error: [40003]") {
-		t.Errorf("unexpected error: %v", err)
-	}
-}
-
-func TestScopeAwareChecker_ScopeError_UserMode(t *testing.T) {
-	scopes := []interface{}{"calendar:read"}
-	checker := scopeAwareChecker(scopes, false)
-	err := checker(map[string]interface{}{
-		"code": float64(output.LarkErrUserScopeInsufficient),
-		"msg":  "scope insufficient",
-	})
-	if err == nil {
-		t.Fatal("expected permission error")
-	}
-	var exitErr *output.ExitError
-	if !isExitError(err, &exitErr) {
-		t.Fatalf("expected ExitError, got %T", err)
-	}
-	if exitErr.Detail.Type != "permission" {
-		t.Errorf("expected type=permission, got %s", exitErr.Detail.Type)
-	}
-	if !strings.Contains(exitErr.Detail.Hint, "auth login") {
-		t.Errorf("expected auth login hint, got %s", exitErr.Detail.Hint)
-	}
-}
-
-func TestScopeAwareChecker_ScopeError_BotMode(t *testing.T) {
-	scopes := []interface{}{"calendar:read"}
-	checker := scopeAwareChecker(scopes, true)
-	err := checker(map[string]interface{}{
-		"code": float64(output.LarkErrUserScopeInsufficient),
-		"msg":  "scope insufficient",
-	})
-	if err == nil {
-		t.Fatal("expected permission error")
-	}
-	// Bot mode should still include the scope hint
-	if !strings.Contains(err.Error(), "insufficient permissions") {
-		t.Errorf("unexpected error: %v", err)
-	}
-}
-
 // ── file upload ──
 
 func imImageMethod() map[string]interface{} {
@@ -866,13 +765,3 @@ func TestDetectFileFields(t *testing.T) {
 		})
 	}
 }
-
-// ── helpers ──
-
-func isExitError(err error, target **output.ExitError) bool {
-	ee, ok := err.(*output.ExitError)
-	if ok && target != nil {
-		*target = ee
-	}
-	return ok
-}

cmd/update/update.go

@@ -31,15 +31,18 @@ var (
 	currentVersion = func() string { return build.Version }
 	currentOS      = runtime.GOOS
 	newUpdater     = func() *selfupdate.Updater { return selfupdate.New() }
+	syncSkills     = func(opts skillscheck.SyncOptions) *skillscheck.SyncResult { return skillscheck.SyncSkills(opts) }
 )
 
 func isWindows() bool { return currentOS == osWindows }
 
-// normalizeVersion canonicalizes a version string for stamp comparison.
+// normalizeVersion canonicalizes a version string for state comparison.
 // Strips a leading "v" so versions written from Makefile (git describe →
 // "v1.0.0") and npm (no prefix → "1.0.0") compare equal.
 func normalizeVersion(s string) string {
-	return strings.TrimPrefix(strings.TrimSpace(s), "v")
+	s = strings.TrimSpace(s)
+	s = strings.TrimPrefix(s, "v")
+	return strings.TrimPrefix(s, "V")
 }
 
 func releaseURL(version string) string {
@@ -121,7 +124,9 @@ func updateRun(opts *UpdateOptions) error {
 	cur := currentVersion()
 	updater := newUpdater()
 
-	updater.CleanupStaleFiles()
+	if !opts.Check {
+		updater.CleanupStaleFiles()
+	}
 	output.PendingNotice = nil
 
 	// 1. Fetch latest version
@@ -137,13 +142,9 @@ func updateRun(opts *UpdateOptions) error {
 
 	// 3. Compare versions
 	if !opts.Force && !update.IsNewer(latest, cur) {
-		// Run skills sync before returning — covers the case where the
-		// binary is already current but skills were never synced.
-		// Stamp dedup makes this a no-op if skills are already in sync.
-		// Skip side-effects under --check (pure report path per spec §3.6).
-		var skillsResult *selfupdate.NpmResult
+		var skillsResult *skillscheck.SyncResult
 		if !opts.Check {
-			skillsResult = runSkillsAndStamp(updater, io, cur, opts.Force)
+			skillsResult = runSkillsAndState(updater, io, cur, opts.Force)
 		}
 		return reportAlreadyUpToDate(opts, io, cur, latest, skillsResult, opts.Check)
 	}
@@ -185,16 +186,7 @@ func reportCheckResult(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest s
 			"message":     fmt.Sprintf("lark-cli %s %s %s available", cur, symArrow(), latest),
 			"url":         releaseURL(latest), "changelog": changelogURL(),
 		}
-		// skills_status: pure report, no side effect, no stamp write.
-		// ReadStamp errors are silently swallowed — if we can't read the
-		// stamp we just omit the block rather than fail the --check.
-		if stamp, err := skillscheck.ReadStamp(); err == nil {
-			out["skills_status"] = map[string]interface{}{
-				"current": stamp,
-				"target":  cur,
-				"in_sync": stamp == cur,
-			}
-		}
+		applySkillsStatus(out, cur)
 		output.PrintJson(io.Out, out)
 		return nil
 	}
@@ -210,7 +202,7 @@ func reportCheckResult(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest s
 }
 
 func doManualUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, detect selfupdate.DetectResult, updater *selfupdate.Updater) error {
-	skillsResult := runSkillsAndStamp(updater, io, cur, opts.Force)
+	skillsResult := runSkillsAndState(updater, io, cur, opts.Force)
 
 	reason := detect.ManualReason()
 	if opts.JSON {
@@ -288,10 +280,7 @@ func doNpmUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string,
 		return output.ErrBare(output.ExitAPI)
 	}
 
-	// Skills update (best-effort) — uses runSkillsAndStamp so the
-	// stamp gets persisted on success and dedup applies if a previous
-	// run already stamped this version.
-	skillsResult := runSkillsAndStamp(updater, io, latest, opts.Force)
+	skillsResult := runSkillsAndState(updater, io, latest, opts.Force)
 
 	if opts.JSON {
 		result := map[string]interface{}{
@@ -328,27 +317,21 @@ func verificationFailureHint(updater *selfupdate.Updater, latest string) string
 	return fmt.Sprintf("automatic rollback is unavailable on this platform; reinstall manually (skills will not be synced): npm install -g %s@%s && npx skills add larksuite/cli -y -g, or download %s", selfupdate.NpmPackage, latest, releaseURL(latest))
 }
 
-// runSkillsAndStamp triggers updater.RunSkillsUpdate and persists the
-// stamp on success. Skips the npx invocation when the stamp already
-// matches stampVersion (unless force is true). The stamp write failure
-// emits a warning to io.ErrOut but does NOT fail the update command —
-// best-effort. ReadStamp errors are swallowed (fail-closed: treated as
-// out-of-sync, so npx re-runs). Returns nil iff skipped due to stamp
-// dedup; otherwise returns the underlying *NpmResult with Err semantics
-// from RunSkillsUpdate.
-func runSkillsAndStamp(updater *selfupdate.Updater, io *cmdutil.IOStreams, stampVersion string, force bool) *selfupdate.NpmResult {
+func runSkillsAndState(updater *selfupdate.Updater, io *cmdutil.IOStreams, stateVersion string, force bool) *skillscheck.SyncResult {
 	if !force {
-		if existing, _ := skillscheck.ReadStamp(); normalizeVersion(existing) == normalizeVersion(stampVersion) {
+		if existing, ok := skillscheck.ReadSyncedVersion(); ok && normalizeVersion(existing) == normalizeVersion(stateVersion) {
 			return nil
 		}
 	}
-	r := updater.RunSkillsUpdate()
-	if r.Err == nil {
-		if err := skillscheck.WriteStamp(stampVersion); err != nil {
-			fmt.Fprintf(io.ErrOut, "warning: skills synced but stamp not written: %v\n", err)
-		}
+	result := syncSkills(skillscheck.SyncOptions{
+		Version: stateVersion,
+		Force:   force,
+		Runner:  updater,
+	})
+	if result.Err != nil && strings.Contains(result.Err.Error(), "state not written") {
+		fmt.Fprintf(io.ErrOut, "warning: %v\n", result.Err)
 	}
-	return r
+	return result
 }
 
 // reportAlreadyUpToDate emits the JSON / pretty output for the
@@ -356,7 +339,7 @@ func runSkillsAndStamp(updater *selfupdate.Updater, io *cmdutil.IOStreams, stamp
 // fields derived from skillsResult. When check is true, this is the pure
 // report path (spec §3.6): no side-effects, JSON envelope uses
 // skills_status (spec §4.2) instead of skills_action.
-func reportAlreadyUpToDate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, skillsResult *selfupdate.NpmResult, check bool) error {
+func reportAlreadyUpToDate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, skillsResult *skillscheck.SyncResult, check bool) error {
 	if opts.JSON {
 		out := map[string]interface{}{
 			"ok": true, "previous_version": cur, "current_version": cur,
@@ -364,16 +347,7 @@ func reportAlreadyUpToDate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, late
 			"message": fmt.Sprintf("lark-cli %s is already up to date", cur),
 		}
 		if check {
-			// Pure report — read stamp directly, emit skills_status block.
-			// ReadStamp errors are silently swallowed — if we can't read
-			// the stamp we just omit the block rather than fail the --check.
-			if stamp, err := skillscheck.ReadStamp(); err == nil {
-				out["skills_status"] = map[string]interface{}{
-					"current": stamp,
-					"target":  cur,
-					"in_sync": stamp == cur,
-				}
-			}
+			applySkillsStatus(out, cur)
 		} else {
 			applySkillsResult(out, skillsResult)
 		}
@@ -387,36 +361,70 @@ func reportAlreadyUpToDate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, late
 	return nil
 }
 
-// applySkillsResult mutates the JSON envelope to include skills_action
-// (and skills_warning when failed). nil result = "in_sync" (dedup hit).
-func applySkillsResult(env map[string]interface{}, r *selfupdate.NpmResult) {
+func applySkillsStatus(env map[string]interface{}, target string) {
+	state, readable, err := skillscheck.ReadState()
+	if err != nil || !readable || state.Version == "" {
+		return
+	}
+	status := map[string]interface{}{
+		"current": state.Version,
+		"target":  target,
+		"in_sync": normalizeVersion(state.Version) == normalizeVersion(target),
+	}
+	if len(state.OfficialSkills) > 0 {
+		status["official"] = len(state.OfficialSkills)
+	}
+	if len(state.UpdatedSkills) > 0 {
+		status["updated"] = len(state.UpdatedSkills)
+	}
+	if len(state.SkippedDeletedSkills) > 0 {
+		status["skipped_deleted"] = state.SkippedDeletedSkills
+	}
+	env["skills_status"] = status
+}
+
+func applySkillsResult(env map[string]interface{}, r *skillscheck.SyncResult) {
 	switch {
 	case r == nil:
 		env["skills_action"] = "in_sync"
 	case r.Err != nil:
 		env["skills_action"] = "failed"
 		env["skills_warning"] = fmt.Sprintf("skills update failed: %s", r.Err)
-		if detail := strings.TrimSpace(r.Stderr.String()); detail != "" {
-			env["skills_detail"] = selfupdate.Truncate(detail, maxNpmOutput)
-		}
+		env["skills_summary"] = skillsSummary(r)
 	default:
 		env["skills_action"] = "synced"
+		env["skills_summary"] = skillsSummary(r)
 	}
 }
 
-// emitSkillsTextHints prints human-readable feedback about the skills
-// sync result for non-JSON output.
-func emitSkillsTextHints(io *cmdutil.IOStreams, r *selfupdate.NpmResult) {
+func skillsSummary(r *skillscheck.SyncResult) map[string]interface{} {
+	summary := map[string]interface{}{
+		"official":        len(r.Official),
+		"updated":         len(r.Updated),
+		"added":           len(r.Added),
+		"skipped_deleted": len(r.SkippedDeleted),
+	}
+	if len(r.Failed) > 0 {
+		summary["failed"] = r.Failed
+	}
+	return summary
+}
+
+func emitSkillsTextHints(io *cmdutil.IOStreams, r *skillscheck.SyncResult) {
 	switch {
 	case r == nil:
-		// dedup hit — silent (already up to date)
 	case r.Err != nil:
 		fmt.Fprintf(io.ErrOut, "%s Skills update failed: %v\n", symWarn(), r.Err)
-		if detail := strings.TrimSpace(r.Stderr.String()); detail != "" {
-			fmt.Fprintf(io.ErrOut, "  %s\n", selfupdate.Truncate(detail, maxStderrDetail))
+		if len(r.Failed) > 0 {
+			fmt.Fprintf(io.ErrOut, "  Failed skills: %s\n", strings.Join(r.Failed, ", "))
 		}
-		fmt.Fprintf(io.ErrOut, "  Run manually: npx -y skills add larksuite/cli -g -y\n")
+		fmt.Fprintf(io.ErrOut, "  To retry all official skills: lark-cli update --force\n")
+	case r.Force:
+		fmt.Fprintf(io.ErrOut, "%s Skills updated: restored all %d official skills\n", symOK(), len(r.Official))
 	default:
-		fmt.Fprintf(io.ErrOut, "%s Skills updated\n", symOK())
+		fmt.Fprintf(io.ErrOut, "%s Skills updated: %d official, %d updated, %d added, %d skipped because deleted locally\n", symOK(), len(r.Official), len(r.Updated), len(r.Added), len(r.SkippedDeleted))
+		if len(r.SkippedDeleted) > 0 {
+			fmt.Fprintf(io.ErrOut, "  To restore all official skills: lark-cli update --force\n")
+		}
 	}
 }

cmd/update/update_test.go

@@ -5,13 +5,14 @@ package cmdupdate
 
 import (
 	"bytes"
+	"context"
 	"encoding/json"
 	"errors"
 	"fmt"
-	"os"
-	"path/filepath"
+	"os/exec"
 	"strings"
 	"testing"
+	"time"
 
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
@@ -28,7 +29,6 @@ func newTestFactory(t *testing.T) (*cmdutil.Factory, *bytes.Buffer, *bytes.Buffe
 }
 
 // mockDetect sets up newUpdater to return an Updater with the given DetectResult.
-// It preserves any existing NpmInstallOverride/SkillsUpdateOverride that may be set later.
 func mockDetect(t *testing.T, result selfupdate.DetectResult) {
 	t.Helper()
 	origNew := newUpdater
@@ -41,22 +41,53 @@ func mockDetect(t *testing.T, result selfupdate.DetectResult) {
 }
 
 // mockDetectAndNpm sets up newUpdater with detect, npm install, and skills overrides all at once.
-func mockDetectAndNpm(t *testing.T, result selfupdate.DetectResult,
-	npmFn func(string) *selfupdate.NpmResult,
-	skillsFn func() *selfupdate.NpmResult) {
+func mockDetectAndNpm(t *testing.T, result selfupdate.DetectResult, npmFn func(string) *selfupdate.NpmResult) {
 	t.Helper()
 	origNew := newUpdater
 	newUpdater = func() *selfupdate.Updater {
 		u := selfupdate.New()
 		u.DetectOverride = func() selfupdate.DetectResult { return result }
 		u.NpmInstallOverride = npmFn
-		u.SkillsUpdateOverride = skillsFn
 		u.VerifyOverride = func(string) error { return nil }
+		u.SkillsCommandOverride = successfulSkillsCommand()
 		return u
 	}
 	t.Cleanup(func() { newUpdater = origNew })
 }
 
+func successfulSkillsCommand() func(args ...string) *selfupdate.NpmResult {
+	return func(args ...string) *selfupdate.NpmResult {
+		r := &selfupdate.NpmResult{}
+		switch strings.Join(args, " ") {
+		case "-y skills add https://open.feishu.cn --list":
+			r.Stdout.WriteString("Available Skills\n │    lark-calendar\n │    lark-mail\n")
+		case "-y skills ls -g":
+			r.Stdout.WriteString("Global Skills\nlark-calendar /tmp/lark-calendar\ncustom-skill /tmp/custom-skill\n")
+		default:
+		}
+		return r
+	}
+}
+
+func TestNormalizeVersion(t *testing.T) {
+	tests := []struct {
+		input string
+		want  string
+	}{
+		{input: "1.2.3", want: "1.2.3"},
+		{input: "v1.2.3", want: "1.2.3"},
+		{input: "V1.2.3", want: "1.2.3"},
+		{input: " v1.2.3 ", want: "1.2.3"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.input, func(t *testing.T) {
+			if got := normalizeVersion(tt.input); got != tt.want {
+				t.Fatalf("normalizeVersion(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
 func TestUpdateAlreadyUpToDate_JSON(t *testing.T) {
 	f, stdout, _ := newTestFactory(t)
 
@@ -168,9 +199,7 @@ func TestUpdateManual_Human(t *testing.T) {
 }
 
 func TestUpdateNpm_JSON(t *testing.T) {
-	// Isolate config dir: this test mocks fetchLatest="2.0.0" and lets
-	// runSkillsAndStamp → WriteStamp succeed, which without isolation would
-	// clobber the real ~/.lark-cli/skills.stamp with "2.0.0".
+	// Isolate config dir because skills sync writes skills-state.json.
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 
 	f, stdout, _ := newTestFactory(t)
@@ -186,7 +215,6 @@ func TestUpdateNpm_JSON(t *testing.T) {
 	mockDetectAndNpm(t,
 		selfupdate.DetectResult{Method: selfupdate.InstallNpm, ResolvedPath: "/node_modules/@larksuite/cli/bin/lark-cli", NpmAvailable: true},
 		func(version string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} },
-		func() *selfupdate.NpmResult { return &selfupdate.NpmResult{} },
 	)
 
 	err := cmd.Execute()
@@ -216,7 +244,6 @@ func TestUpdateNpm_Human(t *testing.T) {
 	mockDetectAndNpm(t,
 		selfupdate.DetectResult{Method: selfupdate.InstallNpm, ResolvedPath: "/node_modules/@larksuite/cli/bin/lark-cli", NpmAvailable: true},
 		func(version string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} },
-		func() *selfupdate.NpmResult { return &selfupdate.NpmResult{} },
 	)
 
 	err := cmd.Execute()
@@ -230,7 +257,7 @@ func TestUpdateNpm_Human(t *testing.T) {
 }
 
 func TestUpdateForce_JSON(t *testing.T) {
-	// Same stamp-isolation rationale as TestUpdateNpm_JSON.
+	// Same state-isolation rationale as TestUpdateNpm_JSON.
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 
 	f, stdout, _ := newTestFactory(t)
@@ -246,7 +273,6 @@ func TestUpdateForce_JSON(t *testing.T) {
 	mockDetectAndNpm(t,
 		selfupdate.DetectResult{Method: selfupdate.InstallNpm, ResolvedPath: "/node_modules/@larksuite/cli/bin/lark-cli", NpmAvailable: true},
 		func(version string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} },
-		func() *selfupdate.NpmResult { return &selfupdate.NpmResult{} },
 	)
 
 	err := cmd.Execute()
@@ -323,7 +349,7 @@ func TestUpdateInvalidVersion_JSON(t *testing.T) {
 }
 
 func TestUpdateDevVersion_JSON(t *testing.T) {
-	// Same stamp-isolation rationale as TestUpdateNpm_JSON.
+	// Same state-isolation rationale as TestUpdateNpm_JSON.
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 
 	f, stdout, _ := newTestFactory(t)
@@ -339,7 +365,6 @@ func TestUpdateDevVersion_JSON(t *testing.T) {
 	mockDetectAndNpm(t,
 		selfupdate.DetectResult{Method: selfupdate.InstallNpm, ResolvedPath: "/node_modules/@larksuite/cli/bin/lark-cli", NpmAvailable: true},
 		func(version string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} },
-		func() *selfupdate.NpmResult { return &selfupdate.NpmResult{} },
 	)
 
 	err := cmd.Execute()
@@ -451,8 +476,8 @@ func TestUpdateNpmVerifyFail_JSON_NoRestoreHintWhenBackupUnavailable(t *testing.
 		u.NpmInstallOverride = func(version string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} }
 		u.VerifyOverride = func(string) error { return errors.New("bad binary") }
 		u.RestoreAvailableOverride = func() bool { return false }
-		u.SkillsUpdateOverride = func() *selfupdate.NpmResult {
-			t.Fatal("skills update should not run when binary verification fails")
+		u.SkillsCommandOverride = func(args ...string) *selfupdate.NpmResult {
+			t.Fatal("skills sync should not run when binary verification fails")
 			return nil
 		}
 		return u
@@ -649,7 +674,7 @@ func TestPermissionHint(t *testing.T) {
 
 func TestUpdateWindows_NpmSuccess_JSON(t *testing.T) {
 	// With the rename trick, Windows npm installs can now auto-update.
-	// Same stamp-isolation rationale as TestUpdateNpm_JSON.
+	// Same state-isolation rationale as TestUpdateNpm_JSON.
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 
 	f, stdout, _ := newTestFactory(t)
@@ -668,7 +693,6 @@ func TestUpdateWindows_NpmSuccess_JSON(t *testing.T) {
 	mockDetectAndNpm(t,
 		selfupdate.DetectResult{Method: selfupdate.InstallNpm, ResolvedPath: `C:\npm\node_modules\@larksuite\cli\bin\lark-cli.exe`, NpmAvailable: true},
 		func(version string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} },
-		func() *selfupdate.NpmResult { return &selfupdate.NpmResult{} },
 	)
 
 	err := cmd.Execute()
@@ -750,7 +774,6 @@ func TestUpdateNpm_SkillsSuccess_JSON(t *testing.T) {
 	mockDetectAndNpm(t,
 		selfupdate.DetectResult{Method: selfupdate.InstallNpm, ResolvedPath: "/node_modules/@larksuite/cli/bin/lark-cli", NpmAvailable: true},
 		func(version string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} },
-		func() *selfupdate.NpmResult { return &selfupdate.NpmResult{} },
 	)
 
 	err := cmd.Execute()
@@ -785,8 +808,7 @@ func TestUpdateNpm_SkillsFail_JSON(t *testing.T) {
 		}
 		u.NpmInstallOverride = func(version string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} }
 		u.VerifyOverride = func(string) error { return nil }
-		// Skills update fails
-		u.SkillsUpdateOverride = func() *selfupdate.NpmResult {
+		u.SkillsCommandOverride = func(args ...string) *selfupdate.NpmResult {
 			r := &selfupdate.NpmResult{}
 			r.Stderr.WriteString("npx: command not found")
 			r.Err = fmt.Errorf("exit status 127")
@@ -812,8 +834,8 @@ func TestUpdateNpm_SkillsFail_JSON(t *testing.T) {
 	if !strings.Contains(out, "skills_warning") {
 		t.Errorf("expected skills_warning in output, got: %s", out)
 	}
-	if !strings.Contains(out, "skills_detail") {
-		t.Errorf("expected skills_detail in output, got: %s", out)
+	if !strings.Contains(out, "skills_summary") {
+		t.Errorf("expected skills_summary in output, got: %s", out)
 	}
 }
 
@@ -838,7 +860,7 @@ func TestUpdateNpm_SkillsFail_Human(t *testing.T) {
 		}
 		u.NpmInstallOverride = func(version string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} }
 		u.VerifyOverride = func(string) error { return nil }
-		u.SkillsUpdateOverride = func() *selfupdate.NpmResult {
+		u.SkillsCommandOverride = func(args ...string) *selfupdate.NpmResult {
 			r := &selfupdate.NpmResult{}
 			r.Stderr.WriteString("npx: command not found")
 			r.Err = fmt.Errorf("exit status 127")
@@ -861,100 +883,96 @@ func TestUpdateNpm_SkillsFail_Human(t *testing.T) {
 	if !strings.Contains(out, "Skills update failed") {
 		t.Errorf("expected skills failure warning, got: %s", out)
 	}
-	if !strings.Contains(out, "npx -y skills add") {
-		t.Errorf("expected manual skills command hint, got: %s", out)
+	if !strings.Contains(out, "lark-cli update --force") {
+		t.Errorf("expected force retry hint, got: %s", out)
 	}
 }
 
-// newTestIO returns a cmdutil.IOStreams backed by bytes.Buffers, suitable
-// for direct calls to internals like runSkillsAndStamp that write to
-// io.ErrOut.
+// newTestIO returns a cmdutil.IOStreams backed by bytes.Buffers.
 func newTestIO() *cmdutil.IOStreams {
 	return cmdutil.NewIOStreams(&bytes.Buffer{}, &bytes.Buffer{}, &bytes.Buffer{})
 }
 
-func TestRunSkillsAndStamp_DedupHit(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-	if err := skillscheck.WriteStamp("1.0.21"); err != nil {
+func TestRunSkillsAndState_DedupHit(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.21"}); err != nil {
 		t.Fatal(err)
 	}
 	called := false
 	updater := &selfupdate.Updater{
-		SkillsUpdateOverride: func() *selfupdate.NpmResult {
+		SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
 			called = true
 			return &selfupdate.NpmResult{}
 		},
 	}
-	got := runSkillsAndStamp(updater, newTestIO(), "1.0.21", false)
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false)
 	if got != nil {
-		t.Errorf("runSkillsAndStamp() = %+v, want nil for dedup hit", got)
+		t.Errorf("runSkillsAndState() = %+v, want nil for dedup hit", got)
 	}
 	if called {
-		t.Error("SkillsUpdateOverride called, want skipped due to dedup")
+		t.Error("SkillsCommandOverride called, want skipped due to dedup")
 	}
 }
 
-func TestRunSkillsAndStamp_DedupForceBypass(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-	if err := skillscheck.WriteStamp("1.0.21"); err != nil {
+func TestRunSkillsAndState_DedupForceBypass(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.21"}); err != nil {
 		t.Fatal(err)
 	}
 	called := false
 	updater := &selfupdate.Updater{
-		SkillsUpdateOverride: func() *selfupdate.NpmResult {
+		SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
 			called = true
-			return &selfupdate.NpmResult{}
+			return successfulSkillsCommand()(args...)
 		},
 	}
-	got := runSkillsAndStamp(updater, newTestIO(), "1.0.21", true)
-	if got == nil {
-		t.Fatal("runSkillsAndStamp(force=true) = nil, want non-nil")
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", true)
+	if got == nil || got.Err != nil {
+		t.Fatalf("runSkillsAndState(force=true) = %+v, want successful result", got)
 	}
 	if !called {
-		t.Error("SkillsUpdateOverride not called with force=true")
+		t.Error("SkillsCommandOverride not called with force=true")
 	}
 }
 
-func TestRunSkillsAndStamp_SuccessWritesStamp(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-	updater := &selfupdate.Updater{
-		SkillsUpdateOverride: func() *selfupdate.NpmResult {
-			return &selfupdate.NpmResult{}
-		},
-	}
-	got := runSkillsAndStamp(updater, newTestIO(), "1.0.21", false)
+func TestRunSkillsAndState_SuccessWritesState(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	updater := &selfupdate.Updater{SkillsCommandOverride: successfulSkillsCommand()}
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false)
 	if got == nil || got.Err != nil {
-		t.Fatalf("runSkillsAndStamp() = %+v, want non-nil with nil Err", got)
+		t.Fatalf("runSkillsAndState() = %+v, want non-nil with nil Err", got)
 	}
-	stamp, _ := skillscheck.ReadStamp()
-	if stamp != "1.0.21" {
-		t.Errorf("stamp = %q, want \"1.0.21\"", stamp)
+	state, readable, err := skillscheck.ReadState()
+	if err != nil || !readable {
+		t.Fatalf("ReadState() = (_, %v, %v), want readable", readable, err)
+	}
+	if state.Version != "1.0.21" {
+		t.Errorf("state.Version = %q, want \"1.0.21\"", state.Version)
 	}
 }
 
-func TestRunSkillsAndStamp_FailureKeepsOldStamp(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-	if err := skillscheck.WriteStamp("1.0.20"); err != nil {
+func TestRunSkillsAndState_FailureKeepsOldState(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.20"}); err != nil {
 		t.Fatal(err)
 	}
 	updater := &selfupdate.Updater{
-		SkillsUpdateOverride: func() *selfupdate.NpmResult {
+		SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
 			r := &selfupdate.NpmResult{}
 			r.Err = fmt.Errorf("npx failed")
 			return r
 		},
 	}
-	got := runSkillsAndStamp(updater, newTestIO(), "1.0.21", false)
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false)
 	if got == nil || got.Err == nil {
-		t.Fatalf("runSkillsAndStamp() = %+v, want non-nil with non-nil Err", got)
+		t.Fatalf("runSkillsAndState() = %+v, want non-nil with non-nil Err", got)
 	}
-	stamp, _ := skillscheck.ReadStamp()
-	if stamp != "1.0.20" {
-		t.Errorf("stamp = %q, want \"1.0.20\" (failure must not overwrite)", stamp)
+	state, readable, err := skillscheck.ReadState()
+	if err != nil || !readable {
+		t.Fatalf("ReadState() = (_, %v, %v), want readable", readable, err)
+	}
+	if state.Version != "1.0.20" {
+		t.Errorf("state.Version = %q, want \"1.0.20\" (failure must not overwrite)", state.Version)
 	}
 }
 
@@ -973,8 +991,7 @@ func TestTruncate(t *testing.T) {
 }
 
 func TestUpdateRun_AlreadyLatest_RunsSkillsSync(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 
 	origFetch := fetchLatest
 	origCur := currentVersion
@@ -987,9 +1004,9 @@ func TestUpdateRun_AlreadyLatest_RunsSkillsSync(t *testing.T) {
 	t.Cleanup(func() { newUpdater = origNew })
 	newUpdater = func() *selfupdate.Updater {
 		return &selfupdate.Updater{
-			SkillsUpdateOverride: func() *selfupdate.NpmResult {
+			SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
 				skillsCalled = true
-				return &selfupdate.NpmResult{}
+				return successfulSkillsCommand()(args...)
 			},
 		}
 	}
@@ -1000,17 +1017,19 @@ func TestUpdateRun_AlreadyLatest_RunsSkillsSync(t *testing.T) {
 		t.Fatalf("updateRun() err = %v, want nil", err)
 	}
 	if !skillsCalled {
-		t.Error("RunSkillsUpdate not called in already-up-to-date branch (cold stamp), want called")
+		t.Error("skills sync not called in already-up-to-date branch")
 	}
-	stamp, _ := skillscheck.ReadStamp()
-	if stamp != "1.0.21" {
-		t.Errorf("stamp = %q, want \"1.0.21\"", stamp)
+	state, readable, err := skillscheck.ReadState()
+	if err != nil || !readable {
+		t.Fatalf("ReadState() = (_, %v, %v), want readable", readable, err)
+	}
+	if state.Version != "1.0.21" {
+		t.Errorf("state.Version = %q, want \"1.0.21\"", state.Version)
 	}
 }
 
 func TestUpdateRun_Manual_RunsSkillsSync(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 
 	origFetch := fetchLatest
 	origCur := currentVersion
@@ -1029,9 +1048,9 @@ func TestUpdateRun_Manual_RunsSkillsSync(t *testing.T) {
 					ResolvedPath: "/usr/local/bin/lark-cli",
 				}
 			},
-			SkillsUpdateOverride: func() *selfupdate.NpmResult {
+			SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
 				skillsCalled = true
-				return &selfupdate.NpmResult{}
+				return successfulSkillsCommand()(args...)
 			},
 		}
 	}
@@ -1042,17 +1061,19 @@ func TestUpdateRun_Manual_RunsSkillsSync(t *testing.T) {
 		t.Fatalf("updateRun() err = %v, want nil", err)
 	}
 	if !skillsCalled {
-		t.Error("RunSkillsUpdate not called in manual branch, want called")
+		t.Error("skills sync not called in manual branch")
 	}
-	stamp, _ := skillscheck.ReadStamp()
-	if stamp != "1.0.21" {
-		t.Errorf("stamp = %q, want \"1.0.21\" (manual path stamps cur)", stamp)
+	state, readable, err := skillscheck.ReadState()
+	if err != nil || !readable {
+		t.Fatalf("ReadState() = (_, %v, %v), want readable", readable, err)
+	}
+	if state.Version != "1.0.21" {
+		t.Errorf("state.Version = %q, want \"1.0.21\" (manual path records current binary)", state.Version)
 	}
 }
 
-func TestUpdateRun_Npm_RunsSkillsSync_StampsLatest(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+func TestUpdateRun_Npm_RunsSkillsSync_WritesLatestState(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 
 	origFetch := fetchLatest
 	origCur := currentVersion
@@ -1075,9 +1096,9 @@ func TestUpdateRun_Npm_RunsSkillsSync_StampsLatest(t *testing.T) {
 				return &selfupdate.NpmResult{}
 			},
 			VerifyOverride: func(expectedVersion string) error { return nil },
-			SkillsUpdateOverride: func() *selfupdate.NpmResult {
+			SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
 				skillsCalled = true
-				return &selfupdate.NpmResult{}
+				return successfulSkillsCommand()(args...)
 			},
 		}
 	}
@@ -1088,18 +1109,25 @@ func TestUpdateRun_Npm_RunsSkillsSync_StampsLatest(t *testing.T) {
 		t.Fatalf("updateRun() err = %v, want nil", err)
 	}
 	if !skillsCalled {
-		t.Error("RunSkillsUpdate not called in npm branch")
+		t.Error("skills sync not called in npm branch")
 	}
-	stamp, _ := skillscheck.ReadStamp()
-	if stamp != "1.0.22" {
-		t.Errorf("stamp = %q, want \"1.0.22\" (npm path stamps latest)", stamp)
+	state, readable, err := skillscheck.ReadState()
+	if err != nil || !readable {
+		t.Fatalf("ReadState() = (_, %v, %v), want readable", readable, err)
+	}
+	if state.Version != "1.0.22" {
+		t.Errorf("state.Version = %q, want \"1.0.22\" (npm path records latest binary)", state.Version)
 	}
 }
 
 func TestUpdateRun_CheckIncludesSkillsStatus(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-	if err := skillscheck.WriteStamp("1.0.20"); err != nil {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	if err := skillscheck.WriteState(skillscheck.SkillsState{
+		Version:              "1.0.20",
+		OfficialSkills:       []string{"lark-calendar", "lark-mail"},
+		UpdatedSkills:        []string{"lark-calendar"},
+		SkippedDeletedSkills: []string{"lark-mail"},
+	}); err != nil {
 		t.Fatal(err)
 	}
 
@@ -1117,9 +1145,9 @@ func TestUpdateRun_CheckIncludesSkillsStatus(t *testing.T) {
 			DetectOverride: func() selfupdate.DetectResult {
 				return selfupdate.DetectResult{Method: selfupdate.InstallNpm, NpmAvailable: true}
 			},
-			SkillsUpdateOverride: func() *selfupdate.NpmResult {
+			SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
 				skillsCalled = true
-				return &selfupdate.NpmResult{}
+				return successfulSkillsCommand()(args...)
 			},
 		}
 	}
@@ -1130,7 +1158,7 @@ func TestUpdateRun_CheckIncludesSkillsStatus(t *testing.T) {
 		t.Fatalf("updateRun(--check) err = %v, want nil", err)
 	}
 	if skillsCalled {
-		t.Error("RunSkillsUpdate called under --check, want skipped (pure report)")
+		t.Error("skills sync called under --check, want skipped")
 	}
 
 	var env map[string]interface{}
@@ -1144,12 +1172,14 @@ func TestUpdateRun_CheckIncludesSkillsStatus(t *testing.T) {
 	if status["current"] != "1.0.20" || status["target"] != "1.0.21" || status["in_sync"] != false {
 		t.Errorf("skills_status = %+v, want {current:\"1.0.20\", target:\"1.0.21\", in_sync:false}", status)
 	}
+	if status["official"] != float64(2) || status["updated"] != float64(1) {
+		t.Errorf("skills_status counts = %+v, want official:2 updated:1", status)
+	}
 }
 
 func TestUpdateRun_CheckAlreadyLatest_NoSideEffect(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-	if err := skillscheck.WriteStamp("1.0.20"); err != nil {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.20"}); err != nil {
 		t.Fatal(err)
 	}
 
@@ -1164,9 +1194,9 @@ func TestUpdateRun_CheckAlreadyLatest_NoSideEffect(t *testing.T) {
 	t.Cleanup(func() { newUpdater = origNew })
 	newUpdater = func() *selfupdate.Updater {
 		return &selfupdate.Updater{
-			SkillsUpdateOverride: func() *selfupdate.NpmResult {
+			SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
 				skillsCalled = true
-				return &selfupdate.NpmResult{}
+				return successfulSkillsCommand()(args...)
 			},
 		}
 	}
@@ -1177,12 +1207,15 @@ func TestUpdateRun_CheckAlreadyLatest_NoSideEffect(t *testing.T) {
 		t.Fatalf("updateRun(--check, already-latest) err = %v, want nil", err)
 	}
 	if skillsCalled {
-		t.Error("RunSkillsUpdate called under --check (already-latest), want skipped (pure report)")
+		t.Error("skills sync called under --check (already-latest), want skipped")
 	}
 
-	stamp, _ := skillscheck.ReadStamp()
-	if stamp != "1.0.20" {
-		t.Errorf("stamp mutated to %q under --check, want \"1.0.20\" (pure report must not write stamp)", stamp)
+	state, readable, err := skillscheck.ReadState()
+	if err != nil || !readable {
+		t.Fatalf("ReadState() = (_, %v, %v), want readable", readable, err)
+	}
+	if state.Version != "1.0.20" {
+		t.Errorf("state.Version mutated to %q under --check, want \"1.0.20\"", state.Version)
 	}
 
 	var env map[string]interface{}
@@ -1204,39 +1237,248 @@ func TestUpdateRun_CheckAlreadyLatest_NoSideEffect(t *testing.T) {
 	}
 }
 
-// TestRunSkillsAndStamp_StampWriteFailureWarns verifies the stderr warning
-// emission when RunSkillsUpdate succeeds but WriteStamp fails.
-func TestRunSkillsAndStamp_StampWriteFailureWarns(t *testing.T) {
-	// Force WriteStamp to fail by pointing config dir at a path that exists
-	// as a regular file (so MkdirAll fails).
-	tmp := t.TempDir()
-	badPath := filepath.Join(tmp, "blocker")
-	if err := os.WriteFile(badPath, []byte("not-a-dir"), 0o644); err != nil {
-		t.Fatal(err)
+func TestRunSkillsAndState_StateWriteFailureWarns(t *testing.T) {
+	origSync := syncSkills
+	syncSkills = func(opts skillscheck.SyncOptions) *skillscheck.SyncResult {
+		return &skillscheck.SyncResult{Err: fmt.Errorf("skills synced but state not written: denied")}
 	}
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", badPath)
+	t.Cleanup(func() { syncSkills = origSync })
 
 	f, _, stderr := newTestFactory(t)
-	updater := &selfupdate.Updater{
-		SkillsUpdateOverride: func() *selfupdate.NpmResult {
-			return &selfupdate.NpmResult{} // success
-		},
+	got := runSkillsAndState(&selfupdate.Updater{}, f.IOStreams, "1.0.21", false)
+	if got == nil || got.Err == nil {
+		t.Fatalf("runSkillsAndState() = %+v, want non-nil with write error", got)
 	}
-	got := runSkillsAndStamp(updater, f.IOStreams, "1.0.21", false)
-	if got == nil || got.Err != nil {
-		t.Fatalf("runSkillsAndStamp() = %+v, want non-nil with nil Err", got)
-	}
-	if !strings.Contains(stderr.String(), "warning: skills synced but stamp not written") {
+	if !strings.Contains(stderr.String(), "warning: skills synced but state not written") {
 		t.Errorf("stderr does not contain warning: %q", stderr.String())
 	}
 }
 
-// TestEmitSkillsTextHints_Success verifies the "Skills updated" success
-// message is printed to ErrOut on a successful (Err == nil) result.
 func TestEmitSkillsTextHints_Success(t *testing.T) {
 	f, _, stderr := newTestFactory(t)
-	emitSkillsTextHints(f.IOStreams, &selfupdate.NpmResult{}) // Err==nil → success
+	emitSkillsTextHints(f.IOStreams, &skillscheck.SyncResult{Official: []string{"lark-calendar"}, Updated: []string{"lark-calendar"}})
 	if !strings.Contains(stderr.String(), "Skills updated") {
 		t.Errorf("stderr does not contain 'Skills updated': %q", stderr.String())
 	}
 }
+
+// TestUpdateCommand_RealSkillsSyncRewritesState is a live integration test that
+// verifies "lark-cli update" correctly triggers skills sync and rewrites the
+// state file. It calls the real npx skills CLI, so the test is skipped when
+// npx or the skills registry is unavailable (e.g. no network or fork PRs).
+func TestUpdateCommand_RealSkillsSyncRewritesState(t *testing.T) {
+	// Phase 1: Verify the real npx skills CLI is available; skip otherwise.
+	if _, err := exec.LookPath("npx"); err != nil {
+		t.Skipf("npx not found in PATH: %v", err)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 45*time.Second)
+	defer cancel()
+	if err := exec.CommandContext(ctx, "npx", "-y", "skills", "add", "https://open.feishu.cn", "--list").Run(); err != nil {
+		t.Skipf("real skills CLI unavailable: %v", err)
+	}
+	globalOut, err := exec.CommandContext(ctx, "npx", "-y", "skills", "ls", "-g").Output()
+	if err != nil {
+		t.Skipf("real global skills CLI unavailable: %v", err)
+	}
+	localSkills := skillscheck.ParseSkillsList(string(globalOut))
+	if err := ctx.Err(); err != nil {
+		t.Skipf("real skills CLI availability check timed out: %v", err)
+	}
+
+	// Phase 2: Seed a previous sync state simulating an upgrade from v1.0.19.
+	// lark-doc and lark-mail are recorded as skipped/deleted, meaning the user
+	// intentionally removed them while they were still official skills.
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	before := skillscheck.SkillsState{
+		Version:              "1.0.19",
+		OfficialSkills:       []string{"lark-approval", "lark-attendance", "lark-base", "lark-calendar", "lark-contact", "lark-doc", "lark-drive", "lark-event", "lark-im", "lark-mail", "lark-markdown", "lark-minutes", "lark-okr", "lark-openapi-explorer", "lark-shared", "lark-sheets", "lark-skill-maker", "lark-slides", "lark-task", "lark-vc", "lark-vc-agent", "lark-whiteboard", "lark-wiki", "lark-workflow-meeting-summary", "lark-workflow-standup-report"},
+		UpdatedSkills:        []string{"lark-approval", "lark-apps", "lark-attendance", "lark-base", "lark-calendar", "lark-contact", "lark-doc", "lark-drive", "lark-event", "lark-im", "lark-mail", "lark-markdown", "lark-minutes", "lark-okr", "lark-openapi-explorer", "lark-shared", "lark-sheets", "lark-skill-maker", "lark-slides", "lark-task", "lark-vc", "lark-vc-agent", "lark-whiteboard", "lark-wiki", "lark-workflow-meeting-summary", "lark-workflow-standup-report"},
+		AddedOfficialSkills:  []string{},
+		SkippedDeletedSkills: []string{},
+		UpdatedAt:            "2026-05-20T00:00:00Z",
+	}
+	if err := skillscheck.WriteState(before); err != nil {
+		t.Fatal(err)
+	}
+	state, readable, err := skillscheck.ReadState()
+	if err != nil || !readable {
+		t.Fatalf("ReadState() before update = (_, %v, %v), want readable", readable, err)
+	}
+	if state.Version != "1.0.19" {
+		t.Fatalf("state.Version before update = %q, want 1.0.19", state.Version)
+	}
+
+	// Phase 3: Mock version functions so the update command believes it has
+	// upgraded from 1.0.19 to 1.0.20, then execute "lark-cli update --json".
+	// This triggers SyncSkills which calls the real npx skills add command.
+	origFetch := fetchLatest
+	origVersion := currentVersion
+	t.Cleanup(func() { fetchLatest = origFetch; currentVersion = origVersion })
+	fetchLatest = func() (string, error) { return "1.0.20", nil }
+	currentVersion = func() string { return "1.0.20" }
+
+	f, stdout, _ := newTestFactory(t)
+	cmd := NewCmdUpdate(f)
+	cmd.SetArgs([]string{"--json"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("lark-cli update --json err = %v, want nil", err)
+	}
+
+	// Phase 4: Verify the state file was rewritten with the new version,
+	// non-empty official/updated skill lists, and a refreshed timestamp.
+	state, readable, err = skillscheck.ReadState()
+	if err != nil || !readable {
+		t.Fatalf("ReadState() after update = (_, %v, %v), want readable", readable, err)
+	}
+	if state.Version != "1.0.20" {
+		t.Errorf("state.Version after update = %q, want 1.0.20", state.Version)
+	}
+	if len(state.OfficialSkills) == 0 {
+		t.Fatalf("state.OfficialSkills after real sync is empty: %+v", state)
+	}
+	if len(state.UpdatedSkills) == 0 {
+		t.Fatalf("state.UpdatedSkills after real sync is empty: %+v", state)
+	}
+	if state.UpdatedAt == "" || state.UpdatedAt == before.UpdatedAt {
+		t.Errorf("state.UpdatedAt = %q, want refreshed non-empty timestamp", state.UpdatedAt)
+	}
+	// Verify that previously-skipped skills are handled correctly:
+	//   - If locally installed  → should appear in UpdatedSkills (updated to latest)
+	//   - If locally absent    → should NOT be force-restored in UpdatedSkills,
+	//                            and should remain in SkippedDeletedSkills
+	for _, skill := range []string{"lark-doc", "lark-mail"} {
+		if containsString(localSkills, skill) {
+			if !containsString(state.UpdatedSkills, skill) {
+				t.Errorf("state.UpdatedSkills = %v, want installed skill %q updated", state.UpdatedSkills, skill)
+			}
+			continue
+		}
+		if containsString(state.UpdatedSkills, skill) {
+			t.Errorf("state.UpdatedSkills = %v, want deleted skill %q not restored without --force", state.UpdatedSkills, skill)
+		}
+		if !containsString(state.SkippedDeletedSkills, skill) {
+			t.Errorf("state.SkippedDeletedSkills = %v, want deleted skill %q preserved when still official", state.SkippedDeletedSkills, skill)
+		}
+	}
+
+	// Phase 5: Verify the JSON output structure is parseable and contains
+	// the expected action fields for AI agent consumption.
+	var env map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("json.Unmarshal stdout: %v\nstdout: %s", err, stdout.String())
+	}
+	if env["action"] != "already_up_to_date" {
+		t.Errorf("action = %v, want already_up_to_date", env["action"])
+	}
+	if env["skills_action"] != "synced" {
+		t.Errorf("skills_action = %v, want synced", env["skills_action"])
+	}
+}
+
+// TestUpdateCommand_SkillsSyncColdStart verifies that when skills-state.json does
+// not exist (cold start), the update command installs all official skills and
+// writes a fresh state file. No skill should appear in SkippedDeletedSkills
+// because there is no previous state to preserve user deletions from.
+// This is a live integration test that calls the real npx skills CLI; it is
+// skipped when npx or the skills registry is unavailable.
+func TestUpdateCommand_SkillsSyncColdStart(t *testing.T) {
+	// Phase 1: Verify the real npx skills CLI is available; skip otherwise.
+	if _, err := exec.LookPath("npx"); err != nil {
+		t.Skipf("npx not found in PATH: %v", err)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 45*time.Second)
+	defer cancel()
+	if err := exec.CommandContext(ctx, "npx", "-y", "skills", "add", "https://open.feishu.cn", "--list").Run(); err != nil {
+		t.Skipf("real skills CLI unavailable: %v", err)
+	}
+	globalOut, err := exec.CommandContext(ctx, "npx", "-y", "skills", "ls", "-g").Output()
+	if err != nil {
+		t.Skipf("real global skills CLI unavailable: %v", err)
+	}
+	localSkills := skillscheck.ParseSkillsList(string(globalOut))
+	if err := ctx.Err(); err != nil {
+		t.Skipf("real skills CLI availability check timed out: %v", err)
+	}
+
+	// Phase 2: Use an isolated config dir with no pre-existing skills-state.json.
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	if _, readable, _ := skillscheck.ReadState(); readable {
+		t.Fatal("skills-state.json should not exist before update")
+	}
+
+	// Phase 3: Mock version functions so the update command believes it is at
+	// v1.0.20, then execute "lark-cli update --json". This triggers SyncSkills
+	// which calls the real npx skills add command.
+	origFetch := fetchLatest
+	origVersion := currentVersion
+	t.Cleanup(func() { fetchLatest = origFetch; currentVersion = origVersion })
+	fetchLatest = func() (string, error) { return "1.0.20", nil }
+	currentVersion = func() string { return "1.0.20" }
+
+	f, stdout, _ := newTestFactory(t)
+	cmd := NewCmdUpdate(f)
+	cmd.SetArgs([]string{"--json"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("lark-cli update --json err = %v, want nil", err)
+	}
+
+	// Phase 4: Verify the state file was created with all official skills in
+	// UpdatedSkills and nothing in SkippedDeletedSkills (cold start = no prior
+	// deletions to honor). Locally installed skills should appear in UpdatedSkills.
+	state, readable, err := skillscheck.ReadState()
+	if err != nil || !readable {
+		t.Fatalf("ReadState() after update = (_, %v, %v), want readable", readable, err)
+	}
+	if state.Version != "1.0.20" {
+		t.Errorf("state.Version = %q, want 1.0.20", state.Version)
+	}
+	if len(state.OfficialSkills) == 0 {
+		t.Fatalf("state.OfficialSkills after real sync is empty: %+v", state)
+	}
+	if len(state.UpdatedSkills) == 0 {
+		t.Fatalf("state.UpdatedSkills after real sync is empty: %+v", state)
+	}
+	if state.UpdatedAt == "" {
+		t.Error("state.UpdatedAt is empty, want non-empty timestamp")
+	}
+	// All locally installed official skills must appear in UpdatedSkills.
+	officialSet := map[string]bool{}
+	for _, s := range state.OfficialSkills {
+		officialSet[s] = true
+	}
+	for _, skill := range localSkills {
+		if !officialSet[skill] {
+			continue
+		}
+		if !containsString(state.UpdatedSkills, skill) {
+			t.Errorf("state.UpdatedSkills = %v, want locally installed official skill %q updated", state.UpdatedSkills, skill)
+		}
+	}
+	// No skill should be in SkippedDeletedSkills on cold start — there is no
+	// previous state recording a user deletion to preserve.
+	if len(state.SkippedDeletedSkills) != 0 {
+		t.Errorf("state.SkippedDeletedSkills = %v, want empty on cold start", state.SkippedDeletedSkills)
+	}
+
+	// Phase 5: Verify the JSON output structure is parseable and contains
+	// the expected action fields for AI agent consumption.
+	var env map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("json.Unmarshal stdout: %v\nstdout: %s", err, stdout.String())
+	}
+	if env["action"] != "already_up_to_date" {
+		t.Errorf("action = %v, want already_up_to_date", env["action"])
+	}
+	if env["skills_action"] != "synced" {
+		t.Errorf("skills_action = %v, want synced", env["skills_action"])
+	}
+}
+
+func containsString(values []string, target string) bool {
+	for _, value := range values {
+		if value == target {
+			return true
+		}
+	}
+	return false
+}

errs/ERROR_CONTRACT.md

@@ -0,0 +1,558 @@
+# lark-cli Error Contract
+
+`errs/` defines a typed, RFC 7807–aligned error taxonomy for the CLI. Three
+audiences depend on it: **AI agents and shell scripts** parsing the JSON
+envelope on stderr; **protocol adapters** mapping CLI errors into MCP /
+OAuth shapes; and **framework + business code** producing errors. This file
+is the single source of truth for all three.
+
+This document describes the **typed authoring target**. The refactor lands
+in stages; some boundaries (e.g. `client.WrapDoAPIError`) still operate on
+legacy shapes today — see **Migration** for what is live in each stage.
+
+Migrating an `*output.ExitError` call site? See **Migration**. Something off
+in production? See **Troubleshooting**.
+
+## Invariants
+
+1. Every error belongs to exactly one **Category**. The set is closed
+   (`errs/category.go`); adding a member requires deliberate review.
+2. Every **newly constructed** typed error has a **Subtype** — a stable
+   lowercase-with-underscores identifier declared in `errs/subtypes*.go`.
+   Undeclared subtypes fail CI. The constraint applies only to typed
+   `*errs.*` literals; stage-1 legacy `*core.ConfigError` flows via the
+   dispatcher's `asExitError` → legacy envelope path (not the typed
+   taxonomy) and is unaffected. `errcompat.PromoteConfigError` is a
+   stage-1 passthrough; its stage-2+ typed migration will subject the
+   promoted typed error to this Subtype constraint at that time.
+3. **`Category` + `Subtype`** are wire-stable identifiers consumers may
+   branch on. Renaming either is a breaking change.
+4. `Code` is the upstream numeric code when known (e.g. Lark API code).
+   It is `omitempty` and never carries CLI-internal meaning.
+5. Every typed error embeds `errs.Problem`. `CheckProblemEmbed` rejects
+   exported `*Error` structs that do not.
+6. Wrapping is idempotent: re-wrapping an already-typed error returns it
+   unchanged across the `errors.As` / `errors.Unwrap` chain.
+7. For the typed-envelope path, exit codes derive from `Category` only
+   via `output.ExitCodeForCategory`. Two stage-1 exceptions:
+   `SecurityPolicyError` always exits `1` (fixed by its legacy envelope),
+   and unmigrated `*output.ExitError` producers carry a hand-set `Code`;
+   both are retired in the legacy-removal stage.
+
+## Wire format
+
+Typed errors render to **stderr** as one JSON object per process exit:
+
+```json
+{
+  "ok": false,
+  "identity": "user",
+  "error": {
+    "type": "authorization",
+    "subtype": "missing_scope",
+    "code": 99991679,
+    "message": "missing scope `calendar:event:create` for app cli_xxx",
+    "hint": "run lark-cli auth login --scope calendar:event:create",
+    "log_id": "20260520-0a1b2c3d",
+    "missing_scopes": ["calendar:event:create"],
+    "console_url": "https://open.feishu.cn/app/cli_xxx/auth?q=..."
+  }
+}
+```
+
+| Field | Stability | Notes |
+|-------|-----------|-------|
+| `ok` | wire-stable | always `false` for errors |
+| `identity` | wire-stable | `user` \| `bot` — caller identity; omitted when not resolved |
+| `error.type` | **wire-stable** | one of the 9 Categories |
+| `error.subtype` | **wire-stable** | declared Subtype constant |
+| `error.code` | wire-stable | upstream numeric code, omitted when zero |
+| `error.message` | informational | not safe to branch on |
+| `error.hint` | informational | actionable recovery guidance |
+| `error.log_id` | informational | upstream request id (server-side trace) |
+| `error.retryable` | wire-stable | `true` when present; omitted when `false` |
+| per-Subtype extension fields | per-Subtype-stable | e.g. `missing_scopes`, `console_url`, `challenge_url` |
+
+Carve-out: `SecurityPolicyError` keeps the legacy
+`{type: "auth_error", code: "challenge_required"|"access_denied", ...}`
+envelope until its consumers migrate. Removal is staged in **Migration**.
+
+## Categories
+
+| Category | When | Exit | Typed struct |
+|----------|------|------|--------------|
+| `validation` | malformed user input | 2 | `ValidationError` |
+| `authentication` | no valid token / login required | 3 | `AuthenticationError` |
+| `authorization` | token lacks scope / app permission denied | 3 | `PermissionError` |
+| `config` | local config missing / unbound | 3 | `ConfigError` |
+| `network` | DNS, refused, timeout, transport | 4 | `NetworkError` |
+| `api` | server-side Lark error w/o specific bucket | 1 | `APIError` |
+| `policy` | content safety / security challenge | 6 | `SecurityPolicyError`, `ContentSafetyError` |
+| `internal` | SDK contract violation / decode failure | 5 | `InternalError` |
+| `confirmation` | high-risk action needs `--yes` | 10 | `ConfirmationRequiredError` |
+
+Canonical mapping: `internal/output/exitcode.go` `ExitCodeForCategory`.
+
+> **Note on the `authorization` / `PermissionError` asymmetry.** The wire
+> `type` field uses the RFC 7807 / taxonomy-formal name `"authorization"`,
+> but the Go type is named `PermissionError`. This is deliberate, following
+> the gRPC / Google APIs convention (`codes.Unauthenticated` +
+> `codes.PermissionDenied`): each name is chosen to be **maximally
+> distinct and readable on its own**, not to be perfectly symmetric.
+> `AuthenticationError` and `AuthorizationError` differ visually only at
+> the 5th character and are easy to confuse in code review;
+> `AuthenticationError` and `PermissionError` cannot be confused. The wire
+> field stays formal because it is the protocol-level taxonomy; the Go
+> type favors call-site readability.
+
+## Flow
+
+```
+  call site
+     │ constructs typed error (e.g. *errs.ValidationError)
+     ▼
+  command runE returns err
+     │
+     ▼
+  cmd/root.go handleRootError dispatches:
+     ├─ *errs.SecurityPolicyError → legacy "auth_error" JSON envelope; exit 1
+     ├─ typed (errs.ProblemOf)    → typed JSON envelope; exit = ExitCodeOf(err)
+     ├─ *core.ConfigError         → asExitError adapts to legacy envelope ↓
+     ├─ *output.ExitError         → legacy JSON envelope;  exit = exitErr.Code
+     └─ untyped / Cobra error     → plain "Error: <msg>" (no envelope); exit 1
+```
+
+Only the typed and `*output.ExitError` branches emit a JSON envelope on
+stderr. Untyped errors (including Cobra's "required flag missing" / unknown
+subcommand messages) print plain text and exit `1` — consumers must
+tolerate that fallback.
+
+## Consumers
+
+### Go (in-process)
+
+```go
+var pe *errs.PermissionError
+if errors.As(err, &pe) {
+    fmt.Println("missing:", pe.MissingScopes)
+}
+```
+
+Predicates cover the common categories (`errs/predicates.go`):
+
+```go
+if errs.IsAuthentication(err)       { ... }
+if errs.IsPermission(err) { ... }
+if errs.IsValidation(err) { ... }
+```
+
+Type-agnostic field access:
+
+```go
+if p, ok := errs.ProblemOf(err); ok {
+    log.Printf("cat=%s subtype=%s retryable=%t", p.Category, p.Subtype, p.Retryable)
+}
+exitCode := output.ExitCodeOf(err) // ExitInternal for non-typed errors
+```
+
+### Shell / AI
+
+```bash
+out=$(lark-cli ... 2>&1)
+code=$?
+
+# Untyped / Cobra errors print plain text — guard before jq.
+if ! jq -e . >/dev/null 2>&1 <<<"$out"; then
+    printf '%s\n' "$out" >&2
+    exit "$code"
+fi
+
+case "$(jq -r '.error.type // empty' <<<"$out")" in
+  authorization) jq -r '.error.missing_scopes[]' <<<"$out" ;;
+  network)       echo "transport failure, safe to retry" ;;
+  internal)      echo "bug — file an issue with log_id $(jq -r '.error.log_id // "n/a"' <<<"$out")" ;;
+esac
+```
+
+Unknown fields are forward-compatible additions: ignore, don't fail.
+Branch only on `type`, `subtype`, `code`, `retryable`, and declared
+extension fields — `message` is human-readable prose that may be
+reworded without notice.
+
+## Producers
+
+### Quick reference
+
+| Situation | Use |
+|-----------|-----|
+| Bad user input | `&errs.ValidationError{...}` or `output.ErrValidation(msg)` |
+| Login required | `&errs.AuthenticationError{...}` |
+| Token lacks scope | `errclass.BuildAPIError(resp, ctx)` |
+| Local config missing | `&errs.ConfigError{...}` |
+| Transport failure | `&errs.NetworkError{...}` |
+| Lark API error | `errclass.BuildAPIError(resp, ctx)` |
+| SDK / decode bug | `&errs.InternalError{Problem: errs.Problem{Category: errs.CategoryInternal, Subtype: errs.SubtypeSDKError, ...}}` |
+| Policy block | `&errs.SecurityPolicyError{...}` or `&errs.ContentSafetyError{...}` |
+| Needs `--yes` | `&errs.ConfirmationRequiredError{...}` |
+
+### Authoring discipline
+
+Five rules every producer follows. Some are enforced by `lint/errscontract`
+AST guards (`go run -C lint . ..`); the rest by code review.
+
+#### Propagate typed errors unchanged
+
+A function that receives an error already carrying `errs.Problem`
+returns it as-is up the stack. Reclassification at non-boundary frames
+(e.g., wrapping a `*ValidationError` into `*InternalError`) defeats the
+single-source taxonomy and silently downgrades typed signals.
+
+Conforming:
+
+```go
+_, err := runtime.DoAPI(req, opts)
+if err != nil {
+    return err // already typed by the framework boundary
+}
+```
+
+Non-conforming:
+
+```go
+return fmt.Errorf("calling /open-apis: %v", err)  // %v strips the typed shape
+return &errs.InternalError{Cause: err}            // re-decides category
+```
+
+#### Never return a typed-nil pointer
+
+A typed-nil pointer (`var pe *errs.PermissionError; return pe`) wraps as
+a non-nil interface — `errors.As` matches and `.Error()` may panic.
+Return interface `nil` literally.
+
+Non-conforming:
+
+```go
+var e *errs.ValidationError  // nil pointer
+return e                     // non-nil interface holding nil pointer
+```
+
+#### Let `Category` derive the exit code
+
+Do not pick exit codes by hand in new typed producers — `ExitCodeForCategory`
+maps `Category` to the shell code. A new exit-code requirement means a
+new `Category`, not a one-off override at the call site.
+
+(Legacy `*output.ExitError` and `SecurityPolicyError` retain hand-set
+codes during stage 1.)
+
+#### Split `Message`, `Hint`, and `Cause`
+
+Each field carries a distinct role:
+
+| Field | Carries | Style |
+|-------|---------|-------|
+| `Message` | What is wrong | Direct, lowercase first letter, no trailing period |
+| `Hint` | What to do next | Imperative ("run `lark-cli auth login`", "use `--as user`") |
+| `Cause` | The wrapped upstream `error`, not a stringified copy | Typed; serialized as `json:"-"` |
+
+`Hint` must not be merged into `Message`. AI agents and humans read them
+on separate channels; merging defeats both.
+
+`Cause` must be a real `error`. If the upstream returned an `error`,
+place it in `Cause` so `errors.Is` and `errors.Unwrap` walk the chain —
+do not inline its `.Error()` into `Message`.
+
+Conforming:
+
+```go
+return &errs.NetworkError{
+    Problem: errs.Problem{
+        Category: errs.CategoryNetwork,
+        Subtype:  errs.SubtypeNetworkTransport,
+        Message:  "request to /open-apis failed after 3 retries",
+        Hint:     "check connectivity and retry; set --log-level debug if it persists",
+    },
+    Cause: ioErr,
+}
+```
+
+Non-conforming:
+
+```go
+Message: fmt.Sprintf("request failed: %v — retry later", ioErr)
+// conflates what + what-to-do + cause into one string
+```
+
+#### `ValidationError.Param` uses the `--flag` form
+
+When a `*ValidationError` originates from a flag value, `Param` holds the
+flag name with leading dashes (`"--priority"`, not `"priority"`). AI
+agents grep this field literally to surface "the bad flag was `--X`".
+
+For positional arguments, use the canonical name without dashes
+(`"target_user_id"`).
+
+### Constructing typed errors
+
+The minimal struct literal:
+
+```go
+return &errs.ValidationError{
+    Problem: errs.Problem{
+        Category: errs.CategoryValidation,
+        Subtype:  errs.SubtypeInvalidArgument,
+        Message:  fmt.Sprintf("--data must be a valid JSON object: %v", parseErr),
+    },
+    Param: "--data",
+}
+```
+
+Legacy helpers (`output.ErrValidation`, `output.ErrAuth`, `output.ErrNetwork`)
+remain callable during migration; new code should prefer the struct
+literal so `Hint`, `Param`, `Cause`, and other extension fields stay
+available per [Split `Message`, `Hint`, and `Cause`](#split-message-hint-and-cause).
+
+#### Shortcut `Execute` walkthrough
+
+Adapted from `shortcuts/calendar/calendar_suggestion.go:222`, whose legacy
+form is `output.ErrValidation("--duration-minutes must be between 1 and
+1440")`. The typed migration target:
+
+```go
+Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+    duration := runtime.Int("duration-minutes")
+    if duration < 1 || duration > 1440 {
+        return &errs.ValidationError{
+            Problem: errs.Problem{
+                Category: errs.CategoryValidation,
+                Subtype:  errs.SubtypeInvalidArgument,
+                Message:  fmt.Sprintf("--duration-minutes must be between 1 and 1440, got %d", duration),
+                Hint:     "pass a value in [1, 1440]",
+            },
+            Param: "--duration-minutes",
+        }
+    }
+
+    _, err := runtime.DoAPI(req, opts)
+    if err != nil {
+        return err // already typed by the framework boundary; propagate
+    }
+    return nil
+}
+```
+
+Two patterns visible: a producer site (the typed `*errs.ValidationError`
+above) and a propagation site (the `return err` after `runtime.DoAPI`,
+applying [Propagate typed errors unchanged](#propagate-typed-errors-unchanged)).
+
+When the validation logic outgrows a single range check — multiple
+flags, format parsing, conditional rules — extract it into a helper that
+also returns the typed `*errs.ValidationError`. The helper, not
+`Execute`, sets `Param` (a helper bound to one shortcut is normal in
+this codebase; see `parseTimeRange` in
+`shortcuts/calendar/calendar_agenda.go:144`).
+
+### Wrapping upstream errors
+
+When a producer receives an error from a function it called, four cases
+cover the decision:
+
+| Source | Decision | Example |
+|--------|----------|---------|
+| Helper returned a typed `*errs.*Error` | Return unchanged | `return err` |
+| Helper returned an untyped error tied to user input (`strconv.Atoi`, `json.Unmarshal`, …) | Construct a typed error; put the untyped error in `Cause` | `return &errs.ValidationError{Problem: ..., Cause: jsonErr}` |
+| SDK call via `runtime.DoAPI` failed | Return unchanged — the framework boundary already wrapped it | `return err` |
+| Invariant broken (must-not-happen state) | Lift with `errs.WrapInternal`, set a `Message` describing the invariant | `return errs.WrapInternal(fmt.Errorf("identity resolver returned nil: %w", err))` |
+
+Prefer the `Cause` field over `fmt.Errorf("ctx: %w", err)` when
+attaching an upstream error to a typed one. `Cause` is the chain
+`errs.UnwrapTypedError` walks and the chain consumer code expects;
+`fmt.Errorf("...: %w", err)` only affects `.Error()` output, which the
+wire envelope does not surface.
+
+#### Boundary helpers (framework-internal)
+
+These helpers are called from framework boundaries, not from domain
+code:
+
+- `errs.WrapInternal(err)` — lifts an untyped error to `*InternalError`;
+  already-typed errors pass through unchanged.
+- `client.WrapDoAPIError(err)` — classifies SDK transport / decode
+  failures into `*errs.NetworkError` / `*errs.InternalError` at the SDK
+  boundary.
+- `client.WrapJSONResponseParseError(body, err)` — lifts response-layer
+  JSON parse failures to `*errs.InternalError`.
+
+If you find yourself reaching for `WrapDoAPIError` from a `shortcuts/**`
+package, you are probably calling the SDK at the wrong layer — go
+through `runtime.DoAPI`.
+
+### Extending the taxonomy
+
+#### Add a Subtype
+
+1. Add a constant in `errs/subtypes.go` (framework) or
+   `errs/subtypes_service_<name>.go` (service).
+2. If it maps from a Lark code, register the mapping in
+   `internal/errclass/codemeta_<service>.go`.
+3. Add a dispatch test in `internal/errclass/classify_test.go`.
+4. Reference the constant from a producer.
+5. `go run -C lint . ..` — `CheckDeclaredSubtype` fails until the
+   constant is wired through.
+
+`ad_hoc_*` subtypes are a temporary unblocker that label a value for
+follow-up, not a permanent identifier. Resolve any `ad_hoc_*` to a
+declared constant within one week of introduction; `CheckAdHocSubtype`
+emits a warning to keep them visible.
+
+#### Add a typed Error struct
+
+Rare; the existing structs cover the 9 Categories with room. If you must:
+
+1. Add the struct in `errs/types.go` embedding `errs.Problem`, with a
+   nil-receiver-safe `Unwrap()` if it carries `Cause`.
+2. Add an `IsXxx` predicate in `errs/predicates.go`.
+3. Add a wire-format pin in `errs/marshal_test.go`.
+
+`CheckProblemEmbed` enforces the `Problem` embed at lint time. New
+top-level wire fields are forbidden — per-Subtype data goes into the
+typed struct as a documented extension field, not into the envelope's
+top level.
+
+## CI guards
+
+| Check | Enforces | Where |
+|-------|----------|-------|
+| forbidigo | business path (`shortcuts/**`, `cmd/service/**`) must not call legacy `output.*` error constructors — route through the typed classifier | `.golangci.yml` |
+| `CheckProblemEmbed` | every exported `*Error` embeds `errs.Problem` | `lint/errscontract/` AST |
+| `CheckNoRegistrar` | no `mergeCodeMeta` / `RegisterServiceMap` from service code | `lint/errscontract/` AST |
+| `CheckAdHocSubtype` | `ad_hoc_*` Subtypes labeled for promotion (warn) | `lint/errscontract/` AST |
+| `CheckDeclaredSubtype` | every `Subtype:` value is a declared constant or `ad_hoc_*` | `lint/errscontract/` AST |
+| `CheckTypedErrorCompleteness` | every `*errs.<X>Error{Problem: errs.Problem{...}}` literal must set `Category`, `Subtype`, and `Message` | `lint/errscontract/` AST |
+
+CI runs `lint/` on every PR. Locally: `go run -C lint . ..`. The
+lintcheck CLI lives in its own Go module so its `golang.org/x/tools`
+dependency stays out of the shipped `lark-cli` binary's module graph;
+see `lint/README.md` for how to add a new lint domain.
+
+## Stability
+
+| Tier | Surface | Change policy |
+|------|---------|---------------|
+| Wire-stable | `error.type`, `error.subtype`, `error.code`, `error.retryable`, declared extension fields, `Category` enum values | breaking change ⇒ semver major; deprecation window required |
+| Additive | new Category, new declared Subtype, new extension field on an existing struct | minor release; consumers ignore unknown fields by contract |
+| Experimental | `ad_hoc_*` Subtypes; fields documented as such in `errs/types.go` | may change or be promoted/removed within one release |
+
+The deprecated `*output.ExitError` surface is outside these tiers — it
+will be removed once business migration completes.
+
+## Migration
+
+The error-contract refactor lands in stages. This PR is **stage 1**, and
+its scope is **strictly framework-only**: every production wire shape
+matches pre-PR byte-for-byte (additive fields only where the legacy slot
+had no subtype emission). Stage 1 ships infrastructure; behavioural
+migration of any specific path lives in later stages.
+
+Stages:
+
+1. **Framework slice — this PR.** Ships the `errs/` typed taxonomy,
+   classifier (`internal/errclass`), promotion stub (`internal/errcompat`,
+   passthrough in stage 1), dispatcher hook (`WriteTypedErrorEnvelope`),
+   and six lint guards (forbidigo + five AST checks). Wire shapes
+   preserved byte-for-byte versus pre-PR, with **one intentional semantic
+   fix**: config-class errors (`*core.ConfigError`) now exit `3` instead
+   of `2`, aligning with `ExitCodeForCategory` (config errors share the
+   auth exit slot per the taxonomy). The classifier and promote helpers
+   are *shipped but unused* in production paths — they exist so stage 2+
+   migrations can plug in without re-architecting.
+2. **`SecurityPolicyError` typed envelope** — replace the legacy
+   `type: "auth_error"` carve-out with the typed shape.
+3. **Business-domain migration**, one PR per domain in declared order:
+   `task → drive → calendar → im → mail → whiteboard → contact`. Each PR
+   moves the domain's `output.ErrAPI(...)` / `output.ErrAuth(...)` /
+   `output.ErrWithHint(...)` call sites to typed constructors or
+   `BuildAPIError`, removes its Deprecated annotations, and announces the
+   wire change explicitly.
+4. **Framework-boundary migration**: `client.WrapDoAPIError` and
+   `client.WrapJSONResponseParseError` flip to typed wrap;
+   `client.CheckResponse` adopts `errclass.BuildAPIError`;
+   `internal/client/client.go resolveAccessToken` adopts the typed
+   `NeedAuthorizationError → *errs.AuthenticationError` recognition;
+   `cmd/auth/scopes.go` and `cmd/service/service.go` adopt typed
+   `*errs.PermissionError`; `errcompat.PromoteConfigError` lifts the
+   `Type="config"` (and later `Type="auth"`) branches to typed.
+5. **Legacy removal** — once `git grep '\*output\.ExitError'` returns no
+   production hits, delete `Errorf`, `ErrAPI`, `ErrAuth`, `ErrWithHint`,
+   `ErrBare`, `ClassifyLarkError`, `ErrDetail`, `ExitError`, and
+   `ErrorEnvelope`.
+
+During migration, helper assertions accept both shapes (see
+`shortcuts/mail/mail_shortcut_validation_test.go` `assertValidationError`)
+so the build stays green domain-by-domain.
+
+Before / after at a call site (illustrative — actually performed in
+stage 3):
+
+```go
+// before (legacy)
+return output.ErrAPI(larkCode, "create event failed", resp.RawBody())
+
+// after (typed) — cc carries Brand / AppID / Identity from the caller's context
+return errclass.BuildAPIError(parsedResp, cc)
+```
+
+## Troubleshooting
+
+**Envelope shows `type=api subtype=unknown` for what should be a more
+specific category.** The Lark code is unknown to `LookupCodeMeta` and fell
+through to the generic bucket (`internal/errclass/classify.go`). Add the
+code to `internal/errclass/codemeta_<service>.go` with the right Category
+and Subtype, plus a dispatch test in `classify_test.go`.
+
+**Envelope shows `type=internal subtype=sdk_error`.** Origin is
+`client.WrapDoAPIError` taking the non-transport branch
+(`internal/client/api_errors.go`). Check: did the SDK fail to decode the
+response (look for `subtype=invalid_response` in the wrapped chain)? Was the
+transport detection too narrow for this error (e.g. a `*url.Error` with an
+inner that does not satisfy `net.Error`)? Either widen the transport
+predicate or add an explicit typed wrap upstream.
+
+**`CheckDeclaredSubtype` rejects my Subtype.** The constant must be
+declared in `errs/subtypes*.go` *and* referenced from the dispatch path.
+Bare string literals trip `CheckDeclaredSubtype` unless they match the
+`ad_hoc_*` prefix; `ad_hoc_*` then trips `CheckAdHocSubtype` as a
+follow-up warning.
+
+**`errors.As(&typedErr)` panics with a nil-pointer receiver.** A typed-nil
+slipped through. All typed errors define nil-safe `Unwrap()`, but
+returning a typed-nil pointer up the stack still defeats `errors.As`.
+Return interface `nil` from constructors, never a typed-nil pointer.
+
+**Exit code is 5 (internal) when I expected 3 (auth).** The error was not
+typed before reaching `handleRootError`. Wrap at the boundary
+(`client.WrapDoAPIError` or a typed constructor) — the bare `error.Error()`
+string cannot be classified retroactively.
+
+## Security & privacy
+
+- `log_id` is a server-side trace token. Safe to surface; it does not
+  carry user content.
+- `missing_scopes` is app configuration, not user data.
+- `Message` and `Hint` must not contain tokens, JWTs, or personally
+  identifying values. CI does not catch this — producer responsibility.
+- Wrapped `Cause` is **not** serialized to the wire (`json:"-"`). It is
+  retained for in-process `errors.Is` / `errors.Unwrap` traversal and
+  optional debug logging only.
+
+## Pointers (task-driven)
+
+- *Which struct to construct?* → **Producers / Quick reference**
+- *Add a new condition?* → **Add a Subtype**
+- *Consume from a shell script?* → **Consumers / Shell / AI**
+- *Understand or fix a CI failure?* → **CI guards**
+- *Migrate a legacy `ExitError` call site?* → **Migration** + the
+  Deprecated note on the symbol being replaced.
+- *Read source.* → `errs/doc.go` → `errs/category.go` → `errs/types.go`
+  → `errs/predicates.go` → `internal/errclass/` →
+  `cmd/root.go` `handleRootError`.

errs/category.go

@@ -0,0 +1,19 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errs
+
+// Category is the top-level taxonomy axis. Wire JSON: "type".
+type Category string
+
+const (
+	CategoryValidation     Category = "validation"
+	CategoryAuthentication Category = "authentication"
+	CategoryAuthorization  Category = "authorization"
+	CategoryConfig         Category = "config"
+	CategoryNetwork        Category = "network"
+	CategoryAPI            Category = "api"
+	CategoryPolicy         Category = "policy"
+	CategoryInternal       Category = "internal"
+	CategoryConfirmation   Category = "confirmation"
+)

errs/category_test.go

@@ -0,0 +1,31 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errs
+
+import "testing"
+
+func TestCategoryWireValues(t *testing.T) {
+	tests := []struct {
+		name string
+		got  Category
+		want string
+	}{
+		{"validation", CategoryValidation, "validation"},
+		{"authentication", CategoryAuthentication, "authentication"},
+		{"authorization", CategoryAuthorization, "authorization"},
+		{"config", CategoryConfig, "config"},
+		{"network", CategoryNetwork, "network"},
+		{"api", CategoryAPI, "api"},
+		{"policy", CategoryPolicy, "policy"},
+		{"internal", CategoryInternal, "internal"},
+		{"confirmation", CategoryConfirmation, "confirmation"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if string(tt.got) != tt.want {
+				t.Errorf("category %s = %q, want %q", tt.name, string(tt.got), tt.want)
+			}
+		})
+	}
+}

errs/doc.go

@@ -0,0 +1,37 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package errs is the public error-contract surface for lark-cli.
+//
+// It defines a closed taxonomy (9 Categories) and a small set of typed
+// errors that embed Problem — an RFC 7807-aligned shared shape. External
+// consumers (AI agents, shell scripts, integrating SDKs) read structured
+// fields instead of regex-parsing free-string error messages.
+//
+// # The Problem shape
+//
+// Every typed error embeds Problem so the JSON wire shape (`type`,
+// `subtype`, `code`, `message`, `hint`, `log_id`, `retryable`) is uniform
+// across categories. Typed extensions (PermissionError.MissingScopes,
+// SecurityPolicyError.ChallengeURL, etc.) appear at the top level of the
+// envelope alongside the shared fields, not nested under a `detail` key.
+//
+// # Working with typed errors
+//
+// Use ProblemOf to read shared fields polymorphically:
+//
+//	if p, ok := errs.ProblemOf(err); ok {
+//	    log.Printf("category=%s subtype=%s retryable=%t", p.Category, p.Subtype, p.Retryable)
+//	}
+//
+// Use the IsXxx predicates or stdlib errors.As to branch on concrete type:
+//
+//	if errs.IsPermission(err) {
+//	    var pe *errs.PermissionError
+//	    _ = errors.As(err, &pe)
+//	    fmt.Println("missing scopes:", pe.MissingScopes)
+//	}
+//
+// Use WrapInternal at boundaries to lift any non-typed error to
+// *InternalError; typed errors pass through unchanged.
+package errs

errs/internal_carrier.go

@@ -0,0 +1,11 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errs
+
+// problemCarrier is the non-exported extraction interface.
+// Used by ProblemOf via errors.As, working around the Go embed semantic where
+// *Problem cannot match *PermissionError directly.
+type problemCarrier interface {
+	ProblemDetail() *Problem
+}

errs/marshal_test.go

@@ -0,0 +1,235 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errs
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+// Per-type marshal tests pin each typed error's wire shape against its
+// canonical fields. They guard against future refactors that change struct
+// layout from accidentally altering the externally visible JSON contract.
+//
+// Each test asserts (a) Problem fields surface at the top level via embed
+// promotion, (b) extension fields sit alongside as siblings (NOT under a
+// `detail` sub-object), and (c) omitempty is honored on optional fields.
+
+func TestPermissionError_MarshalJSON_HasAllWireFields(t *testing.T) {
+	pe := &PermissionError{
+		Problem: Problem{
+			Category: CategoryAuthorization, Subtype: SubtypeMissingScope, Code: 99991679,
+			Message: "x", Hint: "y", LogID: "lg", Retryable: false,
+		},
+		MissingScopes: []string{"docx:document"},
+		Identity:      "user",
+		ConsoleURL:    "https://example",
+	}
+	b, err := json.Marshal(pe)
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := string(b)
+	for _, want := range []string{
+		`"type":"authorization"`,
+		`"subtype":"missing_scope"`,
+		`"code":99991679`,
+		`"message":"x"`,
+		`"hint":"y"`,
+		`"log_id":"lg"`,
+		`"missing_scopes":["docx:document"]`,
+		`"identity":"user"`,
+		`"console_url":"https://example"`,
+	} {
+		if !strings.Contains(s, want) {
+			t.Errorf("missing %q in %s", want, s)
+		}
+	}
+	if strings.Contains(s, `"retryable"`) {
+		t.Errorf("retryable should be omitted when false; got %s", s)
+	}
+	if strings.Contains(s, `"detail"`) {
+		t.Errorf("extension fields must not be wrapped under detail; got %s", s)
+	}
+}
+
+func TestValidationError_MarshalJSON(t *testing.T) {
+	ve := &ValidationError{
+		Problem: Problem{Category: CategoryValidation, Subtype: SubtypeInvalidArgument, Message: "bad"},
+		Param:   "--scope",
+	}
+	b, _ := json.Marshal(ve)
+	s := string(b)
+	for _, want := range []string{
+		`"type":"validation"`,
+		`"subtype":"invalid_argument"`,
+		`"message":"bad"`,
+		`"param":"--scope"`,
+	} {
+		if !strings.Contains(s, want) {
+			t.Errorf("missing %q in %s", want, s)
+		}
+	}
+
+	// Param omitempty when ""
+	ve2 := &ValidationError{Problem: Problem{Category: CategoryValidation, Message: "x"}}
+	b2, _ := json.Marshal(ve2)
+	if strings.Contains(string(b2), `"param"`) {
+		t.Errorf("param should be omitted when empty; got %s", b2)
+	}
+}
+
+func TestAuthError_MarshalJSON(t *testing.T) {
+	ae := &AuthenticationError{
+		Problem:    Problem{Category: CategoryAuthentication, Subtype: SubtypeTokenExpired, Message: "expired"},
+		UserOpenID: "ou_x",
+	}
+	b, _ := json.Marshal(ae)
+	s := string(b)
+	for _, want := range []string{
+		`"type":"authentication"`,
+		`"subtype":"token_expired"`,
+		`"message":"expired"`,
+		`"user_open_id":"ou_x"`,
+	} {
+		if !strings.Contains(s, want) {
+			t.Errorf("missing %q in %s", want, s)
+		}
+	}
+}
+
+func TestConfigError_MarshalJSON(t *testing.T) {
+	ce := &ConfigError{
+		Problem: Problem{Category: CategoryConfig, Subtype: SubtypeInvalidClient, Message: "bad"},
+		Field:   "app_id",
+	}
+	b, _ := json.Marshal(ce)
+	s := string(b)
+	for _, want := range []string{`"type":"config"`, `"subtype":"invalid_client"`, `"field":"app_id"`} {
+		if !strings.Contains(s, want) {
+			t.Errorf("missing %q in %s", want, s)
+		}
+	}
+}
+
+func TestNetworkError_MarshalJSON(t *testing.T) {
+	ne := &NetworkError{
+		Problem:   Problem{Category: CategoryNetwork, Subtype: SubtypeNetworkTransport, Message: "transport"},
+		CauseKind: "timeout",
+	}
+	b, _ := json.Marshal(ne)
+	s := string(b)
+	for _, want := range []string{
+		`"type":"network"`,
+		`"subtype":"transport"`,
+		`"cause":"timeout"`,
+	} {
+		if !strings.Contains(s, want) {
+			t.Errorf("missing %q in %s", want, s)
+		}
+	}
+
+	// CauseKind omitempty when ""
+	ne2 := &NetworkError{Problem: Problem{Category: CategoryNetwork, Message: "x"}}
+	b2, _ := json.Marshal(ne2)
+	if strings.Contains(string(b2), `"cause"`) {
+		t.Errorf("cause should be omitted when empty; got %s", b2)
+	}
+}
+
+func TestAPIError_MarshalJSON(t *testing.T) {
+	ae := &APIError{
+		Problem: Problem{Category: CategoryAPI, Subtype: SubtypeRateLimit, Code: 99991400, Message: "slow", Retryable: true},
+		Detail:  map[string]any{"raw": "value"},
+	}
+	b, _ := json.Marshal(ae)
+	s := string(b)
+	for _, want := range []string{
+		`"type":"api"`,
+		`"subtype":"rate_limit"`,
+		`"code":99991400`,
+		`"retryable":true`,
+		`"detail":{`,
+		`"raw":"value"`,
+	} {
+		if !strings.Contains(s, want) {
+			t.Errorf("missing %q in %s", want, s)
+		}
+	}
+
+	// Detail omitempty when nil
+	ae2 := &APIError{Problem: Problem{Category: CategoryAPI, Message: "x"}}
+	b2, _ := json.Marshal(ae2)
+	if strings.Contains(string(b2), `"detail"`) {
+		t.Errorf("detail should be omitted when nil; got %s", b2)
+	}
+}
+
+func TestSecurityPolicyError_MarshalJSON(t *testing.T) {
+	spe := &SecurityPolicyError{
+		Problem:      Problem{Category: CategoryPolicy, Subtype: SubtypeChallengeRequired, Message: "blocked"},
+		ChallengeURL: "https://chal.example",
+	}
+	b, _ := json.Marshal(spe)
+	s := string(b)
+	for _, want := range []string{
+		`"type":"policy"`,
+		`"subtype":"challenge_required"`,
+		`"challenge_url":"https://chal.example"`,
+	} {
+		if !strings.Contains(s, want) {
+			t.Errorf("missing %q in %s", want, s)
+		}
+	}
+}
+
+func TestContentSafetyError_MarshalJSON(t *testing.T) {
+	cse := &ContentSafetyError{
+		Problem: Problem{Category: CategoryPolicy, Subtype: Subtype("content_blocked"), Message: "blocked"},
+		Rules:   []string{"pii", "violence"},
+	}
+	b, _ := json.Marshal(cse)
+	s := string(b)
+	for _, want := range []string{
+		`"type":"policy"`,
+		`"rules":["pii","violence"]`,
+	} {
+		if !strings.Contains(s, want) {
+			t.Errorf("missing %q in %s", want, s)
+		}
+	}
+}
+
+func TestInternalError_MarshalJSON(t *testing.T) {
+	ie := &InternalError{
+		Problem: Problem{Category: CategoryInternal, Subtype: SubtypeSDKError, Message: "boom"},
+	}
+	b, _ := json.Marshal(ie)
+	s := string(b)
+	for _, want := range []string{`"type":"internal"`, `"subtype":"sdk_error"`} {
+		if !strings.Contains(s, want) {
+			t.Errorf("missing %q in %s", want, s)
+		}
+	}
+}
+
+func TestConfirmationRequiredError_MarshalJSON(t *testing.T) {
+	cre := &ConfirmationRequiredError{
+		Problem: Problem{Category: CategoryConfirmation, Subtype: Subtype("confirmation_required"), Message: "confirm"},
+		Risk:    "write",
+		Action:  "mail +send",
+	}
+	b, _ := json.Marshal(cre)
+	s := string(b)
+	for _, want := range []string{
+		`"type":"confirmation"`,
+		`"risk":"write"`,
+		`"action":"mail +send"`,
+	} {
+		if !strings.Contains(s, want) {
+			t.Errorf("missing %q in %s", want, s)
+		}
+	}
+}

errs/predicates.go

@@ -0,0 +1,88 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errs
+
+import (
+	"errors"
+)
+
+// ProblemOf extracts the embedded Problem via the non-exported problemCarrier interface.
+// This is the supported way to read shared fields without depending on a specific typed error.
+//
+// A typed error whose embedded *Problem is nil is treated as "not a problem
+// carrier" — returning (nil, true) here would cause CategoryOf / IsRetryable
+// and other downstream readers to dereference nil.
+func ProblemOf(err error) (*Problem, bool) {
+	var c problemCarrier
+	if errors.As(err, &c) {
+		if p := c.ProblemDetail(); p != nil {
+			return p, true
+		}
+	}
+	return nil, false
+}
+
+// UnwrapTypedError walks the wrap chain and returns the first error that
+// embeds Problem (i.e. any typed error in this package). Returns the typed
+// error itself (as error) so callers — notably JSON marshaling — see the
+// concrete value's own struct tags rather than an opaque wrapper.
+func UnwrapTypedError(err error) (error, bool) {
+	var c problemCarrier
+	if errors.As(err, &c) {
+		if e, ok := c.(error); ok {
+			return e, true
+		}
+	}
+	return nil, false
+}
+
+// CategoryOf returns the error's Category for metrics/logging/dispatch routing.
+// Falls back to CategoryInternal for non-typed errors.
+func CategoryOf(err error) Category {
+	if p, ok := ProblemOf(err); ok {
+		return p.Category
+	}
+	return CategoryInternal
+}
+
+// IsRetryable reads Problem.Retryable; non-typed errors are non-retryable by default.
+func IsRetryable(err error) bool {
+	if p, ok := ProblemOf(err); ok {
+		return p.Retryable
+	}
+	return false
+}
+
+// IsValidation reports whether err is a *ValidationError.
+func IsValidation(err error) bool { var x *ValidationError; return errors.As(err, &x) }
+
+// IsPermission reports whether err is a *PermissionError.
+func IsPermission(err error) bool { var x *PermissionError; return errors.As(err, &x) }
+
+// IsNetwork reports whether err is a *NetworkError.
+func IsNetwork(err error) bool { var x *NetworkError; return errors.As(err, &x) }
+
+// IsAPI reports whether err is an *APIError.
+func IsAPI(err error) bool { var x *APIError; return errors.As(err, &x) }
+
+// IsSecurityPolicy reports whether err is a *SecurityPolicyError.
+func IsSecurityPolicy(err error) bool { var x *SecurityPolicyError; return errors.As(err, &x) }
+
+// IsContentSafety reports whether err is a *ContentSafetyError.
+func IsContentSafety(err error) bool { var x *ContentSafetyError; return errors.As(err, &x) }
+
+// IsInternal reports whether err is an *InternalError.
+func IsInternal(err error) bool { var x *InternalError; return errors.As(err, &x) }
+
+// IsConfirmationRequired reports whether err is a *ConfirmationRequiredError.
+func IsConfirmationRequired(err error) bool {
+	var x *ConfirmationRequiredError
+	return errors.As(err, &x)
+}
+
+// IsAuthentication reports whether err is an *AuthenticationError.
+func IsAuthentication(err error) bool { var x *AuthenticationError; return errors.As(err, &x) }
+
+// IsConfig reports whether err is a *ConfigError.
+func IsConfig(err error) bool { var x *ConfigError; return errors.As(err, &x) }

errs/predicates_test.go

@@ -0,0 +1,203 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errs_test
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+)
+
+func TestIsRetryable(t *testing.T) {
+	tests := []struct {
+		name string
+		err  error
+		want bool
+	}{
+		{
+			name: "api error with retryable=true",
+			err:  &errs.APIError{Problem: errs.Problem{Category: errs.CategoryAPI, Retryable: true}},
+			want: true,
+		},
+		{
+			name: "api error with retryable=false (zero)",
+			err:  &errs.APIError{Problem: errs.Problem{Category: errs.CategoryAPI}},
+			want: false,
+		},
+		{
+			name: "plain error",
+			err:  fmt.Errorf("plain"),
+			want: false,
+		},
+		{
+			name: "nil error",
+			err:  nil,
+			want: false,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := errs.IsRetryable(tt.err); got != tt.want {
+				t.Errorf("IsRetryable(%v) = %v, want %v", tt.err, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestIsAuthTypedOnly(t *testing.T) {
+	tests := []struct {
+		name string
+		err  error
+		want bool
+	}{
+		{
+			name: "errs.AuthenticationError",
+			err:  &errs.AuthenticationError{Problem: errs.Problem{Category: errs.CategoryAuthentication}},
+			want: true,
+		},
+		{
+			name: "errs.ConfigError",
+			err:  &errs.ConfigError{Problem: errs.Problem{Category: errs.CategoryConfig}},
+			want: false,
+		},
+		{
+			name: "plain error",
+			err:  fmt.Errorf("plain"),
+			want: false,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := errs.IsAuthentication(tt.err); got != tt.want {
+				t.Errorf("IsAuthentication(%v) = %v, want %v", tt.err, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestIsConfigTypedOnly(t *testing.T) {
+	tests := []struct {
+		name string
+		err  error
+		want bool
+	}{
+		{
+			name: "errs.ConfigError",
+			err:  &errs.ConfigError{Problem: errs.Problem{Category: errs.CategoryConfig}},
+			want: true,
+		},
+		{
+			name: "errs.AuthenticationError",
+			err:  &errs.AuthenticationError{Problem: errs.Problem{Category: errs.CategoryAuthentication}},
+			want: false,
+		},
+		{
+			name: "plain error",
+			err:  fmt.Errorf("plain"),
+			want: false,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := errs.IsConfig(tt.err); got != tt.want {
+				t.Errorf("IsConfig(%v) = %v, want %v", tt.err, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestCategoryOf(t *testing.T) {
+	tests := []struct {
+		name string
+		err  error
+		want errs.Category
+	}{
+		{
+			name: "typed validation error",
+			err:  &errs.ValidationError{Problem: errs.Problem{Category: errs.CategoryValidation}},
+			want: errs.CategoryValidation,
+		},
+		{
+			name: "typed permission error",
+			err:  &errs.PermissionError{Problem: errs.Problem{Category: errs.CategoryAuthorization}},
+			want: errs.CategoryAuthorization,
+		},
+		{
+			name: "typed config error",
+			err:  &errs.ConfigError{Problem: errs.Problem{Category: errs.CategoryConfig}},
+			want: errs.CategoryConfig,
+		},
+		{
+			name: "typed auth error",
+			err:  &errs.AuthenticationError{Problem: errs.Problem{Category: errs.CategoryAuthentication}},
+			want: errs.CategoryAuthentication,
+		},
+		{
+			name: "plain error falls back to internal",
+			err:  fmt.Errorf("plain"),
+			want: errs.CategoryInternal,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := errs.CategoryOf(tt.err); got != tt.want {
+				t.Errorf("CategoryOf(%v) = %q, want %q", tt.err, got, tt.want)
+			}
+		})
+	}
+}
+
+// TestProblemOf_NilProblemReturnsFalse pins that a problemCarrier whose
+// ProblemDetail() returns nil does NOT satisfy ProblemOf — otherwise
+// CategoryOf / IsRetryable and other downstream readers would dereference
+// nil and panic. *Problem(nil) is a directly constructable trigger: its
+// ProblemDetail method `return p` is nil-safe and yields nil.
+func TestProblemOf_NilProblemReturnsFalse(t *testing.T) {
+	var nilP *errs.Problem
+	var err error = nilP // *Problem implements error via Error() (nil-receiver safe)
+
+	p, ok := errs.ProblemOf(err)
+	if ok {
+		t.Fatalf("ProblemOf(*Problem(nil)) = (%v, true); want (nil, false)", p)
+	}
+	if p != nil {
+		t.Errorf("ProblemOf(*Problem(nil)).p = %v; want nil", p)
+	}
+
+	// Downstream readers must not panic on the same input.
+	if cat := errs.CategoryOf(err); cat != errs.CategoryInternal {
+		t.Errorf("CategoryOf(*Problem(nil)) = %q, want fallback %q", cat, errs.CategoryInternal)
+	}
+	if retryable := errs.IsRetryable(err); retryable {
+		t.Errorf("IsRetryable(*Problem(nil)) = true; want false")
+	}
+}
+
+func TestTypedPredicates(t *testing.T) {
+	cases := []struct {
+		name string
+		err  error
+		pred func(error) bool
+		want bool
+	}{
+		{"IsValidation+", &errs.ValidationError{}, errs.IsValidation, true},
+		{"IsValidation-", &errs.APIError{}, errs.IsValidation, false},
+		{"IsPermission+", &errs.PermissionError{}, errs.IsPermission, true},
+		{"IsPermission-", &errs.APIError{}, errs.IsPermission, false},
+		{"IsNetwork+", &errs.NetworkError{}, errs.IsNetwork, true},
+		{"IsAPI+", &errs.APIError{}, errs.IsAPI, true},
+		{"IsSecurityPolicy+", &errs.SecurityPolicyError{}, errs.IsSecurityPolicy, true},
+		{"IsContentSafety+", &errs.ContentSafetyError{}, errs.IsContentSafety, true},
+		{"IsInternal+", &errs.InternalError{}, errs.IsInternal, true},
+		{"IsConfirmationRequired+", &errs.ConfirmationRequiredError{}, errs.IsConfirmationRequired, true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := tc.pred(tc.err); got != tc.want {
+				t.Errorf("%s: predicate = %v, want %v", tc.name, got, tc.want)
+			}
+		})
+	}
+}

errs/problem.go

@@ -0,0 +1,38 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errs
+
+// Problem is the RFC 7807-aligned shared shape embedded by every typed error.
+//
+// Message is REQUIRED. Producers must populate it; an empty Message will make
+// Error() return "" — a known Go footgun for fmt.Errorf("...: %v", err).
+//
+// Wire-format notes:
+//   - No Component field. Service / shortcut component is metric-only
+//     enrichment derived by the dispatcher from the cobra command path; it
+//     never appears on the wire.
+//   - No DocURL field. PermissionError carries the same intent via its typed
+//     ConsoleURL extension; other typed errors do not link out.
+//   - Retryable uses omitempty so only `true` is emitted; consumers treat
+//     absence as false.
+type Problem struct {
+	Category  Category `json:"type"`
+	Subtype   Subtype  `json:"subtype,omitempty"`
+	Code      int      `json:"code,omitempty"`
+	Message   string   `json:"message"`
+	Hint      string   `json:"hint,omitempty"`
+	LogID     string   `json:"log_id,omitempty"`
+	Retryable bool     `json:"retryable,omitempty"`
+}
+
+// Error satisfies the standard `error` interface. A nil receiver is treated
+// as the empty string so a stray nil *Problem stored in an error interface
+// cannot panic the dispatcher.
+func (p *Problem) Error() string {
+	if p == nil {
+		return ""
+	}
+	return p.Message
+}
+func (p *Problem) ProblemDetail() *Problem { return p }

errs/problem_test.go

@@ -0,0 +1,72 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errs
+
+import (
+	"reflect"
+	"testing"
+)
+
+func TestProblemError(t *testing.T) {
+	tests := []struct {
+		name string
+		p    Problem
+		want string
+	}{
+		{"empty message", Problem{}, ""},
+		{"plain message", Problem{Message: "boom"}, "boom"},
+		{"message ignores hint", Problem{Message: "msg", Hint: "do x"}, "msg"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := (&tt.p).Error(); got != tt.want {
+				t.Errorf("Error() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+// TestProblemError_NilReceiverDoesNotPanic pins the nil-receiver guard on
+// (*Problem).Error(). Without it, a nil *Problem stored in an error interface
+// would panic when the root dispatcher calls err.Error() for logging.
+func TestProblemError_NilReceiverDoesNotPanic(t *testing.T) {
+	var p *Problem // nil
+	defer func() {
+		if r := recover(); r != nil {
+			t.Fatalf("(*Problem)(nil).Error() panicked: %v", r)
+		}
+	}()
+	if got := p.Error(); got != "" {
+		t.Errorf("(*Problem)(nil).Error() = %q, want \"\"", got)
+	}
+}
+
+func TestProblemDetailReturnsReceiver(t *testing.T) {
+	p := &Problem{Message: "x"}
+	if got := p.ProblemDetail(); got != p {
+		t.Errorf("ProblemDetail() = %p, want receiver %p", got, p)
+	}
+}
+
+func TestProblemHasNoComponentField(t *testing.T) {
+	if f, ok := reflect.TypeOf(Problem{}).FieldByName("Component"); ok {
+		t.Errorf("Problem.Component must not exist; got field %#v", f)
+	}
+}
+
+func TestProblemHasNoDocURLField(t *testing.T) {
+	if f, ok := reflect.TypeOf(Problem{}).FieldByName("DocURL"); ok {
+		t.Errorf("Problem.DocURL must not exist on the base Problem (PermissionError carries ConsoleURL instead); got field %#v", f)
+	}
+}
+
+func TestProblemCategoryTagIsType(t *testing.T) {
+	f, ok := reflect.TypeOf(Problem{}).FieldByName("Category")
+	if !ok {
+		t.Fatalf("Problem.Category must exist")
+	}
+	if got := f.Tag.Get("json"); got != "type" {
+		t.Errorf("Problem.Category json tag = %q, want %q", got, "type")
+	}
+}

errs/subtypes.go

@@ -0,0 +1,75 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errs
+
+// Subtype is the second-level taxonomy axis. Wire JSON: "subtype".
+type Subtype string
+
+const (
+	SubtypeUnknown Subtype = "unknown" // catch-all fallback; producers must prefer a specific subtype
+)
+
+// CategoryValidation subtypes
+const (
+	SubtypeInvalidArgument Subtype = "invalid_argument" // user-supplied flag / arg failed validation (gRPC INVALID_ARGUMENT alignment)
+)
+
+// CategoryAuthentication subtypes
+const (
+	SubtypeTokenMissing        Subtype = "token_missing"         // no token in request (Authorization header absent / no local token cache)
+	SubtypeTokenInvalid        Subtype = "token_invalid"         // token present but content/format wrong
+	SubtypeTokenExpired        Subtype = "token_expired"         // token explicitly expired
+	SubtypeRefreshTokenInvalid Subtype = "refresh_token_invalid" // refresh_token is v1 legacy format, unusable
+	SubtypeRefreshTokenExpired Subtype = "refresh_token_expired" // refresh_token expired
+	SubtypeRefreshTokenRevoked Subtype = "refresh_token_revoked" // refresh_token revoked (user logout / admin action)
+	SubtypeRefreshTokenReused  Subtype = "refresh_token_reused"  // refresh_token already used (single-use rotation triggered)
+	SubtypeRefreshServerError  Subtype = "refresh_server_error"  // refresh endpoint transient error (retryable)
+)
+
+// CategoryAuthorization subtypes
+const (
+	SubtypeMissingScope           Subtype = "missing_scope"            // user authorized app but did not grant this scope
+	SubtypeUserUnauthorized       Subtype = "user_unauthorized"        // user never authorized the app
+	SubtypeAppScopeNotApplied     Subtype = "app_scope_not_applied"    // app did not apply for this scope on the open platform
+	SubtypeTokenScopeInsufficient Subtype = "token_scope_insufficient" // token was issued without this scope (RFC 6750 alignment)
+	SubtypeAppUnavailable         Subtype = "app_unavailable"          // app status unavailable
+	SubtypeAppNotInstalled        Subtype = "app_not_installed"        // app not enabled / not installed in this tenant
+)
+
+// CategoryConfig subtypes
+const (
+	SubtypeInvalidClient Subtype = "invalid_client" // app_id / app_secret incorrect (RFC 6749 §5.2 alignment)
+	SubtypeNotConfigured Subtype = "not_configured" // local config file absent (user has not run `config init`)
+	SubtypeInvalidConfig Subtype = "invalid_config" // local config file present but malformed
+)
+
+// CategoryNetwork subtypes
+const (
+	SubtypeNetworkTransport Subtype = "transport" // transport-layer failure (timeout / TLS / DNS / 5xx); see NetworkError.CauseKind
+)
+
+// CategoryAPI subtypes
+const (
+	SubtypeRateLimit         Subtype = "rate_limit"         // request rate limit exceeded
+	SubtypeConflict          Subtype = "conflict"           // resource state conflict (e.g. concurrent modification)
+	SubtypeCrossTenant       Subtype = "cross_tenant"       // operation crosses tenant boundary (not supported)
+	SubtypeCrossBrand        Subtype = "cross_brand"        // operation crosses brand boundary (feishu vs lark, not supported)
+	SubtypeInvalidParameters Subtype = "invalid_parameters" // API-side parameter validation rejected the request
+	SubtypeOwnershipMismatch Subtype = "ownership_mismatch" // caller is not the resource owner
+)
+
+// CategoryPolicy subtypes (security-policy envelope shape)
+const (
+	SubtypeChallengeRequired Subtype = "challenge_required" // user must complete browser challenge / MFA
+	SubtypeAccessDenied      Subtype = "access_denied"      // policy denies access outright
+)
+
+// CategoryInternal subtypes
+const (
+	SubtypeSDKError        Subtype = "sdk_error"        // lark SDK Do() returned an unexpected error
+	SubtypeInvalidResponse Subtype = "invalid_response" // SDK response body not parsable as JSON
+	// Generic untyped error lifted to InternalError uses SubtypeUnknown.
+)
+
+// CategoryConfirmation subtypes intentionally have no declarations yet.

errs/subtypes_service_task.go

@@ -0,0 +1,21 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errs
+
+// Service-specific Subtype declarations. Per-service files follow the
+// naming pattern subtypes_service_<name>.go so the framework's closed
+// Subtype enum stays readable while service taxonomies remain visible.
+
+// Task service subtypes — consumed by internal/errclass/codemeta_task.go.
+const (
+	SubtypeTaskInvalidParams       Subtype = "task_invalid_params"
+	SubtypeTaskPermissionDenied    Subtype = "task_permission_denied"
+	SubtypeTaskNotFound            Subtype = "task_not_found"
+	SubtypeTaskConflict            Subtype = "task_conflict"
+	SubtypeTaskServerError         Subtype = "task_server_error"
+	SubtypeTaskAssigneeLimit       Subtype = "task_assignee_limit"
+	SubtypeTaskFollowerLimit       Subtype = "task_follower_limit"
+	SubtypeTaskTasklistMemberLimit Subtype = "task_tasklist_member_limit"
+	SubtypeTaskReminderExists      Subtype = "task_reminder_exists"
+)

errs/types.go

@@ -0,0 +1,136 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errs
+
+// ValidationError is the typed error for CategoryValidation.
+// Cause preserves an optional wrapped sentinel for errors.Is / errors.Unwrap;
+// it is intentionally not serialized.
+type ValidationError struct {
+	Problem
+	Param string `json:"param,omitempty"`
+	Cause error  `json:"-"`
+}
+
+// Unwrap exposes the wrapped cause so errors.Unwrap / errors.Is can traverse
+// it. A nil typed-pointer held inside an error interface is treated as
+// "no cause" so callers cannot panic on `errors.Unwrap(err)`.
+func (e *ValidationError) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.Cause
+}
+
+// AuthenticationError is the typed error for CategoryAuthentication.
+// Cause preserves an optional wrapped sentinel for errors.Is / errors.Unwrap;
+// it is intentionally not serialized.
+type AuthenticationError struct {
+	Problem
+	UserOpenID string `json:"user_open_id,omitempty"`
+	Cause      error  `json:"-"`
+}
+
+// Unwrap is nil-receiver safe; see ValidationError.Unwrap.
+func (e *AuthenticationError) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.Cause
+}
+
+// PermissionError is the typed error for CategoryAuthorization.
+type PermissionError struct {
+	Problem
+	MissingScopes []string `json:"missing_scopes,omitempty"`
+	Identity      string   `json:"identity,omitempty"`
+	ConsoleURL    string   `json:"console_url,omitempty"`
+}
+
+// ConfigError is the typed error for CategoryConfig.
+// Cause preserves an optional wrapped sentinel for errors.Is / errors.Unwrap;
+// it is intentionally not serialized.
+type ConfigError struct {
+	Problem
+	Field string `json:"field,omitempty"`
+	Cause error  `json:"-"`
+}
+
+// Unwrap is nil-receiver safe; see ValidationError.Unwrap.
+func (e *ConfigError) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.Cause
+}
+
+// NetworkError is the typed error for CategoryNetwork.
+// CauseKind (string) is one of: "timeout" | "tls" | "dns" | "5xx" — the
+// canonical wire taxonomy (emitted as JSON key "cause"). Cause preserves an
+// optional wrapped sentinel for errors.Is / errors.Unwrap; it is intentionally
+// not serialized.
+type NetworkError struct {
+	Problem
+	CauseKind string `json:"cause,omitempty"`
+	Cause     error  `json:"-"`
+}
+
+// Unwrap is nil-receiver safe; see ValidationError.Unwrap.
+func (e *NetworkError) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.Cause
+}
+
+// APIError is the typed error for CategoryAPI (catch-all for classified Lark API
+// business errors). Detail preserves the raw Lark error map for diagnostics.
+type APIError struct {
+	Problem
+	Detail map[string]any `json:"detail,omitempty"`
+}
+
+// SecurityPolicyError is the typed error for CategoryPolicy security-policy subtypes.
+// Subtype is "challenge_required" or "access_denied"; Code is 21000 or 21001.
+type SecurityPolicyError struct {
+	Problem
+	ChallengeURL string `json:"challenge_url,omitempty"`
+	Cause        error  `json:"-"`
+}
+
+// Unwrap is nil-receiver safe; see ValidationError.Unwrap.
+func (e *SecurityPolicyError) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.Cause
+}
+
+// ContentSafetyError is the typed error for CategoryPolicy content-safety subtypes.
+type ContentSafetyError struct {
+	Problem
+	Rules []string `json:"rules,omitempty"`
+}
+
+// InternalError is the typed error for CategoryInternal.
+// Cause is preserved for logging but not emitted on the wire.
+type InternalError struct {
+	Problem
+	Cause error `json:"-"`
+}
+
+// Unwrap is nil-receiver safe; see ValidationError.Unwrap.
+func (e *InternalError) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.Cause
+}
+
+// ConfirmationRequiredError is the typed error for CategoryConfirmation.
+// Risk is one of: "read" | "write" | "high-risk-write".
+type ConfirmationRequiredError struct {
+	Problem
+	Risk   string `json:"risk"`
+	Action string `json:"action"`
+}

errs/types_test.go

@@ -0,0 +1,154 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errs
+
+import (
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+)
+
+func TestPermissionErrorJSONShape(t *testing.T) {
+	perm := &PermissionError{
+		Problem: Problem{
+			Category: CategoryAuthorization,
+			Subtype:  SubtypeMissingScope,
+			Message:  "x",
+		},
+		MissingScopes: []string{"docx:document"},
+	}
+	b, err := json.Marshal(perm)
+	if err != nil {
+		t.Fatalf("marshal failed: %v", err)
+	}
+	got := string(b)
+
+	mustContain := []string{
+		`"type":"authorization"`,
+		`"subtype":"missing_scope"`,
+		`"missing_scopes":["docx:document"]`,
+	}
+	for _, want := range mustContain {
+		if !strings.Contains(got, want) {
+			t.Errorf("json output missing %q\nfull output: %s", want, got)
+		}
+	}
+
+	mustNotContain := []string{
+		`"component"`,
+		`"doc_url"`,
+		`"retryable":false`,
+	}
+	for _, bad := range mustNotContain {
+		if strings.Contains(got, bad) {
+			t.Errorf("json output unexpectedly contains %q\nfull output: %s", bad, got)
+		}
+	}
+}
+
+// TestEmbedSemanticChasm proves the documented Go embed limitation:
+// errors.As(*PermissionError, &p *Problem) returns false even though
+// PermissionError embeds Problem. ProblemOf works around this by routing
+// via the unexported problemCarrier interface.
+func TestEmbedSemanticChasm(t *testing.T) {
+	perm := &PermissionError{
+		Problem: Problem{
+			Category: CategoryAuthorization,
+			Subtype:  SubtypeMissingScope,
+			Message:  "missing",
+		},
+	}
+
+	var p *Problem
+	if errors.As(perm, &p) {
+		t.Errorf("errors.As(*PermissionError, &*Problem) unexpectedly succeeded; Go embed semantic changed")
+	}
+
+	got, ok := ProblemOf(perm)
+	if !ok {
+		t.Fatalf("ProblemOf(*PermissionError) returned ok=false; expected to extract embedded Problem")
+	}
+	if got != &perm.Problem {
+		t.Errorf("ProblemOf returned %p, want &perm.Problem = %p", got, &perm.Problem)
+	}
+	if got.Category != CategoryAuthorization {
+		t.Errorf("extracted Problem.Category = %q, want %q", got.Category, CategoryAuthorization)
+	}
+}
+
+func TestSecurityPolicyErrorUnwrap(t *testing.T) {
+	orig := errors.New("transport stalled")
+	spe := &SecurityPolicyError{
+		Problem: Problem{Category: CategoryPolicy, Subtype: Subtype("challenge_required"), Message: "blocked"},
+		Cause:   orig,
+	}
+	if got := errors.Unwrap(spe); got != orig {
+		t.Fatalf("errors.Unwrap(spe) = %v, want %v", got, orig)
+	}
+	if !errors.Is(spe, orig) {
+		t.Fatal("errors.Is(spe, orig) = false, want true")
+	}
+}
+
+// TestTypedErrors_UnwrapNilReceiver pins the nil-receiver guard on every typed
+// error's Unwrap. Without these, a typed-nil pointer stored in an error
+// interface would panic when the root dispatcher or any caller walks the
+// errors.Is / errors.Unwrap chain.
+//
+// The doc comments on these types claim "nil-receiver safe" but until this
+// test landed nothing actually pinned that claim — exactly the
+// behavioral-comment-without-test footgun caught in PR #984 review.
+func TestTypedErrors_UnwrapNilReceiver(t *testing.T) {
+	t.Helper()
+	checks := []struct {
+		name string
+		call func() error
+	}{
+		{"ValidationError", func() error { var e *ValidationError; return e.Unwrap() }},
+		{"AuthenticationError", func() error { var e *AuthenticationError; return e.Unwrap() }},
+		{"ConfigError", func() error { var e *ConfigError; return e.Unwrap() }},
+		{"NetworkError", func() error { var e *NetworkError; return e.Unwrap() }},
+		{"SecurityPolicyError", func() error { var e *SecurityPolicyError; return e.Unwrap() }},
+		{"InternalError", func() error { var e *InternalError; return e.Unwrap() }},
+	}
+	for _, c := range checks {
+		t.Run(c.name, func(t *testing.T) {
+			defer func() {
+				if r := recover(); r != nil {
+					t.Fatalf("(*%s)(nil).Unwrap() panicked: %v", c.name, r)
+				}
+			}()
+			if got := c.call(); got != nil {
+				t.Errorf("(*%s)(nil).Unwrap() = %v, want nil", c.name, got)
+			}
+		})
+	}
+}
+
+// TestTypedErrors_UnwrapPropagatesCause pins the positive Unwrap path so the
+// nil-safety guard above does not silently drop a real Cause on non-nil
+// receivers. Without this, a buggy refactor could change `return e.Cause` to
+// `return nil` and the test suite would still pass.
+func TestTypedErrors_UnwrapPropagatesCause(t *testing.T) {
+	cause := errors.New("upstream cause")
+	cases := []struct {
+		name string
+		err  interface{ Unwrap() error }
+	}{
+		{"ValidationError", &ValidationError{Cause: cause}},
+		{"AuthenticationError", &AuthenticationError{Cause: cause}},
+		{"ConfigError", &ConfigError{Cause: cause}},
+		{"NetworkError", &NetworkError{Cause: cause}},
+		{"SecurityPolicyError", &SecurityPolicyError{Cause: cause}},
+		{"InternalError", &InternalError{Cause: cause}},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			if got := c.err.Unwrap(); got != cause {
+				t.Errorf("(*%s).Unwrap() = %v, want %v", c.name, got, cause)
+			}
+		})
+	}
+}

errs/wrap.go

@@ -0,0 +1,27 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errs
+
+import "errors"
+
+// WrapInternal wraps a non-typed error into *InternalError.
+// Typed errors (anything implementing problemCarrier) pass through unchanged.
+// Component is metric-only and derived by the dispatcher, so it is not a parameter here.
+func WrapInternal(err error) error {
+	if err == nil {
+		return nil
+	}
+	var c problemCarrier
+	if errors.As(err, &c) {
+		return err
+	}
+	return &InternalError{
+		Problem: Problem{
+			Category: CategoryInternal,
+			Subtype:  SubtypeUnknown,
+			Message:  err.Error(),
+		},
+		Cause: err,
+	}
+}

errs/wrap_test.go

@@ -0,0 +1,49 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errs
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+)
+
+func TestWrapInternalPlainError(t *testing.T) {
+	orig := fmt.Errorf("boom")
+	wrapped := WrapInternal(orig)
+
+	var ie *InternalError
+	if !errors.As(wrapped, &ie) {
+		t.Fatalf("WrapInternal did not produce *InternalError; got %T", wrapped)
+	}
+	if ie.Category != CategoryInternal {
+		t.Errorf("Category = %q, want %q", ie.Category, CategoryInternal)
+	}
+	if ie.Subtype != SubtypeUnknown {
+		t.Errorf("Subtype = %q, want %q", ie.Subtype, SubtypeUnknown)
+	}
+	if ie.Message != "boom" {
+		t.Errorf("Message = %q, want %q", ie.Message, "boom")
+	}
+	if ie.Cause != orig {
+		t.Errorf("Cause = %v, want original error %v", ie.Cause, orig)
+	}
+	if got := errors.Unwrap(wrapped); got != orig {
+		t.Errorf("errors.Unwrap = %v, want original %v", got, orig)
+	}
+}
+
+func TestWrapInternalPassesThroughTyped(t *testing.T) {
+	apiErr := &APIError{Problem: Problem{Category: CategoryAPI, Message: "api boom"}}
+	got := WrapInternal(apiErr)
+	if got != apiErr {
+		t.Errorf("WrapInternal should pass through typed errors unchanged; got %#v want %#v", got, apiErr)
+	}
+}
+
+func TestWrapInternalNil(t *testing.T) {
+	if got := WrapInternal(nil); got != nil {
+		t.Errorf("WrapInternal(nil) = %v, want nil", got)
+	}
+}

events/minutes/minute_generated.go

@@ -0,0 +1,116 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package minutes
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"github.com/larksuite/cli/internal/event"
+	"github.com/larksuite/cli/internal/validate"
+)
+
+const (
+	minutesDetailRetryDelay = 500 * time.Millisecond
+	minutesDetailMaxRetries = 2
+)
+
+// MinutesMinuteSourceOutput is the flattened minute source payload.
+type MinutesMinuteSourceOutput struct {
+	SourceType     string `json:"source_type,omitempty"      desc:"Minute source type"`
+	SourceEntityID string `json:"source_entity_id,omitempty" desc:"Source entity ID"`
+}
+
+// MinutesMinuteGeneratedOutput is the flattened shape for minutes.minute.generated_v1.
+type MinutesMinuteGeneratedOutput struct {
+	Type         string                     `json:"type"                     desc:"Event type; always minutes.minute.generated_v1"`
+	EventID      string                     `json:"event_id,omitempty"       desc:"Globally unique event ID; safe for deduplication"`
+	Timestamp    string                     `json:"timestamp,omitempty"      desc:"Event delivery time (ms timestamp string); taken from header.create_time when present" kind:"timestamp_ms"`
+	MinuteToken  string                     `json:"minute_token,omitempty"   desc:"Minute token"`
+	Title        string                     `json:"title,omitempty"          desc:"Minute title"`
+	MinuteSource *MinutesMinuteSourceOutput `json:"minute_source,omitempty"  desc:"Minute source metadata"`
+}
+
+func processMinutesMinuteGenerated(ctx context.Context, rt event.APIClient, raw *event.RawEvent, _ map[string]string) (json.RawMessage, error) {
+	var envelope struct {
+		Header struct {
+			EventID    string `json:"event_id"`
+			EventType  string `json:"event_type"`
+			CreateTime string `json:"create_time"`
+		} `json:"header"`
+		Event struct {
+			MinuteToken  string `json:"minute_token"`
+			MinuteSource struct {
+				SourceType     string `json:"source_type"`
+				SourceEntityID string `json:"source_entity_id"`
+			} `json:"minute_source"`
+		} `json:"event"`
+	}
+	if err := json.Unmarshal(raw.Payload, &envelope); err != nil {
+		return raw.Payload, nil //nolint:nilerr // passthrough on malformed payload so consumers still see the event
+	}
+
+	out := &MinutesMinuteGeneratedOutput{
+		Type:        envelope.Header.EventType,
+		EventID:     envelope.Header.EventID,
+		Timestamp:   envelope.Header.CreateTime,
+		MinuteToken: envelope.Event.MinuteToken,
+	}
+	if out.Type == "" {
+		out.Type = raw.EventType
+	}
+	if src := envelope.Event.MinuteSource; src.SourceType != "" || src.SourceEntityID != "" {
+		out.MinuteSource = &MinutesMinuteSourceOutput{
+			SourceType:     src.SourceType,
+			SourceEntityID: src.SourceEntityID,
+		}
+	}
+
+	if rt != nil && out.MinuteToken != "" {
+		fillMinutesMinuteGeneratedDetails(ctx, rt, out)
+	}
+
+	return json.Marshal(out)
+}
+
+func fillMinutesMinuteGeneratedDetails(ctx context.Context, rt event.APIClient, out *MinutesMinuteGeneratedOutput) {
+	if rt == nil || out == nil || out.MinuteToken == "" {
+		return
+	}
+
+	path := fmt.Sprintf(pathMinuteDetailFmt, validate.EncodePathSegment(out.MinuteToken))
+
+	type minuteDetailResp struct {
+		Data struct {
+			Minute struct {
+				Title string `json:"title"`
+			} `json:"minute"`
+		} `json:"data"`
+	}
+
+	for attempt := 0; attempt <= minutesDetailMaxRetries; attempt++ {
+		if attempt > 0 {
+			time.Sleep(minutesDetailRetryDelay)
+		}
+
+		raw, err := rt.CallAPI(ctx, "GET", path, nil)
+		if err != nil {
+			continue
+		}
+
+		var resp minuteDetailResp
+		if err := json.Unmarshal(raw, &resp); err != nil {
+			continue
+		}
+
+		if resp.Data.Minute.Title == "" {
+			continue
+		}
+
+		out.Title = resp.Data.Minute.Title
+		return
+	}
+}

events/minutes/minute_generated_test.go

@@ -0,0 +1,353 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package minutes
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"reflect"
+	"testing"
+	"time"
+
+	"github.com/larksuite/cli/internal/event"
+	"github.com/larksuite/cli/internal/validate"
+)
+
+type stubAPIClient struct {
+	callFn func(ctx context.Context, method, path string, body any) (json.RawMessage, error)
+}
+
+func (s *stubAPIClient) CallAPI(ctx context.Context, method, path string, body any) (json.RawMessage, error) {
+	if s.callFn == nil {
+		return nil, nil
+	}
+	return s.callFn(ctx, method, path, body)
+}
+
+func assertSubscriptionRequest(t *testing.T, gotBody any, wantEventType string) {
+	t.Helper()
+	want := map[string]string{"event_type": wantEventType}
+	if !reflect.DeepEqual(gotBody, want) {
+		t.Fatalf("request body = %#v, want %#v", gotBody, want)
+	}
+}
+
+func TestMain(m *testing.M) {
+	for _, k := range Keys() {
+		event.RegisterKey(k)
+	}
+	os.Exit(m.Run())
+}
+
+func TestMinutesKeys_ProcessedMinuteGeneratedRegistered(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	def, ok := event.Lookup(eventTypeMinuteGenerated)
+	if !ok {
+		t.Fatalf("%s should be registered via Keys()", eventTypeMinuteGenerated)
+	}
+	if def.Schema.Custom == nil {
+		t.Error("Processed key must set Schema.Custom")
+	}
+	if def.Schema.Native != nil {
+		t.Error("Processed key must not set Schema.Native")
+	}
+	if def.Process == nil {
+		t.Error("Process must not be nil for processed key")
+	}
+	if def.PreConsume == nil {
+		t.Error("PreConsume must not be nil for processed key")
+	}
+	if len(def.Scopes) != 1 || def.Scopes[0] != "minutes:minutes.basic:read" {
+		t.Errorf("Scopes = %v", def.Scopes)
+	}
+	if len(def.AuthTypes) != 1 || def.AuthTypes[0] != "user" {
+		t.Errorf("AuthTypes = %v", def.AuthTypes)
+	}
+}
+
+func TestProcessMinutesMinuteGenerated(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	var gotMethod, gotPath string
+	rt := &stubAPIClient{
+		callFn: func(_ context.Context, method, path string, body any) (json.RawMessage, error) {
+			gotMethod = method
+			gotPath = path
+			if body != nil {
+				t.Fatalf("GET detail body = %#v, want nil", body)
+			}
+			return json.RawMessage(`{
+				"code": 0,
+				"msg": "success",
+				"data": {
+					"minute": {
+						"token": "<doc_token_001>",
+						"title": "产品周会的视频会议",
+						"note_id": "7616590025794260496"
+					}
+				}
+			}`), nil
+		},
+	}
+
+	out := runMinuteGenerated(t, rt, `{
+		"schema": "2.0",
+		"header": {
+			"event_id": "ev_minute_001",
+			"event_type": "minutes.minute.generated_v1",
+			"create_time": "1608725989000"
+		},
+		"event": {
+			"minute_token": "<doc_token_001>",
+			"minute_source": {
+				"source_type": "meeting",
+				"source_entity_id": "6911188411934433028"
+			}
+		}
+	}`)
+
+	if gotMethod != "GET" {
+		t.Errorf("detail method = %q, want GET", gotMethod)
+	}
+	if gotPath != fmt.Sprintf("/open-apis/minutes/v1/minutes/%s", validate.EncodePathSegment("<doc_token_001>")) {
+		t.Errorf("detail path = %q", gotPath)
+	}
+	if out.Type != eventTypeMinuteGenerated {
+		t.Errorf("Type = %q", out.Type)
+	}
+	if out.EventID != "ev_minute_001" || out.Timestamp != "1608725989000" {
+		t.Errorf("EventID/Timestamp = %q/%q", out.EventID, out.Timestamp)
+	}
+	if out.MinuteToken != "<doc_token_001>" {
+		t.Errorf("MinuteToken = %q", out.MinuteToken)
+	}
+	if out.Title != "产品周会的视频会议" {
+		t.Errorf("Title = %q", out.Title)
+	}
+	if out.MinuteSource == nil {
+		t.Fatal("MinuteSource should not be nil")
+	}
+	if out.MinuteSource.SourceType != "meeting" || out.MinuteSource.SourceEntityID != "6911188411934433028" {
+		t.Errorf("MinuteSource = %+v", out.MinuteSource)
+	}
+}
+
+func TestProcessMinutesMinuteGenerated_DetailFailureFallsBackToBaseFields(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	called := 0
+	rt := &stubAPIClient{
+		callFn: func(_ context.Context, method, path string, body any) (json.RawMessage, error) {
+			called++
+			return nil, context.DeadlineExceeded
+		},
+	}
+
+	out := runMinuteGenerated(t, rt, `{
+		"schema": "2.0",
+		"header": {
+			"event_id": "ev_minute_002",
+			"event_type": "minutes.minute.generated_v1",
+			"create_time": "1608725989001"
+		},
+		"event": {
+			"minute_token": "<doc_token_004>",
+			"minute_source": {
+				"source_type": "meeting",
+				"source_entity_id": "7641156270787481117"
+			}
+		}
+	}`)
+
+	wantCalls := 1 + minutesDetailMaxRetries
+	if called != wantCalls {
+		t.Fatalf("detail API called %d times, want %d", called, wantCalls)
+	}
+	if out.MinuteToken != "<doc_token_004>" {
+		t.Errorf("MinuteToken = %q", out.MinuteToken)
+	}
+	if out.Title != "" {
+		t.Errorf("Title = %q, want empty", out.Title)
+	}
+	if out.MinuteSource == nil {
+		t.Fatal("MinuteSource should remain from event payload")
+	}
+	if out.MinuteSource.SourceType != "meeting" || out.MinuteSource.SourceEntityID != "7641156270787481117" {
+		t.Errorf("MinuteSource = %+v", out.MinuteSource)
+	}
+}
+
+func TestProcessMinutesMinuteGenerated_EmptyTitleRetriesAndSucceeds(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	called := 0
+	rt := &stubAPIClient{
+		callFn: func(_ context.Context, _, _ string, _ any) (json.RawMessage, error) {
+			called++
+			if called <= 1 {
+				return json.RawMessage(`{
+					"code": 0,
+					"msg": "success",
+					"data": {
+						"minute": {
+							"title": ""
+						}
+					}
+				}`), nil
+			}
+			return json.RawMessage(`{
+				"code": 0,
+				"msg": "success",
+				"data": {
+					"minute": {
+						"title": "delayed title"
+					}
+				}
+			}`), nil
+		},
+	}
+
+	out := runMinuteGenerated(t, rt, `{
+		"schema": "2.0",
+		"header": {
+			"event_id": "ev_minute_retry",
+			"event_type": "minutes.minute.generated_v1",
+			"create_time": "1608725989000"
+		},
+		"event": {
+			"minute_token": "<doc_token_003>"
+		}
+	}`)
+
+	if called != 2 {
+		t.Fatalf("detail API called %d times, want 2 (1 initial + 1 retry)", called)
+	}
+	if out.Title != "delayed title" {
+		t.Errorf("Title = %q, want delayed title", out.Title)
+	}
+}
+
+func TestProcessMinutesMinuteGenerated_EmptyTitleExhaustsRetries(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	called := 0
+	rt := &stubAPIClient{
+		callFn: func(_ context.Context, _, _ string, _ any) (json.RawMessage, error) {
+			called++
+			return json.RawMessage(`{
+				"code": 0,
+				"msg": "success",
+				"data": {
+					"minute": {
+						"title": ""
+					}
+				}
+			}`), nil
+		},
+	}
+
+	out := runMinuteGenerated(t, rt, `{
+		"schema": "2.0",
+		"header": {
+			"event_id": "ev_minute_exhaust",
+			"event_type": "minutes.minute.generated_v1",
+			"create_time": "1608725989000"
+		},
+		"event": {
+			"minute_token": "<doc_token_002>"
+		}
+	}`)
+
+	wantCalls := 1 + minutesDetailMaxRetries
+	if called != wantCalls {
+		t.Fatalf("detail API called %d times, want %d", called, wantCalls)
+	}
+	if out.Title != "" {
+		t.Errorf("Title = %q, want empty after exhausted retries", out.Title)
+	}
+}
+
+func TestMinutesMinuteGenerated_PreConsumeSubscriptionLifecycle(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	def, ok := event.Lookup(eventTypeMinuteGenerated)
+	if !ok {
+		t.Fatalf("%s should be registered via Keys()", eventTypeMinuteGenerated)
+	}
+
+	type call struct {
+		method string
+		path   string
+		body   any
+	}
+	var calls []call
+	rt := &stubAPIClient{
+		callFn: func(_ context.Context, method, path string, body any) (json.RawMessage, error) {
+			calls = append(calls, call{method: method, path: path, body: body})
+			return json.RawMessage(`{"code":0,"msg":"success","data":{}}`), nil
+		},
+	}
+
+	cleanup, err := def.PreConsume(context.Background(), rt, nil)
+	if err != nil {
+		t.Fatalf("PreConsume error: %v", err)
+	}
+	if cleanup == nil {
+		t.Fatal("cleanup must not be nil")
+	}
+	if len(calls) != 1 {
+		t.Fatalf("calls after subscribe = %d, want 1", len(calls))
+	}
+	if calls[0].method != "POST" || calls[0].path != pathMinuteSubscribe {
+		t.Fatalf("subscribe call = %+v", calls[0])
+	}
+	assertSubscriptionRequest(t, calls[0].body, eventTypeMinuteGenerated)
+
+	cleanup()
+	if len(calls) != 2 {
+		t.Fatalf("calls after cleanup = %d, want 2", len(calls))
+	}
+	if calls[1].method != "POST" || calls[1].path != pathMinuteUnsubscribe {
+		t.Fatalf("unsubscribe call = %+v", calls[1])
+	}
+	assertSubscriptionRequest(t, calls[1].body, eventTypeMinuteGenerated)
+}
+
+func TestProcessMinutesMinuteGenerated_MalformedPayload(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	raw := &event.RawEvent{
+		EventType: eventTypeMinuteGenerated,
+		Payload:   json.RawMessage(`not json`),
+		Timestamp: time.Now(),
+	}
+	got, err := processMinutesMinuteGenerated(context.Background(), nil, raw, nil)
+	if err != nil {
+		t.Fatalf("Process should swallow parse errors, got %v", err)
+	}
+	if string(got) != "not json" {
+		t.Errorf("malformed fallback output = %q, want original bytes", string(got))
+	}
+}
+
+func runMinuteGenerated(t *testing.T, rt event.APIClient, payload string) MinutesMinuteGeneratedOutput {
+	t.Helper()
+	raw := &event.RawEvent{
+		EventType: eventTypeMinuteGenerated,
+		Payload:   json.RawMessage(payload),
+		Timestamp: time.Now(),
+	}
+	got, err := processMinutesMinuteGenerated(context.Background(), rt, raw, nil)
+	if err != nil {
+		t.Fatalf("Process error: %v", err)
+	}
+	var out MinutesMinuteGeneratedOutput
+	if err := json.Unmarshal(got, &out); err != nil {
+		t.Fatalf("Process output is not valid MinutesMinuteGeneratedOutput JSON: %v\nraw=%s", err, string(got))
+	}
+	return out
+}

events/minutes/preconsume.go

@@ -0,0 +1,33 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package minutes
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/larksuite/cli/internal/event"
+)
+
+const cleanupTimeout = 5 * time.Second
+
+func subscriptionPreConsume(eventType, subscribePath, unsubscribePath string) func(context.Context, event.APIClient, map[string]string) (func(), error) {
+	return func(ctx context.Context, rt event.APIClient, _ map[string]string) (func(), error) {
+		if rt == nil {
+			return nil, fmt.Errorf("runtime API client is required for pre-consume subscription")
+		}
+
+		body := map[string]string{"event_type": eventType}
+		if _, err := rt.CallAPI(ctx, "POST", subscribePath, body); err != nil {
+			return nil, err
+		}
+
+		return func() {
+			cleanupCtx, cancel := context.WithTimeout(context.Background(), cleanupTimeout)
+			defer cancel()
+			_, _ = rt.CallAPI(cleanupCtx, "POST", unsubscribePath, body)
+		}, nil
+	}
+}

events/minutes/register.go

@@ -0,0 +1,42 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package minutes registers Minutes-domain EventKeys.
+package minutes
+
+import (
+	"reflect"
+
+	"github.com/larksuite/cli/internal/event"
+)
+
+const (
+	eventTypeMinuteGenerated = "minutes.minute.generated_v1"
+
+	pathMinuteSubscribe   = "/open-apis/minutes/v1/minutes/subscription"
+	pathMinuteUnsubscribe = "/open-apis/minutes/v1/minutes/unsubscription"
+
+	pathMinuteDetailFmt = "/open-apis/minutes/v1/minutes/%s"
+)
+
+// Keys returns all Minutes-domain EventKey definitions.
+func Keys() []event.KeyDefinition {
+	return []event.KeyDefinition{
+		{
+			Key:         eventTypeMinuteGenerated,
+			DisplayName: "Minute generated",
+			Description: "Triggered when a minute has been generated",
+			EventType:   eventTypeMinuteGenerated,
+			Schema: event.SchemaDef{
+				Custom: &event.SchemaSpec{Type: reflect.TypeOf(MinutesMinuteGeneratedOutput{})},
+			},
+			Process:    processMinutesMinuteGenerated,
+			PreConsume: subscriptionPreConsume(eventTypeMinuteGenerated, pathMinuteSubscribe, pathMinuteUnsubscribe),
+			Scopes:     []string{"minutes:minutes.basic:read"},
+			AuthTypes: []string{
+				"user",
+			},
+			RequiredConsoleEvents: []string{eventTypeMinuteGenerated},
+		},
+	}
+}

events/register.go

@@ -6,13 +6,17 @@ package events
 
 import (
 	"github.com/larksuite/cli/events/im"
+	"github.com/larksuite/cli/events/minutes"
+	"github.com/larksuite/cli/events/vc"
 	"github.com/larksuite/cli/internal/event"
 )
 
-// Mail is intentionally omitted: only IM is wired up this phase.
+// Mail is intentionally omitted in this phase.
 func init() {
 	all := [][]event.KeyDefinition{
 		im.Keys(),
+		minutes.Keys(),
+		vc.Keys(),
 	}
 	for _, keys := range all {
 		for _, k := range keys {

events/vc/note_generated.go

@@ -0,0 +1,156 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/larksuite/cli/internal/event"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+)
+
+const (
+	vcNoteArtifactTypeNote     = 1
+	vcNoteArtifactTypeVerbatim = 2
+
+	vcNoteDetailRetryDelay   = 500 * time.Millisecond
+	vcNoteDetailMaxRetries   = 2
+	vcNoteDetailNotFoundCode = 121004
+)
+
+// VCNoteSourceOutput is the flattened note source payload.
+type VCNoteSourceOutput struct {
+	SourceType     string `json:"source_type,omitempty"      desc:"Note source type"`
+	SourceEntityID string `json:"source_entity_id,omitempty" desc:"Source entity ID"`
+}
+
+// VCNoteGeneratedOutput is the flattened shape for vc.note.generated_v1.
+type VCNoteGeneratedOutput struct {
+	Type          string              `json:"type"                        desc:"Event type; always vc.note.generated_v1"`
+	EventID       string              `json:"event_id,omitempty"          desc:"Globally unique event ID; safe for deduplication"`
+	Timestamp     string              `json:"timestamp,omitempty"         desc:"Event delivery time (ms timestamp string); taken from header.create_time when present" kind:"timestamp_ms"`
+	NoteID        string              `json:"note_id,omitempty"           desc:"Note ID"`
+	NoteToken     string              `json:"note_token,omitempty"        desc:"Generated note document token"`
+	VerbatimToken string              `json:"verbatim_token,omitempty"    desc:"Generated verbatim document token"`
+	NoteSource    *VCNoteSourceOutput `json:"note_source,omitempty"       desc:"Note source metadata"`
+}
+
+func processVCNoteGenerated(ctx context.Context, rt event.APIClient, raw *event.RawEvent, _ map[string]string) (json.RawMessage, error) {
+	var envelope struct {
+		Header struct {
+			EventID    string `json:"event_id"`
+			EventType  string `json:"event_type"`
+			CreateTime string `json:"create_time"`
+		} `json:"header"`
+		Event struct {
+			NoteID string `json:"note_id"`
+		} `json:"event"`
+	}
+	if err := json.Unmarshal(raw.Payload, &envelope); err != nil {
+		return raw.Payload, nil //nolint:nilerr // passthrough on malformed payload so consumers still see the event
+	}
+
+	out := &VCNoteGeneratedOutput{
+		Type:      envelope.Header.EventType,
+		EventID:   envelope.Header.EventID,
+		Timestamp: envelope.Header.CreateTime,
+		NoteID:    envelope.Event.NoteID,
+	}
+	if out.Type == "" {
+		out.Type = raw.EventType
+	}
+
+	if rt != nil && out.NoteID != "" {
+		fillVCNoteGeneratedDetails(ctx, rt, out)
+	}
+
+	return json.Marshal(out)
+}
+
+func fillVCNoteGeneratedDetails(ctx context.Context, rt event.APIClient, out *VCNoteGeneratedOutput) {
+	if rt == nil || out == nil || out.NoteID == "" {
+		return
+	}
+
+	path := fmt.Sprintf(pathNoteDetailFmt, validate.EncodePathSegment(out.NoteID))
+
+	type noteDetailResp struct {
+		Data struct {
+			Note struct {
+				Artifacts []struct {
+					ArtifactType int    `json:"artifact_type"`
+					DocToken     string `json:"doc_token"`
+				} `json:"artifacts"`
+				NoteSource struct {
+					SourceEntityID string `json:"source_entity_id"`
+					SourceType     string `json:"source_type"`
+				} `json:"note_source"`
+			} `json:"note"`
+		} `json:"data"`
+	}
+
+	for attempt := 0; attempt <= vcNoteDetailMaxRetries; attempt++ {
+		if attempt > 0 {
+			time.Sleep(vcNoteDetailRetryDelay)
+		}
+
+		raw, err := rt.CallAPI(ctx, "GET", path, nil)
+		if err != nil {
+			if isLarkCode(err, vcNoteDetailNotFoundCode) {
+				continue
+			}
+			return
+		}
+
+		var resp noteDetailResp
+		if err := json.Unmarshal(raw, &resp); err != nil {
+			continue
+		}
+
+		var noteToken, verbatimToken string
+		for _, artifact := range resp.Data.Note.Artifacts {
+			switch artifact.ArtifactType {
+			case vcNoteArtifactTypeNote:
+				if noteToken == "" {
+					noteToken = artifact.DocToken
+				}
+			case vcNoteArtifactTypeVerbatim:
+				if verbatimToken == "" {
+					verbatimToken = artifact.DocToken
+				}
+			}
+		}
+
+		if noteToken == "" && verbatimToken == "" {
+			continue
+		}
+
+		if noteToken != "" {
+			out.NoteToken = noteToken
+		}
+		if verbatimToken != "" {
+			out.VerbatimToken = verbatimToken
+		}
+		if src := resp.Data.Note.NoteSource; src.SourceType != "" || src.SourceEntityID != "" {
+			out.NoteSource = &VCNoteSourceOutput{
+				SourceType:     src.SourceType,
+				SourceEntityID: src.SourceEntityID,
+			}
+		}
+		return
+	}
+}
+
+func isLarkCode(err error, code int) bool {
+	var exitErr *output.ExitError
+	if errors.As(err, &exitErr) && exitErr.Detail != nil {
+		return exitErr.Detail.Code == code
+	}
+	return false
+}

events/vc/note_generated_test.go

@@ -0,0 +1,328 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"encoding/json"
+	"testing"
+	"time"
+
+	"github.com/larksuite/cli/internal/event"
+)
+
+func TestVCKeys_ProcessedNoteGeneratedRegistered(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	def, ok := event.Lookup(eventTypeNoteGenerated)
+	if !ok {
+		t.Fatalf("%s should be registered via Keys()", eventTypeNoteGenerated)
+	}
+	if def.Schema.Custom == nil {
+		t.Error("Processed key must set Schema.Custom")
+	}
+	if def.Schema.Native != nil {
+		t.Error("Processed key must not set Schema.Native")
+	}
+	if def.Process == nil {
+		t.Error("Process must not be nil for processed key")
+	}
+	if def.PreConsume == nil {
+		t.Error("PreConsume must not be nil for processed key")
+	}
+	if len(def.Scopes) != 1 || def.Scopes[0] != "vc:note:read" {
+		t.Errorf("Scopes = %v", def.Scopes)
+	}
+	if len(def.AuthTypes) != 1 || def.AuthTypes[0] != "user" {
+		t.Errorf("AuthTypes = %v", def.AuthTypes)
+	}
+}
+
+func TestProcessVCNoteGenerated(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	var gotMethod, gotPath string
+	rt := &stubAPIClient{
+		callFn: func(_ context.Context, method, path string, body any) (json.RawMessage, error) {
+			gotMethod = method
+			gotPath = path
+			if body != nil {
+				t.Fatalf("GET detail body = %#v, want nil", body)
+			}
+			return json.RawMessage(`{
+				"code": 0,
+				"msg": "success",
+				"data": {
+					"note": {
+						"artifacts": [
+							{"artifact_type": 1, "doc_token": "note_doc_token"},
+							{"artifact_type": 2, "doc_token": "verbatim_doc_token"}
+						],
+						"note_source": {
+							"source_type": "meeting",
+							"source_entity_id": "6911188411934433028"
+						}
+					}
+				}
+			}`), nil
+		},
+	}
+
+	out := runNoteGenerated(t, rt, `{
+		"schema": "2.0",
+		"header": {
+			"event_id": "ev_vc_note_001",
+			"event_type": "vc.note.generated_v1",
+			"create_time": "1608725989000"
+		},
+		"event": {
+			"note_id": "6943848821689040898"
+		}
+	}`)
+
+	if gotMethod != "GET" {
+		t.Errorf("detail method = %q, want GET", gotMethod)
+	}
+	if gotPath != "/open-apis/vc/v1/notes/6943848821689040898" {
+		t.Errorf("detail path = %q", gotPath)
+	}
+	if out.Type != eventTypeNoteGenerated {
+		t.Errorf("Type = %q", out.Type)
+	}
+	if out.EventID != "ev_vc_note_001" || out.Timestamp != "1608725989000" {
+		t.Errorf("EventID/Timestamp = %q/%q", out.EventID, out.Timestamp)
+	}
+	if out.NoteID != "6943848821689040898" {
+		t.Errorf("NoteID = %q", out.NoteID)
+	}
+	if out.NoteToken != "note_doc_token" {
+		t.Errorf("NoteToken = %q", out.NoteToken)
+	}
+	if out.VerbatimToken != "verbatim_doc_token" {
+		t.Errorf("VerbatimToken = %q", out.VerbatimToken)
+	}
+	if out.NoteSource == nil {
+		t.Fatal("NoteSource should not be nil")
+	}
+	if out.NoteSource.SourceType != "meeting" || out.NoteSource.SourceEntityID != "6911188411934433028" {
+		t.Errorf("NoteSource = %+v", out.NoteSource)
+	}
+}
+
+func TestVCNoteGenerated_PreConsumeSubscriptionLifecycle(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	def, ok := event.Lookup(eventTypeNoteGenerated)
+	if !ok {
+		t.Fatalf("%s should be registered via Keys()", eventTypeNoteGenerated)
+	}
+
+	type call struct {
+		method string
+		path   string
+		body   any
+	}
+	var calls []call
+	rt := &stubAPIClient{
+		callFn: func(_ context.Context, method, path string, body any) (json.RawMessage, error) {
+			calls = append(calls, call{method: method, path: path, body: body})
+			return json.RawMessage(`{"code":0,"msg":"success","data":{}}`), nil
+		},
+	}
+
+	cleanup, err := def.PreConsume(context.Background(), rt, nil)
+	if err != nil {
+		t.Fatalf("PreConsume error: %v", err)
+	}
+	if cleanup == nil {
+		t.Fatal("cleanup must not be nil")
+	}
+	if len(calls) != 1 {
+		t.Fatalf("calls after subscribe = %d, want 1", len(calls))
+	}
+	if calls[0].method != "POST" || calls[0].path != pathNoteSubscribe {
+		t.Fatalf("subscribe call = %+v", calls[0])
+	}
+	assertSubscriptionRequest(t, calls[0].body, eventTypeNoteGenerated)
+
+	cleanup()
+	if len(calls) != 2 {
+		t.Fatalf("calls after cleanup = %d, want 2", len(calls))
+	}
+	if calls[1].method != "POST" || calls[1].path != pathNoteUnsubscribe {
+		t.Fatalf("unsubscribe call = %+v", calls[1])
+	}
+	assertSubscriptionRequest(t, calls[1].body, eventTypeNoteGenerated)
+}
+
+func TestProcessVCNoteGenerated_DetailFailureFallsBackToBaseFields(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	called := 0
+	rt := &stubAPIClient{
+		callFn: func(_ context.Context, method, path string, body any) (json.RawMessage, error) {
+			called++
+			return nil, context.DeadlineExceeded
+		},
+	}
+
+	out := runNoteGenerated(t, rt, `{
+		"schema": "2.0",
+		"header": {
+			"event_id": "ev_vc_note_002",
+			"event_type": "vc.note.generated_v1",
+			"create_time": "1608725989001"
+		},
+		"event": {
+			"note_id": "6943848821689040999"
+		}
+	}`)
+
+	if called != 1 {
+		t.Fatalf("detail API called %d times, want 1", called)
+	}
+	if out.NoteID != "6943848821689040999" {
+		t.Errorf("NoteID = %q", out.NoteID)
+	}
+	if out.NoteToken != "" || out.VerbatimToken != "" {
+		t.Errorf("NoteToken/VerbatimToken = %q/%q, want empty", out.NoteToken, out.VerbatimToken)
+	}
+	if out.NoteSource != nil {
+		t.Errorf("NoteSource = %+v, want nil", out.NoteSource)
+	}
+}
+
+func TestProcessVCNoteGenerated_EmptyTokensRetriesAndSucceeds(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	called := 0
+	rt := &stubAPIClient{
+		callFn: func(_ context.Context, _, _ string, _ any) (json.RawMessage, error) {
+			called++
+			if called <= 1 {
+				return json.RawMessage(`{
+					"code": 0,
+					"msg": "success",
+					"data": {
+						"note": {
+							"artifacts": [],
+							"note_source": {"source_type": "meeting", "source_entity_id": "123"}
+						}
+					}
+				}`), nil
+			}
+			return json.RawMessage(`{
+				"code": 0,
+				"msg": "success",
+				"data": {
+					"note": {
+						"artifacts": [
+							{"artifact_type": 1, "doc_token": "delayed_note_token"},
+							{"artifact_type": 2, "doc_token": "delayed_verbatim_token"}
+						],
+						"note_source": {"source_type": "meeting", "source_entity_id": "123"}
+					}
+				}
+			}`), nil
+		},
+	}
+
+	out := runNoteGenerated(t, rt, `{
+		"schema": "2.0",
+		"header": {
+			"event_id": "ev_vc_note_empty_retry",
+			"event_type": "vc.note.generated_v1",
+			"create_time": "1608725989000"
+		},
+		"event": {
+			"note_id": "6943848821689040empty"
+		}
+	}`)
+
+	if called != 2 {
+		t.Fatalf("detail API called %d times, want 2 (1 initial + 1 retry)", called)
+	}
+	if out.NoteToken != "delayed_note_token" {
+		t.Errorf("NoteToken = %q, want delayed_note_token", out.NoteToken)
+	}
+	if out.VerbatimToken != "delayed_verbatim_token" {
+		t.Errorf("VerbatimToken = %q, want delayed_verbatim_token", out.VerbatimToken)
+	}
+}
+
+func TestProcessVCNoteGenerated_EmptyTokensExhaustsRetries(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	called := 0
+	rt := &stubAPIClient{
+		callFn: func(_ context.Context, _, _ string, _ any) (json.RawMessage, error) {
+			called++
+			return json.RawMessage(`{
+				"code": 0,
+				"msg": "success",
+				"data": {
+					"note": {
+						"artifacts": [],
+						"note_source": {"source_type": "meeting", "source_entity_id": "123"}
+					}
+				}
+			}`), nil
+		},
+	}
+
+	out := runNoteGenerated(t, rt, `{
+		"schema": "2.0",
+		"header": {
+			"event_id": "ev_vc_note_empty_exhaust",
+			"event_type": "vc.note.generated_v1",
+			"create_time": "1608725989000"
+		},
+		"event": {
+			"note_id": "6943848821689040emptyex"
+		}
+	}`)
+
+	wantCalls := 1 + vcNoteDetailMaxRetries
+	if called != wantCalls {
+		t.Fatalf("detail API called %d times, want %d", called, wantCalls)
+	}
+	if out.NoteToken != "" || out.VerbatimToken != "" {
+		t.Errorf("NoteToken/VerbatimToken = %q/%q, want empty after exhausted retries", out.NoteToken, out.VerbatimToken)
+	}
+}
+
+func TestProcessVCNoteGenerated_MalformedPayload(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	raw := &event.RawEvent{
+		EventType: eventTypeNoteGenerated,
+		Payload:   json.RawMessage(`not json`),
+		Timestamp: time.Now(),
+	}
+	got, err := processVCNoteGenerated(context.Background(), nil, raw, nil)
+	if err != nil {
+		t.Fatalf("Process should swallow parse errors, got %v", err)
+	}
+	if string(got) != "not json" {
+		t.Errorf("malformed fallback output = %q, want original bytes", string(got))
+	}
+}
+
+func runNoteGenerated(t *testing.T, rt event.APIClient, payload string) VCNoteGeneratedOutput {
+	t.Helper()
+	raw := &event.RawEvent{
+		EventType: eventTypeNoteGenerated,
+		Payload:   json.RawMessage(payload),
+		Timestamp: time.Now(),
+	}
+	got, err := processVCNoteGenerated(context.Background(), rt, raw, nil)
+	if err != nil {
+		t.Fatalf("Process error: %v", err)
+	}
+	var out VCNoteGeneratedOutput
+	if err := json.Unmarshal(got, &out); err != nil {
+		t.Fatalf("Process output is not valid VCNoteGeneratedOutput JSON: %v\nraw=%s", err, string(got))
+	}
+	return out
+}

events/vc/participant_meeting_ended.go

@@ -0,0 +1,77 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"encoding/json"
+	"strconv"
+	"time"
+
+	"github.com/larksuite/cli/internal/event"
+)
+
+// VCParticipantMeetingEndedOutput is the flattened shape for vc.meeting.participant_meeting_ended_v1.
+type VCParticipantMeetingEndedOutput struct {
+	Type            string `json:"type"                      desc:"Event type; always vc.meeting.participant_meeting_ended_v1"`
+	EventID         string `json:"event_id,omitempty"        desc:"Globally unique event ID; safe for deduplication"`
+	Timestamp       string `json:"timestamp,omitempty"       desc:"Event delivery time (ms timestamp string); taken from header.create_time when present"                                                                 kind:"timestamp_ms"`
+	MeetingID       string `json:"meeting_id,omitempty"      desc:"Meeting ID"                                                                                                                                                kind:"meeting_id"`
+	Topic           string `json:"topic,omitempty"           desc:"Meeting topic"`
+	MeetingNo       string `json:"meeting_no,omitempty"      desc:"Meeting number"`
+	StartTime       string `json:"start_time,omitempty"      desc:"Meeting start time in RFC3339, converted to the local timezone"`
+	EndTime         string `json:"end_time,omitempty"        desc:"Meeting end time in RFC3339, converted to the local timezone"`
+	CalendarEventID string `json:"calendar_event_id,omitempty" desc:"Calendar event ID associated with the meeting"`
+}
+
+func processVCParticipantMeetingEnded(_ context.Context, _ event.APIClient, raw *event.RawEvent, _ map[string]string) (json.RawMessage, error) {
+	var envelope struct {
+		Header struct {
+			EventID    string `json:"event_id"`
+			EventType  string `json:"event_type"`
+			CreateTime string `json:"create_time"`
+		} `json:"header"`
+		Event struct {
+			Meeting struct {
+				ID              string `json:"id"`
+				Topic           string `json:"topic"`
+				MeetingNo       string `json:"meeting_no"`
+				StartTime       string `json:"start_time"`
+				EndTime         string `json:"end_time"`
+				CalendarEventID string `json:"calendar_event_id"`
+			} `json:"meeting"`
+		} `json:"event"`
+	}
+	if err := json.Unmarshal(raw.Payload, &envelope); err != nil {
+		return raw.Payload, nil //nolint:nilerr // passthrough on malformed payload so consumers still see the event
+	}
+
+	meeting := envelope.Event.Meeting
+	out := &VCParticipantMeetingEndedOutput{
+		Type:            envelope.Header.EventType,
+		EventID:         envelope.Header.EventID,
+		Timestamp:       envelope.Header.CreateTime,
+		MeetingID:       meeting.ID,
+		Topic:           meeting.Topic,
+		MeetingNo:       meeting.MeetingNo,
+		StartTime:       unixSecondsToLocalRFC3339(meeting.StartTime),
+		EndTime:         unixSecondsToLocalRFC3339(meeting.EndTime),
+		CalendarEventID: meeting.CalendarEventID,
+	}
+	if out.Type == "" {
+		out.Type = raw.EventType
+	}
+	return json.Marshal(out)
+}
+
+func unixSecondsToLocalRFC3339(raw string) string {
+	if raw == "" {
+		return ""
+	}
+	secs, err := strconv.ParseInt(raw, 10, 64)
+	if err != nil {
+		return ""
+	}
+	return time.Unix(secs, 0).Local().Format(time.RFC3339)
+}

events/vc/participant_meeting_ended_test.go

@@ -0,0 +1,203 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/larksuite/cli/internal/event"
+)
+
+func TestMain(m *testing.M) {
+	for _, k := range Keys() {
+		event.RegisterKey(k)
+	}
+	os.Exit(m.Run())
+}
+
+func TestVCKeys_ProcessedMeetingEndedRegistered(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	def, ok := event.Lookup(eventTypeMeetingEnded)
+	if !ok {
+		t.Fatalf("%s should be registered via Keys()", eventTypeMeetingEnded)
+	}
+	if def.Schema.Custom == nil {
+		t.Error("Processed key must set Schema.Custom")
+	}
+	if def.Schema.Native != nil {
+		t.Error("Processed key must not set Schema.Native")
+	}
+	if def.Process == nil {
+		t.Error("Process must not be nil for processed key")
+	}
+	if def.PreConsume == nil {
+		t.Error("PreConsume must not be nil for processed key")
+	}
+	if len(def.Scopes) != 1 || def.Scopes[0] != "vc:meeting.meetingevent:read" {
+		t.Errorf("Scopes = %v", def.Scopes)
+	}
+	if len(def.AuthTypes) != 1 || def.AuthTypes[0] != "user" {
+		t.Errorf("AuthTypes = %v", def.AuthTypes)
+	}
+}
+
+func TestProcessVCParticipantMeetingEnded(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	payload := `{
+		"schema": "2.0",
+		"header": {
+			"event_id": "ev_vc_end_001",
+			"event_type": "vc.meeting.participant_meeting_ended_v1",
+			"create_time": "1608725989000",
+			"app_id": "cli_test"
+		},
+		"event": {
+			"meeting": {
+				"id": "6911188411934433028",
+				"topic": "my meeting",
+				"meeting_no": "235812466",
+				"start_time": "1608883322",
+				"end_time": "1608883899",
+				"calendar_event_id": "efa67a98-06a8-4df5-8559-746c8f4477ef_0"
+			}
+		}
+	}`
+	out := runMeetingEnded(t, payload)
+
+	if out.Type != eventTypeMeetingEnded {
+		t.Errorf("Type = %q", out.Type)
+	}
+	if out.EventID != "ev_vc_end_001" {
+		t.Errorf("EventID = %q", out.EventID)
+	}
+	if out.Timestamp != "1608725989000" {
+		t.Errorf("Timestamp = %q", out.Timestamp)
+	}
+	if out.MeetingID != "6911188411934433028" {
+		t.Errorf("MeetingID = %q", out.MeetingID)
+	}
+	if out.Topic != "my meeting" || out.MeetingNo != "235812466" {
+		t.Errorf("Topic/MeetingNo = %q/%q", out.Topic, out.MeetingNo)
+	}
+	if out.CalendarEventID != "efa67a98-06a8-4df5-8559-746c8f4477ef_0" {
+		t.Errorf("CalendarEventID = %q", out.CalendarEventID)
+	}
+	if want := time.Unix(1608883322, 0).Local().Format(time.RFC3339); out.StartTime != want {
+		t.Errorf("StartTime = %q, want %q", out.StartTime, want)
+	}
+	if want := time.Unix(1608883899, 0).Local().Format(time.RFC3339); out.EndTime != want {
+		t.Errorf("EndTime = %q, want %q", out.EndTime, want)
+	}
+}
+
+func TestProcessVCParticipantMeetingEnded_InvalidMeetingTimes(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	payload := `{
+		"schema": "2.0",
+		"header": {
+			"event_id": "ev_vc_end_002",
+			"event_type": "vc.meeting.participant_meeting_ended_v1",
+			"create_time": "1608725989001"
+		},
+		"event": {
+			"meeting": {
+				"id": "meeting_invalid_time",
+				"start_time": "bad",
+				"end_time": ""
+			}
+		}
+	}`
+	out := runMeetingEnded(t, payload)
+	if out.StartTime != "" || out.EndTime != "" {
+		t.Errorf("StartTime/EndTime = %q/%q, want empty strings", out.StartTime, out.EndTime)
+	}
+}
+
+func TestProcessVCParticipantMeetingEnded_MalformedPayload(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	raw := &event.RawEvent{
+		EventType: eventTypeMeetingEnded,
+		Payload:   json.RawMessage(`not json`),
+		Timestamp: time.Now(),
+	}
+	got, err := processVCParticipantMeetingEnded(context.Background(), nil, raw, nil)
+	if err != nil {
+		t.Fatalf("Process should swallow parse errors, got %v", err)
+	}
+	if string(got) != "not json" {
+		t.Errorf("malformed fallback output = %q, want original bytes", string(got))
+	}
+}
+
+func TestVCParticipantMeetingEnded_PreConsumeSubscriptionLifecycle(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	def, ok := event.Lookup("vc.meeting.participant_meeting_ended_v1")
+	if !ok {
+		t.Fatal("vc.meeting.participant_meeting_ended_v1 should be registered via Keys()")
+	}
+
+	type call struct {
+		method string
+		path   string
+		body   any
+	}
+	var calls []call
+	rt := &stubAPIClient{
+		callFn: func(_ context.Context, method, path string, body any) (json.RawMessage, error) {
+			calls = append(calls, call{method: method, path: path, body: body})
+			return json.RawMessage(`{"code":0,"msg":"success","data":{}}`), nil
+		},
+	}
+
+	cleanup, err := def.PreConsume(context.Background(), rt, nil)
+	if err != nil {
+		t.Fatalf("PreConsume error: %v", err)
+	}
+	if cleanup == nil {
+		t.Fatal("cleanup must not be nil")
+	}
+	if len(calls) != 1 {
+		t.Fatalf("calls after subscribe = %d, want 1", len(calls))
+	}
+	if calls[0].method != "POST" || calls[0].path != pathMeetingSubscribe {
+		t.Fatalf("subscribe call = %+v", calls[0])
+	}
+	assertSubscriptionRequest(t, calls[0].body, eventTypeMeetingEnded)
+
+	cleanup()
+	if len(calls) != 2 {
+		t.Fatalf("calls after cleanup = %d, want 2", len(calls))
+	}
+	if calls[1].method != "POST" || calls[1].path != pathMeetingUnsubscribe {
+		t.Fatalf("unsubscribe call = %+v", calls[1])
+	}
+	assertSubscriptionRequest(t, calls[1].body, eventTypeMeetingEnded)
+}
+
+func runMeetingEnded(t *testing.T, payload string) VCParticipantMeetingEndedOutput {
+	t.Helper()
+	raw := &event.RawEvent{
+		EventType: eventTypeMeetingEnded,
+		Payload:   json.RawMessage(payload),
+		Timestamp: time.Now(),
+	}
+	got, err := processVCParticipantMeetingEnded(context.Background(), nil, raw, nil)
+	if err != nil {
+		t.Fatalf("Process error: %v", err)
+	}
+	var out VCParticipantMeetingEndedOutput
+	if err := json.Unmarshal(got, &out); err != nil {
+		t.Fatalf("Process output is not valid VCParticipantMeetingEndedOutput JSON: %v\nraw=%s", err, string(got))
+	}
+	return out
+}

events/vc/preconsume.go

@@ -0,0 +1,33 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/larksuite/cli/internal/event"
+)
+
+const cleanupTimeout = 5 * time.Second
+
+func subscriptionPreConsume(eventType, subscribePath, unsubscribePath string) func(context.Context, event.APIClient, map[string]string) (func(), error) {
+	return func(ctx context.Context, rt event.APIClient, _ map[string]string) (func(), error) {
+		if rt == nil {
+			return nil, fmt.Errorf("runtime API client is required for pre-consume subscription")
+		}
+
+		body := map[string]string{"event_type": eventType}
+		if _, err := rt.CallAPI(ctx, "POST", subscribePath, body); err != nil {
+			return nil, err
+		}
+
+		return func() {
+			cleanupCtx, cancel := context.WithTimeout(context.Background(), cleanupTimeout)
+			defer cancel()
+			_, _ = rt.CallAPI(cleanupCtx, "POST", unsubscribePath, body)
+		}, nil
+	}
+}

events/vc/register.go

@@ -0,0 +1,61 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package vc registers VC-domain EventKeys.
+package vc
+
+import (
+	"reflect"
+
+	"github.com/larksuite/cli/internal/event"
+)
+
+const (
+	eventTypeMeetingEnded  = "vc.meeting.participant_meeting_ended_v1"
+	eventTypeNoteGenerated = "vc.note.generated_v1"
+
+	pathMeetingSubscribe   = "/open-apis/vc/v1/meetings/subscription"
+	pathMeetingUnsubscribe = "/open-apis/vc/v1/meetings/unsubscription"
+	pathNoteSubscribe      = "/open-apis/vc/v1/notes/subscription"
+	pathNoteUnsubscribe    = "/open-apis/vc/v1/notes/unsubscription"
+
+	pathNoteDetailFmt = "/open-apis/vc/v1/notes/%s"
+)
+
+// Keys returns all VC-domain EventKey definitions.
+func Keys() []event.KeyDefinition {
+	return []event.KeyDefinition{
+		{
+			Key:         eventTypeMeetingEnded,
+			DisplayName: "Participant meeting ended",
+			Description: "Triggered when a meeting the current user participates in has ended",
+			EventType:   eventTypeMeetingEnded,
+			Schema: event.SchemaDef{
+				Custom: &event.SchemaSpec{Type: reflect.TypeOf(VCParticipantMeetingEndedOutput{})},
+			},
+			Process:    processVCParticipantMeetingEnded,
+			PreConsume: subscriptionPreConsume(eventTypeMeetingEnded, pathMeetingSubscribe, pathMeetingUnsubscribe),
+			Scopes:     []string{"vc:meeting.meetingevent:read"},
+			AuthTypes: []string{
+				"user",
+			},
+			RequiredConsoleEvents: []string{eventTypeMeetingEnded},
+		},
+		{
+			Key:         eventTypeNoteGenerated,
+			DisplayName: "Note generated",
+			Description: "Triggered when a note has been generated",
+			EventType:   eventTypeNoteGenerated,
+			Schema: event.SchemaDef{
+				Custom: &event.SchemaSpec{Type: reflect.TypeOf(VCNoteGeneratedOutput{})},
+			},
+			Process:    processVCNoteGenerated,
+			PreConsume: subscriptionPreConsume(eventTypeNoteGenerated, pathNoteSubscribe, pathNoteUnsubscribe),
+			Scopes:     []string{"vc:note:read"},
+			AuthTypes: []string{
+				"user",
+			},
+			RequiredConsoleEvents: []string{eventTypeNoteGenerated},
+		},
+	}
+}

events/vc/test_helpers_test.go

@@ -0,0 +1,30 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"encoding/json"
+	"reflect"
+	"testing"
+)
+
+type stubAPIClient struct {
+	callFn func(ctx context.Context, method, path string, body any) (json.RawMessage, error)
+}
+
+func (s *stubAPIClient) CallAPI(ctx context.Context, method, path string, body any) (json.RawMessage, error) {
+	if s.callFn == nil {
+		return nil, nil
+	}
+	return s.callFn(ctx, method, path, body)
+}
+
+func assertSubscriptionRequest(t *testing.T, gotBody any, wantEventType string) {
+	t.Helper()
+	want := map[string]string{"event_type": wantEventType}
+	if !reflect.DeepEqual(gotBody, want) {
+		t.Fatalf("request body = %#v, want %#v", gotBody, want)
+	}
+}

internal/auth/errors.go

@@ -8,21 +8,14 @@ import (
 	"fmt"
 	"strings"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/output"
 )
 
 const (
-	LarkErrBlockByPolicy        = 21001 // access denied by access control policy
-	LarkErrBlockByPolicyTryAuth = 21000 // access denied by access control policy; challenge is required to be completed by user in order to gain access
 	needUserAuthorizationMarker = "need_user_authorization"
 )
 
-// RefreshTokenRetryable contains error codes that allow one immediate retry.
-// All other refresh errors clear the token immediately.
-var RefreshTokenRetryable = map[int]bool{
-	output.LarkErrRefreshServerError: true,
-}
-
 // TokenRetryCodes contains error codes that allow retry after token refresh.
 var TokenRetryCodes = map[int]bool{
 	output.LarkErrTokenInvalid: true,
@@ -51,6 +44,7 @@ func IsNeedUserAuthorizationError(err error) bool {
 		return true
 	}
 
+	// Deprecated: legacy *output.ExitError / string-match branches; removed after typed migration.
 	var exitErr *output.ExitError
 	if errors.As(err, &exitErr) && exitErr.Detail != nil {
 		return strings.Contains(exitErr.Detail.Message, needUserAuthorizationMarker)
@@ -58,24 +52,7 @@ func IsNeedUserAuthorizationError(err error) bool {
 	return strings.Contains(err.Error(), needUserAuthorizationMarker)
 }
 
-// SecurityPolicyError is returned when a request is blocked by access control policies.
-type SecurityPolicyError struct {
-	Code         int
-	Message      string
-	ChallengeURL string
-	CLIHint      string
-	Err          error
-}
-
-// Error returns the error message for SecurityPolicyError.
-func (e *SecurityPolicyError) Error() string {
-	if e.Err != nil {
-		return fmt.Sprintf("security policy error [%d]: %s: %v", e.Code, e.Message, e.Err)
-	}
-	return fmt.Sprintf("security policy error [%d]: %s", e.Code, e.Message)
-}
-
-// Unwrap returns the underlying error.
-func (e *SecurityPolicyError) Unwrap() error {
-	return e.Err
-}
+// SecurityPolicyError is preserved as a Go type alias so existing
+// errors.As(&SecurityPolicyError{}) consumers (cmd/root.go etc.) keep working.
+// The concrete struct lives in errs/types.go.
+type SecurityPolicyError = errs.SecurityPolicyError

internal/auth/transport.go

@@ -12,6 +12,8 @@ import (
 	"net/url"
 	"strings"
 
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/errclass"
 	"github.com/larksuite/cli/internal/util"
 )
 
@@ -85,34 +87,56 @@ func (t *SecurityPolicyTransport) RoundTrip(req *http.Request) (*http.Response,
 	return resp, nil
 }
 
-// tryHandleMCPResponse attempts to parse a JSON-RPC (MCP) formatted error response.
+// tryHandleMCPResponse attempts to parse a JSON-RPC (MCP) formatted error
+// response coming back from a remote server (this transport is installed on
+// lark-cli's outbound HTTP client; the bodies it inspects are produced by the
+// remote, not by lark-cli itself).
+//
+// Observed production shape from the MCP gateway — Lark code in the outer
+// `error.code` slot, hint under `data.cli_hint`:
+//
+//	{"jsonrpc": "2.0", "id": 1,
+//	 "error": {"code": 21000, "message": "...",
+//	           "data": {"challenge_url": "...", "cli_hint": "..."}}}
+//
+// The parser also accepts a JSON-RPC-canonical shape (outer `error.code`
+// carrying the JSON-RPC status like -32603, Lark code under `error.data.code`,
+// hint under `data.hint`) so a future server-side migration to that layout
+// would not silently drop policy detection. The Lark code is looked up in the
+// central code registry; the hint key is read from `data.hint` first and
+// falls back to `data.cli_hint`.
 func (t *SecurityPolicyTransport) tryHandleMCPResponse(result map[string]interface{}) error {
-	// MCP (JSON-RPC) response format:
-	// {
-	//   "error": {
-	//     "code": 21000,
-	//     "message": "...",
-	//     "data": { "challenge_url": "...", "cli_hint": "..." }
-	//   }
-	// }
 	errMap, ok := result["error"].(map[string]interface{})
 	if !ok {
 		return nil
 	}
 
-	code := getInt(errMap, "code", 0)
-	if code != LarkErrBlockByPolicyTryAuth && code != LarkErrBlockByPolicy {
+	dataMap, _ := errMap["data"].(map[string]interface{})
+
+	// Try data.code first (shape B); fall back to outer error.code (shape A).
+	code := 0
+	if dataMap != nil {
+		code = getInt(dataMap, "code", 0)
+	}
+	if code == 0 {
+		code = getInt(errMap, "code", 0)
+	}
+	meta, ok := errclass.LookupCodeMeta(code)
+	if !ok || meta.Category != errs.CategoryPolicy {
 		return nil
 	}
 
-	dataMap, ok := errMap["data"].(map[string]interface{})
-	if !ok {
+	if dataMap == nil {
 		return nil
 	}
 
 	// Clean up backticks and spaces from challenge_url
 	challengeUrl := strings.Trim(getStr(dataMap, "challenge_url"), " `")
-	cliHint := getStr(dataMap, "cli_hint")
+	// Read `hint` first; fall back to `cli_hint` so either spelling surfaces.
+	cliHint := getStr(dataMap, "hint")
+	if cliHint == "" {
+		cliHint = getStr(dataMap, "cli_hint")
+	}
 	msg := getStr(errMap, "message")
 
 	if challengeUrl != "" || cliHint != "" {
@@ -122,11 +146,15 @@ func (t *SecurityPolicyTransport) tryHandleMCPResponse(result map[string]interfa
 		}
 
 		if challengeUrl != "" || cliHint != "" {
-			return &SecurityPolicyError{
-				Code:         code,
-				Message:      msg,
+			return &errs.SecurityPolicyError{
+				Problem: errs.Problem{
+					Category: errs.CategoryPolicy,
+					Subtype:  meta.Subtype,
+					Code:     code,
+					Message:  msg,
+					Hint:     cliHint,
+				},
 				ChallengeURL: challengeUrl,
-				CLIHint:      cliHint,
 			}
 		}
 	}
@@ -146,8 +174,9 @@ func (t *SecurityPolicyTransport) tryHandleOAPIResponse(result map[string]interf
 		}
 	}
 
-	// 2. Check if it's a security policy error
-	if code != LarkErrBlockByPolicyTryAuth && code != LarkErrBlockByPolicy {
+	// 2. Check if it's a security policy error (consult central code registry)
+	meta, ok := errclass.LookupCodeMeta(code)
+	if !ok || meta.Category != errs.CategoryPolicy {
 		return nil
 	}
 
@@ -173,11 +202,15 @@ func (t *SecurityPolicyTransport) tryHandleOAPIResponse(result map[string]interf
 		}
 
 		if msg != "" || challengeUrl != "" || cliHint != "" {
-			return &SecurityPolicyError{
-				Code:         code,
-				Message:      msg,
+			return &errs.SecurityPolicyError{
+				Problem: errs.Problem{
+					Category: errs.CategoryPolicy,
+					Subtype:  meta.Subtype,
+					Code:     code,
+					Message:  msg,
+					Hint:     cliHint,
+				},
 				ChallengeURL: challengeUrl,
-				CLIHint:      cliHint,
 			}
 		}
 	}

internal/auth/transport_test.go

@@ -0,0 +1,114 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package auth
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+)
+
+// TestTryHandleMCPResponse_RecognisesDataCode pins the parser's primary path:
+// when the outer `error.code` carries a JSON-RPC status (e.g. -32603) and the
+// Lark numeric code lives in `error.data.code`, the transport reads `data.code`
+// to look up the codeMeta and converts the response into *errs.SecurityPolicyError.
+// This shape is forward-compat for a future server-side migration to the
+// JSON-RPC-canonical layout; see also TestTryHandleMCPResponse_FallsBackToOuterCode
+// for the shape observed in production today.
+func TestTryHandleMCPResponse_RecognisesDataCode(t *testing.T) {
+	t.Parallel()
+	transport := &SecurityPolicyTransport{}
+
+	result := map[string]interface{}{
+		"jsonrpc": "2.0",
+		"id":      1,
+		"error": map[string]interface{}{
+			"code":    -32603, // JSON-RPC internal error
+			"message": "challenge required",
+			"data": map[string]interface{}{
+				"code":          21000, // Lark code for challenge_required
+				"type":          "policy",
+				"subtype":       "challenge_required",
+				"challenge_url": "https://example.com/challenge",
+				"hint":          "please complete the challenge in your browser",
+			},
+		},
+	}
+
+	got := transport.tryHandleMCPResponse(result)
+	var spErr *errs.SecurityPolicyError
+	if !errors.As(got, &spErr) {
+		t.Fatalf("expected *errs.SecurityPolicyError, got %T (err = %v)", got, got)
+	}
+	if spErr.Code != 21000 {
+		t.Errorf("Code = %d, want 21000", spErr.Code)
+	}
+	if spErr.Subtype != errs.SubtypeChallengeRequired {
+		t.Errorf("Subtype = %q, want %q", spErr.Subtype, errs.SubtypeChallengeRequired)
+	}
+	if spErr.ChallengeURL != "https://example.com/challenge" {
+		t.Errorf("ChallengeURL = %q", spErr.ChallengeURL)
+	}
+	if spErr.Hint != "please complete the challenge in your browser" {
+		t.Errorf("Hint = %q", spErr.Hint)
+	}
+}
+
+// TestTryHandleMCPResponse_FallsBackToOuterCode pins the inbound shape observed
+// in production from the MCP gateway: the Lark code sits in the outer
+// `error.code` slot (no `data.code`), and the hint surfaces as `data.cli_hint`.
+// The transport's outer-code fallback path must recognise the policy code and
+// surface the typed error with the hint promoted.
+func TestTryHandleMCPResponse_FallsBackToOuterCode(t *testing.T) {
+	t.Parallel()
+	transport := &SecurityPolicyTransport{}
+
+	result := map[string]interface{}{
+		"error": map[string]interface{}{
+			"code":    21001, // outer slot carries the Lark code
+			"message": "access denied",
+			"data": map[string]interface{}{
+				"challenge_url": "https://example.com/c",
+				"cli_hint":      "contact admin",
+			},
+		},
+	}
+
+	got := transport.tryHandleMCPResponse(result)
+	var spErr *errs.SecurityPolicyError
+	if !errors.As(got, &spErr) {
+		t.Fatalf("expected *errs.SecurityPolicyError, got %T (err = %v)", got, got)
+	}
+	if spErr.Subtype != errs.SubtypeAccessDenied {
+		t.Errorf("Subtype = %q, want %q", spErr.Subtype, errs.SubtypeAccessDenied)
+	}
+	// `cli_hint` must surface when `hint` is absent.
+	if spErr.Hint != "contact admin" {
+		t.Errorf("Hint = %q, want fallback from cli_hint", spErr.Hint)
+	}
+}
+
+// TestTryHandleMCPResponse_NonPolicyCodeIgnored verifies the transport returns
+// nil (passes through) when the Lark code does not classify as
+// CategoryPolicy — keeps regular API errors out of the security-policy path.
+func TestTryHandleMCPResponse_NonPolicyCodeIgnored(t *testing.T) {
+	t.Parallel()
+	transport := &SecurityPolicyTransport{}
+
+	result := map[string]interface{}{
+		"error": map[string]interface{}{
+			"code":    -32603,
+			"message": "permission denied",
+			"data": map[string]interface{}{
+				"code": 99991672, // app_scope_not_enabled — Authorization, not Policy
+				"type": "authorization",
+			},
+		},
+	}
+
+	if err := transport.tryHandleMCPResponse(result); err != nil {
+		t.Fatalf("expected nil (non-policy code), got %v", err)
+	}
+}

internal/auth/uat_client.go

@@ -18,7 +18,9 @@ import (
 	"time"
 
 	"github.com/gofrs/flock"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/errclass"
 	"github.com/larksuite/cli/internal/vfs"
 )
 
@@ -223,16 +225,21 @@ func doRefreshToken(httpClient *http.Client, opts UATCallOptions, stored *Stored
 	}
 
 	code := getInt(data, "code", -1)
-	if code == LarkErrBlockByPolicy || code == LarkErrBlockByPolicyTryAuth {
+	meta, metaOK := errclass.LookupCodeMeta(code)
+	if metaOK && meta.Category == errs.CategoryPolicy {
 		challengeUrl := getStr(data, "challenge_url")
 		cliHint := getStr(data, "cli_hint")
 		msg := getStr(data, "error_description")
 
-		return nil, &SecurityPolicyError{
-			Code:         code,
-			Message:      msg,
+		return nil, &errs.SecurityPolicyError{
+			Problem: errs.Problem{
+				Category: errs.CategoryPolicy,
+				Subtype:  meta.Subtype,
+				Code:     code,
+				Message:  msg,
+				Hint:     cliHint,
+			},
 			ChallengeURL: challengeUrl,
-			CLIHint:      cliHint,
 		}
 	}
 
@@ -240,7 +247,7 @@ func doRefreshToken(httpClient *http.Client, opts UATCallOptions, stored *Stored
 
 	if (code != -1 && code != 0) || errStr != "" {
 		// Retryable server error: retry once, then clear token on second failure.
-		if RefreshTokenRetryable[code] {
+		if metaOK && meta.Category == errs.CategoryAuthentication && meta.Retryable {
 			fmt.Fprintf(errOut, "[lark-cli] [WARN] uat-client: refresh transient error (code=%d) for %s, retrying once\n", code, opts.UserOpenId)
 			data, err = callEndpoint()
 			if err != nil {

internal/client/api_errors.go

@@ -11,6 +11,7 @@ import (
 	"io"
 	"strings"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/output"
 )
 
@@ -19,10 +20,31 @@ const rawAPIJSONHint = "The endpoint may have returned an empty or non-standard
 // WrapDoAPIError upgrades malformed JSON decode errors from the SDK into
 // actionable API errors for raw `lark-cli api` calls. All other failures
 // remain network errors.
+//
+// Already-classified errors pass through unchanged: any *output.ExitError
+// (legacy envelope from output.ErrAuth / output.ErrAPI / output.ErrWithHint)
+// and any typed *errs.* error (carries an embedded Problem) keeps its own
+// category and exit code. This is what makes the wrap idempotent on the
+// auth/credential chain — resolveAccessToken returns output.ErrAuth for
+// missing tokens, and that classification must survive the SDK boundary.
+//
+// Deprecated: legacy *output.ExitError wire shape (api_error + rawAPIJSONHint
+// on JSON-decode, network otherwise) for the wrap-from-untyped branch.
+// Preserved so SDK Do() callers keep the original envelope until per-domain
+// migration to typed errors. New code should route through
+// APIClient.CheckResponse (typed *errs.APIError) or construct
+// *errs.NetworkError / *errs.InternalError directly.
 func WrapDoAPIError(err error) error {
 	if err == nil {
 		return nil
 	}
+	var existing *output.ExitError
+	if errors.As(err, &existing) {
+		return err
+	}
+	if _, ok := errs.ProblemOf(err); ok {
+		return err
+	}
 	if isJSONDecodeError(err, false) {
 		return output.ErrWithHint(output.ExitAPI, "api_error",
 			fmt.Sprintf("API returned an invalid JSON response: %v", err), rawAPIJSONHint)
@@ -32,6 +54,11 @@ func WrapDoAPIError(err error) error {
 
 // WrapJSONResponseParseError upgrades empty or malformed JSON response bodies
 // into API errors with hints instead of generic parse failures.
+//
+// Deprecated: legacy *output.ExitError wire shape (api_error + ExitAPI +
+// rawAPIJSONHint). The 3-branch behaviour is preserved so existing callers
+// of internal/client/response.go keep emitting the same envelope until
+// per-domain migration to typed errors.
 func WrapJSONResponseParseError(err error, body []byte) error {
 	if err == nil {
 		return nil

internal/client/api_errors_test.go

@@ -6,31 +6,15 @@ package client
 import (
 	"encoding/json"
 	"errors"
+	"fmt"
 	"io"
 	"strings"
 	"testing"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/output"
 )
 
-func TestWrapDoAPIError_BareEOFIsNetworkError(t *testing.T) {
-	err := WrapDoAPIError(io.EOF)
-	if err == nil {
-		t.Fatal("expected error")
-	}
-
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected ExitError, got %T", err)
-	}
-	if exitErr.Code != output.ExitNetwork {
-		t.Fatalf("expected ExitNetwork, got %d", exitErr.Code)
-	}
-	if strings.Contains(exitErr.Error(), "invalid JSON response") {
-		t.Fatalf("unexpected JSON diagnostic for bare EOF: %q", exitErr.Error())
-	}
-}
-
 func TestWrapDoAPIError_SyntaxErrorIsAPIDiagnostic(t *testing.T) {
 	err := WrapDoAPIError(&json.SyntaxError{Offset: 1})
 	if err == nil {
@@ -66,3 +50,127 @@ func TestWrapJSONResponseParseError_UnexpectedEOFIsAPIDiagnostic(t *testing.T) {
 		t.Fatalf("expected invalid JSON diagnostic, got %#v", exitErr.Detail)
 	}
 }
+
+// TestWrapJSONResponseParseError_EmptyBodyIsAPIDiagnostic pins branch 1 of
+// the documented 3-branch behaviour: empty (or whitespace-only) response
+// bodies surface as api_error + rawAPIJSONHint, not network. Pages returning
+// only "\n" must not be reclassified as transport failures.
+func TestWrapJSONResponseParseError_EmptyBodyIsAPIDiagnostic(t *testing.T) {
+	for _, body := range [][]byte{nil, {}, []byte(" \t\n")} {
+		err := WrapJSONResponseParseError(io.ErrUnexpectedEOF, body)
+		var exitErr *output.ExitError
+		if !errors.As(err, &exitErr) {
+			t.Fatalf("body=%q: expected ExitError, got %T", body, err)
+		}
+		if exitErr.Code != output.ExitAPI {
+			t.Errorf("body=%q: Code = %d, want %d", body, exitErr.Code, output.ExitAPI)
+		}
+		if exitErr.Detail == nil || exitErr.Detail.Type != "api_error" {
+			t.Errorf("body=%q: Detail.Type = %v, want api_error", body, exitErr.Detail)
+		}
+		if exitErr.Detail == nil || !strings.Contains(exitErr.Detail.Message, "empty JSON response") {
+			t.Errorf("body=%q: Detail.Message = %v, want empty-body diagnostic", body, exitErr.Detail)
+		}
+	}
+}
+
+// TestWrapJSONResponseParseError_NonJSONErrorIsNetwork pins branch 3:
+// a non-JSON-decode error with a non-empty body falls back to ErrNetwork
+// (the SDK delivered something but the read itself failed mid-flight).
+func TestWrapJSONResponseParseError_NonJSONErrorIsNetwork(t *testing.T) {
+	raw := errors.New("connection reset by peer")
+	err := WrapJSONResponseParseError(raw, []byte(`{"code":0,"data":{}}`))
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected ExitError, got %T", err)
+	}
+	if exitErr.Code != output.ExitNetwork {
+		t.Errorf("Code = %d, want %d (network)", exitErr.Code, output.ExitNetwork)
+	}
+	if exitErr.Detail == nil || exitErr.Detail.Type != "network" {
+		t.Errorf("Detail.Type = %v, want network", exitErr.Detail)
+	}
+}
+
+// TestWrapDoAPIError_LegacyExitErrorPassesThrough pins the invariant that an
+// already-classified *output.ExitError (e.g. output.ErrAuth from
+// resolveAccessToken) survives WrapDoAPIError with its category and exit code
+// intact. Without this, missing-token errors regress from exit 3/auth to
+// exit 4/network at the SDK boundary.
+func TestWrapDoAPIError_LegacyExitErrorPassesThrough(t *testing.T) {
+	cases := []struct {
+		name     string
+		in       error
+		want     int
+		wantType string
+	}{
+		{"auth", output.ErrAuth("no access token available for user"), output.ExitAuth, "auth"},
+		{"validation", output.ErrValidation("missing flag --foo"), output.ExitValidation, "validation"},
+		{"api_unknown_code", output.ErrAPI(12345, "unknown lark code", nil), output.ExitAPI, "api_error"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := WrapDoAPIError(tc.in)
+			if got != tc.in {
+				t.Fatalf("expected identity passthrough, got %v (orig %v)", got, tc.in)
+			}
+			var exitErr *output.ExitError
+			if !errors.As(got, &exitErr) {
+				t.Fatalf("expected *output.ExitError, got %T", got)
+			}
+			if exitErr.Code != tc.want {
+				t.Fatalf("Code = %d, want %d", exitErr.Code, tc.want)
+			}
+			if exitErr.Detail == nil || exitErr.Detail.Type != tc.wantType {
+				t.Fatalf("Detail.Type = %q, want %q (detail=%#v)",
+					func() string {
+						if exitErr.Detail == nil {
+							return "<nil>"
+						}
+						return exitErr.Detail.Type
+					}(),
+					tc.wantType, exitErr.Detail)
+			}
+		})
+	}
+}
+
+// TestWrapDoAPIError_TypedErrsPassesThrough pins that any *errs.* typed error
+// (carries an embedded Problem) passes through unchanged. Forward-compat for
+// stage-4 credential chain migration that will return *errs.AuthenticationError
+// directly instead of legacy output.ErrAuth.
+func TestWrapDoAPIError_TypedErrsPassesThrough(t *testing.T) {
+	cases := []error{
+		&errs.AuthenticationError{Problem: errs.Problem{Category: errs.CategoryAuthentication, Subtype: errs.SubtypeTokenMissing}},
+		&errs.PermissionError{Problem: errs.Problem{Category: errs.CategoryAuthorization, Subtype: errs.SubtypeMissingScope}},
+		&errs.NetworkError{Problem: errs.Problem{Category: errs.CategoryNetwork, Subtype: errs.SubtypeNetworkTransport}},
+		&errs.InternalError{Problem: errs.Problem{Category: errs.CategoryInternal, Subtype: errs.SubtypeSDKError}},
+	}
+	for _, in := range cases {
+		t.Run(fmt.Sprintf("%T", in), func(t *testing.T) {
+			got := WrapDoAPIError(in)
+			if got != in {
+				t.Fatalf("expected identity passthrough, got %T %v", got, got)
+			}
+		})
+	}
+}
+
+// TestWrapDoAPIError_PassthroughBeforeJSONDecode pins that even if a typed/legacy
+// error wraps a JSON decode error somewhere in its chain, the outer
+// classification takes precedence — we never re-classify an already-typed error
+// as a JSON parse error.
+func TestWrapDoAPIError_PassthroughBeforeJSONDecode(t *testing.T) {
+	jsonErr := &json.SyntaxError{Offset: 1}
+	authWrappingJSON := fmt.Errorf("%w: wrapped %w", output.ErrAuth("token expired"), jsonErr)
+
+	got := WrapDoAPIError(authWrappingJSON)
+
+	var exitErr *output.ExitError
+	if !errors.As(got, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T", got)
+	}
+	if exitErr.Code != output.ExitAuth {
+		t.Fatalf("outer auth classification should win, Code = %d want %d", exitErr.Code, output.ExitAuth)
+	}
+}

internal/client/client.go

@@ -91,12 +91,28 @@ func (c *APIClient) buildApiReq(request RawApiRequest) (*larkcore.ApiReq, []lark
 // DoSDKRequest resolves auth for the given identity and executes a pre-built SDK request.
 // This is the shared auth+execute path used by both DoAPI (generic API calls via RawApiRequest)
 // and shortcut RuntimeContext.DoAPI (direct larkcore.ApiReq calls).
+//
+// SDK Do() failures are normalised through WrapDoAPIError so every caller
+// (cmd/api, RuntimeContext, shortcuts) gets the same wire shape without each
+// one remembering to wrap. In stage 1 that wire shape is still the legacy
+// *output.ExitError envelope (network / api_error) — the stage-4 framework
+// boundary migration flips WrapDoAPIError to typed *errs.NetworkError /
+// *errs.InternalError per the contract in errs/ERROR_CONTRACT.md.
+// Errors that arrive already-classified (legacy *output.ExitError from
+// resolveAccessToken's missing-credential paths, or a typed *errs.* from
+// future stages) flow through unchanged.
 func (c *APIClient) DoSDKRequest(ctx context.Context, req *larkcore.ApiReq, as core.Identity, extraOpts ...larkcore.RequestOptionFunc) (*larkcore.ApiResp, error) {
 	var opts []larkcore.RequestOptionFunc
 
 	token, err := c.resolveAccessToken(ctx, as)
 	if err != nil {
-		return nil, err
+		// WrapDoAPIError is idempotent on already-classified errors:
+		// the *output.ExitError that resolveAccessToken returns for missing
+		// tokens (via output.ErrAuth) passes through with its auth category
+		// and exit 3 intact, and any future typed *errs.* error from the
+		// credential chain survives the same way. Only stray untyped errors
+		// (raw fmt.Errorf) get the transport-or-internal fallback.
+		return nil, WrapDoAPIError(err)
 	}
 	if as.IsBot() {
 		req.SupportedAccessTokenTypes = []larkcore.AccessTokenType{larkcore.AccessTokenTypeTenant}
@@ -107,7 +123,11 @@ func (c *APIClient) DoSDKRequest(ctx context.Context, req *larkcore.ApiReq, as c
 	}
 
 	opts = append(opts, extraOpts...)
-	return c.SDK.Do(ctx, req, opts...)
+	resp, err := c.SDK.Do(ctx, req, opts...)
+	if err != nil {
+		return nil, WrapDoAPIError(err)
+	}
+	return resp, nil
 }
 
 // DoStream executes a streaming HTTP request against the Lark OpenAPI endpoint.
@@ -123,7 +143,10 @@ func (c *APIClient) DoStream(ctx context.Context, req *larkcore.ApiReq, as core.
 	// Resolve auth
 	token, err := c.resolveAccessToken(ctx, as)
 	if err != nil {
-		return nil, err
+		// See DoSDKRequest comment on the same wrap pattern; the typed
+		// auth-error pass-through plus untyped fallback applies equally to
+		// streaming requests.
+		return nil, WrapDoAPIError(err)
 	}
 
 	// Build URL
@@ -182,14 +205,32 @@ func (c *APIClient) DoStream(ctx context.Context, req *larkcore.ApiReq, as core.
 		errBody, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
 		msg := strings.TrimSpace(string(errBody))
 		if msg != "" {
-			return nil, output.ErrNetwork("HTTP %d: %s", resp.StatusCode, msg)
+			err := output.ErrNetwork("HTTP %d: %s", resp.StatusCode, msg)
+			attachStreamLogID(err, resp.Header)
+			return nil, err
 		}
-		return nil, output.ErrNetwork("HTTP %d", resp.StatusCode)
+		err := output.ErrNetwork("HTTP %d", resp.StatusCode)
+		attachStreamLogID(err, resp.Header)
+		return nil, err
 	}
 
 	return resp, nil
 }
 
+func attachStreamLogID(err *output.ExitError, header http.Header) {
+	if err == nil || err.Detail == nil {
+		return
+	}
+	logID := strings.TrimSpace(header.Get(larkcore.HttpHeaderKeyLogId))
+	if logID == "" {
+		logID = strings.TrimSpace(header.Get(larkcore.HttpHeaderKeyRequestId))
+	}
+	if logID == "" {
+		return
+	}
+	err.Detail.Detail = map[string]any{"log_id": logID}
+}
+
 type cancelOnCloseBody struct {
 	io.ReadCloser
 	cancel context.CancelFunc
@@ -259,14 +300,27 @@ func (c *APIClient) DoAPI(ctx context.Context, request RawApiRequest) (*larkcore
 	return c.DoSDKRequest(ctx, apiReq, request.As, extraOpts...)
 }
 
-// CallAPI is a convenience wrapper: DoAPI + ParseJSONResponse.
-// Use DoAPI directly when the response may not be JSON (e.g. file downloads).
+// CallAPI is a convenience wrapper: DoAPI + ParseJSONResponse. Use DoAPI
+// directly when the response may not be JSON (e.g. file downloads).
+//
+// JSON parse failures are wrapped via WrapJSONResponseParseError so callers
+// (notably the pagination loop and --page-all paths in cmd/api / cmd/service)
+// see an *output.ExitError envelope (api_error for malformed JSON, network
+// for everything else) instead of a bare fmt.Errorf. Without this, an empty
+// or malformed page body would surface to the root handler as a plain-text
+// "Error: ..." line, bypassing the JSON stderr envelope contract. Stage-4
+// framework-boundary migration will flip this wrapper to typed
+// *errs.InternalError / *errs.NetworkError.
 func (c *APIClient) CallAPI(ctx context.Context, request RawApiRequest) (interface{}, error) {
 	resp, err := c.DoAPI(ctx, request)
 	if err != nil {
 		return nil, err
 	}
-	return ParseJSONResponse(resp)
+	result, parseErr := ParseJSONResponse(resp)
+	if parseErr != nil {
+		return nil, WrapJSONResponseParseError(parseErr, resp.RawBody)
+	}
+	return result, nil
 }
 
 // paginateLoop runs the core pagination loop. For each successful page (code == 0),
@@ -410,10 +464,14 @@ func (c *APIClient) StreamPages(ctx context.Context, request RawApiRequest, onIt
 	return map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{}}, false, nil
 }
 
-// CheckLarkResponse inspects a Lark API response for business-level errors (non-zero code).
-// Uses type assertion instead of interface{} == nil to satisfy interface_nil_check lint.
-// Returns nil if result is not a map, map is nil, or code is 0.
-func CheckLarkResponse(result interface{}) error {
+// CheckResponse inspects a Lark API response for business-level errors (non-zero code).
+//
+// Deprecated: legacy *output.ExitError wire shape via output.ErrAPI /
+// ClassifyLarkError (type "api_error" / "permission" / etc). Preserved so
+// existing callers keep emitting the same envelope until per-domain
+// migration to typed errors. The identity parameter is reserved for the
+// stage-2 typed path; stage-1 ignores it.
+func (c *APIClient) CheckResponse(result interface{}, identity core.Identity) error {
 	resultMap, ok := result.(map[string]interface{})
 	if !ok || resultMap == nil {
 		return nil

internal/client/client_test.go

@@ -45,12 +45,6 @@ func (s *staticTokenResolver) ResolveToken(_ context.Context, _ credential.Token
 	return &credential.TokenResult{Token: "test-token"}, nil
 }
 
-type missingTokenResolver struct{}
-
-func (s *missingTokenResolver) ResolveToken(_ context.Context, req credential.TokenSpec) (*credential.TokenResult, error) {
-	return nil, &credential.TokenUnavailableError{Source: "default", Type: req.Type}
-}
-
 // newTestAPIClient creates an APIClient with a mock HTTP transport.
 func newTestAPIClient(t *testing.T, rt http.RoundTripper) (*APIClient, *bytes.Buffer) {
 	t.Helper()
@@ -434,42 +428,118 @@ func TestDoStream_IgnoresBaseHTTPClientTimeout(t *testing.T) {
 	}
 }
 
-func TestDoSDKRequest_MissingTokenReturnsAuthError(t *testing.T) {
-	ac, _ := newTestAPIClient(t, roundTripFunc(func(req *http.Request) (*http.Response, error) {
-		t.Fatal("unexpected HTTP request")
-		return nil, nil
-	}))
-	ac.Credential = credential.NewCredentialProvider(nil, nil, &missingTokenResolver{}, nil)
+// failingTokenResolver always returns TokenUnavailableError, exercising the
+// auth/credential failure path through resolveAccessToken.
+type failingTokenResolver struct{}
 
-	_, err := ac.DoSDKRequest(context.Background(), &larkcore.ApiReq{
-		HttpMethod: http.MethodGet,
-		ApiPath:    "/open-apis/test",
-	}, core.AsBot)
-	if err == nil {
-		t.Fatal("DoSDKRequest() error = nil, want auth error")
-	}
-	var exitErr *output.ExitError
-	if !strings.Contains(err.Error(), "no access token available") || !errors.As(err, &exitErr) || exitErr.Detail == nil || exitErr.Detail.Type != "auth" {
-		t.Fatalf("DoSDKRequest() error = %v, want auth error", err)
-	}
+func (f *failingTokenResolver) ResolveToken(_ context.Context, spec credential.TokenSpec) (*credential.TokenResult, error) {
+	return nil, &credential.TokenUnavailableError{Source: "test", Type: spec.Type}
 }
 
-func TestDoStream_MissingTokenReturnsAuthError(t *testing.T) {
+// TestDoSDKRequest_AuthFailurePreservesAuthCategory pins the end-to-end
+// invariant codex caught the day this PR landed: when resolveAccessToken
+// produces output.ErrAuth ("no access token available for <identity>"),
+// DoSDKRequest must surface it with the original auth classification —
+// not silently downgrade it to a network error via the SDK-failure wrap.
+//
+// Regression scenario: shortcut path
+// (shortcuts/common/runner.go DoAPI → DoSDKRequest) calling against a user
+// identity with no cached token. Pre-fix this surfaced as exit 4/type=network
+// and routed agents into "check your connection" instead of "log in".
+func TestDoSDKRequest_AuthFailurePreservesAuthCategory(t *testing.T) {
 	ac := &APIClient{
 		HTTP:       &http.Client{},
-		Credential: credential.NewCredentialProvider(nil, nil, &missingTokenResolver{}, nil),
+		Credential: credential.NewCredentialProvider(nil, nil, &failingTokenResolver{}, nil),
 		Config:     &core.CliConfig{AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu},
 	}
 
-	_, err := ac.DoStream(context.Background(), &larkcore.ApiReq{
+	_, err := ac.DoSDKRequest(context.Background(), &larkcore.ApiReq{
 		HttpMethod: http.MethodGet,
-		ApiPath:    "https://example.com/open-apis/test",
-	}, core.AsBot)
+		ApiPath:    "/open-apis/contact/v3/users/me",
+	}, core.AsUser)
+
 	if err == nil {
-		t.Fatal("DoStream() error = nil, want auth error")
+		t.Fatal("expected auth error, got nil")
 	}
 	var exitErr *output.ExitError
-	if !strings.Contains(err.Error(), "no access token available") || !errors.As(err, &exitErr) || exitErr.Detail == nil || exitErr.Detail.Type != "auth" {
-		t.Fatalf("DoStream() error = %v, want auth error", err)
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T", err)
+	}
+	if exitErr.Code != output.ExitAuth {
+		t.Fatalf("Code = %d, want %d (auth) — confirms ErrAuth was downgraded to network at SDK wrap", exitErr.Code, output.ExitAuth)
+	}
+	if exitErr.Detail == nil || exitErr.Detail.Type != "auth" {
+		t.Fatalf("Detail.Type = %v, want auth", exitErr.Detail)
+	}
+}
+
+// TestDoSDKRequest_TransportFailureWrapsAsNetwork pins that genuinely untyped
+// SDK transport errors get the network classification via WrapDoAPIError.
+// io.ErrUnexpectedEOF from a RoundTripper surfaces through net/http as a
+// *url.Error, which the wrap classifier recognises as a transport error.
+func TestDoSDKRequest_TransportFailureWrapsAsNetwork(t *testing.T) {
+	rt := roundTripFunc(func(_ *http.Request) (*http.Response, error) {
+		return nil, io.ErrUnexpectedEOF
+	})
+	ac, _ := newTestAPIClient(t, rt)
+
+	_, err := ac.DoSDKRequest(context.Background(), &larkcore.ApiReq{
+		HttpMethod: http.MethodGet,
+		ApiPath:    "/open-apis/contact/v3/users/me",
+	}, core.AsBot)
+
+	if err == nil {
+		t.Fatal("expected error from broken transport, got nil")
+	}
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T", err)
+	}
+	if exitErr.Code != output.ExitNetwork {
+		t.Fatalf("Code = %d, want %d (network)", exitErr.Code, output.ExitNetwork)
+	}
+	if exitErr.Detail == nil || exitErr.Detail.Type != "network" {
+		t.Fatalf("Detail.Type = %v, want network", exitErr.Detail)
+	}
+}
+
+// TestCallAPI_ParseJSONFailureWrapsAsAPI pins the legacy-envelope contract for
+// malformed JSON response bodies: WrapJSONResponseParseError emits api_error
+// (exit 1) with the rawAPIJSONHint, so the pagination / cmd/api / cmd/service
+// callers always see a JSON stderr envelope instead of a bare "Error: ..."
+// line. Stage-4 framework-boundary migration will flip this wrapper to typed
+// *errs.InternalError; until then this test pins the legacy shape so we do
+// not regress envelope coverage.
+func TestCallAPI_ParseJSONFailureWrapsAsAPI(t *testing.T) {
+	rt := roundTripFunc(func(_ *http.Request) (*http.Response, error) {
+		return &http.Response{
+			StatusCode: 200,
+			Header:     http.Header{"Content-Type": []string{"application/json"}},
+			Body:       io.NopCloser(strings.NewReader(`{ malformed`)),
+		}, nil
+	})
+	ac, _ := newTestAPIClient(t, rt)
+
+	_, err := ac.CallAPI(context.Background(), RawApiRequest{
+		Method: "GET",
+		URL:    "/open-apis/contact/v3/users/me",
+		As:     "bot",
+	})
+
+	if err == nil {
+		t.Fatal("expected JSON parse error, got nil")
+	}
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T", err)
+	}
+	if exitErr.Code != output.ExitAPI {
+		t.Fatalf("Code = %d, want %d (api)", exitErr.Code, output.ExitAPI)
+	}
+	if exitErr.Detail == nil || exitErr.Detail.Type != "api_error" {
+		t.Fatalf("Detail.Type = %v, want api_error", exitErr.Detail)
+	}
+	if exitErr.Detail.Hint != rawAPIJSONHint {
+		t.Errorf("Detail.Hint = %q, want rawAPIJSONHint", exitErr.Detail.Hint)
 	}
 }

internal/client/dostream_test.go

@@ -0,0 +1,52 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package client_test
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"testing"
+
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
+)
+
+func TestDoStream_HTTPErrorIncludesLogID(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	config := &core.CliConfig{AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu}
+	factory, _, _, reg := cmdutil.TestFactory(t, config)
+	reg.Register(&httpmock.Stub{
+		Method:  http.MethodGet,
+		URL:     "/open-apis/drive/v1/medias/file_token/download",
+		Status:  http.StatusForbidden,
+		RawBody: []byte("forbidden"),
+		Headers: http.Header{
+			larkcore.HttpHeaderKeyLogId: []string{"202605270003"},
+		},
+	})
+
+	client, err := factory.NewAPIClientWithConfig(config)
+	if err != nil {
+		t.Fatalf("NewAPIClientWithConfig() error = %v", err)
+	}
+
+	_, err = client.DoStream(context.Background(), &larkcore.ApiReq{
+		HttpMethod: http.MethodGet,
+		ApiPath:    "/open-apis/drive/v1/medias/file_token/download",
+	}, core.AsBot)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		t.Fatalf("expected structured error, got %T %v", err, err)
+	}
+	detail, _ := exitErr.Detail.Detail.(map[string]any)
+	if detail["log_id"] != "202605270003" {
+		t.Fatalf("detail=%#v, want log_id", exitErr.Detail.Detail)
+	}
+}

internal/client/pagination.go

@@ -8,25 +8,38 @@ import (
 	"fmt"
 	"io"
 
+	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
 )
 
 // PaginationOptions contains pagination control options.
 type PaginationOptions struct {
-	PageLimit int // max pages to fetch; 0 = unlimited (default: 10)
-	PageDelay int // ms, default 200
+	PageLimit int           // max pages to fetch; 0 = unlimited (default: 10)
+	PageDelay int           // ms, default 200
+	Identity  core.Identity // identity passed to checkErr; defaults to AsUser when empty
 }
 
 // PaginateWithJq aggregates all pages, checks for API errors, then applies a jq filter.
 // If checkErr detects an error, the raw result is printed as JSON before returning the error.
 func PaginateWithJq(ctx context.Context, ac *APIClient, request RawApiRequest,
 	jqExpr string, out io.Writer, pagOpts PaginationOptions,
-	checkErr func(interface{}) error) error {
+	checkErr func(interface{}, core.Identity) error) error {
 	result, err := ac.PaginateAll(ctx, request, pagOpts)
 	if err != nil {
-		return output.ErrNetwork("API call failed: %v", err)
+		return err
 	}
-	if apiErr := checkErr(result); apiErr != nil {
+	// Identity resolution honors pagOpts.Identity first, then the request's
+	// own identity, and only falls back to AsUser when neither caller
+	// supplied one. Without checking request.As, bot/auto requests would
+	// always be classified as user identity for checkErr.
+	identity := pagOpts.Identity
+	if identity == "" {
+		identity = request.As
+	}
+	if identity == "" || identity == core.AsAuto {
+		identity = core.AsUser
+	}
+	if apiErr := checkErr(result, identity); apiErr != nil {
 		output.FormatValue(out, result, output.FormatJSON)
 		return apiErr
 	}

internal/client/response.go

@@ -15,6 +15,7 @@ import (
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 
 	"github.com/larksuite/cli/extension/fileio"
+	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/util"
 )
@@ -30,8 +31,13 @@ type ResponseOptions struct {
 	ErrOut      io.Writer     // stderr
 	FileIO      fileio.FileIO // file transfer abstraction; required when saving files (--output or binary response)
 	CommandPath string        // raw cobra CommandPath() for content safety scanning
-	// CheckError is called on parsed JSON results. Nil defaults to CheckLarkResponse.
-	CheckError func(interface{}) error
+	// Identity is forwarded to CheckError (default or caller-supplied) so the
+	// classifier can populate identity-aware fields (e.g. PermissionError.Identity).
+	// Defaults to core.AsUser when empty.
+	Identity core.Identity
+	// CheckError is called on parsed JSON results. Nil defaults to (*APIClient).CheckResponse
+	// with the Identity field (or AsUser when unset).
+	CheckError func(result interface{}, identity core.Identity) error
 }
 
 // HandleResponse routes a raw *larkcore.ApiResp to the appropriate output:
@@ -40,9 +46,21 @@ type ResponseOptions struct {
 //  3. If Content-Type is non-JSON and no --output, auto-save binary to file.
 func HandleResponse(resp *larkcore.ApiResp, opts ResponseOptions) error {
 	ct := resp.Header.Get("Content-Type")
+	identity := opts.Identity
+	if identity == "" {
+		identity = core.AsUser
+	}
 	check := opts.CheckError
 	if check == nil {
-		check = CheckLarkResponse
+		// Stage 1: default check routes through legacy CheckResponse
+		// (output.ErrAPI / ClassifyLarkError). Stage-2+ migration will
+		// switch this to errclass.BuildAPIError so PermissionError carries
+		// MissingScopes / ConsoleURL — at that point a zero-value
+		// *APIClient still works because BuildAPIError short-circuits on
+		// empty AppID, gracefully degrading identity-aware fields.
+		check = func(r interface{}, id core.Identity) error {
+			return (&APIClient{}).CheckResponse(r, id)
+		}
 	}
 
 	// Non-JSON error responses (e.g. 404 text/plain from gateway): return error directly
@@ -58,7 +76,7 @@ func HandleResponse(resp *larkcore.ApiResp, opts ResponseOptions) error {
 		if err != nil {
 			return WrapJSONResponseParseError(err, resp.RawBody)
 		}
-		if apiErr := check(result); apiErr != nil {
+		if apiErr := check(result, identity); apiErr != nil {
 			return apiErr
 		}
 		// Content safety scanning

internal/client/response_test.go

@@ -234,37 +234,6 @@ func TestHandleResponse_JSONWithError(t *testing.T) {
 	}
 }
 
-func TestHandleResponse_EmptyJSONBody_ShowsDiagnostic(t *testing.T) {
-	resp := newApiResp([]byte{}, map[string]string{"Content-Type": "application/json"})
-
-	var out bytes.Buffer
-	var errOut bytes.Buffer
-	err := HandleResponse(resp, ResponseOptions{
-		Out:    &out,
-		ErrOut: &errOut,
-	})
-	if err == nil {
-		t.Fatal("expected error for empty JSON body")
-	}
-
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected ExitError, got %T", err)
-	}
-	if exitErr.Code != output.ExitAPI {
-		t.Fatalf("expected ExitAPI, got %d", exitErr.Code)
-	}
-	if exitErr.Detail == nil {
-		t.Fatal("expected detail on exit error")
-	}
-	if exitErr.Detail.Message != "API returned an empty JSON response body" {
-		t.Fatalf("unexpected message: %q", exitErr.Detail.Message)
-	}
-	if !strings.Contains(exitErr.Detail.Hint, "--output") {
-		t.Fatalf("expected hint to mention --output, got %q", exitErr.Detail.Hint)
-	}
-}
-
 func TestHandleResponse_BinaryAutoSave(t *testing.T) {
 	dir := t.TempDir()
 	origWd, _ := os.Getwd()
@@ -424,17 +393,3 @@ func TestSaveResponse_MetadataContainsAbsolutePath(t *testing.T) {
 		t.Errorf("saved_path should be absolute, got %q", savedPath)
 	}
 }
-
-func TestHandleResponse_403JSON_CheckLarkResponse(t *testing.T) {
-	body := []byte(`{"code":99991400,"msg":"invalid token"}`)
-	resp := newApiRespWithStatus(403, body, map[string]string{"Content-Type": "application/json"})
-
-	var out, errOut bytes.Buffer
-	err := HandleResponse(resp, ResponseOptions{Out: &out, ErrOut: &errOut, FileIO: &localfileio.LocalFileIO{}})
-	if err == nil {
-		t.Fatal("expected error for 403 JSON with non-zero code")
-	}
-	if !strings.Contains(err.Error(), "99991400") {
-		t.Errorf("expected lark error code in message, got: %s", err.Error())
-	}
-}

internal/cmdpolicy/apply.go

@@ -130,6 +130,13 @@ func DenialDetailMap(cd *platform.CommandDeniedError) map[string]any {
 // Message comes from CommandDeniedError.Error(), no Hint. Callers that
 // need a custom Message or an independent Hint (strict-mode) should
 // compose CommandDeniedFromDenial + DenialDetailMap themselves.
+//
+// Deprecated: BuildDenialError produces a legacy *output.ExitError that
+// predates the typed error contract introduced by errs/. New code MUST NOT
+// use it — denial signals should move to a typed *errs.XxxError (a dedicated
+// typed Error for policy denial is tracked for the cmdpolicy migration PR).
+// This helper is retained only while existing call sites are migrated; it
+// will be removed once they have moved to the typed surface.
 func BuildDenialError(path string, d Denial) *output.ExitError {
 	cd := CommandDeniedFromDenial(path, d)
 	return &output.ExitError{

internal/cmdutil/confirm.go

@@ -19,6 +19,13 @@ import (
 // command: agents already know their original invocation and only need to
 // append --yes per the hint, which keeps the protocol free of shell-quoting
 // pitfalls.
+// Deprecated: RequireConfirmation produces a legacy *output.ExitError that
+// predates the typed error contract introduced by errs/. New code MUST NOT
+// use it — confirmation-required signals should move to typed
+// *errs.ConfirmationRequiredError carrying the same agent-protocol metadata
+// (level/action) as typed extension fields. This helper is retained only
+// while existing call sites are migrated; it will be removed once they have
+// moved to the typed surface.
 func RequireConfirmation(action string) error {
 	return &output.ExitError{
 		Code: output.ExitConfirmationRequired,
@@ -27,7 +34,7 @@ func RequireConfirmation(action string) error {
 			Message: fmt.Sprintf("%s requires confirmation", action),
 			Hint:    "add --yes to confirm",
 			Risk: &output.RiskDetail{
-				Level:  "high-risk-write",
+				Level:  RiskHighRiskWrite,
 				Action: action,
 			},
 		},

internal/cmdutil/lang.go

@@ -0,0 +1,27 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmdutil
+
+import (
+	"strings"
+
+	"github.com/larksuite/cli/internal/i18n"
+	"github.com/larksuite/cli/internal/output"
+)
+
+// ParseLangFlag validates and canonicalizes a --lang value, shared by config
+// and profile so every entry point honors one contract. Empty is unset (no-op);
+// a non-empty value must resolve via i18n.Parse or it errors.
+func ParseLangFlag(raw string) (i18n.Lang, error) {
+	if raw == "" {
+		return "", nil
+	}
+	lang, ok := i18n.Parse(raw)
+	if !ok {
+		return "", output.ErrValidation(
+			"invalid --lang %q; valid values: %s",
+			raw, strings.Join(i18n.Codes(), ", "))
+	}
+	return lang, nil
+}

internal/cmdutil/risk.go

@@ -7,11 +7,20 @@ import "github.com/spf13/cobra"
 
 const riskLevelAnnotationKey = "risk_level"
 
+// Risk level constants — the three-tier convention used across the CLI.
+// Use these in place of string literals so the typo radius is one place,
+// not every call site.
+const (
+	RiskRead          = "read"
+	RiskWrite         = "write"
+	RiskHighRiskWrite = "high-risk-write"
+)
+
 // SetRisk stores a command's static risk level on cobra annotations so the
 // help renderer (cmd/root.go) can surface a Risk: line without importing
-// shortcuts/common. Levels follow the three-tier convention: "read" | "write"
-// | "high-risk-write". Framework-level confirmation gating only acts on
-// "high-risk-write".
+// shortcuts/common. Levels follow the three-tier convention: RiskRead |
+// RiskWrite | RiskHighRiskWrite. Framework-level confirmation gating only
+// acts on RiskHighRiskWrite.
 func SetRisk(cmd *cobra.Command, level string) {
 	if level == "" {
 		return

internal/core/config.go

@@ -11,6 +11,7 @@ import (
 	"strings"
 	"unicode/utf8"
 
+	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
@@ -41,7 +42,7 @@ type AppConfig struct {
 	AppId      string      `json:"appId"`
 	AppSecret  SecretInput `json:"appSecret"`
 	Brand      LarkBrand   `json:"brand"`
-	Lang       string      `json:"lang,omitempty"`
+	Lang       i18n.Lang   `json:"lang,omitempty"`
 	DefaultAs  Identity    `json:"defaultAs,omitempty"` // AsUser | AsBot | AsAuto
 	StrictMode *StrictMode `json:"strictMode,omitempty"`
 	Users      []AppUser   `json:"users"`
@@ -159,6 +160,7 @@ type CliConfig struct {
 	DefaultAs           Identity // AsUser | AsBot | AsAuto | "" (from config file)
 	UserOpenId          string
 	UserName            string
+	Lang                i18n.Lang
 	SupportedIdentities uint8 `json:"-"` // bitflag: 1=user, 2=bot; set by credential provider
 }
 
@@ -236,7 +238,7 @@ func ResolveConfigFromMulti(raw *MultiAppConfig, kc keychain.KeychainAccess, pro
 	app := raw.CurrentAppConfig(profileOverride)
 	if app == nil {
 		return nil, &ConfigError{
-			Code:    2,
+			Code:    3,
 			Type:    "config",
 			Message: fmt.Sprintf("profile %q not found", profileOverride),
 			Hint:    fmt.Sprintf("available profiles: %s", formatProfileNames(raw.ProfileNames())),
@@ -244,20 +246,19 @@ func ResolveConfigFromMulti(raw *MultiAppConfig, kc keychain.KeychainAccess, pro
 	}
 
 	if err := ValidateSecretKeyMatch(app.AppId, app.AppSecret); err != nil {
-		return nil, &ConfigError{Code: 2, Type: "config",
+		return nil, &ConfigError{Code: 3, Type: "config",
 			Message: "appId and appSecret keychain key are out of sync",
 			Hint:    err.Error()}
 	}
 
 	secret, err := ResolveSecretInput(app.AppSecret, kc)
 	if err != nil {
-		// If the error comes from the keychain, it will already be wrapped as an ExitError.
-		// For other errors (e.g. file read errors, unknown sources), wrap them as ConfigError.
+		// Deprecated: legacy *output.ExitError passthrough; removed after typed migration.
 		var exitErr *output.ExitError
 		if errors.As(err, &exitErr) {
 			return nil, exitErr
 		}
-		return nil, &ConfigError{Code: 2, Type: "config", Message: err.Error()}
+		return nil, &ConfigError{Code: 3, Type: "config", Message: err.Error()}
 	}
 	cfg := &CliConfig{
 		ProfileName: app.ProfileName(),
@@ -265,6 +266,7 @@ func ResolveConfigFromMulti(raw *MultiAppConfig, kc keychain.KeychainAccess, pro
 		AppSecret:   secret,
 		Brand:       app.Brand,
 		DefaultAs:   app.DefaultAs,
+		Lang:        app.Lang,
 	}
 	if len(app.Users) > 0 {
 		cfg.UserOpenId = app.Users[0].UserOpenId

internal/core/errors.go

@@ -8,7 +8,7 @@ import "fmt"
 // ConfigError is a structured error from config resolution.
 // It carries enough information for main.go to convert it into an output.ExitError.
 type ConfigError struct {
-	Code    int    // exit code: 2=validation, 3=auth
+	Code    int    // exit code: 3 (config errors share the auth exit code)
 	Type    string // "config" or "auth"
 	Message string
 	Hint    string

internal/core/notconfigured.go

@@ -31,7 +31,7 @@ func LoadOrNotConfigured() (*MultiAppConfig, error) {
 		// keeps it on the standard structured-envelope path at the root
 		// command's error sink.
 		return nil, &ConfigError{
-			Code:    2,
+			Code:    3,
 			Type:    "config",
 			Message: fmt.Sprintf("failed to load config: %v", err),
 		}
@@ -71,14 +71,14 @@ func NotConfiguredError() error {
 	ws := CurrentWorkspace()
 	if ws.IsLocal() {
 		return &ConfigError{
-			Code:    2,
+			Code:    3,
 			Type:    "config",
 			Message: "not configured",
 			Hint:    localInitHint,
 		}
 	}
 	return &ConfigError{
-		Code:    2,
+		Code:    3,
 		Type:    ws.Display(),
 		Message: fmt.Sprintf("%s context detected but lark-cli is not bound to it", ws.Display()),
 		Hint:    agentBindHint,
@@ -105,14 +105,14 @@ func NoActiveProfileError() error {
 	ws := CurrentWorkspace()
 	if ws.IsLocal() {
 		return &ConfigError{
-			Code:    2,
+			Code:    3,
 			Type:    "config",
 			Message: "no active profile",
 			Hint:    localInitHint,
 		}
 	}
 	return &ConfigError{
-		Code:    2,
+		Code:    3,
 		Type:    ws.Display(),
 		Message: fmt.Sprintf("no active profile in %s workspace", ws.Display()),
 		Hint:    agentBindHint,

internal/credential/integration_test.go

@@ -12,6 +12,7 @@ import (
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/credential"
 	"github.com/larksuite/cli/internal/envvars"
+	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/keychain"
 )
 
@@ -115,3 +116,45 @@ func TestFullChain_ConfigStrictMode(t *testing.T) {
 		t.Errorf("expected SupportsBot (%d), got %d", extcred.SupportsBot, acct.SupportedIdentities)
 	}
 }
+
+// TestFullChain_LangSurvivesProductionPath exercises the exact data flow the
+// production Factory uses (factory_default.go Phase 3): disk → multi config →
+// DefaultAccountProvider.ResolveAccount → Account → ToCliConfig. If Lang gets
+// dropped at the credential boundary (as it would when Account lacks the field),
+// shortcuts/common/runner.go RuntimeContext.Lang() returns "" and downstream
+// consumers (mail signature, etc.) silently fall back to defaults — defeating
+// the whole point of persisting --lang.
+func TestFullChain_LangSurvivesProductionPath(t *testing.T) {
+	t.Setenv(envvars.CliAppID, "")
+	t.Setenv(envvars.CliAppSecret, "")
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	multi := &core.MultiAppConfig{
+		Apps: []core.AppConfig{{
+			AppId:     "cfg_app",
+			AppSecret: core.PlainSecret("cfg_secret"),
+			Brand:     core.BrandFeishu,
+			Lang:      i18n.LangJaJP,
+		}},
+	}
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		t.Fatalf("SaveMultiAppConfig: %v", err)
+	}
+
+	defaultAcct := credential.NewDefaultAccountProvider(func() keychain.KeychainAccess { return &noopKC{} }, "")
+	acct, err := defaultAcct.ResolveAccount(context.Background())
+	if err != nil {
+		t.Fatalf("ResolveAccount: %v", err)
+	}
+	if acct.Lang != i18n.LangJaJP {
+		t.Errorf("Account.Lang = %q, want %q (DefaultAccountProvider must propagate Lang from config)", acct.Lang, i18n.LangJaJP)
+	}
+
+	cfg := acct.ToCliConfig()
+	if cfg == nil {
+		t.Fatal("ToCliConfig() = nil")
+	}
+	if cfg.Lang != i18n.LangJaJP {
+		t.Errorf("CliConfig.Lang = %q, want %q (this is the value RuntimeContext.Lang() reads in production)", cfg.Lang, i18n.LangJaJP)
+	}
+}

internal/credential/types.go

@@ -10,6 +10,7 @@ import (
 
 	extcred "github.com/larksuite/cli/extension/credential"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/i18n"
 )
 
 // Account is the credential-layer view of the active runtime account.
@@ -23,6 +24,7 @@ type Account struct {
 	DefaultAs           core.Identity
 	UserOpenId          string
 	UserName            string
+	Lang                i18n.Lang
 	SupportedIdentities uint8
 }
 
@@ -65,6 +67,7 @@ func AccountFromCliConfig(cfg *core.CliConfig) *Account {
 		DefaultAs:           cfg.DefaultAs,
 		UserOpenId:          cfg.UserOpenId,
 		UserName:            cfg.UserName,
+		Lang:                cfg.Lang,
 		SupportedIdentities: cfg.SupportedIdentities,
 	}
 }
@@ -82,6 +85,7 @@ func (a *Account) ToCliConfig() *core.CliConfig {
 		DefaultAs:           a.DefaultAs,
 		UserOpenId:          a.UserOpenId,
 		UserName:            a.UserName,
+		Lang:                a.Lang,
 		SupportedIdentities: a.SupportedIdentities,
 	}
 }

internal/credential/types_test.go

@@ -7,6 +7,7 @@ import (
 	"testing"
 
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/i18n"
 )
 
 func TestTokenTypeString(t *testing.T) {
@@ -53,6 +54,7 @@ func TestAccountFromCliConfigAndBack_ReturnCopies(t *testing.T) {
 		DefaultAs:           "user",
 		UserOpenId:          "ou_123",
 		UserName:            "alice",
+		Lang:                i18n.LangJaJP,
 		SupportedIdentities: 3,
 	}
 
@@ -63,6 +65,9 @@ func TestAccountFromCliConfigAndBack_ReturnCopies(t *testing.T) {
 	if acct.AppID != cfg.AppID || acct.ProfileName != cfg.ProfileName || acct.UserName != cfg.UserName {
 		t.Fatalf("AccountFromCliConfig() = %#v, want copied fields from %#v", acct, cfg)
 	}
+	if acct.Lang != cfg.Lang {
+		t.Fatalf("AccountFromCliConfig().Lang = %q, want %q", acct.Lang, cfg.Lang)
+	}
 
 	roundtrip := acct.ToCliConfig()
 	if roundtrip == nil {
@@ -71,6 +76,9 @@ func TestAccountFromCliConfigAndBack_ReturnCopies(t *testing.T) {
 	if roundtrip.AppID != cfg.AppID || roundtrip.ProfileName != cfg.ProfileName || roundtrip.UserName != cfg.UserName {
 		t.Fatalf("ToCliConfig() = %#v, want copied fields from %#v", roundtrip, cfg)
 	}
+	if roundtrip.Lang != cfg.Lang {
+		t.Fatalf("ToCliConfig().Lang = %q, want %q (production Factory path reads Lang via this conversion)", roundtrip.Lang, cfg.Lang)
+	}
 
 	roundtrip.AppID = "mutated-cli"
 	acct.AppID = "mutated-account"

internal/errclass/classify.go

@@ -0,0 +1,284 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errclass
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/url"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+)
+
+// ClassifyContext is the contextual data BuildAPIError uses to populate
+// identity-aware fields on typed errors (PermissionError.Identity / ConsoleURL).
+// Identity is a plain string ("user" / "bot" / "") so this package does not
+// depend on internal/core (which would create an import cycle).
+type ClassifyContext struct {
+	Brand    string // "feishu" | "lark" — drives console_url host
+	AppID    string // placed in console_url
+	Identity string // "user" / "bot" / "" — caller converts core.Identity at the boundary
+}
+
+// BuildAPIError consumes a parsed Lark API response and returns a typed error.
+// Returns nil when resp is nil or resp["code"] is 0.
+//
+// Routing by Category:
+//
+//	Authorization → *errs.PermissionError (with MissingScopes / Identity / ConsoleURL)
+//	Authentication → *errs.AuthenticationError
+//	Config → *errs.ConfigError
+//	Policy → *errs.SecurityPolicyError
+//	Validation → *errs.ValidationError
+//	Network → *errs.NetworkError
+//	Internal → *errs.InternalError
+//	Confirmation → *errs.ConfirmationRequiredError
+//	default (CategoryAPI) → *errs.APIError (Detail preserves raw response)
+//
+// Unknown Lark codes (LookupCodeMeta returns false) fall back to
+// CategoryAPI + SubtypeUnknown.
+func BuildAPIError(resp map[string]any, cc ClassifyContext) error {
+	if resp == nil {
+		return nil
+	}
+	code := intFromAny(resp["code"])
+	if code == 0 {
+		return nil
+	}
+	msg, _ := resp["msg"].(string)
+	if msg == "" {
+		// Upstream omitted or sent non-string msg. Keep Problem.Message non-empty
+		// so the typed wire envelope still carries a human-readable signal.
+		msg = fmt.Sprintf("API error: [%d]", code)
+	}
+	// Lark API responses sometimes carry log_id at the top level
+	// ({"code":..., "log_id":"..."}) and sometimes nested under "error"
+	// ({"code":..., "error":{"log_id":"..."}}). Prefer top level and fall
+	// back to the nested location so log_id always surfaces on the typed
+	// envelope.
+	logID, _ := resp["log_id"].(string)
+	if logID == "" {
+		if errBlock, ok := resp["error"].(map[string]any); ok {
+			if nested, ok := errBlock["log_id"].(string); ok {
+				logID = nested
+			}
+		}
+	}
+
+	meta, ok := LookupCodeMeta(code)
+	if !ok {
+		meta = CodeMeta{Category: errs.CategoryAPI, Subtype: errs.SubtypeUnknown}
+	}
+
+	base := errs.Problem{
+		Category:  meta.Category,
+		Subtype:   meta.Subtype,
+		Code:      code,
+		Message:   msg,
+		LogID:     logID,
+		Retryable: meta.Retryable,
+	}
+
+	switch meta.Category {
+	case errs.CategoryAuthorization:
+		return buildPermissionError(base, resp, cc)
+	case errs.CategoryAuthentication:
+		return &errs.AuthenticationError{Problem: base}
+	case errs.CategoryConfig:
+		return &errs.ConfigError{Problem: base}
+	case errs.CategoryPolicy:
+		return buildSecurityPolicyError(base, resp)
+	case errs.CategoryValidation:
+		return &errs.ValidationError{Problem: base}
+	case errs.CategoryNetwork:
+		return &errs.NetworkError{Problem: base}
+	case errs.CategoryInternal:
+		return &errs.InternalError{Problem: base}
+	case errs.CategoryConfirmation:
+		return &errs.ConfirmationRequiredError{Problem: base}
+	default:
+		return &errs.APIError{Problem: base, Detail: resp}
+	}
+}
+
+// buildSecurityPolicyError extracts challenge_url and the hint from a Lark API
+// response's data block, so the typed SecurityPolicyError carries the same
+// browser-challenge information that internal/auth/transport.go surfaces at
+// the HTTP layer.
+//
+// Data shapes accepted (whichever the upstream sends):
+//
+//	{"code": 21000, "msg": "...", "data": {"challenge_url": "...", "hint"|"cli_hint": "..."}}
+//	{"code": 21000, "error": {"data": {"challenge_url": "...", "hint"|"cli_hint": "..."}}}
+//
+// challenge_url is dropped (set to "") if it is not an https:// URL — same
+// validation policy as internal/auth/transport.go.isValidChallengeURL.
+// Hint is read from `data.hint` first and falls back to `data.cli_hint` so
+// either spelling surfaces, matching the transport layer.
+func buildSecurityPolicyError(p errs.Problem, resp map[string]any) *errs.SecurityPolicyError {
+	dataMap, _ := resp["data"].(map[string]any)
+	if dataMap == nil {
+		if errBlock, ok := resp["error"].(map[string]any); ok {
+			dataMap, _ = errBlock["data"].(map[string]any)
+		}
+	}
+	if dataMap == nil {
+		return &errs.SecurityPolicyError{Problem: p}
+	}
+
+	challengeURL := strings.Trim(stringFromAny(dataMap["challenge_url"]), " `")
+	if challengeURL != "" && !isHTTPSURL(challengeURL) {
+		challengeURL = ""
+	}
+
+	hint := stringFromAny(dataMap["hint"])
+	if hint == "" {
+		hint = stringFromAny(dataMap["cli_hint"])
+	}
+	if hint != "" {
+		p.Hint = hint
+	}
+
+	return &errs.SecurityPolicyError{
+		Problem:      p,
+		ChallengeURL: challengeURL,
+	}
+}
+
+// isHTTPSURL is the local-to-errclass duplicate of internal/auth/transport.go's
+// isValidChallengeURL. Kept local to avoid coupling errclass to internal/auth;
+// the two will collapse when the auth transport adopts BuildAPIError in stage 4.
+func isHTTPSURL(rawURL string) bool {
+	if rawURL == "" {
+		return false
+	}
+	u, err := url.Parse(rawURL)
+	if err != nil {
+		return false
+	}
+	return u.Scheme == "https"
+}
+
+// stringFromAny coerces a map value to string when it is a string, returning "" otherwise.
+func stringFromAny(v any) string {
+	s, _ := v.(string)
+	return s
+}
+
+func buildPermissionError(p errs.Problem, resp map[string]any, cc ClassifyContext) *errs.PermissionError {
+	missing := extractMissingScopes(resp)
+	identity := cc.Identity
+	if identity == "" {
+		identity = "user"
+	}
+	p.Hint = PermissionHint(missing, identity, p.Subtype)
+	return &errs.PermissionError{
+		Problem:       p,
+		MissingScopes: missing,
+		Identity:      identity,
+		ConsoleURL:    ConsoleURL(cc.Brand, cc.AppID, missing),
+	}
+}
+
+// PermissionHint returns an actionable next-step string for a permission
+// error. User identity with a missing user-scope is recovered by re-running
+// `auth login --scope ...`; bot identity or app-level scope errors are
+// recovered by enabling scopes in the open-platform console. The subtype
+// argument distinguishes app-level failures (e.g. SubtypeAppScopeNotApplied)
+// where re-authentication will not help regardless of the caller identity.
+//
+// Exported so direct construction sites (cmd/service/service.go's
+// checkServiceScopes) can produce hints that match the dispatcher path
+// byte-for-byte instead of hand-rolling divergent strings.
+func PermissionHint(missing []string, identity string, subtype errs.Subtype) string {
+	// app_scope_not_enabled means the scope has not been granted at the
+	// app (developer console) level — re-authenticating cannot fix it,
+	// so route every caller identity to the console hint.
+	useConsole := identity == "bot" || subtype == errs.SubtypeAppScopeNotApplied
+	if len(missing) == 0 {
+		if useConsole {
+			return "check the app's scope grant in the Lark open platform console"
+		}
+		return "ensure the calling identity has been granted the required scopes"
+	}
+	scopes := strings.Join(missing, " ")
+	if useConsole {
+		return fmt.Sprintf("the app is missing required scope(s): %s. Open the app's open platform console and add them.", scopes)
+	}
+	return fmt.Sprintf("run `lark-cli auth login --scope \"%s\"` to re-authenticate with the missing scope(s)", scopes)
+}
+
+// extractMissingScopes walks resp["error"]["permission_violations"][].subject.
+// Returns nil when the structure is absent.
+func extractMissingScopes(resp map[string]any) []string {
+	errBlock, ok := resp["error"].(map[string]any)
+	if !ok {
+		return nil
+	}
+	raw, ok := errBlock["permission_violations"].([]any)
+	if !ok || len(raw) == 0 {
+		return nil
+	}
+	seen := map[string]bool{}
+	var out []string
+	for _, v := range raw {
+		m, ok := v.(map[string]any)
+		if !ok {
+			continue
+		}
+		s, _ := m["subject"].(string)
+		if s == "" || seen[s] {
+			continue
+		}
+		seen[s] = true
+		out = append(out, s)
+	}
+	return out
+}
+
+// ConsoleURL composes the Feishu/Lark open-platform scope-grant console URL,
+// suitable for PermissionError.ConsoleURL. Empty appID → empty string. Empty
+// scopes list returns the bare /auth landing page; scopes are joined with
+// commas in the `q` query parameter so the console can pre-select them.
+//
+// brand is "feishu" or "lark"; unknown values default to feishu.
+func ConsoleURL(brand, appID string, scopes []string) string {
+	if appID == "" {
+		return ""
+	}
+	host := "open.feishu.cn"
+	if brand == "lark" {
+		host = "open.larksuite.com"
+	}
+	// PathEscape on appID — it sits in the URL path. QueryEscape on the
+	// comma-joined scopes — they sit in the `?q=` value, and untrusted scope
+	// content must not be able to inject extra query parameters via `&`/`#`.
+	pathID := url.PathEscape(appID)
+	if len(scopes) == 0 {
+		return fmt.Sprintf("https://%s/app/%s/auth", host, pathID)
+	}
+	return fmt.Sprintf("https://%s/app/%s/auth?q=%s", host, pathID, url.QueryEscape(strings.Join(scopes, ",")))
+}
+
+func intFromAny(v any) int {
+	switch n := v.(type) {
+	case int:
+		return n
+	case int64:
+		return int(n)
+	case float64:
+		return int(n)
+	case json.Number:
+		i, err := n.Int64()
+		if err == nil {
+			return int(i)
+		}
+		f, err := n.Float64()
+		if err == nil {
+			return int(f)
+		}
+	}
+	return 0
+}

internal/errclass/classify_test.go

@@ -0,0 +1,747 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errclass_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/errclass"
+	"github.com/larksuite/cli/internal/output"
+)
+
+// missingScopeResp builds a minimal Lark missing-scope response with one
+// violation. Shared across the envelope-shape and brand-switch tests.
+func missingScopeResp(scope string) map[string]any {
+	return map[string]any{
+		"code": 99991679,
+		"msg":  "scope missing",
+		"error": map[string]any{
+			"permission_violations": []any{
+				map[string]any{"subject": scope},
+			},
+		},
+	}
+}
+
+func TestBuildAPIError_NilAndZeroCode(t *testing.T) {
+	if got := errclass.BuildAPIError(nil, errclass.ClassifyContext{}); got != nil {
+		t.Errorf("nil resp should return nil error, got %v", got)
+	}
+	if got := errclass.BuildAPIError(map[string]any{"code": 0, "msg": "ok"}, errclass.ClassifyContext{}); got != nil {
+		t.Errorf("code=0 should return nil error, got %v", got)
+	}
+	// json.Number 0 path (real-world SDK decodes with UseNumber)
+	resp := map[string]any{"code": json.Number("0"), "msg": "ok"}
+	if got := errclass.BuildAPIError(resp, errclass.ClassifyContext{}); got != nil {
+		t.Errorf("json.Number(0) should return nil error, got %v", got)
+	}
+}
+
+// matchesTypedError reports whether err is the typed-error variant identified by
+// wantTyped (e.g. "ValidationError" → *errs.ValidationError). Used by the
+// ExitCode matrix so a wrong-Category routing (e.g. CategoryValidation falling
+// through to *APIError) fails loudly instead of passing on Category alone.
+func matchesTypedError(err error, wantTyped string) bool {
+	switch wantTyped {
+	case "PermissionError":
+		var x *errs.PermissionError
+		return errors.As(err, &x)
+	case "AuthenticationError":
+		var x *errs.AuthenticationError
+		return errors.As(err, &x)
+	case "ValidationError":
+		var x *errs.ValidationError
+		return errors.As(err, &x)
+	case "NetworkError":
+		var x *errs.NetworkError
+		return errors.As(err, &x)
+	case "ConfigError":
+		var x *errs.ConfigError
+		return errors.As(err, &x)
+	case "InternalError":
+		var x *errs.InternalError
+		return errors.As(err, &x)
+	case "ConfirmationRequiredError":
+		var x *errs.ConfirmationRequiredError
+		return errors.As(err, &x)
+	case "SecurityPolicyError":
+		var x *errs.SecurityPolicyError
+		return errors.As(err, &x)
+	case "APIError":
+		// APIError is the default fallback; use a direct type assertion to avoid
+		// matching against typed subclasses that also satisfy IsAPI.
+		_, ok := err.(*errs.APIError)
+		return ok
+	}
+	return false
+}
+
+func TestBuildAPIError_ExitCodeMatrix(t *testing.T) {
+	cases := []struct {
+		name        string
+		code        int
+		wantCat     errs.Category
+		wantSubtype errs.Subtype
+		wantExit    int
+		wantTyped   string
+	}{
+		{"99991672 app_missing_scope", 99991672, errs.CategoryAuthorization, errs.SubtypeAppScopeNotApplied, 3, "PermissionError"},
+		{"99991676 token_no_permission", 99991676, errs.CategoryAuthorization, errs.SubtypeTokenScopeInsufficient, 3, "PermissionError"},
+		{"99991679 missing_scope", 99991679, errs.CategoryAuthorization, errs.SubtypeMissingScope, 3, "PermissionError"},
+		{"230027 user_not_authorized", 230027, errs.CategoryAuthorization, errs.SubtypeUserUnauthorized, 3, "PermissionError"},
+		{"1470403 task_permission_denied", 1470403, errs.CategoryAuthorization, errs.Subtype("task_permission_denied"), 3, "PermissionError"},
+		{"1470400 task_invalid_params", 1470400, errs.CategoryValidation, errs.Subtype("task_invalid_params"), 2, "ValidationError"},
+		{"99991400 rate_limit", 99991400, errs.CategoryAPI, errs.SubtypeRateLimit, 1, "APIError"},
+		{"99991661 token_missing", 99991661, errs.CategoryAuthentication, errs.SubtypeTokenMissing, 3, "AuthenticationError"},
+		{"21000 challenge_required", 21000, errs.CategoryPolicy, errs.Subtype("challenge_required"), 6, "SecurityPolicyError"},
+		{"unknown code 999999", 999999, errs.CategoryAPI, errs.SubtypeUnknown, 1, "APIError"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			resp := map[string]any{"code": tc.code, "msg": "x"}
+			err := errclass.BuildAPIError(resp, errclass.ClassifyContext{Brand: "feishu", AppID: "cli_test", Identity: "user"})
+			if err == nil {
+				t.Fatalf("expected error for code %d, got nil", tc.code)
+			}
+			p, ok := errs.ProblemOf(err)
+			if !ok {
+				t.Fatalf("ProblemOf returned !ok for code %d (err = %T)", tc.code, err)
+			}
+			if p.Category != tc.wantCat {
+				t.Errorf("Category = %q, want %q", p.Category, tc.wantCat)
+			}
+			if p.Subtype != tc.wantSubtype {
+				t.Errorf("Subtype = %q, want %q", p.Subtype, tc.wantSubtype)
+			}
+			if got := output.ExitCodeOf(err); got != tc.wantExit {
+				t.Errorf("ExitCodeOf = %d, want %d (typed = %s)", got, tc.wantExit, tc.wantTyped)
+			}
+			if !matchesTypedError(err, tc.wantTyped) {
+				t.Errorf("typed-error mismatch: got %T, want %s", err, tc.wantTyped)
+			}
+		})
+	}
+}
+
+// TestBuildAPIError_ValidationRoutesToValidationError pins that code 1470400
+// (taskCodeMeta → CategoryValidation) produces *errs.ValidationError, not
+// the default *errs.APIError. The dispatcher must read codeMeta.Category and
+// route accordingly so the embedded Problem.Category matches the wire type.
+func TestBuildAPIError_ValidationRoutesToValidationError(t *testing.T) {
+	resp := map[string]any{"code": 1470400, "msg": "bad params"}
+	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{})
+	if err == nil {
+		t.Fatal("expected error for code 1470400")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T", err)
+	}
+	if _, isAPI := err.(*errs.APIError); isAPI {
+		t.Fatalf("unexpected *errs.APIError fallthrough (F2 regression): %T", err)
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatal("ProblemOf returned !ok")
+	}
+	if p.Category != errs.CategoryValidation {
+		t.Errorf("Category = %q, want %q", p.Category, errs.CategoryValidation)
+	}
+}
+
+func TestPermissionErrorEnvelopeShape(t *testing.T) {
+	resp := map[string]any{
+		"code":   99991679,
+		"msg":    "missing scope",
+		"log_id": "lg-1",
+		"error": map[string]any{
+			"permission_violations": []any{
+				map[string]any{"subject": "docx:document"},
+			},
+		},
+	}
+	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{Brand: "feishu", AppID: "cli_a123", Identity: "user"})
+
+	var buf bytes.Buffer
+	ok := output.WriteTypedErrorEnvelope(&buf, err, "user")
+	if !ok {
+		t.Fatal("WriteTypedErrorEnvelope returned false for typed error")
+	}
+	out := buf.String()
+
+	// positive assertions
+	for _, want := range []string{
+		`"type": "authorization"`,
+		`"subtype": "missing_scope"`,
+		`"code": 99991679`,
+		`"missing_scopes":`,
+		`"docx:document"`,
+		`"console_url":`,
+		`open.feishu.cn/app/cli_a123/auth`,
+		`"identity": "user"`,
+		`"log_id": "lg-1"`,
+	} {
+		if !strings.Contains(out, want) {
+			t.Errorf("envelope missing %q\nfull: %s", want, out)
+		}
+	}
+	// negative assertions on the wire format
+	for _, mustNot := range []string{
+		`"component"`,
+		`"doc_url"`,
+		`"retryable":`, // Retryable defaults false, omitempty → key absent
+	} {
+		if strings.Contains(out, mustNot) {
+			t.Errorf("envelope must not contain %q\nfull: %s", mustNot, out)
+		}
+	}
+}
+
+func TestRetryableEnvelope_TrueOnly(t *testing.T) {
+	// Test 1: Retryable:true → key present
+	apiErr := &errs.APIError{Problem: errs.Problem{
+		Category: errs.CategoryAPI, Subtype: errs.SubtypeRateLimit, Message: "x", Retryable: true,
+	}}
+	var buf bytes.Buffer
+	output.WriteTypedErrorEnvelope(&buf, apiErr, "user")
+	if !strings.Contains(buf.String(), `"retryable": true`) {
+		t.Errorf("Retryable:true should emit key; got: %s", buf.String())
+	}
+
+	// Test 2: Retryable:false → key absent
+	buf.Reset()
+	apiErr2 := &errs.APIError{Problem: errs.Problem{
+		Category: errs.CategoryAPI, Message: "x", Retryable: false,
+	}}
+	if ok := output.WriteTypedErrorEnvelope(&buf, apiErr2, "user"); !ok {
+		t.Fatal("WriteTypedErrorEnvelope returned false for typed error — emission failed silently")
+	}
+	if strings.Contains(buf.String(), `"retryable"`) {
+		t.Errorf("Retryable:false should omit key; got: %s", buf.String())
+	}
+}
+
+func TestConsoleURL_FeishuBrand(t *testing.T) {
+	resp := missingScopeResp("docx:document")
+	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{Brand: "feishu", AppID: "cli_a123", Identity: "user"})
+	pe, ok := err.(*errs.PermissionError)
+	if !ok {
+		t.Fatalf("expected *errs.PermissionError, got %T", err)
+	}
+	if !strings.Contains(pe.ConsoleURL, "open.feishu.cn/app/cli_a123") {
+		t.Fatalf("ConsoleURL = %q, want open.feishu.cn prefix", pe.ConsoleURL)
+	}
+}
+
+func TestConsoleURL_LarkBrand(t *testing.T) {
+	resp := missingScopeResp("docx:document")
+	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{Brand: "lark", AppID: "cli_a123", Identity: "user"})
+	pe, ok := err.(*errs.PermissionError)
+	if !ok {
+		t.Fatalf("expected *errs.PermissionError, got %T", err)
+	}
+	if !strings.Contains(pe.ConsoleURL, "open.larksuite.com/app/cli_a123") {
+		t.Fatalf("ConsoleURL = %q, want open.larksuite.com prefix", pe.ConsoleURL)
+	}
+}
+
+func TestConsoleURL_EmptyAppID(t *testing.T) {
+	resp := missingScopeResp("docx:document")
+	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{Brand: "feishu", AppID: "", Identity: "user"})
+	pe := err.(*errs.PermissionError)
+	if pe.ConsoleURL != "" {
+		t.Errorf("ConsoleURL with empty AppID should be empty; got %q", pe.ConsoleURL)
+	}
+}
+
+// TestConsoleURL_EscapesDangerousChars pins that ConsoleURL escapes appID and
+// scope values so a hostile value cannot break out of the URL framing
+// (e.g. by smuggling extra `&` parameters or a `#` fragment).
+func TestConsoleURL_EscapesDangerousChars(t *testing.T) {
+	tests := []struct {
+		name      string
+		appID     string
+		scopes    []string
+		wantInURL []string // substrings that MUST appear
+		denyInURL []string // substrings that MUST NOT appear
+	}{
+		{
+			name:      "ampersand in scope smuggles extra param",
+			appID:     "cli_good",
+			scopes:    []string{"scope&evil=injected"},
+			wantInURL: []string{"q=scope%26evil%3Dinjected"},
+			denyInURL: []string{"q=scope&evil=injected"},
+		},
+		{
+			name:      "hash in scope splits fragment",
+			appID:     "cli_good",
+			scopes:    []string{"scope#fragment"},
+			wantInURL: []string{"q=scope%23fragment"},
+			denyInURL: []string{"q=scope#fragment"},
+		},
+		{
+			name:      "question mark in appID prematurely opens query",
+			appID:     "good?q=injected",
+			scopes:    []string{"docx:document"},
+			wantInURL: []string{"/app/good%3Fq=injected/auth"},
+			denyInURL: []string{"/app/good?q=injected/auth"},
+		},
+		{
+			name:      "hash in appID truncates URL",
+			appID:     "good#fragment",
+			scopes:    []string{"docx:document"},
+			wantInURL: []string{"/app/good%23fragment/auth"},
+			denyInURL: []string{"/app/good#fragment/auth"},
+		},
+		{
+			name:      "slash in appID escapes path segment",
+			appID:     "good/extra/segment",
+			scopes:    []string{"docx:document"},
+			wantInURL: []string{"/app/good%2Fextra%2Fsegment/auth"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := errclass.ConsoleURL("feishu", tt.appID, tt.scopes)
+			for _, want := range tt.wantInURL {
+				if !strings.Contains(got, want) {
+					t.Errorf("ConsoleURL missing escaped substring\n  want: %s\n  got:  %s", want, got)
+				}
+			}
+			for _, deny := range tt.denyInURL {
+				if strings.Contains(got, deny) {
+					t.Errorf("ConsoleURL contains unescaped dangerous substring\n  deny: %s\n  got:  %s", deny, got)
+				}
+			}
+		})
+	}
+}
+
+func TestPermissionError_DefaultIdentity(t *testing.T) {
+	resp := missingScopeResp("docx:document")
+	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{Brand: "feishu", AppID: "cli_a123" /* no Identity */})
+	pe := err.(*errs.PermissionError)
+	if pe.Identity != "user" {
+		t.Errorf("default Identity should be \"user\"; got %q", pe.Identity)
+	}
+}
+
+func TestPermissionError_NoViolations(t *testing.T) {
+	// permission error without a permission_violations array → MissingScopes nil,
+	// ConsoleURL falls back to the no-scope form.
+	resp := map[string]any{"code": 99991679, "msg": "x"}
+	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{Brand: "feishu", AppID: "cli_a123", Identity: "user"})
+	pe := err.(*errs.PermissionError)
+	if pe.MissingScopes != nil {
+		t.Errorf("MissingScopes should be nil; got %v", pe.MissingScopes)
+	}
+	if !strings.HasSuffix(pe.ConsoleURL, "/app/cli_a123/auth") {
+		t.Errorf("ConsoleURL (no scopes) = %q, want trailing /app/cli_a123/auth", pe.ConsoleURL)
+	}
+}
+
+func TestExtractMissingScopes_Dedup(t *testing.T) {
+	resp := map[string]any{
+		"code": 99991679,
+		"msg":  "x",
+		"error": map[string]any{
+			"permission_violations": []any{
+				map[string]any{"subject": "docx:document"},
+				map[string]any{"subject": "docx:document"}, // dup
+				map[string]any{"subject": ""},              // ignored
+				map[string]any{"subject": "im:message"},
+			},
+		},
+	}
+	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{Brand: "feishu", AppID: "cli_a123", Identity: "user"})
+	pe := err.(*errs.PermissionError)
+	if got, want := len(pe.MissingScopes), 2; got != want {
+		t.Fatalf("MissingScopes len = %d, want %d (raw: %v)", got, want, pe.MissingScopes)
+	}
+}
+
+// TestServiceShortcutEnvelopeConverge guards that the wire envelope is
+// identical whether produced via the dispatcher (BuildAPIError — the normal
+// service / shortcut path) or constructed directly at the call site (the
+// cmd/service permission path).
+//
+// cmd/service/service.go's checkServiceScopes builds PermissionError using the
+// exported PermissionHint and ConsoleURL helpers — the same helpers
+// BuildAPIError uses. The hand-constructed branch below intentionally mirrors
+// service.go line-by-line so a future drift on either side (e.g. a new
+// extension field on PermissionError that only BuildAPIError populates) fails
+// loudly here. The remaining limitation is that this test invokes the helpers
+// directly rather than driving checkServiceScopes (which requires a credential
+// + factory mock). TODO: lift this into cmd/service_test.go once a lightweight
+// mock harness lands.
+func TestServiceShortcutEnvelopeConverge(t *testing.T) {
+	const (
+		brand    = "feishu"
+		appID    = "cli_a123"
+		identity = "user"
+	)
+	missing := []string{"docx:document"}
+
+	// Path A: dispatcher — BuildAPIError parsing a Lark API response.
+	resp := missingScopeResp(missing[0])
+	dispatcherErr := errclass.BuildAPIError(resp, errclass.ClassifyContext{Brand: brand, AppID: appID, Identity: identity})
+	dispatcherPE, ok := dispatcherErr.(*errs.PermissionError)
+	if !ok {
+		t.Fatalf("BuildAPIError did not return *PermissionError, got %T", dispatcherErr)
+	}
+
+	// Path B: direct construction — exactly mirrors cmd/service/service.go's
+	// checkServiceScopes (same helpers, same field-fill order). Code
+	// and Message are copied from Path A so the byte-comparison below isolates
+	// the contract under test (Hint + Identity + ConsoleURL convergence).
+	directErr := &errs.PermissionError{
+		Problem: errs.Problem{
+			Category: errs.CategoryAuthorization,
+			Subtype:  errs.SubtypeMissingScope,
+			Code:     dispatcherPE.Code,
+			Message:  dispatcherPE.Message,
+			Hint:     errclass.PermissionHint(missing, identity, errs.SubtypeMissingScope),
+		},
+		MissingScopes: missing,
+		Identity:      identity,
+		ConsoleURL:    errclass.ConsoleURL(brand, appID, missing),
+	}
+
+	var bufA, bufB bytes.Buffer
+	if ok := output.WriteTypedErrorEnvelope(&bufA, dispatcherErr, identity); !ok {
+		t.Fatal("dispatcher path failed to emit typed envelope")
+	}
+	if ok := output.WriteTypedErrorEnvelope(&bufB, directErr, identity); !ok {
+		t.Fatal("direct path failed to emit typed envelope")
+	}
+
+	if bufA.String() != bufB.String() {
+		t.Errorf("dispatcher vs direct-construction envelopes diverge:\nDispatcher: %s\nDirect:     %s", bufA.String(), bufB.String())
+	}
+}
+
+func TestDirectPermissionPath_TypedExitCode(t *testing.T) {
+	// Mirrors what the cmd/service direct-construction path produces.
+	pe := &errs.PermissionError{
+		Problem: errs.Problem{
+			Category: errs.CategoryAuthorization,
+			Subtype:  errs.SubtypeMissingScope,
+			Message:  "missing required scope(s): docx:document",
+		},
+		MissingScopes: []string{"docx:document"},
+		Identity:      "user",
+	}
+	if got := output.ExitCodeOf(pe); got != 3 {
+		t.Errorf("ExitCodeOf = %d, want 3", got)
+	}
+	if !errs.IsPermission(pe) {
+		t.Error("expected IsPermission(pe) == true")
+	}
+}
+
+func TestWriteTypedEnvelope_UntypedReturnsFalse(t *testing.T) {
+	var buf bytes.Buffer
+	if output.WriteTypedErrorEnvelope(&buf, errors.New("plain"), "user") {
+		t.Error("expected WriteTypedErrorEnvelope to return false for untyped error")
+	}
+	if buf.Len() > 0 {
+		t.Errorf("expected no output for untyped error, got: %s", buf.String())
+	}
+}
+
+func TestBuildAPIError_LogIDNestedInError(t *testing.T) {
+	// Some Lark API responses carry log_id nested under "error" rather than
+	// at the top level. BuildAPIError must surface either location.
+	resp := map[string]any{
+		"code": 99991679,
+		"msg":  "missing scope",
+		"error": map[string]any{
+			"log_id": "lg-nested-123",
+		},
+	}
+	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{Brand: "feishu", AppID: "cli_x", Identity: "user"})
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("ProblemOf returned !ok, err = %T", err)
+	}
+	if p.LogID != "lg-nested-123" {
+		t.Errorf("LogID = %q, want lg-nested-123", p.LogID)
+	}
+}
+
+func TestBuildAPIError_LogIDTopLevel(t *testing.T) {
+	resp := map[string]any{
+		"code":   99991679,
+		"msg":    "missing scope",
+		"log_id": "lg-top-456",
+	}
+	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{Identity: "user"})
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("ProblemOf returned !ok, err = %T", err)
+	}
+	if p.LogID != "lg-top-456" {
+		t.Errorf("LogID = %q, want lg-top-456", p.LogID)
+	}
+}
+
+func TestBuildPermissionHint_UserWithScopes(t *testing.T) {
+	got := errclass.PermissionHint([]string{"docx:document", "im:message"}, "user", errs.SubtypeMissingScope)
+	if !strings.Contains(got, "lark-cli auth login") {
+		t.Errorf("user hint should suggest `lark-cli auth login`; got %q", got)
+	}
+	if !strings.Contains(got, "docx:document") || !strings.Contains(got, "im:message") {
+		t.Errorf("user hint should include missing scopes; got %q", got)
+	}
+}
+
+func TestBuildPermissionHint_BotWithScopes(t *testing.T) {
+	got := errclass.PermissionHint([]string{"docx:document"}, "bot", errs.SubtypeMissingScope)
+	if !strings.Contains(got, "open platform console") {
+		t.Errorf("bot hint should mention the open-platform console; got %q", got)
+	}
+	if strings.Contains(got, "auth login") {
+		t.Errorf("bot hint must not suggest re-running `auth login`; got %q", got)
+	}
+}
+
+func TestBuildPermissionHint_NoScopes(t *testing.T) {
+	if got := errclass.PermissionHint(nil, "user", errs.SubtypeMissingScope); !strings.Contains(got, "required scopes") {
+		t.Errorf("user no-scope hint missing fallback wording; got %q", got)
+	}
+	if got := errclass.PermissionHint(nil, "bot", errs.SubtypeMissingScope); !strings.Contains(got, "open platform console") {
+		t.Errorf("bot no-scope hint should still point at the console; got %q", got)
+	}
+}
+
+func TestBuildPermissionHint_AppMissingScopeRoutesToConsole(t *testing.T) {
+	// 99991672 / app_scope_not_enabled means the scope has not been granted
+	// at the app level — re-authenticating cannot fix it. The hint must
+	// point to the developer console regardless of caller identity, or
+	// agents will loop on `auth login` forever.
+	for _, identity := range []string{"user", "bot", ""} {
+		got := errclass.PermissionHint([]string{"contact:contact"}, identity, errs.SubtypeAppScopeNotApplied)
+		if !strings.Contains(got, "open platform console") {
+			t.Errorf("identity=%q: hint should point to console; got %q", identity, got)
+		}
+		if strings.Contains(got, "auth login") {
+			t.Errorf("identity=%q: hint must not suggest `auth login`; got %q", identity, got)
+		}
+	}
+}
+
+func TestBuildAPIError_AppMissingScope_UserIdentityHintRoutesToConsole(t *testing.T) {
+	// Regression: code 99991672 with user identity previously emitted
+	// `lark-cli auth login --scope ...` which sends agents into a re-auth
+	// loop because the missing scope is not yet enabled at the app level.
+	resp := map[string]any{
+		"code":  99991672,
+		"msg":   "app scope not enabled",
+		"error": map[string]any{"permission_violations": []any{map[string]any{"subject": "contact:contact"}}},
+	}
+	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{Brand: "feishu", AppID: "cli_x", Identity: "user"})
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("ProblemOf returned !ok, err = %T", err)
+	}
+	if p.Subtype != errs.SubtypeAppScopeNotApplied {
+		t.Errorf("Subtype = %q, want %q", p.Subtype, errs.SubtypeAppScopeNotApplied)
+	}
+	if !strings.Contains(p.Hint, "open platform console") {
+		t.Errorf("Hint should route to console; got %q", p.Hint)
+	}
+	if strings.Contains(p.Hint, "auth login") {
+		t.Errorf("Hint must not suggest `auth login` for app-level scope errors; got %q", p.Hint)
+	}
+}
+
+func TestPermissionError_HintPopulated(t *testing.T) {
+	resp := missingScopeResp("docx:document")
+	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{Brand: "feishu", AppID: "cli_a123", Identity: "user"})
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("ProblemOf returned !ok, err = %T", err)
+	}
+	if p.Hint == "" {
+		t.Error("PermissionError.Hint should be populated by BuildAPIError")
+	}
+	if !strings.Contains(p.Hint, "docx:document") {
+		t.Errorf("Hint should reference missing scope; got %q", p.Hint)
+	}
+}
+
+func TestBuildAPIError_JSONNumberCode(t *testing.T) {
+	// SDK parses with json.Number; verify intFromAny handles it.
+	resp := map[string]any{"code": json.Number("99991679"), "msg": "x"}
+	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{Brand: "feishu", AppID: "cli_a123", Identity: "user"})
+	if err == nil {
+		t.Fatal("expected error for json.Number-encoded code")
+	}
+	if _, ok := err.(*errs.PermissionError); !ok {
+		t.Errorf("expected *errs.PermissionError, got %T", err)
+	}
+}
+
+// TestBuildAPIError_SecurityPolicyExtractsChallenge pins that policy responses
+// passing through BuildAPIError keep the browser-challenge URL and hint —
+// agents need challenge_url to drive the user through MFA / device-trust
+// flows. Without extraction, the typed envelope is degenerate vs. what the
+// internal/auth/transport.go HTTP-layer interceptor already produces.
+func TestBuildAPIError_SecurityPolicyExtractsChallenge(t *testing.T) {
+	resp := map[string]any{
+		"code": 21000,
+		"msg":  "challenge required",
+		"data": map[string]any{
+			"challenge_url": "https://passport.feishu.cn/challenge/xyz",
+			"hint":          "complete MFA in the browser, then retry",
+		},
+	}
+	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{Brand: "feishu", AppID: "cli_test", Identity: "user"})
+	spe, ok := err.(*errs.SecurityPolicyError)
+	if !ok {
+		t.Fatalf("expected *SecurityPolicyError, got %T", err)
+	}
+	if spe.ChallengeURL != "https://passport.feishu.cn/challenge/xyz" {
+		t.Errorf("ChallengeURL = %q, want https://passport.feishu.cn/challenge/xyz", spe.ChallengeURL)
+	}
+	if spe.Hint != "complete MFA in the browser, then retry" {
+		t.Errorf("Hint = %q, want MFA hint", spe.Hint)
+	}
+}
+
+// TestBuildAPIError_SecurityPolicyHintFallsBackToCliHint pins that responses
+// using data.cli_hint still surface via Hint when data.hint is absent.
+func TestBuildAPIError_SecurityPolicyHintFallsBackToCliHint(t *testing.T) {
+	resp := map[string]any{
+		"code": 21001,
+		"msg":  "access denied",
+		"data": map[string]any{
+			"cli_hint": "ask your admin for elevated approval",
+		},
+	}
+	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{Brand: "feishu", AppID: "cli_test", Identity: "user"})
+	spe, ok := err.(*errs.SecurityPolicyError)
+	if !ok {
+		t.Fatalf("expected *SecurityPolicyError, got %T", err)
+	}
+	if spe.Hint != "ask your admin for elevated approval" {
+		t.Errorf("Hint = %q, want cli_hint fallback", spe.Hint)
+	}
+}
+
+// TestBuildAPIError_SecurityPolicyDropsNonHTTPSChallenge pins that an
+// untrusted challenge_url (non-https) is dropped — same policy as
+// internal/auth/transport.go isValidChallengeURL.
+func TestBuildAPIError_SecurityPolicyDropsNonHTTPSChallenge(t *testing.T) {
+	cases := []string{
+		"http://attacker.example.com/challenge",
+		"javascript:alert(1)",
+		"ftp://example.com/challenge",
+		"not a url at all",
+	}
+	for _, bad := range cases {
+		t.Run(bad, func(t *testing.T) {
+			resp := map[string]any{
+				"code": 21000,
+				"msg":  "challenge required",
+				"data": map[string]any{"challenge_url": bad, "hint": "h"},
+			}
+			err := errclass.BuildAPIError(resp, errclass.ClassifyContext{})
+			spe, ok := err.(*errs.SecurityPolicyError)
+			if !ok {
+				t.Fatalf("expected *SecurityPolicyError, got %T", err)
+			}
+			if spe.ChallengeURL != "" {
+				t.Errorf("ChallengeURL should be dropped for %q, got %q", bad, spe.ChallengeURL)
+			}
+		})
+	}
+}
+
+// TestBuildAPIError_SecurityPolicyNoData pins the no-data case — typed
+// envelope still routes correctly with empty extension fields when the
+// upstream response carries only code+msg.
+func TestBuildAPIError_SecurityPolicyNoData(t *testing.T) {
+	resp := map[string]any{"code": 21000, "msg": "challenge required"}
+	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{})
+	spe, ok := err.(*errs.SecurityPolicyError)
+	if !ok {
+		t.Fatalf("expected *SecurityPolicyError, got %T", err)
+	}
+	if spe.ChallengeURL != "" {
+		t.Errorf("ChallengeURL should be empty without data; got %q", spe.ChallengeURL)
+	}
+	if spe.Message != "challenge required" {
+		t.Errorf("Message = %q, want challenge required", spe.Message)
+	}
+}
+
+// TestBuildAPIError_SecurityPolicyMalformedData pins that malformed `data`
+// blocks (wrong type, wrong shape, non-string fields) degrade gracefully —
+// extension fields stay empty, no panic. Server-side bugs or transitional
+// API shapes must never crash the CLI dispatcher.
+func TestBuildAPIError_SecurityPolicyMalformedData(t *testing.T) {
+	cases := []struct {
+		name string
+		resp map[string]any
+	}{
+		{"data is string not map", map[string]any{"code": 21000, "msg": "x", "data": "oops"}},
+		{"data is array not map", map[string]any{"code": 21000, "msg": "x", "data": []any{1, 2}}},
+		{"data is nil", map[string]any{"code": 21000, "msg": "x", "data": nil}},
+		{"challenge_url is int", map[string]any{"code": 21000, "msg": "x", "data": map[string]any{"challenge_url": 123}}},
+		{"challenge_url is nil", map[string]any{"code": 21000, "msg": "x", "data": map[string]any{"challenge_url": nil}}},
+		{"hint is array", map[string]any{"code": 21000, "msg": "x", "data": map[string]any{"hint": []any{"a"}}}},
+		{"error.data is wrong type", map[string]any{"code": 21000, "msg": "x", "error": map[string]any{"data": "oops"}}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			defer func() {
+				if r := recover(); r != nil {
+					t.Fatalf("BuildAPIError panicked on malformed data: %v", r)
+				}
+			}()
+			err := errclass.BuildAPIError(tc.resp, errclass.ClassifyContext{})
+			spe, ok := err.(*errs.SecurityPolicyError)
+			if !ok {
+				t.Fatalf("expected *SecurityPolicyError even with malformed data, got %T", err)
+			}
+			if spe.ChallengeURL != "" {
+				t.Errorf("ChallengeURL should be empty for malformed data, got %q", spe.ChallengeURL)
+			}
+		})
+	}
+}
+
+// TestBuildAPIError_SecurityPolicyErrorDataShape pins extraction from the
+// {"error": {"data": {...}}} envelope variant — same lookup paths the
+// transport-layer interceptor uses on inbound responses.
+func TestBuildAPIError_SecurityPolicyErrorDataShape(t *testing.T) {
+	resp := map[string]any{
+		"code": 21000,
+		"msg":  "challenge required",
+		"error": map[string]any{
+			"data": map[string]any{
+				"challenge_url": "https://passport.feishu.cn/c/abc",
+				"hint":          "wrapped variant",
+			},
+		},
+	}
+	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{})
+	spe, ok := err.(*errs.SecurityPolicyError)
+	if !ok {
+		t.Fatalf("expected *SecurityPolicyError, got %T", err)
+	}
+	if spe.ChallengeURL != "https://passport.feishu.cn/c/abc" {
+		t.Errorf("ChallengeURL = %q, want https://passport.feishu.cn/c/abc", spe.ChallengeURL)
+	}
+	if spe.Hint != "wrapped variant" {
+		t.Errorf("Hint = %q, want wrapped variant", spe.Hint)
+	}
+}

internal/errclass/codemeta.go

@@ -0,0 +1,87 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errclass
+
+import (
+	"fmt"
+
+	"github.com/larksuite/cli/errs"
+)
+
+// CodeMeta is the classification metadata attached to a Lark numeric code.
+// It does NOT carry Message or Hint — those are derived at the dispatcher
+// (see BuildAPIError).
+type CodeMeta struct {
+	Category  errs.Category
+	Subtype   errs.Subtype
+	Retryable bool
+}
+
+// codeMeta is the central registry. Top-level entries (auth/authorization/api/
+// policy/config codes shared across services) live here; service-specific
+// sub-tables (e.g. task) live in dedicated files like codemeta_task.go and
+// merge into this map via init().
+//
+// Go language guarantees package-level vars initialize before init() functions,
+// so sub-tables registering via init() can always assume codeMeta is non-nil.
+var codeMeta = map[int]CodeMeta{
+	// CategoryAuthentication
+	99991661: {errs.CategoryAuthentication, errs.SubtypeTokenMissing, false},        // Authorization header missing
+	99991671: {errs.CategoryAuthentication, errs.SubtypeTokenInvalid, false},        // token format error (must start with t- / u-)
+	99991668: {errs.CategoryAuthentication, errs.SubtypeTokenInvalid, false},        // UAT invalid/expired (server does not distinguish)
+	99991663: {errs.CategoryAuthentication, errs.SubtypeTokenInvalid, false},        // access_token invalid
+	99991677: {errs.CategoryAuthentication, errs.SubtypeTokenExpired, false},        // UAT expired
+	20026:    {errs.CategoryAuthentication, errs.SubtypeRefreshTokenInvalid, false}, // refresh_token v1 legacy format
+	20037:    {errs.CategoryAuthentication, errs.SubtypeRefreshTokenExpired, false}, // refresh_token expired
+	20064:    {errs.CategoryAuthentication, errs.SubtypeRefreshTokenRevoked, false}, // refresh_token revoked
+	20073:    {errs.CategoryAuthentication, errs.SubtypeRefreshTokenReused, false},  // refresh_token already used
+	20050:    {errs.CategoryAuthentication, errs.SubtypeRefreshServerError, true},   // refresh endpoint transient error
+
+	// CategoryAuthorization
+	99991672: {errs.CategoryAuthorization, errs.SubtypeAppScopeNotApplied, false},
+	99991676: {errs.CategoryAuthorization, errs.SubtypeTokenScopeInsufficient, false},
+	99991679: {errs.CategoryAuthorization, errs.SubtypeMissingScope, false},     // user authorized app but did not grant this scope
+	230027:   {errs.CategoryAuthorization, errs.SubtypeUserUnauthorized, false}, // user never authorized the app
+	99991673: {errs.CategoryAuthorization, errs.SubtypeAppUnavailable, false},   // app status unavailable
+	99991662: {errs.CategoryAuthorization, errs.SubtypeAppNotInstalled, false},  // app not enabled / not installed in tenant
+
+	// CategoryAPI
+	99991400: {errs.CategoryAPI, errs.SubtypeRateLimit, true},
+	1061045:  {errs.CategoryAPI, errs.SubtypeConflict, true},
+	131009:   {errs.CategoryAPI, errs.SubtypeConflict, true}, // wiki write-path lock contention; retryable with backoff
+	1064510:  {errs.CategoryAPI, errs.SubtypeCrossTenant, false},
+	1064511:  {errs.CategoryAPI, errs.SubtypeCrossBrand, false},
+	1310246:  {errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
+	1063006:  {errs.CategoryAPI, errs.SubtypeRateLimit, false}, // drive perm-apply quota; 5/day, not short-term retryable
+	1063007:  {errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
+	231205:   {errs.CategoryAPI, errs.SubtypeOwnershipMismatch, false},
+
+	// CategoryConfig
+	99991543: {errs.CategoryConfig, errs.SubtypeInvalidClient, false}, // RFC 6749 §5.2 — app_id / app_secret incorrect
+
+	// CategoryPolicy
+	21000: {errs.CategoryPolicy, errs.SubtypeChallengeRequired, false},
+	21001: {errs.CategoryPolicy, errs.SubtypeAccessDenied, false},
+}
+
+// LookupCodeMeta is the single lookup entry. Returns ok=false for unknown codes —
+// the caller (BuildAPIError) is responsible for falling back to
+// CategoryAPI/SubtypeUnknown.
+func LookupCodeMeta(code int) (CodeMeta, bool) {
+	m, ok := codeMeta[code]
+	return m, ok
+}
+
+// mergeCodeMeta is invoked by sub-table init() functions to merge service-specific
+// codes into the central registry. Panics on duplicate code so a misregistration
+// fails fast at startup rather than producing silently-inconsistent classification.
+func mergeCodeMeta(src map[int]CodeMeta, owner string) {
+	for code, meta := range src {
+		if existing, dup := codeMeta[code]; dup {
+			panic(fmt.Sprintf("codeMeta dup: code %d already mapped %+v; %s wants %+v",
+				code, existing, owner, meta))
+		}
+		codeMeta[code] = meta
+	}
+}

internal/errclass/codemeta_task.go

@@ -0,0 +1,24 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errclass
+
+import "github.com/larksuite/cli/errs"
+
+// taskCodeMeta holds the task-service-specific Lark code classifications.
+// 1470403 permission_denied is CategoryAuthorization (exit 3); the other task
+// codes route to CategoryAPI / CategoryValidation. BuildAPIError consumes this
+// map via mergeCodeMeta + LookupCodeMeta.
+var taskCodeMeta = map[int]CodeMeta{
+	1470400: {errs.CategoryValidation, errs.SubtypeTaskInvalidParams, false},
+	1470403: {errs.CategoryAuthorization, errs.SubtypeTaskPermissionDenied, false}, // permission_denied
+	1470404: {errs.CategoryAPI, errs.SubtypeTaskNotFound, false},
+	1470422: {errs.CategoryAPI, errs.SubtypeTaskConflict, true},
+	1470500: {errs.CategoryAPI, errs.SubtypeTaskServerError, true},
+	1470610: {errs.CategoryAPI, errs.SubtypeTaskAssigneeLimit, false},
+	1470611: {errs.CategoryAPI, errs.SubtypeTaskFollowerLimit, false},
+	1470612: {errs.CategoryAPI, errs.SubtypeTaskTasklistMemberLimit, false},
+	1470613: {errs.CategoryAPI, errs.SubtypeTaskReminderExists, false},
+}
+
+func init() { mergeCodeMeta(taskCodeMeta, "task") }

internal/errclass/codemeta_test.go

@@ -0,0 +1,105 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errclass
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+)
+
+func TestLookupCodeMeta_MissingScope(t *testing.T) {
+	got, ok := LookupCodeMeta(99991679)
+	if !ok {
+		t.Fatalf("LookupCodeMeta(99991679) ok=false, want true")
+	}
+	want := CodeMeta{Category: errs.CategoryAuthorization, Subtype: errs.SubtypeMissingScope, Retryable: false}
+	if got != want {
+		t.Fatalf("LookupCodeMeta(99991679) = %+v, want %+v", got, want)
+	}
+}
+
+func TestLookupCodeMeta_TaskPermissionDenied_MergedViaInit(t *testing.T) {
+	got, ok := LookupCodeMeta(1470403)
+	if !ok {
+		t.Fatalf("LookupCodeMeta(1470403) ok=false, want true (task sub-table init merge)")
+	}
+	if got.Category != errs.CategoryAuthorization {
+		t.Errorf("Category = %q, want %q", got.Category, errs.CategoryAuthorization)
+	}
+	if got.Subtype != errs.Subtype("task_permission_denied") {
+		t.Errorf("Subtype = %q, want %q", got.Subtype, "task_permission_denied")
+	}
+	if got.Retryable {
+		t.Errorf("Retryable = true, want false")
+	}
+}
+
+func TestLookupCodeMeta_RetryableAuthCode(t *testing.T) {
+	got, ok := LookupCodeMeta(20050)
+	if !ok {
+		t.Fatalf("LookupCodeMeta(20050) ok=false, want true")
+	}
+	if !got.Retryable {
+		t.Errorf("LookupCodeMeta(20050).Retryable = false, want true (sole retryable refresh code)")
+	}
+	if got.Category != errs.CategoryAuthentication {
+		t.Errorf("Category = %q, want %q", got.Category, errs.CategoryAuthentication)
+	}
+}
+
+func TestLookupCodeMeta_RetryableRateLimit(t *testing.T) {
+	got, ok := LookupCodeMeta(99991400)
+	if !ok {
+		t.Fatalf("LookupCodeMeta(99991400) ok=false, want true")
+	}
+	if !got.Retryable {
+		t.Errorf("LookupCodeMeta(99991400).Retryable = false, want true (rate_limit retryable)")
+	}
+	if got.Subtype != errs.SubtypeRateLimit {
+		t.Errorf("Subtype = %q, want %q", got.Subtype, errs.SubtypeRateLimit)
+	}
+}
+
+func TestLookupCodeMeta_Unknown(t *testing.T) {
+	_, ok := LookupCodeMeta(999999)
+	if ok {
+		t.Fatalf("LookupCodeMeta(999999) ok=true, want false for unknown code")
+	}
+}
+
+func TestLookupCodeMeta_PolicyChallengeRequired(t *testing.T) {
+	got, ok := LookupCodeMeta(21000)
+	if !ok {
+		t.Fatalf("LookupCodeMeta(21000) ok=false, want true")
+	}
+	if got.Category != errs.CategoryPolicy {
+		t.Errorf("Category = %q, want %q", got.Category, errs.CategoryPolicy)
+	}
+	if got.Subtype != errs.Subtype("challenge_required") {
+		t.Errorf("Subtype = %q, want %q", got.Subtype, "challenge_required")
+	}
+}
+
+func TestMergeCodeMeta_PanicsOnDuplicate(t *testing.T) {
+	defer func() {
+		r := recover()
+		if r == nil {
+			t.Fatalf("mergeCodeMeta with duplicate code did not panic")
+		}
+		msg, ok := r.(string)
+		if !ok {
+			t.Fatalf("panic value is not a string: %T (%v)", r, r)
+		}
+		for _, needle := range []string{"1470403", "task_permission_denied", "intruder", "test"} {
+			if !strings.Contains(msg, needle) {
+				t.Errorf("panic message %q missing substring %q", msg, needle)
+			}
+		}
+	}()
+	mergeCodeMeta(map[int]CodeMeta{
+		1470403: {Category: errs.CategoryAPI, Subtype: errs.Subtype("intruder")},
+	}, "test")
+}

internal/errcompat/promote.go

@@ -0,0 +1,32 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package errcompat bridges the legacy *core.ConfigError shape into the
+// canonical typed errors taxonomy in errs/. It is a thin boundary helper —
+// placed in its own package so it can import both core (for the legacy
+// type) and errs (for the typed targets) without creating an import cycle
+// with internal/errclass, which intentionally avoids depending on
+// internal/core.
+package errcompat
+
+import (
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/core"
+)
+
+// PromoteConfigError is the stage-2 boundary helper that will convert a
+// *core.ConfigError into the matching typed errs.* error. In stage 1 it
+// is a passthrough — the dispatcher continues to render *core.ConfigError
+// via the legacy envelope path (cmd/root.go asExitError) so the wire
+// shape stays identical to pre-PR. Per-domain typed migration in stage 2+
+// will fill in the actual promotion logic alongside its corresponding
+// wire-change announcement.
+func PromoteConfigError(cfgErr *core.ConfigError) error {
+	if cfgErr == nil {
+		return nil
+	}
+	return cfgErr
+}
+
+// _ keeps the errs import live so stage-2 fill-in does not need to re-add it.
+var _ = errs.CategoryConfig

internal/errcompat/promote_test.go

@@ -0,0 +1,37 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errcompat_test
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/errcompat"
+)
+
+// TestPromoteConfigError_Stage1Passthrough pins the stage-1 passthrough
+// behaviour: every input *core.ConfigError flows out unchanged so the
+// dispatcher's legacy envelope path emits the same wire shape as pre-PR.
+// Per-domain typed migration will replace this in stage 2+.
+func TestPromoteConfigError_Stage1Passthrough(t *testing.T) {
+	for _, cfgType := range []string{"config", "auth", "openclaw", ""} {
+		t.Run(cfgType, func(t *testing.T) {
+			src := &core.ConfigError{Code: 3, Type: cfgType, Message: "msg", Hint: "hint"}
+			out := errcompat.PromoteConfigError(src)
+			var got *core.ConfigError
+			if !errors.As(out, &got) || got != src {
+				t.Fatalf("Type=%q: expected passthrough of original *core.ConfigError, got %T (%v)", cfgType, out, out)
+			}
+		})
+	}
+}
+
+// TestPromoteConfigError_NilInputReturnsNil pins that PromoteConfigError on a
+// nil input returns nil rather than panicking on the (cfgErr.Type) access.
+func TestPromoteConfigError_NilInputReturnsNil(t *testing.T) {
+	if got := errcompat.PromoteConfigError(nil); got != nil {
+		t.Errorf("PromoteConfigError(nil) = %v, want nil", got)
+	}
+}

internal/hook/install.go

@@ -199,6 +199,13 @@ func runObserverSafe(ctx context.Context, obs ObserverEntry, inv platform.Invoca
 // *output.ExitError so cmd/root.go's envelope writer emits the right
 // JSON structure (type="hook"). Non-AbortError values pass through
 // unchanged.
+//
+// Deprecated: wrapAbortError converts to a legacy *output.ExitError that
+// predates the typed error contract introduced by errs/. New code MUST NOT
+// add producers of this shape — hook abort signals should move to a typed
+// *errs.XxxError (typed hook error is tracked for the hook framework
+// migration PR). This helper is retained only while existing call sites are
+// migrated; it will be removed once they have moved to the typed surface.
 func wrapAbortError(err error) error {
 	if err == nil {
 		return nil

internal/i18n/lang.go

@@ -0,0 +1,76 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package i18n
+
+// Lang is a Feishu locale (e.g. "zh_cn"); "" means unset.
+type Lang string
+
+const (
+	LangZhCN Lang = "zh_cn"
+	LangEnUS Lang = "en_us"
+	LangJaJP Lang = "ja_jp"
+	LangKoKR Lang = "ko_kr"
+	LangFrFR Lang = "fr_fr"
+	LangDeDE Lang = "de_de"
+	LangEsES Lang = "es_es"
+	LangItIT Lang = "it_it"
+	LangRuRU Lang = "ru_ru"
+	LangPtBR Lang = "pt_br"
+	LangThTH Lang = "th_th"
+	LangViVN Lang = "vi_vn"
+	LangIdID Lang = "id_id"
+	LangMsMY Lang = "ms_my"
+)
+
+type langEntry struct {
+	Code  Lang   // canonical Feishu locale
+	Short string // ISO 639-1 code, also accepted as input shorthand
+}
+
+// catalog is the single source of truth; order drives --help and error listing.
+var catalog = []langEntry{
+	{LangZhCN, "zh"}, {LangEnUS, "en"}, {LangJaJP, "ja"}, {LangKoKR, "ko"},
+	{LangFrFR, "fr"}, {LangDeDE, "de"}, {LangEsES, "es"}, {LangItIT, "it"},
+	{LangRuRU, "ru"}, {LangPtBR, "pt"}, {LangThTH, "th"}, {LangViVN, "vi"},
+	{LangIdID, "id"}, {LangMsMY, "ms"},
+}
+
+// find matches a short code or Feishu locale against the catalog (case-sensitive).
+func find(s string) (langEntry, bool) {
+	for _, e := range catalog {
+		if string(e.Code) == s || e.Short == s {
+			return e, true
+		}
+	}
+	return langEntry{}, false
+}
+
+// Parse resolves a short code or Feishu locale to its canonical Lang.
+// "" and unrecognized values return ("", false).
+func Parse(s string) (Lang, bool) {
+	e, ok := find(s)
+	return e.Code, ok
+}
+
+// IsEnglish reports whether l uses the English TUI bundle (robust to "en_us"
+// and legacy "en").
+func (l Lang) IsEnglish() bool {
+	e, _ := find(string(l))
+	return e.Code == LangEnUS
+}
+
+// Base returns the ISO 639-1 short code ("en_us" → "en"), or "" if unknown.
+func (l Lang) Base() string {
+	e, _ := find(string(l))
+	return e.Short
+}
+
+// Codes lists the canonical locales, for --help and error messages.
+func Codes() []string {
+	out := make([]string, len(catalog))
+	for i, e := range catalog {
+		out[i] = string(e.Code)
+	}
+	return out
+}

internal/i18n/lang_test.go

@@ -0,0 +1,96 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package i18n
+
+import "testing"
+
+func TestParse(t *testing.T) {
+	tests := []struct {
+		in     string
+		want   Lang
+		wantOK bool
+	}{
+		{"zh", LangZhCN, true},    // short code
+		{"zh_cn", LangZhCN, true}, // canonical locale
+		{"en", LangEnUS, true},    // short code
+		{"en_us", LangEnUS, true}, // canonical locale
+		{"ja", LangJaJP, true},    // short code
+		{"pt", LangPtBR, true},    // pt → pt_br, not pt_pt
+		{"ms", LangMsMY, true},    // ms → ms_my
+		{"", "", false},           // unset
+		{"ZH", "", false},         // case-sensitive
+		{"zh-CN", "", false},      // hyphen form not accepted
+		{"zh_CN", "", false},      // case-sensitive region
+		{"ar", "", false},         // not in the supported set
+		{"xx", "", false},         // unknown
+	}
+	for _, tt := range tests {
+		t.Run(tt.in, func(t *testing.T) {
+			got, ok := Parse(tt.in)
+			if got != tt.want || ok != tt.wantOK {
+				t.Errorf("Parse(%q) = (%q, %v), want (%q, %v)", tt.in, got, ok, tt.want, tt.wantOK)
+			}
+		})
+	}
+}
+
+func TestIsEnglish(t *testing.T) {
+	tests := []struct {
+		lang Lang
+		want bool
+	}{
+		{LangEnUS, true},
+		{Lang("en"), true}, // legacy short value on disk stays robust
+		{LangZhCN, false},
+		{LangJaJP, false},
+		{Lang("zh"), false},
+		{Lang(""), false}, // unset → not English (zh bundle)
+		{Lang("garbage"), false},
+	}
+	for _, tt := range tests {
+		t.Run(string(tt.lang), func(t *testing.T) {
+			if got := tt.lang.IsEnglish(); got != tt.want {
+				t.Errorf("Lang(%q).IsEnglish() = %v, want %v", tt.lang, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestBase(t *testing.T) {
+	tests := []struct {
+		lang Lang
+		want string
+	}{
+		{LangEnUS, "en"},
+		{LangZhCN, "zh"},
+		{LangJaJP, "ja"},
+		{Lang("en"), "en"}, // legacy short value
+		{Lang("zh"), "zh"},
+		{Lang(""), ""},        // unset
+		{Lang("garbage"), ""}, // unknown
+	}
+	for _, tt := range tests {
+		t.Run(string(tt.lang), func(t *testing.T) {
+			if got := tt.lang.Base(); got != tt.want {
+				t.Errorf("Lang(%q).Base() = %q, want %q", tt.lang, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestCodes(t *testing.T) {
+	codes := Codes()
+	if len(codes) != 14 {
+		t.Fatalf("len(Codes()) = %d, want 14", len(codes))
+	}
+	if codes[0] != "zh_cn" {
+		t.Errorf("Codes()[0] = %q, want %q (catalog order)", codes[0], "zh_cn")
+	}
+	// Every code must round-trip through Parse to itself (canonical).
+	for _, c := range codes {
+		if got, ok := Parse(c); !ok || string(got) != c {
+			t.Errorf("Parse(%q) = (%q, %v), want (%q, true)", c, got, ok, c)
+		}
+	}
+}