feat: recommend keywords for minutes

Co-authored-by: Cursor <cursoragent@cursor.com>

.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-cli <domain> <command>` flow works as expected
+- [ ] Manual local verification confirms the `lark xxx` command 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/
@@ -34,13 +34,9 @@ tests/mail/reports/
 
 # Generated / test artifacts
 .hammer/
-.lark-slides/
 internal/registry/meta_data.json
 cmd/api/download.bin
 app.log
 /sidecar-server-demo
 /server-demo
 .tmp/
-cover*.out
-
-lark-env.sh

.golangci.yml

@@ -45,7 +45,6 @@ linters:
       - path: _test\.go$
         linters:
           - bodyclose
-          - bidichk
           - gocritic
           - depguard
           - forbidigo

CHANGELOG.md

@@ -2,171 +2,6 @@
 
 All notable changes to this project will be documented in this file.
 
-## [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
-
-- **wiki**: Add exponential backoff retry for `+node-create` lock contention (#1012)
-- **auth**: Add `auth qrcode` subcommand and update auth docs/hints (#968)
-
-### Bug Fixes
-
-- **wiki**: Rename `+node-get --token` to `--node-token`, keep alias (#1074)
-- **output**: Classify wiki lock-contention error (131009) with retry hint (#1014)
-- **contact**: Add actionable hint when fanout search all-fail with no API code (#1054)
-- **permission**: Annotate auto-grant permission failures with `required_scope` and `console_url` (#1045)
-- **validation**: Use `ErrValidation` instead of `fmt.Errorf` in `Validate` paths (#1001)
-
-### Documentation
-
-- **skills**: Add 云盘/云存储 alias alongside 云空间 for agent clarity (#1073)
-- **task**: Refresh `lark-task` shortcut docs (#1057)
-
-## [v1.0.39] - 2026-05-22
-
-### Features
-
-- **slides**: Add `+export` shortcut to export slides (#988)
-- **sidecar**: Support multi-client identity isolation in `server-demo` via per-client HMAC keys, preventing UAT cross-contamination when multiple CLI sandboxes share one sidecar (#934)
-- **im**: Support Markdown image rendering in post content (#893)
-
-### Bug Fixes
-
-- **scope**: Add 22 new scope entries to scope priorities (#1050)
-
-### Documentation
-
-- **base**: Update location `full_address` guidance (#754)
-- **apps**: Refine `lark-apps` skill description and surface, document `index.html` / `--path` hard constraints (#1040)
-
-## [v1.0.38] - 2026-05-22
-
-### Features
-
-- **apps**: Gate the Miaoda apps domain off on the Lark brand — the `apps` shortcut subtree returns a structured brand-restriction error, `auth login --domain apps` is rejected, `--domain all` skips it, and `spark:*` scopes are no longer requested (#1025)
-
-## [v1.0.37] - 2026-05-21
-
-### Features
-
-- **apps**: Add miaoda apps domain with 6 shortcuts covering `+create` / `+update` / `+list` / `+access-scope-get` / `+access-scope-set` / `+html-publish` (#1002)
-
-### Bug Fixes
-
-- **permission**: Surface auto-grant skipped/failed cases via stderr warnings and a `hint` field in the `permission_grant` JSON output (#1015)
-- **sheets**: Use `FileIO` for `+write-image` input so stdin / `-` works consistently (#996)
-
-## [v1.0.36] - 2026-05-21
-
-### Features
-
-- **drive/markdown**: Return real tenant URLs for `drive +upload` and `markdown +create` (#992)
-
-### Bug Fixes
-
-- **auth**: Return validation error when `--scope` is empty in `auth check` (#999)
-
-### Documentation
-
-- **lark-drive**: Improve search evidence guidance (#864)
-
-## [v1.0.35] - 2026-05-20
-
-### Features
-
-- **markdown**: Support wiki node target in `+create` (#883)
-- **markdown**: Add `+diff` shortcut (#876)
-- **base**: Add form `+detail` / `+submit` shortcuts (#759)
-- **skills**: Add incremental skills sync (#965)
-- **doc**: Warn before overwrite when document contains whiteboard or file blocks (#825)
-
-### Documentation
-
-- **im**: Clarify media key formats for message media flags (#991)
-- **im**: Add media-preview reference (#990)
-- **drive**: Migrate `docs +search` to `drive +search` and fix `creator_ids` owner semantic (#951)
-- **drive**: Prefer local comments for drive reviews (#981)
-- **wiki**: Add wiki base fast path (#982)
-
-## [v1.0.34] - 2026-05-19
-
-### Features
-
-- **drive**: Switch markdown export to V2 `docs_ai` fetch API (#948)
-- **drive**: Add `+inspect` shortcut for document URL inspection with wiki unwrapping (#947)
-- **wiki**: Add `+node-get` / `+node-delete` / `+space-create` shortcuts (#904)
-- **base**: Support Base attachment APIs (#887)
-- **mail**: Validate `bot` + `mailbox=me` and add dynamic `--as` help tests (#895)
-- **mail**: Expose draft priority in `--inspect` projection and document `--set-priority` (#779)
-
-### Bug Fixes
-
-- **identitydiag**: Harden verify path and tighten status semantics (#961)
-- **wiki**: Surface real node URL for `+node-create` / `+node-copy` (#960)
-- **auth**: Split bot and user identity diagnostics (#957)
-- **base**: Address Base attachment review follow-ups (#958)
-- **docs**: Clarify `replace_all` selection errors (#954)
-
-### Documentation
-
-- **drive**: Clarify add comment constraints (#967)
-- **lark-im**: Clarify message activity search (#865)
-
-### Tests
-
-- Verify e2e resource cleanup (#949)
-- **lint**: Exclude `bidichk` from test files (#959)
-
-## [v1.0.33] - 2026-05-18
-
-### Features
-
-- **markdown**: Add `+patch` shortcut (#857)
-- **slides**: Improve slide planning and validation guidance (#847)
-- **drive**: Add `+sync` workflow for Drive directories (#873)
-- **drive**: Add drive version shortcut (#841)
-- **extension**: Plugin / Hook framework with command pruning (#910)
-
-### Bug Fixes
-
-- **sheets**: Explicitly document safe JSON unmarshal ignore in `DryRun` (#935)
-- **base**: Mark base field update high risk (#936)
-- **auth**: Guide agents to yield during auth device flow (#933)
-
-### Documentation
-
-- **lark-wiki**: Correct the `--as` default-identity claim (#919)
-
-### Tests
-
-- Drop stale e2e `--yes` flags (#920)
-
 ## [v1.0.32] - 2026-05-15
 
 ### Features
@@ -886,15 +721,6 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
-[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
-[v1.0.37]: https://github.com/larksuite/cli/releases/tag/v1.0.37
-[v1.0.36]: https://github.com/larksuite/cli/releases/tag/v1.0.36
-[v1.0.35]: https://github.com/larksuite/cli/releases/tag/v1.0.35
-[v1.0.34]: https://github.com/larksuite/cli/releases/tag/v1.0.34
-[v1.0.33]: https://github.com/larksuite/cli/releases/tag/v1.0.33
 [v1.0.32]: https://github.com/larksuite/cli/releases/tag/v1.0.32
 [v1.0.31]: https://github.com/larksuite/cli/releases/tag/v1.0.31
 [v1.0.30]: https://github.com/larksuite/cli/releases/tag/v1.0.30

README.md

@@ -6,14 +6,14 @@
 
 [中文版](./README.zh.md) | [English](./README.md)
 
-The official [Lark/Feishu](https://www.larksuite.com/) CLI tool, maintained by the [larksuite](https://github.com/larksuite) team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Slides, Calendar, Mail, Tasks, Meetings, Markdown, and more, with 200+ commands and 26 AI Agent [Skills](./skills/).
+The official [Lark/Feishu](https://www.larksuite.com/) CLI tool, maintained by the [larksuite](https://github.com/larksuite) team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Slides, Calendar, Mail, Tasks, Meetings, Markdown, and more, with 200+ commands and 24 AI Agent [Skills](./skills/).
 
 [Install](#installation--quick-start) · [AI Agent Skills](#agent-skills) · [Auth](#authentication) · [Commands](#three-layer-command-system) · [Advanced](#advanced-usage) · [Security](#security--risk-warnings-read-before-use) · [Contributing](#contributing)
 
 ## Why lark-cli?
 
 - **Agent-Native Design** — 24 structured [Skills](./skills/) out of the box, compatible with popular AI tools — Agents can operate Lark with zero extra setup
-- **Wide Coverage** — 18 business domains, 200+ curated commands, 26 AI Agent [Skills](./skills/)
+- **Wide Coverage** — 17 business domains, 200+ curated commands, 24 AI Agent [Skills](./skills/)
 - **AI-Friendly & Optimized** — Every command is tested with real Agents, featuring concise parameters, smart defaults, and structured output to maximize Agent call success rates
 - **Open Source, Zero Barriers** — MIT license, ready to use, just `npm install`
 - **Up and Running in 3 Minutes** — One-click app creation, interactive login, from install to first API call in just 3 steps
@@ -28,7 +28,7 @@ The official [Lark/Feishu](https://www.larksuite.com/) CLI tool, maintained by t
 | 💬 Messenger  | Send/reply messages, create and manage group chats, view chat history & threads, search messages, download media                  |
 | 📄 Docs       | Create, read, update, and search documents, read/write media & whiteboards                                                        |
 | 📁 Drive      | Upload and download files, search docs & wiki, manage comments                                                                    |
-| 📝 Markdown   | Create, fetch, patch, and overwrite Drive-native `.md` files                                                                      |
+| 📝 Markdown   | Create, fetch, and overwrite Drive-native `.md` files                                                                             |
 | 📊 Base       | Create and manage tables, fields, records, views, dashboards, workflows, forms, roles & permissions, data aggregation & analytics |
 | 📈 Sheets     | Create, read, write, append, find, and export spreadsheet data                                                                    |
 | 🖼️ Slides     | Create and manage presentations, read presentation content, and add or remove slides                                              |
@@ -41,7 +41,6 @@ The official [Lark/Feishu](https://www.larksuite.com/) CLI tool, maintained by t
 | ✍️ Approval   | Query approval tasks, approve/reject/transfer tasks, cancel and CC instances                                                      |
 | 🎯 OKR        | Query, create, update OKRs; manage objective & key results, alignments, indicators and progress.                                  |
 | 📋 Project    | Meegle — manage work items, schedules, and data via the standalone [meegle-cli](https://github.com/larksuite/meegle-cli) (install separately) |
-| 🔗 Apps       | Develop, deploy HTML, web pages and applications                                                                                  |
 
 ## Installation & Quick Start
 
@@ -133,7 +132,7 @@ lark-cli auth status
 | `lark-im`                       | Send/reply messages, group chat management, message search, upload/download images & files, reactions          |
 | `lark-doc`                      | Create, read, update, search documents (Markdown-based)                                                        |
 | `lark-drive`                    | Upload, download files, manage permissions & comments                                                          |
-| `lark-markdown`                 | Create, fetch, patch, and overwrite Drive-native Markdown files                                                |
+| `lark-markdown`                 | Create, fetch, and overwrite Drive-native Markdown files                                                       |
 | `lark-sheets`                   | Create, read, write, append, find, export spreadsheets                                                         |
 | `lark-slides`                   | Create and manage presentations, read presentation content, and add or remove slides                          |
 | `lark-base`                     | Tables, fields, records, views, dashboards, data aggregation & analytics                                       |
@@ -279,8 +278,6 @@ 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

@@ -6,14 +6,14 @@
 
 [中文版](./README.zh.md) | [English](./README.md)
 
-飞书官方 CLI 工具，由 [larksuite](https://github.com/larksuite) 团队维护 — 让人类和 AI Agent 都能在终端中操作飞书。覆盖消息、文档、多维表格、电子表格、幻灯片、日历、邮箱、任务、会议、Markdown 等核心业务域，提供 200+ 命令及 26 个 AI Agent [Skills](./skills/)。
+飞书官方 CLI 工具，由 [larksuite](https://github.com/larksuite) 团队维护 — 让人类和 AI Agent 都能在终端中操作飞书。覆盖消息、文档、多维表格、电子表格、幻灯片、日历、邮箱、任务、会议、Markdown 等核心业务域，提供 200+ 命令及 24 个 AI Agent [Skills](./skills/)。
 
 [安装](#安装与快速开始) · [AI Agent Skills](#agent-skills) · [认证](#认证) · [命令](#三层命令调用) · [进阶用法](#进阶用法) · [安全](#安全与风险提示使用前必读) · [贡献](#贡献)
 
 ## 为什么选 lark-cli？
 
-- **为 Agent 原生设计** — 26 个 [Skills](./skills/) 开箱即用，适配主流 AI 工具，Agent 无需额外适配即可操作飞书
-- **覆盖面广** — 18 大业务域、200+ 精选命令、26 个 AI Agent [Skills](./skills/)
+- **为 Agent 原生设计** — 24 个 [Skills](./skills/) 开箱即用，适配主流 AI 工具，Agent 无需额外适配即可操作飞书
+- **覆盖面广** — 17 大业务域、200+ 精选命令、24 个 AI Agent [Skills](./skills/)
 - **AI 友好调优** — 每条命令经过 Agent 实测验证，提供更友好的参数、智能默认值和结构化输出，大幅提升 Agent 调用成功率
 - **开源零门槛** — MIT 协议，开箱即用，`npm install` 即可使用
 - **三分钟上手** — 一键创建应用、交互式登录授权，从安装到第一次 API 调用只需三步
@@ -28,7 +28,7 @@
 | 💬 即时通讯 | 发送/回复消息、创建和管理群聊、查看聊天记录与话题、搜索消息、下载媒体文件      |
 | 📄 云文档   | 创建、读取、更新文档、搜索文档、读写素材与画板                    |
 | 📁 云空间   | 上传和下载文件、搜索文档与知识库、管理评论                      |
-| 📝 Markdown | 创建、读取、局部 patch、覆盖更新 Drive 中的原生 `.md` 文件          |
+| 📝 Markdown | 创建、读取、覆盖更新 Drive 中的原生 `.md` 文件                |
 | 📊 多维表格 | 创建和管理数据表、字段、记录、视图、仪表盘、自动化流程、表单、角色权限，数据聚合分析 |
 | 📈 电子表格 | 创建、读取、写入、追加、查找和导出表格数据                      |
 | 🖼️ 幻灯片   | 创建和管理演示文稿、读取演示文稿内容，以及新增或删除幻灯片页面 |
@@ -41,7 +41,6 @@
 | ✍️ 审批     | 查询审批任务、同意/拒绝/转交审批任务、撤回与抄送审批实例              |
 | 🎯 OKR  | 查询、创建、更新 OKR，管理目标、关键结果、对齐、指标和进展记录        |
 | 📋 飞书项目 | 管理工作项、排期与数据 — 由独立的 [meegle-cli](https://github.com/larksuite/meegle-cli) 提供（需单独安装） |
-| 🔗 应用     | 开发、部署 HTML、Web 页面和应用                                                                                                          |
 
 ## 安装与快速开始
 
@@ -134,7 +133,7 @@ lark-cli auth status
 | `lark-im`                       | 发送/回复消息、群聊管理、消息搜索、上传下载图片与文件、表情回复          |
 | `lark-doc`                      | 创建、读取、更新、搜索文档（基于 Markdown）                |
 | `lark-drive`                    | 上传、下载文件，管理权限与评论                           |
-| `lark-markdown`                 | 创建、读取、局部 patch、覆盖更新 Drive 中的原生 Markdown 文件   |
+| `lark-markdown`                 | 创建、读取、覆盖更新 Drive 中的原生 Markdown 文件         |
 | `lark-sheets`                   | 创建、读取、写入、追加、查找、导出电子表格                     |
 | `lark-slides`                   | 创建和管理演示文稿、读取演示文稿内容，以及新增或删除幻灯片页面 |
 | `lark-base`                     | 多维表格、字段、记录、视图、仪表盘、数据聚合分析                  |
@@ -280,8 +279,6 @@ lark-cli schema im.messages.delete
 
 对于较大的改动，建议先通过 Issue 与我们讨论。
 
-提交 PR 前，请先阅读 [AGENTS.md](./AGENTS.md)，其中列出了贡献者和 AI Agent 使用的本地构建、测试和 PR 检查清单。
-
 ## 许可证
 
 本项目基于 **MIT 许可证** 开源。

cmd/api/api.go

@@ -238,11 +238,7 @@ func apiRun(opts *APIOptions) error {
 
 	resp, err := ac.DoAPI(opts.Ctx, request)
 	if err != nil {
-		// 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)
+		return output.MarkRaw(client.WrapDoAPIError(err))
 	}
 	err = client.HandleResponse(resp, client.ResponseOptions{
 		OutputPath:  opts.Output,
@@ -252,15 +248,9 @@ 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: see comment above on the DoAPI path. Applies equally to
-	// HandleResponse failures so the raw API error survives to the wire.
+	// MarkRaw tells root error handler to skip enrichPermissionError,
+	// preserving the original API error detail (log_id, troubleshooter, etc.).
 	if err != nil {
 		return output.MarkRaw(err)
 	}
@@ -272,12 +262,9 @@ 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, ac.CheckResponse); err != nil {
+		if err := client.PaginateWithJq(ctx, ac, request, jqExpr, out, pagOpts, client.CheckLarkResponse); err != nil {
 			return output.MarkRaw(err)
 		}
 		return nil
@@ -290,9 +277,9 @@ func apiPaginate(ctx context.Context, ac *client.APIClient, request client.RawAp
 			pf.FormatPage(items)
 		}, pagOpts)
 		if err != nil {
-			return output.MarkRaw(err)
+			return output.MarkRaw(output.ErrNetwork("API call failed: %v", err))
 		}
-		if apiErr := ac.CheckResponse(result, pagOpts.Identity); apiErr != nil {
+		if apiErr := client.CheckLarkResponse(result); apiErr != nil {
 			output.FormatValue(out, result, output.FormatJSON)
 			return output.MarkRaw(apiErr)
 		}
@@ -304,9 +291,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(err)
+			return output.MarkRaw(output.ErrNetwork("API call failed: %v", err))
 		}
-		if apiErr := ac.CheckResponse(result, pagOpts.Identity); apiErr != nil {
+		if apiErr := client.CheckLarkResponse(result); apiErr != nil {
 			output.FormatValue(out, result, output.FormatJSON)
 			return output.MarkRaw(apiErr)
 		}

cmd/api/api_test.go

@@ -4,6 +4,7 @@
 package api
 
 import (
+	"errors"
 	"os"
 	"sort"
 	"strings"
@@ -12,6 +13,7 @@ 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"
 )
 
@@ -397,6 +399,154 @@ 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/auth.go

@@ -43,7 +43,6 @@ func NewCmdAuth(f *cmdutil.Factory) *cobra.Command {
 	cmd.AddCommand(NewCmdAuthScopes(f, nil))
 	cmd.AddCommand(NewCmdAuthList(f, nil))
 	cmd.AddCommand(NewCmdAuthCheck(f, nil))
-	cmd.AddCommand(NewCmdAuthQRCode(f, nil))
 	return cmd
 }
 

cmd/auth/auth_test.go

@@ -61,7 +61,7 @@ func TestAuthLoginCmd_HelpGuidesNonStreamingAgentsToSplitFlow(t *testing.T) {
 	for _, want := range []string{
 		"only delivers final turn messages",
 		"--no-wait --json",
-		"send the verification URL (or QR code) to the user as your final message",
+		"send the verification URL to the user as your final message",
 		"run --device-code in a later step",
 	} {
 		if !strings.Contains(got, want) {

cmd/auth/check.go

@@ -47,7 +47,8 @@ func authCheckRun(opts *CheckOptions) error {
 
 	required := strings.Fields(opts.Scope)
 	if len(required) == 0 {
-		return output.ErrValidation("--scope cannot be empty")
+		output.PrintJson(f.IOStreams.Out, map[string]interface{}{"ok": true, "granted": []string{}, "missing": []string{}})
+		return nil
 	}
 
 	config, err := f.Config()

cmd/auth/login.go

@@ -47,10 +47,9 @@ func NewCmdAuthLogin(f *cmdutil.Factory, runF func(*LoginOptions) error) *cobra.
 		Long: `Device Flow authorization login.
 
 For AI agents: this command blocks until the user completes authorization in the
-browser. If your harness or agent tool only delivers final turn messages, use --no-wait --json,
-send the verification URL (or QR code) to the user as your final message, end the turn, then
-run --device-code in a later step after the user confirms authorization. Use 'lark-cli auth qrcode'
-to generate QR codes (supports ASCII and PNG formats).`,
+browser. If your harness only delivers final turn messages, use --no-wait --json,
+send the verification URL to the user as your final message, end the turn, then
+run --device-code in a later step after the user confirms authorization.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if mode := f.ResolveStrictMode(cmd.Context()); mode == core.StrictModeBot {
 				return output.ErrWithHint(output.ExitValidation, "command_denied",
@@ -69,13 +68,7 @@ to generate QR codes (supports ASCII and PNG formats).`,
 
 	cmd.Flags().StringVar(&opts.Scope, "scope", "", "scopes to request (space- or comma-separated). Combines additively with --domain/--recommend")
 	cmd.Flags().BoolVar(&opts.Recommend, "recommend", false, "request only recommended (auto-approve) scopes")
-	var helpBrand core.LarkBrand
-	if f != nil && f.Config != nil {
-		if cfg, err := f.Config(); err == nil && cfg != nil {
-			helpBrand = cfg.Brand
-		}
-	}
-	available := sortedKnownDomains(helpBrand)
+	available := sortedKnownDomains()
 	cmd.Flags().StringSliceVar(&opts.Domains, "domain", nil,
 		fmt.Sprintf("domain (repeatable or comma-separated, e.g. --domain calendar,task)\navailable: %s, all", strings.Join(available, ", ")))
 	cmd.Flags().StringSliceVar(&opts.Exclude, "exclude", nil,
@@ -146,14 +139,14 @@ func authLoginRun(opts *LoginOptions) error {
 	// Expand --domain all to all available domains (from_meta projects + shortcut services)
 	for _, d := range selectedDomains {
 		if strings.EqualFold(d, "all") {
-			selectedDomains = sortedKnownDomains(config.Brand)
+			selectedDomains = sortedKnownDomains()
 			break
 		}
 	}
 
 	// Validate domain names and suggest corrections for unknown ones
 	if len(selectedDomains) > 0 {
-		knownDomains := allKnownDomains(config.Brand)
+		knownDomains := allKnownDomains()
 		for _, d := range selectedDomains {
 			if !knownDomains[d] {
 				if suggestion := suggestDomain(d, knownDomains); suggestion != "" {
@@ -177,7 +170,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, msg)
 			if err != nil {
 				return err
 			}
@@ -215,10 +208,10 @@ func authLoginRun(opts *LoginOptions) error {
 	if len(selectedDomains) > 0 || opts.Recommend {
 		var candidateScopes []string
 		if len(selectedDomains) > 0 {
-			candidateScopes = collectScopesForDomains(selectedDomains, "user", config.Brand)
+			candidateScopes = collectScopesForDomains(selectedDomains, "user")
 		} else {
 			// --recommend without --domain: all domains
-			candidateScopes = collectScopesForDomains(sortedKnownDomains(config.Brand), "user", config.Brand)
+			candidateScopes = collectScopesForDomains(sortedKnownDomains(), "user")
 		}
 
 		// Filter to auto-approve scopes if --recommend or interactive "common"
@@ -276,7 +269,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.**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),
+			"hint":             fmt.Sprintf("Show verification_url to the user exactly as returned by the CLI and treat it as an opaque string. Do not URL-encode or decode it, do not normalize or rewrite it, do not add %%20, spaces, or punctuation, and do not wrap it as Markdown link text; prefer a fenced code block containing only the raw URL. For agent harnesses that only deliver final turn messages, make the 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)
@@ -459,7 +452,6 @@ func authLoginPollDeviceCode(opts *LoginOptions, config *core.CliConfig, msg *lo
 	return nil
 }
 
-// syncLoginUserToProfile persists the logged-in user info into the named profile.
 func syncLoginUserToProfile(profileName, appID, openID, userName string) error {
 	multi, err := core.LoadMultiAppConfig()
 	if err != nil {
@@ -485,7 +477,6 @@ func syncLoginUserToProfile(profileName, appID, openID, userName string) error {
 	return nil
 }
 
-// findProfileByName returns the AppConfig matching profileName, or nil.
 func findProfileByName(multi *core.MultiAppConfig, profileName string) *core.AppConfig {
 	for i := range multi.Apps {
 		if multi.Apps[i].ProfileName() == profileName {
@@ -499,7 +490,7 @@ func findProfileByName(multi *core.MultiAppConfig, profileName string) *core.App
 // shortcut scopes for the given domain names.
 // Domains with auth_domain children are automatically expanded to include
 // their children's scopes.
-func collectScopesForDomains(domains []string, identity string, brand core.LarkBrand) []string {
+func collectScopesForDomains(domains []string, identity string) []string {
 	scopeSet := make(map[string]bool)
 
 	// 1. API scopes from from_meta projects
@@ -518,9 +509,6 @@ func collectScopesForDomains(domains []string, identity string, brand core.LarkB
 
 	// 3. Shortcut scopes matching by Service (only include shortcuts supporting the identity)
 	for _, sc := range shortcuts.AllShortcuts() {
-		if !shortcuts.IsShortcutServiceAvailable(sc.Service, brand) {
-			continue
-		}
 		if domainSet[sc.Service] && shortcutSupportsIdentity(sc, identity) {
 			for _, s := range sc.DeclaredScopesForIdentity(identity) {
 				scopeSet[s] = true
@@ -540,7 +528,7 @@ func collectScopesForDomains(domains []string, identity string, brand core.LarkB
 // allKnownDomains returns all valid auth domain names (from_meta projects +
 // shortcut services), excluding domains that have auth_domain set (they are
 // folded into their parent domain).
-func allKnownDomains(brand core.LarkBrand) map[string]bool {
+func allKnownDomains() map[string]bool {
 	domains := make(map[string]bool)
 	for _, p := range registry.ListFromMetaProjects() {
 		if !registry.HasAuthDomain(p) {
@@ -548,9 +536,6 @@ func allKnownDomains(brand core.LarkBrand) map[string]bool {
 		}
 	}
 	for _, sc := range shortcuts.AllShortcuts() {
-		if !shortcuts.IsShortcutServiceAvailable(sc.Service, brand) {
-			continue
-		}
 		if !registry.HasAuthDomain(sc.Service) {
 			domains[sc.Service] = true
 		}
@@ -559,8 +544,8 @@ func allKnownDomains(brand core.LarkBrand) map[string]bool {
 }
 
 // sortedKnownDomains returns all valid domain names sorted alphabetically.
-func sortedKnownDomains(brand core.LarkBrand) []string {
-	m := allKnownDomains(brand)
+func sortedKnownDomains() []string {
+	m := allKnownDomains()
 	domains := make([]string, 0, len(m))
 	for d := range m {
 		domains = append(domains, d)

cmd/auth/login_brand_filter_test.go

@@ -1,32 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package auth
-
-import (
-	"testing"
-
-	"github.com/larksuite/cli/internal/core"
-)
-
-func TestBrandFilter_AppsExcludedOnLark(t *testing.T) {
-	feishuDomains := allKnownDomains(core.BrandFeishu)
-	if !feishuDomains["apps"] {
-		t.Errorf("expected apps domain to be known on Feishu brand")
-	}
-
-	larkDomains := allKnownDomains(core.BrandLark)
-	if larkDomains["apps"] {
-		t.Errorf("expected apps domain to be EXCLUDED on Lark brand")
-	}
-
-	feishuScopes := collectScopesForDomains([]string{"apps"}, "user", core.BrandFeishu)
-	if len(feishuScopes) == 0 {
-		t.Errorf("expected non-empty scopes for apps on Feishu brand, got %d", len(feishuScopes))
-	}
-
-	larkScopes := collectScopesForDomains([]string{"apps"}, "user", core.BrandLark)
-	if len(larkScopes) != 0 {
-		t.Errorf("expected empty scopes for apps on Lark brand, got %d: %v", len(larkScopes), larkScopes)
-	}
-}

cmd/auth/login_interactive.go

@@ -11,7 +11,6 @@ import (
 	"github.com/charmbracelet/huh"
 
 	"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/larksuite/cli/shortcuts"
@@ -106,7 +105,7 @@ func buildDomainMeta(name, lang string) domainMeta {
 }
 
 // runInteractiveLogin shows an interactive TUI form for domain and permission selection.
-func runInteractiveLogin(ios *cmdutil.IOStreams, lang string, msg *loginMsg, brand core.LarkBrand) (*interactiveResult, error) {
+func runInteractiveLogin(ios *cmdutil.IOStreams, lang string, msg *loginMsg) (*interactiveResult, error) {
 	allDomains := getDomainMetadata(lang)
 
 	// Build multi-select options
@@ -166,7 +165,7 @@ func runInteractiveLogin(ios *cmdutil.IOStreams, lang string, msg *loginMsg, bra
 	}
 
 	// Compute scope summary
-	scopes := collectScopesForDomains(selectedDomains, "user", brand)
+	scopes := collectScopesForDomains(selectedDomains, "user")
 	if permLevel == "common" {
 		scopes = registry.FilterAutoApproveScopes(scopes)
 	}

cmd/auth/login_messages.go

@@ -59,7 +59,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 编码/解码、添加空格或标点）。",
+	AgentTimeoutHint:   "[AI agent] 此命令最长阻塞约 10 分钟，等待用户在浏览器内完成授权。请确保 runner 的 timeout >= 600s。若你的 harness 只会把最终回复发给用户，请改用 `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，导致用户授权链接失效。向用户展示授权链接时，必须逐字原样转发 CLI 返回的 URL，把它视为不可修改的 opaque string；不要做 URL 编码或解码，不要补 `%20`、空格或标点，不要改写成 Markdown 链接，建议用只包含该 URL 的代码块单独输出。",
 	AuthSuccess:        "已收到授权确认，正在获取用户信息并校验授权结果...",
 	LoginSuccess:       "授权成功! 用户: %s (%s)",
 	AuthorizedUser:     "当前授权账号: %s (%s)",
@@ -95,7 +95,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.**URL Output Rules:** Treat verification_url as an opaque string that cannot be modified. Do NOT URL-encode/decode or add spaces/punctuation.",
+	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 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. When showing the authorization URL to the user, copy the CLI-returned URL exactly as-is and treat it as an opaque string. Do not URL-encode or decode it, do not add `%20`, spaces, or punctuation, do not rewrite it as Markdown link text, and prefer a fenced code block containing only the raw URL.",
 	AuthSuccess:        "Authorization confirmed, fetching user info and validating granted scopes...",
 	LoginSuccess:       "Authorization successful! User: %s (%s)",
 	AuthorizedUser:     "Authorized account: %s (%s)",
@@ -114,7 +114,6 @@ var loginMsgEn = &loginMsg{
 	HintFooter:  "  lark-cli auth login --help",
 }
 
-// getLoginMsg returns the login message bundle for the given language.
 func getLoginMsg(lang string) *loginMsg {
 	if lang == "en" {
 		return loginMsgEn
@@ -126,5 +125,5 @@ func getLoginMsg(lang string) *loginMsg {
 // (not backed by from_meta service specs). Descriptions are now centralized in
 // service_descriptions.json.
 func getShortcutOnlyDomainNames() []string {
-	return []string{"base", "contact", "docs", "markdown", "apps"}
+	return []string{"base", "contact", "docs", "markdown"}
 }

cmd/auth/login_result.go

@@ -176,11 +176,6 @@ 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

@@ -171,7 +171,7 @@ func TestCompleteDomain_CommaSeparated(t *testing.T) {
 }
 
 func TestAllKnownDomains(t *testing.T) {
-	domains := allKnownDomains("")
+	domains := allKnownDomains()
 	if len(domains) == 0 {
 		t.Fatal("expected non-empty known domains")
 	}
@@ -185,7 +185,7 @@ func TestAllKnownDomains(t *testing.T) {
 }
 
 func TestSortedKnownDomains(t *testing.T) {
-	sorted := sortedKnownDomains("")
+	sorted := sortedKnownDomains()
 	if len(sorted) == 0 {
 		t.Fatal("expected non-empty sorted domains")
 	}
@@ -195,7 +195,7 @@ func TestSortedKnownDomains(t *testing.T) {
 	}
 
 	// Should match allKnownDomains
-	known := allKnownDomains("")
+	known := allKnownDomains()
 	if len(sorted) != len(known) {
 		t.Errorf("sorted (%d) and known (%d) length mismatch", len(sorted), len(known))
 	}
@@ -220,7 +220,7 @@ func TestCollectScopesForDomains(t *testing.T) {
 		t.Skip("no from_meta data available")
 	}
 
-	scopes := collectScopesForDomains([]string{"calendar"}, "user", "")
+	scopes := collectScopesForDomains([]string{"calendar"}, "user")
 	if len(scopes) == 0 {
 		t.Fatal("expected non-empty scopes for calendar domain")
 	}
@@ -247,7 +247,7 @@ func TestCollectScopesForDomains(t *testing.T) {
 }
 
 func TestCollectScopesForDomains_NonexistentDomain(t *testing.T) {
-	scopes := collectScopesForDomains([]string{"nonexistent_domain_xyz"}, "user", "")
+	scopes := collectScopesForDomains([]string{"nonexistent_domain_xyz"}, "user")
 	if len(scopes) != 0 {
 		t.Errorf("expected empty scopes for nonexistent domain, got %d", len(scopes))
 	}
@@ -945,19 +945,12 @@ func TestAuthLoginRun_NoWaitJSONHintIncludesRawURLGuidance(t *testing.T) {
 	}
 	hint, _ := data["hint"].(string)
 	for _, want := range []string{
-		"MUST generate QR code AND display it",
-		"lark-cli auth qrcode",
-		"Prefer PNG QR code (--output)",
-		"use ASCII (--ascii) only when the user explicitly requests it",
-		"This is a required step, do NOT skip it",
-		"CRITICAL",
-		"You MUST include the QR image in your response",
-		"Generating the file alone is NOT enough",
-		"image tags, inline images, or file attachments",
-		"Display order",
-		"place the QR code image below the URL",
+		"exactly as returned by the CLI",
 		"opaque string",
-		"cannot be modified",
+		"Do not URL-encode or decode it",
+		"do not add %20, spaces, or punctuation",
+		"do not wrap it as Markdown link text",
+		"fenced code block containing only the raw URL",
 		"final message of the turn",
 		"return control to the user",
 		"do not block on --device-code in the same turn",
@@ -1061,17 +1054,12 @@ func TestAuthLoginRun_JSONDeviceAuthorizationAgentHintIncludesRawURLGuidance(t *
 		"结束本轮",
 		"用户回复已完成授权",
 		"不要在同一轮里展示 URL 后立刻阻塞执行 --device-code",
-		"必须生成二维码并展示",
-		"lark-cli auth qrcode",
-		"优先生成 PNG 二维码（--output）",
-		"仅当用户明确要求时才使用 ASCII（--ascii）",
-		"生成后必须在回复中展示图片",
-		"仅生成文件不算完成",
-		"image 标签或内联图片",
-		"二维码图片置于 URL 下方完整展示",
-		"URL 输出规则",
+		"逐字原样转发 CLI 返回的 URL",
 		"opaque string",
-		"不要做任何修改",
+		"不要做 URL 编码或解码",
+		"不要补 `%20`、空格或标点",
+		"不要改写成 Markdown 链接",
+		"只包含该 URL 的代码块单独输出",
 	} {
 		if !strings.Contains(hint, want) {
 			t.Fatalf("agent_hint missing %q, got:\n%s", want, hint)
@@ -1089,7 +1077,7 @@ func TestGetDomainMetadata_ExcludesEvent(t *testing.T) {
 }
 
 func TestAllKnownDomains_ExcludesAuthDomainChildren(t *testing.T) {
-	domains := allKnownDomains("")
+	domains := allKnownDomains()
 	if domains["whiteboard"] {
 		t.Error("whiteboard should not appear in known auth domains (it has auth_domain=docs)")
 	}
@@ -1099,7 +1087,7 @@ func TestAllKnownDomains_ExcludesAuthDomainChildren(t *testing.T) {
 }
 
 func TestCollectScopesForDomains_ExpandsAuthDomainChildren(t *testing.T) {
-	scopes := collectScopesForDomains([]string{"docs"}, "user", "")
+	scopes := collectScopesForDomains([]string{"docs"}, "user")
 	// docs domain should include whiteboard shortcut scopes (board:whiteboard:*)
 	found := false
 	for _, s := range scopes {

cmd/auth/qrcode.go

@@ -1,142 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package auth
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"io"
-	"os"
-
-	"github.com/skip2/go-qrcode"
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/validate"
-	"github.com/larksuite/cli/internal/vfs"
-)
-
-// QRCodeOptions holds inputs for auth qrcode command.
-type QRCodeOptions struct {
-	Factory *cmdutil.Factory
-	Ctx     context.Context
-	URL     string
-	Size    int
-	ASCII   bool
-	Output  string
-}
-
-// NewCmdAuthQRCode creates the auth qrcode subcommand.
-func NewCmdAuthQRCode(f *cmdutil.Factory, runF func(*QRCodeOptions) error) *cobra.Command {
-	opts := &QRCodeOptions{Factory: f, Size: 256}
-
-	cmd := &cobra.Command{
-		Use:   "qrcode <url>",
-		Short: "Generate QR code for verification URL",
-		Long: `Generate a QR code image or ASCII representation for a verification URL.
-
-This command is designed for AI agents to generate QR codes for OAuth authorization URLs.
-
-For PNG output, the --output flag is required to specify the output file path (must be a relative path within the current directory).
-For ASCII output, the result is printed to stdout with fixed size.`,
-		Args: cobra.ExactArgs(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			opts.URL = args[0]
-			opts.Ctx = cmd.Context()
-			if runF != nil {
-				return runF(opts)
-			}
-			return runQRCode(opts)
-		},
-	}
-
-	cmd.Flags().IntVar(&opts.Size, "size", 256, "Size of the QR code image in pixels (default: 256, for PNG mode only)")
-	cmd.Flags().BoolVar(&opts.ASCII, "ascii", false, "Output ASCII QR code to stdout")
-	cmd.Flags().StringVarP(&opts.Output, "output", "o", "", "Output file path for PNG image (relative path within current directory, required for non-ASCII mode)")
-
-	return cmd
-}
-
-// runQRCode executes the auth qrcode command.
-func runQRCode(opts *QRCodeOptions) error {
-	if opts.URL == "" {
-		return output.Errorf(output.ExitValidation, "missing_url", "url is required")
-	}
-
-	if opts.ASCII {
-		var out io.Writer = os.Stdout
-		if opts.Factory != nil {
-			out = opts.Factory.IOStreams.Out
-		}
-		return generateASCIIQRCode(opts.URL, out)
-	}
-
-	if opts.Output == "" {
-		return output.Errorf(output.ExitValidation, "missing_output", "output file path is required for PNG mode. Use --output or -o flag to specify the output file path.")
-	}
-
-	if opts.Size < 32 {
-		return output.Errorf(output.ExitValidation, "invalid_size", fmt.Sprintf("size must be at least 32, got %d", opts.Size))
-	}
-
-	if opts.Size > 1024 {
-		return output.Errorf(output.ExitValidation, "invalid_size", fmt.Sprintf("size must be at most 1024, got %d", opts.Size))
-	}
-
-	safePath, err := validate.SafeOutputPath(opts.Output)
-	if err != nil {
-		return output.ErrValidation("unsafe output path: %s", err)
-	}
-
-	if err := generateImageQRCode(opts.URL, opts.Size, safePath); err != nil {
-		return err
-	}
-
-	result := map[string]interface{}{
-		"ok":        true,
-		"file_path": safePath,
-		"hint":      "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.",
-	}
-
-	var out io.Writer = os.Stdout
-	if opts.Factory != nil {
-		out = opts.Factory.IOStreams.Out
-	}
-	encoder := json.NewEncoder(out)
-	encoder.SetEscapeHTML(false)
-	if err := encoder.Encode(result); err != nil {
-		return output.Errorf(output.ExitInternal, "internal", "failed to write output: %v", err)
-	}
-
-	return nil
-}
-
-// generateImageQRCode encodes the URL as a PNG QR code and writes it to outputPath.
-func generateImageQRCode(url string, size int, outputPath string) error {
-	png, err := qrcode.Encode(url, qrcode.Medium, size)
-	if err != nil {
-		return output.Errorf(output.ExitInternal, "encode_error", fmt.Sprintf("failed to encode QR code: %v", err))
-	}
-
-	err = vfs.WriteFile(outputPath, png, 0644)
-	if err != nil {
-		return output.Errorf(output.ExitInternal, "write_error", fmt.Sprintf("failed to write QR code to %s: %v", outputPath, err))
-	}
-
-	return nil
-}
-
-// generateASCIIQRCode encodes the URL as an ASCII QR code and prints it to stdout.
-func generateASCIIQRCode(url string, w io.Writer) error {
-	q, err := qrcode.New(url, qrcode.Medium)
-	if err != nil {
-		return output.Errorf(output.ExitInternal, "encode_error", fmt.Sprintf("failed to create QR code: %v", err))
-	}
-
-	fmt.Fprint(w, q.ToSmallString(false))
-
-	return nil
-}

cmd/auth/qrcode_test.go

@@ -1,368 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package auth
-
-import (
-	"encoding/json"
-	"errors"
-	"io"
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
-)
-
-func TestNewCmdAuthQRCode_FlagParsing(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-
-	var gotOpts *QRCodeOptions
-	cmd := NewCmdAuthQRCode(f, func(opts *QRCodeOptions) error {
-		gotOpts = opts
-		return nil
-	})
-	cmd.SetArgs([]string{"https://example.com", "--output", "qr.png", "--size", "128"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if gotOpts.URL != "https://example.com" {
-		t.Errorf("URL = %q, want %q", gotOpts.URL, "https://example.com")
-	}
-	if gotOpts.Size != 128 {
-		t.Errorf("Size = %d, want %d", gotOpts.Size, 128)
-	}
-	if gotOpts.Output != "qr.png" {
-		t.Errorf("Output = %q, want %q", gotOpts.Output, "qr.png")
-	}
-	if gotOpts.ASCII {
-		t.Error("ASCII should be false by default")
-	}
-}
-
-func TestNewCmdAuthQRCode_ASCIIFlag(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-
-	var gotOpts *QRCodeOptions
-	cmd := NewCmdAuthQRCode(f, func(opts *QRCodeOptions) error {
-		gotOpts = opts
-		return nil
-	})
-	cmd.SetArgs([]string{"https://example.com", "--ascii"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if !gotOpts.ASCII {
-		t.Error("ASCII should be true when --ascii is passed")
-	}
-}
-
-func TestNewCmdAuthQRCode_DefaultSize(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-
-	var gotOpts *QRCodeOptions
-	cmd := NewCmdAuthQRCode(f, func(opts *QRCodeOptions) error {
-		gotOpts = opts
-		return nil
-	})
-	cmd.SetArgs([]string{"https://example.com", "--ascii"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if gotOpts.Size != 256 {
-		t.Errorf("default Size = %d, want 256", gotOpts.Size)
-	}
-}
-
-func TestNewCmdAuthQRCode_ExactOneArg(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-
-	cmd := NewCmdAuthQRCode(f, nil)
-	cmd.SetErr(io.Discard)
-	cmd.SetArgs([]string{})
-	if err := cmd.Execute(); err == nil {
-		t.Fatal("expected error when no URL argument provided")
-	}
-}
-
-func TestNewCmdAuthQRCode_RunE_PNGEndToEnd(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
-	tmpDir := t.TempDir()
-	oldWd, _ := os.Getwd()
-	if err := os.Chdir(tmpDir); err != nil {
-		t.Fatalf("chdir: %v", err)
-	}
-	t.Cleanup(func() { os.Chdir(oldWd) })
-
-	cmd := NewCmdAuthQRCode(f, nil)
-	cmd.SetArgs([]string{"https://example.com", "--output", "qr.png"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	data, err := os.ReadFile("qr.png")
-	if err != nil {
-		t.Fatalf("output file not created: %v", err)
-	}
-	if string(data[:4]) != "\x89PNG" {
-		t.Errorf("output does not start with PNG magic bytes, got %x", data[:4])
-	}
-
-	var result map[string]interface{}
-	if err := json.Unmarshal(stdout.Bytes(), &result); err != nil {
-		t.Fatalf("stdout is not valid JSON: %v, got: %s", err, stdout.String())
-	}
-	if result["ok"] != true {
-		t.Errorf("ok = %v, want true", result["ok"])
-	}
-	hint, _ := result["hint"].(string)
-	if hint == "" {
-		t.Error("hint is empty")
-	}
-	if !strings.Contains(hint, "MUST include") {
-		t.Errorf("hint missing 'MUST include', got: %s", hint)
-	}
-	if !strings.Contains(hint, "NOT enough") {
-		t.Errorf("hint missing 'NOT enough', got: %s", hint)
-	}
-}
-
-func TestNewCmdAuthQRCode_RunE_MissingOutput(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-
-	cmd := NewCmdAuthQRCode(f, nil)
-	cmd.SetErr(io.Discard)
-	cmd.SetArgs([]string{"https://example.com"})
-	if err := cmd.Execute(); err == nil {
-		t.Fatal("expected error when --output is missing in PNG mode")
-	}
-}
-
-func TestNewCmdAuthQRCode_HelpText(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
-
-	cmd := NewCmdAuthQRCode(f, nil)
-	cmd.SetOut(stdout)
-	cmd.SetErr(io.Discard)
-	cmd.SetArgs([]string{"--help"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	got := stdout.String()
-	for _, want := range []string{
-		"qrcode <url>",
-		"QR code",
-		"--output",
-		"--ascii",
-		"relative path",
-	} {
-		if !strings.Contains(got, want) {
-			t.Errorf("help missing %q", want)
-		}
-	}
-}
-
-func TestRunQRCode_MissingURL(t *testing.T) {
-	err := runQRCode(&QRCodeOptions{URL: ""})
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
-	}
-	if exitErr.Code != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
-	}
-	if exitErr.Detail.Type != "missing_url" {
-		t.Errorf("error type = %q, want %q", exitErr.Detail.Type, "missing_url")
-	}
-}
-
-func TestRunQRCode_MissingOutput(t *testing.T) {
-	err := runQRCode(&QRCodeOptions{URL: "https://example.com", Size: 256})
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
-	}
-	if exitErr.Code != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
-	}
-	if exitErr.Detail.Type != "missing_output" {
-		t.Errorf("error type = %q, want %q", exitErr.Detail.Type, "missing_output")
-	}
-}
-
-func TestRunQRCode_InvalidSize(t *testing.T) {
-	err := runQRCode(&QRCodeOptions{
-		URL:    "https://example.com",
-		Size:   16,
-		Output: "qr.png",
-	})
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
-	}
-	if exitErr.Code != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
-	}
-	if exitErr.Detail.Type != "invalid_size" {
-		t.Errorf("error type = %q, want %q", exitErr.Detail.Type, "invalid_size")
-	}
-}
-
-func TestRunQRCode_SizeTooLarge(t *testing.T) {
-	err := runQRCode(&QRCodeOptions{
-		URL:    "https://example.com",
-		Size:   2048,
-		Output: "qr.png",
-	})
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
-	}
-	if exitErr.Code != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
-	}
-	if exitErr.Detail.Type != "invalid_size" {
-		t.Errorf("error type = %q, want %q", exitErr.Detail.Type, "invalid_size")
-	}
-}
-
-func TestRunQRCode_UnsafeOutputPath(t *testing.T) {
-	err := runQRCode(&QRCodeOptions{
-		URL:    "https://example.com",
-		Size:   256,
-		Output: "/etc/passwd",
-	})
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
-	}
-	if exitErr.Code != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
-	}
-}
-
-func TestRunQRCode_PNGWritesFile(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
-	tmpDir := t.TempDir()
-	oldWd, _ := os.Getwd()
-	if err := os.Chdir(tmpDir); err != nil {
-		t.Fatalf("chdir: %v", err)
-	}
-	t.Cleanup(func() { os.Chdir(oldWd) })
-
-	err := runQRCode(&QRCodeOptions{
-		URL:     "https://example.com",
-		Size:    256,
-		Output:  "qr.png",
-		Factory: f,
-	})
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	info, err := os.Stat("qr.png")
-	if err != nil {
-		t.Fatalf("output file not created: %v", err)
-	}
-	if info.Size() == 0 {
-		t.Error("output file is empty")
-	}
-
-	var result map[string]interface{}
-	if jsonErr := json.Unmarshal(stdout.Bytes(), &result); jsonErr != nil {
-		t.Fatalf("stdout is not valid JSON: %v, got: %s", jsonErr, stdout.String())
-	}
-	if result["ok"] != true {
-		t.Errorf("ok = %v, want true", result["ok"])
-	}
-}
-
-func TestRunQRCode_ASCIIOutputsToStdout(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
-
-	err := runQRCode(&QRCodeOptions{
-		URL:     "https://example.com",
-		ASCII:   true,
-		Factory: f,
-	})
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	if stdout.Len() == 0 {
-		t.Error("ASCII QR code produced no output")
-	}
-}
-
-func TestGenerateImageQRCode_Success(t *testing.T) {
-	tmpDir := t.TempDir()
-	outputPath := filepath.Join(tmpDir, "test-qr.png")
-
-	if err := generateImageQRCode("https://example.com", 256, outputPath); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	data, err := os.ReadFile(outputPath)
-	if err != nil {
-		t.Fatalf("failed to read output file: %v", err)
-	}
-	if len(data) == 0 {
-		t.Error("output file is empty")
-	}
-	if len(data) < 8 {
-		t.Error("output too small to be a valid PNG")
-	}
-	if string(data[:4]) != "\x89PNG" {
-		t.Errorf("output does not start with PNG magic bytes, got %x", data[:4])
-	}
-}
-
-func TestGenerateImageQRCode_WriteError(t *testing.T) {
-	err := generateImageQRCode("https://example.com", 256, "/nonexistent/deep/nested/dir/qr.png")
-	if err == nil {
-		t.Fatal("expected error writing to nonexistent directory")
-	}
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
-	}
-	if exitErr.Code != output.ExitInternal {
-		t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitInternal)
-	}
-	if exitErr.Detail.Type != "write_error" {
-		t.Errorf("error type = %q, want %q", exitErr.Detail.Type, "write_error")
-	}
-}
-
-func TestGenerateASCIIQRCode_Success(t *testing.T) {
-	var buf strings.Builder
-	err := generateASCIIQRCode("https://example.com", &buf)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if buf.Len() == 0 {
-		t.Error("ASCII QR code produced no output")
-	}
-}
-
-func TestGenerateASCIIQRCode_EmptyString(t *testing.T) {
-	var buf strings.Builder
-	err := generateASCIIQRCode("", &buf)
-	if err == nil {
-		t.Fatal("expected error for empty string")
-	}
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
-	}
-	if exitErr.Detail.Type != "encode_error" {
-		t.Errorf("error type = %q, want %q", exitErr.Detail.Type, "encode_error")
-	}
-}

cmd/auth/status.go

@@ -5,11 +5,13 @@ package auth
 
 import (
 	"context"
+	"time"
 
 	"github.com/spf13/cobra"
 
+	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/identitydiag"
+	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
 )
 
@@ -58,83 +60,73 @@ func authStatusRun(opts *StatusOptions) error {
 		"defaultAs": defaultAs,
 	}
 
-	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)
+	if config.UserOpenId == "" {
+		result["identity"] = "bot"
+		result["note"] = "No user logged in. Only bot (tenant) identity is available for API calls. Run `lark-cli auth login` to log in."
+		output.PrintJson(f.IOStreams.Out, result)
+		return nil
+	}
+
+	stored := larkauth.GetStoredToken(config.AppID, config.UserOpenId)
+	if stored == nil {
+		result["identity"] = "bot"
+		result["userName"] = config.UserName
+		result["userOpenId"] = config.UserOpenId
+		result["note"] = "Token does not exist or has been cleared. Only bot (tenant) identity is available. Re-login: lark-cli auth login"
+		output.PrintJson(f.IOStreams.Out, result)
+		return nil
+	}
+
+	status := larkauth.TokenStatus(stored)
+	if status == "expired" {
+		result["identity"] = "bot"
+		result["note"] = "User token has expired. Only bot (tenant) identity is available. Re-login: lark-cli auth login"
+	} else {
+		result["identity"] = "user"
+	}
+	result["userName"] = config.UserName
+	result["userOpenId"] = config.UserOpenId
+	result["tokenStatus"] = status
+	result["scope"] = stored.Scope
+	result["expiresAt"] = time.UnixMilli(stored.ExpiresAt).Format(time.RFC3339)
+	result["refreshExpiresAt"] = time.UnixMilli(stored.RefreshExpiresAt).Format(time.RFC3339)
+	result["grantedAt"] = time.UnixMilli(stored.GrantedAt).Format(time.RFC3339)
+
+	// --verify: call the server to confirm token is actually usable.
+	if opts.Verify && status != "expired" {
+		verified, verifyErr := verifyTokenOnServer(f, config)
+		result["verified"] = verified
+		if verifyErr != "" {
+			result["verifyError"] = verifyErr
+		}
+	}
 
 	output.PrintJson(f.IOStreams.Out, result)
 	return nil
 }
 
-const (
-	identityUser = "user"
-	identityBot  = "bot"
-	identityNone = "none"
-)
+// verifyTokenOnServer obtains a valid access token (refreshing if needed)
+// and calls /authen/v1/user_info to confirm the server accepts it.
+// Returns (true, "") on success or (false, reason) on failure.
+func verifyTokenOnServer(f *cmdutil.Factory, config *core.CliConfig) (bool, string) {
+	httpClient, err := f.HttpClient()
+	if err != nil {
+		return false, "failed to create HTTP client: " + err.Error()
+	}
 
-func effectiveIdentity(d identitydiag.Result) string {
-	switch {
-	case d.User.Available:
-		return identityUser
-	case d.Bot.Available:
-		return identityBot
-	default:
-		return identityNone
+	token, err := larkauth.GetValidAccessToken(httpClient, larkauth.NewUATCallOptions(config, f.IOStreams.ErrOut))
+	if err != nil {
+		return false, "token unusable: " + err.Error()
 	}
-}
 
-func addLegacyUserFields(result map[string]interface{}, user identitydiag.Identity) {
-	if user.OpenID == "" {
-		return
+	sdk, err := f.LarkClient()
+	if err != nil {
+		return false, "failed to create SDK client: " + err.Error()
 	}
-	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:
-		if d.User.Verified != nil {
-			result["verified"] = *d.User.Verified
-			if !*d.User.Verified {
-				result["verifyError"] = d.User.Message
-			}
-		}
-	case identityBot:
-		if d.Bot.Verified != nil {
-			result["verified"] = *d.Bot.Verified
-			if !*d.Bot.Verified {
-				result["verifyError"] = d.Bot.Message
-			}
-		}
+	if err := larkauth.VerifyUserToken(context.Background(), sdk, token); err != nil {
+		return false, "server rejected token: " + err.Error()
 	}
-}
 
-func addStatusNote(result map[string]interface{}, d identitydiag.Result) {
-	switch {
-	case !d.User.Available && d.Bot.Available:
-		result["note"] = "User identity is " + identitydiag.StatusMessage(d.User.Status) + "; bot identity is ready for bot/tenant API calls. Run `lark-cli auth login` to enable user identity."
-	case d.User.Status == identitydiag.StatusNeedsRefresh:
-		result["note"] = "User identity needs refresh and will be refreshed automatically on the next user API call."
-	case !d.User.Available && !d.Bot.Available:
-		result["note"] = "No usable identity is available. Configure bot credentials or run `lark-cli auth login`."
-	}
+	return true, ""
 }

cmd/auth/status_test.go

@@ -1,96 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package auth
-
-import (
-	"encoding/json"
-	"net/http"
-	"testing"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/httpmock"
-)
-
-func TestAuthStatusRun_SplitsBotAndUserIdentity(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "secret", Brand: core.BrandFeishu,
-	})
-
-	if err := authStatusRun(&StatusOptions{Factory: f}); err != nil {
-		t.Fatalf("authStatusRun() error = %v", err)
-	}
-
-	var got statusOutput
-	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
-		t.Fatalf("json.Unmarshal() error = %v", err)
-	}
-	if got.Identity != "bot" {
-		t.Fatalf("identity = %q, want bot", got.Identity)
-	}
-	if got.Identities.Bot.Status != "ready" || !got.Identities.Bot.Available {
-		t.Fatalf("bot = %#v, want ready and available", got.Identities.Bot)
-	}
-	if got.Identities.User.Status != "missing" || got.Identities.User.Available {
-		t.Fatalf("user = %#v, want missing and unavailable", got.Identities.User)
-	}
-}
-
-func TestAuthStatusRun_VerifyReportsBotIdentity(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "secret", Brand: core.BrandFeishu,
-	})
-	reg.Register(&httpmock.Stub{
-		Method: http.MethodGet,
-		URL:    "/open-apis/bot/v3/info",
-		Body: map[string]interface{}{
-			"code": 0,
-			"msg":  "ok",
-			"bot": map[string]interface{}{
-				"open_id":  "ou_bot",
-				"app_name": "diagnostic bot",
-			},
-		},
-	})
-
-	if err := authStatusRun(&StatusOptions{Factory: f, Verify: true}); err != nil {
-		t.Fatalf("authStatusRun() error = %v", err)
-	}
-
-	var got statusOutput
-	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
-		t.Fatalf("json.Unmarshal() error = %v", err)
-	}
-	if got.Identity != "bot" {
-		t.Fatalf("identity = %q, want bot", got.Identity)
-	}
-	if got.Verified == nil || !*got.Verified {
-		t.Fatalf("verified = %v, want true", got.Verified)
-	}
-	if got.Identities.Bot.Verified == nil || !*got.Identities.Bot.Verified {
-		t.Fatalf("bot verified = %v, want true", got.Identities.Bot.Verified)
-	}
-	if got.Identities.Bot.OpenID != "ou_bot" {
-		t.Fatalf("bot open id = %q, want ou_bot", got.Identities.Bot.OpenID)
-	}
-	if got.Identities.User.Status != "missing" {
-		t.Fatalf("user status = %q, want missing", got.Identities.User.Status)
-	}
-}
-
-type statusOutput struct {
-	Identity   string `json:"identity"`
-	Verified   *bool  `json:"verified"`
-	Identities struct {
-		Bot  statusIdentity `json:"bot"`
-		User statusIdentity `json:"user"`
-	} `json:"identities"`
-}
-
-type statusIdentity struct {
-	Status    string `json:"status"`
-	Available bool   `json:"available"`
-	Verified  *bool  `json:"verified"`
-	OpenID    string `json:"openId"`
-}

cmd/config/bind_test.go

@@ -13,45 +13,30 @@ 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/output"
 )
 
-// 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.
+// assertExitError checks the full structured error in one assertion.
 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) {
-		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 !errors.As(err, &exitErr) {
+		t.Fatalf("error type = %T, want *output.ExitError; error = %v", err, err)
 	}
-	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
+	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)
 	}
-	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
@@ -610,10 +595,8 @@ func TestConfigShowRun_AgentWorkspaceNotBound(t *testing.T) {
 	if !errors.As(err, &cfgErr) {
 		t.Fatalf("error type = %T, want *core.ConfigError", err)
 	}
-	// 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.Code != output.ExitValidation {
+		t.Errorf("exit code = %d, want %d", cfgErr.Code, output.ExitValidation)
 	}
 	if cfgErr.Type != "openclaw" {
 		t.Errorf("type = %q, want %q", cfgErr.Type, "openclaw")

cmd/config/config.go

@@ -33,7 +33,6 @@ 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

@@ -95,9 +95,8 @@ func TestConfigShowRun_NotConfiguredReturnsStructuredError(t *testing.T) {
 	if !errors.As(err, &cfgErr) {
 		t.Fatalf("error type = %T, want *core.ConfigError", err)
 	}
-	// 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.Code != output.ExitValidation {
+		t.Fatalf("exit code = %d, want %d", cfgErr.Code, output.ExitValidation)
 	}
 	if cfgErr.Type != "config" || cfgErr.Message != "not configured" {
 		t.Fatalf("detail = %+v, want config/not configured", cfgErr)

cmd/config/init.go

@@ -352,7 +352,6 @@ 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

cmd/config/keychain_downgrade.go

@@ -1,73 +0,0 @@
-// 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

@@ -1,28 +0,0 @@
-// 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/doctor/doctor.go

@@ -14,10 +14,10 @@ import (
 
 	"github.com/spf13/cobra"
 
+	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/build"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/identitydiag"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/update"
 )
@@ -51,7 +51,7 @@ func NewCmdDoctor(f *cmdutil.Factory) *cobra.Command {
 // checkResult represents one diagnostic check.
 type checkResult struct {
 	Name    string `json:"name"`
-	Status  string `json:"status"` // "pass", "warn", "fail", "skip"
+	Status  string `json:"status"` // "pass", "fail", "skip"
 	Message string `json:"message"`
 	Hint    string `json:"hint,omitempty"`
 }
@@ -118,31 +118,59 @@ func doctorRun(opts *DoctorOptions) error {
 
 	ep := core.ResolveEndpoints(cfg.Brand)
 
-	// ── 3. Identity readiness ──
-	diagnostics := identitydiag.Diagnose(opts.Ctx, f, cfg, !opts.Offline)
-	checks = append(checks,
-		identityCheck("bot_identity", diagnostics.Bot),
-		identityCheck("user_identity", diagnostics.User),
-	)
-	if diagnostics.Bot.Available || diagnostics.User.Available {
-		checks = append(checks, pass("identity_ready", "at least one identity is available"))
-	} else {
-		checks = append(checks, fail("identity_ready", "no usable bot or user identity is available", "run: lark-cli auth status --verify"))
+	// ── 3. Token exists ──
+	if cfg.UserOpenId == "" {
+		checks = append(checks, fail("token_exists", "no user logged in", "run: lark-cli auth login --help"))
+		checks = append(checks, networkChecks(opts.Ctx, opts, ep)...)
+		return finishDoctor(f, checks)
+	}
+	stored := larkauth.GetStoredToken(cfg.AppID, cfg.UserOpenId)
+	if stored == nil {
+		checks = append(checks, fail("token_exists", "no token in keychain for "+cfg.UserOpenId, "run: lark-cli auth login --help"))
+		checks = append(checks, networkChecks(opts.Ctx, opts, ep)...)
+		return finishDoctor(f, checks)
+	}
+	checks = append(checks, pass("token_exists", fmt.Sprintf("token found for %s (%s)", cfg.UserName, cfg.UserOpenId)))
+
+	// ── 4. Token local validity ──
+	status := larkauth.TokenStatus(stored)
+	switch status {
+	case "valid":
+		checks = append(checks, pass("token_local", "token valid, expires "+time.UnixMilli(stored.ExpiresAt).Format(time.RFC3339)))
+	case "needs_refresh":
+		checks = append(checks, pass("token_local", "token needs refresh (will auto-refresh on next call)"))
+	default: // expired
+		checks = append(checks, fail("token_local", "token expired", "run: lark-cli auth login --help"))
+		checks = append(checks, networkChecks(opts.Ctx, opts, ep)...)
+		return finishDoctor(f, checks)
 	}
 
-	// ── 4 & 5. Endpoint reachability ──
+	// ── 5. Token server verification ──
+	if opts.Offline {
+		checks = append(checks, skip("token_verified", "skipped (--offline)"))
+	} else {
+		httpClient := mustHTTPClient(f)
+		token, err := larkauth.GetValidAccessToken(httpClient, larkauth.NewUATCallOptions(cfg, f.IOStreams.ErrOut))
+		if err != nil {
+			checks = append(checks, fail("token_verified", "cannot obtain valid token: "+err.Error(), "run: lark-cli auth login --help"))
+		} else {
+			sdk, err := f.LarkClient()
+			if err != nil {
+				checks = append(checks, fail("token_verified", "SDK init failed: "+err.Error(), ""))
+			} else if err := larkauth.VerifyUserToken(opts.Ctx, sdk, token); err != nil {
+				checks = append(checks, fail("token_verified", "server rejected token: "+err.Error(), "run: lark-cli auth login --help"))
+			} else {
+				checks = append(checks, pass("token_verified", "server confirmed token is valid"))
+			}
+		}
+	}
+
+	// ── 6 & 7. Endpoint reachability ──
 	checks = append(checks, networkChecks(opts.Ctx, opts, ep)...)
 
 	return finishDoctor(f, checks)
 }
 
-func identityCheck(name string, id identitydiag.Identity) checkResult {
-	if id.Available {
-		return pass(name, id.Message)
-	}
-	return warn(name, id.Message, id.Hint)
-}
-
 // networkChecks probes Open API and MCP endpoints concurrently.
 func networkChecks(ctx context.Context, opts *DoctorOptions, ep core.Endpoints) []checkResult {
 	if opts.Offline {
@@ -204,6 +232,15 @@ func probeEndpoint(ctx context.Context, client *http.Client, url string) error {
 	return nil
 }
 
+// mustHTTPClient returns f.HttpClient() or a default client.
+func mustHTTPClient(f *cmdutil.Factory) *http.Client {
+	c, err := f.HttpClient()
+	if err != nil {
+		return &http.Client{Timeout: 30 * time.Second}
+	}
+	return c
+}
+
 // checkCLIUpdate actively queries the npm registry for the latest version.
 // Unlike the root-level async check, this does a synchronous fetch with timeout
 // and works regardless of build version (dev builds included).

cmd/doctor/doctor_test.go

@@ -95,59 +95,3 @@ func TestNetworkChecks_Offline(t *testing.T) {
 		}
 	}
 }
-
-func TestDoctorRun_SplitsBotAndMissingUserIdentity(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	if err := core.SaveMultiAppConfig(&core.MultiAppConfig{
-		CurrentApp: "default",
-		Apps: []core.AppConfig{
-			{
-				Name:      "default",
-				AppId:     "test-app",
-				AppSecret: core.PlainSecret("secret"),
-				Brand:     core.BrandFeishu,
-			},
-		},
-	}); err != nil {
-		t.Fatalf("SaveMultiAppConfig() error = %v", err)
-	}
-
-	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "secret", Brand: core.BrandFeishu,
-	})
-	err := doctorRun(&DoctorOptions{
-		Factory: f,
-		Ctx:     context.Background(),
-		Offline: true,
-	})
-	if err != nil {
-		t.Fatalf("doctorRun() error = %v", err)
-	}
-
-	var got struct {
-		OK     bool          `json:"ok"`
-		Checks []checkResult `json:"checks"`
-	}
-	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
-		t.Fatalf("json.Unmarshal() error = %v", err)
-	}
-	if !got.OK {
-		t.Fatalf("ok = false, want true; checks = %#v", got.Checks)
-	}
-	assertCheck(t, got.Checks, "bot_identity", "pass")
-	assertCheck(t, got.Checks, "user_identity", "warn")
-	assertCheck(t, got.Checks, "identity_ready", "pass")
-}
-
-func assertCheck(t *testing.T, checks []checkResult, name, status string) {
-	t.Helper()
-	for _, check := range checks {
-		if check.Name == name {
-			if check.Status != status {
-				t.Fatalf("%s status = %q, want %q", name, check.Status, status)
-			}
-			return
-		}
-	}
-	t.Fatalf("check %q not found in %#v", name, checks)
-}

cmd/error_auth_hint.go

@@ -4,13 +4,9 @@
 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"
@@ -18,49 +14,12 @@ import (
 	"github.com/larksuite/cli/internal/registry"
 	"github.com/larksuite/cli/shortcuts"
 	shortcutcommon "github.com/larksuite/cli/shortcuts/common"
+	"github.com/spf13/cobra"
 )
 
-// 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.
+// enrichMissingScopeError preserves the original need_user_authorization
+// message and appends a scope hint when the current command declares the
+// required scopes locally.
 func enrichMissingScopeError(f *cmdutil.Factory, exitErr *output.ExitError) {
 	if exitErr == nil || exitErr.Detail == nil {
 		return
@@ -68,10 +27,12 @@ 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 := r.client.CheckResponse(result, r.accessIdentity); apiErr != nil {
+	if apiErr := client.CheckLarkResponse(result); apiErr != nil {
 		return json.RawMessage(resp.RawBody), apiErr
 	}
 	return json.RawMessage(resp.RawBody), nil

cmd/platform_guards.go

@@ -36,13 +36,6 @@ 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
@@ -82,12 +75,6 @@ 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
@@ -129,12 +116,6 @@ 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"
@@ -162,12 +143,6 @@ 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"
@@ -219,13 +194,6 @@ 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/prune.go

@@ -105,10 +105,6 @@ 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

@@ -10,13 +10,14 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"net/url"
 	"os"
 	"sort"
 	"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,52 +200,22 @@ 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 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
+	// 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
 	if errors.As(err, &spErr) {
 		writeSecurityPolicyError(errOut, spErr)
 		return 1
 	}
 
-	// *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)
-	}
-
+	// All other structured errors normalize to ExitError.
 	if exitErr := asExitError(err); exitErr != nil {
 		if !exitErr.Raw {
-			// Raw errors (e.g. from `api` command via output.MarkRaw)
-			// preserve the original API error detail; skip enrichment
-			// which would clear it.
+			// Raw errors (e.g. from `api` command) preserve the original API
+			// error detail; skip enrichment which would clear it.
 			enrichMissingScopeError(f, exitErr)
 			enrichPermissionError(f, exitErr)
 		}
@@ -252,21 +223,35 @@ 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
 }
 
-// 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) {
+// 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) {
 	var codeStr string
-	switch spErr.Subtype {
-	case errs.SubtypeChallengeRequired:
+	switch spErr.Code {
+	case internalauth.LarkErrBlockByPolicyTryAuth:
 		codeStr = "challenge_required"
-	case errs.SubtypeAccessDenied:
+	case internalauth.LarkErrBlockByPolicy:
 		codeStr = "access_denied"
 	default:
 		codeStr = strconv.Itoa(spErr.Code)
@@ -281,8 +266,8 @@ func writeSecurityPolicyError(w io.Writer, spErr *errs.SecurityPolicyError) {
 	if spErr.ChallengeURL != "" {
 		errData["challenge_url"] = spErr.ChallengeURL
 	}
-	if spErr.Hint != "" {
-		errData["hint"] = spErr.Hint
+	if spErr.CLIHint != "" {
+		errData["hint"] = spErr.CLIHint
 	}
 
 	env := map[string]interface{}{"ok": false, "error": errData}
@@ -291,29 +276,15 @@ func writeSecurityPolicyError(w io.Writer, spErr *errs.SecurityPolicyError) {
 	encoder := json.NewEncoder(buffer)
 	encoder.SetEscapeHTML(false)
 	encoder.SetIndent("", "  ")
-	if encErr := encoder.Encode(env); encErr != nil {
+	err := encoder.Encode(env)
+
+	if err != 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.
 //
@@ -336,13 +307,6 @@ 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()
@@ -417,22 +381,16 @@ func installTipsHelpFunc(root *cobra.Command) {
 	})
 }
 
-// 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.
+// 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
 func enrichPermissionError(f *cmdutil.Factory, exitErr *output.ExitError) {
 	if exitErr.Detail == nil || exitErr.Detail.Type != "permission" {
 		return
 	}
-	// Extract required scopes from API error detail (shared helper)
-	scopes := registry.ExtractRequiredScopes(exitErr.Detail.Detail)
+	// Extract required scopes from API error detail
+	scopes := extractRequiredScopes(exitErr.Detail.Detail)
 	if len(scopes) == 0 {
 		return
 	}
@@ -443,18 +401,31 @@ func enrichPermissionError(f *cmdutil.Factory, exitErr *output.ExitError) {
 	}
 
 	// Select the recommended (least-privilege) scope
-	recommended := registry.SelectRecommendedScopeFromStrings(scopes, "tenant")
+	scopeIfaces := make([]interface{}, len(scopes))
+	for i, s := range scopes {
+		scopeIfaces[i] = s
+	}
+	recommended := registry.SelectRecommendedScope(scopeIfaces, "tenant")
+	if recommended == "" {
+		recommended = scopes[0]
+	}
 
 	// Build admin console URL with the recommended scope
-	consoleURL := registry.BuildConsoleScopeURL(cfg.Brand, cfg.AppID, recommended)
+	host := "open.feishu.cn"
+	if cfg.Brand == "lark" {
+		host = "open.larksuite.com"
+	}
+	consoleURL := fmt.Sprintf("https://%s/page/scope-apply?clientID=%s&scopes=%s", host, url.QueryEscape(cfg.AppID), url.QueryEscape(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)"
@@ -464,11 +435,13 @@ 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)"
@@ -479,3 +452,26 @@ func enrichPermissionError(f *cmdutil.Factory, exitErr *output.ExitError) {
 		exitErr.Detail.ConsoleURL = consoleURL
 	}
 }
+
+// extractRequiredScopes extracts scope names from the API error's permission_violations field.
+func extractRequiredScopes(detail interface{}) []string {
+	m, ok := detail.(map[string]interface{})
+	if !ok {
+		return nil
+	}
+	violations, ok := m["permission_violations"].([]interface{})
+	if !ok {
+		return nil
+	}
+	var scopes []string
+	for _, v := range violations {
+		vm, ok := v.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		if subject, ok := vm["subject"].(string); ok {
+			scopes = append(scopes, subject)
+		}
+	}
+	return scopes
+}

cmd/root_integration_test.go

@@ -161,8 +161,160 @@ 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)
@@ -372,7 +524,7 @@ func TestIntegration_Shortcut_BusinessError_OutputsEnvelope(t *testing.T) {
 		"im", "+messages-send", "--as", "bot", "--chat-id", "oc_xxx", "--text", "test",
 	})
 
-	// shortcut: typed error via DoAPIJSON path
+	// shortcut: no MarkRaw, no HandleResponse — error via DoAPIJSON path
 	assertEnvelope(t, code, output.ExitAPI, stdout, stderr, output.ErrorEnvelope{
 		OK:       false,
 		Identity: "bot",
@@ -384,8 +536,11 @@ func TestIntegration_Shortcut_BusinessError_OutputsEnvelope(t *testing.T) {
 	})
 }
 
-// TestSetupNotices_ColdStart_NoNotice verifies that missing state
-// produces no skills key in the composed notice.
+// 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.
 func TestSetupNotices_ColdStart_NoNotice(t *testing.T) {
 	clearNoticeEnv(t)
 	dir := t.TempDir()
@@ -416,13 +571,13 @@ func TestSetupNotices_ColdStart_NoNotice(t *testing.T) {
 	}
 }
 
-// TestSetupNotices_InSync verifies that matching state produces no
+// TestSetupNotices_InSync verifies that a matching stamp 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.WriteState(skillscheck.SkillsState{Version: "1.0.21"}); err != nil {
+	if err := skillscheck.WriteStamp("1.0.21"); err != nil {
 		t.Fatal(err)
 	}
 
@@ -449,13 +604,13 @@ func TestSetupNotices_InSync(t *testing.T) {
 	}
 }
 
-// TestSetupNotices_Drift verifies mismatching state produces the
+// TestSetupNotices_Drift verifies a mismatching stamp 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.WriteState(skillscheck.SkillsState{Version: "1.0.20"}); err != nil {
+	if err := skillscheck.WriteStamp("1.0.20"); err != nil {
 		t.Fatal(err)
 	}
 
@@ -504,7 +659,7 @@ func TestSetupNotices_BothUpdateAndSkills(t *testing.T) {
 	clearNoticeEnv(t)
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.20"}); err != nil {
+	if err := skillscheck.WriteStamp("1.0.20"); err != nil {
 		t.Fatal(err)
 	}
 

cmd/root_test.go

@@ -4,23 +4,19 @@
 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
@@ -72,6 +68,273 @@ 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)
@@ -133,227 +396,3 @@ 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,7 +14,6 @@ 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"
 )
@@ -25,8 +24,7 @@ type SchemaOptions struct {
 	Ctx     context.Context
 
 	// Positional args
-	Path      string   // first positional, when only one is given
-	ExtraArgs []string // 2nd+ positional args (space-separated form)
+	Path string
 
 	// Flags
 	Format string
@@ -361,16 +359,13 @@ func NewCmdSchema(f *cmdutil.Factory, runF func(*SchemaOptions) error) *cobra.Co
 	opts := &SchemaOptions{Factory: f}
 
 	cmd := &cobra.Command{
-		Use:   "schema [path | service resource method]",
+		Use:   "schema [path]",
 		Short: "View API method parameters, types, and scopes",
-		Args:  cobra.MaximumNArgs(8),
+		Args:  cobra.MaximumNArgs(1),
 		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)
@@ -385,108 +380,60 @@ 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, cmdutil.RiskRead)
+	cmdutil.SetRisk(cmd, "read")
 
 	return cmd
 }
 
 // completeSchemaPath provides tab-completion for the schema path argument.
-// It handles both legacy dotted resource names (e.g. app.table.fields) and the
-// newer space-separated form (e.g. `schema im messages reply`).
+// It handles dotted resource names (e.g. app.table.fields) by iterating all
+// resources and classifying each as a prefix-match or fully-matched.
 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) {
-		mode := f.ResolveStrictMode(cmd.Context())
-
-		// 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
-				}
-			}
-			directive := cobra.ShellCompDirectiveNoFileComp
-			if allTrailingDot {
-				directive |= cobra.ShellCompDirectiveNoSpace
-			}
-			return completions, directive
+		if len(args) > 0 {
+			return nil, cobra.ShellCompDirectiveNoFileComp
 		}
 
-		// Case 2: space-form, args already has segments
-		// Walk down service -> resource(s) -> method based on existing args
-		serviceName := args[0]
+		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+".")
+				}
+			}
+			return completions, cobra.ShellCompDirectiveNoFileComp | cobra.ShellCompDirectiveNoSpace
+		}
+
+		serviceName := parts[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
 		}
 
-		// 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)
+		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
 			}
 		}
-		sort.Strings(completions)
-		return completions, cobra.ShellCompDirectiveNoFileComp
+		directive := cobra.ShellCompDirectiveNoFileComp
+		if allTrailingDot {
+			directive |= cobra.ShellCompDirectiveNoSpace
+		}
+		return completions, directive
 	}
 }
 
@@ -522,231 +469,94 @@ func schemaRun(opts *SchemaOptions) error {
 	out := opts.Factory.IOStreams.Out
 	mode := opts.Factory.ResolveStrictMode(opts.Ctx)
 
-	// 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}
-	}
-	if len(opts.ExtraArgs) > 0 {
-		if opts.Path != "" {
-			rawArgs = append([]string{opts.Path}, opts.ExtraArgs...)
-		} else {
-			rawArgs = append([]string(nil), opts.ExtraArgs...)
-		}
-	}
-	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 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 {
-		// 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 {
+	if opts.Path == "" {
 		printServices(out)
 		return nil
 	}
+
+	parts := strings.Split(opts.Path, ".")
+
 	serviceName := parts[0]
 	spec := registry.LoadFromMeta(serviceName)
 	if spec == nil {
-		return errUnknownService(serviceName)
+		return output.ErrWithHint(output.ExitValidation, "validation",
+			fmt.Sprintf("Unknown service: %s", serviceName),
+			fmt.Sprintf("Available: %s", strings.Join(registry.ListFromMetaProjects(), ", ")))
 	}
+
 	if len(parts) == 1 {
-		printResourceList(out, spec, mode)
+		if opts.Format == "pretty" {
+			printResourceList(out, spec, mode)
+		} else {
+			output.PrintJson(out, filterSpecByStrictMode(spec, mode))
+		}
 		return nil
 	}
+
 	resources, _ := spec["resources"].(map[string]interface{})
 	resource, resName, remaining := findResourceByPath(resources, parts[1:])
 	if resource == nil {
-		var names []string
+		var resNames []string
 		for k := range resources {
-			names = append(names, k)
+			resNames = append(resNames, 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, ", ")))
+			fmt.Sprintf("Available: %s", strings.Join(resNames, ", ")))
 	}
+
 	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)
+		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)
+			}
 		}
-		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 names []string
+		var mNames []string
 		for k := range methods {
-			names = append(names, k)
+			mNames = append(mNames, 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, ", ")))
+			fmt.Sprintf("Available: %s", strings.Join(mNames, ", ")))
 	}
-	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:], ".")))
+
+	if opts.Format == "pretty" {
+		printMethodDetail(out, spec, resName, methodName, method)
+	} else {
+		output.PrintJson(out, method)
 	}
-	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,7 +5,6 @@ package schema
 
 import (
 	"bytes"
-	"encoding/json"
 	"strings"
 	"testing"
 
@@ -34,165 +33,17 @@ func TestSchemaCmd_FlagParsing(t *testing.T) {
 	}
 }
 
-func TestSchemaCmd_NoArgs_Pretty(t *testing.T) {
+func TestSchemaCmd_NoArgs(t *testing.T) {
 	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
 
 	cmd := NewCmdSchema(f, nil)
-	cmd.SetArgs([]string{"--format", "pretty"})
-	if err := cmd.Execute(); err != nil {
+	cmd.SetArgs([]string{})
+	err := cmd.Execute()
+	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
 	if !strings.Contains(stdout.String(), "Available services") {
-		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)
-		}
+		t.Error("expected service list output")
 	}
 }
 

cmd/service/service.go

@@ -271,11 +271,6 @@ 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 {
@@ -285,7 +280,7 @@ func serviceMethodRun(opts *ServiceMethodOptions) error {
 
 	resp, err := ac.DoAPI(opts.Ctx, request)
 	if err != nil {
-		return err
+		return output.ErrNetwork("API call failed: %s", err)
 	}
 	return client.HandleResponse(resp, client.ResponseOptions{
 		OutputPath:  opts.Output,
@@ -295,56 +290,10 @@ 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 {
@@ -390,7 +339,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.
@@ -525,10 +474,36 @@ func serviceDryRun(f *cmdutil.Factory, request client.RawApiRequest, config *cor
 	return cmdutil.PrintDryRun(f.IOStreams.Out, request, config, format)
 }
 
-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
+// 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{}) error) error {
 	// When jq is set, always aggregate all pages then filter.
 	if jqExpr != "" {
 		return client.PaginateWithJq(ctx, ac, request, jqExpr, out, pagOpts, checkErr)
@@ -541,9 +516,9 @@ func servicePaginate(ctx context.Context, ac *client.APIClient, request client.R
 			pf.FormatPage(items)
 		}, pagOpts)
 		if err != nil {
-			return err
+			return output.ErrNetwork("API call failed: %s", err)
 		}
-		if apiErr := checkErr(result, pagOpts.Identity); apiErr != nil {
+		if apiErr := checkErr(result); apiErr != nil {
 			return apiErr
 		}
 		if !hasItems {
@@ -554,9 +529,9 @@ func servicePaginate(ctx context.Context, ac *client.APIClient, request client.R
 	default:
 		result, err := ac.PaginateAll(ctx, request, pagOpts)
 		if err != nil {
-			return err
+			return output.ErrNetwork("API call failed: %s", err)
 		}
-		if apiErr := checkErr(result, pagOpts.Identity); apiErr != nil {
+		if apiErr := checkErr(result); apiErr != nil {
 			return apiErr
 		}
 		output.FormatValue(out, result, format)

cmd/service/service_test.go

@@ -11,6 +11,7 @@ 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"
 )
 
@@ -411,6 +412,39 @@ 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,
@@ -628,6 +662,73 @@ 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{} {
@@ -765,3 +866,13 @@ 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,18 +31,15 @@ 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 state comparison.
+// normalizeVersion canonicalizes a version string for stamp 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 {
-	s = strings.TrimSpace(s)
-	s = strings.TrimPrefix(s, "v")
-	return strings.TrimPrefix(s, "V")
+	return strings.TrimPrefix(strings.TrimSpace(s), "v")
 }
 
 func releaseURL(version string) string {
@@ -124,9 +121,7 @@ func updateRun(opts *UpdateOptions) error {
 	cur := currentVersion()
 	updater := newUpdater()
 
-	if !opts.Check {
-		updater.CleanupStaleFiles()
-	}
+	updater.CleanupStaleFiles()
 	output.PendingNotice = nil
 
 	// 1. Fetch latest version
@@ -142,9 +137,13 @@ func updateRun(opts *UpdateOptions) error {
 
 	// 3. Compare versions
 	if !opts.Force && !update.IsNewer(latest, cur) {
-		var skillsResult *skillscheck.SyncResult
+		// 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
 		if !opts.Check {
-			skillsResult = runSkillsAndState(updater, io, cur, opts.Force)
+			skillsResult = runSkillsAndStamp(updater, io, cur, opts.Force)
 		}
 		return reportAlreadyUpToDate(opts, io, cur, latest, skillsResult, opts.Check)
 	}
@@ -186,7 +185,16 @@ 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(),
 		}
-		applySkillsStatus(out, cur)
+		// 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,
+			}
+		}
 		output.PrintJson(io.Out, out)
 		return nil
 	}
@@ -202,7 +210,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 := runSkillsAndState(updater, io, cur, opts.Force)
+	skillsResult := runSkillsAndStamp(updater, io, cur, opts.Force)
 
 	reason := detect.ManualReason()
 	if opts.JSON {
@@ -280,7 +288,10 @@ func doNpmUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string,
 		return output.ErrBare(output.ExitAPI)
 	}
 
-	skillsResult := runSkillsAndState(updater, io, latest, opts.Force)
+	// 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)
 
 	if opts.JSON {
 		result := map[string]interface{}{
@@ -317,21 +328,27 @@ 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))
 }
 
-func runSkillsAndState(updater *selfupdate.Updater, io *cmdutil.IOStreams, stateVersion string, force bool) *skillscheck.SyncResult {
+// 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 {
 	if !force {
-		if existing, ok := skillscheck.ReadSyncedVersion(); ok && normalizeVersion(existing) == normalizeVersion(stateVersion) {
+		if existing, _ := skillscheck.ReadStamp(); normalizeVersion(existing) == normalizeVersion(stampVersion) {
 			return nil
 		}
 	}
-	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)
+	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)
+		}
 	}
-	return result
+	return r
 }
 
 // reportAlreadyUpToDate emits the JSON / pretty output for the
@@ -339,7 +356,7 @@ func runSkillsAndState(updater *selfupdate.Updater, io *cmdutil.IOStreams, state
 // 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 *skillscheck.SyncResult, check bool) error {
+func reportAlreadyUpToDate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, skillsResult *selfupdate.NpmResult, check bool) error {
 	if opts.JSON {
 		out := map[string]interface{}{
 			"ok": true, "previous_version": cur, "current_version": cur,
@@ -347,7 +364,16 @@ func reportAlreadyUpToDate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, late
 			"message": fmt.Sprintf("lark-cli %s is already up to date", cur),
 		}
 		if check {
-			applySkillsStatus(out, cur)
+			// 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,
+				}
+			}
 		} else {
 			applySkillsResult(out, skillsResult)
 		}
@@ -361,70 +387,36 @@ func reportAlreadyUpToDate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, late
 	return nil
 }
 
-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) {
+// 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) {
 	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)
-		env["skills_summary"] = skillsSummary(r)
+		if detail := strings.TrimSpace(r.Stderr.String()); detail != "" {
+			env["skills_detail"] = selfupdate.Truncate(detail, maxNpmOutput)
+		}
 	default:
 		env["skills_action"] = "synced"
-		env["skills_summary"] = skillsSummary(r)
 	}
 }
 
-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) {
+// emitSkillsTextHints prints human-readable feedback about the skills
+// sync result for non-JSON output.
+func emitSkillsTextHints(io *cmdutil.IOStreams, r *selfupdate.NpmResult) {
 	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 len(r.Failed) > 0 {
-			fmt.Fprintf(io.ErrOut, "  Failed skills: %s\n", strings.Join(r.Failed, ", "))
+		if detail := strings.TrimSpace(r.Stderr.String()); detail != "" {
+			fmt.Fprintf(io.ErrOut, "  %s\n", selfupdate.Truncate(detail, maxStderrDetail))
 		}
-		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))
+		fmt.Fprintf(io.ErrOut, "  Run manually: npx -y skills add larksuite/cli -g -y\n")
 	default:
-		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")
-		}
+		fmt.Fprintf(io.ErrOut, "%s Skills updated\n", symOK())
 	}
 }

cmd/update/update_test.go

@@ -5,14 +5,13 @@ package cmdupdate
 
 import (
 	"bytes"
-	"context"
 	"encoding/json"
 	"errors"
 	"fmt"
-	"os/exec"
+	"os"
+	"path/filepath"
 	"strings"
 	"testing"
-	"time"
 
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
@@ -29,6 +28,7 @@ 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,53 +41,22 @@ 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) {
+func mockDetectAndNpm(t *testing.T, result selfupdate.DetectResult,
+	npmFn func(string) *selfupdate.NpmResult,
+	skillsFn func() *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)
 
@@ -199,7 +168,9 @@ func TestUpdateManual_Human(t *testing.T) {
 }
 
 func TestUpdateNpm_JSON(t *testing.T) {
-	// Isolate config dir because skills sync writes skills-state.json.
+	// 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".
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 
 	f, stdout, _ := newTestFactory(t)
@@ -215,6 +186,7 @@ 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()
@@ -244,6 +216,7 @@ 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()
@@ -257,7 +230,7 @@ func TestUpdateNpm_Human(t *testing.T) {
 }
 
 func TestUpdateForce_JSON(t *testing.T) {
-	// Same state-isolation rationale as TestUpdateNpm_JSON.
+	// Same stamp-isolation rationale as TestUpdateNpm_JSON.
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 
 	f, stdout, _ := newTestFactory(t)
@@ -273,6 +246,7 @@ 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()
@@ -349,7 +323,7 @@ func TestUpdateInvalidVersion_JSON(t *testing.T) {
 }
 
 func TestUpdateDevVersion_JSON(t *testing.T) {
-	// Same state-isolation rationale as TestUpdateNpm_JSON.
+	// Same stamp-isolation rationale as TestUpdateNpm_JSON.
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 
 	f, stdout, _ := newTestFactory(t)
@@ -365,6 +339,7 @@ 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()
@@ -476,8 +451,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.SkillsCommandOverride = func(args ...string) *selfupdate.NpmResult {
-			t.Fatal("skills sync should not run when binary verification fails")
+		u.SkillsUpdateOverride = func() *selfupdate.NpmResult {
+			t.Fatal("skills update should not run when binary verification fails")
 			return nil
 		}
 		return u
@@ -674,7 +649,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 state-isolation rationale as TestUpdateNpm_JSON.
+	// Same stamp-isolation rationale as TestUpdateNpm_JSON.
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 
 	f, stdout, _ := newTestFactory(t)
@@ -693,6 +668,7 @@ 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()
@@ -774,6 +750,7 @@ 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()
@@ -808,7 +785,8 @@ func TestUpdateNpm_SkillsFail_JSON(t *testing.T) {
 		}
 		u.NpmInstallOverride = func(version string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} }
 		u.VerifyOverride = func(string) error { return nil }
-		u.SkillsCommandOverride = func(args ...string) *selfupdate.NpmResult {
+		// Skills update fails
+		u.SkillsUpdateOverride = func() *selfupdate.NpmResult {
 			r := &selfupdate.NpmResult{}
 			r.Stderr.WriteString("npx: command not found")
 			r.Err = fmt.Errorf("exit status 127")
@@ -834,8 +812,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_summary") {
-		t.Errorf("expected skills_summary in output, got: %s", out)
+	if !strings.Contains(out, "skills_detail") {
+		t.Errorf("expected skills_detail in output, got: %s", out)
 	}
 }
 
@@ -860,7 +838,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.SkillsCommandOverride = func(args ...string) *selfupdate.NpmResult {
+		u.SkillsUpdateOverride = func() *selfupdate.NpmResult {
 			r := &selfupdate.NpmResult{}
 			r.Stderr.WriteString("npx: command not found")
 			r.Err = fmt.Errorf("exit status 127")
@@ -883,96 +861,100 @@ 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, "lark-cli update --force") {
-		t.Errorf("expected force retry hint, got: %s", out)
+	if !strings.Contains(out, "npx -y skills add") {
+		t.Errorf("expected manual skills command hint, got: %s", out)
 	}
 }
 
-// newTestIO returns a cmdutil.IOStreams backed by bytes.Buffers.
+// newTestIO returns a cmdutil.IOStreams backed by bytes.Buffers, suitable
+// for direct calls to internals like runSkillsAndStamp that write to
+// io.ErrOut.
 func newTestIO() *cmdutil.IOStreams {
 	return cmdutil.NewIOStreams(&bytes.Buffer{}, &bytes.Buffer{}, &bytes.Buffer{})
 }
 
-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 {
+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 {
 		t.Fatal(err)
 	}
 	called := false
 	updater := &selfupdate.Updater{
-		SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
+		SkillsUpdateOverride: func() *selfupdate.NpmResult {
 			called = true
 			return &selfupdate.NpmResult{}
 		},
 	}
-	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false)
+	got := runSkillsAndStamp(updater, newTestIO(), "1.0.21", false)
 	if got != nil {
-		t.Errorf("runSkillsAndState() = %+v, want nil for dedup hit", got)
+		t.Errorf("runSkillsAndStamp() = %+v, want nil for dedup hit", got)
 	}
 	if called {
-		t.Error("SkillsCommandOverride called, want skipped due to dedup")
+		t.Error("SkillsUpdateOverride called, want skipped due to dedup")
 	}
 }
 
-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 {
+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 {
 		t.Fatal(err)
 	}
 	called := false
 	updater := &selfupdate.Updater{
-		SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
+		SkillsUpdateOverride: func() *selfupdate.NpmResult {
 			called = true
-			return successfulSkillsCommand()(args...)
+			return &selfupdate.NpmResult{}
 		},
 	}
-	got := runSkillsAndState(updater, newTestIO(), "1.0.21", true)
-	if got == nil || got.Err != nil {
-		t.Fatalf("runSkillsAndState(force=true) = %+v, want successful result", got)
+	got := runSkillsAndStamp(updater, newTestIO(), "1.0.21", true)
+	if got == nil {
+		t.Fatal("runSkillsAndStamp(force=true) = nil, want non-nil")
 	}
 	if !called {
-		t.Error("SkillsCommandOverride not called with force=true")
+		t.Error("SkillsUpdateOverride not called with force=true")
 	}
 }
 
-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)
+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)
 	if got == nil || got.Err != nil {
-		t.Fatalf("runSkillsAndState() = %+v, want non-nil with nil Err", got)
+		t.Fatalf("runSkillsAndStamp() = %+v, want non-nil with nil Err", got)
 	}
-	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)
+	stamp, _ := skillscheck.ReadStamp()
+	if stamp != "1.0.21" {
+		t.Errorf("stamp = %q, want \"1.0.21\"", stamp)
 	}
 }
 
-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 {
+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 {
 		t.Fatal(err)
 	}
 	updater := &selfupdate.Updater{
-		SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
+		SkillsUpdateOverride: func() *selfupdate.NpmResult {
 			r := &selfupdate.NpmResult{}
 			r.Err = fmt.Errorf("npx failed")
 			return r
 		},
 	}
-	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false)
+	got := runSkillsAndStamp(updater, newTestIO(), "1.0.21", false)
 	if got == nil || got.Err == nil {
-		t.Fatalf("runSkillsAndState() = %+v, want non-nil with non-nil Err", got)
+		t.Fatalf("runSkillsAndStamp() = %+v, want non-nil with non-nil Err", got)
 	}
-	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)
+	stamp, _ := skillscheck.ReadStamp()
+	if stamp != "1.0.20" {
+		t.Errorf("stamp = %q, want \"1.0.20\" (failure must not overwrite)", stamp)
 	}
 }
 
@@ -991,7 +973,8 @@ func TestTruncate(t *testing.T) {
 }
 
 func TestUpdateRun_AlreadyLatest_RunsSkillsSync(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 
 	origFetch := fetchLatest
 	origCur := currentVersion
@@ -1004,9 +987,9 @@ func TestUpdateRun_AlreadyLatest_RunsSkillsSync(t *testing.T) {
 	t.Cleanup(func() { newUpdater = origNew })
 	newUpdater = func() *selfupdate.Updater {
 		return &selfupdate.Updater{
-			SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
+			SkillsUpdateOverride: func() *selfupdate.NpmResult {
 				skillsCalled = true
-				return successfulSkillsCommand()(args...)
+				return &selfupdate.NpmResult{}
 			},
 		}
 	}
@@ -1017,19 +1000,17 @@ func TestUpdateRun_AlreadyLatest_RunsSkillsSync(t *testing.T) {
 		t.Fatalf("updateRun() err = %v, want nil", err)
 	}
 	if !skillsCalled {
-		t.Error("skills sync not called in already-up-to-date branch")
+		t.Error("RunSkillsUpdate not called in already-up-to-date branch (cold stamp), want called")
 	}
-	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)
+	stamp, _ := skillscheck.ReadStamp()
+	if stamp != "1.0.21" {
+		t.Errorf("stamp = %q, want \"1.0.21\"", stamp)
 	}
 }
 
 func TestUpdateRun_Manual_RunsSkillsSync(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 
 	origFetch := fetchLatest
 	origCur := currentVersion
@@ -1048,9 +1029,9 @@ func TestUpdateRun_Manual_RunsSkillsSync(t *testing.T) {
 					ResolvedPath: "/usr/local/bin/lark-cli",
 				}
 			},
-			SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
+			SkillsUpdateOverride: func() *selfupdate.NpmResult {
 				skillsCalled = true
-				return successfulSkillsCommand()(args...)
+				return &selfupdate.NpmResult{}
 			},
 		}
 	}
@@ -1061,19 +1042,17 @@ func TestUpdateRun_Manual_RunsSkillsSync(t *testing.T) {
 		t.Fatalf("updateRun() err = %v, want nil", err)
 	}
 	if !skillsCalled {
-		t.Error("skills sync not called in manual branch")
+		t.Error("RunSkillsUpdate not called in manual branch, want called")
 	}
-	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)
+	stamp, _ := skillscheck.ReadStamp()
+	if stamp != "1.0.21" {
+		t.Errorf("stamp = %q, want \"1.0.21\" (manual path stamps cur)", stamp)
 	}
 }
 
-func TestUpdateRun_Npm_RunsSkillsSync_WritesLatestState(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+func TestUpdateRun_Npm_RunsSkillsSync_StampsLatest(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 
 	origFetch := fetchLatest
 	origCur := currentVersion
@@ -1096,9 +1075,9 @@ func TestUpdateRun_Npm_RunsSkillsSync_WritesLatestState(t *testing.T) {
 				return &selfupdate.NpmResult{}
 			},
 			VerifyOverride: func(expectedVersion string) error { return nil },
-			SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
+			SkillsUpdateOverride: func() *selfupdate.NpmResult {
 				skillsCalled = true
-				return successfulSkillsCommand()(args...)
+				return &selfupdate.NpmResult{}
 			},
 		}
 	}
@@ -1109,25 +1088,18 @@ func TestUpdateRun_Npm_RunsSkillsSync_WritesLatestState(t *testing.T) {
 		t.Fatalf("updateRun() err = %v, want nil", err)
 	}
 	if !skillsCalled {
-		t.Error("skills sync not called in npm branch")
+		t.Error("RunSkillsUpdate not called in npm branch")
 	}
-	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)
+	stamp, _ := skillscheck.ReadStamp()
+	if stamp != "1.0.22" {
+		t.Errorf("stamp = %q, want \"1.0.22\" (npm path stamps latest)", stamp)
 	}
 }
 
 func TestUpdateRun_CheckIncludesSkillsStatus(t *testing.T) {
-	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 {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := skillscheck.WriteStamp("1.0.20"); err != nil {
 		t.Fatal(err)
 	}
 
@@ -1145,9 +1117,9 @@ func TestUpdateRun_CheckIncludesSkillsStatus(t *testing.T) {
 			DetectOverride: func() selfupdate.DetectResult {
 				return selfupdate.DetectResult{Method: selfupdate.InstallNpm, NpmAvailable: true}
 			},
-			SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
+			SkillsUpdateOverride: func() *selfupdate.NpmResult {
 				skillsCalled = true
-				return successfulSkillsCommand()(args...)
+				return &selfupdate.NpmResult{}
 			},
 		}
 	}
@@ -1158,7 +1130,7 @@ func TestUpdateRun_CheckIncludesSkillsStatus(t *testing.T) {
 		t.Fatalf("updateRun(--check) err = %v, want nil", err)
 	}
 	if skillsCalled {
-		t.Error("skills sync called under --check, want skipped")
+		t.Error("RunSkillsUpdate called under --check, want skipped (pure report)")
 	}
 
 	var env map[string]interface{}
@@ -1172,14 +1144,12 @@ 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) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.20"}); err != nil {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := skillscheck.WriteStamp("1.0.20"); err != nil {
 		t.Fatal(err)
 	}
 
@@ -1194,9 +1164,9 @@ func TestUpdateRun_CheckAlreadyLatest_NoSideEffect(t *testing.T) {
 	t.Cleanup(func() { newUpdater = origNew })
 	newUpdater = func() *selfupdate.Updater {
 		return &selfupdate.Updater{
-			SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
+			SkillsUpdateOverride: func() *selfupdate.NpmResult {
 				skillsCalled = true
-				return successfulSkillsCommand()(args...)
+				return &selfupdate.NpmResult{}
 			},
 		}
 	}
@@ -1207,15 +1177,12 @@ func TestUpdateRun_CheckAlreadyLatest_NoSideEffect(t *testing.T) {
 		t.Fatalf("updateRun(--check, already-latest) err = %v, want nil", err)
 	}
 	if skillsCalled {
-		t.Error("skills sync called under --check (already-latest), want skipped")
+		t.Error("RunSkillsUpdate called under --check (already-latest), want skipped (pure report)")
 	}
 
-	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)
+	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)
 	}
 
 	var env map[string]interface{}
@@ -1237,248 +1204,39 @@ func TestUpdateRun_CheckAlreadyLatest_NoSideEffect(t *testing.T) {
 	}
 }
 
-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")}
+// 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)
 	}
-	t.Cleanup(func() { syncSkills = origSync })
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", badPath)
 
 	f, _, stderr := newTestFactory(t)
-	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)
+	updater := &selfupdate.Updater{
+		SkillsUpdateOverride: func() *selfupdate.NpmResult {
+			return &selfupdate.NpmResult{} // success
+		},
 	}
-	if !strings.Contains(stderr.String(), "warning: skills synced but state not written") {
+	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") {
 		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, &skillscheck.SyncResult{Official: []string{"lark-calendar"}, Updated: []string{"lark-calendar"}})
+	emitSkillsTextHints(f.IOStreams, &selfupdate.NpmResult{}) // Err==nil → success
 	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

@@ -1,558 +0,0 @@
-# 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

@@ -1,19 +0,0 @@
-// 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

@@ -1,31 +0,0 @@
-// 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

@@ -1,37 +0,0 @@
-// 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

@@ -1,11 +0,0 @@
-// 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

@@ -1,235 +0,0 @@
-// 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

@@ -1,88 +0,0 @@
-// 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

@@ -1,203 +0,0 @@
-// 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

@@ -1,38 +0,0 @@
-// 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

@@ -1,72 +0,0 @@
-// 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

@@ -1,75 +0,0 @@
-// 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

@@ -1,21 +0,0 @@
-// 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

@@ -1,136 +0,0 @@
-// 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

@@ -1,154 +0,0 @@
-// 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

@@ -1,27 +0,0 @@
-// 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

@@ -1,49 +0,0 @@
-// 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

@@ -1,116 +0,0 @@
-// 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

@@ -1,353 +0,0 @@
-// 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

@@ -1,33 +0,0 @@
-// 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

@@ -1,42 +0,0 @@
-// 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,17 +6,13 @@ 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 in this phase.
+// Mail is intentionally omitted: only IM is wired up this phase.
 func init() {
 	all := [][]event.KeyDefinition{
 		im.Keys(),
-		minutes.Keys(),
-		vc.Keys(),
 	}
 	for _, keys := range all {
 		for _, k := range keys {

events/vc/participant_meeting_ended.go

@@ -1,77 +0,0 @@
-// 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

@@ -1,203 +0,0 @@
-// 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

@@ -1,33 +0,0 @@
-// 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

@@ -1,43 +0,0 @@
-// 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"
-)
-
-// 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},
-		},
-	}
-}

events/vc/test_helpers_test.go

@@ -1,30 +0,0 @@
-// 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)
-	}
-}

go.mod

@@ -11,7 +11,6 @@ require (
 	github.com/google/uuid v1.6.0
 	github.com/itchyny/gojq v0.12.17
 	github.com/larksuite/oapi-sdk-go/v3 v3.5.4
-	github.com/sergi/go-diff v1.4.0
 	github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e
 	github.com/smartystreets/goconvey v1.8.1
 	github.com/spf13/cobra v1.10.2
@@ -20,7 +19,6 @@ require (
 	github.com/tidwall/gjson v1.18.0
 	github.com/zalando/go-keyring v0.2.8
 	golang.org/x/net v0.33.0
-	golang.org/x/sync v0.15.0
 	golang.org/x/sys v0.33.0
 	golang.org/x/term v0.27.0
 	golang.org/x/text v0.23.0
@@ -63,4 +61,5 @@ require (
 	github.com/tidwall/match v1.1.1 // indirect
 	github.com/tidwall/pretty v1.2.0 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
+	golang.org/x/sync v0.15.0 // indirect
 )

go.sum

@@ -45,7 +45,6 @@ github.com/creack/pty v1.1.24 h1:bJrF4RRfyJnbTJqzRLHzcGaZK1NeM5kTC9jGgovnR1s=
 github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE=
 github.com/danieljoos/wincred v1.2.3 h1:v7dZC2x32Ut3nEfRH+vhoZGvN72+dQ/snVXo/vMFLdQ=
 github.com/danieljoos/wincred v1.2.3/go.mod h1:6qqX0WNrS4RzPZ1tnroDzq9kY3fu1KwE7MRLQK4X0bs=
-github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
@@ -74,11 +73,6 @@ github.com/jtolds/gls v4.20.0+incompatible h1:xdiiI2gbIgH/gLH7ADydsJ1uDOEzR8yvV7
 github.com/jtolds/gls v4.20.0+incompatible/go.mod h1:QJZ7F/aHp+rZTRtaJ1ow/lLfFfVYBRgL+9YlvaHOwJU=
 github.com/kisielk/errcheck v1.5.0/go.mod h1:pFxgyoBC7bSaBwPgfKdkLd5X25qrDl4LWUI2bnpBCr8=
 github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck=
-github.com/kr/pretty v0.1.0 h1:L/CwN0zerZDmRFUapSPitk6f+Q3+0za1rQkzVuMiMFI=
-github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
-github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
-github.com/kr/text v0.1.0 h1:45sCR5RtlFHMR4UwH9sdQ5TC8v0qDQCHnXt+kaKSTVE=
-github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
 github.com/larksuite/oapi-sdk-go/v3 v3.5.4 h1:U2S9x9LrfH++ZqJ+YAiUlqzCWJmVXhFdS8Z7rIBH8H0=
 github.com/larksuite/oapi-sdk-go/v3 v3.5.4/go.mod h1:ZEplY+kwuIrj/nqw5uSCINNATcH3KdxSN7y+UxYY5fI=
 github.com/lucasb-eyer/go-colorful v1.2.0 h1:1nnpGOrhyZZuNyfu1QjKiUICQ74+3FNCN69Aj6K7nkY=
@@ -103,8 +97,6 @@ github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJ
 github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
 github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
-github.com/sergi/go-diff v1.4.0 h1:n/SP9D5ad1fORl+llWyN+D6qoUETXNZARKjyY2/KVCw=
-github.com/sergi/go-diff v1.4.0/go.mod h1:A0bzQcvG0E7Rwjx0REVgAGH58e96+X0MeOfepqsbeW4=
 github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e h1:MRM5ITcdelLK2j1vwZ3Je0FKVCfqOLp5zO6trqMLYs0=
 github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e/go.mod h1:XV66xRDqSt+GTGFMVlhk3ULuV0y9ZmzeVGR4mloJI3M=
 github.com/smarty/assertions v1.15.0 h1:cR//PqUBUiQRakZWqBiFFQ9wb8emQGDb0HeGdqGByCY=
@@ -115,10 +107,8 @@ github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
 github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
 github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
 github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
-github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
 github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
-github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/tidwall/gjson v1.18.0 h1:FIDeeyB800efLX89e5a8Y0BNH+LOngJyGrIWxG2FKQY=
@@ -173,10 +163,7 @@ golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8T
 golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 h1:YR8cESwS4TdDjEe65xsg0ogRM/Nc3DYOhEAlW+xobZo=
-gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
-gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

internal/auth/errors.go

@@ -8,14 +8,21 @@ 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,
@@ -44,7 +51,6 @@ 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)
@@ -52,7 +58,24 @@ func IsNeedUserAuthorizationError(err error) bool {
 	return strings.Contains(err.Error(), needUserAuthorizationMarker)
 }
 
-// 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
+// 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
+}

internal/auth/transport.go

@@ -12,8 +12,6 @@ import (
 	"net/url"
 	"strings"
 
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/errclass"
 	"github.com/larksuite/cli/internal/util"
 )
 
@@ -87,56 +85,34 @@ func (t *SecurityPolicyTransport) RoundTrip(req *http.Request) (*http.Response,
 	return resp, nil
 }
 
-// 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`.
+// tryHandleMCPResponse attempts to parse a JSON-RPC (MCP) formatted error response.
 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
 	}
 
-	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 {
+	code := getInt(errMap, "code", 0)
+	if code != LarkErrBlockByPolicyTryAuth && code != LarkErrBlockByPolicy {
 		return nil
 	}
 
-	if dataMap == nil {
+	dataMap, ok := errMap["data"].(map[string]interface{})
+	if !ok {
 		return nil
 	}
 
 	// Clean up backticks and spaces from challenge_url
 	challengeUrl := strings.Trim(getStr(dataMap, "challenge_url"), " `")
-	// Read `hint` first; fall back to `cli_hint` so either spelling surfaces.
-	cliHint := getStr(dataMap, "hint")
-	if cliHint == "" {
-		cliHint = getStr(dataMap, "cli_hint")
-	}
+	cliHint := getStr(dataMap, "cli_hint")
 	msg := getStr(errMap, "message")
 
 	if challengeUrl != "" || cliHint != "" {
@@ -146,15 +122,11 @@ func (t *SecurityPolicyTransport) tryHandleMCPResponse(result map[string]interfa
 		}
 
 		if challengeUrl != "" || cliHint != "" {
-			return &errs.SecurityPolicyError{
-				Problem: errs.Problem{
-					Category: errs.CategoryPolicy,
-					Subtype:  meta.Subtype,
-					Code:     code,
-					Message:  msg,
-					Hint:     cliHint,
-				},
+			return &SecurityPolicyError{
+				Code:         code,
+				Message:      msg,
 				ChallengeURL: challengeUrl,
+				CLIHint:      cliHint,
 			}
 		}
 	}
@@ -174,9 +146,8 @@ func (t *SecurityPolicyTransport) tryHandleOAPIResponse(result map[string]interf
 		}
 	}
 
-	// 2. Check if it's a security policy error (consult central code registry)
-	meta, ok := errclass.LookupCodeMeta(code)
-	if !ok || meta.Category != errs.CategoryPolicy {
+	// 2. Check if it's a security policy error
+	if code != LarkErrBlockByPolicyTryAuth && code != LarkErrBlockByPolicy {
 		return nil
 	}
 
@@ -202,15 +173,11 @@ func (t *SecurityPolicyTransport) tryHandleOAPIResponse(result map[string]interf
 		}
 
 		if msg != "" || challengeUrl != "" || cliHint != "" {
-			return &errs.SecurityPolicyError{
-				Problem: errs.Problem{
-					Category: errs.CategoryPolicy,
-					Subtype:  meta.Subtype,
-					Code:     code,
-					Message:  msg,
-					Hint:     cliHint,
-				},
+			return &SecurityPolicyError{
+				Code:         code,
+				Message:      msg,
 				ChallengeURL: challengeUrl,
+				CLIHint:      cliHint,
 			}
 		}
 	}

internal/auth/transport_test.go

@@ -1,114 +0,0 @@
-// 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,9 +18,7 @@ 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"
 )
 
@@ -225,21 +223,16 @@ func doRefreshToken(httpClient *http.Client, opts UATCallOptions, stored *Stored
 	}
 
 	code := getInt(data, "code", -1)
-	meta, metaOK := errclass.LookupCodeMeta(code)
-	if metaOK && meta.Category == errs.CategoryPolicy {
+	if code == LarkErrBlockByPolicy || code == LarkErrBlockByPolicyTryAuth {
 		challengeUrl := getStr(data, "challenge_url")
 		cliHint := getStr(data, "cli_hint")
 		msg := getStr(data, "error_description")
 
-		return nil, &errs.SecurityPolicyError{
-			Problem: errs.Problem{
-				Category: errs.CategoryPolicy,
-				Subtype:  meta.Subtype,
-				Code:     code,
-				Message:  msg,
-				Hint:     cliHint,
-			},
+		return nil, &SecurityPolicyError{
+			Code:         code,
+			Message:      msg,
 			ChallengeURL: challengeUrl,
+			CLIHint:      cliHint,
 		}
 	}
 
@@ -247,7 +240,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 metaOK && meta.Category == errs.CategoryAuthentication && meta.Retryable {
+		if RefreshTokenRetryable[code] {
 			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,7 +11,6 @@ import (
 	"io"
 	"strings"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/output"
 )
 
@@ -20,31 +19,10 @@ 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)
@@ -54,11 +32,6 @@ 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,15 +6,31 @@ 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 {
@@ -50,127 +66,3 @@ 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,28 +91,12 @@ 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 {
-		// 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)
+		return nil, err
 	}
 	if as.IsBot() {
 		req.SupportedAccessTokenTypes = []larkcore.AccessTokenType{larkcore.AccessTokenTypeTenant}
@@ -123,11 +107,7 @@ func (c *APIClient) DoSDKRequest(ctx context.Context, req *larkcore.ApiReq, as c
 	}
 
 	opts = append(opts, extraOpts...)
-	resp, err := c.SDK.Do(ctx, req, opts...)
-	if err != nil {
-		return nil, WrapDoAPIError(err)
-	}
-	return resp, nil
+	return c.SDK.Do(ctx, req, opts...)
 }
 
 // DoStream executes a streaming HTTP request against the Lark OpenAPI endpoint.
@@ -143,10 +123,7 @@ func (c *APIClient) DoStream(ctx context.Context, req *larkcore.ApiReq, as core.
 	// Resolve auth
 	token, err := c.resolveAccessToken(ctx, as)
 	if err != nil {
-		// 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)
+		return nil, err
 	}
 
 	// Build URL
@@ -282,27 +259,14 @@ 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).
-//
-// 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.
+// CallAPI is a convenience wrapper: DoAPI + ParseJSONResponse.
+// Use DoAPI directly when the response may not be JSON (e.g. file downloads).
 func (c *APIClient) CallAPI(ctx context.Context, request RawApiRequest) (interface{}, error) {
 	resp, err := c.DoAPI(ctx, request)
 	if err != nil {
 		return nil, err
 	}
-	result, parseErr := ParseJSONResponse(resp)
-	if parseErr != nil {
-		return nil, WrapJSONResponseParseError(parseErr, resp.RawBody)
-	}
-	return result, nil
+	return ParseJSONResponse(resp)
 }
 
 // paginateLoop runs the core pagination loop. For each successful page (code == 0),
@@ -446,14 +410,10 @@ func (c *APIClient) StreamPages(ctx context.Context, request RawApiRequest, onIt
 	return map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{}}, false, nil
 }
 
-// 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 {
+// 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 {
 	resultMap, ok := result.(map[string]interface{})
 	if !ok || resultMap == nil {
 		return nil

internal/client/client_test.go

@@ -45,6 +45,12 @@ 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()
@@ -428,118 +434,42 @@ func TestDoStream_IgnoresBaseHTTPClientTimeout(t *testing.T) {
 	}
 }
 
-// failingTokenResolver always returns TokenUnavailableError, exercising the
-// auth/credential failure path through resolveAccessToken.
-type failingTokenResolver struct{}
+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)
 
-func (f *failingTokenResolver) ResolveToken(_ context.Context, spec credential.TokenSpec) (*credential.TokenResult, error) {
-	return nil, &credential.TokenUnavailableError{Source: "test", Type: spec.Type}
+	_, 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)
+	}
 }
 
-// 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) {
+func TestDoStream_MissingTokenReturnsAuthError(t *testing.T) {
 	ac := &APIClient{
 		HTTP:       &http.Client{},
-		Credential: credential.NewCredentialProvider(nil, nil, &failingTokenResolver{}, nil),
+		Credential: credential.NewCredentialProvider(nil, nil, &missingTokenResolver{}, nil),
 		Config:     &core.CliConfig{AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu},
 	}
 
-	_, err := ac.DoSDKRequest(context.Background(), &larkcore.ApiReq{
+	_, err := ac.DoStream(context.Background(), &larkcore.ApiReq{
 		HttpMethod: http.MethodGet,
-		ApiPath:    "/open-apis/contact/v3/users/me",
-	}, core.AsUser)
-
-	if err == nil {
-		t.Fatal("expected auth error, got nil")
-	}
-	var exitErr *output.ExitError
-	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",
+		ApiPath:    "https://example.com/open-apis/test",
 	}, core.AsBot)
-
 	if err == nil {
-		t.Fatal("expected error from broken transport, got nil")
+		t.Fatal("DoStream() error = nil, want auth error")
 	}
 	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)
+	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)
 	}
 }

internal/client/pagination.go

@@ -8,38 +8,25 @@ 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
-	Identity  core.Identity // identity passed to checkErr; defaults to AsUser when empty
+	PageLimit int // max pages to fetch; 0 = unlimited (default: 10)
+	PageDelay int // ms, default 200
 }
 
 // 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{}, core.Identity) error) error {
+	checkErr func(interface{}) error) error {
 	result, err := ac.PaginateAll(ctx, request, pagOpts)
 	if err != nil {
-		return err
+		return output.ErrNetwork("API call failed: %v", err)
 	}
-	// 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 {
+	if apiErr := checkErr(result); apiErr != nil {
 		output.FormatValue(out, result, output.FormatJSON)
 		return apiErr
 	}

internal/client/response.go

@@ -15,7 +15,6 @@ 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"
 )
@@ -31,13 +30,8 @@ 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
-	// 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
+	// CheckError is called on parsed JSON results. Nil defaults to CheckLarkResponse.
+	CheckError func(interface{}) error
 }
 
 // HandleResponse routes a raw *larkcore.ApiResp to the appropriate output:
@@ -46,21 +40,9 @@ 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 {
-		// 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)
-		}
+		check = CheckLarkResponse
 	}
 
 	// Non-JSON error responses (e.g. 404 text/plain from gateway): return error directly
@@ -76,7 +58,7 @@ func HandleResponse(resp *larkcore.ApiResp, opts ResponseOptions) error {
 		if err != nil {
 			return WrapJSONResponseParseError(err, resp.RawBody)
 		}
-		if apiErr := check(result, identity); apiErr != nil {
+		if apiErr := check(result); apiErr != nil {
 			return apiErr
 		}
 		// Content safety scanning

internal/client/response_test.go

@@ -234,6 +234,37 @@ 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()
@@ -393,3 +424,17 @@ 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,13 +130,6 @@ 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,13 +19,6 @@ 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,
@@ -34,7 +27,7 @@ func RequireConfirmation(action string) error {
 			Message: fmt.Sprintf("%s requires confirmation", action),
 			Hint:    "add --yes to confirm",
 			Risk: &output.RiskDetail{
-				Level:  RiskHighRiskWrite,
+				Level:  "high-risk-write",
 				Action: action,
 			},
 		},

internal/cmdutil/identity_flag_test.go

@@ -5,7 +5,6 @@ package cmdutil
 
 import (
 	"context"
-	"strings"
 	"testing"
 
 	"github.com/larksuite/cli/internal/core"
@@ -67,49 +66,3 @@ func TestAddShortcutIdentityFlag_NoDefault(t *testing.T) {
 		t.Fatalf("default value = %q, want empty string", got)
 	}
 }
-
-// TC-10: AuthTypes=["user"] → usage contains "identity type: user" and NOT "bot".
-func TestAddShortcutIdentityFlag_UserOnlyAuthTypes(t *testing.T) {
-	f, _, _, _ := TestFactory(t, &core.CliConfig{AppID: "a", AppSecret: "s"})
-	cmd := &cobra.Command{Use: "test"}
-
-	AddShortcutIdentityFlag(context.Background(), cmd, f, []string{"user"})
-
-	flag := cmd.Flags().Lookup("as")
-	if flag == nil {
-		t.Fatal("expected --as flag to be registered")
-	}
-	if flag.Hidden {
-		t.Fatal("expected --as flag to be visible")
-	}
-	wantUsage := "identity type: user"
-	if flag.Usage != wantUsage {
-		t.Errorf("Usage = %q, want %q", flag.Usage, wantUsage)
-	}
-	if strings.Contains(flag.Usage, "bot") {
-		t.Errorf("Usage should not contain \"bot\" for user-only shortcut, got %q", flag.Usage)
-	}
-}
-
-// TC-11: AuthTypes=["user","bot"] → usage == "identity type: user | bot".
-func TestAddShortcutIdentityFlag_UserBotAuthTypes(t *testing.T) {
-	f, _, _, _ := TestFactory(t, &core.CliConfig{AppID: "a", AppSecret: "s"})
-	cmd := &cobra.Command{Use: "test"}
-
-	AddShortcutIdentityFlag(context.Background(), cmd, f, []string{"user", "bot"})
-
-	flag := cmd.Flags().Lookup("as")
-	if flag == nil {
-		t.Fatal("expected --as flag to be registered")
-	}
-	if flag.Hidden {
-		t.Fatal("expected --as flag to be visible")
-	}
-	if got := flag.DefValue; got != "" {
-		t.Fatalf("default value = %q, want empty string", got)
-	}
-	wantUsage := "identity type: user | bot"
-	if flag.Usage != wantUsage {
-		t.Errorf("Usage = %q, want %q", flag.Usage, wantUsage)
-	}
-}

internal/cmdutil/risk.go

@@ -7,20 +7,11 @@ 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: RiskRead |
-// RiskWrite | RiskHighRiskWrite. Framework-level confirmation gating only
-// acts on RiskHighRiskWrite.
+// shortcuts/common. Levels follow the three-tier convention: "read" | "write"
+// | "high-risk-write". Framework-level confirmation gating only acts on
+// "high-risk-write".
 func SetRisk(cmd *cobra.Command, level string) {
 	if level == "" {
 		return

internal/core/config.go

@@ -236,7 +236,7 @@ func ResolveConfigFromMulti(raw *MultiAppConfig, kc keychain.KeychainAccess, pro
 	app := raw.CurrentAppConfig(profileOverride)
 	if app == nil {
 		return nil, &ConfigError{
-			Code:    3,
+			Code:    2,
 			Type:    "config",
 			Message: fmt.Sprintf("profile %q not found", profileOverride),
 			Hint:    fmt.Sprintf("available profiles: %s", formatProfileNames(raw.ProfileNames())),
@@ -244,19 +244,20 @@ func ResolveConfigFromMulti(raw *MultiAppConfig, kc keychain.KeychainAccess, pro
 	}
 
 	if err := ValidateSecretKeyMatch(app.AppId, app.AppSecret); err != nil {
-		return nil, &ConfigError{Code: 3, Type: "config",
+		return nil, &ConfigError{Code: 2, Type: "config",
 			Message: "appId and appSecret keychain key are out of sync",
 			Hint:    err.Error()}
 	}
 
 	secret, err := ResolveSecretInput(app.AppSecret, kc)
 	if err != nil {
-		// Deprecated: legacy *output.ExitError passthrough; removed after typed migration.
+		// 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.
 		var exitErr *output.ExitError
 		if errors.As(err, &exitErr) {
 			return nil, exitErr
 		}
-		return nil, &ConfigError{Code: 3, Type: "config", Message: err.Error()}
+		return nil, &ConfigError{Code: 2, Type: "config", Message: err.Error()}
 	}
 	cfg := &CliConfig{
 		ProfileName: app.ProfileName(),

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: 3 (config errors share the auth exit code)
+	Code    int    // exit code: 2=validation, 3=auth
 	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:    3,
+			Code:    2,
 			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:    3,
+			Code:    2,
 			Type:    "config",
 			Message: "not configured",
 			Hint:    localInitHint,
 		}
 	}
 	return &ConfigError{
-		Code:    3,
+		Code:    2,
 		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:    3,
+			Code:    2,
 			Type:    "config",
 			Message: "no active profile",
 			Hint:    localInitHint,
 		}
 	}
 	return &ConfigError{
-		Code:    3,
+		Code:    2,
 		Type:    ws.Display(),
 		Message: fmt.Sprintf("no active profile in %s workspace", ws.Display()),
 		Hint:    agentBindHint,

internal/errclass/classify.go

@@ -1,284 +0,0 @@
-// 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

@@ -1,747 +0,0 @@
-// 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

@@ -1,87 +0,0 @@
-// 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

@@ -1,24 +0,0 @@
-// 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

@@ -1,105 +0,0 @@
-// 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

@@ -1,32 +0,0 @@
-// 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

@@ -1,37 +0,0 @@
-// 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,13 +199,6 @@ 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/identitydiag/diagnostics.go

@@ -1,325 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package identitydiag
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"io"
-	"net/http"
-	"strings"
-	"time"
-
-	larkauth "github.com/larksuite/cli/internal/auth"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/credential"
-)
-
-const (
-	StatusReady         = "ready"
-	StatusNotConfigured = "not_configured"
-	StatusMissing       = "missing"
-	StatusNeedsRefresh  = "needs_refresh"
-	StatusVerifyFailed  = "verify_failed"
-)
-
-// verifyTimeout bounds each network call made during --verify so that a
-// hanging server cannot wedge `auth status --verify` or `doctor`. Mirrors
-// the 10s timeout used by the doctor endpoint probe.
-const verifyTimeout = 10 * time.Second
-
-// Result describes the independently usable bot and user identities.
-type Result struct {
-	Bot  Identity `json:"bot"`
-	User Identity `json:"user"`
-}
-
-// Identity is a single identity diagnostic result.
-type Identity struct {
-	Status           string `json:"status"`
-	Available        bool   `json:"available"`
-	Verified         *bool  `json:"verified,omitempty"`
-	Message          string `json:"message,omitempty"`
-	Hint             string `json:"hint,omitempty"`
-	OpenID           string `json:"openId,omitempty"`
-	AppName          string `json:"appName,omitempty"`
-	UserName         string `json:"userName,omitempty"`
-	TokenStatus      string `json:"tokenStatus,omitempty"`
-	Scope            string `json:"scope,omitempty"`
-	ExpiresAt        string `json:"expiresAt,omitempty"`
-	RefreshExpiresAt string `json:"refreshExpiresAt,omitempty"`
-	GrantedAt        string `json:"grantedAt,omitempty"`
-}
-
-// Diagnose checks bot and user identities separately. When verify is false,
-// it only reports local readiness and skips server calls.
-func Diagnose(ctx context.Context, f *cmdutil.Factory, cfg *core.CliConfig, verify bool) Result {
-	if ctx == nil {
-		ctx = context.Background()
-	}
-	return Result{
-		Bot:  diagnoseBot(ctx, f, cfg, verify),
-		User: diagnoseUser(ctx, f, cfg, verify),
-	}
-}
-
-func diagnoseBot(ctx context.Context, f *cmdutil.Factory, cfg *core.CliConfig, verify bool) Identity {
-	if cfg == nil || cfg.AppID == "" {
-		return Identity{
-			Status:  StatusNotConfigured,
-			Message: "Bot identity: not configured (missing app config)",
-			Hint:    "run: lark-cli config --help",
-		}
-	}
-	if !cfg.CanBot() {
-		return Identity{
-			Status:  StatusNotConfigured,
-			Message: "Bot identity: not configured (bot identity is not available in current credential context)",
-			Hint:    "check strict mode or the active credential provider",
-		}
-	}
-	if cfg.SupportedIdentities == 0 && !credential.HasRealAppSecret(cfg.AppSecret) {
-		return Identity{
-			Status:  StatusNotConfigured,
-			Message: "Bot identity: not configured (missing app secret or bot token)",
-			Hint:    "run: lark-cli config --help",
-		}
-	}
-
-	id := Identity{
-		Status:    StatusReady,
-		Available: true,
-		Message:   "Bot identity: ready",
-	}
-	if !verify {
-		return id
-	}
-
-	token, err := resolveBotToken(ctx, f, cfg)
-	if err != nil {
-		status := StatusVerifyFailed
-		var unavailable *credential.TokenUnavailableError
-		if errors.As(err, &unavailable) {
-			status = StatusNotConfigured
-		}
-		return Identity{
-			Status:   status,
-			Verified: boolPtr(false),
-			Message:  "Bot identity: " + StatusMessage(status) + ": " + err.Error(),
-			Hint:     "check app credentials or the active credential provider",
-		}
-	}
-
-	info, err := fetchBotInfo(ctx, f, cfg, token)
-	if err != nil {
-		return Identity{
-			Status:   StatusVerifyFailed,
-			Verified: boolPtr(false),
-			Message:  "Bot identity: verify failed: " + err.Error(),
-			Hint:     "check app credentials, scopes, network, or tenant access token configuration",
-		}
-	}
-
-	id.Verified = boolPtr(true)
-	id.OpenID = info.OpenID
-	id.AppName = info.AppName
-	return id
-}
-
-func diagnoseUser(ctx context.Context, f *cmdutil.Factory, cfg *core.CliConfig, verify bool) Identity {
-	if cfg == nil || cfg.AppID == "" {
-		return Identity{
-			Status:  StatusNotConfigured,
-			Message: "User identity: not configured (missing app config)",
-			Hint:    "run: lark-cli config --help",
-		}
-	}
-	if cfg.UserOpenId == "" {
-		return Identity{
-			Status:  StatusMissing,
-			Message: "User identity: missing (no user logged in)",
-			Hint:    "run: lark-cli auth login --help",
-		}
-	}
-
-	id := Identity{
-		UserName: cfg.UserName,
-		OpenID:   cfg.UserOpenId,
-	}
-	stored := larkauth.GetStoredToken(cfg.AppID, cfg.UserOpenId)
-	if stored == nil {
-		id.Status = StatusMissing
-		id.Message = "User identity: missing (no token in keychain for " + cfg.UserOpenId + ")"
-		id.Hint = "run: lark-cli auth login --help"
-		return id
-	}
-
-	fillTokenFields(&id, stored)
-	switch larkauth.TokenStatus(stored) {
-	case "valid":
-		id.Status = StatusReady
-		id.Available = true
-		id.Message = "User identity: ready"
-	case "needs_refresh":
-		id.Status = StatusNeedsRefresh
-		id.Available = true
-		id.Message = "User identity: needs refresh (will auto-refresh on next user API call)"
-	default:
-		id.Status = StatusMissing
-		id.Message = "User identity: missing (refresh token expired)"
-		id.Hint = "run: lark-cli auth login --help"
-		return id
-	}
-
-	if !verify {
-		return id
-	}
-
-	markVerifyFailed := func(reason, hint string) Identity {
-		id.Status = StatusVerifyFailed
-		id.Available = false
-		id.Verified = boolPtr(false)
-		id.Message = "User identity: verify failed: " + reason
-		if hint != "" {
-			id.Hint = hint
-		}
-		return id
-	}
-
-	httpClient, err := f.HttpClient()
-	if err != nil {
-		return markVerifyFailed("create HTTP client: "+err.Error(), "")
-	}
-	token, err := larkauth.GetValidAccessToken(httpClient, larkauth.NewUATCallOptions(cfg, f.IOStreams.ErrOut))
-	if err != nil {
-		return markVerifyFailed("token unusable: "+err.Error(), "run: lark-cli auth login --help")
-	}
-	sdk, err := f.LarkClient()
-	if err != nil {
-		return markVerifyFailed("SDK init failed: "+err.Error(), "")
-	}
-	verifyCtx, cancel := context.WithTimeout(ctx, verifyTimeout)
-	defer cancel()
-	if err := larkauth.VerifyUserToken(verifyCtx, sdk, token); err != nil {
-		return markVerifyFailed("server rejected token: "+err.Error(), "run: lark-cli auth login --help")
-	}
-
-	id.Verified = boolPtr(true)
-	if id.Status == StatusReady {
-		id.Message = "User identity: ready"
-	} else {
-		id.Message = "User identity: needs refresh (server verification succeeded after refresh)"
-	}
-	return id
-}
-
-func resolveBotToken(ctx context.Context, f *cmdutil.Factory, cfg *core.CliConfig) (string, error) {
-	if f == nil || f.Credential == nil {
-		return "", &credential.TokenUnavailableError{Type: credential.TokenTypeTAT}
-	}
-	result, err := f.Credential.ResolveToken(ctx, credential.NewTokenSpec(core.AsBot, cfg.AppID))
-	if err != nil {
-		return "", err
-	}
-	if result == nil || result.Token == "" {
-		return "", &credential.TokenUnavailableError{Type: credential.TokenTypeTAT}
-	}
-	return result.Token, nil
-}
-
-type botInfo struct {
-	OpenID  string
-	AppName string
-}
-
-func fetchBotInfo(ctx context.Context, f *cmdutil.Factory, cfg *core.CliConfig, token string) (*botInfo, error) {
-	httpClient, err := f.HttpClient()
-	if err != nil {
-		return nil, fmt.Errorf("create HTTP client: %w", err)
-	}
-	ctx, cancel := context.WithTimeout(ctx, verifyTimeout)
-	defer cancel()
-	url := strings.TrimRight(core.ResolveEndpoints(cfg.Brand).Open, "/") + "/open-apis/bot/v3/info"
-	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
-	if err != nil {
-		return nil, err
-	}
-	req.Header.Set("Authorization", "Bearer "+token)
-
-	resp, err := httpClient.Do(req)
-	if err != nil {
-		return nil, err
-	}
-	defer resp.Body.Close()
-
-	body, _ := io.ReadAll(resp.Body)
-	// /open-apis/bot/v3/info returns `{code, msg, bot: {...}}` — the bot
-	// payload is under "bot", not "data" as the newer Lark API convention.
-	var envelope struct {
-		Code int    `json:"code"`
-		Msg  string `json:"msg"`
-		Data struct {
-			OpenID  string `json:"open_id"`
-			AppName string `json:"app_name"`
-		} `json:"bot"`
-	}
-	parseErr := json.Unmarshal(body, &envelope)
-
-	if resp.StatusCode >= 400 {
-		// Lark error responses are usually `{code, msg}` envelopes even on
-		// non-2xx — surface them when present so callers see why bot auth
-		// was rejected, not just the bare HTTP code.
-		if parseErr == nil && envelope.Code != 0 {
-			return nil, fmt.Errorf("HTTP %d: [%d] %s", resp.StatusCode, envelope.Code, envelope.Msg)
-		}
-		return nil, fmt.Errorf("HTTP %d", resp.StatusCode)
-	}
-	if parseErr != nil {
-		return nil, fmt.Errorf("parse response: %w", parseErr)
-	}
-	if envelope.Code != 0 {
-		return nil, fmt.Errorf("[%d] %s", envelope.Code, envelope.Msg)
-	}
-	if envelope.Data.OpenID == "" {
-		return nil, errors.New("open_id is empty")
-	}
-	return &botInfo{OpenID: envelope.Data.OpenID, AppName: envelope.Data.AppName}, nil
-}
-
-func fillTokenFields(id *Identity, token *larkauth.StoredUAToken) {
-	id.TokenStatus = larkauth.TokenStatus(token)
-	id.Scope = token.Scope
-	id.ExpiresAt = formatMillis(token.ExpiresAt)
-	id.RefreshExpiresAt = formatMillis(token.RefreshExpiresAt)
-	id.GrantedAt = formatMillis(token.GrantedAt)
-}
-
-func formatMillis(ms int64) string {
-	if ms <= 0 {
-		return ""
-	}
-	return time.UnixMilli(ms).Format(time.RFC3339)
-}
-
-func StatusMessage(status string) string {
-	switch status {
-	case StatusNotConfigured:
-		return "not configured"
-	case StatusVerifyFailed:
-		return "verify failed"
-	case StatusNeedsRefresh:
-		return "needs refresh"
-	case StatusMissing:
-		return "missing"
-	default:
-		return status
-	}
-}
-
-func boolPtr(v bool) *bool {
-	return &v
-}

internal/identitydiag/diagnostics_test.go

@@ -1,350 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package identitydiag
-
-import (
-	"context"
-	"net/http"
-	"strings"
-	"testing"
-	"time"
-
-	larkauth "github.com/larksuite/cli/internal/auth"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/zalando/go-keyring"
-)
-
-func TestDiagnose_NoUserReportsBotReadyAndUserMissing(t *testing.T) {
-	cfg := &core.CliConfig{AppID: "test-app", AppSecret: "secret", Brand: core.BrandFeishu}
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-
-	got := Diagnose(context.Background(), f, cfg, false)
-	if got.Bot.Status != StatusReady || !got.Bot.Available {
-		t.Fatalf("bot = %#v, want ready and available", got.Bot)
-	}
-	if got.User.Status != StatusMissing || got.User.Available {
-		t.Fatalf("user = %#v, want missing and unavailable", got.User)
-	}
-}
-
-func TestDiagnose_BotIdentityNotConfigured(t *testing.T) {
-	cfg := &core.CliConfig{AppID: "test-app", Brand: core.BrandFeishu}
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-
-	got := Diagnose(context.Background(), f, cfg, false)
-	if got.Bot.Status != StatusNotConfigured || got.Bot.Available {
-		t.Fatalf("bot = %#v, want not_configured and unavailable", got.Bot)
-	}
-}
-
-func TestDiagnose_VerifyBotIdentity(t *testing.T) {
-	cfg := &core.CliConfig{AppID: "test-app", AppSecret: "secret", Brand: core.BrandFeishu}
-	f, _, _, reg := cmdutil.TestFactory(t, cfg)
-	stub := &httpmock.Stub{
-		Method: http.MethodGet,
-		URL:    "/open-apis/bot/v3/info",
-		Body: map[string]interface{}{
-			"code": 0,
-			"msg":  "ok",
-			"bot": map[string]interface{}{
-				"open_id":  "ou_bot",
-				"app_name": "diagnostic bot",
-			},
-		},
-	}
-	reg.Register(stub)
-
-	got := Diagnose(context.Background(), f, cfg, true)
-	if got.Bot.Status != StatusReady || !got.Bot.Available {
-		t.Fatalf("bot = %#v, want ready and available", got.Bot)
-	}
-	if got.Bot.Verified == nil || !*got.Bot.Verified {
-		t.Fatalf("bot verified = %v, want true", got.Bot.Verified)
-	}
-	if got.Bot.OpenID != "ou_bot" || got.Bot.AppName != "diagnostic bot" {
-		t.Fatalf("bot info = %#v, want open id and app name", got.Bot)
-	}
-	if got := stub.CapturedHeaders.Get("Authorization"); got != "Bearer test-token" {
-		t.Fatalf("Authorization = %q, want %q", got, "Bearer test-token")
-	}
-}
-
-func TestDiagnose_VerifyUserIdentity(t *testing.T) {
-	keyring.MockInit()
-	t.Setenv("HOME", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_DATA_DIR", t.TempDir())
-
-	cfg := &core.CliConfig{
-		AppID:      "test-app-user",
-		AppSecret:  "secret",
-		Brand:      core.BrandFeishu,
-		UserOpenId: "ou_user",
-		UserName:   "tester",
-	}
-	now := time.Now()
-	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
-		AppId:            cfg.AppID,
-		UserOpenId:       cfg.UserOpenId,
-		AccessToken:      "user-access-token",
-		RefreshToken:     "refresh-token",
-		ExpiresAt:        now.Add(time.Hour).UnixMilli(),
-		RefreshExpiresAt: now.Add(24 * time.Hour).UnixMilli(),
-		GrantedAt:        now.Add(-time.Hour).UnixMilli(),
-		Scope:            "offline_access",
-	}); err != nil {
-		t.Fatalf("SetStoredToken() error = %v", err)
-	}
-
-	f, _, _, reg := cmdutil.TestFactory(t, cfg)
-	reg.Register(&httpmock.Stub{
-		Method: http.MethodGet,
-		URL:    "/open-apis/bot/v3/info",
-		Body: map[string]interface{}{
-			"code": 0,
-			"msg":  "ok",
-			"bot": map[string]interface{}{
-				"open_id":  "ou_bot",
-				"app_name": "diagnostic bot",
-			},
-		},
-	})
-	reg.Register(&httpmock.Stub{
-		Method: http.MethodGet,
-		URL:    larkauth.PathUserInfoV1,
-		Body: map[string]interface{}{
-			"code": 0,
-			"msg":  "ok",
-		},
-	})
-
-	got := Diagnose(context.Background(), f, cfg, true)
-	if got.User.Status != StatusReady || !got.User.Available {
-		t.Fatalf("user = %#v, want ready and available", got.User)
-	}
-	if got.User.Verified == nil || !*got.User.Verified {
-		t.Fatalf("user verified = %v, want true", got.User.Verified)
-	}
-	if got.User.OpenID != "ou_user" || got.User.UserName != "tester" {
-		t.Fatalf("user = %#v, want user identity details", got.User)
-	}
-}
-
-func TestDiagnose_VerifyBotIdentity_HTTPErrorSurfacesEnvelope(t *testing.T) {
-	cfg := &core.CliConfig{AppID: "test-app", AppSecret: "secret", Brand: core.BrandFeishu}
-	f, _, _, reg := cmdutil.TestFactory(t, cfg)
-	reg.Register(&httpmock.Stub{
-		Method: http.MethodGet,
-		URL:    "/open-apis/bot/v3/info",
-		Status: http.StatusUnauthorized,
-		Body: map[string]interface{}{
-			"code": 99991663,
-			"msg":  "app ticket invalid",
-		},
-	})
-
-	got := Diagnose(context.Background(), f, cfg, true)
-	if got.Bot.Status != StatusVerifyFailed || got.Bot.Available {
-		t.Fatalf("bot = %#v, want verify_failed and unavailable", got.Bot)
-	}
-	if got.Bot.Verified == nil || *got.Bot.Verified {
-		t.Fatalf("bot verified = %v, want false", got.Bot.Verified)
-	}
-	if !strings.Contains(got.Bot.Message, "401") || !strings.Contains(got.Bot.Message, "99991663") {
-		t.Fatalf("bot message = %q, want both HTTP code and envelope code", got.Bot.Message)
-	}
-}
-
-func TestDiagnose_VerifyBotIdentity_BusinessErrorCode(t *testing.T) {
-	cfg := &core.CliConfig{AppID: "test-app", AppSecret: "secret", Brand: core.BrandFeishu}
-	f, _, _, reg := cmdutil.TestFactory(t, cfg)
-	reg.Register(&httpmock.Stub{
-		Method: http.MethodGet,
-		URL:    "/open-apis/bot/v3/info",
-		Body: map[string]interface{}{
-			"code": 10013,
-			"msg":  "scope not granted",
-		},
-	})
-
-	got := Diagnose(context.Background(), f, cfg, true)
-	if got.Bot.Status != StatusVerifyFailed || got.Bot.Available {
-		t.Fatalf("bot = %#v, want verify_failed and unavailable", got.Bot)
-	}
-	if !strings.Contains(got.Bot.Message, "10013") || !strings.Contains(got.Bot.Message, "scope not granted") {
-		t.Fatalf("bot message = %q, want envelope code/msg", got.Bot.Message)
-	}
-}
-
-func TestDiagnose_VerifyUserIdentity_ServerRejects(t *testing.T) {
-	keyring.MockInit()
-	t.Setenv("HOME", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_DATA_DIR", t.TempDir())
-
-	cfg := &core.CliConfig{
-		AppID:      "test-app-reject",
-		AppSecret:  "secret",
-		Brand:      core.BrandFeishu,
-		UserOpenId: "ou_user",
-		UserName:   "tester",
-	}
-	now := time.Now()
-	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
-		AppId:            cfg.AppID,
-		UserOpenId:       cfg.UserOpenId,
-		AccessToken:      "user-access-token",
-		RefreshToken:     "refresh-token",
-		ExpiresAt:        now.Add(time.Hour).UnixMilli(),
-		RefreshExpiresAt: now.Add(24 * time.Hour).UnixMilli(),
-		GrantedAt:        now.Add(-time.Hour).UnixMilli(),
-		Scope:            "offline_access",
-	}); err != nil {
-		t.Fatalf("SetStoredToken() error = %v", err)
-	}
-
-	f, _, _, reg := cmdutil.TestFactory(t, cfg)
-	reg.Register(&httpmock.Stub{
-		Method: http.MethodGet,
-		URL:    "/open-apis/bot/v3/info",
-		Body: map[string]interface{}{
-			"code": 0,
-			"bot":  map[string]interface{}{"open_id": "ou_bot", "app_name": "bot"},
-		},
-	})
-	reg.Register(&httpmock.Stub{
-		Method: http.MethodGet,
-		URL:    larkauth.PathUserInfoV1,
-		Body: map[string]interface{}{
-			"code": 99991661,
-			"msg":  "access token invalid",
-		},
-	})
-
-	got := Diagnose(context.Background(), f, cfg, true)
-	if got.User.Status != StatusVerifyFailed || got.User.Available {
-		t.Fatalf("user = %#v, want verify_failed and unavailable", got.User)
-	}
-	if got.User.Verified == nil || *got.User.Verified {
-		t.Fatalf("user verified = %v, want false", got.User.Verified)
-	}
-	if !strings.Contains(got.User.Message, "server rejected token") {
-		t.Fatalf("user message = %q, want 'server rejected token'", got.User.Message)
-	}
-}
-
-func TestDiagnose_UserIdentityExpired(t *testing.T) {
-	keyring.MockInit()
-	t.Setenv("HOME", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_DATA_DIR", t.TempDir())
-
-	cfg := &core.CliConfig{
-		AppID:      "test-app-expired",
-		AppSecret:  "secret",
-		Brand:      core.BrandFeishu,
-		UserOpenId: "ou_expired",
-		UserName:   "tester",
-	}
-	now := time.Now()
-	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
-		AppId:            cfg.AppID,
-		UserOpenId:       cfg.UserOpenId,
-		AccessToken:      "user-access-token",
-		RefreshToken:     "refresh-token",
-		ExpiresAt:        now.Add(-time.Hour).UnixMilli(),
-		RefreshExpiresAt: now.Add(-time.Minute).UnixMilli(),
-		GrantedAt:        now.Add(-24 * time.Hour).UnixMilli(),
-		Scope:            "offline_access",
-	}); err != nil {
-		t.Fatalf("SetStoredToken() error = %v", err)
-	}
-
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-	got := Diagnose(context.Background(), f, cfg, false)
-	if got.User.Status != StatusMissing || got.User.Available {
-		t.Fatalf("user = %#v, want missing and unavailable", got.User)
-	}
-	if got.User.Hint == "" {
-		t.Fatalf("user hint is empty, want re-login hint")
-	}
-}
-
-func TestDiagnose_BotIdentityStrictUserOnly(t *testing.T) {
-	// SupportedIdentities = SupportsUser (1) only — bot path should be
-	// reported as not_configured even though an app secret is present.
-	cfg := &core.CliConfig{
-		AppID:               "test-app",
-		AppSecret:           "secret",
-		Brand:               core.BrandFeishu,
-		SupportedIdentities: 1,
-	}
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-
-	got := Diagnose(context.Background(), f, cfg, false)
-	if got.Bot.Status != StatusNotConfigured || got.Bot.Available {
-		t.Fatalf("bot = %#v, want not_configured and unavailable", got.Bot)
-	}
-}
-
-func TestDiagnose_UserIdentityMissingAppConfig(t *testing.T) {
-	cfg := &core.CliConfig{Brand: core.BrandFeishu}
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-
-	got := Diagnose(context.Background(), f, cfg, false)
-	if got.User.Status != StatusNotConfigured || got.User.Available {
-		t.Fatalf("user = %#v, want not_configured and unavailable", got.User)
-	}
-}
-
-func TestStatusMessage(t *testing.T) {
-	cases := map[string]string{
-		StatusReady:         StatusReady,
-		StatusNotConfigured: "not configured",
-		StatusVerifyFailed:  "verify failed",
-		StatusNeedsRefresh:  "needs refresh",
-		StatusMissing:       "missing",
-		"unknown":           "unknown",
-	}
-	for in, want := range cases {
-		if got := StatusMessage(in); got != want {
-			t.Errorf("StatusMessage(%q) = %q, want %q", in, got, want)
-		}
-	}
-}
-
-func TestDiagnose_UserIdentityNeedsRefresh(t *testing.T) {
-	keyring.MockInit()
-	t.Setenv("HOME", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_DATA_DIR", t.TempDir())
-
-	cfg := &core.CliConfig{
-		AppID:      "test-app-needs-refresh",
-		AppSecret:  "secret",
-		Brand:      core.BrandFeishu,
-		UserOpenId: "ou_refresh",
-		UserName:   "tester",
-	}
-	now := time.Now()
-	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
-		AppId:            cfg.AppID,
-		UserOpenId:       cfg.UserOpenId,
-		AccessToken:      "user-access-token",
-		RefreshToken:     "refresh-token",
-		ExpiresAt:        now.Add(time.Minute).UnixMilli(),
-		RefreshExpiresAt: now.Add(24 * time.Hour).UnixMilli(),
-		GrantedAt:        now.Add(-time.Hour).UnixMilli(),
-		Scope:            "offline_access",
-	}); err != nil {
-		t.Fatalf("SetStoredToken() error = %v", err)
-	}
-
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-	got := Diagnose(context.Background(), f, cfg, false)
-	if got.User.Status != StatusNeedsRefresh || !got.User.Available {
-		t.Fatalf("user = %#v, want needs_refresh and available", got.User)
-	}
-	if got.User.TokenStatus != "needs_refresh" {
-		t.Fatalf("token status = %q, want needs_refresh", got.User.TokenStatus)
-	}
-}

internal/keychain/keychain.go

@@ -41,7 +41,6 @@ func wrapError(op string, err error) error {
 	if errors.Is(err, errNotInitialized) {
 		hint = "The keychain master key may have been cleaned up or deleted. If running inside a sandbox or CI environment, please ensure the process has the necessary permissions to access the keychain, you can try running this outside the sandbox. Otherwise, please reconfigure the CLI by running lark-cli config init."
 	}
-	hint += extraHint(err)
 
 	func() {
 		defer func() { recover() }()

internal/keychain/keychain_darwin.go

@@ -43,12 +43,6 @@ var keyringGet = keyring.Get
 // keyringSet is overridden in tests to simulate system keychain writes.
 var keyringSet = keyring.Set
 
-// errKeychainBlocked is returned when the OS Keychain is reachable but
-// denies access — sandbox restriction, user-denied prompt, or a 5-second
-// timeout (typically caused by an ignored permission dialog). Distinct
-// from errNotInitialized (master key entry genuinely absent).
-var errKeychainBlocked = errors.New("keychain access blocked")
-
 // StorageDir returns the storage directory for a given service name on macOS.
 func StorageDir(service string) string {
 	home, err := vfs.UserHomeDir()
@@ -91,7 +85,7 @@ func getMasterKey(service string, allowCreate bool) ([]byte, error) {
 			return
 		} else if !errors.Is(err, keyring.ErrNotFound) {
 			// Not ErrNotFound, which means access was denied or blocked by the system
-			resCh <- result{key: nil, err: errKeychainBlocked}
+			resCh <- result{key: nil, err: errors.New("keychain access blocked")}
 			return
 		}
 
@@ -123,7 +117,7 @@ func getMasterKey(service string, allowCreate bool) ([]byte, error) {
 		return res.key, res.err
 	case <-ctx.Done():
 		// Timeout is usually caused by ignored/blocked permission prompts
-		return nil, errKeychainBlocked
+		return nil, errors.New("keychain access blocked")
 	}
 }
 
@@ -271,7 +265,11 @@ func platformGet(service, account string) (string, error) {
 	if err != nil {
 		return "", err
 	}
-	return decryptData(data, key)
+	plaintext, err := decryptData(data, key)
+	if err != nil {
+		return "", err
+	}
+	return plaintext, nil
 }
 
 // platformSet stores a value in the macOS keychain.
@@ -318,116 +316,3 @@ func platformRemove(service, account string) error {
 	}
 	return nil
 }
-
-// DowngradeResult reports what DowngradeMasterKeyToFile did. The command
-// never writes to or removes from the OS Keychain — it only reads from it
-// and only writes to the local file fallback.
-type DowngradeResult int
-
-const (
-	// DowngradeAlreadyDone means master.key.file was already present and valid.
-	DowngradeAlreadyDone DowngradeResult = iota
-	// DowngradeUsedKeychainKey means the existing OS Keychain master key was
-	// copied verbatim into the local file fallback. Existing .enc credentials
-	// remain readable via the file path.
-	DowngradeUsedKeychainKey
-	// DowngradeCreatedNewKey means the OS Keychain held no master key, so a
-	// fresh random key was generated and written to the file fallback only.
-	// The OS Keychain was not touched.
-	DowngradeCreatedNewKey
-)
-
-// MasterKeyFilePath returns the absolute path of the file fallback master key
-// for the given service.
-func MasterKeyFilePath(service string) string {
-	return filepath.Join(StorageDir(service), fileMasterKeyName)
-}
-
-// DowngradeMasterKeyToFile materializes the OS Keychain master key into the
-// local file fallback so that subsequent platformGet calls take the file-first
-// path and bypass the OS Keychain entirely. The Keychain entry itself is kept
-// as a cold backup; nothing is removed there.
-//
-// Idempotent: if master.key.file is already present and valid, returns
-// DowngradeAlreadyDone without touching anything.
-func DowngradeMasterKeyToFile(service string) (DowngradeResult, error) {
-	dir := StorageDir(service)
-	keyPath := filepath.Join(dir, fileMasterKeyName)
-
-	existing, statErr := vfs.ReadFile(keyPath)
-	if statErr == nil {
-		if len(existing) == masterKeyBytes {
-			return DowngradeAlreadyDone, nil
-		}
-		return 0, errors.New("keychain is corrupted")
-	}
-	if !errors.Is(statErr, os.ErrNotExist) {
-		return 0, statErr
-	}
-
-	result := DowngradeUsedKeychainKey
-	key, err := getMasterKey(service, false)
-	if err != nil {
-		if !errors.Is(err, errNotInitialized) {
-			return 0, err
-		}
-		// Keychain has no master key. Generate a fresh one *locally* — do
-		// NOT call getMasterKey(service, true), which would write the new
-		// key into the OS Keychain as a side effect. keychain-downgrade
-		// must never modify the OS Keychain; it only ever reads from it.
-		key = make([]byte, masterKeyBytes)
-		if _, err := rand.Read(key); err != nil {
-			return 0, err
-		}
-		result = DowngradeCreatedNewKey
-	}
-
-	if err := vfs.MkdirAll(dir, 0700); err != nil {
-		return 0, err
-	}
-	file, err := vfs.OpenFile(keyPath, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0600)
-	if err != nil {
-		if errors.Is(err, os.ErrExist) {
-			concurrent, readErr := vfs.ReadFile(keyPath)
-			if readErr == nil && len(concurrent) == masterKeyBytes {
-				return DowngradeAlreadyDone, nil
-			}
-			if readErr != nil {
-				return 0, readErr
-			}
-			return 0, errors.New("keychain is corrupted")
-		}
-		return 0, err
-	}
-	writeFailed := true
-	defer func() {
-		if writeFailed {
-			_ = vfs.Remove(keyPath)
-		}
-	}()
-	if _, err := file.Write(key); err != nil {
-		_ = file.Close()
-		return 0, err
-	}
-	if err := file.Close(); err != nil {
-		return 0, err
-	}
-	writeFailed = false
-	return result, nil
-}
-
-// extraHint appends a darwin-specific suggestion to wrapError's hint message
-// when the failure is one keychain-downgrade can recover from: either the
-// master key is missing (errNotInitialized) or the OS Keychain is reachable
-// but blocking access (errKeychainBlocked — sandbox, denied prompt, timeout).
-// In both cases the user can run keychain-downgrade from an interactive
-// Terminal session, after which the file fallback is readable from any
-// context (sandbox, automation, CI, etc.). Corruption errors are
-// deliberately excluded — downgrade would re-read the same bad bytes and
-// fail; the right fix there is to delete the corrupt Keychain entry first.
-func extraHint(err error) string {
-	if errors.Is(err, errNotInitialized) || errors.Is(err, errKeychainBlocked) {
-		return " On macOS, you can also open an interactive Terminal session (where the system Keychain is reachable) and run `lark-cli config keychain-downgrade` to materialize the master key into a local file; subsequent runs in this sandbox/automation context will then read from the file and succeed. Trade-off: after downgrade, any process running as your macOS user can read that file (file permissions replace the Keychain's per-app ACL)."
-	}
-	return ""
-}