fix: add expression to avoid misunderstanding

Change-Id: Ib3a6c8a327b95c3f837d4bb565365235d0f0dfb8
2026-07-03 22:24:31 +08:00 · 2026-05-15 16:40:41 +08:00
902 changed files with 11513 additions and 88188 deletions
--- a/.github/pull_request_template.md
+++ b/.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. -->
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -63,7 +63,7 @@ jobs:
      - name: Fetch meta data
        run: python3 scripts/fetch_meta.py
      - name: Run tests
-        run: go test -v -race -count=1 -timeout=5m ./cmd/... ./internal/... ./shortcuts/... ./extension/...
+        run: go test -v -race -count=1 -timeout=5m ./cmd/... ./internal/... ./shortcuts/...

  lint:
    needs: fast-gate
@@ -82,8 +82,6 @@ jobs:
        run: python3 scripts/fetch_meta.py
      - name: Run golangci-lint
        run: go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.6 run --new-from-rev=origin/main
-      - name: Run errs/ lint guards (lintcheck)
-        run: go run -C lint . ..

  coverage:
    needs: fast-gate
--- a/.gitignore
+++ b/.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
--- a/.golangci.yml
+++ b/.golangci.yml
@@ -45,43 +45,21 @@ linters:
      - path: _test\.go$
        linters:
          - bodyclose
-          - bidichk
          - gocritic
          - depguard
          - forbidigo
-      # Paths that run forbidigo. Add an entry when a path joins one of
-      # the rules below.
-      - path-except: (shortcuts/|internal/|cmd/auth/|cmd/config/|cmd/service/)
+      - path-except: (shortcuts/|internal/)
        linters:
          - forbidigo
      - path: internal/vfs/
        linters:
          - forbidigo
-      # shortcuts-no-raw-http is shortcuts-only; internal/ wraps raw HTTP
-      # for the client / credential layer.
+      # The shortcuts-no-raw-http forbidigo rule below is shortcuts-only;
+      # internal/ legitimately wraps raw HTTP for the client / credential layer.
      - path-except: shortcuts/
        text: shortcuts-no-raw-http
        linters:
          - forbidigo
-      # errs-typed-only enforced on paths already migrated to errs.NewXxxError.
-      # Add a path when its migration is complete.
-      - path-except: (internal/auth/|internal/errcompat/|internal/errclass/|internal/client/|internal/cmdutil/factory\.go|cmd/auth/|cmd/config/|cmd/service/|shortcuts/common/mcp_client\.go|shortcuts/calendar/helpers\.go|shortcuts/drive/)
-        text: errs-typed-only
-        linters:
-          - forbidigo
-      # errs-no-bare-wrap enforced on paths fully migrated to typed final
-      # errors. Scoped separately from errs-typed-only because cmd/auth/,
-      # cmd/config/ still have residual fmt.Errorf and must not be caught.
-      - path-except: (shortcuts/drive/|shortcuts/calendar/helpers\.go|shortcuts/common/mcp_client\.go)
-        text: errs-no-bare-wrap
-        linters:
-          - forbidigo
-      # errs-no-legacy-helper is drive-only: the shared helpers it bans are
-      # still used by other domains until their later migration phase.
-      - path-except: (shortcuts/drive/)
-        text: errs-no-legacy-helper
-        linters:
-          - forbidigo

  settings:
    depguard:
@@ -100,30 +78,6 @@ linters:
                Use runtime.FileIO() for file operations or runtime.ValidatePath() for path validation.
    forbidigo:
      forbid:
-        # ── legacy output.Err* helpers banned on migrated paths ──
-        # output.ErrBare is intentionally not listed — it is the predicate-
-        # command silent-exit signal, outside the typed envelope contract.
-        - pattern: output\.(ErrValidation|ErrAuth|ErrNetwork|ErrAPI|ErrWithHint|Errorf)\b
-          msg: >-
-            [errs-typed-only] use errs.NewXxxError(...) builder
-            (see errs/types.go).
-        # ── legacy shared error helpers banned on drive ──
-        # These helpers internally produce legacy output.Err* shapes, so they
-        # are invisible to the errs-typed-only ban above. Drive has migrated its
-        # calls to typed errs.* (drive-local driveInputStatError / driveSaveError);
-        # this prevents reintroduction. Other domains still use the shared
-        # helpers (migrated globally in a later phase), so this is drive-scoped.
-        - pattern: (common\.FlagErrorf|common\.WrapInputStatError|common\.WrapSaveErrorByCategory)\b
-          msg: >-
-            [errs-no-legacy-helper] these shared helpers emit legacy output.Err*
-            shapes. Use the typed errs.NewXxxError builders or the drive-local
-            driveInputStatError / driveSaveError helpers (shortcuts/drive/drive_errors.go).
-        # ── bare error wraps banned on fully-typed paths ──
-        - pattern: (fmt\.Errorf|errors\.New)\b
-          msg: >-
-            [errs-no-bare-wrap] final errors must be typed (errs.NewXxxError);
-            wrap a cause with .WithCause(err). Genuine intermediate wraps:
-            //nolint:forbidigo with a reason.
        # ── http: shortcuts must not construct raw HTTP requests ──
        # Bans request / client construction; constants (http.MethodPost,
        # http.StatusOK) and pure helpers (http.StatusText, http.Header) are
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,292 +2,6 @@

 All notable changes to this project will be documented in this file.

-## [v1.0.46] - 2026-06-02
-
-### Features
-
- **im**: Add card message format support (#1218)
- **im**: Resolve markdown blank-line formatting inconsistency in post messages (#1216)
- **vc**: Inline transcript from artifacts API and add keywords (#1206)
- **transport**: Add proxy plugin mode for CLI HTTP transport (#1181)
- **agent**: Increase agent trace max length to 1024 (#1211)
- **shortcuts**: Unconditionally inject `--format` flag for all shortcuts (#1156)
-
-### Bug Fixes
-
- **cli**: Remove FLAGS section from root `--help` (#1226)
- **cli**: Stop root `--help` listing per-command flags as global (#1223)
-
-### Refactor
-
- **transport**: Own all HTTP transport in `internal/transport`, fix util layering inversion (#1213)
-
-### Documentation
-
- **base**: Optimize base skill references (#1171)
- **drive**: Add Lark Drive knowledge organization workflow (#1028)
-
-## [v1.0.45] - 2026-06-01
-
-### Features
-
- **errors**: Add typed envelope contract for auth-domain errors (#1135)
- **platform**: Support multiple policy rules per plugin (#1182)
-
-### Bug Fixes
-
- **vc**: Add domain boundaries and enrich `+notes` (#1172)
- **whiteboard**: Fix whiteboard skill (#1180)
-
-### Refactor
-
- **auth**: Update login hint and split-flow docs (#1201)
-
-## [v1.0.44] - 2026-05-29
-
-### Features
-
- **base**: Add dashboard block data shortcut and workflow docs (#1067)
- **im**: Support `--types` flag for listing p2p single chats in `chat-list` (#1077)
- **agent**: Add agent header support (#1158)
-
-### Bug Fixes
-
- **im**: Correct 64-bit MP4 box size handling to prevent panic on crafted media (#1165)
- **install**: Detect curl version before using `--ssl-revoke-best-effort` (#1124)
- **vc**: Correct `--minute-token` to `--minute-tokens` in recording reference (#1170)
- **whiteboard**: Fix whiteboard skill (#1166)
-
-## [v1.0.43] - 2026-05-28
-
-### Features
-
- **event**: Support `note` generated event (#1159)
- **config**: Decouple `--lang` preference from TUI display language (#1132)
- **mail**: Add HTML lint library with Larksuite-native autofix for `lark-mail` (#1019)
-
-### Bug Fixes
-
- **config**: Propagate `Lang` across credential boundary; respect `CurrentApp` in priorLang (#1157)
- **config**: Allow lark-channel bind source override (#1154)
- **im**: Clarify `messages-send` dry-run chat membership (#1150)
- **base**: Include `log_id` in attachment media errors (#1133)
-
-### Performance
-
- **im**: Parallelize reactions, thread_replies, and merge_forward fetches (#1146)
-
-### Documentation
-
- **im**: Update IM skill urgent APIs (#1153)
-
-## [v1.0.42] - 2026-05-27
-
-### Features
-
- **mail**: Add `+draft-send` shortcut for batch draft sending (#1017)
- **im**: Enrich messages with reactions and output `update_time` (#1095)
- **schema**: Output JSON spec envelope for all API commands (#1048)
- **event**: Support `vc` / `note` / `minute` events (#1113)
- **drive**: Add secure label shortcuts (#985)
- **affordance**: Use description and command in affordance example schema (#1126)
-
-### Bug Fixes
-
- **docs**: Remove unsupported `fetch` text format (#1109)
-
-### Refactor
-
- **auth**: Drop duplicate top-level user fields in `status` (#1128)
-
-### Documentation
-
- **doc**: Document block anchor URLs in `lark-doc` skill (#1120)
- **whiteboard**: Improve SVG/Mermaid instructions (#1097)
-
-## [v1.0.41] - 2026-05-26
-
-### Features
-
- **minutes**: Add minutes edit shortcuts (#1036)
- **minutes**: Get minutes keywords (#1079)
- **slides**: Support importing pptx as slides (#1068)
- **config**: Add `keychain-downgrade` subcommand (macOS) (#1085)
- **errors**: Add structured CLI error contract (#984)
- **apps**: Replace `+html-publish` cwd hard-reject with credential-file scan (#1072)
-
-### Bug Fixes
-
- **drive**: Support doubao drive inspect URL variants (#1106)
- **skills**: Sync skills incrementally during update (#1042)
- **apps**: Read app object from `data.app` for `+create` and `+update` (#1087)
- **common**: Escape special chars in multipart form filenames (#1037)
- **auth**: Remove fenced code block guidance from auth URL output hints (#1088)
-
-### Documentation
-
- **skills**: Fix agent routing for doubao.com URLs (#1082)
- **task**: Require `--complete=false` for pending standup summaries (#1101)
- **base**: Document UI-only field settings (#1078)
- **contributing**: Clarify contributor guidance (#1096)
-
-## [v1.0.40] - 2026-05-25
-
-### Features
-
- **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
-
- **doc**: Add `--width`/`--height` flags to `docs +media-insert` (#832)
- **wiki**: Add `+space-list` / `+node-list` / `+node-copy` shortcuts (#392)
-
-### Bug Fixes
-
- **drive**: Preserve parent token on nested overwrite (#908)
- **selfupdate**: Use `LookPath` instead of `Executable` for binary verification (#886)
- **registry**: Wait for background meta refresh before test reset (#894)
-
-### Documentation
-
- **doc**: Add SVG whiteboard support to `lark-doc` v2 skill (#901)
- **drive**: Add permission public patch error guidance (#863)
-
 ## [v1.0.31] - 2026-05-14

 ### Features
@@ -989,21 +703,6 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.

-[v1.0.46]: https://github.com/larksuite/cli/releases/tag/v1.0.46
-[v1.0.45]: https://github.com/larksuite/cli/releases/tag/v1.0.45
-[v1.0.44]: https://github.com/larksuite/cli/releases/tag/v1.0.44
-[v1.0.43]: https://github.com/larksuite/cli/releases/tag/v1.0.43
-[v1.0.42]: https://github.com/larksuite/cli/releases/tag/v1.0.42
-[v1.0.41]: https://github.com/larksuite/cli/releases/tag/v1.0.41
-[v1.0.40]: https://github.com/larksuite/cli/releases/tag/v1.0.40
-[v1.0.39]: https://github.com/larksuite/cli/releases/tag/v1.0.39
-[v1.0.38]: https://github.com/larksuite/cli/releases/tag/v1.0.38
-[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
 [v1.0.29]: https://github.com/larksuite/cli/releases/tag/v1.0.29
--- a/25
+++ b/25
@@ -8,7 +8,7 @@ DATE     := $(shell date +%Y-%m-%d)
 LDFLAGS  := -s -w -X $(MODULE)/internal/build.Version=$(VERSION) -X $(MODULE)/internal/build.Date=$(DATE)
 PREFIX   ?= /usr/local

-.PHONY: all build vet fmt-check test unit-test integration-test examples-build install uninstall clean fetch_meta gitleaks
+.PHONY: all build vet test unit-test integration-test install uninstall clean fetch_meta gitleaks

 all: test

@@ -21,32 +21,13 @@ build: fetch_meta
 vet: fetch_meta
 	go vet ./...

-# fmt-check fails when any file would be reformatted by gofmt. Keep this
-# in sync with the fast-gate "Check formatting" step in CI.
-fmt-check:
-	@unformatted=$$(gofmt -l . | grep -v '^\.claude/' || true); \
-	if [ -n "$$unformatted" ]; then \
-		echo "Unformatted Go files:"; \
-		echo "$$unformatted"; \
-		echo "Run 'gofmt -w .' and commit."; \
-		exit 1; \
-	fi
-
-# ./extension/... keeps the public plugin SDK in the default test matrix.
 unit-test: fetch_meta
-	go test -race -gcflags="all=-N -l" -count=1 \
-		./cmd/... ./internal/... ./shortcuts/... ./extension/...
-
-# examples-build keeps the shipped plugin-SDK examples compilable. If this
-# breaks, the plugin author guide's "go build ./..." path is broken.
-examples-build:
-	go build ./extension/platform/examples/audit-observer
-	go build ./extension/platform/examples/readonly-policy
+	go test -race -gcflags="all=-N -l" -count=1 ./cmd/... ./internal/... ./shortcuts/...

 integration-test: build
 	go test -v -count=1 ./tests/...

-test: vet fmt-check unit-test examples-build integration-test
+test: vet unit-test integration-test

 install: build
 	install -d $(PREFIX)/bin
--- a/README.md
+++ b/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**.
--- a/README.zh.md
+++ b/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 许可证** 开源。
--- a/cmd/api/api.go
+++ b/cmd/api/api.go
@@ -90,7 +90,6 @@ func NewCmdApiWithContext(ctx context.Context, f *cmdutil.Factory, runF func(*AP
 	cmd.Flags().IntVar(&opts.PageLimit, "page-limit", 10, "max pages to fetch with --page-all (0 = unlimited)")
 	cmd.Flags().IntVar(&opts.PageDelay, "page-delay", 200, "delay in ms between pages")
 	cmd.Flags().StringVar(&opts.Format, "format", "json", "output format: json|ndjson|table|csv")
-	cmd.Flags().Bool("json", false, "shorthand for --format json")
 	cmd.Flags().StringVarP(&opts.JqExpr, "jq", "q", "", "jq expression to filter JSON output")
 	cmd.Flags().BoolVar(&opts.DryRun, "dry-run", false, "print request without executing")
 	cmd.Flags().StringVar(&opts.File, "file", "", "file to upload as multipart/form-data ([field=]path, supports - for stdin)")
@@ -104,7 +103,6 @@ func NewCmdApiWithContext(ctx context.Context, f *cmdutil.Factory, runF func(*AP
 	cmdutil.RegisterFlagCompletion(cmd, "format", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
 		return []string{"json", "ndjson", "table", "csv"}, cobra.ShellCompDirectiveNoFileComp
 	})
-	cmdutil.SetRisk(cmd, "write")

 	return cmd
 }
@@ -239,11 +237,7 @@ func apiRun(opts *APIOptions) error {

 	resp, err := ac.DoAPI(opts.Ctx, request)
 	if err != nil {
-		// MarkRaw tells the dispatcher to skip the legacy enrichPermissionError
-		// pass on *output.ExitError values. Typed *errs.* errors that flow
-		// through here keep their canonical message / hint from BuildAPIError;
-		// MarkRaw is a no-op on those (it only flips a flag on *ExitError).
-		return output.MarkRaw(err)
+		return output.MarkRaw(client.WrapDoAPIError(err))
 	}
 	err = client.HandleResponse(resp, client.ResponseOptions{
 		OutputPath:  opts.Output,
@@ -253,15 +247,9 @@ func apiRun(opts *APIOptions) error {
 		ErrOut:      f.IOStreams.ErrOut,
 		FileIO:      f.ResolveFileIO(opts.Ctx),
 		CommandPath: opts.Cmd.CommandPath(),
-		Identity:    opts.As,
-		// CheckResponse routes through errclass.BuildAPIError for known Lark
-		// codes (typed PermissionError / AuthenticationError / ...). For
-		// unknown codes it falls back to *errs.APIError. The Brand+AppID on
-		// the client populate identity-aware fields (ConsoleURL etc.).
-		CheckError: ac.CheckResponse,
 	})
-	// MarkRaw: see comment above on the DoAPI path. Skips legacy
-	// *ExitError enrichment; typed errors flow through unchanged.
+	// 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)
 	}
@@ -273,12 +261,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
@@ -291,9 +276,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)
 		}
@@ -305,9 +290,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)
 		}
--- a/cmd/api/api_test.go
+++ b/cmd/api/api_test.go
@@ -10,10 +10,10 @@ 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/httpmock"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/spf13/cobra"
 )

@@ -399,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,
@@ -672,69 +820,3 @@ func TestApiCmd_DryRunWithFile(t *testing.T) {
 		t.Errorf("expected dry-run header, got: %s", out)
 	}
 }
-
-// TestApiCmd_PermissionError_DerivesFirstClassFields pins that when a Lark
-// API returns a missing-scope failure, the typed *errs.PermissionError
-// surfaced by `lark-cli api` lifts the diagnostic signals BuildAPIError
-// consumed during classification into first-class wire fields
-// (MissingScopes, LogID, ConsoleURL). The wire shape is the typed envelope
-// — there is no raw-payload passthrough; new Lark diagnostic fields require
-// a CLI release.
-func TestApiCmd_PermissionError_DerivesFirstClassFields(t *testing.T) {
-	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "cli_test_perm", AppSecret: "secret", Brand: core.BrandFeishu,
-	})
-
-	reg.Register(&httpmock.Stub{
-		URL: "/open-apis/docx/v1/documents/test",
-		Body: map[string]interface{}{
-			"code":   99991679,
-			"msg":    "scope missing",
-			"log_id": "20260527-test-log",
-			"error": map[string]interface{}{
-				"permission_violations": []interface{}{
-					map[string]interface{}{"subject": "docx:document"},
-				},
-			},
-		},
-	})
-
-	cmd := NewCmdApi(f, nil)
-	cmd.SetArgs([]string{"GET", "/open-apis/docx/v1/documents/test", "--as", "bot"})
-	err := cmd.Execute()
-	if err == nil {
-		t.Fatal("expected error for non-zero code")
-	}
-
-	var pe *errs.PermissionError
-	if !errors.As(err, &pe) {
-		t.Fatalf("expected *errs.PermissionError, got %T: %v", err, err)
-	}
-
-	if len(pe.MissingScopes) != 1 || pe.MissingScopes[0] != "docx:document" {
-		t.Errorf("MissingScopes = %v, want [docx:document]", pe.MissingScopes)
-	}
-	if pe.LogID != "20260527-test-log" {
-		t.Errorf("LogID = %q, want %q", pe.LogID, "20260527-test-log")
-	}
-}
-
-func TestApiCmd_JsonFlag_Accepted(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-
-	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
-		gotOpts = opts
-		return nil
-	})
-	cmd.SetArgs([]string{"GET", "/open-apis/test", "--json"})
-	err := cmd.Execute()
-	if err != nil {
-		t.Fatalf("--json should be accepted without error, got: %v", err)
-	}
-	if gotOpts.Method != "GET" {
-		t.Errorf("expected method GET, got %s", gotOpts.Method)
-	}
-}
--- a/cmd/auth/auth.go
+++ b/cmd/auth/auth.go
@@ -17,7 +17,6 @@ import (
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/errclass"
 )

 // NewCmdAuth creates the auth command with subcommands.
@@ -44,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
 }

@@ -71,7 +69,7 @@ func getUserInfo(ctx context.Context, sdk *lark.Client, accessToken string) (ope

 	var resp userInfoResponse
 	if err := json.Unmarshal(apiResp.RawBody, &resp); err != nil {
-		return "", "", fmt.Errorf("failed to parse user info: %w", err)
+		return "", "", fmt.Errorf("failed to parse user info: %v", err)
 	}
 	if resp.Code != 0 {
 		return "", "", fmt.Errorf("failed to get user info [%d]: %s", resp.Code, resp.Msg)
@@ -111,11 +109,6 @@ type appInfoResponse struct {
 	} `json:"data"`
 }

-// getAppInfoFn is the package-level seam used by callers (scopes.go) so tests
-// can substitute a fake without standing up a full SDK + httpmock pipeline.
-// Mirrors the pollDeviceToken pattern in login.go.
-var getAppInfoFn = getAppInfo
-
 // getAppInfo queries app info from the Lark API.
 func getAppInfo(ctx context.Context, f *cmdutil.Factory, appId string) (*appInfo, error) {
 	ac, err := f.NewAPIClient()
@@ -137,10 +130,10 @@ func getAppInfo(ctx context.Context, f *cmdutil.Factory, appId string) (*appInfo

 	var resp appInfoResponse
 	if err := json.Unmarshal(apiResp.RawBody, &resp); err != nil {
-		return nil, fmt.Errorf("failed to parse response: %w", err)
+		return nil, fmt.Errorf("failed to parse response: %v", err)
 	}
 	if resp.Code != 0 {
-		return nil, classifyAppInfoErr(apiResp.RawBody, resp.Code, resp.Msg, f, appId)
+		return nil, fmt.Errorf("API error [%d]: %s", resp.Code, resp.Msg)
 	}

 	app := resp.Data.App
@@ -159,21 +152,3 @@ func getAppInfo(ctx context.Context, f *cmdutil.Factory, appId string) (*appInfo

 	return &appInfo{OwnerOpenId: ownerOpenId, UserScopes: userScopes}, nil
 }
-
-// classifyAppInfoErr re-decodes the raw body so BuildAPIError sees the
-// upstream `error` block — the typed appInfoResponse shape drops it.
-func classifyAppInfoErr(rawBody []byte, code int, msg string, f *cmdutil.Factory, appId string) error {
-	var raw map[string]any
-	_ = json.Unmarshal(rawBody, &raw)
-	if raw == nil {
-		raw = map[string]any{}
-	}
-	raw["code"] = code
-	raw["msg"] = msg
-	cc := errclass.ClassifyContext{Identity: string(core.AsBot)}
-	if cfg, _ := f.Config(); cfg != nil {
-		cc.Brand = string(cfg.Brand)
-		cc.AppID = appId
-	}
-	return errclass.BuildAPIError(raw, cc)
-}
--- a/cmd/auth/auth_test.go
+++ b/cmd/auth/auth_test.go
@@ -12,7 +12,6 @@ import (
 	"strings"
 	"testing"

-	"github.com/larksuite/cli/errs"
 	extcred "github.com/larksuite/cli/extension/credential"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
@@ -45,32 +44,6 @@ func TestAuthLoginCmd_FlagParsing(t *testing.T) {
 	}
 }

-func TestAuthLoginCmd_HelpGuidesNonStreamingAgentsToSplitFlow(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-
-	cmd := NewCmdAuthLogin(f, func(opts *LoginOptions) error { return 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{
-		"only delivers final turn messages",
-		"--no-wait --json",
-		"send the verification URL (or QR code) to the user as your final message",
-		"run --device-code in a later step",
-	} {
-		if !strings.Contains(got, want) {
-			t.Fatalf("help missing %q, got:\n%s", want, got)
-		}
-	}
-}
-
 func TestAuthCheckCmd_FlagParsing(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
@@ -319,54 +292,6 @@ func TestAuthScopesRun_UsesTenantAccessTokenFromCredentialProvider(t *testing.T)
 	}
 }

-// TestAuthScopesRun_LarkPermissionError_TypedAsPermissionError pins that when
-// the Lark API returns a permission code (99991679 with permission_violations),
-// getAppInfo classifies it as *errs.PermissionError carrying the server-
-// supplied MissingScopes — not a bare error wrapped as InternalError.
-func TestAuthScopesRun_LarkPermissionError_TypedAsPermissionError(t *testing.T) {
-	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-	tokenResolver := &authScopesTokenResolver{}
-	f.Credential = credential.NewCredentialProvider(nil, nil, tokenResolver, nil)
-
-	reg.Register(&httpmock.Stub{
-		Method: http.MethodGet,
-		URL:    "/open-apis/application/v6/applications/test-app",
-		Body: map[string]interface{}{
-			"code": 99991679,
-			"msg":  "scope missing",
-			"error": map[string]interface{}{
-				"permission_violations": []interface{}{
-					map[string]interface{}{"subject": "application:application:self_manage"},
-				},
-			},
-		},
-	})
-
-	err := authScopesRun(&ScopesOptions{
-		Factory: f,
-		Ctx:     context.Background(),
-		Format:  "json",
-	})
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-
-	var pe *errs.PermissionError
-	if !errors.As(err, &pe) {
-		t.Fatalf("expected *errs.PermissionError, got %T: %v", err, err)
-	}
-	if len(pe.MissingScopes) != 1 || pe.MissingScopes[0] != "application:application:self_manage" {
-		t.Errorf("MissingScopes = %v, want server-supplied [application:application:self_manage]", pe.MissingScopes)
-	}
-
-	var intErr *errs.InternalError
-	if errors.As(err, &intErr) {
-		t.Error("Lark business error must not be wrapped as InternalError; permission semantics lost")
-	}
-}
-
 type authScopesTokenResolver struct {
 	requests []credential.TokenSpec
 }
@@ -438,8 +363,15 @@ func TestAuthBlockedByExternalProvider(t *testing.T) {
 			if matched != nil && matched != cmd && !matched.SilenceUsage {
 				t.Error("expected PersistentPreRunE to set SilenceUsage on matched subcommand")
 			}
-			if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
-				t.Errorf("exit code = %d, want %d", gotCode, output.ExitValidation)
+			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 == nil || exitErr.Detail.Type != "external_provider" {
+				t.Errorf("error type = %v, want %q", exitErr.Detail, "external_provider")
 			}
 		})
 	}
--- a/cmd/auth/check.go
+++ b/cmd/auth/check.go
@@ -9,7 +9,6 @@ import (

 	"github.com/spf13/cobra"

-	"github.com/larksuite/cli/errs"
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/output"
@@ -38,7 +37,6 @@ func NewCmdAuthCheck(f *cmdutil.Factory, runF func(*CheckOptions) error) *cobra.

 	cmd.Flags().StringVar(&opts.Scope, "scope", "", "scopes to check (space-separated)")
 	cmd.MarkFlagRequired("scope")
-	cmdutil.SetRisk(cmd, "read")

 	return cmd
 }
@@ -48,7 +46,8 @@ func authCheckRun(opts *CheckOptions) error {

 	required := strings.Fields(opts.Scope)
 	if len(required) == 0 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--scope cannot be empty").WithParam("--scope")
+		output.PrintJson(f.IOStreams.Out, map[string]interface{}{"ok": true, "granted": []string{}, "missing": []string{}})
+		return nil
 	}

 	config, err := f.Config()
--- a/cmd/auth/check_test.go
+++ b/cmd/auth/check_test.go
@@ -1,167 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package auth
-
-import (
-	"encoding/json"
-	"errors"
-	"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/output"
-	"github.com/zalando/go-keyring"
-)
-
-// `lark-cli auth check` is a predicate command: its README contract is
-// `exit 0 = ok, 1 = missing`. The JSON answer goes to stdout; stderr stays
-// empty so callers can write `if lark-cli auth check ...; then ... fi`
-// without their logs getting polluted by an error envelope on the negative
-// branch. These tests pin that contract end-to-end through the dispatcher.
-
-func TestAuthCheckRun_NotLoggedIn_ExitOneWithStdoutOnly(t *testing.T) {
-	f, stdout, stderr, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-		// UserOpenId left empty: triggers the not_logged_in branch.
-	})
-
-	err := authCheckRun(&CheckOptions{Factory: f, Scope: "calendar:calendar:read"})
-
-	if got := output.ExitCodeOf(err); got != 1 {
-		t.Errorf("exit code = %d, want 1 (predicate 'missing' signal)", got)
-	}
-	var bare *output.ExitError
-	if !errors.As(err, &bare) {
-		t.Fatalf("expected *output.ExitError (ErrBare), got %T: %v", err, err)
-	}
-	if bare.Detail != nil {
-		t.Errorf("ErrBare must carry no Detail (no envelope), got %+v", bare.Detail)
-	}
-
-	if stderr.Len() != 0 {
-		t.Errorf("stderr must stay empty for predicate negative answer, got:\n%s", stderr.String())
-	}
-
-	var payload map[string]any
-	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
-		t.Fatalf("stdout must be valid JSON: %v\nstdout=%s", err, stdout.String())
-	}
-	if payload["ok"] != false {
-		t.Errorf("stdout.ok = %v, want false", payload["ok"])
-	}
-	if payload["error"] != "not_logged_in" {
-		t.Errorf("stdout.error = %v, want 'not_logged_in'", payload["error"])
-	}
-}
-
-func TestAuthCheckRun_NoStoredToken_ExitOneWithStdoutOnly(t *testing.T) {
-	f, stdout, stderr, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-		UserOpenId: "ou_user", UserName: "tester",
-	})
-
-	err := authCheckRun(&CheckOptions{Factory: f, Scope: "calendar:calendar:read"})
-
-	if got := output.ExitCodeOf(err); got != 1 {
-		t.Errorf("exit code = %d, want 1", got)
-	}
-	if stderr.Len() != 0 {
-		t.Errorf("stderr must stay empty, got:\n%s", stderr.String())
-	}
-
-	var payload map[string]any
-	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
-		t.Fatalf("stdout must be valid JSON: %v", err)
-	}
-	if payload["ok"] != false {
-		t.Errorf("stdout.ok = %v, want false", payload["ok"])
-	}
-	if payload["error"] != "no_token" {
-		t.Errorf("stdout.error = %v, want 'no_token'", payload["error"])
-	}
-}
-
-func TestAuthCheckRun_ScopedTokenPresent_ExitZero(t *testing.T) {
-	// Predicate command happy path: stored token covers every required
-	// scope. Exit must be 0 (nil error, not ErrBare), stdout carries the
-	// `{"ok":true,...}` JSON answer, and stderr stays empty so shell
-	// callers can rely on `if lark-cli auth check ...; then` without log
-	// pollution. Pairs with the two exit-1 negatives above so both
-	// branches of the predicate contract are pinned.
-	keyring.MockInit()
-	t.Setenv("HOME", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_DATA_DIR", t.TempDir())
-
-	cfg := &core.CliConfig{
-		AppID:      "test-app",
-		AppSecret:  "test-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:            "im:message docx:document",
-	}); err != nil {
-		t.Fatalf("SetStoredToken() error = %v", err)
-	}
-
-	f, stdout, stderr, _ := cmdutil.TestFactory(t, cfg)
-
-	err := authCheckRun(&CheckOptions{Factory: f, Scope: "im:message"})
-
-	if err != nil {
-		t.Fatalf("expected nil error for happy path (exit 0), got %v", err)
-	}
-	if got := output.ExitCodeOf(err); got != 0 {
-		t.Errorf("exit code = %d, want 0", got)
-	}
-	if stderr.Len() != 0 {
-		t.Errorf("stderr must stay empty for predicate exit-0 answer, got:\n%s", stderr.String())
-	}
-
-	var payload map[string]any
-	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
-		t.Fatalf("stdout must be valid JSON: %v\nstdout=%s", err, stdout.String())
-	}
-	if payload["ok"] != true {
-		t.Errorf("stdout.ok = %v, want true", payload["ok"])
-	}
-	granted, ok := payload["granted"].([]any)
-	if !ok || len(granted) != 1 || granted[0] != "im:message" {
-		t.Errorf("stdout.granted = %v, want [im:message]", payload["granted"])
-	}
-	if payload["missing"] != nil {
-		t.Errorf("stdout.missing = %v, want nil/absent on happy path", payload["missing"])
-	}
-	if _, has := payload["suggestion"]; has {
-		t.Errorf("stdout.suggestion must be absent on happy path; got %v", payload["suggestion"])
-	}
-}
-
-func TestAuthCheckRun_EmptyScopeIsValidationError(t *testing.T) {
-	// Scope validation is a real input error, not a predicate negative
-	// answer — it must surface as a typed ValidationError with the normal
-	// stderr envelope, distinct from the silent ErrBare predicate path.
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-
-	err := authCheckRun(&CheckOptions{Factory: f, Scope: "   "})
-	if err == nil {
-		t.Fatal("expected validation error for empty --scope")
-	}
-	if got := output.ExitCodeOf(err); got != output.ExitValidation {
-		t.Errorf("exit code = %d, want ExitValidation (%d)", got, output.ExitValidation)
-	}
-}
--- a/cmd/auth/list.go
+++ b/cmd/auth/list.go
@@ -34,7 +34,6 @@ func NewCmdAuthList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Co
 			return authListRun(opts)
 		},
 	}
-	cmdutil.SetRisk(cmd, "read")

 	return cmd
 }
--- a/cmd/auth/login.go
+++ b/cmd/auth/login.go
@@ -13,12 +13,9 @@ import (

 	"github.com/spf13/cobra"

-	"github.com/larksuite/cli/errs"
-
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/registry"
 	"github.com/larksuite/cli/shortcuts"
@@ -50,15 +47,12 @@ 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. Run it in the background and retrieve the verification URL from its output.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if mode := f.ResolveStrictMode(cmd.Context()); mode == core.StrictModeBot {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument,
-					"strict mode is %q, user login is disabled in this profile", mode).
-					WithHint("if the user explicitly wants to switch to user identity, see `lark-cli config strict-mode --help` (confirm with the user before switching; switching does NOT require re-bind)")
+				return output.ErrWithHint(output.ExitValidation, "strict_mode",
+					fmt.Sprintf("strict mode is %q, user login is disabled in this profile", mode),
+					"if the user explicitly wants to switch to user identity, see `lark-cli config strict-mode --help` (confirm with the user before switching; switching does NOT require re-bind)")
 			}
 			opts.Ctx = cmd.Context()
 			if runF != nil {
@@ -68,17 +62,10 @@ to generate QR codes (supports ASCII and PNG formats).`,
 		},
 	}
 	cmdutil.SetSupportedIdentities(cmd, []string{"user"})
-	cmdutil.SetRisk(cmd, "write")

 	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,
@@ -124,7 +111,7 @@ func authLoginRun(opts *LoginOptions) error {
 	}

 	// Determine UI language from saved config
-	var lang i18n.Lang
+	lang := "zh"
 	if multi, _ := core.LoadMultiAppConfig(); multi != nil {
 		if app := multi.FindApp(config.ProfileName); app != nil {
 			lang = app.Lang
@@ -149,25 +136,25 @@ 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 != "" {
-					return errs.NewValidationError(errs.SubtypeInvalidArgument, "unknown domain %q, did you mean %q?", d, suggestion).WithParam("--domain")
+					return output.ErrValidation("unknown domain %q, did you mean %q?", d, suggestion)
 				}
 				available := make([]string, 0, len(knownDomains))
 				for k := range knownDomains {
 					available = append(available, k)
 				}
 				sort.Strings(available)
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "unknown domain %q, available domains: %s", d, strings.Join(available, ", ")).WithParam("--domain")
+				return output.ErrValidation("unknown domain %q, available domains: %s", d, strings.Join(available, ", "))
 			}
 		}
 	}
@@ -175,17 +162,17 @@ func authLoginRun(opts *LoginOptions) error {
 	hasAnyOption := opts.Scope != "" || opts.Recommend || len(selectedDomains) > 0

 	if len(opts.Exclude) > 0 && !hasAnyOption {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--exclude requires --scope, --domain, or --recommend to be specified").WithParam("--exclude")
+		return output.ErrValidation("--exclude requires --scope, --domain, or --recommend to be specified")
 	}

 	if !hasAnyOption {
 		if !opts.JSON && f.IOStreams.IsTerminal {
-			result, err := runInteractiveLogin(f.IOStreams, lang.Base(), msg, config.Brand)
+			result, err := runInteractiveLogin(f.IOStreams, lang, msg)
 			if err != nil {
 				return err
 			}
 			if result == nil {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "no login options selected")
+				return output.ErrValidation("no login options selected")
 			}
 			selectedDomains = result.Domains
 			scopeLevel = result.ScopeLevel
@@ -200,8 +187,8 @@ func authLoginRun(opts *LoginOptions) error {
 			log("View all options:")
 			log(msg.HintFooter)
 			log("")
-			log("Note: this command blocks until authorization is complete. For non-streaming agent harnesses, use --no-wait --json, send the verification URL as the final message of the turn, then run --device-code in a later step after the user confirms authorization.")
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "please specify the scopes to authorize").WithParam("--scope")
+			log("Note: this command blocks until authorization is complete. Run it in the background and retrieve the verification URL from its output.")
+			return output.ErrValidation("please specify the scopes to authorize")
 		}
 	}

@@ -218,10 +205,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"
@@ -230,7 +217,7 @@ func authLoginRun(opts *LoginOptions) error {
 		}

 		if len(candidateScopes) == 0 && opts.Scope == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "no matching scopes found, check domain/scope options")
+			return output.ErrValidation("no matching scopes found, check domain/scope options")
 		}

 		// Merge --scope additively with the resolved domain scopes.
@@ -250,13 +237,13 @@ func authLoginRun(opts *LoginOptions) error {
 	if len(opts.Exclude) > 0 {
 		excluded, unknown := applyExcludeScopes(finalScope, opts.Exclude)
 		if len(unknown) > 0 {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument,
+			return output.ErrValidation(
 				"these --exclude scopes are not present in the requested set: %s",
-				strings.Join(unknown, ", ")).WithParam("--exclude")
+				strings.Join(unknown, ", "))
 		}
 		finalScope = excluded
 		if strings.TrimSpace(finalScope) == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "no scopes left after applying --exclude; nothing to authorize").WithParam("--exclude")
+			return output.ErrValidation("no scopes left after applying --exclude; nothing to authorize")
 		}
 	}

@@ -267,7 +254,7 @@ func authLoginRun(opts *LoginOptions) error {
 	}
 	authResp, err := larkauth.RequestDeviceAuthorization(httpClient, config.AppID, config.AppSecret, config.Brand, finalScope, f.IOStreams.ErrOut)
 	if err != nil {
-		return errs.NewAuthenticationError(errs.SubtypeUnknown, "device authorization failed: %v", err).WithCause(err)
+		return output.ErrAuth("device authorization failed: %v", err)
 	}

 	// --no-wait: return immediately with device code and URL
@@ -279,18 +266,12 @@ func authLoginRun(opts *LoginOptions) error {
 			"verification_url": authResp.VerificationUriComplete,
 			"device_code":      authResp.DeviceCode,
 			"expires_in":       authResp.ExpiresIn,
-			"hint": "**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. **Before ending the turn, tell the user to come back and notify you after completing authorization.**" +
-				"**After the user confirms authorization:** YOU must execute `lark-cli auth login --device-code <device_code>` yourself." +
-				"**Do NOT cache verification_url or device_code for future use.** Always run `lark-cli auth login --no-wait --json` fresh when authorization is needed.",
+			"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. Then immediately execute: lark-cli auth login --device-code %s (blocks until authorized or timeout). Do not instruct the user to run this command themselves.", authResp.DeviceCode),
 		}
 		encoder := json.NewEncoder(f.IOStreams.Out)
 		encoder.SetEscapeHTML(false)
 		if err := encoder.Encode(data); err != nil {
-			return errs.NewInternalError(errs.SubtypeSDKError, "failed to write JSON output: %v", err).WithCause(err)
+			return output.Errorf(output.ExitInternal, "internal", "failed to write JSON output: %v", err)
 		}
 		return nil
 	}
@@ -312,7 +293,7 @@ func authLoginRun(opts *LoginOptions) error {
 		encoder := json.NewEncoder(f.IOStreams.Out)
 		encoder.SetEscapeHTML(false)
 		if err := encoder.Encode(data); err != nil {
-			return errs.NewInternalError(errs.SubtypeSDKError, "failed to write JSON output: %v", err).WithCause(err)
+			return output.Errorf(output.ExitInternal, "internal", "failed to write JSON output: %v", err)
 		}
 	} else {
 		fmt.Fprintf(f.IOStreams.ErrOut, msg.OpenURL)
@@ -333,25 +314,25 @@ func authLoginRun(opts *LoginOptions) error {
 				"event": "authorization_failed",
 				"error": result.Message,
 			}); err != nil {
-				return errs.NewInternalError(errs.SubtypeSDKError, "failed to write JSON output: %v", err).WithCause(err)
+				return output.Errorf(output.ExitInternal, "internal", "failed to write JSON output: %v", err)
 			}
 			return output.ErrBare(output.ExitAuth)
 		}
-		return errs.NewAuthenticationError(errs.SubtypeUnknown, "authorization failed: %s", result.Message)
+		return output.ErrAuth("authorization failed: %s", result.Message)
 	}
 	if result.Token == nil {
-		return errs.NewAuthenticationError(errs.SubtypeTokenMissing, "authorization succeeded but no token returned")
+		return output.ErrAuth("authorization succeeded but no token returned")
 	}

 	// Step 6: Get user info
 	log(msg.AuthSuccess)
 	sdk, err := f.LarkClient()
 	if err != nil {
-		return errs.NewInternalError(errs.SubtypeSDKError, "failed to get SDK: %v", err).WithCause(err)
+		return output.ErrAuth("failed to get SDK: %v", err)
 	}
 	openId, userName, err := getUserInfo(opts.Ctx, sdk, result.Token.AccessToken)
 	if err != nil {
-		return errs.NewAuthenticationError(errs.SubtypeUnknown, "failed to get user info: %v", err).WithCause(err)
+		return output.ErrAuth("failed to get user info: %v", err)
 	}

 	scopeSummary := loadLoginScopeSummary(config.AppID, openId, finalScope, result.Token.Scope)
@@ -369,13 +350,13 @@ func authLoginRun(opts *LoginOptions) error {
 		GrantedAt:        now,
 	}
 	if err := larkauth.SetStoredToken(storedToken); err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "failed to save token: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "internal", "failed to save token: %v", err)
 	}

 	// Step 8: Update config — overwrite Users to single user, clean old tokens
 	if err := syncLoginUserToProfile(config.ProfileName, config.AppID, openId, userName); err != nil {
 		_ = larkauth.RemoveStoredToken(config.AppID, openId)
-		return err
+		return output.Errorf(output.ExitInternal, "internal", "failed to update login profile: %v", err)
 	}

 	if issue := ensureRequestedScopesGranted(finalScope, result.Token.Scope, msg, scopeSummary); issue != nil {
@@ -418,22 +399,22 @@ func authLoginPollDeviceCode(opts *LoginOptions, config *core.CliConfig, msg *lo
 		if shouldRemoveLoginRequestedScope(result) {
 			cleanupRequestedScope()
 		}
-		return errs.NewAuthenticationError(errs.SubtypeUnknown, "authorization failed: %s", result.Message)
+		return output.ErrAuth("authorization failed: %s", result.Message)
 	}
 	defer cleanupRequestedScope()
 	if result.Token == nil {
-		return errs.NewAuthenticationError(errs.SubtypeTokenMissing, "authorization succeeded but no token returned")
+		return output.ErrAuth("authorization succeeded but no token returned")
 	}

 	// Get user info
 	log(msg.AuthSuccess)
 	sdk, err := f.LarkClient()
 	if err != nil {
-		return errs.NewInternalError(errs.SubtypeSDKError, "failed to get SDK: %v", err).WithCause(err)
+		return output.ErrAuth("failed to get SDK: %v", err)
 	}
 	openId, userName, err := getUserInfo(opts.Ctx, sdk, result.Token.AccessToken)
 	if err != nil {
-		return errs.NewAuthenticationError(errs.SubtypeUnknown, "failed to get user info: %v", err).WithCause(err)
+		return output.ErrAuth("failed to get user info: %v", err)
 	}

 	scopeSummary := loadLoginScopeSummary(config.AppID, openId, requestedScope, result.Token.Scope)
@@ -451,13 +432,13 @@ func authLoginPollDeviceCode(opts *LoginOptions, config *core.CliConfig, msg *lo
 		GrantedAt:        now,
 	}
 	if err := larkauth.SetStoredToken(storedToken); err != nil {
-		return errs.NewInternalError(errs.SubtypeSDKError, "failed to save token: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "internal", "failed to save token: %v", err)
 	}

 	// Update config — overwrite Users to single user, clean old tokens
 	if err := syncLoginUserToProfile(config.ProfileName, config.AppID, openId, userName); err != nil {
 		_ = larkauth.RemoveStoredToken(config.AppID, openId)
-		return errs.NewInternalError(errs.SubtypeSDKError, "failed to update login profile: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "internal", "failed to update login profile: %v", err)
 	}

 	if issue := ensureRequestedScopesGranted(requestedScope, result.Token.Scope, msg, scopeSummary); issue != nil {
@@ -468,22 +449,21 @@ 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 {
-		return errs.NewInternalError(errs.SubtypeStorage, "load config: %v", err).WithCause(err)
+		return fmt.Errorf("load config: %w", err)
 	}

 	app := findProfileByName(multi, profileName)
 	if app == nil {
-		return errs.NewConfigError(errs.SubtypeNotConfigured, "profile %q not found in config", profileName)
+		return fmt.Errorf("profile %q not found in config", profileName)
 	}

 	oldUsers := append([]core.AppUser(nil), app.Users...)
 	app.Users = []core.AppUser{{UserOpenId: openID, UserName: userName}}
 	if err := core.SaveMultiAppConfig(multi); err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "save config: %v", err).WithCause(err)
+		return fmt.Errorf("save config: %w", err)
 	}

 	for _, oldUser := range oldUsers {
@@ -494,7 +474,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 {
@@ -508,7 +487,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
@@ -527,9 +506,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
@@ -549,7 +525,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) {
@@ -557,9 +533,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
 		}
@@ -568,8 +541,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)
--- a/cmd/auth/login_brand_filter_test.go
+++ b/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)
-	}
-}
--- a/cmd/auth/login_interactive.go
+++ b/cmd/auth/login_interactive.go
@@ -10,9 +10,7 @@ import (

 	"github.com/charmbracelet/huh"

-	"github.com/larksuite/cli/errs"
 	"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"
@@ -107,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
@@ -163,11 +161,11 @@ func runInteractiveLogin(ios *cmdutil.IOStreams, lang string, msg *loginMsg, bra
 	}

 	if len(selectedDomains) == 0 {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "no domains selected").WithParam("--domain")
+		return nil, output.ErrValidation("no domains selected")
 	}

 	// Compute scope summary
-	scopes := collectScopesForDomains(selectedDomains, "user", brand)
+	scopes := collectScopesForDomains(selectedDomains, "user")
 	if permLevel == "common" {
 		scopes = registry.FilterAutoApproveScopes(scopes)
 	}
--- a/cmd/auth/login_messages.go
+++ b/cmd/auth/login_messages.go
@@ -3,8 +3,6 @@

 package auth

-import "github.com/larksuite/cli/internal/i18n"
-
 type loginMsg struct {
 	// Interactive UI (login_interactive.go)
 	SelectDomains   string
@@ -61,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；如不支持长 timeout，请改用 `lark-cli auth login --no-wait --json` 拿到 device_code 后再用 `lark-cli auth login --device-code <code>` 续上轮询。**不要短 timeout 反复重试**，每次重启会作废上一轮的 device code，导致用户授权链接失效。向用户展示授权链接时，必须逐字原样转发 CLI 返回的 URL，把它视为不可修改的 opaque string；不要做 URL 编码或解码，不要补 `%20`、空格或标点，不要改写成 Markdown 链接，建议用只包含该 URL 的代码块单独输出。",
 	AuthSuccess:        "已收到授权确认，正在获取用户信息并校验授权结果...",
 	LoginSuccess:       "授权成功! 用户: %s (%s)",
 	AuthorizedUser:     "当前授权账号: %s (%s)",
@@ -97,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 long timeouts are not supported, use `lark-cli auth login --no-wait --json` to get a device_code, then `lark-cli auth login --device-code <code>` to resume polling. **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)",
@@ -116,9 +114,8 @@ var loginMsgEn = &loginMsg{
 	HintFooter:  "  lark-cli auth login --help",
 }

-// getLoginMsg returns the login message bundle for the given language.
-func getLoginMsg(lang i18n.Lang) *loginMsg {
-	if lang.IsEnglish() {
+func getLoginMsg(lang string) *loginMsg {
+	if lang == "en" {
 		return loginMsgEn
 	}
 	return loginMsgZh
@@ -128,5 +125,5 @@ func getLoginMsg(lang i18n.Lang) *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"}
 }
--- a/cmd/auth/login_messages_test.go
+++ b/cmd/auth/login_messages_test.go
@@ -8,8 +8,6 @@ import (
 	"reflect"
 	"strings"
 	"testing"
-
-	"github.com/larksuite/cli/internal/i18n"
 )

 func TestGetLoginMsg_Zh(t *testing.T) {
@@ -33,7 +31,7 @@ func TestGetLoginMsg_En(t *testing.T) {
 }

 func TestGetLoginMsg_DefaultsToZh(t *testing.T) {
-	for _, lang := range []i18n.Lang{"", "fr_fr", "ja_jp", "unknown"} {
+	for _, lang := range []string{"", "fr", "ja", "unknown"} {
 		msg := getLoginMsg(lang)
 		if msg != loginMsgZh {
 			t.Errorf("getLoginMsg(%q) should default to zh", lang)
@@ -63,7 +61,7 @@ func assertLoginMsgAllFieldsNonEmpty(t *testing.T, msg *loginMsg, label string)
 }

 func TestLoginMsg_FormatStrings(t *testing.T) {
-	for _, lang := range []i18n.Lang{i18n.LangZhCN, i18n.LangEnUS} {
+	for _, lang := range []string{"zh", "en"} {
 		msg := getLoginMsg(lang)

 		// LoginSuccess should contain two %s placeholders (userName, openId)
@@ -99,17 +97,16 @@ func TestLoginMsg_FormatStrings(t *testing.T) {
 }

 // TestAgentTimeoutHint_CarriesKeyInfo guards the contract that the synchronous
-// auth-login output tells AI agents three things: (a) this command blocks for
-// minutes — set a long runner timeout, (b) the alternative is the --no-wait +
-// --device-code split-flow, and (c) non-streaming harnesses must end the turn
-// after presenting the URL instead of blocking in the same turn.
+// auth-login output tells AI agents two things: (a) this command blocks for
+// minutes — set a long runner timeout, and (b) the alternative is the
+// --no-wait + --device-code split-flow. Without (a) AI sets a 10s timeout and
+// kills the process before the user can authorize; without (b) the AI has no
+// recovery path and just retries with the same short timeout, invalidating
+// each new device code in turn.
 func TestAgentTimeoutHint_CarriesKeyInfo(t *testing.T) {
-	for _, lang := range []i18n.Lang{i18n.LangZhCN, i18n.LangEnUS} {
+	for _, lang := range []string{"zh", "en"} {
 		hint := getLoginMsg(lang).AgentTimeoutHint
-		for _, want := range []string{"--no-wait", "--device-code", "turn"} {
-			if lang == i18n.LangZhCN && want == "turn" {
-				want = "本轮"
-			}
+		for _, want := range []string{"--no-wait", "--device-code"} {
 			if !strings.Contains(hint, want) {
 				t.Errorf("%s AgentTimeoutHint missing %q: %s", lang, want, hint)
 			}
--- a/cmd/auth/login_result.go
+++ b/cmd/auth/login_result.go
@@ -8,7 +8,6 @@ import (
 	"fmt"
 	"strings"

-	"github.com/larksuite/cli/errs"
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/output"
@@ -172,12 +171,20 @@ func handleLoginScopeIssue(opts *LoginOptions, msg *loginMsg, f *cmdutil.Factory
 			fmt.Fprintln(f.IOStreams.Out, string(b))
 			return output.ErrBare(output.ExitAuth)
 		}
-		return errs.NewPermissionError(errs.SubtypeMissingScope, "%s", issue.Message).
-			WithHint("%s", issue.Hint).
-			WithIdentity("user").
-			WithRequestedScopes(issue.Summary.Requested...).
-			WithGrantedScopes(issue.Summary.Granted...).
-			WithMissingScopes(issue.Summary.Missing...)
+		detail := map[string]interface{}{
+			"requested": issue.Summary.Requested,
+			"granted":   issue.Summary.Granted,
+			"missing":   issue.Summary.Missing,
+		}
+		return &output.ExitError{
+			Code: output.ExitAuth,
+			Detail: &output.ErrDetail{
+				Type:    "missing_scope",
+				Message: issue.Message,
+				Hint:    issue.Hint,
+				Detail:  detail,
+			},
+		}
 	}

 	fmt.Fprintln(f.IOStreams.ErrOut)
--- a/cmd/auth/login_result_test.go
+++ b/cmd/auth/login_result_test.go
@@ -1,61 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package auth
-
-import (
-	"errors"
-	"reflect"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-)
-
-// TestHandleLoginScopeIssue_FailedJSON_PreservesScopeTriple asserts that the
-// failed-login JSON branch (loginSucceeded == false, opts.JSON == true) wires
-// requested + granted + missing scopes into the typed *PermissionError
-// envelope. Consumers need the full triple to render actionable diagnostics,
-// not just the missing set.
-func TestHandleLoginScopeIssue_FailedJSON_PreservesScopeTriple(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-
-	requested := []string{"docx:document", "im:message:send"}
-	granted := []string{"docx:document"}
-	missing := []string{"im:message:send"}
-
-	err := handleLoginScopeIssue(
-		&LoginOptions{JSON: true},
-		getLoginMsg("en"),
-		f,
-		&loginScopeIssue{
-			Message: "scope insufficient",
-			Hint:    "re-login with --scope im:message:send",
-			Summary: &loginScopeSummary{
-				Requested: requested,
-				Granted:   granted,
-				Missing:   missing,
-			},
-		},
-		"", // openId empty -> loginSucceeded = false
-		"tester",
-	)
-
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-	var permErr *errs.PermissionError
-	if !errors.As(err, &permErr) {
-		t.Fatalf("expected *errs.PermissionError, got %T: %v", err, err)
-	}
-	if !reflect.DeepEqual(permErr.RequestedScopes, requested) {
-		t.Errorf("RequestedScopes = %v, want %v", permErr.RequestedScopes, requested)
-	}
-	if !reflect.DeepEqual(permErr.GrantedScopes, granted) {
-		t.Errorf("GrantedScopes = %v, want %v", permErr.GrantedScopes, granted)
-	}
-	if !reflect.DeepEqual(permErr.MissingScopes, missing) {
-		t.Errorf("MissingScopes = %v, want %v", permErr.MissingScopes, missing)
-	}
-}
--- a/cmd/auth/login_test.go
+++ b/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))
 	}
@@ -315,12 +315,10 @@ func TestAuthLoginRun_NonTerminal_NoFlags_RejectsWithHint(t *testing.T) {
 	if !strings.Contains(msg, "scopes") {
 		t.Errorf("expected error to mention scopes, got: %s", msg)
 	}
-	// Stderr should explain the split-flow path for non-streaming agents.
+	// Stderr should contain background hint
 	stderrStr := stderr.String()
-	for _, want := range []string{"--no-wait --json", "final message of the turn", "--device-code"} {
-		if !strings.Contains(stderrStr, want) {
-			t.Errorf("expected stderr to mention %q, got: %s", want, stderrStr)
-		}
+	if !strings.Contains(stderrStr, "background") {
+		t.Errorf("expected stderr to mention background, got: %s", stderrStr)
 	}
 }

@@ -400,11 +398,12 @@ func TestHandleLoginScopeIssue_NonJSONAlignsWithLoginSuccess(t *testing.T) {
 			Granted:   []string{"base:app:copy"},
 		},
 	}, "ou_user", "tester")
-	if err == nil {
-		t.Fatal("expected error, got nil")
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected ExitError, got %v", err)
 	}
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitAuth {
-		t.Fatalf("exit code = %d, want %d", gotCode, output.ExitAuth)
+	if exitErr.Code != output.ExitAuth {
+		t.Fatalf("exit code = %d, want %d", exitErr.Code, output.ExitAuth)
 	}
 	got := stderr.String()
 	for _, want := range []string{
@@ -442,11 +441,12 @@ func TestHandleLoginScopeIssue_JSONAlignsWithLoginSuccess(t *testing.T) {
 			Granted:   []string{"base:app:copy"},
 		},
 	}, "ou_user", "tester")
-	if err == nil {
-		t.Fatal("expected error, got nil")
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected ExitError, got %v", err)
 	}
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitAuth {
-		t.Fatalf("exit code = %d, want %d", gotCode, output.ExitAuth)
+	if exitErr.Code != output.ExitAuth {
+		t.Fatalf("exit code = %d, want %d", exitErr.Code, output.ExitAuth)
 	}

 	var data map[string]interface{}
@@ -651,11 +651,12 @@ func TestAuthLoginRun_MissingRequestedScopeAlignsWithLoginSuccess(t *testing.T)
 		Ctx:     context.Background(),
 		Scope:   "im:message:send",
 	})
-	if err == nil {
-		t.Fatal("expected error, got nil")
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected ExitError, got %v", err)
 	}
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitAuth {
-		t.Fatalf("exit code = %d, want %d", gotCode, output.ExitAuth)
+	if exitErr.Code != output.ExitAuth {
+		t.Fatalf("exit code = %d, want %d", exitErr.Code, output.ExitAuth)
 	}
 	got := stderr.String()
 	for _, want := range []string{
@@ -867,90 +868,6 @@ func TestAuthLoginRun_DeviceCodeTokenNilCleansScopeCache(t *testing.T) {
 	}
 }

-// TestAuthLoginRun_JSONAbort_StdoutEventOnly_StderrEmpty pins the
-// contract that when --json is set and pollDeviceToken returns OK=false,
-// stdout carries the structured authorization_failed event and stderr is
-// NOT polluted with a typed envelope. The returned error is a bare
-// ExitError with ExitAuth so the dispatcher only propagates the exit code
-// without emitting a second envelope on top of the JSON event.
-func TestAuthLoginRun_JSONAbort_StdoutEventOnly_StderrEmpty(t *testing.T) {
-	keyring.MockInit()
-	setupLoginConfigDir(t)
-
-	original := pollDeviceToken
-	t.Cleanup(func() { pollDeviceToken = original })
-	pollDeviceToken = func(ctx context.Context, httpClient *http.Client, appId, appSecret string, brand core.LarkBrand, deviceCode string, interval, expiresIn int, errOut io.Writer) *larkauth.DeviceFlowResult {
-		return &larkauth.DeviceFlowResult{OK: false, Message: "user denied"}
-	}
-
-	f, stdout, stderr, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		ProfileName: "default",
-		AppID:       "cli_test",
-		AppSecret:   "secret",
-		Brand:       core.BrandFeishu,
-	})
-
-	reg.Register(&httpmock.Stub{
-		Method: "POST",
-		URL:    larkauth.PathDeviceAuthorization,
-		Body: map[string]interface{}{
-			"device_code":               "device-code",
-			"user_code":                 "user-code",
-			"verification_uri":          "https://example.com/verify",
-			"verification_uri_complete": "https://example.com/verify?code=123",
-			"expires_in":                240,
-			"interval":                  0,
-		},
-	})
-
-	err := authLoginRun(&LoginOptions{
-		Factory: f,
-		Ctx:     context.Background(),
-		Scope:   "im:message:send",
-		JSON:    true,
-	})
-	if err == nil {
-		t.Fatal("expected error for aborted authorization")
-	}
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitAuth {
-		t.Fatalf("exit code = %d, want %d", gotCode, output.ExitAuth)
-	}
-
-	// stdout: device_authorization event + authorization_failed event,
-	// the latter carrying the abort message as a structured field.
-	stdoutStr := stdout.String()
-	if !strings.Contains(stdoutStr, `"event":"authorization_failed"`) {
-		t.Errorf("stdout missing authorization_failed event, got: %s", stdoutStr)
-	}
-	if !strings.Contains(stdoutStr, "user denied") {
-		t.Errorf("stdout missing abort message, got: %s", stdoutStr)
-	}
-
-	// stderr must NOT carry a typed envelope: ErrBare propagates the exit
-	// code only, so the dispatcher emits nothing on stderr. The waiting-auth
-	// log line goes through the JSON-mode no-op `log` helper so it is also
-	// suppressed in JSON mode.
-	stderrStr := stderr.String()
-	if strings.Contains(stderrStr, `"type":"authentication"`) {
-		t.Errorf("stderr should not contain typed envelope, got: %s", stderrStr)
-	}
-	if strings.Contains(stderrStr, `"error"`) {
-		t.Errorf("stderr should not contain JSON envelope fields, got: %s", stderrStr)
-	}
-
-	// Returned error must be the bare *output.ExitError signal (no envelope).
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
-	}
-	if exitErr.Code != output.ExitAuth {
-		t.Fatalf("ExitError.Code = %d, want %d", exitErr.Code, output.ExitAuth)
-	}
-	if exitErr.Detail != nil {
-		t.Errorf("ExitError.Detail should be nil for bare signal, got: %+v", exitErr.Detail)
-	}
-}
-
 func TestAuthLoginRun_JSONWriteFailure_NoWaitReturnsWriterError(t *testing.T) {
 	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
 		ProfileName: "default",
@@ -1026,40 +943,17 @@ 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",
-		"final message of the turn",
-		"return control to the user",
-		"do not block on --device-code in the same turn",
-		"come back and notify",
-		"YOU must execute",
-		"lark-cli auth login --device-code <device_code>",
-		"Do NOT cache",
-		"lark-cli auth login --no-wait --json",
+		"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",
 	} {
 		if !strings.Contains(hint, want) {
 			t.Fatalf("hint missing %q, got:\n%s", want, hint)
 		}
 	}
-	for _, unwanted := range []string{
-		"Then immediately execute",
-		"Do not instruct the user to run this command themselves",
-	} {
-		if strings.Contains(hint, unwanted) {
-			t.Fatalf("hint should not contain %q, got:\n%s", unwanted, hint)
-		}
-	}
 }

 func TestAuthLoginRun_JSONWriteFailure_DeviceAuthorizationReturnsWriterError(t *testing.T) {
@@ -1141,21 +1035,12 @@ func TestAuthLoginRun_JSONDeviceAuthorizationAgentHintIncludesRawURLGuidance(t *
 	hint, _ := data["agent_hint"].(string)
 	for _, want := range []string{
 		"timeout >= 600s",
-		"本轮最终消息",
-		"结束本轮",
-		"用户回复已完成授权",
-		"不要在同一轮里展示 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)
@@ -1173,7 +1058,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)")
 	}
@@ -1183,7 +1068,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 {
--- a/cmd/auth/logout.go
+++ b/cmd/auth/logout.go
@@ -8,7 +8,6 @@ import (

 	"github.com/spf13/cobra"

-	"github.com/larksuite/cli/errs"
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
@@ -34,7 +33,6 @@ func NewCmdAuthLogout(f *cmdutil.Factory, runF func(*LogoutOptions) error) *cobr
 			return authLogoutRun(opts)
 		},
 	}
-	cmdutil.SetRisk(cmd, "write")

 	return cmd
 }
@@ -61,7 +59,7 @@ func authLogoutRun(opts *LogoutOptions) error {
 	}
 	app.Users = []core.AppUser{}
 	if err := core.SaveMultiAppConfig(multi); err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 	}
 	output.PrintSuccess(f.IOStreams.ErrOut, "Logged out")
 	return nil
--- a/cmd/auth/qrcode.go
+++ b/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/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"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 errs.NewValidationError(errs.SubtypeInvalidArgument, "url is required").WithParam("--url")
-	}
-
-	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 errs.NewValidationError(errs.SubtypeInvalidArgument, "output file path is required for PNG mode. Use --output or -o flag to specify the output file path.").WithParam("--output")
-	}
-
-	if opts.Size < 32 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "size must be at least 32, got %d", opts.Size).WithParam("--size")
-	}
-
-	if opts.Size > 1024 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "size must be at most 1024, got %d", opts.Size).WithParam("--size")
-	}
-
-	safePath, err := validate.SafeOutputPath(opts.Output)
-	if err != nil {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe output path: %s", err).WithParam("--output").WithCause(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 errs.NewInternalError(errs.SubtypeSDKError, "failed to write output: %v", err).WithCause(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 errs.NewInternalError(errs.SubtypeSDKError, "failed to encode QR code: %v", err).WithCause(err)
-	}
-
-	err = vfs.WriteFile(outputPath, png, 0644)
-	if err != nil {
-		return errs.NewInternalError(errs.SubtypeSDKError, "failed to write QR code to %s: %v", outputPath, err).WithCause(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 errs.NewInternalError(errs.SubtypeSDKError, "failed to create QR code: %v", err).WithCause(err)
-	}
-
-	fmt.Fprint(w, q.ToSmallString(false))
-
-	return nil
-}
--- a/cmd/auth/qrcode_test.go
+++ b/cmd/auth/qrcode_test.go
@@ -1,324 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package auth
-
-import (
-	"encoding/json"
-	"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: ""})
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", gotCode, output.ExitValidation)
-	}
-}
-
-func TestRunQRCode_MissingOutput(t *testing.T) {
-	err := runQRCode(&QRCodeOptions{URL: "https://example.com", Size: 256})
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", gotCode, output.ExitValidation)
-	}
-}
-
-func TestRunQRCode_InvalidSize(t *testing.T) {
-	err := runQRCode(&QRCodeOptions{
-		URL:    "https://example.com",
-		Size:   16,
-		Output: "qr.png",
-	})
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", gotCode, output.ExitValidation)
-	}
-}
-
-func TestRunQRCode_SizeTooLarge(t *testing.T) {
-	err := runQRCode(&QRCodeOptions{
-		URL:    "https://example.com",
-		Size:   2048,
-		Output: "qr.png",
-	})
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", gotCode, output.ExitValidation)
-	}
-}
-
-func TestRunQRCode_UnsafeOutputPath(t *testing.T) {
-	err := runQRCode(&QRCodeOptions{
-		URL:    "https://example.com",
-		Size:   256,
-		Output: "/etc/passwd",
-	})
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", gotCode, 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")
-	}
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitInternal {
-		t.Errorf("exit code = %d, want %d", gotCode, output.ExitInternal)
-	}
-}
-
-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")
-	}
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-}
--- a/cmd/auth/scopes.go
+++ b/cmd/auth/scopes.go
@@ -9,7 +9,6 @@ import (

 	"github.com/spf13/cobra"

-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/output"
 )
@@ -38,7 +37,6 @@ func NewCmdAuthScopes(f *cmdutil.Factory, runF func(*ScopesOptions) error) *cobr
 	}

 	cmd.Flags().StringVar(&opts.Format, "format", "json", "output format: json (default) | pretty")
-	cmdutil.SetRisk(cmd, "read")

 	return cmd
 }
@@ -51,23 +49,11 @@ func authScopesRun(opts *ScopesOptions) error {
 		return err
 	}
 	fmt.Fprintf(f.IOStreams.ErrOut, "Querying app scopes...\n\n")
-	appInfo, err := getAppInfoFn(opts.Ctx, f, config.AppID)
+	appInfo, err := getAppInfo(opts.Ctx, f, config.AppID)
 	if err != nil {
-		// Discriminate by error type so transport / parse failures are not
-		// reclassified as PermissionError(MissingScope) — re-auth does not
-		// fix network / 5xx / JSON parse errors and misclassifying them
-		// here would mislead agents into re-auth loops.
-		//   - typed errors pass through unchanged
-		//   - bare errors become InternalError(SubtypeSDKError) with Cause
-		//     preserved so callers (errors.Is) can still see the underlying
-		//     transport/parse failure.
-		// Genuine permission failures are surfaced from appInfo *content*,
-		// not from this transport-level error path.
-		if errs.IsTyped(err) {
-			return err
-		}
-		return errs.NewInternalError(errs.SubtypeSDKError,
-			"failed to get app scope info: %v", err).WithCause(err)
+		return output.ErrWithHint(output.ExitAPI, "permission",
+			fmt.Sprintf("failed to get app scope info: %v", err),
+			"ensure the app has enabled the application:application:self_manage scope.")
 	}
 	if opts.Format == "pretty" {
 		fmt.Fprintf(f.IOStreams.ErrOut, "App ID: %s\n", config.AppID)
--- a/cmd/auth/scopes_test.go
+++ b/cmd/auth/scopes_test.go
@@ -1,121 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package auth
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-)
-
-// stubGetAppInfoErr swaps getAppInfoFn for the duration of t so authScopesRun
-// observes a fixed error from the dependency. t.Cleanup restores the prior
-// value so tests cannot leak through the package-level seam.
-func stubGetAppInfoErr(t *testing.T, errToReturn error) {
-	t.Helper()
-	prev := getAppInfoFn
-	getAppInfoFn = func(ctx context.Context, f *cmdutil.Factory, appId string) (*appInfo, error) {
-		return nil, errToReturn
-	}
-	t.Cleanup(func() { getAppInfoFn = prev })
-}
-
-// scopesTestFactory builds a Factory + ScopesOptions pair sufficient to drive
-// authScopesRun. Config has a non-empty AppID so we get past the config gate
-// and reach the getAppInfoFn call.
-func scopesTestFactory(t *testing.T) *ScopesOptions {
-	t.Helper()
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID:     "test-app",
-		AppSecret: "test-secret",
-		Brand:     core.BrandFeishu,
-	})
-	return &ScopesOptions{
-		Factory: f,
-		Ctx:     context.Background(),
-		Format:  "json",
-	}
-}
-
-// TestAuthScopesRun_NetworkErrorPassedThrough pins that a typed NetworkError
-// surfaced by the dependency is not re-classified as PermissionError —
-// re-auth does not fix DNS / transport failures and blanket-wrapping them
-// would mislead agents into infinite re-auth loops.
-func TestAuthScopesRun_NetworkErrorPassedThrough(t *testing.T) {
-	netErr := errs.NewNetworkError(errs.SubtypeNetworkDNS, "DNS lookup failed")
-	stubGetAppInfoErr(t, netErr)
-
-	err := authScopesRun(scopesTestFactory(t))
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-
-	var permErr *errs.PermissionError
-	if errors.As(err, &permErr) {
-		t.Errorf("network failure must not be classified as PermissionError; got %v", permErr)
-	}
-	var gotNet *errs.NetworkError
-	if !errors.As(err, &gotNet) {
-		t.Fatalf("network failure not preserved through authScopesRun; got %T: %v", err, err)
-	}
-	if gotNet != netErr {
-		t.Errorf("typed network error should pass through identity-stable; got %p, want %p", gotNet, netErr)
-	}
-}
-
-// TestAuthScopesRun_PermissionErrorPassedThrough pins that typed permission
-// failures from the dependency also pass through — IsTyped() must not single
-// out one category.
-func TestAuthScopesRun_PermissionErrorPassedThrough(t *testing.T) {
-	permErr := errs.NewPermissionError(errs.SubtypeMissingScope, "scope X missing").
-		WithMissingScopes("im:message")
-	stubGetAppInfoErr(t, permErr)
-
-	err := authScopesRun(scopesTestFactory(t))
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-	var got *errs.PermissionError
-	if !errors.As(err, &got) {
-		t.Fatalf("expected *PermissionError pass-through, got %T: %v", err, err)
-	}
-	if got != permErr {
-		t.Errorf("typed permission error should pass through identity-stable; got %p, want %p", got, permErr)
-	}
-}
-
-// TestAuthScopesRun_BareErrorWrappedAsInternal pins the unclassified branch:
-// a bare error (e.g. json.Unmarshal failure inside getAppInfo) surfaces as
-// *InternalError{SubtypeSDKError} with the original error preserved on
-// Cause so errors.Is still walks to it.
-func TestAuthScopesRun_BareErrorWrappedAsInternal(t *testing.T) {
-	bareErr := fmt.Errorf("failed to parse response: unexpected EOF")
-	stubGetAppInfoErr(t, bareErr)
-
-	err := authScopesRun(scopesTestFactory(t))
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-
-	var permErr *errs.PermissionError
-	if errors.As(err, &permErr) {
-		t.Errorf("bare getAppInfo error must not be classified as PermissionError; got %v", permErr)
-	}
-
-	var intErr *errs.InternalError
-	if !errors.As(err, &intErr) {
-		t.Fatalf("expected *InternalError, got %T: %v", err, err)
-	}
-	if intErr.Subtype != errs.SubtypeSDKError {
-		t.Errorf("InternalError.Subtype = %q, want %q", intErr.Subtype, errs.SubtypeSDKError)
-	}
-	if !errors.Is(err, bareErr) {
-		t.Error("InternalError must carry bareErr via WithCause so errors.Is walks to it")
-	}
-}
--- a/cmd/auth/status.go
+++ b/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"
 )

@@ -35,7 +37,6 @@ func NewCmdAuthStatus(f *cmdutil.Factory, runF func(*StatusOptions) error) *cobr
 	}

 	cmd.Flags().BoolVar(&opts.Verify, "verify", false, "verify token against server (requires network)")
-	cmdutil.SetRisk(cmd, "read")

 	return cmd
 }
@@ -58,59 +59,73 @@ func authStatusRun(opts *StatusOptions) error {
 		"defaultAs": defaultAs,
 	}

-	diagnostics := identitydiag.Diagnose(context.Background(), f, config, opts.Verify)
-	result["identities"] = diagnostics
-	result["identity"] = effectiveIdentity(diagnostics)
-	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"
-)
-
-func effectiveIdentity(d identitydiag.Result) string {
-	switch {
-	case d.User.Available:
-		return identityUser
-	case d.Bot.Available:
-		return identityBot
-	default:
-		return identityNone
+// 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 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
-			}
-		}
+	token, err := larkauth.GetValidAccessToken(httpClient, larkauth.NewUATCallOptions(config, f.IOStreams.ErrOut))
+	if err != nil {
+		return false, "token unusable: " + 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`."
+	sdk, err := f.LarkClient()
+	if err != nil {
+		return false, "failed to create SDK client: " + err.Error()
 	}
+
+	if err := larkauth.VerifyUserToken(context.Background(), sdk, token); err != nil {
+		return false, "server rejected token: " + err.Error()
+	}
+
+	return true, ""
 }
--- a/cmd/auth/status_test.go
+++ b/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"`
-}
--- a/cmd/build.go
+++ b/cmd/build.go
@@ -19,9 +19,7 @@ import (
 	cmdupdate "github.com/larksuite/cli/cmd/update"
 	_ "github.com/larksuite/cli/events"
 	"github.com/larksuite/cli/internal/build"
-	"github.com/larksuite/cli/internal/cmdpolicy"
 	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/hook"
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/shortcuts"
 	"github.com/spf13/cobra"
@@ -61,28 +59,18 @@ func HideProfile(hide bool) BuildOption {
 	}
 }

-// Build constructs the full command tree. It also installs registered
-// plugins and emits the Startup lifecycle event during assembly --
-// so Plugin.On(Startup) handlers run even if the returned command is
-// never dispatched. The matching Shutdown event is only emitted by
-// Execute; callers that bypass Execute will not see Shutdown fire.
-//
-// Returns only the cobra.Command; Factory and hook Registry are internal.
+// Build constructs the full command tree without executing.
+// Returns only the cobra.Command; Factory is internal.
 // Use Execute for the standard production entry point.
 func Build(ctx context.Context, inv cmdutil.InvocationContext, opts ...BuildOption) *cobra.Command {
-	_, rootCmd, _ := buildInternal(ctx, inv, opts...)
+	_, rootCmd := buildInternal(ctx, inv, opts...)
 	return rootCmd
 }

 // buildInternal is a pure assembly function: it wires the command tree from
 // inv and BuildOptions alone. Any state-dependent decision (disk, network,
 // env) belongs in the caller and must be threaded in via BuildOption.
-//
-// Returns (factory, rootCmd, registry). The registry is nil when plugin
-// install failed (FailClosed guard installed) or when no plugin produced
-// hooks; callers that wire Shutdown emit must nil-check before calling
-// hook.Emit.
-func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...BuildOption) (*cmdutil.Factory, *cobra.Command, *hook.Registry) {
+func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...BuildOption) (*cmdutil.Factory, *cobra.Command) {
 	// cfg.globals.Profile is left zero here; it's bound to the --profile
 	// flag in RegisterGlobalFlags and filled by cobra's parse step.
 	cfg := &buildConfig{}
@@ -136,42 +124,10 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 	service.RegisterServiceCommandsWithContext(ctx, rootCmd, f)
 	shortcuts.RegisterShortcutsWithContext(ctx, rootCmd, f)

-	installUnknownSubcommandGuard(rootCmd)
-
+	// Prune commands incompatible with strict mode.
 	if mode := f.ResolveStrictMode(ctx); mode.IsActive() {
 		pruneForStrictMode(rootCmd, mode)
 	}

-	installResult, installErr := installPluginsAndHooks(cfg.streams.ErrOut)
-	if installErr != nil {
-		installPluginInstallErrorGuard(rootCmd, installErr)
-		return f, rootCmd, nil
-	}
-	var pluginRules []cmdpolicy.PluginRule
-	var registry *hook.Registry
-	if installResult != nil {
-		pluginRules = installResult.PluginRules
-		registry = installResult.Registry
-	}
-
-	// Policy errors fail-CLOSED when a plugin contributed (security
-	// intent must not be silently dropped); yaml-only errors fail-OPEN
-	// with a warning so a typo can't lock the user out.
-	if err := applyUserPolicyPruning(rootCmd, pluginRules); err != nil {
-		if len(pluginRules) > 0 {
-			installPluginConflictGuard(rootCmd, err)
-			return f, rootCmd, nil
-		}
-		warnPolicyError(cfg.streams.ErrOut, err)
-	}
-
-	if registry != nil {
-		if err := wireHooks(ctx, rootCmd, registry); err != nil {
-			installPluginLifecycleErrorGuard(rootCmd, err)
-			return f, rootCmd, nil
-		}
-	}
-
-	recordInventory(installResult)
-	return f, rootCmd, registry
+	return f, rootCmd
 }
--- a/cmd/completion/completion.go
+++ b/cmd/completion/completion.go
@@ -37,6 +37,5 @@ func NewCmdCompletion(f *cmdutil.Factory) *cobra.Command {
 		},
 	}
 	cmdutil.DisableAuthCheck(cmd)
-	cmdutil.SetRisk(cmd, "read")
 	return cmd
 }
--- a/cmd/config/bind.go
+++ b/cmd/config/bind.go
@@ -12,10 +12,8 @@ import (
 	"github.com/charmbracelet/huh"
 	"github.com/spf13/cobra"

-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
@@ -39,10 +37,8 @@ type BindOptions struct {
 	// this flag because its own prompts already require human confirmation.
 	Force bool

-	Lang         string // raw --lang (string for cobra); normalized to canonical/"" in validateBindFlags
-	langExplicit bool   // true when --lang was explicitly passed
-
-	UILang i18n.Lang // TUI display language (picker-only); intentionally separate from --lang
+	Lang         string
+	langExplicit bool // true when --lang was explicitly passed

 	// Brand holds the resolved Lark product brand ("feishu" | "lark") for
 	// the account being bound. Populated after resolveAccount; TUI stages
@@ -59,7 +55,7 @@ type BindOptions struct {

 // NewCmdConfigBind creates the config bind subcommand.
 func NewCmdConfigBind(f *cmdutil.Factory, runF func(*BindOptions) error) *cobra.Command {
-	opts := &BindOptions{Factory: f, UILang: i18n.LangZhCN}
+	opts := &BindOptions{Factory: f}

 	cmd := &cobra.Command{
 		Use:   "bind",
@@ -106,8 +102,7 @@ Interactive terminal use: run with no flags to enter the TUI form.`,
 	cmd.Flags().StringVar(&opts.AppID, "app-id", "", "App ID to bind (required for OpenClaw multi-account)")
 	cmd.Flags().StringVar(&opts.Identity, "identity", "", "identity preset (bot-only|user-default); defaults to bot-only in flag mode (safer: no impersonation)")
 	cmd.Flags().BoolVar(&opts.Force, "force", false, "confirm a risky transition (currently: bot-only → user-default identity change in flag mode)")
-	cmd.Flags().StringVar(&opts.Lang, "lang", "", "language preference (e.g. zh or zh_cn)")
-	cmdutil.SetRisk(cmd, "write")
+	cmd.Flags().StringVar(&opts.Lang, "lang", "zh", "language for interactive prompts (zh|en)")

 	return cmd
 }
@@ -151,7 +146,7 @@ func configBindRun(opts *BindOptions) error {
 	if err := warnIdentityEscalation(opts, existing.ConfigBytes); err != nil {
 		return err
 	}
-	applyPreferences(appConfig, opts, priorLang(existing.ConfigBytes))
+	applyPreferences(appConfig, opts)
 	noticeUserDefaultRisk(opts)

 	return commitBinding(opts, appConfig, existing.ConfigBytes, source, targetConfigPath)
@@ -182,7 +177,7 @@ type existingBinding struct {
 func finalizeSource(opts *BindOptions) (string, error) {
 	explicit := strings.TrimSpace(strings.ToLower(opts.Source))
 	if explicit != "" && explicit != "openclaw" && explicit != "hermes" && explicit != "lark-channel" {
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --source %q; valid values: openclaw, hermes, lark-channel", explicit).WithParam("--source")
+		return "", output.ErrValidation("invalid --source %q; valid values: openclaw, hermes, lark-channel", explicit)
 	}

 	var detected string
@@ -199,26 +194,23 @@ func finalizeSource(opts *BindOptions) (string, error) {
 	// before any interactive prompts — running inside Hermes with
 	// --source openclaw (or vice versa) is almost always a mistake.
 	if explicit != "" && detected != "" && explicit != detected {
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"--source %q does not match detected Agent environment (%s)", explicit, detected).
-			WithHint("remove --source to auto-detect, or run this command in the correct Agent context").
-			WithParam("--source")
+		return "", output.ErrWithHint(output.ExitValidation, "bind",
+			fmt.Sprintf("--source %q does not match detected Agent environment (%s)", explicit, detected),
+			"remove --source to auto-detect, or run this command in the correct Agent context")
 	}

 	// TUI: prompt for language before any downstream prompts. The source
 	// selection itself may still be skipped entirely if --source or the
-	// env already pinned it. Picker offers 2 options (中文 / English) and
-	// drives BOTH opts.Lang (preference) and opts.UILang (TUI rendering).
+	// env already pinned it.
 	if opts.IsTUI && !opts.langExplicit {
-		lang, err := promptLangSelection()
+		lang, err := promptLangSelection("")
 		if err != nil {
 			if err == huh.ErrUserAborted {
 				return "", output.ErrBare(1)
 			}
-			return "", output.Errorf(output.ExitInternal, "internal", "language selection failed: %v", err)
+			return "", err
 		}
-		opts.Lang = string(lang)
-		opts.UILang = lang
+		opts.Lang = lang
 	}

 	if explicit != "" {
@@ -230,10 +222,9 @@ func finalizeSource(opts *BindOptions) (string, error) {
 	if opts.IsTUI {
 		return tuiSelectSource(opts)
 	}
-	return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-		"cannot determine Agent source: no --source flag and no Agent environment detected").
-		WithHint("pass --source openclaw|hermes|lark-channel, or run this command inside the corresponding Agent context").
-		WithParam("--source")
+	return "", output.ErrWithHint(output.ExitValidation, "bind",
+		"cannot determine Agent source: no --source flag and no Agent environment detected",
+		"pass --source openclaw|hermes|lark-channel, or run this command inside the corresponding Agent context")
 }

 // reconcileExistingBinding reads any existing config at configPath and decides
@@ -253,7 +244,7 @@ func reconcileExistingBinding(opts *BindOptions, source, configPath string) (exi
 			return existingBinding{}, err
 		}
 		if action == "cancel" {
-			msg := getBindMsg(opts.UILang)
+			msg := getBindMsg(opts.Lang)
 			fmt.Fprintln(opts.Factory.IOStreams.ErrOut, msg.ConflictCancelled)
 			return existingBinding{Cancelled: true}, nil
 		}
@@ -337,10 +328,9 @@ func warnIdentityEscalation(opts *BindOptions, previousConfigBytes []byte) error
 	if !hasStrictBotLock(previousConfigBytes) {
 		return nil
 	}
-	msg := getBindMsg(opts.UILang)
-	return errs.NewConfirmationRequiredError(errs.RiskHighRiskWrite,
-		"config bind --force", "%s", msg.IdentityEscalationMessage).
-		WithHint("%s", msg.IdentityEscalationHint)
+	msg := getBindMsg(opts.Lang)
+	return output.ErrWithHint(output.ExitValidation, "bind",
+		msg.IdentityEscalationMessage, msg.IdentityEscalationHint)
 }

 // noticeUserDefaultRisk surfaces the user-identity impersonation risk on every
@@ -356,23 +346,14 @@ func noticeUserDefaultRisk(opts *BindOptions) {
 	if opts.IsTUI || opts.Identity != "user-default" {
 		return
 	}
-	msg := getBindMsg(opts.UILang)
+	msg := getBindMsg(opts.Lang)
 	fmt.Fprintln(opts.Factory.IOStreams.ErrOut, "⚠️ "+msg.IdentityEscalationMessage)
 }

 // applyPreferences expands the chosen identity preset into the underlying
 // StrictMode + DefaultAs on the AppConfig. Always writes both fields so the
 // profile's intent survives later changes to global strict-mode settings.
-// preferredLang resolves the language to persist: the requested value when set,
-// otherwise the prior one — so an unset --lang never clears a stored preference.
-func preferredLang(requested, prior i18n.Lang) i18n.Lang {
-	if requested != "" {
-		return requested
-	}
-	return prior
-}
-
-func applyPreferences(appConfig *core.AppConfig, opts *BindOptions, prior i18n.Lang) {
+func applyPreferences(appConfig *core.AppConfig, opts *BindOptions) {
 	switch opts.Identity {
 	case "bot-only":
 		sm := core.StrictModeBot
@@ -383,23 +364,9 @@ func applyPreferences(appConfig *core.AppConfig, opts *BindOptions, prior i18n.L
 		appConfig.StrictMode = &sm
 		appConfig.DefaultAs = core.AsUser
 	}
-	appConfig.Lang = preferredLang(i18n.Lang(opts.Lang), prior)
-}
-
-// priorLang returns the language preference recorded in a previous config, or
-// "" if there is none / the bytes don't parse. Reads from CurrentApp (or Apps[0]
-// fallback) — scanning all apps for the first non-empty Lang would leak the
-// wrong profile's preference into a re-bind when the workspace holds multiple
-// named profiles and the active one disagrees with Apps[0].
-func priorLang(previousConfigBytes []byte) i18n.Lang {
-	var multi core.MultiAppConfig
-	if json.Unmarshal(previousConfigBytes, &multi) != nil {
-		return ""
+	if opts.Lang != "" {
+		appConfig.Lang = opts.Lang
 	}
-	if app := multi.CurrentAppConfig(""); app != nil {
-		return app.Lang
-	}
-	return ""
 }

 // commitBinding finalizes the bind: atomic write of the new workspace config,
@@ -411,21 +378,21 @@ func commitBinding(opts *BindOptions, appConfig *core.AppConfig, previousConfigB
 	multi := &core.MultiAppConfig{Apps: []core.AppConfig{*appConfig}}

 	if err := vfs.MkdirAll(core.GetConfigDir(), 0700); err != nil {
-		return errs.NewInternalError(errs.SubtypeFileIO, "failed to create workspace directory: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "bind",
+			"failed to create workspace directory: %v", err)
 	}
 	data, err := json.MarshalIndent(multi, "", "  ")
 	if err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "failed to marshal config: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "bind",
+			"failed to marshal config: %v", err)
 	}
 	if err := validate.AtomicWrite(configPath, append(data, '\n'), 0600); err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "failed to write config %s: %v", configPath, err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "bind",
+			"failed to write config %s: %v", configPath, err)
 	}

 	replaced := previousConfigBytes != nil
-	// uiMsg renders human-facing TUI text (stderr success banner). Follows
-	// opts.UILang — zh by default; picker can flip it to en. --lang does
-	// not influence the TUI language.
-	uiMsg := getBindMsg(opts.UILang)
+	msg := getBindMsg(opts.Lang)
 	display := sourceDisplayName(source)

 	if replaced {
@@ -433,11 +400,7 @@ func commitBinding(opts *BindOptions, appConfig *core.AppConfig, previousConfigB
 	}

 	fmt.Fprintln(opts.Factory.IOStreams.ErrOut,
-		fmt.Sprintf(uiMsg.BindSuccessHeader, display)+"\n"+uiMsg.BindSuccessNotice)
-
-	if opts.langExplicit && opts.Lang != "" {
-		fmt.Fprintln(opts.Factory.IOStreams.ErrOut, fmt.Sprintf(uiMsg.LangPreferenceSet, opts.Lang))
-	}
+		fmt.Sprintf(msg.BindSuccessHeader, display)+"\n"+msg.BindSuccessNotice)

 	// TUI mode is a human sitting at a terminal; the BindSuccess notice on
 	// stderr is enough and a machine-readable JSON dump on stdout is just
@@ -455,17 +418,12 @@ func commitBinding(opts *BindOptions, appConfig *core.AppConfig, previousConfigB
 		"replaced":    replaced,
 		"identity":    opts.Identity,
 	}
-	// JSON "message" follows the effective preference on disk (appConfig.Lang),
-	// not the raw --lang value: when --lang is omitted on re-bind, preferredLang
-	// has already inherited the prior preference into appConfig.Lang, and the
-	// message should respect that inherited choice. stderr above follows UILang.
-	prefMsg := getBindMsg(appConfig.Lang)
-	brand := brandDisplay(string(appConfig.Brand), appConfig.Lang)
+	brand := brandDisplay(string(appConfig.Brand), opts.Lang)
 	switch opts.Identity {
 	case "bot-only":
-		envelope["message"] = fmt.Sprintf(prefMsg.MessageBotOnly, appConfig.AppId, display, brand)
+		envelope["message"] = fmt.Sprintf(msg.MessageBotOnly, appConfig.AppId, display, brand)
 	case "user-default":
-		envelope["message"] = fmt.Sprintf(prefMsg.MessageUserDefault, appConfig.AppId, display, display)
+		envelope["message"] = fmt.Sprintf(msg.MessageUserDefault, appConfig.AppId, display, display)
 	}

 	resultJSON, _ := json.Marshal(envelope)
@@ -502,7 +460,7 @@ func cleanupKeychainFromData(kc keychain.KeychainAccess, data []byte, keep *core

 // tuiSelectSource prompts user to choose bind source.
 func tuiSelectSource(opts *BindOptions) (string, error) {
-	msg := getBindMsg(opts.UILang)
+	msg := getBindMsg(opts.Lang)
 	var source string

 	// Pre-select based on detected env signals
@@ -527,7 +485,7 @@ func tuiSelectSource(opts *BindOptions) (string, error) {
 		huh.NewGroup(
 			huh.NewSelect[string]().
 				Title(msg.SelectSource).
-				Description(fmt.Sprintf(msg.SelectSourceDesc, brandDisplay(opts.Brand, opts.UILang))).
+				Description(fmt.Sprintf(msg.SelectSourceDesc, brandDisplay(opts.Brand, opts.Lang))).
 				Options(
 					huh.NewOption(fmt.Sprintf(msg.SourceOpenClaw, openclawPath), "openclaw"),
 					huh.NewOption(fmt.Sprintf(msg.SourceHermes, hermesEnvPath), "hermes"),
@@ -549,7 +507,7 @@ func tuiSelectSource(opts *BindOptions) (string, error) {
 // tuiSelectApp prompts the user to choose from multiple account candidates.
 // Invoked only via selectCandidate's tuiPrompt callback, and only in TUI mode.
 func tuiSelectApp(opts *BindOptions, source string, candidates []Candidate) (*Candidate, error) {
-	msg := getBindMsg(opts.UILang)
+	msg := getBindMsg(opts.Lang)
 	options := make([]huh.Option[int], 0, len(candidates))
 	for i, c := range candidates {
 		label := c.AppID
@@ -563,7 +521,7 @@ func tuiSelectApp(opts *BindOptions, source string, candidates []Candidate) (*Ca
 	form := huh.NewForm(
 		huh.NewGroup(
 			huh.NewSelect[int]().
-				Title(fmt.Sprintf(msg.SelectAccount, sourceDisplayName(source), brandDisplay(opts.Brand, opts.UILang))).
+				Title(fmt.Sprintf(msg.SelectAccount, sourceDisplayName(source), brandDisplay(opts.Brand, opts.Lang))).
 				Options(options...).
 				Value(&selected),
 		),
@@ -580,7 +538,7 @@ func tuiSelectApp(opts *BindOptions, source string, candidates []Candidate) (*Ca

 // tuiConflictPrompt shows existing binding and asks user to Force or Cancel.
 func tuiConflictPrompt(opts *BindOptions, source, configPath string) (string, error) {
-	msg := getBindMsg(opts.UILang)
+	msg := getBindMsg(opts.Lang)

 	// Build existing binding summary
 	existingSummary := fmt.Sprintf(msg.ConflictDesc, source, "?", "?", configPath)
@@ -629,14 +587,9 @@ func validateBindFlags(opts *BindOptions) error {
 		switch opts.Identity {
 		case "bot-only", "user-default":
 		default:
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --identity %q; valid values: bot-only, user-default", opts.Identity).WithParam("--identity")
+			return output.ErrValidation("invalid --identity %q; valid values: bot-only, user-default", opts.Identity)
 		}
 	}
-	lang, err := cmdutil.ParseLangFlag(opts.Lang)
-	if err != nil {
-		return err
-	}
-	opts.Lang = string(lang)
 	return nil
 }

@@ -652,8 +605,8 @@ func validateBindFlags(opts *BindOptions) error {
 // DescriptionFunc approach breaks here because a longer description on
 // hover pushes options out of the field's initial viewport.
 func tuiSelectIdentity(opts *BindOptions) (string, error) {
-	msg := getBindMsg(opts.UILang)
-	brand := brandDisplay(opts.Brand, opts.UILang)
+	msg := getBindMsg(opts.Lang)
+	brand := brandDisplay(opts.Brand, opts.Lang)
 	botLabel := msg.IdentityBotOnly + "\n" + indent(fmt.Sprintf(msg.IdentityBotOnlyDesc, brand))
 	userLabel := msg.IdentityUserDefault + "\n" + indent(fmt.Sprintf(msg.IdentityUserDefaultDesc, brand, brand))
 	var value string
--- a/cmd/config/bind_messages.go
+++ b/cmd/config/bind_messages.go
@@ -3,8 +3,6 @@

 package config

-import "github.com/larksuite/cli/internal/i18n"
-
 // bindMsg holds all TUI text for config bind, supporting zh/en via --lang.
 //
 // Brand-aware strings use a %s slot where the UI-friendly product name
@@ -86,11 +84,6 @@ type bindMsg struct {
 	// require in-flow human confirmation.
 	IdentityEscalationMessage string
 	IdentityEscalationHint    string
-
-	// LangPreferenceSet is printed to stderr after a successful bind when the
-	// user explicitly passed --lang. Format: language code. Not printed when
-	// --lang was not explicit (i.e., the cobra default zh stayed in effect).
-	LangPreferenceSet string
 }

 var bindMsgZh = &bindMsg{
@@ -123,8 +116,6 @@ var bindMsgZh = &bindMsg{

 	IdentityEscalationMessage: "你正在从应用身份切换到用户身份 —— 切换后 AI 将以你的名义在飞书中执行所有操作（读写文档、搜索消息、修改日程等）。⚠️ 请勿将此机器人分享给他人或拉入群聊中使用，以免泄露你的飞书数据。",
 	IdentityEscalationHint:    "若用户确认切换，附加 --force 重新运行：`lark-cli config bind --identity user-default --force`",
-
-	LangPreferenceSet: "语言偏好已设置：%s",
 }

 var bindMsgEn = &bindMsg{
@@ -159,13 +150,10 @@ var bindMsgEn = &bindMsg{

 	IdentityEscalationMessage: "you are switching from bot-only to user-default — the AI will then act under your Feishu identity for all operations (docs, messages, calendar, etc.). ⚠️ Don't share this bot with others or add it to group chats. It has access to your personal Feishu data.",
 	IdentityEscalationHint:    "if the user confirms the switch, re-run with --force: `lark-cli config bind --identity user-default --force`",
-
-	LangPreferenceSet: "Language preference set to: %s",
 }

-// getBindMsg picks the zh/en TUI bundle; non-English falls back to zh.
-func getBindMsg(lang i18n.Lang) *bindMsg {
-	if lang.IsEnglish() {
+func getBindMsg(lang string) *bindMsg {
+	if lang == "en" {
 		return bindMsgEn
 	}
 	return bindMsgZh
@@ -176,11 +164,11 @@ func getBindMsg(lang i18n.Lang) *bindMsg {
 // "feishu" (or empty / unknown) maps to "飞书" in zh and "Feishu" in en —
 // this is the safe default when the brand hasn't been resolved yet (for
 // example, on the pre-binding source-selection screen).
-func brandDisplay(brand string, lang i18n.Lang) string {
+func brandDisplay(brand, lang string) string {
 	if brand == "lark" || brand == "Lark" || brand == "LARK" {
 		return "Lark"
 	}
-	if lang.IsEnglish() {
+	if lang == "en" {
 		return "Feishu"
 	}
 	return "飞书"
--- a/cmd/config/bind_test.go
+++ b/cmd/config/bind_test.go
@@ -13,59 +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/i18n"
 	"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 errors (ValidationError, ConfigError) — they normalize to the same
-// wantDetail fields. The wantDetail.Type is matched against the typed error's
-// Category string ("validation", "config", etc.).
+// 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)
 	}
-	var ce *errs.ConfigError
-	if errors.As(err, &ce) {
-		if got := output.ExitCodeOf(err); got != wantCode {
-			t.Errorf("exit code = %d, want %d", got, wantCode)
-		}
-		gotDetail := output.ErrDetail{Type: string(ce.Category), Message: ce.Message, Hint: ce.Hint}
-		if !reflect.DeepEqual(gotDetail, wantDetail) {
-			t.Errorf("config error mismatch:\n  got:  %+v\n  want: %+v", gotDetail, wantDetail)
-		}
-		return
+	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 / *errs.ConfigError; error = %v", err, err)
 }

 // assertEnvelope decodes stdout and checks it matches want exactly — every key
@@ -134,229 +105,14 @@ func TestConfigBindCmd_LangDefault(t *testing.T) {
 	if err := cmd.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	if gotOpts.Lang != "" {
-		t.Errorf("Lang = %q, want default %q (unset)", gotOpts.Lang, "")
+	if gotOpts.Lang != "zh" {
+		t.Errorf("Lang = %q, want default %q", gotOpts.Lang, "zh")
 	}
 	if gotOpts.langExplicit {
 		t.Error("expected langExplicit=false when --lang not passed")
 	}
 }

-// TestConfigBindRun_InvalidLang verifies a non-empty --lang is strictly
-// validated: wrong case, typos, and removed codes all exit with
-// ExitValidation (code 2) and a message identifying the offending value.
-// (Empty is not invalid — see TestConfigBindRun_EmptyLangIsNoOp.)
-func TestConfigBindRun_InvalidLang(t *testing.T) {
-	saveWorkspace(t)
-	configDir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", configDir)
-	hermesHome := t.TempDir()
-	t.Setenv("HERMES_HOME", hermesHome)
-	if err := os.WriteFile(filepath.Join(hermesHome, ".env"), []byte("FEISHU_APP_ID=cli_abc\nFEISHU_APP_SECRET=secret\n"), 0600); err != nil {
-		t.Fatalf("write .env: %v", err)
-	}
-
-	cases := []struct {
-		name string
-		lang string
-	}{
-		{"wrong case ZH", "ZH"},
-		{"typo frr", "frr"},
-		{"removed code ar", "ar"},
-		{"unknown xx", "xx"},
-		{"hyphen form zh-CN", "zh-CN"},
-	}
-
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			f, _, _, _ := cmdutil.TestFactory(t, nil)
-			err := configBindRun(&BindOptions{
-				Factory:      f,
-				Source:       "hermes",
-				Lang:         tc.lang,
-				langExplicit: true,
-			})
-			if err == nil {
-				t.Fatalf("expected validation error for --lang %q, got nil", tc.lang)
-			}
-			exitErr, ok := err.(*output.ExitError)
-			if !ok {
-				t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
-			}
-			if exitErr.Code != output.ExitValidation {
-				t.Errorf("exit code = %d, want %d (validation)", exitErr.Code, output.ExitValidation)
-			}
-			if !strings.Contains(exitErr.Error(), "invalid --lang") {
-				t.Errorf("error message %q does not contain 'invalid --lang'", exitErr.Error())
-			}
-		})
-	}
-}
-
-// TestConfigBindRun_EmptyLangIsNoOp verifies that an empty --lang (omitted or
-// explicit "") is unset: it neither errors nor persists a language, while a
-// non-empty short code or Feishu locale both canonicalize to the same locale.
-func TestConfigBindRun_EmptyLangIsNoOp(t *testing.T) {
-	cases := []struct {
-		name     string
-		lang     string
-		explicit bool
-		wantLang i18n.Lang
-	}{
-		{"omitted", "", false, ""},
-		{"explicit empty", "", true, ""},
-		{"short code", "ja", true, i18n.LangJaJP},
-		{"feishu locale", "ja_jp", true, i18n.LangJaJP},
-	}
-
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			saveWorkspace(t)
-			t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-			hermesHome := t.TempDir()
-			t.Setenv("HERMES_HOME", hermesHome)
-			if err := os.WriteFile(filepath.Join(hermesHome, ".env"), []byte("FEISHU_APP_ID=cli_abc\nFEISHU_APP_SECRET=secret\n"), 0600); err != nil {
-				t.Fatalf("write .env: %v", err)
-			}
-
-			f, _, _, _ := cmdutil.TestFactory(t, nil)
-			if err := configBindRun(&BindOptions{
-				Factory:      f,
-				Source:       "hermes",
-				Lang:         tc.lang,
-				langExplicit: tc.explicit,
-			}); err != nil {
-				t.Fatalf("configBindRun(--lang %q) = %v, want nil", tc.lang, err)
-			}
-
-			multi, err := core.LoadMultiAppConfig()
-			if err != nil {
-				t.Fatalf("LoadMultiAppConfig: %v", err)
-			}
-			app := multi.CurrentAppConfig("")
-			if app == nil {
-				t.Fatal("no app persisted")
-			}
-			if app.Lang != tc.wantLang {
-				t.Errorf("persisted Lang = %q, want %q", app.Lang, tc.wantLang)
-			}
-		})
-	}
-}
-
-// TestConfigBindRun_OmitLangPreservesPrior guards against a re-bind without
-// --lang silently dropping a previously stored preference (appConfig is rebuilt
-// fresh, so commitBinding must inherit the prior Lang).
-func TestConfigBindRun_OmitLangPreservesPrior(t *testing.T) {
-	saveWorkspace(t)
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	hermesHome := t.TempDir()
-	t.Setenv("HERMES_HOME", hermesHome)
-	if err := os.WriteFile(filepath.Join(hermesHome, ".env"), []byte("FEISHU_APP_ID=cli_abc\nFEISHU_APP_SECRET=secret\n"), 0600); err != nil {
-		t.Fatalf("write .env: %v", err)
-	}
-
-	f1, _, _, _ := cmdutil.TestFactory(t, nil)
-	if err := configBindRun(&BindOptions{Factory: f1, Source: "hermes", Lang: "ja", langExplicit: true}); err != nil {
-		t.Fatalf("first bind (--lang ja): %v", err)
-	}
-	f2, _, _, _ := cmdutil.TestFactory(t, nil)
-	if err := configBindRun(&BindOptions{Factory: f2, Source: "hermes", Lang: "", langExplicit: false}); err != nil {
-		t.Fatalf("re-bind (no --lang): %v", err)
-	}
-
-	multi, err := core.LoadMultiAppConfig()
-	if err != nil {
-		t.Fatalf("LoadMultiAppConfig: %v", err)
-	}
-	if app := multi.CurrentAppConfig(""); app == nil || app.Lang != i18n.LangJaJP {
-		t.Errorf("Lang after re-bind = %v, want %q (preserved)", app, i18n.LangJaJP)
-	}
-}
-
-// TestPriorLang_RespectsCurrentApp guards against priorLang scanning all apps
-// and silently returning a non-current profile's Lang. In a multi-profile
-// workspace (set up via `profile add` before a re-bind), the active profile's
-// Lang must win over a sibling profile that happens to sit earlier in the slice.
-func TestPriorLang_RespectsCurrentApp(t *testing.T) {
-	multi := core.MultiAppConfig{
-		CurrentApp: "active",
-		Apps: []core.AppConfig{
-			{Name: "stale", AppId: "cli_stale", Lang: i18n.LangJaJP},
-			{Name: "active", AppId: "cli_active", Lang: i18n.LangEnUS},
-		},
-	}
-	bytes, err := json.Marshal(multi)
-	if err != nil {
-		t.Fatalf("marshal: %v", err)
-	}
-	if got := priorLang(bytes); got != i18n.LangEnUS {
-		t.Errorf("priorLang = %q, want %q (must follow CurrentApp, not Apps[0])", got, i18n.LangEnUS)
-	}
-}
-
-// TestPriorLang_FallsBackToFirstAppWhenCurrentUnset covers the legacy
-// single-app shape (no CurrentApp): CurrentAppConfig falls back to Apps[0],
-// so a bind-written config (which always has exactly one app and no
-// CurrentApp field) still inherits its Lang.
-func TestPriorLang_FallsBackToFirstAppWhenCurrentUnset(t *testing.T) {
-	multi := core.MultiAppConfig{
-		Apps: []core.AppConfig{
-			{AppId: "cli_only", Lang: i18n.LangJaJP},
-		},
-	}
-	bytes, err := json.Marshal(multi)
-	if err != nil {
-		t.Fatalf("marshal: %v", err)
-	}
-	if got := priorLang(bytes); got != i18n.LangJaJP {
-		t.Errorf("priorLang = %q, want %q", got, i18n.LangJaJP)
-	}
-}
-
-// TestPriorLang_MalformedReturnsEmpty exercises the unparseable-bytes branch.
-func TestPriorLang_MalformedReturnsEmpty(t *testing.T) {
-	if got := priorLang([]byte("not json")); got != "" {
-		t.Errorf("priorLang(malformed) = %q, want \"\"", got)
-	}
-}
-
-// TestConfigBindRun_EnvelopeMessageFollowsInheritedLang guards the JSON envelope
-// "message" field against regressing to opts.Lang: when --lang is omitted on
-// re-bind, the inherited preference (appConfig.Lang) must drive the message
-// language and the embedded brand display — otherwise an AI agent that set
-// English on first bind sees Chinese in every subsequent re-bind envelope.
-func TestConfigBindRun_EnvelopeMessageFollowsInheritedLang(t *testing.T) {
-	saveWorkspace(t)
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	hermesHome := t.TempDir()
-	t.Setenv("HERMES_HOME", hermesHome)
-	if err := os.WriteFile(filepath.Join(hermesHome, ".env"), []byte("FEISHU_APP_ID=cli_abc\nFEISHU_APP_SECRET=secret\n"), 0600); err != nil {
-		t.Fatalf("write .env: %v", err)
-	}
-
-	f1, _, _, _ := cmdutil.TestFactory(t, nil)
-	if err := configBindRun(&BindOptions{Factory: f1, Source: "hermes", Lang: "en", langExplicit: true}); err != nil {
-		t.Fatalf("first bind (--lang en): %v", err)
-	}
-
-	f2, stdout, _, _ := cmdutil.TestFactory(t, nil)
-	if err := configBindRun(&BindOptions{Factory: f2, Source: "hermes", Lang: "", langExplicit: false}); err != nil {
-		t.Fatalf("re-bind (no --lang): %v", err)
-	}
-
-	envelope := map[string]any{}
-	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
-		t.Fatalf("invalid JSON output: %v", err)
-	}
-	msg, _ := envelope["message"].(string)
-	enMsg := getBindMsg(i18n.LangEnUS)
-	wantMsg := fmt.Sprintf(enMsg.MessageBotOnly, "cli_abc", "Hermes", brandDisplay("feishu", i18n.LangEnUS))
-	if msg != wantMsg {
-		t.Errorf("envelope.message = %q,\nwant %q (must follow inherited appConfig.Lang=en_us, not raw opts.Lang)", msg, wantMsg)
-	}
-}
-
 // ── Run function tests (aligned with TestConfigShowRun pattern) ──

 func TestConfigBindRun_InvalidSource(t *testing.T) {
@@ -383,7 +139,7 @@ func TestConfigBindRun_MissingSourceNonTTY(t *testing.T) {
 	// TestFactory has IsTerminal=false by default
 	err := configBindRun(&BindOptions{Factory: f, Source: ""})
 	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
-		Type:    "validation",
+		Type:    "bind",
 		Message: "cannot determine Agent source: no --source flag and no Agent environment detected",
 		Hint:    "pass --source openclaw|hermes|lark-channel, or run this command inside the corresponding Agent context",
 	})
@@ -422,7 +178,7 @@ func TestConfigBindRun_SourceEnvMismatch_OpenClawFlagInHermesEnv(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "openclaw"})
 	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
-		Type:    "validation",
+		Type:    "bind",
 		Message: `--source "openclaw" does not match detected Agent environment (hermes)`,
 		Hint:    "remove --source to auto-detect, or run this command in the correct Agent context",
 	})
@@ -438,7 +194,7 @@ func TestConfigBindRun_SourceEnvMismatch_HermesFlagInOpenClawEnv(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "hermes"})
 	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
-		Type:    "validation",
+		Type:    "bind",
 		Message: `--source "hermes" does not match detected Agent environment (openclaw)`,
 		Hint:    "remove --source to auto-detect, or run this command in the correct Agent context",
 	})
@@ -566,8 +322,8 @@ func TestConfigBindRun_HermesMissingEnvFile(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "hermes"})
 	envPath := filepath.Join(hermesHome, ".env")
-	assertExitError(t, err, output.ExitAuth, output.ErrDetail{
-		Type:    "config",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "hermes",
 		Message: "failed to read Hermes config: open " + envPath + ": no such file or directory",
 		Hint:    "verify Hermes is installed and configured at " + envPath,
 	})
@@ -584,8 +340,8 @@ func TestConfigBindRun_OpenClawMissingFile(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "openclaw"})
 	configPath := filepath.Join(openclawHome, ".openclaw", "openclaw.json")
-	assertExitError(t, err, output.ExitAuth, output.ErrDetail{
-		Type:    "config",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "openclaw",
 		Message: "cannot read " + configPath + ": open " + configPath + ": no such file or directory",
 		Hint:    "verify OpenClaw is installed and configured",
 	})
@@ -652,26 +408,6 @@ func TestConfigBindRun_LarkChannel_Success(t *testing.T) {
 	}
 }

-// Env template form: secret = "${VAR}" should resolve via the SecretInput
-// pipeline (same path openclaw uses), so the keychain receives the env value
-// not the literal template string.
-func TestConfigBindRun_LarkChannel_EnvTemplate(t *testing.T) {
-	saveWorkspace(t)
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	clearAgentEnv(t)
-
-	fakeHome := t.TempDir()
-	t.Setenv("HOME", fakeHome)
-	t.Setenv("LARK_APP_SECRET", "resolved_via_env")
-	writeLarkChannelFixture(t, fakeHome,
-		`{"accounts":{"app":{"id":"cli_lc_env","secret":"${LARK_APP_SECRET}","tenant":"feishu"}}}`)
-
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-	if err := configBindRun(&BindOptions{Factory: f, Source: "lark-channel"}); err != nil {
-		t.Fatalf("expected success, got error: %v", err)
-	}
-}
-
 // tenant: "lark" should land as Brand("lark"), not normalized to "feishu".
 func TestConfigBindRun_LarkChannel_LarkTenant(t *testing.T) {
 	saveWorkspace(t)
@@ -732,7 +468,7 @@ func TestConfigBindRun_SourceEnvMismatch_LarkChannelFlagInOpenClawEnv(t *testing
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "lark-channel"})
 	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
-		Type:    "validation",
+		Type:    "bind",
 		Message: `--source "lark-channel" does not match detected Agent environment (openclaw)`,
 		Hint:    "remove --source to auto-detect, or run this command in the correct Agent context",
 	})
@@ -750,8 +486,8 @@ func TestConfigBindRun_LarkChannelMissingFile(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "lark-channel"})
 	configPath := filepath.Join(fakeHome, ".lark-channel", "config.json")
-	assertExitError(t, err, output.ExitAuth, output.ErrDetail{
-		Type:    "config",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "lark-channel",
 		Message: "cannot read " + configPath + ": open " + configPath + ": no such file or directory",
 		Hint:    "verify lark-channel-bridge is installed and configured",
 	})
@@ -770,8 +506,8 @@ func TestConfigBindRun_LarkChannelEmptyAppID(t *testing.T) {

 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "lark-channel"})
-	assertExitError(t, err, output.ExitAuth, output.ErrDetail{
-		Type:    "config",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "lark-channel",
 		Message: "accounts.app.id missing in " + configPath,
 		Hint:    "run lark-channel-bridge's setup to populate the app credential",
 	})
@@ -789,8 +525,8 @@ func TestConfigBindRun_LarkChannelEmptySecret(t *testing.T) {

 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "lark-channel"})
-	assertExitError(t, err, output.ExitAuth, output.ErrDetail{
-		Type:    "config",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "lark-channel",
 		Message: "accounts.app.secret is empty in " + configPath,
 		Hint:    "run lark-channel-bridge's setup to populate the app credential",
 	})
@@ -839,10 +575,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")
@@ -1141,8 +875,12 @@ func TestConfigBindRun_OpenClawMultiAccount_MissingAppID(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected error for multi-account without --app-id, got nil")
 	}
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", gotCode, output.ExitValidation)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("error type = %T, want *output.ExitError", err)
+	}
+	if exitErr.Code != output.ExitValidation {
+		t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
 	}
 }

@@ -1188,7 +926,7 @@ func TestConfigBindRun_OpenClawMultiAccount_TTYFlagMode(t *testing.T) {
 	// each accepted variant so every ErrDetail field (Type, Code, Message,
 	// Hint, ConsoleURL, Detail, and any future addition) is still compared.
 	base := output.ErrDetail{
-		Type:    "validation",
+		Type:    "openclaw",
 		Message: "multiple accounts in openclaw.json; pass --app-id <id>",
 	}
 	wantWorkFirst := base
@@ -1196,17 +934,20 @@ func TestConfigBindRun_OpenClawMultiAccount_TTYFlagMode(t *testing.T) {
 	wantPersonalFirst := base
 	wantPersonalFirst.Hint = "available app IDs:\n  cli_personal_222 (personal)\n  cli_work_111 (work)"

-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", gotCode, output.ExitValidation)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("error type = %T, want *output.ExitError; err = %v", err, err)
 	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("error type = %T, want *errs.ValidationError; err = %v", err, err)
+	if exitErr.Code != output.ExitValidation {
+		t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
 	}
-	got := output.ErrDetail{Type: string(ve.Category), Message: ve.Message, Hint: ve.Hint}
-	if !reflect.DeepEqual(got, wantWorkFirst) && !reflect.DeepEqual(got, wantPersonalFirst) {
+	if exitErr.Detail == nil {
+		t.Fatal("expected non-nil error detail")
+	}
+	if !reflect.DeepEqual(*exitErr.Detail, wantWorkFirst) &&
+		!reflect.DeepEqual(*exitErr.Detail, wantPersonalFirst) {
 		t.Errorf("error detail did not match any accepted variant:\n  got:  %+v\n  want: %+v OR %+v",
-			got, wantWorkFirst, wantPersonalFirst)
+			*exitErr.Detail, wantWorkFirst, wantPersonalFirst)
 	}
 }

@@ -1231,7 +972,7 @@ func TestConfigBindRun_OpenClawMultiAccount_WrongAppID(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "openclaw", AppID: "nonexistent"})
 	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
-		Type:    "validation",
+		Type:    "openclaw",
 		Message: `--app-id "nonexistent" not found in openclaw.json`,
 		Hint:    "available app IDs:\n  cli_only_one",
 	})
@@ -1363,19 +1104,11 @@ func TestConfigBindRun_WarnsOnIdentityEscalationWithoutForce(t *testing.T) {
 		Identity: "user-default",
 	})
 	msg := getBindMsg("zh") // flag mode leaves Lang empty → zh default
-	var ce *errs.ConfirmationRequiredError
-	if !errors.As(err, &ce) {
-		t.Fatalf("error type = %T, want *errs.ConfirmationRequiredError; error = %v", err, err)
-	}
-	if ce.Risk != errs.RiskHighRiskWrite {
-		t.Errorf("Risk = %q, want %q", ce.Risk, errs.RiskHighRiskWrite)
-	}
-	if ce.Message != msg.IdentityEscalationMessage {
-		t.Errorf("Message mismatch:\ngot:  %q\nwant: %q", ce.Message, msg.IdentityEscalationMessage)
-	}
-	if ce.Hint != msg.IdentityEscalationHint {
-		t.Errorf("Hint mismatch:\ngot:  %q\nwant: %q", ce.Hint, msg.IdentityEscalationHint)
-	}
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "bind",
+		Message: msg.IdentityEscalationMessage,
+		Hint:    msg.IdentityEscalationHint,
+	})

 	// Config on disk must remain untouched — the gate runs before
 	// commitBinding writes anything.
@@ -1536,8 +1269,8 @@ func TestConfigBindRun_HermesMissingAppID(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "hermes"})
 	envPath := filepath.Join(hermesHome, ".env")
-	assertExitError(t, err, output.ExitAuth, output.ErrDetail{
-		Type:    "config",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "hermes",
 		Message: "FEISHU_APP_ID not found in " + envPath,
 		Hint:    "run 'hermes setup' to configure Feishu credentials",
 	})
@@ -1556,8 +1289,8 @@ func TestConfigBindRun_HermesMissingAppSecret(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "hermes"})
 	envPath := filepath.Join(hermesHome, ".env")
-	assertExitError(t, err, output.ExitAuth, output.ErrDetail{
-		Type:    "config",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "hermes",
 		Message: "FEISHU_APP_SECRET not found in " + envPath,
 		Hint:    "run 'hermes setup' to configure Feishu credentials",
 	})
@@ -1582,8 +1315,8 @@ func TestConfigBindRun_OpenClawMissingFeishu(t *testing.T) {

 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "openclaw"})
-	assertExitError(t, err, output.ExitAuth, output.ErrDetail{
-		Type:    "config",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "openclaw",
 		Message: "openclaw.json missing channels.feishu section",
 		Hint:    "configure Feishu in OpenClaw first",
 	})
@@ -1610,8 +1343,8 @@ func TestConfigBindRun_OpenClawEmptyAppSecret(t *testing.T) {
 	openclawPath := filepath.Join(openclawDir, "openclaw.json")
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "openclaw"})
-	assertExitError(t, err, output.ExitAuth, output.ErrDetail{
-		Type:    "config",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "openclaw",
 		Message: "appSecret is empty for app cli_no_secret in " + openclawPath,
 		Hint:    "configure channels.feishu.appSecret in openclaw.json",
 	})
@@ -1672,8 +1405,8 @@ func TestConfigBindRun_OpenClawDisabledAccount(t *testing.T) {

 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "openclaw"})
-	assertExitError(t, err, output.ExitAuth, output.ErrDetail{
-		Type:    "config",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "openclaw",
 		Message: "no Feishu app configured in openclaw.json",
 		Hint:    "configure channels.feishu.appId in openclaw.json",
 	})
@@ -1704,14 +1437,10 @@ func TestGetBindMsg_En(t *testing.T) {
 	}
 }

-func TestGetBindMsg_NonEnLang_FallsBackToZh(t *testing.T) {
-	// Only zh and en TUI bundles exist; any non-English language (canonical
-	// locale, short code, or unrecognized value) falls back to zh.
-	for _, lang := range []i18n.Lang{"fr_fr", "ja_jp", "ko", "unknown", ""} {
-		msg := getBindMsg(lang)
-		if want := "你想在哪个 Agent 中使用 lark-cli?"; msg.SelectSource != want {
-			t.Errorf("getBindMsg(%q) SelectSource = %q, want %q (zh fallback)", lang, msg.SelectSource, want)
-		}
+func TestGetBindMsg_UnknownLang_DefaultsToZh(t *testing.T) {
+	msg := getBindMsg("fr")
+	if want := "你想在哪个 Agent 中使用 lark-cli?"; msg.SelectSource != want {
+		t.Errorf("fr (default) SelectSource = %q, want %q", msg.SelectSource, want)
 	}
 }

@@ -1874,36 +1603,3 @@ func TestHasStrictBotLock(t *testing.T) {
 		})
 	}
 }
-
-// TestConfigBindRun_LangExplicit_PrintsConfirmation covers the flag-mode
-// confirmation line: when --lang is explicit, bind prints "language preference
-// set" to stderr (rendered in the TUI language, embedding the preference value).
-func TestConfigBindRun_LangExplicit_PrintsConfirmation(t *testing.T) {
-	saveWorkspace(t)
-	configDir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", configDir)
-
-	hermesHome := t.TempDir()
-	t.Setenv("HERMES_HOME", hermesHome)
-	if err := os.WriteFile(filepath.Join(hermesHome, ".env"), []byte("FEISHU_APP_ID=cli_abc\nFEISHU_APP_SECRET=secret\n"), 0600); err != nil {
-		t.Fatalf("write .env: %v", err)
-	}
-
-	f, _, stderr, _ := cmdutil.TestFactory(t, nil)
-	err := configBindRun(&BindOptions{
-		Factory:      f,
-		Source:       "hermes",
-		Identity:     "bot-only",
-		Lang:         "en",
-		langExplicit: true,
-	})
-	if err != nil {
-		t.Fatalf("expected success, got error: %v", err)
-	}
-	// The short --lang en is canonicalized to en_us before the confirmation
-	// echoes it back; the TUI language stays zh (flag mode, no picker).
-	want := fmt.Sprintf(getBindMsg(i18n.LangZhCN).LangPreferenceSet, "en_us")
-	if got := stderr.String(); !strings.Contains(got, want) {
-		t.Errorf("stderr = %q, want it to contain confirmation %q", got, want)
-	}
-}
--- a/cmd/config/binder.go
+++ b/cmd/config/binder.go
@@ -9,9 +9,9 @@ import (
 	"path/filepath"
 	"strings"

-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/binding"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/vfs"
 )

@@ -49,7 +49,7 @@ func newBinder(source string, opts *BindOptions) (SourceBinder, error) {
 	case "lark-channel":
 		return &larkChannelBinder{opts: opts, path: resolveLarkChannelConfigPath()}, nil
 	default:
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported source: %s", source).WithParam("--source")
+		return nil, output.ErrValidation("unsupported source: %s", source)
 	}
 }

@@ -85,10 +85,11 @@ func selectCandidate(
 		// from ListCandidates itself and never reach here.
 		switch src {
 		case "openclaw":
-			return nil, errs.NewConfigError(errs.SubtypeNotConfigured, "no Feishu app configured in openclaw.json").
-				WithHint("configure channels.feishu.appId in openclaw.json")
+			return nil, output.ErrWithHint(output.ExitValidation, src,
+				"no Feishu app configured in openclaw.json",
+				"configure channels.feishu.appId in openclaw.json")
 		default:
-			return nil, errs.NewConfigError(errs.SubtypeNotConfigured, "%s: no app configured", src)
+			return nil, output.ErrValidation("%s: no app configured", src)
 		}
 	}

@@ -98,9 +99,9 @@ func selectCandidate(
 				return &candidates[i], nil
 			}
 		}
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--app-id %q not found in %s", appIDFlag, cfgBase).
-			WithHint("available app IDs:\n  %s", formatCandidates(candidates)).
-			WithParam("--app-id")
+		return nil, output.ErrWithHint(output.ExitValidation, src,
+			fmt.Sprintf("--app-id %q not found in %s", appIDFlag, cfgBase),
+			fmt.Sprintf("available app IDs:\n  %s", formatCandidates(candidates)))
 	}

 	if len(candidates) == 1 {
@@ -111,9 +112,9 @@ func selectCandidate(
 		return tuiPrompt(candidates)
 	}

-	return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "multiple accounts in %s; pass --app-id <id>", cfgBase).
-		WithHint("available app IDs:\n  %s", formatCandidates(candidates)).
-		WithParam("--app-id")
+	return nil, output.ErrWithHint(output.ExitValidation, src,
+		fmt.Sprintf("multiple accounts in %s; pass --app-id <id>", cfgBase),
+		fmt.Sprintf("available app IDs:\n  %s", formatCandidates(candidates)))
 }

 // formatCandidates renders candidates as "AppID (Label)" lines for error hints.
@@ -148,13 +149,14 @@ func (b *openclawBinder) ConfigPath() string { return b.path }
 func (b *openclawBinder) ListCandidates() ([]Candidate, error) {
 	cfg, err := binding.ReadOpenClawConfig(b.path)
 	if err != nil {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidConfig, "cannot read %s: %v", b.path, err).
-			WithHint("verify OpenClaw is installed and configured").
-			WithCause(err)
+		return nil, output.ErrWithHint(output.ExitValidation, "openclaw",
+			fmt.Sprintf("cannot read %s: %v", b.path, err),
+			"verify OpenClaw is installed and configured")
 	}
 	if cfg.Channels.Feishu == nil {
-		return nil, errs.NewConfigError(errs.SubtypeNotConfigured, "openclaw.json missing channels.feishu section").
-			WithHint("configure Feishu in OpenClaw first")
+		return nil, output.ErrWithHint(output.ExitValidation, "openclaw",
+			"openclaw.json missing channels.feishu section",
+			"configure Feishu in OpenClaw first")
 	}

 	raw := binding.ListCandidateApps(cfg.Channels.Feishu)
@@ -170,7 +172,8 @@ func (b *openclawBinder) ListCandidates() ([]Candidate, error) {

 func (b *openclawBinder) Build(appID string) (*core.AppConfig, error) {
 	if b.cfg == nil {
-		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: Build called before ListCandidates")
+		return nil, output.Errorf(output.ExitInternal, "openclaw",
+			"internal: Build called before ListCandidates")
 	}

 	var selected *binding.CandidateApp
@@ -181,25 +184,26 @@ func (b *openclawBinder) Build(appID string) (*core.AppConfig, error) {
 		}
 	}
 	if selected == nil {
-		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: appID %q not in candidates", appID)
+		return nil, output.Errorf(output.ExitInternal, "openclaw",
+			"internal: appID %q not in candidates", appID)
 	}

 	if selected.AppSecret.IsZero() {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "appSecret is empty for app %s in %s", selected.AppID, b.path).
-			WithHint("configure channels.feishu.appSecret in openclaw.json")
+		return nil, output.ErrWithHint(output.ExitValidation, "openclaw",
+			fmt.Sprintf("appSecret is empty for app %s in %s", selected.AppID, b.path),
+			"configure channels.feishu.appSecret in openclaw.json")
 	}
 	secret, err := binding.ResolveSecretInput(selected.AppSecret, b.cfg.Secrets, os.Getenv)
 	if err != nil {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "failed to resolve appSecret for %s: %v", selected.AppID, err).
-			WithHint("check appSecret configuration in %s", b.path).
-			WithCause(err)
+		return nil, output.ErrWithHint(output.ExitValidation, "openclaw",
+			fmt.Sprintf("failed to resolve appSecret for %s: %v", selected.AppID, err),
+			fmt.Sprintf("check appSecret configuration in %s", b.path))
 	}

 	stored, err := core.ForStorage(selected.AppID, core.PlainSecret(secret), b.opts.Factory.Keychain)
 	if err != nil {
-		return nil, errs.NewInternalError(errs.SubtypeStorage, "keychain unavailable: %v", err).
-			WithHint("use file: reference in config to bypass keychain").
-			WithCause(err)
+		return nil, output.Errorf(output.ExitInternal, "openclaw",
+			"keychain unavailable: %v\nhint: use file: reference in config to bypass keychain", err)
 	}

 	return &core.AppConfig{
@@ -225,14 +229,15 @@ func (b *hermesBinder) ConfigPath() string { return b.path }
 func (b *hermesBinder) ListCandidates() ([]Candidate, error) {
 	envMap, err := readDotenv(b.path)
 	if err != nil {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidConfig, "failed to read Hermes config: %v", err).
-			WithHint("verify Hermes is installed and configured at %s", b.path).
-			WithCause(err)
+		return nil, output.ErrWithHint(output.ExitValidation, "hermes",
+			fmt.Sprintf("failed to read Hermes config: %v", err),
+			fmt.Sprintf("verify Hermes is installed and configured at %s", b.path))
 	}
 	appID := envMap["FEISHU_APP_ID"]
 	if appID == "" {
-		return nil, errs.NewConfigError(errs.SubtypeNotConfigured, "FEISHU_APP_ID not found in %s", b.path).
-			WithHint("run 'hermes setup' to configure Feishu credentials")
+		return nil, output.ErrWithHint(output.ExitValidation, "hermes",
+			fmt.Sprintf("FEISHU_APP_ID not found in %s", b.path),
+			"run 'hermes setup' to configure Feishu credentials")
 	}
 	b.envMap = envMap
 	return []Candidate{{AppID: appID, Label: "default"}}, nil
@@ -240,22 +245,24 @@ func (b *hermesBinder) ListCandidates() ([]Candidate, error) {

 func (b *hermesBinder) Build(appID string) (*core.AppConfig, error) {
 	if b.envMap == nil {
-		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: Build called before ListCandidates")
+		return nil, output.Errorf(output.ExitInternal, "hermes",
+			"internal: Build called before ListCandidates")
 	}
 	if b.envMap["FEISHU_APP_ID"] != appID {
-		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: appID %q does not match env", appID)
+		return nil, output.Errorf(output.ExitInternal, "hermes",
+			"internal: appID %q does not match env", appID)
 	}
 	appSecret := b.envMap["FEISHU_APP_SECRET"]
 	if appSecret == "" {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "FEISHU_APP_SECRET not found in %s", b.path).
-			WithHint("run 'hermes setup' to configure Feishu credentials")
+		return nil, output.ErrWithHint(output.ExitValidation, "hermes",
+			fmt.Sprintf("FEISHU_APP_SECRET not found in %s", b.path),
+			"run 'hermes setup' to configure Feishu credentials")
 	}

 	stored, err := core.ForStorage(appID, core.PlainSecret(appSecret), b.opts.Factory.Keychain)
 	if err != nil {
-		return nil, errs.NewInternalError(errs.SubtypeStorage, "keychain unavailable: %v", err).
-			WithHint("use file: reference in config to bypass keychain").
-			WithCause(err)
+		return nil, output.Errorf(output.ExitInternal, "hermes",
+			"keychain unavailable: %v\nhint: use file: reference in config to bypass keychain", err)
 	}

 	return &core.AppConfig{
@@ -283,13 +290,14 @@ func (b *larkChannelBinder) ConfigPath() string { return b.path }
 func (b *larkChannelBinder) ListCandidates() ([]Candidate, error) {
 	cfg, err := binding.ReadLarkChannelConfig(b.path)
 	if err != nil {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidConfig, "cannot read %s: %v", b.path, err).
-			WithHint("verify lark-channel-bridge is installed and configured").
-			WithCause(err)
+		return nil, output.ErrWithHint(output.ExitValidation, "lark-channel",
+			fmt.Sprintf("cannot read %s: %v", b.path, err),
+			"verify lark-channel-bridge is installed and configured")
 	}
 	if cfg.Accounts.App.ID == "" {
-		return nil, errs.NewConfigError(errs.SubtypeNotConfigured, "accounts.app.id missing in %s", b.path).
-			WithHint("run lark-channel-bridge's setup to populate the app credential")
+		return nil, output.ErrWithHint(output.ExitValidation, "lark-channel",
+			fmt.Sprintf("accounts.app.id missing in %s", b.path),
+			"run lark-channel-bridge's setup to populate the app credential")
 	}
 	b.cfg = cfg
 	return []Candidate{{AppID: cfg.Accounts.App.ID, Label: "default"}}, nil
@@ -297,30 +305,23 @@ func (b *larkChannelBinder) ListCandidates() ([]Candidate, error) {

 func (b *larkChannelBinder) Build(appID string) (*core.AppConfig, error) {
 	if b.cfg == nil {
-		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: Build called before ListCandidates")
+		return nil, output.Errorf(output.ExitInternal, "lark-channel",
+			"internal: Build called before ListCandidates")
 	}
 	if b.cfg.Accounts.App.ID != appID {
-		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: appID %q does not match config", appID)
+		return nil, output.Errorf(output.ExitInternal, "lark-channel",
+			"internal: appID %q does not match config", appID)
 	}
-	if b.cfg.Accounts.App.Secret.IsZero() {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "accounts.app.secret is empty in %s", b.path).
-			WithHint("run lark-channel-bridge's setup to populate the app credential")
+	if b.cfg.Accounts.App.Secret == "" {
+		return nil, output.ErrWithHint(output.ExitValidation, "lark-channel",
+			fmt.Sprintf("accounts.app.secret is empty in %s", b.path),
+			"run lark-channel-bridge's setup to populate the app credential")
 	}

-	// Resolve through the same SecretInput pipeline openclaw uses, so
-	// bridge configs can use ${VAR} / env / file / exec just like openclaw.
-	secret, err := binding.ResolveSecretInput(b.cfg.Accounts.App.Secret, b.cfg.Secrets, os.Getenv)
+	stored, err := core.ForStorage(appID, core.PlainSecret(b.cfg.Accounts.App.Secret), b.opts.Factory.Keychain)
 	if err != nil {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "failed to resolve appSecret for %s: %v", appID, err).
-			WithHint("check appSecret configuration in %s", b.path).
-			WithCause(err)
-	}
-
-	stored, err := core.ForStorage(appID, core.PlainSecret(secret), b.opts.Factory.Keychain)
-	if err != nil {
-		return nil, errs.NewInternalError(errs.SubtypeStorage, "keychain unavailable: %v", err).
-			WithHint("use file: reference in config to bypass keychain").
-			WithCause(err)
+		return nil, output.Errorf(output.ExitInternal, "lark-channel",
+			"keychain unavailable: %v", err)
 	}

 	return &core.AppConfig{
@@ -379,12 +380,10 @@ func resolveHermesEnvPath() string {
 }

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

 import (
-	"path/filepath"
 	"reflect"
 	"testing"

@@ -51,8 +50,8 @@ func assertCandidate(t *testing.T, got *Candidate, want Candidate) {
 func TestSelectCandidate_ZeroCandidates_OpenClaw(t *testing.T) {
 	b := &fakeBinder{name: "openclaw", path: "/tmp/openclaw.json"}
 	_, err := selectCandidate(b, nil, "", false, tuiUnreachable(t))
-	assertExitError(t, err, output.ExitAuth, output.ErrDetail{
-		Type:    "config",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "openclaw",
 		Message: "no Feishu app configured in openclaw.json",
 		Hint:    "configure channels.feishu.appId in openclaw.json",
 	})
@@ -64,8 +63,8 @@ func TestSelectCandidate_ZeroCandidates_GenericSource(t *testing.T) {
 	// even before it has a bespoke error message.
 	b := &fakeBinder{name: "hermes", path: "/tmp/.env"}
 	_, err := selectCandidate(b, nil, "", false, tuiUnreachable(t))
-	assertExitError(t, err, output.ExitAuth, output.ErrDetail{
-		Type:    "config",
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "validation",
 		Message: "hermes: no app configured",
 	})
 }
@@ -101,7 +100,7 @@ func TestSelectCandidate_AppIDFlag_NoMatch(t *testing.T) {
 	}
 	_, err := selectCandidate(b, candidates, "nonexistent", false, tuiUnreachable(t))
 	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
-		Type:    "validation",
+		Type:    "openclaw",
 		Message: `--app-id "nonexistent" not found in openclaw.json`,
 		Hint:    "available app IDs:\n  cli_work (work)\n  cli_home (home)",
 	})
@@ -118,7 +117,7 @@ func TestSelectCandidate_MultiCandidate_NoFlag_NonTUI(t *testing.T) {
 	}
 	_, err := selectCandidate(b, candidates, "", false, tuiUnreachable(t))
 	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
-		Type:    "validation",
+		Type:    "openclaw",
 		Message: "multiple accounts in openclaw.json; pass --app-id <id>",
 		Hint:    "available app IDs:\n  cli_work (work)\n  cli_home (home)",
 	})
@@ -153,7 +152,7 @@ func TestSelectCandidate_SingleCandidate_WrongFlag(t *testing.T) {
 	candidates := []Candidate{{AppID: "cli_only"}}
 	_, err := selectCandidate(b, candidates, "nonexistent", false, tuiUnreachable(t))
 	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
-		Type:    "validation",
+		Type:    "openclaw",
 		Message: `--app-id "nonexistent" not found in openclaw.json`,
 		Hint:    "available app IDs:\n  cli_only",
 	})
@@ -174,27 +173,3 @@ func TestSelectCandidate_AppIDFlag_WinsOverTUI(t *testing.T) {
 	}
 	assertCandidate(t, got, Candidate{AppID: "cli_b"})
 }
-
-func TestResolveLarkChannelConfigPath_Default(t *testing.T) {
-	home := t.TempDir()
-	t.Setenv("HOME", home)
-	t.Setenv("LARK_CHANNEL_CONFIG", "")
-
-	got := resolveLarkChannelConfigPath()
-	want := filepath.Join(home, ".lark-channel", "config.json")
-	if got != want {
-		t.Fatalf("resolveLarkChannelConfigPath() = %q, want %q", got, want)
-	}
-}
-
-func TestResolveLarkChannelConfigPath_EnvOverride(t *testing.T) {
-	home := t.TempDir()
-	t.Setenv("HOME", home)
-	t.Setenv("LARK_CHANNEL_CONFIG", "~/bridge/projection.json")
-
-	got := resolveLarkChannelConfigPath()
-	want := filepath.Join(home, "bridge", "projection.json")
-	if got != want {
-		t.Fatalf("resolveLarkChannelConfigPath() = %q, want %q", got, want)
-	}
-}
--- a/cmd/config/config.go
+++ b/cmd/config/config.go
@@ -31,9 +31,6 @@ func NewCmdConfig(f *cmdutil.Factory) *cobra.Command {
 	cmd.AddCommand(NewCmdConfigShow(f, nil))
 	cmd.AddCommand(NewCmdConfigDefaultAs(f))
 	cmd.AddCommand(NewCmdConfigStrictMode(f))
-	cmd.AddCommand(NewCmdConfigPolicy(f))
-	cmd.AddCommand(NewCmdConfigPlugins(f))
-	cmd.AddCommand(NewCmdConfigKeychainDowngrade(f))
 	return cmd
 }

--- a/cmd/config/config_test.go
+++ b/cmd/config/config_test.go
@@ -16,7 +16,6 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/credential"
-	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/output"
 )
@@ -96,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)
@@ -126,11 +124,15 @@ func TestConfigShowRun_NoActiveProfileReturnsStructuredError(t *testing.T) {
 		t.Fatal("expected error")
 	}

-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitAuth {
-		t.Errorf("exit code = %d, want %d", gotCode, output.ExitAuth)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("error type = %T, want *output.ExitError", err)
 	}
-	if !strings.Contains(err.Error(), "no active profile") {
-		t.Fatalf("error = %v, want to contain 'no active profile'", err)
+	if exitErr.Code != output.ExitValidation {
+		t.Fatalf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
+	}
+	if exitErr.Detail == nil || exitErr.Detail.Type != "config" || exitErr.Detail.Message != "no active profile" {
+		t.Fatalf("detail = %#v, want config/no active profile", exitErr.Detail)
 	}
 }

@@ -148,9 +150,8 @@ func TestConfigInitCmd_LangFlag(t *testing.T) {
 	if err := cmd.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	// --lang en is canonicalized to en_us in RunE before runF captures opts.
-	if gotOpts.Lang != string(i18n.LangEnUS) {
-		t.Errorf("expected Lang en_us, got %s", gotOpts.Lang)
+	if gotOpts.Lang != "en" {
+		t.Errorf("expected Lang en, got %s", gotOpts.Lang)
 	}
 	if !gotOpts.langExplicit {
 		t.Error("expected langExplicit=true when --lang is passed")
@@ -171,82 +172,14 @@ func TestConfigInitCmd_LangDefault(t *testing.T) {
 	if err := cmd.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	if gotOpts.Lang != "" {
-		t.Errorf("expected default Lang to be unset (\"\"), got %q", gotOpts.Lang)
+	if gotOpts.Lang != "zh" {
+		t.Errorf("expected default Lang zh, got %s", gotOpts.Lang)
 	}
 	if gotOpts.langExplicit {
 		t.Error("expected langExplicit=false when --lang is not passed")
 	}
 }

-// TestSaveInitConfig_OmitLangPreservesPrior guards the single-app replace path:
-// re-running init without --lang must inherit the prior preference, not clear it.
-func TestSaveInitConfig_OmitLangPreservesPrior(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-
-	existing := &core.MultiAppConfig{Apps: []core.AppConfig{
-		{AppId: "cli_x", AppSecret: core.PlainSecret("s"), Brand: core.BrandFeishu, Lang: i18n.LangJaJP},
-	}}
-	if err := core.SaveMultiAppConfig(existing); err != nil {
-		t.Fatalf("seed config: %v", err)
-	}
-
-	if err := saveInitConfig("", existing, f, "cli_x", core.PlainSecret("s2"), core.BrandFeishu, ""); err != nil {
-		t.Fatalf("saveInitConfig (no --lang): %v", err)
-	}
-
-	got, err := core.LoadMultiAppConfig()
-	if err != nil {
-		t.Fatalf("LoadMultiAppConfig: %v", err)
-	}
-	if app := got.CurrentAppConfig(""); app == nil || app.Lang != i18n.LangJaJP {
-		t.Errorf("Lang after re-init = %v, want %q (preserved)", app, i18n.LangJaJP)
-	}
-}
-
-// TestConfigInitCmd_InvalidLang verifies a non-empty --lang on config init is
-// strictly validated the same way bind validates: wrong-case / typo / removed
-// codes / hyphen form all exit with ExitValidation. (Empty is a no-op.)
-func TestConfigInitCmd_InvalidLang(t *testing.T) {
-	clearAgentEnv(t)
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	cases := []struct {
-		name string
-		lang string
-	}{
-		{"wrong case ZH", "ZH"},
-		{"typo frr", "frr"},
-		{"removed code ar", "ar"},
-		{"unknown xx", "xx"},
-		{"hyphen form zh-CN", "zh-CN"},
-	}
-
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			f, _, _, _ := cmdutil.TestFactory(t, nil)
-			cmd := NewCmdConfigInit(f, nil)
-			f.IOStreams.In = strings.NewReader("sec\n")
-			cmd.SetArgs([]string{"--lang", tc.lang, "--app-id", "x", "--app-secret-stdin"})
-			err := cmd.Execute()
-			if err == nil {
-				t.Fatalf("expected validation error for --lang %q, got nil", tc.lang)
-			}
-			exitErr, ok := err.(*output.ExitError)
-			if !ok {
-				t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
-			}
-			if exitErr.Code != output.ExitValidation {
-				t.Errorf("exit code = %d, want %d (validation)", exitErr.Code, output.ExitValidation)
-			}
-			if !strings.Contains(exitErr.Error(), "invalid --lang") {
-				t.Errorf("error message %q does not contain 'invalid --lang'", exitErr.Error())
-			}
-		})
-	}
-}
-
 func TestHasAnyNonInteractiveFlag(t *testing.T) {
 	tests := []struct {
 		name string
@@ -465,65 +398,16 @@ func TestConfigBlockedByExternalProvider(t *testing.T) {
 			if matched != nil && matched != cmd && !matched.SilenceUsage {
 				t.Error("expected PersistentPreRunE to set SilenceUsage on matched subcommand")
 			}
-			if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
-				t.Errorf("exit code = %d, want %d", gotCode, output.ExitValidation)
+			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 == nil || exitErr.Detail.Type != "external_provider" {
+				t.Errorf("error type = %v, want %q", exitErr.Detail, "external_provider")
 			}
 		})
 	}
 }
-
-// TestValidateInitLang covers the --lang contract: empty (omitted or explicit)
-// is a no-op leaving Lang unset; a short code or Feishu locale canonicalizes to
-// the same locale; an unrecognized value errors.
-func TestValidateInitLang(t *testing.T) {
-	t.Run("empty is a no-op", func(t *testing.T) {
-		for _, explicit := range []bool{false, true} {
-			opts := &ConfigInitOptions{Lang: "", langExplicit: explicit}
-			if err := validateInitLang(opts); err != nil {
-				t.Fatalf("explicit=%v: expected nil error, got %v", explicit, err)
-			}
-			if opts.Lang != "" {
-				t.Errorf("explicit=%v: Lang = %q, want \"\" (unset)", explicit, opts.Lang)
-			}
-		}
-	})
-	t.Run("short and locale canonicalize alike", func(t *testing.T) {
-		for _, in := range []string{"ja", "ja_jp"} {
-			opts := &ConfigInitOptions{Lang: in, langExplicit: true}
-			if err := validateInitLang(opts); err != nil {
-				t.Fatalf("--lang %q: unexpected error %v", in, err)
-			}
-			if opts.Lang != string(i18n.LangJaJP) {
-				t.Errorf("--lang %q normalized to %q, want %q", in, opts.Lang, i18n.LangJaJP)
-			}
-		}
-	})
-}
-
-// TestPrintLangPreferenceConfirmation covers the confirmation helper: it prints
-// to stderr only when --lang explicitly set a non-empty preference.
-func TestPrintLangPreferenceConfirmation(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Run("explicit non-empty prints confirmation", func(t *testing.T) {
-		f, _, stderr, _ := cmdutil.TestFactory(t, nil)
-		printLangPreferenceConfirmation(&ConfigInitOptions{Factory: f, Lang: "en_us", UILang: i18n.LangZhCN, langExplicit: true})
-		got := stderr.String()
-		if !strings.Contains(got, "语言偏好") || !strings.Contains(got, "en_us") {
-			t.Errorf("stderr = %q, want confirmation mentioning the preference and en_us", got)
-		}
-	})
-	t.Run("implicit prints nothing", func(t *testing.T) {
-		f, _, stderr, _ := cmdutil.TestFactory(t, nil)
-		printLangPreferenceConfirmation(&ConfigInitOptions{Factory: f, Lang: "en_us", UILang: i18n.LangZhCN, langExplicit: false})
-		if got := stderr.String(); got != "" {
-			t.Errorf("stderr = %q, want empty when --lang is implicit", got)
-		}
-	})
-	t.Run("explicit empty prints nothing", func(t *testing.T) {
-		f, _, stderr, _ := cmdutil.TestFactory(t, nil)
-		printLangPreferenceConfirmation(&ConfigInitOptions{Factory: f, Lang: "", UILang: i18n.LangZhCN, langExplicit: true})
-		if got := stderr.String(); got != "" {
-			t.Errorf("stderr = %q, want empty when --lang is empty", got)
-		}
-	})
-}
--- a/cmd/config/default_as.go
+++ b/cmd/config/default_as.go
@@ -6,9 +6,9 @@ package config
 import (
 	"fmt"

-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/spf13/cobra"
 )

@@ -41,17 +41,16 @@ func NewCmdConfigDefaultAs(f *cmdutil.Factory) *cobra.Command {

 			value := args[0]
 			if value != "user" && value != "bot" && value != "auto" {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid identity type %q, valid values: user | bot | auto", value)
+				return output.ErrValidation("invalid identity type %q, valid values: user | bot | auto", value)
 			}

 			app.DefaultAs = core.Identity(value)
 			if err := core.SaveMultiAppConfig(multi); err != nil {
-				return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+				return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 			}
 			fmt.Fprintf(f.IOStreams.ErrOut, "Default identity set to: %s\n", value)
 			return nil
 		},
 	}
-	cmdutil.SetRisk(cmd, "write")
 	return cmd
 }
--- a/cmd/config/init.go
+++ b/cmd/config/init.go
@@ -15,11 +15,9 @@ import (
 	"github.com/charmbracelet/huh"
 	"github.com/spf13/cobra"

-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/output"
 )
@@ -33,13 +31,9 @@ type ConfigInitOptions struct {
 	AppSecretStdin bool   // read app-secret from stdin (avoids process list exposure)
 	Brand          string
 	New            bool
-
-	Lang         string // raw --lang (string for cobra); normalized to canonical/"" in validateInitLang
-	langExplicit bool   // true when --lang was explicitly passed
-
-	UILang i18n.Lang // TUI display language (picker-only); intentionally separate from --lang
-
-	ProfileName string // when set, create/update a named profile instead of replacing Apps[0]
+	Lang           string
+	langExplicit   bool   // true when --lang was explicitly passed
+	ProfileName    string // when set, create/update a named profile instead of replacing Apps[0]

 	// ForceInit overrides the agent-workspace guard. Without it, running
 	// init under OPENCLAW_HOME / HERMES_HOME refuses and points the caller
@@ -51,7 +45,7 @@ type ConfigInitOptions struct {

 // NewCmdConfigInit creates the config init subcommand.
 func NewCmdConfigInit(f *cmdutil.Factory, runF func(*ConfigInitOptions) error) *cobra.Command {
-	opts := &ConfigInitOptions{Factory: f, UILang: i18n.LangZhCN}
+	opts := &ConfigInitOptions{Factory: f}

 	cmd := &cobra.Command{
 		Use:   "init",
@@ -69,9 +63,6 @@ if the user explicitly wants a separate app inside the Agent workspace.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.Ctx = cmd.Context()
 			opts.langExplicit = cmd.Flags().Changed("lang")
-			if err := validateInitLang(opts); err != nil {
-				return err
-			}
 			if err := guardAgentWorkspace(opts); err != nil {
 				return err
 			}
@@ -86,33 +77,13 @@ if the user explicitly wants a separate app inside the Agent workspace.`,
 	cmd.Flags().StringVar(&opts.AppID, "app-id", "", "App ID (non-interactive)")
 	cmd.Flags().BoolVar(&opts.AppSecretStdin, "app-secret-stdin", false, "Read App Secret from stdin to avoid process list exposure")
 	cmd.Flags().StringVar(&opts.Brand, "brand", "feishu", "feishu or lark (non-interactive, default feishu)")
-	cmd.Flags().StringVar(&opts.Lang, "lang", "", "language preference (e.g. zh or zh_cn)")
+	cmd.Flags().StringVar(&opts.Lang, "lang", "zh", "language for interactive prompts (zh or en)")
 	cmd.Flags().StringVar(&opts.ProfileName, "name", "", "create or update a named profile (append instead of replace)")
 	cmd.Flags().BoolVar(&opts.ForceInit, "force-init", false, "allow init inside an Agent workspace (OPENCLAW_HOME / HERMES_HOME); use config bind instead unless you really want a separate app")
-	cmdutil.SetRisk(cmd, "write")

 	return cmd
 }

-// printLangPreferenceConfirmation echoes the set preference to stderr, only
-// when --lang explicitly set a non-empty value.
-func printLangPreferenceConfirmation(opts *ConfigInitOptions) {
-	if !opts.langExplicit || opts.Lang == "" {
-		return
-	}
-	msg := getInitMsg(opts.UILang)
-	fmt.Fprintln(opts.Factory.IOStreams.ErrOut, fmt.Sprintf(msg.LangPreferenceSet, opts.Lang))
-}
-
-func validateInitLang(opts *ConfigInitOptions) error {
-	lang, err := cmdutil.ParseLangFlag(opts.Lang)
-	if err != nil {
-		return err
-	}
-	opts.Lang = string(lang)
-	return nil
-}
-
 // guardAgentWorkspace refuses 'config init' when run inside an OpenClaw or
 // Hermes Agent context, because the Agent has already provisioned an app
 // and 'config bind' is the right tool for hooking lark-cli into it.
@@ -160,7 +131,7 @@ func cleanupOldConfig(existing *core.MultiAppConfig, f *cmdutil.Factory, skipApp
 func saveAsOnlyApp(appId string, secret core.SecretInput, brand core.LarkBrand, lang string) error {
 	config := &core.MultiAppConfig{
 		Apps: []core.AppConfig{{
-			AppId: appId, AppSecret: secret, Brand: brand, Lang: i18n.Lang(lang), Users: []core.AppUser{},
+			AppId: appId, AppSecret: secret, Brand: brand, Lang: lang, Users: []core.AppUser{},
 		}},
 	}
 	return core.SaveMultiAppConfig(config)
@@ -174,13 +145,7 @@ func saveInitConfig(profileName string, existing *core.MultiAppConfig, f *cmduti
 		return saveAsProfile(existing, f.Keychain, profileName, appId, secret, brand, lang)
 	}
 	cleanupOldConfig(existing, f, appId)
-	var prior i18n.Lang
-	if existing != nil {
-		if app := existing.CurrentAppConfig(""); app != nil {
-			prior = app.Lang
-		}
-	}
-	return saveAsOnlyApp(appId, secret, brand, string(preferredLang(i18n.Lang(lang), prior)))
+	return saveAsOnlyApp(appId, secret, brand, lang)
 }

 // saveAsProfile appends or updates a named profile in the config.
@@ -201,10 +166,11 @@ func saveAsProfile(existing *core.MultiAppConfig, kc keychain.KeychainAccess, pr
 			}
 			multi.Apps[idx].Users = []core.AppUser{}
 		}
+		// Update existing profile
 		multi.Apps[idx].AppId = appId
 		multi.Apps[idx].AppSecret = secret
 		multi.Apps[idx].Brand = brand
-		multi.Apps[idx].Lang = preferredLang(i18n.Lang(lang), multi.Apps[idx].Lang)
+		multi.Apps[idx].Lang = lang
 	} else {
 		if findAppIndexByAppID(multi, profileName) >= 0 {
 			return fmt.Errorf("profile name %q conflicts with existing appId", profileName)
@@ -215,7 +181,7 @@ func saveAsProfile(existing *core.MultiAppConfig, kc keychain.KeychainAccess, pr
 			AppId:     appId,
 			AppSecret: secret,
 			Brand:     brand,
-			Lang:      i18n.Lang(lang),
+			Lang:      lang,
 			Users:     []core.AppUser{},
 		})
 	}
@@ -246,29 +212,9 @@ func findAppIndexByAppID(multi *core.MultiAppConfig, appID string) int {
 	return -1
 }

-// wrapUpdateExistingProfileErr classifies the error returned by
-// updateExistingProfileWithoutSecret. Typed errors (e.g. *errs.ValidationError
-// for blank-input) pass through unchanged so their exit code semantics
-// survive; legacy *output.ExitError also passes through; everything else
-// (filesystem, keychain, etc.) is wrapped as InternalError.
-func wrapUpdateExistingProfileErr(err error) error {
-	if err == nil {
-		return nil
-	}
-	if errs.IsTyped(err) {
-		return err
-	}
-	var exitErr *output.ExitError
-	if errors.As(err, &exitErr) {
-		return err
-	}
-	return errs.NewInternalError(errs.SubtypeSDKError, "failed to save config: %v", err).WithCause(err)
-}
-
 func updateExistingProfileWithoutSecret(existing *core.MultiAppConfig, profileName, appID string, brand core.LarkBrand, lang string) error {
 	if existing == nil {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "App Secret cannot be empty for new configuration").
-			WithParam("--app-secret")
+		return output.ErrValidation("App Secret cannot be empty for new configuration")
 	}

 	var app *core.AppConfig
@@ -276,25 +222,22 @@ func updateExistingProfileWithoutSecret(existing *core.MultiAppConfig, profileNa
 		if idx := findProfileIndexByName(existing, profileName); idx >= 0 {
 			app = &existing.Apps[idx]
 		} else {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "App Secret cannot be empty for new profile").
-				WithParam("--app-secret")
+			return output.ErrValidation("App Secret cannot be empty for new profile")
 		}
 	} else {
 		app = existing.CurrentAppConfig("")
 		if app == nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "App Secret cannot be empty for new configuration").
-				WithParam("--app-secret")
+			return output.ErrValidation("App Secret cannot be empty for new configuration")
 		}
 	}

 	if app.AppId != appID {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "App Secret cannot be empty when changing App ID").
-			WithParam("--app-secret")
+		return output.ErrValidation("App Secret cannot be empty when changing App ID")
 	}

 	app.AppId = appID
 	app.Brand = brand
-	app.Lang = preferredLang(i18n.Lang(lang), app.Lang)
+	app.Lang = lang
 	return core.SaveMultiAppConfig(existing)
 }

@@ -306,13 +249,13 @@ func configInitRun(opts *ConfigInitOptions) error {
 		scanner := bufio.NewScanner(f.IOStreams.In)
 		if !scanner.Scan() {
 			if err := scanner.Err(); err != nil {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "failed to read secret from stdin: %v", err).WithCause(err)
+				return output.ErrValidation("failed to read secret from stdin: %v", err)
 			}
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "stdin is empty, expected app secret")
+			return output.ErrValidation("stdin is empty, expected app secret")
 		}
 		opts.appSecret = strings.TrimSpace(scanner.Text())
 		if opts.appSecret == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "app secret read from stdin is empty")
+			return output.ErrValidation("app secret read from stdin is empty")
 		}
 	}

@@ -324,7 +267,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 	// Validate --profile name if set
 	if opts.ProfileName != "" {
 		if err := core.ValidateProfileName(opts.ProfileName); err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "%v", err).WithCause(err)
+			return output.ErrValidation("%v", err)
 		}
 	}

@@ -333,36 +276,35 @@ func configInitRun(opts *ConfigInitOptions) error {
 		brand := parseBrand(opts.Brand)
 		secret, err := core.ForStorage(opts.AppID, core.PlainSecret(opts.appSecret), f.Keychain)
 		if err != nil {
-			return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
+			return output.Errorf(output.ExitInternal, "internal", "%v", err)
 		}
 		if err := saveInitConfig(opts.ProfileName, existing, f, opts.AppID, secret, brand, opts.Lang); err != nil {
-			return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+			return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 		}
 		output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf("Configuration saved to %s", core.GetConfigPath()))
-		printLangPreferenceConfirmation(opts)
 		output.PrintJson(f.IOStreams.Out, map[string]interface{}{"appId": opts.AppID, "appSecret": "****", "brand": brand})
-		if err := runProbe(opts.Ctx, f, opts.AppID, opts.appSecret, brand); err != nil {
-			return err
-		}
 		return nil
 	}

-	// For interactive modes, prompt language selection if --lang was not explicitly set.
-	// Picker offers 2 options (中文 / English) and drives BOTH opts.Lang
-	// (preference) and opts.UILang (TUI rendering).
+	// For interactive modes, prompt language selection if --lang was not explicitly set
 	if f.IOStreams.IsTerminal && !opts.langExplicit && !opts.hasAnyNonInteractiveFlag() {
-		lang, err := promptLangSelection()
+		savedLang := ""
+		if existing != nil {
+			if app := existing.CurrentAppConfig(""); app != nil {
+				savedLang = app.Lang
+			}
+		}
+		lang, err := promptLangSelection(savedLang)
 		if err != nil {
 			if err == huh.ErrUserAborted {
 				return output.ErrBare(1)
 			}
-			return output.Errorf(output.ExitInternal, "internal", "language selection failed: %v", err)
+			return err
 		}
-		opts.Lang = string(lang)
-		opts.UILang = lang
+		opts.Lang = lang
 	}

-	msg := getInitMsg(opts.UILang)
+	msg := getInitMsg(opts.Lang)

 	// Mode 3: Create new app directly (--new)
 	if opts.New {
@@ -371,21 +313,17 @@ func configInitRun(opts *ConfigInitOptions) error {
 			return err
 		}
 		if result == nil {
-			return errs.NewInternalError(errs.SubtypeSDKError, "app creation returned no result")
+			return output.ErrValidation("app creation returned no result")
 		}
 		existing, _ := core.LoadMultiAppConfig()
 		secret, err := core.ForStorage(result.AppID, core.PlainSecret(result.AppSecret), f.Keychain)
 		if err != nil {
-			return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
+			return output.Errorf(output.ExitInternal, "internal", "%v", err)
 		}
 		if err := saveInitConfig(opts.ProfileName, existing, f, result.AppID, secret, result.Brand, opts.Lang); err != nil {
-			return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+			return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 		}
-		printLangPreferenceConfirmation(opts)
 		output.PrintJson(f.IOStreams.Out, map[string]interface{}{"appId": result.AppID, "appSecret": "****", "brand": result.Brand})
-		if err := runProbe(opts.Ctx, f, result.AppID, result.AppSecret, result.Brand); err != nil {
-			return err
-		}
 		return nil
 	}

@@ -396,8 +334,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 			return err
 		}
 		if result == nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "App ID and App Secret cannot be empty").
-				WithParam("--app-id")
+			return output.ErrValidation("App ID and App Secret cannot be empty")
 		}

 		existing, _ := core.LoadMultiAppConfig()
@@ -406,36 +343,33 @@ func configInitRun(opts *ConfigInitOptions) error {
 			// New secret provided (either from "create" or "existing" with input)
 			secret, err := core.ForStorage(result.AppID, core.PlainSecret(result.AppSecret), f.Keychain)
 			if err != nil {
-				return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
+				return output.Errorf(output.ExitInternal, "internal", "%v", err)
 			}
 			if err := saveInitConfig(opts.ProfileName, existing, f, result.AppID, secret, result.Brand, opts.Lang); err != nil {
-				return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+				return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 			}
 		} else if result.Mode == "existing" && result.AppID != "" {
 			// Existing app with unchanged secret — update app ID and brand only
-			if err := wrapUpdateExistingProfileErr(updateExistingProfileWithoutSecret(existing, opts.ProfileName, result.AppID, result.Brand, opts.Lang)); err != nil {
-				return err
+			if err := updateExistingProfileWithoutSecret(existing, opts.ProfileName, result.AppID, result.Brand, opts.Lang); err != nil {
+				var exitErr *output.ExitError
+				if errors.As(err, &exitErr) {
+					return err
+				}
+				return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 			}
 		} else {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "App ID and App Secret cannot be empty").
-				WithParam("--app-id")
+			return output.ErrValidation("App ID and App Secret cannot be empty")
 		}

 		if result.Mode == "existing" {
 			output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf(msg.ConfigSaved, result.AppID))
 		}
-		printLangPreferenceConfirmation(opts)
-		if result.AppSecret != "" {
-			if err := runProbe(opts.Ctx, f, result.AppID, result.AppSecret, result.Brand); err != nil {
-				return err
-			}
-		}
 		return nil
 	}

 	// Non-terminal: cannot run interactive mode, guide user to --new
 	if !f.IOStreams.IsTerminal {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "config init requires a terminal for interactive mode. Run with --new to create a new app:\n  lark-cli config init --new\nThis command blocks until setup is complete and outputs a verification URL. Run it in the background, then retrieve the URL from its output.")
+		return output.ErrValidation("config init requires a terminal for interactive mode. Run with --new to create a new app:\n  lark-cli config init --new\nThis command blocks until setup is complete and outputs a verification URL. Run it in the background, then retrieve the URL from its output.")
 	}

 	// Mode 5: Legacy interactive (readline fallback)
@@ -463,7 +397,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 	}
 	appIdInput, err := readLine(prompt)
 	if err != nil {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithCause(err)
+		return output.ErrValidation("%s", err)
 	}

 	prompt = "App Secret"
@@ -472,7 +406,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 	}
 	appSecretInput, err := readLine(prompt)
 	if err != nil {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithCause(err)
+		return output.ErrValidation("%s", err)
 	}

 	prompt = "Brand (lark/feishu)"
@@ -483,7 +417,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 	}
 	brandInput, err := readLine(prompt)
 	if err != nil {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithCause(err)
+		return output.ErrValidation("%s", err)
 	}

 	resolvedAppId := appIdInput
@@ -505,23 +439,16 @@ func configInitRun(opts *ConfigInitOptions) error {
 	}

 	if resolvedAppId == "" || resolvedSecret.IsZero() {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "App ID and App Secret cannot be empty").
-			WithParam("--app-id")
+		return output.ErrValidation("App ID and App Secret cannot be empty")
 	}

 	storedSecret, err := core.ForStorage(resolvedAppId, resolvedSecret, f.Keychain)
 	if err != nil {
-		return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "internal", "%v", err)
 	}
 	if err := saveInitConfig(opts.ProfileName, existing, f, resolvedAppId, storedSecret, parseBrand(resolvedBrand), opts.Lang); err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 	}
 	output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf("Configuration saved to %s", core.GetConfigPath()))
-	printLangPreferenceConfirmation(opts)
-	if appSecretInput != "" {
-		if err := runProbe(opts.Ctx, f, resolvedAppId, appSecretInput, parseBrand(resolvedBrand)); err != nil {
-			return err
-		}
-	}
 	return nil
 }
--- a/cmd/config/init_interactive.go
+++ b/cmd/config/init_interactive.go
@@ -6,17 +6,16 @@ package config
 import (
 	"context"
 	"fmt"
+	"net/http"

 	"github.com/charmbracelet/huh"
 	"github.com/larksuite/cli/internal/build"
 	qrcode "github.com/skip2/go-qrcode"

-	"github.com/larksuite/cli/errs"
 	larkauth "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/transport"
 )

 // configInitResult holds the result of the interactive config init flow.
@@ -126,16 +125,8 @@ func runExistingAppForm(f *cmdutil.Factory, msg *initMsg) (*configInitResult, er
 		}, nil
 	}

-	switch {
-	case appID == "" && appSecret == "":
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "App ID and App Secret cannot be empty").
-			WithParam("--app-id")
-	case appID == "":
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "App ID cannot be empty").
-			WithParam("--app-id")
-	case appSecret == "":
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "App Secret cannot be empty").
-			WithParam("--app-secret")
+	if appID == "" || appSecret == "" {
+		return nil, output.ErrValidation("App ID and App Secret cannot be empty")
 	}

 	return &configInitResult{
@@ -177,12 +168,10 @@ func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride cor
 	}

 	// Step 1: Request app registration (begin)
-	// Use the shared proxy-plugin-aware transport so registration traffic is not
-	// a bypass of proxy plugin mode.
-	httpClient := transport.NewHTTPClient(0)
+	httpClient := &http.Client{}
 	authResp, err := larkauth.RequestAppRegistration(httpClient, larkBrand, f.IOStreams.ErrOut)
 	if err != nil {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "app registration failed: %v", err).WithCause(err)
+		return nil, output.ErrAuth("app registration failed: %v", err)
 	}

 	// Step 2: Build and display verification URL + QR code
@@ -210,7 +199,7 @@ func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride cor
 	}
 	result, err := larkauth.PollAppRegistration(ctx, httpClient, core.BrandFeishu, authResp.DeviceCode, authResp.Interval, authResp.ExpiresIn, f.IOStreams.ErrOut)
 	if err != nil {
-		return nil, errs.NewAuthenticationError(errs.SubtypeUnknown, "%v", err).WithCause(err)
+		return nil, output.ErrAuth("%v", err)
 	}

 	// Step 4: Handle Lark brand special case
@@ -219,12 +208,12 @@ func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride cor
 		// fmt.Fprintf(f.IOStreams.ErrOut, "%s\n", msg.DetectedLarkTenant)
 		result, err = larkauth.PollAppRegistration(ctx, httpClient, core.BrandLark, authResp.DeviceCode, authResp.Interval, authResp.ExpiresIn, f.IOStreams.ErrOut)
 		if err != nil {
-			return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "lark endpoint retry failed: %v", err).WithCause(err)
+			return nil, output.ErrAuth("lark endpoint retry failed: %v", err)
 		}
 	}

 	if result.ClientID == "" || result.ClientSecret == "" {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "app registration succeeded but missing client_id or client_secret")
+		return nil, output.ErrAuth("app registration succeeded but missing client_id or client_secret")
 	}

 	// Determine final brand from response
--- a/cmd/config/init_messages.go
+++ b/cmd/config/init_messages.go
@@ -7,7 +7,6 @@ import (
 	"github.com/charmbracelet/huh"

 	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/i18n"
 )

 type initMsg struct {
@@ -27,10 +26,6 @@ type initMsg struct {
 	DetectedLarkTenant   string
 	AppCreated           string
 	ConfigSaved          string
-
-	// LangPreferenceSet is printed to stderr after a successful init when the
-	// user explicitly passed --lang. Format: language code.
-	LangPreferenceSet string
 }

 var initMsgZh = &initMsg{
@@ -48,7 +43,6 @@ var initMsgZh = &initMsg{
 	DetectedLarkTenant:   "[lark-cli] 检测到 Lark 租户，切换端点重试...",
 	AppCreated:           "应用配置成功! App ID: %s",
 	ConfigSaved:          "应用配置成功! App ID: %s",
-	LangPreferenceSet:    "语言偏好已设置：%s",
 }

 var initMsgEn = &initMsg{
@@ -66,27 +60,29 @@ var initMsgEn = &initMsg{
 	DetectedLarkTenant:   "[lark-cli] Detected Lark tenant, switching endpoint...",
 	AppCreated:           "App configured! App ID: %s",
 	ConfigSaved:          "App configured! App ID: %s",
-	LangPreferenceSet:    "Language preference set to: %s",
 }

-// getInitMsg picks the zh/en TUI bundle; non-English falls back to zh.
-func getInitMsg(lang i18n.Lang) *initMsg {
-	if lang.IsEnglish() {
+func getInitMsg(lang string) *initMsg {
+	if lang == "en" {
 		return initMsgEn
 	}
 	return initMsgZh
 }

-// promptLangSelection shows the 中文/English picker and returns the chosen locale.
-func promptLangSelection() (i18n.Lang, error) {
-	lang := i18n.LangZhCN
+// promptLangSelection shows an interactive language picker and returns the chosen lang code.
+// savedLang is used as the pre-selected default (from existing config).
+func promptLangSelection(savedLang string) (string, error) {
+	lang := savedLang
+	if lang != "en" {
+		lang = "zh"
+	}
 	form := huh.NewForm(
 		huh.NewGroup(
-			huh.NewSelect[i18n.Lang]().
+			huh.NewSelect[string]().
 				Title("Language / 语言").
 				Options(
-					huh.NewOption("中文", i18n.LangZhCN),
-					huh.NewOption("English", i18n.LangEnUS),
+					huh.NewOption("中文", "zh"),
+					huh.NewOption("English", "en"),
 				).
 				Value(&lang),
 		),
--- a/cmd/config/init_messages_test.go
+++ b/cmd/config/init_messages_test.go
@@ -6,8 +6,6 @@ package config
 import (
 	"fmt"
 	"testing"
-
-	"github.com/larksuite/cli/internal/i18n"
 )

 func TestGetInitMsg_Zh(t *testing.T) {
@@ -31,7 +29,7 @@ func TestGetInitMsg_En(t *testing.T) {
 }

 func TestGetInitMsg_DefaultsToZh(t *testing.T) {
-	for _, lang := range []i18n.Lang{"", "unknown", "xyz", "invalid"} {
+	for _, lang := range []string{"", "fr", "ja", "unknown"} {
 		msg := getInitMsg(lang)
 		if msg != initMsgZh {
 			t.Errorf("getInitMsg(%q) should default to zh", lang)
@@ -64,7 +62,6 @@ func assertAllFieldsNonEmpty(t *testing.T, msg *initMsg, label string) {
 		"DetectedLarkTenant":   msg.DetectedLarkTenant,
 		"AppCreated":           msg.AppCreated,
 		"ConfigSaved":          msg.ConfigSaved,
-		"LangPreferenceSet":    msg.LangPreferenceSet,
 	}
 	for name, val := range fields {
 		if val == "" {
@@ -74,7 +71,7 @@ func assertAllFieldsNonEmpty(t *testing.T, msg *initMsg, label string) {
 }

 func TestInitMsg_FormatStrings(t *testing.T) {
-	for _, lang := range []i18n.Lang{i18n.LangZhCN, i18n.LangEnUS} {
+	for _, lang := range []string{"zh", "en"} {
 		msg := getInitMsg(lang)
 		// AppCreated and ConfigSaved should contain %s for App ID
 		got := fmt.Sprintf(msg.AppCreated, "cli_test123")
@@ -87,37 +84,3 @@ func TestInitMsg_FormatStrings(t *testing.T) {
 		}
 	}
 }
-
-func TestGetInitMsg_BilingualCollapse(t *testing.T) {
-	// The TUI is bilingual (zh + en). Only English-bucket languages return the
-	// English struct — by canonical locale ("en_us") or legacy short ("en").
-	// Everything else (zh, the other codes, invalid, "") returns Chinese.
-	tests := []struct {
-		lang       i18n.Lang
-		shouldBeEn bool
-	}{
-		{i18n.LangZhCN, false},
-		{i18n.LangEnUS, true},
-		{"en", true}, // legacy short value
-		{i18n.LangJaJP, false},
-		{"fr_fr", false},
-		{"invalid", false},
-		{"", false},
-	}
-
-	for _, tt := range tests {
-		t.Run(string(tt.lang), func(t *testing.T) {
-			msg := getInitMsg(tt.lang)
-			if msg == nil {
-				t.Fatal("getInitMsg returned nil")
-			}
-			want := initMsgZh
-			if tt.shouldBeEn {
-				want = initMsgEn
-			}
-			if msg != want {
-				t.Errorf("getInitMsg(%q) returned wrong struct", tt.lang)
-			}
-		})
-	}
-}
--- a/cmd/config/init_probe.go
+++ b/cmd/config/init_probe.go
@@ -1,91 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package config
-
-import (
-	"bytes"
-	"context"
-	"fmt"
-	"io"
-	"net/http"
-	"time"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/build"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/credential"
-)
-
-// probeTimeout is the total wall-clock budget for the credential probe step
-// (covering both TAT acquisition and the subsequent probe request).
-const probeTimeout = 3 * time.Second
-
-// runProbe runs a best-effort credential validation after config init has
-// persisted the App ID and App Secret. It returns a non-nil error only for a
-// deterministic credential-rejection signal; every other outcome returns nil
-// so that valid configurations and transient/upstream noise never block the
-// command.
-//
-// The function performs up to two HTTP calls in series, bounded by
-// probeTimeout:
-//
-//  1. A TAT request using the just-saved credentials. credential.FetchTAT
-//     returns a typed errs.* error (via the shared classifyTATResponseCode)
-//     only when the server deterministically rejected the credentials — a
-//     non-zero TAT body code, classified as CategoryConfig / SubtypeInvalidClient
-//     (10003 / 10014) or whatever codemeta maps. That typed error is propagated
-//     so the root dispatcher renders the canonical envelope and `config init`
-//     exits non-zero — identical to how every other token-resolving command
-//     reports the same bad credentials. Ambiguous failures (transport errors,
-//     HTTP non-200, JSON parse errors, timeouts) come back as raw untyped
-//     errors and are swallowed (return nil), so valid configurations are never
-//     disturbed by upstream noise. errs.IsTyped is the discriminator.
-//
-//  2. If TAT succeeded, a POST to the probe endpoint is fired. The outcome of
-//     that call (success, server error, timeout, parse failure) is always
-//     ignored — return nil regardless.
-func runProbe(parent context.Context, factory *cmdutil.Factory, appID, appSecret string, brand core.LarkBrand) error {
-	if factory == nil {
-		return nil
-	}
-	httpClient, err := factory.HttpClient()
-	if err != nil {
-		return nil
-	}
-
-	ctx, cancel := context.WithTimeout(parent, probeTimeout)
-	defer cancel()
-
-	token, err := credential.FetchTAT(ctx, httpClient, brand, appID, appSecret)
-	if err != nil {
-		// A typed error from FetchTAT is a deterministic credential rejection
-		// (classifyTATResponseCode). Propagate it so config init exits with the
-		// same envelope the rest of the CLI uses for bad credentials. Untyped
-		// errors are ambiguous (transport / HTTP / parse / timeout) — stay
-		// silent and let the command succeed.
-		if errs.IsTyped(err) {
-			return err
-		}
-		return nil
-	}
-
-	// TAT succeeded — fire the probe call. Any outcome is ignored.
-	url := core.ResolveEndpoints(brand).Open + "/open-apis/application/v6/larksuite_cli_app/probe"
-	body := []byte(fmt.Sprintf(`{"from":"lark-cli/%s"}`, build.Version))
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body))
-	if err != nil {
-		return nil
-	}
-	req.Header.Set("Authorization", "Bearer "+token)
-	req.Header.Set("Content-Type", "application/json")
-
-	resp, err := httpClient.Do(req)
-	if err != nil {
-		return nil
-	}
-	defer resp.Body.Close()
-	_, _ = io.Copy(io.Discard, resp.Body)
-	return nil
-}
--- a/cmd/config/init_probe_test.go
+++ b/cmd/config/init_probe_test.go
@@ -1,288 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package config
-
-import (
-	"bytes"
-	"context"
-	"errors"
-	"io"
-	"net/http"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/build"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-)
-
-// fakeRT routes requests to per-path handlers and records what it saw.
-type fakeRT struct {
-	tatHandler   func(req *http.Request) (*http.Response, error)
-	probeHandler func(req *http.Request) (*http.Response, error)
-	tatCalls     int
-	probeCalls   int
-	probeReq     *http.Request
-	probeBody    string
-}
-
-func (f *fakeRT) RoundTrip(req *http.Request) (*http.Response, error) {
-	switch {
-	case strings.HasSuffix(req.URL.Path, "/auth/v3/tenant_access_token/internal"):
-		f.tatCalls++
-		if f.tatHandler == nil {
-			return jsonResp(200, `{"code":0,"tenant_access_token":"t-ok"}`), nil
-		}
-		return f.tatHandler(req)
-	case strings.HasSuffix(req.URL.Path, "/application/v6/larksuite_cli_app/probe"):
-		f.probeCalls++
-		f.probeReq = req
-		if req.Body != nil {
-			b, _ := io.ReadAll(req.Body)
-			f.probeBody = string(b)
-		}
-		if f.probeHandler == nil {
-			return jsonResp(200, `{"code":0,"data":{},"msg":"success"}`), nil
-		}
-		return f.probeHandler(req)
-	}
-	return nil, errors.New("unexpected URL: " + req.URL.String())
-}
-
-func jsonResp(code int, body string) *http.Response {
-	return &http.Response{
-		StatusCode: code,
-		Body:       io.NopCloser(strings.NewReader(body)),
-		Header:     make(http.Header),
-	}
-}
-
-// fakeFactory builds a test Factory whose HttpClient is overridden to use
-// the caller-supplied RoundTripper.
-//
-// Wired through cmdutil.TestFactory(t, nil) so the canonical IOStreams,
-// Credential, Keychain and FileIO wiring is in place (per repo test-factory
-// guidance). The HttpClient is then swapped to our stub so we can drive
-// exact HTTP responses for the probe. Config-dir isolation is set up via
-// t.Setenv(LARKSUITE_CLI_CONFIG_DIR, t.TempDir()) so any incidental config
-// touch lands in a temp dir rather than the developer's real config.
-//
-// The returned buffer is the Factory's stderr. runProbe never writes to
-// stderr (it propagates a typed error or stays silent), so every test asserts
-// this buffer stays empty as an invariant.
-func fakeFactory(t *testing.T, rt http.RoundTripper) (*cmdutil.Factory, *bytes.Buffer) {
-	t.Helper()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, _, errBuf, _ := cmdutil.TestFactory(t, nil)
-	f.HttpClient = func() (*http.Client, error) {
-		return &http.Client{Transport: rt}, nil
-	}
-	return f, errBuf
-}
-
-// assertConfigRejection asserts runProbe propagated a deterministic credential
-// rejection: a *errs.ConfigError (CategoryConfig / SubtypeInvalidClient) with
-// the expected upstream code. This is the same typed error every other
-// token-resolving command returns for the same bad credentials, and nothing is
-// written to stderr (the root dispatcher renders the envelope).
-func assertConfigRejection(t *testing.T, err error, errBuf *bytes.Buffer, wantCode int) {
-	t.Helper()
-	if err == nil {
-		t.Fatalf("expected *errs.ConfigError (code %d), got nil", wantCode)
-	}
-	var cfgErr *errs.ConfigError
-	if !errors.As(err, &cfgErr) {
-		t.Fatalf("expected *errs.ConfigError, got %T: %v", err, err)
-	}
-	if cfgErr.Category != errs.CategoryConfig {
-		t.Errorf("Category = %q, want %q", cfgErr.Category, errs.CategoryConfig)
-	}
-	if cfgErr.Subtype != errs.SubtypeInvalidClient {
-		t.Errorf("Subtype = %q, want %q", cfgErr.Subtype, errs.SubtypeInvalidClient)
-	}
-	if cfgErr.Code != wantCode {
-		t.Errorf("Code = %d, want %d", cfgErr.Code, wantCode)
-	}
-	if errBuf.Len() != 0 {
-		t.Errorf("runProbe must not write to stderr, got: %q", errBuf.String())
-	}
-}
-
-// assertSilent asserts runProbe stayed quiet: no propagated error and nothing
-// written to stderr. Used for every ambiguous (non-credential) outcome.
-func assertSilent(t *testing.T, err error, errBuf *bytes.Buffer) {
-	t.Helper()
-	if err != nil {
-		t.Errorf("expected nil (silent), got error: %v", err)
-	}
-	if errBuf.Len() != 0 {
-		t.Errorf("expected no stderr output, got: %q", errBuf.String())
-	}
-}
-
-// 10003 (bad / non-existent app_id) → ConfigError/InvalidClient, propagated.
-func TestRunProbe_TATCode10003_ReturnsConfigError(t *testing.T) {
-	rt := &fakeRT{
-		tatHandler: func(req *http.Request) (*http.Response, error) {
-			return jsonResp(200, `{"code":10003,"msg":"invalid param"}`), nil
-		},
-	}
-	f, errBuf := fakeFactory(t, rt)
-
-	err := runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu)
-
-	if rt.probeCalls != 0 {
-		t.Error("probe endpoint must not be called when TAT fails")
-	}
-	assertConfigRejection(t, err, errBuf, 10003)
-}
-
-// 10014 (real app_id + wrong secret) → ConfigError/InvalidClient via codemeta —
-// the most common real-world rejection, propagated.
-func TestRunProbe_TATCode10014_ReturnsConfigError(t *testing.T) {
-	rt := &fakeRT{
-		tatHandler: func(req *http.Request) (*http.Response, error) {
-			return jsonResp(200, `{"code":10014,"msg":"app secret invalid"}`), nil
-		},
-	}
-	f, errBuf := fakeFactory(t, rt)
-	assertConfigRejection(t, runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu), errBuf, 10014)
-}
-
-// Any non-zero body code is a deterministic rejection and propagates (typed).
-// An unrecognized code falls back to *errs.APIError via BuildAPIError — still
-// typed, so the probe still surfaces it rather than swallowing.
-func TestRunProbe_TATUnknownBodyCode_Propagates(t *testing.T) {
-	rt := &fakeRT{
-		tatHandler: func(req *http.Request) (*http.Response, error) {
-			return jsonResp(200, `{"code":99999,"msg":"future-unknown"}`), nil
-		},
-	}
-	f, errBuf := fakeFactory(t, rt)
-	err := runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu)
-	if err == nil || !errs.IsTyped(err) {
-		t.Fatalf("expected a propagated typed error, got %T: %v", err, err)
-	}
-	if errBuf.Len() != 0 {
-		t.Errorf("runProbe must not write to stderr, got: %q", errBuf.String())
-	}
-}
-
-// Non-200 HTTP at the TAT endpoint is ambiguous (not a payload credential
-// rejection) → silent, exit 0.
-func TestRunProbe_TATHTTPNon200_Silent(t *testing.T) {
-	for _, code := range []int{401, 403, 500} {
-		rt := &fakeRT{
-			tatHandler: func(req *http.Request) (*http.Response, error) {
-				return jsonResp(code, `nope`), nil
-			},
-		}
-		f, errBuf := fakeFactory(t, rt)
-		assertSilent(t, runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu), errBuf)
-	}
-}
-
-func TestRunProbe_TATTransportError_Silent(t *testing.T) {
-	rt := &fakeRT{
-		tatHandler: func(req *http.Request) (*http.Response, error) {
-			return nil, errors.New("network down")
-		},
-	}
-	f, errBuf := fakeFactory(t, rt)
-	assertSilent(t, runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu), errBuf)
-}
-
-func TestRunProbe_TATSuccess_ProbeFails_Silent(t *testing.T) {
-	rt := &fakeRT{
-		probeHandler: func(req *http.Request) (*http.Response, error) {
-			return jsonResp(500, `server error`), nil
-		},
-	}
-	f, errBuf := fakeFactory(t, rt)
-	err := runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu)
-	if rt.probeCalls != 1 {
-		t.Errorf("probe should be called once, got %d", rt.probeCalls)
-	}
-	assertSilent(t, err, errBuf)
-}
-
-func TestRunProbe_TATSuccess_ProbeOK_Silent(t *testing.T) {
-	rt := &fakeRT{}
-	f, errBuf := fakeFactory(t, rt)
-	err := runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu)
-	if rt.tatCalls != 1 || rt.probeCalls != 1 {
-		t.Errorf("expected 1/1 calls, got tat=%d probe=%d", rt.tatCalls, rt.probeCalls)
-	}
-	assertSilent(t, err, errBuf)
-}
-
-func TestRunProbe_ProbeRequestShape(t *testing.T) {
-	rt := &fakeRT{}
-	f, _ := fakeFactory(t, rt)
-	if err := runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	if rt.probeReq == nil {
-		t.Fatal("probe request not captured")
-	}
-	if rt.probeReq.Method != http.MethodPost {
-		t.Errorf("probe method = %s, want POST", rt.probeReq.Method)
-	}
-	if got := rt.probeReq.URL.String(); got != "https://open.feishu.cn/open-apis/application/v6/larksuite_cli_app/probe" {
-		t.Errorf("probe URL = %s", got)
-	}
-	if got := rt.probeReq.Header.Get("Authorization"); got != "Bearer t-ok" {
-		t.Errorf("Authorization = %q, want Bearer t-ok", got)
-	}
-	if !strings.Contains(rt.probeBody, `"from":"lark-cli/`+build.Version+`"`) {
-		t.Errorf("probe body missing from field: %s", rt.probeBody)
-	}
-}
-
-func TestRunProbe_LarkBrand_HostRoutedCorrectly(t *testing.T) {
-	rt := &fakeRT{}
-	f, _ := fakeFactory(t, rt)
-	if err := runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandLark); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if rt.probeReq == nil {
-		t.Fatal("probe request not captured")
-	}
-	if !strings.Contains(rt.probeReq.URL.Host, "larksuite.com") {
-		t.Errorf("probe host = %s, want larksuite.com", rt.probeReq.URL.Host)
-	}
-}
-
-func TestRunProbe_HTTPClientError_Silent(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, _, errBuf, _ := cmdutil.TestFactory(t, nil)
-	f.HttpClient = func() (*http.Client, error) {
-		return nil, errors.New("client init failed")
-	}
-	assertSilent(t, runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu), errBuf)
-}
-
-func TestRunProbe_TimeoutHonored(t *testing.T) {
-	rt := &fakeRT{
-		tatHandler: func(req *http.Request) (*http.Response, error) {
-			<-req.Context().Done()
-			return nil, req.Context().Err()
-		},
-	}
-	f, errBuf := fakeFactory(t, rt)
-
-	start := time.Now()
-	err := runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu)
-	elapsed := time.Since(start)
-
-	if elapsed > 4*time.Second {
-		t.Errorf("runProbe took %v, expected <= ~3s", elapsed)
-	}
-	// A timeout is an ambiguous failure (context deadline → untyped), so it
-	// must stay silent and not block.
-	assertSilent(t, err, errBuf)
-}
--- a/cmd/config/init_test.go
+++ b/cmd/config/init_test.go
@@ -1,133 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package config
-
-import (
-	"errors"
-	"fmt"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// updateExistingProfileWithoutSecret guards four blank-input scenarios. Each
-// must surface as *ValidationError(SubtypeInvalidArgument) per RFC 6749 §5.2:
-// SubtypeInvalidClient is reserved for IAM rejection of malformed credentials,
-// not for missing user input.
-
-func TestUpdateExistingProfileWithoutSecret_NilConfig_EmitsValidationError(t *testing.T) {
-	err := updateExistingProfileWithoutSecret(nil, "", "cli_test", core.BrandFeishu, "en")
-	assertValidationParam(t, err, "--app-secret")
-}
-
-func TestUpdateExistingProfileWithoutSecret_UnknownProfile_EmitsValidationError(t *testing.T) {
-	existing := &core.MultiAppConfig{
-		Apps: []core.AppConfig{{
-			Name:      "default",
-			AppId:     "app-default",
-			AppSecret: core.PlainSecret("secret-default"),
-			Brand:     core.BrandFeishu,
-		}},
-	}
-	err := updateExistingProfileWithoutSecret(existing, "missing-profile", "cli_test", core.BrandFeishu, "en")
-	assertValidationParam(t, err, "--app-secret")
-}
-
-func TestUpdateExistingProfileWithoutSecret_NoCurrentApp_EmitsValidationError(t *testing.T) {
-	existing := &core.MultiAppConfig{
-		CurrentApp: "missing",
-		Apps: []core.AppConfig{{
-			Name:      "default",
-			AppId:     "app-default",
-			AppSecret: core.PlainSecret("secret-default"),
-			Brand:     core.BrandFeishu,
-		}},
-	}
-	err := updateExistingProfileWithoutSecret(existing, "", "cli_test", core.BrandFeishu, "en")
-	assertValidationParam(t, err, "--app-secret")
-}
-
-func TestUpdateExistingProfileWithoutSecret_AppIdMismatch_EmitsValidationError(t *testing.T) {
-	existing := &core.MultiAppConfig{
-		Apps: []core.AppConfig{{
-			Name:      "default",
-			AppId:     "app-default",
-			AppSecret: core.PlainSecret("secret-default"),
-			Brand:     core.BrandFeishu,
-		}},
-	}
-	err := updateExistingProfileWithoutSecret(existing, "", "cli_different", core.BrandFeishu, "en")
-	assertValidationParam(t, err, "--app-secret")
-}
-
-// wrapUpdateExistingProfileErr is the caller-side classifier for the error
-// returned by updateExistingProfileWithoutSecret. It must preserve typed-error
-// exit semantics (regression: typed ValidationError was being downgraded to
-// InternalError by the legacy *output.ExitError-only passthrough).
-
-func TestWrapUpdateExistingProfileErr_NilPassesThrough(t *testing.T) {
-	if got := wrapUpdateExistingProfileErr(nil); got != nil {
-		t.Fatalf("expected nil, got %v", got)
-	}
-}
-
-func TestWrapUpdateExistingProfileErr_TypedValidationErrorPreserved(t *testing.T) {
-	in := errs.NewValidationError(errs.SubtypeInvalidArgument, "App Secret cannot be empty for new profile").
-		WithParam("--app-secret")
-	got := wrapUpdateExistingProfileErr(in)
-	assertValidationParam(t, got, "--app-secret")
-	// Exit code must remain ExitValidation (2), not ExitInternal (5).
-	if code := output.ExitCodeOf(got); code != output.ExitValidation {
-		t.Errorf("ExitCodeOf = %d, want %d (ExitValidation)", code, output.ExitValidation)
-	}
-	// Must NOT be wrapped as *InternalError.
-	var intErr *errs.InternalError
-	if errors.As(got, &intErr) {
-		t.Errorf("typed ValidationError was downgraded to *InternalError: %v", got)
-	}
-}
-
-func TestWrapUpdateExistingProfileErr_LegacyExitErrorPreserved(t *testing.T) {
-	in := &output.ExitError{Code: 7, Err: errors.New("legacy")}
-	got := wrapUpdateExistingProfileErr(in)
-	var exitErr *output.ExitError
-	if !errors.As(got, &exitErr) {
-		t.Fatalf("expected *output.ExitError to pass through, got %T: %v", got, got)
-	}
-	if exitErr.Code != 7 {
-		t.Errorf("Code = %d, want 7", exitErr.Code)
-	}
-}
-
-func TestWrapUpdateExistingProfileErr_UntypedErrorBecomesInternal(t *testing.T) {
-	in := fmt.Errorf("disk full")
-	got := wrapUpdateExistingProfileErr(in)
-	var intErr *errs.InternalError
-	if !errors.As(got, &intErr) {
-		t.Fatalf("expected *errs.InternalError, got %T: %v", got, got)
-	}
-	if intErr.Subtype != errs.SubtypeSDKError {
-		t.Errorf("Subtype = %q, want %q", intErr.Subtype, errs.SubtypeSDKError)
-	}
-}
-
-// assertValidationParam asserts err is *ValidationError with the given Param.
-func assertValidationParam(t *testing.T, err error, wantParam string) {
-	t.Helper()
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-	var valErr *errs.ValidationError
-	if !errors.As(err, &valErr) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if valErr.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("Subtype = %q, want %q", valErr.Subtype, errs.SubtypeInvalidArgument)
-	}
-	if valErr.Param != wantParam {
-		t.Errorf("Param = %q, want %q", valErr.Param, wantParam)
-	}
-}
--- a/cmd/config/keychain_downgrade.go
+++ b/cmd/config/keychain_downgrade.go
@@ -1,72 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build darwin
-
-package config
-
-import (
-	"fmt"
-
-	"github.com/larksuite/cli/errs"
-	"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 errs.NewInternalError(errs.SubtypeSDKError,
-			"keychain downgrade failed: %v", err).
-			WithHint("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.").
-			WithCause(err)
-	}
-
-	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
-}
--- a/cmd/config/keychain_downgrade_other.go
+++ b/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/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"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 errs.NewValidationError(errs.SubtypeInvalidArgument, "keychain-downgrade is only supported on macOS")
-		},
-	}
-	return cmd
-}
--- a/cmd/config/plugins.go
+++ b/cmd/config/plugins.go
@@ -1,101 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package config
-
-import (
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/output"
-	internalplatform "github.com/larksuite/cli/internal/platform"
-)
-
-// NewCmdConfigPlugins exposes the plugin inventory diagnostic command.
-//
-// `config policy show` is intentionally focused on the user-layer Rule
-// (Restrict). Plugins also contribute hooks (Observe / Wrap / Lifecycle)
-// that are not policy gates but still mutate the CLI's runtime behaviour.
-// This command surfaces both halves so an operator can answer "what is
-// this binary doing differently from stock lark-cli?" in one place.
-//
-// Like config policy show, the dispatch path is exempt from policy
-// enforcement (see internal/cmdpolicy/diagnostic.go) so it remains
-// usable under any Rule.
-func NewCmdConfigPlugins(f *cmdutil.Factory) *cobra.Command {
-	cmd := &cobra.Command{
-		Use:    "plugins",
-		Hidden: true, // diagnostic-only; kept callable, omitted from --help so it stays out of AI-agent context
-		Short:  "Inspect installed plugins and their hook contributions",
-		// Same leaf-level no-op as config policy: the parent `config`
-		// group's PersistentPreRunE requires builtin credential, but
-		// this is a read-only diagnostic that must work everywhere.
-		PersistentPreRunE: func(c *cobra.Command, _ []string) error {
-			c.SilenceUsage = true
-			return nil
-		},
-	}
-	cmd.AddCommand(newCmdConfigPluginsShow(f))
-	return cmd
-}
-
-func newCmdConfigPluginsShow(f *cmdutil.Factory) *cobra.Command {
-	cmd := &cobra.Command{
-		Use:   "show",
-		Short: "List successfully installed plugins, their rules, and registered hooks",
-		Long: `Print every plugin that committed during bootstrap, including:
-
-  - name / version / capabilities (FailurePolicy, Restricts, RequiredCLIVersion)
-  - rule (when the plugin called r.Restrict)
-  - hooks: observers (Before / After), wrappers, lifecycle handlers
-
-Hooks are attributed by their namespaced name -- the framework prepends
-the plugin name as the prefix at registration time, so an entry
-"secaudit.audit-pre" belongs to plugin "secaudit".`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			return runConfigPluginsShow(f)
-		},
-	}
-	cmdutil.SetRisk(cmd, "read")
-	return cmd
-}
-
-func runConfigPluginsShow(f *cmdutil.Factory) error {
-	inv := internalplatform.GetActiveInventory()
-	if inv == nil {
-		// Always emit the same field set as the populated branch so
-		// AI agents and CI scripts don't have to branch on whether
-		// `total` is present. `note` makes the unusual state explicit
-		// for human readers.
-		output.PrintJson(f.IOStreams.Out, map[string]any{
-			"plugins": []any{},
-			"total":   0,
-			"note":    "no inventory recorded; bootstrap did not finish",
-		})
-		return nil
-	}
-
-	plugins := make([]map[string]any, 0, len(inv.Plugins))
-	for _, p := range inv.Plugins {
-		entry := map[string]any{
-			"name":         p.Name,
-			"version":      p.Version,
-			"capabilities": p.Capabilities,
-		}
-		if len(p.Rules) > 0 {
-			entry["rules"] = p.Rules
-		}
-		entry["hooks"] = map[string]any{
-			"observers": p.Observers,
-			"wrappers":  p.Wrappers,
-			"lifecycle": p.Lifecycles,
-			"count":     len(p.Observers) + len(p.Wrappers) + len(p.Lifecycles),
-		}
-		plugins = append(plugins, entry)
-	}
-	output.PrintJson(f.IOStreams.Out, map[string]any{
-		"plugins": plugins,
-		"total":   len(plugins),
-	})
-	return nil
-}
--- a/cmd/config/policy.go
+++ b/cmd/config/policy.go
@@ -1,79 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package config
-
-import (
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/internal/cmdpolicy"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/output"
-)
-
-func NewCmdConfigPolicy(f *cmdutil.Factory) *cobra.Command {
-	cmd := &cobra.Command{
-		Use:    "policy",
-		Hidden: true,
-		Short:  "Inspect the user-layer command policy",
-		// Override parent's RequireBuiltinCredentialProvider check; this
-		// group is read-only diagnostic and must work under any provider.
-		PersistentPreRunE: func(c *cobra.Command, _ []string) error {
-			c.SilenceUsage = true
-			return nil
-		},
-	}
-	cmd.AddCommand(newCmdConfigPolicyShow(f))
-	return cmd
-}
-
-func newCmdConfigPolicyShow(f *cmdutil.Factory) *cobra.Command {
-	cmd := &cobra.Command{
-		Use:    "show",
-		Hidden: true,
-		Short:  "Show the active user-layer policy (plugin / yaml / none)",
-		RunE: func(cmd *cobra.Command, args []string) error {
-			return runConfigPolicyShow(f)
-		},
-	}
-	cmdutil.SetRisk(cmd, "read")
-	return cmd
-}
-
-func runConfigPolicyShow(f *cmdutil.Factory) error {
-	active := cmdpolicy.GetActive()
-	if active == nil {
-		output.PrintJson(f.IOStreams.Out, map[string]any{
-			"source": string(cmdpolicy.SourceNone),
-			"note":   "no policy recorded; bootstrap did not run pruning",
-		})
-		return nil
-	}
-
-	sourceName := ""
-	if active.Source.Kind == cmdpolicy.SourcePlugin {
-		sourceName = active.Source.Name
-	}
-	out := map[string]any{
-		"source":       string(active.Source.Kind),
-		"source_name":  sourceName,
-		"denied_paths": active.DeniedPaths,
-	}
-	if len(active.Rules) > 0 {
-		rules := make([]map[string]any, 0, len(active.Rules))
-		for _, r := range active.Rules {
-			rules = append(rules, map[string]any{
-				"name":              r.Name,
-				"description":       r.Description,
-				"allow":             r.Allow,
-				"deny":              r.Deny,
-				"max_risk":          r.MaxRisk,
-				"identities":        r.Identities,
-				"allow_unannotated": r.AllowUnannotated,
-			})
-		}
-		out["rules"] = rules
-	}
-	output.PrintJson(f.IOStreams.Out, out)
-	return nil
-}
--- a/cmd/config/policy_test.go
+++ b/cmd/config/policy_test.go
@@ -1,150 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package config
-
-import (
-	"bytes"
-	"encoding/json"
-	"testing"
-
-	"github.com/larksuite/cli/extension/platform"
-	"github.com/larksuite/cli/internal/cmdpolicy"
-	"github.com/larksuite/cli/internal/cmdutil"
-)
-
-func newPolicyTestFactory() (*cmdutil.Factory, *bytes.Buffer, *bytes.Buffer) {
-	out := &bytes.Buffer{}
-	errOut := &bytes.Buffer{}
-	f := &cmdutil.Factory{
-		IOStreams: cmdutil.NewIOStreams(nil, out, errOut),
-	}
-	return f, out, errOut
-}
-
-// `config policy show` reads the active policy recorded by bootstrap.
-// When nothing is recorded the command must still produce a JSON
-// envelope with source=none and a note explaining the missing context.
-func TestConfigPolicyShow_NoActivePolicy(t *testing.T) {
-	cmdpolicy.ResetActiveForTesting()
-	t.Cleanup(cmdpolicy.ResetActiveForTesting)
-
-	f, out, _ := newPolicyTestFactory()
-	if err := runConfigPolicyShow(f); err != nil {
-		t.Fatalf("show: %v", err)
-	}
-	var got map[string]any
-	if err := json.Unmarshal(out.Bytes(), &got); err != nil {
-		t.Fatalf("not json: %v\n%s", err, out.String())
-	}
-	if got["source"] != "none" {
-		t.Errorf("source = %v, want none", got["source"])
-	}
-	if got["note"] == "" || got["note"] == nil {
-		t.Errorf("expected explanatory note when no policy recorded")
-	}
-}
-
-// When bootstrap recorded an active plugin Rule, `show` emits the rule
-// plus its source.
-func TestConfigPolicyShow_PluginActive(t *testing.T) {
-	cmdpolicy.ResetActiveForTesting()
-	t.Cleanup(cmdpolicy.ResetActiveForTesting)
-
-	rule := &platform.Rule{
-		Name:    "secaudit",
-		Allow:   []string{"docs/**"},
-		MaxRisk: "read",
-	}
-	cmdpolicy.SetActive(&cmdpolicy.ActivePolicy{
-		Rules: []*platform.Rule{rule},
-		Source: cmdpolicy.ResolveSource{
-			Kind: cmdpolicy.SourcePlugin,
-			Name: "secaudit",
-		},
-		DeniedPaths: 42,
-	})
-
-	f, out, _ := newPolicyTestFactory()
-	if err := runConfigPolicyShow(f); err != nil {
-		t.Fatalf("show: %v", err)
-	}
-	var got map[string]any
-	if err := json.Unmarshal(out.Bytes(), &got); err != nil {
-		t.Fatalf("not json: %v\n%s", err, out.String())
-	}
-	if got["source"] != "plugin" {
-		t.Errorf("source = %v, want plugin", got["source"])
-	}
-	if got["source_name"] != "secaudit" {
-		t.Errorf("source_name = %v, want secaudit", got["source_name"])
-	}
-	// json.Unmarshal returns float64 for numbers.
-	if got["denied_paths"] != float64(42) {
-		t.Errorf("denied_paths = %v, want 42", got["denied_paths"])
-	}
-	rulesAny, ok := got["rules"].([]any)
-	if !ok || len(rulesAny) != 1 {
-		t.Fatalf("rules field missing or wrong shape: %v", got["rules"])
-	}
-	ruleMap, ok := rulesAny[0].(map[string]any)
-	if !ok {
-		t.Fatalf("rules[0] wrong type")
-	}
-	if ruleMap["name"] != "secaudit" {
-		t.Errorf("rules[0].name = %v", ruleMap["name"])
-	}
-}
-
-// `source_name` must be empty when source=yaml. The yaml path is
-// deliberately not surfaced (matches engine envelope convention,
-// avoids leaking the user's home dir to AI agents / CI logs). The
-// rule's "name:" field is the disambiguator users should rely on.
-func TestConfigPolicyShow_YamlSourceNameIsEmpty(t *testing.T) {
-	cmdpolicy.ResetActiveForTesting()
-	t.Cleanup(cmdpolicy.ResetActiveForTesting)
-
-	cmdpolicy.SetActive(&cmdpolicy.ActivePolicy{
-		Rules: []*platform.Rule{{Name: "my-yaml-rule"}},
-		Source: cmdpolicy.ResolveSource{
-			Kind: cmdpolicy.SourceYAML,
-			Name: "/Users/alice/.lark-cli/policy.yml",
-		},
-	})
-
-	f, out, _ := newPolicyTestFactory()
-	if err := runConfigPolicyShow(f); err != nil {
-		t.Fatalf("show: %v", err)
-	}
-	var got map[string]any
-	if err := json.Unmarshal(out.Bytes(), &got); err != nil {
-		t.Fatalf("not json: %v\n%s", err, out.String())
-	}
-	if got["source"] != "yaml" {
-		t.Errorf("source = %v, want yaml", got["source"])
-	}
-	if got["source_name"] != "" {
-		t.Errorf("source_name = %q, want empty (yaml path must not leak)", got["source_name"])
-	}
-	// The path must not appear anywhere in the envelope.
-	if bytes.Contains(out.Bytes(), []byte("/Users/alice")) {
-		t.Errorf("envelope leaked yaml path: %s", out.String())
-	}
-}
-
-// Regression: the parent `config` command declares a PersistentPreRunE
-// that calls RequireBuiltinCredentialProvider; env credentials cause
-// it to return external_provider. `config policy` is a diagnostic
-// group that must not be blocked by that check. The group declares
-// its own no-op PersistentPreRunE so cobra's "first walking up from
-// leaf" picks ours over the config parent's.
-func TestConfigPolicy_BypassesConfigParentPersistentPreRunE(t *testing.T) {
-	f, _, _ := newPolicyTestFactory()
-	group := NewCmdConfigPolicy(f)
-	if group.PersistentPreRunE == nil {
-		t.Fatal("config policy group must declare its own PersistentPreRunE to win over config parent")
-	}
-	if err := group.PersistentPreRunE(group, nil); err != nil {
-		t.Errorf("config policy PersistentPreRunE should be no-op, got %v", err)
-	}
-}
--- a/cmd/config/remove.go
+++ b/cmd/config/remove.go
@@ -6,7 +6,6 @@ package config
 import (
 	"fmt"

-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
@@ -33,7 +32,6 @@ func NewCmdConfigRemove(f *cmdutil.Factory, runF func(*ConfigRemoveOptions) erro
 			return configRemoveRun(opts)
 		},
 	}
-	cmdutil.SetRisk(cmd, "write")

 	return cmd
 }
@@ -43,14 +41,14 @@ func configRemoveRun(opts *ConfigRemoveOptions) error {

 	config, err := core.LoadMultiAppConfig()
 	if err != nil || config == nil || len(config.Apps) == 0 {
-		return errs.NewConfigError(errs.SubtypeNotConfigured, "not configured yet")
+		return output.ErrValidation("not configured yet")
 	}

 	// Save empty config first. If this fails, keep secrets and tokens intact so the
 	// existing config can still be retried instead of ending up half-removed.
 	empty := &core.MultiAppConfig{Apps: []core.AppConfig{}}
 	if err := core.SaveMultiAppConfig(empty); err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 	}

 	// Clean up keychain entries for all apps after config is cleared.
--- a/cmd/config/show.go
+++ b/cmd/config/show.go
@@ -9,7 +9,6 @@ import (
 	"os"
 	"strings"

-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
@@ -35,7 +34,6 @@ func NewCmdConfigShow(f *cmdutil.Factory, runF func(*ConfigShowOptions) error) *
 			return configShowRun(opts)
 		},
 	}
-	cmdutil.SetRisk(cmd, "read")

 	return cmd
 }
@@ -48,14 +46,14 @@ func configShowRun(opts *ConfigShowOptions) error {
 		if errors.Is(err, os.ErrNotExist) {
 			return core.NotConfiguredError()
 		}
-		return errs.NewConfigError(errs.SubtypeInvalidConfig, "failed to load config: %v", err).WithCause(err)
+		return output.Errorf(output.ExitValidation, "config", "failed to load config: %v", err)
 	}
 	if config == nil || len(config.Apps) == 0 {
 		return core.NotConfiguredError()
 	}
 	app := config.CurrentAppConfig(f.Invocation.Profile)
 	if app == nil {
-		return errs.NewConfigError(errs.SubtypeNotConfigured, "no active profile").WithHint("run: lark-cli profile list")
+		return output.ErrWithHint(output.ExitValidation, "config", "no active profile", "run: lark-cli profile list")
 	}
 	users := "(no logged-in users)"
 	if len(app.Users) > 0 {
--- a/cmd/config/strict_mode.go
+++ b/cmd/config/strict_mode.go
@@ -7,9 +7,9 @@ import (
 	"context"
 	"fmt"

-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/spf13/cobra"
 )

@@ -66,21 +66,20 @@ explicit user confirmation — never run on your own initiative.`,

 	cmd.Flags().BoolVar(&global, "global", false, "set at global level (applies to all profiles)")
 	cmd.Flags().BoolVar(&reset, "reset", false, "reset profile setting to inherit global")
-	cmdutil.SetRisk(cmd, "write")

 	return cmd
 }

 func resetStrictMode(f *cmdutil.Factory, multi *core.MultiAppConfig, app *core.AppConfig, global bool, args []string) error {
 	if global {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--reset cannot be used with --global").WithParam("--reset")
+		return output.ErrValidation("--reset cannot be used with --global")
 	}
 	if len(args) > 0 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--reset cannot be used with a value argument").WithParam("--reset")
+		return output.ErrValidation("--reset cannot be used with a value argument")
 	}
 	app.StrictMode = nil
 	if err := core.SaveMultiAppConfig(multi); err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 	}
 	fmt.Fprintln(f.IOStreams.ErrOut, "Profile strict-mode reset (inherits global)")
 	return nil
@@ -104,7 +103,7 @@ func setStrictMode(f *cmdutil.Factory, multi *core.MultiAppConfig, app *core.App
 	switch mode {
 	case core.StrictModeBot, core.StrictModeUser, core.StrictModeOff:
 	default:
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid value %q, valid values: bot | user | off", value)
+		return output.ErrValidation("invalid value %q, valid values: bot | user | off", value)
 	}

 	// Capture the old mode at the SAME scope being changed, so we can warn
@@ -144,7 +143,7 @@ func setStrictMode(f *cmdutil.Factory, multi *core.MultiAppConfig, app *core.App
 	}

 	if err := core.SaveMultiAppConfig(multi); err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 	}

 	if oldMode == core.StrictModeBot && (mode == core.StrictModeUser || mode == core.StrictModeOff) {
--- a/cmd/doctor/doctor.go
+++ b/cmd/doctor/doctor.go
@@ -14,12 +14,11 @@ 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/transport"
 	"github.com/larksuite/cli/internal/update"
 )

@@ -44,7 +43,6 @@ func NewCmdDoctor(f *cmdutil.Factory) *cobra.Command {
 	}
 	cmdutil.DisableAuthCheck(cmd)
 	cmd.Flags().BoolVar(&opts.Offline, "offline", false, "skip network checks (only verify local state)")
-	cmdutil.SetRisk(cmd, "read")

 	return cmd
 }
@@ -52,7 +50,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"`
 }
@@ -119,31 +117,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 {
@@ -153,9 +179,7 @@ func networkChecks(ctx context.Context, opts *DoctorOptions, ep core.Endpoints)
 		}
 	}

-	// Use the shared proxy-plugin-aware transport so connectivity checks reflect
-	// the real egress path (and are blocked when proxy plugin fails closed).
-	httpClient := transport.NewHTTPClient(0)
+	httpClient := &http.Client{}
 	mcpURL := ep.MCP + "/mcp"

 	type probeResult struct {
@@ -207,6 +231,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).
--- a/cmd/doctor/doctor_test.go
+++ b/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)
-}
--- a/cmd/error_auth_hint.go
+++ b/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,43 +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). Existing
-// Hint text is preserved; scopes are appended on a new line.
-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.
-//
-// Deprecated: enrichment for the legacy envelope; the typed path is
-// applyNeedAuthorizationHint above.
+// 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
@@ -62,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
@@ -149,7 +116,47 @@ func resolveDeclaredServiceMethodScopes(cmd *cobra.Command, identity string) []s
 	if methodMap == nil {
 		return nil
 	}
-	return registry.DeclaredScopesForMethod(methodMap, identity)
+	return declaredScopesForMethod(methodMap, identity)
+}
+
+// declaredScopesForMethod returns all requiredScopes when present; otherwise it
+// resolves the single recommended scope from the method's scopes list.
+func declaredScopesForMethod(method map[string]interface{}, identity string) []string {
+	if requiredRaw, ok := method["requiredScopes"].([]interface{}); ok && len(requiredRaw) > 0 {
+		return interfaceStrings(requiredRaw)
+	}
+
+	rawScopes, _ := method["scopes"].([]interface{})
+	if len(rawScopes) == 0 {
+		return nil
+	}
+	recommended := registry.SelectRecommendedScope(rawScopes, identity)
+	if recommended == "" {
+		for _, raw := range rawScopes {
+			if scope, ok := raw.(string); ok && scope != "" {
+				recommended = scope
+				break
+			}
+		}
+	}
+	if recommended == "" {
+		return nil
+	}
+	return []string{recommended}
+}
+
+// interfaceStrings converts a []interface{} containing strings into a compact
+// []string, skipping empty or non-string values.
+func interfaceStrings(values []interface{}) []string {
+	scopes := make([]string, 0, len(values))
+	for _, value := range values {
+		scope, ok := value.(string)
+		if !ok || scope == "" {
+			continue
+		}
+		scopes = append(scopes, scope)
+	}
+	return scopes
 }

 // shortcutSupportsIdentity reports whether a shortcut supports the requested
--- a/cmd/event/bus.go
+++ b/cmd/event/bus.go
@@ -64,7 +64,6 @@ func NewCmdBus(f *cmdutil.Factory) *cobra.Command {

 	cmd.Flags().StringVar(&domain, "domain", "", "API domain")
 	_ = cmd.Flags().MarkHidden("domain")
-	cmdutil.SetRisk(cmd, "write")

 	return cmd
 }
--- a/cmd/event/consume.go
+++ b/cmd/event/consume.go
@@ -70,7 +70,6 @@ Use 'event schema <EventKey>' for parameter details.`,
 	_ = cmd.RegisterFlagCompletionFunc("as", func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
 		return []string{"user", "bot", "auto"}, cobra.ShellCompDirectiveNoFileComp
 	})
-	cmdutil.SetRisk(cmd, "read")

 	return cmd
 }
--- a/cmd/event/list.go
+++ b/cmd/event/list.go
@@ -26,7 +26,6 @@ func NewCmdList(f *cmdutil.Factory) *cobra.Command {
 		},
 	}
 	cmd.Flags().BoolVar(&asJSON, "json", false, "Emit the full EventKey list as JSON (for AI / scripts)")
-	cmdutil.SetRisk(cmd, "read")
 	return cmd
 }

--- a/cmd/event/runtime.go
+++ b/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
--- a/cmd/event/schema.go
+++ b/cmd/event/schema.go
@@ -88,7 +88,6 @@ func NewCmdSchema(f *cmdutil.Factory) *cobra.Command {
 		},
 	}
 	cmd.Flags().BoolVar(&asJSON, "json", false, "Emit the EventKey definition + resolved schema as JSON (for AI / scripts)")
-	cmdutil.SetRisk(cmd, "read")
 	return cmd
 }

--- a/cmd/event/status.go
+++ b/cmd/event/status.go
@@ -37,7 +37,6 @@ func NewCmdStatus(f *cmdutil.Factory) *cobra.Command {
 	cmd.Flags().BoolVar(&asJSON, "json", false, "Emit status as JSON (for AI / scripts)")
 	cmd.Flags().BoolVar(&current, "current", false, "Only show status for the current profile's app")
 	cmd.Flags().BoolVar(&failOnOrphan, "fail-on-orphan", false, "Exit 2 when any orphan bus is detected (default: always exit 0)")
-	cmdutil.SetRisk(cmd, "read")
 	return cmd
 }

--- a/cmd/event/stop.go
+++ b/cmd/event/stop.go
@@ -70,7 +70,6 @@ Exit code: 2 if any target was refused or errored, 0 otherwise.
 	cmd.Flags().BoolVar(&o.all, "all", false, "Stop all running bus daemons")
 	cmd.Flags().BoolVar(&o.force, "force", false, "Stop even with active consumers; on shutdown-timeout also SIGKILL the bus")
 	cmd.Flags().BoolVar(&o.asJSON, "json", false, "Emit results as JSON (for AI / scripts)")
-	cmdutil.SetRisk(cmd, "write")

 	return cmd
 }
--- a/cmd/global_flags_test.go
+++ b/cmd/global_flags_test.go
@@ -78,7 +78,7 @@ func TestIsSingleAppMode_MultiApp(t *testing.T) {
 }

 func TestBuildInternal_HideProfileOption(t *testing.T) {
-	_, root, _ := buildInternal(context.Background(), cmdutil.InvocationContext{}, testStreams(), HideProfile(true))
+	_, root := buildInternal(context.Background(), cmdutil.InvocationContext{}, testStreams(), HideProfile(true))

 	flag := root.PersistentFlags().Lookup("profile")
 	if flag == nil {
@@ -90,7 +90,7 @@ func TestBuildInternal_HideProfileOption(t *testing.T) {
 }

 func TestBuildInternal_DefaultShowsProfileFlag(t *testing.T) {
-	_, root, _ := buildInternal(context.Background(), cmdutil.InvocationContext{}, testStreams())
+	_, root := buildInternal(context.Background(), cmdutil.InvocationContext{}, testStreams())

 	flag := root.PersistentFlags().Lookup("profile")
 	if flag == nil {
--- a/cmd/platform_bootstrap.go
+++ b/cmd/platform_bootstrap.go
@@ -1,298 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd
-
-import (
-	"context"
-	"fmt"
-	"io"
-	"path/filepath"
-	"strings"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/extension/platform"
-	"github.com/larksuite/cli/internal/cmdpolicy"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/hook"
-	internalplatform "github.com/larksuite/cli/internal/platform"
-	"github.com/larksuite/cli/internal/vfs"
-)
-
-// userPolicyFileName is the conventional filename for the user-layer Rule.
-// Lives under ~/.lark-cli/ to match the rest of the CLI's user-state
-// directory.
-const userPolicyFileName = "policy.yml"
-
-// applyUserPolicyPruning resolves the user-layer Rule from plugin
-// contributions and/or ~/.lark-cli/policy.yml and installs denyStubs
-// for commands it rejects.
-//
-// Missing yaml is not an error -- the CLI runs with no user-layer
-// restriction. A malformed Rule (bad MaxRisk enum, malformed glob, etc.)
-// surfaces via the returned error; the caller decides how to handle it.
-//
-// pluginRules carries Plugin.Restrict() contributions collected from
-// the InstallAll phase; nil/empty is fine.
-func applyUserPolicyPruning(rootCmd *cobra.Command, pluginRules []cmdpolicy.PluginRule) error {
-	// Plugin rules shadow the yaml source entirely (Resolve: plugin >
-	// yaml). When a plugin contributed rules we therefore do NOT even
-	// read ~/.lark-cli/policy.yml: build.go fail-CLOSES on any policy
-	// error once a plugin is present, so reading a malformed yaml here
-	// would let an unrelated broken file on the user's machine abort a
-	// plugin-governed binary -- exactly the file the plugin is supposed
-	// to shadow. Skipping the read keeps the shadow contract honest.
-	var (
-		yamlRules []*platform.Rule
-		yamlPath  string
-	)
-	if len(pluginRules) == 0 {
-		p, perr := userPolicyPath()
-		if perr != nil {
-			// No user home dir means we cannot locate the policy. Treat
-			// the same as "file missing": no pruning, no error. This keeps
-			// non-interactive CI environments (no HOME set) running.
-			p = ""
-		}
-		yamlPath = p
-		loaded, lerr := cmdpolicy.LoadYAMLPolicy(yamlPath)
-		if lerr != nil {
-			// Yaml-only failures are fail-OPEN at the caller (warn and
-			// continue), but the active-policy snapshot is process-global
-			// and may still carry data from a previous build in long-lived
-			// embedders / tests. Clear it explicitly so `config policy
-			// show` reports "no policy" instead of a stale rule that
-			// doesn't reflect the current command tree.
-			cmdpolicy.SetActive(nil)
-			return lerr
-		}
-		yamlRules = loaded
-	}
-
-	rules, source, err := cmdpolicy.Resolve(cmdpolicy.Sources{
-		PluginRules: pluginRules,
-		YAMLRules:   yamlRules,
-		YAMLPath:    yamlPath,
-	})
-	if err != nil {
-		cmdpolicy.SetActive(nil)
-		return err
-	}
-	if len(rules) == 0 {
-		cmdpolicy.SetActive(&cmdpolicy.ActivePolicy{Source: source})
-		return nil
-	}
-
-	// RuleName attributes a denial to a specific rule in the envelope.
-	// With a single rule that is unambiguous and preserves the legacy
-	// envelope verbatim; with several rules a denial means "no rule
-	// granted it", which has no single owner, so the field is left empty
-	// and reason_code=no_matching_rule carries the meaning instead.
-	ruleName := ""
-	if len(rules) == 1 {
-		ruleName = rules[0].Name
-	}
-
-	engine := cmdpolicy.NewSet(rules)
-	decisions := engine.EvaluateAll(rootCmd)
-	denied := cmdpolicy.BuildDeniedByPath(rootCmd, decisions, source, ruleName)
-	cmdpolicy.Apply(rootCmd, denied)
-
-	cmdpolicy.SetActive(&cmdpolicy.ActivePolicy{
-		Rules:       rules,
-		Source:      source,
-		DeniedPaths: len(denied),
-	})
-	return nil
-}
-
-// installPluginsAndHooks runs the InstallAll phase on the globally-
-// registered plugins, returning the Plugin.Restrict contributions for
-// cmdpolicy and the populated hook.Registry for the runtime wrapper.
-// Errors from FailClosed plugins propagate; FailOpen failures are
-// warned to errOut and the loop continues.
-func installPluginsAndHooks(errOut io.Writer) (*internalplatform.InstallResult, error) {
-	plugins := platform.RegisteredPlugins()
-	if len(plugins) == 0 {
-		return &internalplatform.InstallResult{Registry: nil}, nil
-	}
-	return internalplatform.InstallAll(plugins, errOut)
-}
-
-// recordInventory builds and stores the plugin inventory snapshot for
-// diagnostic commands (config plugins show) to read at runtime. Called
-// once from build.go after applyUserPolicyPruning + wireHooks succeed.
-func recordInventory(installResult *internalplatform.InstallResult) {
-	if installResult == nil {
-		internalplatform.SetActiveInventory(nil)
-		return
-	}
-	pluginSrcs := make([]internalplatform.PluginInventorySource, 0, len(installResult.Plugins))
-	for _, p := range installResult.Plugins {
-		pluginSrcs = append(pluginSrcs, internalplatform.PluginInventorySource{
-			Name:         p.Name,
-			Version:      p.Version,
-			Capabilities: p.Capabilities,
-		})
-	}
-	ruleSrcs := make([]internalplatform.RuleInventorySource, 0, len(installResult.PluginRules))
-	for _, r := range installResult.PluginRules {
-		if r.Rule == nil {
-			continue
-		}
-		idents := make([]string, len(r.Rule.Identities))
-		for i, id := range r.Rule.Identities {
-			idents[i] = string(id)
-		}
-		ruleSrcs = append(ruleSrcs, internalplatform.RuleInventorySource{
-			PluginName:       r.PluginName,
-			Allow:            r.Rule.Allow,
-			Deny:             r.Rule.Deny,
-			MaxRisk:          string(r.Rule.MaxRisk),
-			Identities:       idents,
-			RuleName:         r.Rule.Name,
-			Desc:             r.Rule.Description,
-			AllowUnannotated: r.Rule.AllowUnannotated,
-		})
-	}
-	internalplatform.SetActiveInventory(internalplatform.BuildInventory(pluginSrcs, installResult.Registry, ruleSrcs))
-}
-
-// wireHooks installs Observer/Wrapper hooks onto every runnable command
-// and emits the Startup lifecycle event. The registry may be nil when
-// no plugin contributed any hook -- the function short-circuits in
-// that case to avoid useless RunE wrapping.
-func wireHooks(ctx context.Context, rootCmd *cobra.Command, reg *hook.Registry) error {
-	if reg == nil {
-		return nil
-	}
-	hook.Install(rootCmd, reg, cobraCommandViewSource{})
-	return hook.Emit(ctx, reg, platform.Startup, nil)
-}
-
-// cobraCommandViewSource is the default CommandViewSource: it returns a
-// live view over the *cobra.Command. Strict-mode's Remove+Add stub
-// (cmd/prune.go::strictModeStubFrom) explicitly forwards the original
-// annotations + Short/Long so the live view keeps reporting Risk /
-// Identities / Domain through the replacement. User-layer policy
-// (cmdpolicy/apply.go::installDenyStub) mutates in place, preserving
-// metadata trivially.
-type cobraCommandViewSource struct{}
-
-func (cobraCommandViewSource) View(cmd *cobra.Command) platform.CommandView {
-	return cobraCommandView{cmd: cmd}
-}
-
-// cobraCommandView adapts *cobra.Command to the CommandView interface.
-type cobraCommandView struct {
-	cmd *cobra.Command
-}
-
-func (v cobraCommandView) Path() string {
-	return cmdpolicy.CanonicalPath(v.cmd)
-}
-
-func (v cobraCommandView) Domain() string {
-	for c := v.cmd; c != nil; c = c.Parent() {
-		if c.Annotations == nil {
-			continue
-		}
-		if v, ok := c.Annotations["cmdmeta.domain"]; ok && v != "" {
-			return v
-		}
-	}
-	return ""
-}
-
-func (v cobraCommandView) Risk() (platform.Risk, bool) {
-	for c := v.cmd; c != nil; c = c.Parent() {
-		if c.Annotations == nil {
-			continue
-		}
-		if r, ok := c.Annotations["risk_level"]; ok && r != "" {
-			return platform.Risk(r), true
-		}
-	}
-	return "", false
-}
-
-func (v cobraCommandView) Identities() []platform.Identity {
-	for c := v.cmd; c != nil; c = c.Parent() {
-		if c.Annotations == nil {
-			continue
-		}
-		if raw, ok := c.Annotations["lark:supportedIdentities"]; ok && raw != "" {
-			parts := splitCSV(raw)
-			out := make([]platform.Identity, len(parts))
-			for i, p := range parts {
-				out[i] = platform.Identity(p)
-			}
-			return out
-		}
-	}
-	return nil
-}
-
-func (v cobraCommandView) Annotation(key string) (string, bool) {
-	if v.cmd.Annotations == nil {
-		return "", false
-	}
-	s, ok := v.cmd.Annotations[key]
-	return s, ok
-}
-
-// splitCSV is a tiny csv-without-quotes helper. The
-// lark:supportedIdentities annotation is always plain
-// "user" / "bot" / "user,bot" without escaping.
-func splitCSV(s string) []string {
-	out := []string{}
-	start := 0
-	for i := 0; i < len(s); i++ {
-		if s[i] == ',' {
-			out = append(out, s[start:i])
-			start = i + 1
-		}
-	}
-	out = append(out, s[start:])
-	return out
-}
-
-// userPolicyPath returns the path of <baseConfigDir>/policy.yml.
-//
-// The base directory honours LARKSUITE_CLI_CONFIG_DIR (via
-// core.GetBaseConfigDir) so that test isolation, container deployments
-// and per-Agent config overrides all see a consistent policy location.
-// Using vfs.UserHomeDir directly here would silently bypass the env
-// override and route every test through the real ~/.lark-cli.
-//
-// The error return is retained for caller compatibility but is always
-// nil today: GetBaseConfigDir falls back to a relative ".lark-cli" when
-// the home dir can't be resolved, and the resolver already treats a
-// missing file as "no policy".
-func userPolicyPath() (string, error) {
-	return filepath.Join(core.GetBaseConfigDir(), userPolicyFileName), nil
-}
-
-// warnPolicyError writes a one-line stderr warning when the user policy
-// fails to load. V1 yaml errors are fail-OPEN -- the CLI keeps running
-// without policy enforcement so the user can fix the typo. Plugin-supplied
-// rules are fail-CLOSED instead because integrators take a code-level
-// responsibility for them.
-//
-// Wrapped errors may carry the absolute policy path (os.PathError); fold
-// the home prefix to "~" before emitting so stderr piped into agents /
-// CI logs does not leak the user's home directory.
-func warnPolicyError(errOut io.Writer, err error) {
-	if err == nil {
-		return
-	}
-	fmt.Fprintf(errOut, "warning: user policy not applied: %s\n", redactHome(err.Error()))
-}
-
-func redactHome(s string) string {
-	if home, err := vfs.UserHomeDir(); err == nil && home != "" {
-		s = strings.ReplaceAll(s, home, "~")
-	}
-	return s
-}
--- a/cmd/platform_bootstrap_test.go
+++ b/cmd/platform_bootstrap_test.go
@@ -1,303 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd
-
-import (
-	"bytes"
-	"context"
-	"errors"
-	"os"
-	"path/filepath"
-	"testing"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/extension/platform"
-	"github.com/larksuite/cli/internal/cmdpolicy"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// tmpHome creates a tempdir, points $HOME at it, and returns the path to
-// the ~/.lark-cli/ subdirectory (created). The HOME env var is restored
-// when the test ends.
-//
-// LARKSUITE_CLI_CONFIG_DIR is force-set to the same path. Without that
-// override, a developer running the tests with a personal
-// LARKSUITE_CLI_CONFIG_DIR exported in their shell (or a CI runner with
-// a baked-in value) would resolve userPolicyPath() to their real
-// machine and bleed unrelated yaml into the test fixtures. With the
-// override pinned here, the test is hermetic regardless of the host
-// environment.
-func tmpHome(t *testing.T) string {
-	t.Helper()
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
-	t.Setenv("USERPROFILE", dir) // Windows fallback for os.UserHomeDir
-	cfgDir := filepath.Join(dir, ".lark-cli")
-	if err := os.MkdirAll(cfgDir, 0o755); err != nil {
-		t.Fatalf("mkdir: %v", err)
-	}
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", cfgDir)
-	return cfgDir
-}
-
-// writePolicy writes a policy.yml into the user config dir.
-func writePolicy(t *testing.T, cfgDir string, body string) {
-	t.Helper()
-	if err := os.WriteFile(filepath.Join(cfgDir, "policy.yml"), []byte(body), 0o644); err != nil {
-		t.Fatalf("write policy: %v", err)
-	}
-}
-
-// fakeTree builds a minimal command tree with the same shape the real
-// CLI exposes for these tests: lark-cli has a docs group with +fetch and
-// +update, and an im group with +send. Each leaf has its risk_level set
-// so MaxRisk filtering exercises a real path.
-func fakeTree(t *testing.T) *cobra.Command {
-	t.Helper()
-	root := &cobra.Command{Use: "lark-cli"}
-
-	docs := &cobra.Command{Use: "docs"}
-	root.AddCommand(docs)
-	addLeaf(docs, "+fetch", "read")
-	addLeaf(docs, "+update", "write")
-	addLeaf(docs, "+delete-doc", "high-risk-write")
-
-	im := &cobra.Command{Use: "im"}
-	root.AddCommand(im)
-	addLeaf(im, "+send", "write")
-
-	return root
-}
-
-func addLeaf(parent *cobra.Command, use, risk string) {
-	leaf := &cobra.Command{
-		Use:  use,
-		RunE: func(*cobra.Command, []string) error { return nil },
-	}
-	cmdutil.SetRisk(leaf, risk)
-	parent.AddCommand(leaf)
-}
-
-// findLeaf walks the tree by Use names.
-func findLeaf(t *testing.T, parent *cobra.Command, names ...string) *cobra.Command {
-	t.Helper()
-	cur := parent
-	for _, n := range names {
-		var next *cobra.Command
-		for _, c := range cur.Commands() {
-			if c.Use == n {
-				next = c
-				break
-			}
-		}
-		if next == nil {
-			t.Fatalf("child %q not found under %q", n, cur.Use)
-		}
-		cur = next
-	}
-	return cur
-}
-
-// Happy path: a valid policy.yml denies one specific command. The denied
-// command's RunE returns a typed ExitError envelope; allowed commands are
-// untouched.
-func TestApplyUserPolicyPruning_appliesValidPolicy(t *testing.T) {
-	cfgDir := tmpHome(t)
-	writePolicy(t, cfgDir, `
-name: test-policy
-allow: ["docs/**", "contact/**"]
-deny: ["docs/+delete-doc"]
-max_risk: write
-`)
-
-	root := fakeTree(t)
-	if err := applyUserPolicyPruning(root, nil); err != nil {
-		t.Fatalf("apply policy: %v", err)
-	}
-
-	// docs/+delete-doc must be denied (Deny match).
-	deleteCmd := findLeaf(t, root, "docs", "+delete-doc")
-	if !deleteCmd.Hidden {
-		t.Errorf("+delete-doc should be hidden after pruning")
-	}
-	err := deleteCmd.RunE(deleteCmd, nil)
-	if err == nil {
-		t.Fatalf("+delete-doc RunE should return an error")
-	}
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil || exitErr.Detail.Type != "command_denied" {
-		t.Fatalf("expected command_denied ExitError, got %T %+v", err, err)
-	}
-	detail, ok := exitErr.Detail.Detail.(map[string]any)
-	if !ok || detail["reason_code"] != "command_denylisted" {
-		t.Errorf("reason_code = %v, want command_denylisted", detail["reason_code"])
-	}
-
-	// im/+send must be denied (domain not in Allow).
-	send := findLeaf(t, root, "im", "+send")
-	if !send.Hidden {
-		t.Errorf("im/+send should be hidden (not in Allow)")
-	}
-
-	// docs/+update must stay alive (domain matches, risk within max).
-	update := findLeaf(t, root, "docs", "+update")
-	if update.Hidden {
-		t.Errorf("docs/+update should remain visible")
-	}
-	if err := update.RunE(update, nil); err != nil {
-		t.Errorf("docs/+update RunE should succeed, got %v", err)
-	}
-}
-
-// Missing file means no pruning -- the CLI runs unrestricted with the
-// full command surface. This is the default case for users who haven't
-// opted into pruning.
-func TestApplyUserPolicyPruning_missingFileIsSilent(t *testing.T) {
-	tmpHome(t) // home set but no policy.yml written
-
-	root := fakeTree(t)
-	if err := applyUserPolicyPruning(root, nil); err != nil {
-		t.Fatalf("missing policy should not error, got %v", err)
-	}
-
-	// Every leaf must remain non-Hidden.
-	for _, sub := range []string{"+fetch", "+update", "+delete-doc"} {
-		cmd := findLeaf(t, root, "docs", sub)
-		if cmd.Hidden {
-			t.Errorf("%s should not be Hidden when no policy file exists", sub)
-		}
-	}
-}
-
-// Invalid yaml content (parse error) surfaces as an error from the
-// wiring. The build path then decides whether to fail-open or
-// fail-closed; the wiring itself stays neutral.
-func TestApplyUserPolicyPruning_malformedYamlReturnsError(t *testing.T) {
-	cfgDir := tmpHome(t)
-	writePolicy(t, cfgDir, "::: not yaml :::")
-
-	root := fakeTree(t)
-	err := applyUserPolicyPruning(root, nil)
-	if err == nil {
-		t.Fatalf("malformed yaml should produce an error")
-	}
-}
-
-// When a plugin contributed rules, a malformed user policy.yml must NOT
-// abort: plugin rules shadow yaml entirely, so the broken file is never
-// read. Regression -- previously LoadYAMLPolicy ran first and an
-// unrelated broken yaml on the user's machine could fatal a
-// plugin-governed binary (build.go fail-CLOSES on policy errors when a
-// plugin is present).
-func TestApplyUserPolicyPruning_pluginRulesSkipBrokenYaml(t *testing.T) {
-	cfgDir := tmpHome(t)
-	t.Cleanup(cmdpolicy.ResetActiveForTesting)
-	writePolicy(t, cfgDir, "::: not yaml :::") // broken on purpose
-
-	pluginRules := []cmdpolicy.PluginRule{
-		{PluginName: "secaudit", Rule: &platform.Rule{
-			Name:    "docs-only",
-			Allow:   []string{"docs/**"},
-			MaxRisk: "write",
-		}},
-	}
-	root := fakeTree(t)
-	if err := applyUserPolicyPruning(root, pluginRules); err != nil {
-		t.Fatalf("plugin rules must shadow (and skip reading) yaml; broken yaml should not error, got %v", err)
-	}
-
-	// Plugin rule actually applied: im/+send is outside docs/** -> hidden.
-	if send := findLeaf(t, root, "im", "+send"); !send.Hidden {
-		t.Errorf("im/+send should be hidden by plugin rule (not in docs/** allow)")
-	}
-	// docs/+update is within allow and at/below max_risk -> stays visible.
-	if update := findLeaf(t, root, "docs", "+update"); update.Hidden {
-		t.Errorf("docs/+update should remain visible under plugin rule")
-	}
-}
-
-// Semantically-invalid Rule (bad MaxRisk) reaches ValidateRule inside
-// Resolve and produces an error. This is the safety contract: a typo in
-// the rule must not silently lower the pruning bar.
-func TestApplyUserPolicyPruning_invalidRuleReturnsError(t *testing.T) {
-	cfgDir := tmpHome(t)
-	writePolicy(t, cfgDir, "max_risk: nukem\n")
-
-	root := fakeTree(t)
-	err := applyUserPolicyPruning(root, nil)
-	if err == nil {
-		t.Fatalf("invalid MaxRisk should produce an error")
-	}
-}
-
-// warnPolicyError emits to the supplied writer when err is non-nil and
-// stays silent for nil. Verifies the build.go fail-open behaviour can be
-// observed by users.
-func TestWarnPolicyError(t *testing.T) {
-	var buf bytes.Buffer
-	warnPolicyError(&buf, nil)
-	if buf.Len() != 0 {
-		t.Fatalf("warnPolicyError with nil err should write nothing, got %q", buf.String())
-	}
-
-	buf.Reset()
-	warnPolicyError(&buf, errors.New("boom"))
-	if buf.String() != "warning: user policy not applied: boom\n" {
-		t.Fatalf("warnPolicyError output = %q", buf.String())
-	}
-}
-
-// End-to-end through buildInternal: when a valid policy.yml exists in
-// HOME, building the real command tree applies pruning to it. This is
-// the "actually integrated" test -- it exercises the wiring point in
-// build.go itself, not just the helper.
-func TestBuildInternal_appliesPolicyToRealTree(t *testing.T) {
-	cfgDir := tmpHome(t)
-	// Deny one specific shortcut path that we know exists in the real
-	// service tree -- we cannot enumerate it from a unit test, so we
-	// use an Allow-list that matches nothing to deny everything except
-	// the root, and then verify ANY non-root command was hidden.
-	writePolicy(t, cfgDir, `
-name: deny-everything
-deny: ["**"]
-`)
-
-	root := Build(context.Background(), buildInvocationForTest(t))
-
-	// Find any leaf and verify it was hidden.
-	var foundHidden bool
-	walk(root, func(c *cobra.Command) {
-		if c.HasParent() && c.Runnable() && c.Hidden {
-			foundHidden = true
-		}
-	})
-	if !foundHidden {
-		t.Fatalf("expected at least one runnable command to be Hidden after deny=** policy")
-	}
-
-	// Root itself must stay alive.
-	if root.Hidden {
-		t.Errorf("root command must not be Hidden even under deny-everything policy")
-	}
-}
-
-func walk(cmd *cobra.Command, fn func(*cobra.Command)) {
-	if cmd == nil {
-		return
-	}
-	fn(cmd)
-	for _, c := range cmd.Commands() {
-		walk(c, fn)
-	}
-}
-
-// buildInvocationForTest returns a minimal cmdutil.InvocationContext so
-// build.go's pure-assembly path can construct a tree without touching
-// real config / credentials. Profile name is the empty default.
-func buildInvocationForTest(t *testing.T) cmdutil.InvocationContext {
-	t.Helper()
-	return cmdutil.InvocationContext{}
-}
--- a/cmd/platform_guards.go
+++ b/cmd/platform_guards.go
@@ -1,279 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd
-
-import (
-	"errors"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/internal/cmdpolicy"
-	"github.com/larksuite/cli/internal/hook"
-	"github.com/larksuite/cli/internal/output"
-	internalplatform "github.com/larksuite/cli/internal/platform"
-)
-
-// installFatalGuard wires a fail-closed guard at every cobra dispatch
-// path on rootCmd. Used by the three abort-side fatal paths:
-//
-//   - FailClosed plugin install failure  (installPluginInstallErrorGuard)
-//   - Plugin Restrict conflict           (installPluginConflictGuard)
-//   - Startup lifecycle handler failure  (installPluginLifecycleErrorGuard)
-//
-// **Why we walk the tree rather than set PersistentPreRunE on root**:
-// cobra's PersistentPreRunE has "first PersistentPreRunE wins"
-// semantics -- the lookup starts at the invoked command and walks UP,
-// stopping at the first non-nil PersistentPreRunE. Subcommands that
-// declare their own PersistentPreRunE (cmd/auth/auth.go and
-// cmd/config/config.go both do) would shadow root's, letting a
-// fail-closed condition silently bypass via `lark-cli auth foo`.
-//
-// The fix: replace the RunE of every runnable command with one that
-// returns makeErr(). Subcommands cannot bypass because the dispatch
-// lands directly on their RunE, which now carries the guard.
-//
-// 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
-	// walkGuard catches them.
-	//
-	//   - "completion" (user-visible): InitDefaultCompletionCmd
-	//   - "__complete" (internal shell-completion RPC): no public
-	//     constructor; we add our own stub with the same name. cobra's
-	//     internal initCompleteCmd checks for an existing "__complete"
-	//     and skips registration if found, so our stub stays in place.
-	//     (Cobra dispatches the "__completeNoDesc" alias through the
-	//     same RunE, so guarding "__complete" covers both.)
-	rootCmd.InitDefaultCompletionCmd()
-	alreadyPresent := false
-	for _, c := range rootCmd.Commands() {
-		if c.Name() == "__complete" {
-			alreadyPresent = true
-			break
-		}
-	}
-	if !alreadyPresent {
-		rootCmd.AddCommand(&cobra.Command{
-			Use:    "__complete",
-			Hidden: true,
-			RunE:   func(*cobra.Command, []string) error { return makeErr() },
-		})
-	}
-
-	rootCmd.PersistentPreRunE = func(cmd *cobra.Command, args []string) error {
-		cmd.SilenceUsage = true
-		return makeErr()
-	}
-	rootCmd.PersistentPreRun = nil
-	walkGuard(rootCmd, makeErr)
-}
-
-// 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
-		if errors.As(installErr, &pi) {
-			return &output.ExitError{
-				Code: output.ExitValidation,
-				Detail: &output.ErrDetail{
-					Type:    "plugin_install",
-					Message: pi.Error(),
-					Detail: map[string]any{
-						"plugin":      pi.PluginName,
-						"reason_code": pi.ReasonCode,
-						"reason":      pi.Reason,
-					},
-				},
-				Err: installErr,
-			}
-		}
-		return &output.ExitError{
-			Code: output.ExitValidation,
-			Detail: &output.ErrDetail{
-				Type:    "plugin_install",
-				Message: installErr.Error(),
-				Detail: map[string]any{
-					"reason_code": internalplatform.ReasonInstallFailed,
-				},
-			},
-			Err: installErr,
-		}
-	}
-	installFatalGuard(rootCmd, makeErr)
-}
-
-// installPluginConflictGuard surfaces a Plugin.Restrict() configuration
-// error (single plugin invalid Rule or multiple plugins each contributing
-// Restrict). The design separates the envelope type:
-//
-//   - "plugin_install" with reason_code "invalid_rule"           - single bad rule
-//   - "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"
-		reasonCode := internalplatform.ReasonInvalidRule
-		if errors.Is(err, cmdpolicy.ErrMultipleRestricts) {
-			envelopeType = "plugin_conflict"
-			reasonCode = internalplatform.ReasonMultipleRestricts
-		}
-		return &output.ExitError{
-			Code: output.ExitValidation,
-			Detail: &output.ErrDetail{
-				Type:    envelopeType,
-				Message: err.Error(),
-				Detail: map[string]any{
-					"reason_code": reasonCode,
-				},
-			},
-			Err: err,
-		}
-	}
-	installFatalGuard(rootCmd, makeErr)
-}
-
-// installPluginLifecycleErrorGuard surfaces a Startup lifecycle handler
-// 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"
-		detail := map[string]any{
-			"reason_code": reasonCode,
-		}
-		var le *hook.LifecycleError
-		if errors.As(err, &le) {
-			if le.Panic {
-				reasonCode = "lifecycle_panic"
-			}
-			detail = map[string]any{
-				"reason_code": reasonCode,
-				"hook_name":   le.HookName,
-				"event":       "startup",
-			}
-		}
-		return &output.ExitError{
-			Code: output.ExitValidation,
-			Detail: &output.ErrDetail{
-				Type:    "plugin_lifecycle",
-				Message: err.Error(),
-				Detail:  detail,
-			},
-			Err: err,
-		}
-	}
-	installFatalGuard(rootCmd, makeErr)
-}
-
-// walkGuard recurses through cmd's subtree and installs the guard at
-// EVERY level cobra might dispatch to. The cobra execution order is:
-//
-//  1. PersistentPreRunE (looked up from leaf, walking up; "first wins")
-//  2. PreRunE
-//  3. RunE
-//  4. PostRunE
-//  5. PersistentPostRunE
-//
-// A subcommand that declares its own PersistentPreRunE (cmd/auth and
-// cmd/config both do) would not only shadow root's PersistentPreRunE
-// -- if that PreRunE itself returns an error (e.g. auth's
-// external_provider check), the user sees THAT error instead of
-// our plugin_install envelope, even if RunE was guarded.
-//
-// To close every dispatch hole we replace:
-//   - every command's PersistentPreRunE (including non-runnable groups)
-//   - every runnable command's PreRunE and RunE
-//
-// 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
-	}
-	// PersistentPreRunE is the first step cobra runs (after Args /
-	// flag validation -- see below). Set it on every command (root
-	// included) so cobra's "first wins" walk-up always finds OUR
-	// PersistentPreRunE before hitting any subcommand's pre-existing
-	// one.
-	cmd.PersistentPreRunE = func(c *cobra.Command, args []string) error {
-		c.SilenceUsage = true
-		return makeErr()
-	}
-	cmd.PersistentPreRun = nil
-
-	// **Cobra dispatch order before PersistentPreRunE:**
-	//   1. ValidateArgs(cmd.Args)            -- can return arg error
-	//   2. ParsePersistentFlags / ParseFlags -- can return flag error
-	//   3. Find legacyArgs check for unknown-command at root
-	//   4. PersistentPreRunE / PreRunE / RunE
-	//   5. Non-runnable groups fall through to help (PreRunE skipped)
-	//
-	// We neutralise each step:
-	//   - Args = ArbitraryArgs     -> ValidateArgs no-op. **Not nil**:
-	//                                 cobra falls back to legacyArgs
-	//                                 when Args==nil, which returns an
-	//                                 unknown-command error during Find
-	//                                 BEFORE PersistentPreRunE runs.
-	//                                 ArbitraryArgs explicitly accepts
-	//                                 everything, suppressing that path.
-	//   - DisableFlagParsing       -> ParseFlags skipped (and legacy
-	//                                 "unknown flag" suppressed)
-	//   - PreRunE / RunE on EVERY  -> Even non-runnable groups now run
-	//     command (not just leaves)   the guard instead of showing help
-	//
-	// Setting RunE on a parent group flips Runnable() to true, so
-	// cobra dispatches to it (and our guard fires) rather than calling
-	// the help command on a "help-only" group.
-	cmd.Args = cobra.ArbitraryArgs
-	cmd.DisableFlagParsing = true
-	cmd.PreRunE = func(c *cobra.Command, args []string) error {
-		c.SilenceUsage = true
-		return makeErr()
-	}
-	cmd.PreRun = nil
-	cmd.RunE = func(*cobra.Command, []string) error { return makeErr() }
-	cmd.Run = nil
-	for _, c := range cmd.Commands() {
-		walkGuard(c, makeErr)
-	}
-}
--- a/cmd/platform_guards_test.go
+++ b/cmd/platform_guards_test.go
@@ -1,208 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd
-
-import (
-	"context"
-	"errors"
-	"sync"
-	"testing"
-	"time"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/extension/platform"
-	"github.com/larksuite/cli/internal/hook"
-	"github.com/larksuite/cli/internal/output"
-	internalplatform "github.com/larksuite/cli/internal/platform"
-)
-
-// failClosedAbortingPlugin returns a PluginInstallError on Install,
-// declaring FailClosed so InstallAll surfaces the error.
-type failClosedAbortingPlugin struct{}
-
-func (failClosedAbortingPlugin) Name() string    { return "policy" }
-func (failClosedAbortingPlugin) Version() string { return "1.0.0" }
-func (failClosedAbortingPlugin) Capabilities() platform.Capabilities {
-	return platform.Capabilities{FailurePolicy: platform.FailClosed}
-}
-func (failClosedAbortingPlugin) Install(platform.Registrar) error {
-	return errors.New("upstream policy server unreachable")
-}
-
-// When a FailClosed plugin fails to install, buildInternal must
-// install a PersistentPreRunE that returns a structured *output.ExitError.
-// The user must NEVER see a silent partial-install state.
-//
-// This pins the build.go fix for codex's NEW ISSUE about
-// build.go demoting FailClosed errors to warnings.
-func TestBuildInternal_failClosedAbortsCLI(t *testing.T) {
-	platform.ResetForTesting()
-	t.Cleanup(platform.ResetForTesting)
-	platform.Register(failClosedAbortingPlugin{})
-
-	root := Build(context.Background(), buildInvocationForTest(t))
-
-	if root.PersistentPreRunE == nil {
-		t.Fatalf("FailClosed install error must wire a PersistentPreRunE that aborts subsequent commands")
-	}
-
-	err := root.PersistentPreRunE(root, nil)
-	checkGuardError(t, err)
-
-	// CRITICAL: subcommands that declare their own PersistentPreRunE
-	// (cmd/auth/auth.go and cmd/config/config.go both do) would
-	// shadow root's via cobra's "first wins" semantics if we only set
-	// root.PersistentPreRunE. Moreover, those subcommand PersistentPreRunE
-	// handlers may themselves return an error (e.g. auth's
-	// external_provider check at internal/cmdutil/factory.go:223),
-	// which would mask the plugin_install envelope even if RunE were
-	// guarded.
-	//
-	// The guard MUST therefore walk the tree and replace each command's
-	// PersistentPreRunE / PreRunE / RunE directly. This test pins
-	// that the bypass is closed.
-	auth := findChildByUse(t, root, "auth")
-	if auth == nil {
-		t.Skip("auth subcommand not present in build; cannot exercise bypass case")
-	}
-	// (a) auth's own PersistentPreRunE must be the guard, not the
-	// factory-checking handler that lived there before walkGuard ran.
-	if auth.PersistentPreRunE == nil {
-		t.Fatalf("auth.PersistentPreRunE must be guarded after walkGuard")
-	}
-	checkGuardError(t, auth.PersistentPreRunE(auth, nil))
-
-	// (b) A runnable leaf below auth also gets the guard on RunE. We
-	// match by RunE != nil (not just Runnable()) because the guard
-	// replaces RunE specifically — selecting a Run-only command and
-	// then calling leaf.RunE would nil-deref.
-	var leaf *cobra.Command
-	walk(auth, func(c *cobra.Command) {
-		if leaf != nil {
-			return
-		}
-		if c != auth && c.RunE != nil {
-			leaf = c
-		}
-	})
-	if leaf == nil {
-		t.Skip("no auth subcommand with RunE found")
-	}
-	checkGuardError(t, leaf.RunE(leaf, nil))
-}
-
-// checkGuardError asserts that err is the structured plugin_install
-// ExitError the guard produces.
-func checkGuardError(t *testing.T, err error) {
-	t.Helper()
-	if err == nil {
-		t.Fatalf("PersistentPreRunE must surface the install error, got nil")
-	}
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
-		t.Fatalf("expected *output.ExitError, got %T %+v", err, err)
-	}
-	if exitErr.Detail.Type != "plugin_install" {
-		t.Errorf("envelope type = %q, want plugin_install", exitErr.Detail.Type)
-	}
-	detail := exitErr.Detail.Detail.(map[string]any)
-	if detail["plugin"] != "policy" {
-		t.Errorf("detail.plugin = %v, want policy", detail["plugin"])
-	}
-	if detail["reason_code"] != internalplatform.ReasonInstallFailed {
-		t.Errorf("detail.reason_code = %v, want install_failed", detail["reason_code"])
-	}
-}
-
-// findChildByUse helper.
-func findChildByUse(t *testing.T, parent *cobra.Command, use string) *cobra.Command {
-	t.Helper()
-	for _, c := range parent.Commands() {
-		if c.Use == use {
-			return c
-		}
-	}
-	return nil
-}
-
-// namespacedWrap copy semantics: a plugin reusing a sentinel AbortError
-// across two concurrent command invocations must produce two distinct
-// HookName values on the wire. Mutation would interleave them.
-//
-// We exercise this by sharing one AbortError across two goroutines,
-// each invoking through a different namespacedWrap; both observed
-// errors must keep their own HookName.
-func TestNamespacedWrap_doesNotMutateSharedAbortError(t *testing.T) {
-	shared := &platform.AbortError{HookName: "plugin-shared-name", Reason: "rejected"}
-
-	makeWrapper := func(name string) platform.Wrapper {
-		return func(next platform.Handler) platform.Handler {
-			return func(context.Context, platform.Invocation) error { return shared }
-		}
-	}
-
-	reg := hook.NewRegistry()
-	reg.AddWrapper(hook.WrapperEntry{
-		Name: "p1.wrap", Selector: platform.All(), Fn: makeWrapper("p1.wrap"),
-	})
-	reg.AddWrapper(hook.WrapperEntry{
-		Name: "p2.wrap", Selector: platform.All(), Fn: makeWrapper("p2.wrap"),
-	})
-
-	// Drive matched wrappers separately to exercise both namespace paths.
-	matched := reg.MatchingWrappers(stubView{})
-	if len(matched) != 2 {
-		t.Fatalf("expected 2 matched wrappers, got %d", len(matched))
-	}
-
-	results := make([]string, 2)
-	var wg sync.WaitGroup
-	wg.Add(2)
-	for i, m := range matched {
-		go func() {
-			defer wg.Done()
-			err := m.Fn(func(context.Context, platform.Invocation) error { return nil })(
-				context.Background(), stubInvocation{})
-			if ab, ok := err.(*platform.AbortError); ok {
-				results[i] = ab.HookName
-			}
-		}()
-	}
-	wg.Wait()
-
-	// We are not using namespacedWrap directly here -- the test isolates
-	// the semantic by reading what each WrapperEntry's Fn returns.
-	// The real guarantee we depend on is the install-side namespacedWrap;
-	// see internal/hook/install.go for the production path. This test
-	// pins the sentinel-not-mutated invariant at the unit level: each
-	// Wrap returned the shared AbortError unchanged, so the production
-	// namespacedWrap can safely copy without touching the original.
-	if shared.HookName != "plugin-shared-name" {
-		t.Errorf("shared sentinel AbortError was mutated: HookName = %q", shared.HookName)
-	}
-	_ = results
-}
-
-// stubView for the wrap selector match.
-type stubView struct{}
-
-func (stubView) Path() string                     { return "x" }
-func (stubView) Domain() string                   { return "" }
-func (stubView) Risk() (platform.Risk, bool)      { return "", false }
-func (stubView) Identities() []platform.Identity  { return nil }
-func (stubView) Annotation(string) (string, bool) { return "", false }
-
-// stubInvocation is the minimal platform.Invocation implementation
-// used by tests that need to drive a Wrap without going through the
-// full hook.Install pipeline.
-type stubInvocation struct{}
-
-func (stubInvocation) Cmd() platform.CommandView  { return stubView{} }
-func (stubInvocation) Args() []string             { return nil }
-func (stubInvocation) Started() time.Time         { return time.Time{} }
-func (stubInvocation) Err() error                 { return nil }
-func (stubInvocation) DeniedByPolicy() bool       { return false }
-func (stubInvocation) DenialLayer() string        { return "" }
-func (stubInvocation) DenialPolicySource() string { return "" }
--- a/cmd/plugin_integration_test.go
+++ b/cmd/plugin_integration_test.go
@@ -1,684 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd
-
-import (
-	"context"
-	"errors"
-	"os"
-	"path/filepath"
-	"sync/atomic"
-	"testing"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/extension/platform"
-	"github.com/larksuite/cli/internal/cmdpolicy"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/hook"
-	"github.com/larksuite/cli/internal/output"
-	internalplatform "github.com/larksuite/cli/internal/platform"
-)
-
-// These integration tests exercise the Hook framework's plumbing
-// (Plugin -> InstallAll -> Registry -> wireHooks -> RunE wrapper)
-// against a SYNTHETIC command tree, not the real lark-cli shortcut
-// tree. The synthetic tree keeps the test hermetic -- invoking real
-// shortcuts requires a fully-populated Factory (HTTP, credentials,
-// etc.) which is out of scope for a hook plumbing test.
-//
-// The e2e tests that go through Build() are kept thin (see
-// TestBuildInternal_appliesPolicyToRealTree in policy_test.go); they
-// assert plumbing existence (Hidden flag, etc.) without invoking
-// shortcuts.
-
-type fakeIntegrationPlugin struct {
-	name            string
-	caps            platform.Capabilities
-	rule            *platform.Rule
-	beforeCount     int64
-	afterCount      int64
-	wrapCount       int64
-	wrapDeniesWrite bool // when true, Wrap returns AbortError for risk=write
-	shutdownCalled  int64
-}
-
-func (p *fakeIntegrationPlugin) Name() string                        { return p.name }
-func (p *fakeIntegrationPlugin) Version() string                     { return "0.0.1" }
-func (p *fakeIntegrationPlugin) Capabilities() platform.Capabilities { return p.caps }
-
-func (p *fakeIntegrationPlugin) Install(r platform.Registrar) error {
-	if p.caps.Restricts && p.rule != nil {
-		r.Restrict(p.rule)
-	}
-	r.Observe(platform.Before, "audit-pre", platform.All(),
-		func(context.Context, platform.Invocation) {
-			atomic.AddInt64(&p.beforeCount, 1)
-		})
-	r.Observe(platform.After, "audit-post", platform.All(),
-		func(context.Context, platform.Invocation) {
-			atomic.AddInt64(&p.afterCount, 1)
-		})
-	r.Wrap("policy", platform.ByWrite(),
-		func(next platform.Handler) platform.Handler {
-			return func(ctx context.Context, inv platform.Invocation) error {
-				atomic.AddInt64(&p.wrapCount, 1)
-				if p.wrapDeniesWrite {
-					return &platform.AbortError{
-						HookName: "policy",
-						Reason:   "writes blocked by integration test plugin",
-					}
-				}
-				return next(ctx, inv)
-			}
-		})
-	r.On(platform.Shutdown, "flush",
-		func(context.Context, *platform.LifecycleContext) error {
-			atomic.AddInt64(&p.shutdownCalled, 1)
-			return nil
-		})
-	return nil
-}
-
-// syntheticTree builds a small command tree we own end-to-end. The leaf
-// has risk=write so the Wrap's ByWrite() selector matches.
-func syntheticTree() (*cobra.Command, *cobra.Command) {
-	root := &cobra.Command{Use: "lark-cli"}
-	group := &cobra.Command{Use: "docs"}
-	root.AddCommand(group)
-	leaf := &cobra.Command{
-		Use:  "+write",
-		RunE: func(*cobra.Command, []string) error { return nil },
-	}
-	cmdutil.SetRisk(leaf, "write")
-	group.AddCommand(leaf)
-	return root, leaf
-}
-
-// End-to-end through the public install pipeline: register a plugin,
-// run internalplatform.InstallAll (the same function buildInternal calls),
-// wire hooks onto a synthetic tree, invoke the leaf, and confirm
-// observers fired.
-func TestPluginPipeline_observersWired(t *testing.T) {
-	platform.ResetForTesting()
-	t.Cleanup(platform.ResetForTesting)
-	plugin := &fakeIntegrationPlugin{
-		name: "audit-plugin",
-		caps: platform.Capabilities{FailurePolicy: platform.FailOpen},
-	}
-	platform.Register(plugin)
-
-	result, err := internalplatform.InstallAll(platform.RegisteredPlugins(), nil)
-	if err != nil {
-		t.Fatalf("InstallAll: %v", err)
-	}
-
-	root, leaf := syntheticTree()
-	if err := wireHooks(context.Background(), root, result.Registry); err != nil {
-		t.Fatalf("wireHooks: %v", err)
-	}
-
-	_ = leaf.RunE(leaf, nil)
-
-	if got := atomic.LoadInt64(&plugin.beforeCount); got != 1 {
-		t.Errorf("Before observer fired %d times, want 1", got)
-	}
-	if got := atomic.LoadInt64(&plugin.afterCount); got != 1 {
-		t.Errorf("After observer fired %d times, want 1", got)
-	}
-	if got := atomic.LoadInt64(&plugin.wrapCount); got != 1 {
-		t.Errorf("Wrap fired %d times (ByWrite matches risk=write), want 1", got)
-	}
-}
-
-// A Wrapper returning AbortError on a write command must surface as
-// type="hook" in the envelope so the caller can parse the structured
-// rejection.
-func TestPluginPipeline_wrapAbortReachesEnvelope(t *testing.T) {
-	platform.ResetForTesting()
-	t.Cleanup(platform.ResetForTesting)
-	plugin := &fakeIntegrationPlugin{
-		name:            "policy-plugin",
-		caps:            platform.Capabilities{FailurePolicy: platform.FailOpen},
-		wrapDeniesWrite: true,
-	}
-	platform.Register(plugin)
-
-	result, err := internalplatform.InstallAll(platform.RegisteredPlugins(), nil)
-	if err != nil {
-		t.Fatalf("InstallAll: %v", err)
-	}
-
-	root, leaf := syntheticTree()
-	if err := wireHooks(context.Background(), root, result.Registry); err != nil {
-		t.Fatalf("wireHooks: %v", err)
-	}
-
-	err = leaf.RunE(leaf, nil)
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
-		t.Fatalf("expected *output.ExitError, got %T %+v", err, err)
-	}
-	if exitErr.Detail.Type != "hook" {
-		t.Errorf("envelope type = %q, want hook", exitErr.Detail.Type)
-	}
-	detail := exitErr.Detail.Detail.(map[string]any)
-	if detail["reason_code"] != "aborted" {
-		t.Errorf("detail.reason_code = %v, want aborted", detail["reason_code"])
-	}
-	if detail["hook_name"] != "policy-plugin.policy" {
-		t.Errorf("detail.hook_name = %v, want policy-plugin.policy", detail["hook_name"])
-	}
-
-	// errors.As must still reach the original AbortError so consumers
-	// can inspect the typed cause.
-	var ab *platform.AbortError
-	if !errors.As(err, &ab) {
-		t.Errorf("error chain should expose *platform.AbortError")
-	}
-}
-
-// Plugin.Restrict() contribution must reach the pruning resolver and
-// take precedence over a yaml file (single-rule, plugin wins). This
-// goes through the REAL Build() pipeline so the wiring between
-// installPluginsAndHooks -> applyUserPolicyPruning -> cmdpolicy.Resolve
-// is covered.
-func TestPluginPipeline_restrictBeatsYaml(t *testing.T) {
-	cfgDir := tmpHome(t)
-	// yaml says allow everything; plugin says deny everything. Plugin
-	// should win and a command should be denied.
-	if err := os.WriteFile(filepath.Join(cfgDir, "policy.yml"),
-		[]byte("name: yaml-allow\nallow: [\"**\"]\n"), 0o644); err != nil {
-		t.Fatalf("write yaml: %v", err)
-	}
-
-	platform.ResetForTesting()
-	t.Cleanup(platform.ResetForTesting)
-	plugin := &fakeIntegrationPlugin{
-		name: "restricter",
-		caps: platform.Capabilities{
-			Restricts:     true,
-			FailurePolicy: platform.FailClosed,
-		},
-		rule: &platform.Rule{Name: "deny-all", Deny: []string{"**"}},
-	}
-	platform.Register(plugin)
-
-	root := Build(context.Background(), buildInvocationForTest(t))
-
-	// At least one runnable command must end up Hidden because of the
-	// plugin Restrict (yaml had been allow-all and would have left
-	// everything visible).
-	var foundHidden bool
-	walk(root, func(c *cobra.Command) {
-		if c.HasParent() && c.Runnable() && c.Hidden {
-			foundHidden = true
-		}
-	})
-	if !foundHidden {
-		t.Fatalf("plugin Restrict should have denied at least one command despite yaml allow-all")
-	}
-}
-
-// Denial-guard end-to-end: register a plugin with a Wrap that would
-// SILENTLY suppress denial (return nil without calling next). After
-// installing pruning (which marks a command as denied) and wiring
-// hooks, calling the denied command must STILL produce the denial
-// error -- the Wrap must never run on the denied path.
-func TestPluginPipeline_denialGuardIntegrated(t *testing.T) {
-	platform.ResetForTesting()
-	t.Cleanup(platform.ResetForTesting)
-
-	wrapCalled := false
-	plugin := &fakeIntegrationPlugin{
-		name:            "policy-plugin",
-		caps:            platform.Capabilities{FailurePolicy: platform.FailOpen},
-		wrapDeniesWrite: false, // wrap would normally allow
-	}
-	// Override Wrap with a malicious behavior: return nil (silence the
-	// denial). We do this by wrapping the install: register a
-	// second Wrap that suppresses errors.
-	platform.Register(plugin)
-
-	// Add another plugin with a malicious wrap.
-	malicious := &mockMaliciousPlugin{
-		name:        "malicious",
-		invokedFlag: &wrapCalled,
-	}
-	platform.Register(malicious)
-
-	result, err := internalplatform.InstallAll(platform.RegisteredPlugins(), nil)
-	if err != nil {
-		t.Fatalf("InstallAll: %v", err)
-	}
-
-	root, leaf := syntheticTree()
-	// Simulate cmdpolicy.Apply marking leaf as denied.
-	leaf.Hidden = true
-	leaf.DisableFlagParsing = true
-	if leaf.Annotations == nil {
-		leaf.Annotations = map[string]string{}
-	}
-	leaf.Annotations["lark:policy_denied_layer"] = "policy"
-	leaf.Annotations["lark:policy_denied_source"] = "plugin:other"
-	denyStubCalled := false
-	leaf.RunE = func(*cobra.Command, []string) error {
-		denyStubCalled = true
-		return errors.New("CommandPruned (denyStub)")
-	}
-
-	if err := wireHooks(context.Background(), root, result.Registry); err != nil {
-		t.Fatalf("wireHooks: %v", err)
-	}
-
-	err = leaf.RunE(leaf, nil)
-	if wrapCalled {
-		t.Errorf("denial guard violated: malicious Wrap ran on a denied command")
-	}
-	if !denyStubCalled {
-		t.Errorf("denyStub should run on the denial path even when a Wrap is registered")
-	}
-	if err == nil {
-		t.Errorf("denial error must propagate, got nil")
-	}
-}
-
-// mockMaliciousPlugin registers a Wrap that returns nil unconditionally
-// -- exactly the kind of plugin the denial guard defends against.
-type mockMaliciousPlugin struct {
-	name        string
-	invokedFlag *bool
-}
-
-func (p *mockMaliciousPlugin) Name() string    { return p.name }
-func (p *mockMaliciousPlugin) Version() string { return "0.0.1" }
-func (p *mockMaliciousPlugin) Capabilities() platform.Capabilities {
-	return platform.Capabilities{FailurePolicy: platform.FailOpen}
-}
-func (p *mockMaliciousPlugin) Install(r platform.Registrar) error {
-	r.Wrap("hijack", platform.All(),
-		func(_ platform.Handler) platform.Handler {
-			return func(context.Context, platform.Invocation) error {
-				if p.invokedFlag != nil {
-					*p.invokedFlag = true
-				}
-				return nil // silence everything
-			}
-		})
-	return nil
-}
-
-// Verifies buildInternal returns a non-nil *hook.Registry when a plugin
-// is registered and Emit(Shutdown) on that registry fires the plugin's
-// On(Shutdown) handler. This is the contract Execute relies on to fire
-// Shutdown after rootCmd.Execute returns.
-func TestBuildInternal_returnsRegistryForShutdownEmit(t *testing.T) {
-	tmpHome(t)
-
-	platform.ResetForTesting()
-	t.Cleanup(platform.ResetForTesting)
-	plugin := &fakeIntegrationPlugin{
-		name: "shutdown-test",
-		caps: platform.Capabilities{FailurePolicy: platform.FailOpen},
-	}
-	platform.Register(plugin)
-
-	_, _, reg := buildInternal(context.Background(), buildInvocationForTest(t))
-	if reg == nil {
-		t.Fatalf("buildInternal returned nil registry; plugin's Shutdown handler is unreachable")
-	}
-
-	if err := hook.Emit(context.Background(), reg, platform.Shutdown, nil); err != nil {
-		t.Fatalf("Emit(Shutdown): %v", err)
-	}
-	if got := atomic.LoadInt64(&plugin.shutdownCalled); got != 1 {
-		t.Errorf("On(Shutdown) handler fired %d times, want 1", got)
-	}
-}
-
-// When plugin install fails (FailClosed), buildInternal returns nil
-// registry. Execute must nil-check before calling Emit so we don't fault
-// on the FailClosed bypass-guard path.
-func TestBuildInternal_failClosedYieldsNilRegistry(t *testing.T) {
-	tmpHome(t)
-
-	platform.ResetForTesting()
-	t.Cleanup(platform.ResetForTesting)
-	// A plugin that fails install and is FailClosed -> InstallAll
-	// returns an error, buildInternal installs the guard and returns
-	// early with nil registry.
-	plugin := &failingPlugin{
-		name: "fail-closed",
-		caps: platform.Capabilities{FailurePolicy: platform.FailClosed},
-		err:  errors.New("install failure simulated"),
-	}
-	platform.Register(plugin)
-
-	_, _, reg := buildInternal(context.Background(), buildInvocationForTest(t))
-	if reg != nil {
-		t.Errorf("buildInternal returned non-nil registry on FailClosed install error")
-	}
-}
-
-type failingPlugin struct {
-	name string
-	caps platform.Capabilities
-	err  error
-}
-
-func (p *failingPlugin) Name() string                        { return p.name }
-func (p *failingPlugin) Version() string                     { return "0.0.1" }
-func (p *failingPlugin) Capabilities() platform.Capabilities { return p.caps }
-func (p *failingPlugin) Install(platform.Registrar) error    { return p.err }
-
-// === Plugin Restrict conflict guard ===
-//
-// Two plugins both calling r.Restrict must surface as a structured
-// plugin_conflict envelope (reason_code multiple_restrict_plugins) at
-// dispatch time, NOT as a silent stderr warning. Otherwise a
-// safety-sensitive operator could miss that their policy never took
-// effect.
-func TestPluginConflictGuard_MultipleRestrictAbortsCLI(t *testing.T) {
-	tmpHome(t)
-	platform.ResetForTesting()
-	t.Cleanup(platform.ResetForTesting)
-	cmdpolicy.ResetActiveForTesting()
-	t.Cleanup(cmdpolicy.ResetActiveForTesting)
-
-	rule := &platform.Rule{Name: "any", Allow: []string{"**"}}
-	platform.Register(&fakeIntegrationPlugin{
-		name: "plugin-a",
-		caps: platform.Capabilities{Restricts: true, FailurePolicy: platform.FailClosed},
-		rule: rule,
-	})
-	platform.Register(&fakeIntegrationPlugin{
-		name: "plugin-b",
-		caps: platform.Capabilities{Restricts: true, FailurePolicy: platform.FailClosed},
-		rule: rule,
-	})
-
-	_, root, reg := buildInternal(context.Background(), buildInvocationForTest(t))
-	if reg != nil {
-		t.Errorf("conflict guard path should yield nil registry")
-	}
-
-	// Pick any leaf and verify it returns the structured envelope.
-	leaf := findRunnableLeaf(root)
-	if leaf == nil {
-		t.Fatalf("no runnable leaf in command tree")
-	}
-	err := leaf.RunE(leaf, nil)
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
-		t.Fatalf("expected *output.ExitError, got %T %+v", err, err)
-	}
-	if exitErr.Detail.Type != "plugin_conflict" {
-		t.Errorf("envelope type = %q, want plugin_conflict", exitErr.Detail.Type)
-	}
-	if rc := exitErr.Detail.Detail.(map[string]any)["reason_code"]; rc != "multiple_restrict_plugins" {
-		t.Errorf("reason_code = %v, want multiple_restrict_plugins", rc)
-	}
-}
-
-// Single plugin with an invalid Rule must surface as plugin_install /
-// invalid_rule envelope (distinct error.type from multi-Restrict).
-func TestPluginConflictGuard_InvalidRuleAbortsCLI(t *testing.T) {
-	tmpHome(t)
-	platform.ResetForTesting()
-	t.Cleanup(platform.ResetForTesting)
-	cmdpolicy.ResetActiveForTesting()
-	t.Cleanup(cmdpolicy.ResetActiveForTesting)
-
-	// MaxRisk "nukem" is rejected by ValidateRule -> Resolve returns
-	// an error that is NOT ErrMultipleRestricts.
-	platform.Register(&fakeIntegrationPlugin{
-		name: "bad",
-		caps: platform.Capabilities{Restricts: true, FailurePolicy: platform.FailClosed},
-		rule: &platform.Rule{Name: "bad", MaxRisk: "nukem"},
-	})
-
-	_, root, reg := buildInternal(context.Background(), buildInvocationForTest(t))
-	if reg != nil {
-		t.Errorf("conflict guard path should yield nil registry")
-	}
-	leaf := findRunnableLeaf(root)
-	if leaf == nil {
-		t.Fatalf("no runnable leaf in command tree")
-	}
-	err := leaf.RunE(leaf, nil)
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
-		t.Fatalf("expected *output.ExitError, got %T %+v", err, err)
-	}
-	if exitErr.Detail.Type != "plugin_install" {
-		t.Errorf("envelope type = %q, want plugin_install", exitErr.Detail.Type)
-	}
-	if rc := exitErr.Detail.Detail.(map[string]any)["reason_code"]; rc != "invalid_rule" {
-		t.Errorf("reason_code = %v, want invalid_rule", rc)
-	}
-}
-
-// === Startup lifecycle guard ===
-//
-// Plugin On(Startup) handler returning error must abort startup with
-// a plugin_lifecycle envelope (reason_code lifecycle_failed). Silently
-// continuing would leave the plugin's invariants violated while the
-// rest of its hooks still fire.
-func TestPluginLifecycleGuard_StartupErrorAbortsCLI(t *testing.T) {
-	tmpHome(t)
-	platform.ResetForTesting()
-	t.Cleanup(platform.ResetForTesting)
-	cmdpolicy.ResetActiveForTesting()
-	t.Cleanup(cmdpolicy.ResetActiveForTesting)
-
-	platform.Register(&startupFailingPlugin{
-		name:    "lc",
-		failErr: errors.New("backend unreachable"),
-	})
-
-	_, root, reg := buildInternal(context.Background(), buildInvocationForTest(t))
-	if reg != nil {
-		t.Errorf("lifecycle guard path should yield nil registry")
-	}
-
-	leaf := findRunnableLeaf(root)
-	err := leaf.RunE(leaf, nil)
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
-		t.Fatalf("expected *output.ExitError, got %T %+v", err, err)
-	}
-	if exitErr.Detail.Type != "plugin_lifecycle" {
-		t.Errorf("envelope type = %q, want plugin_lifecycle", exitErr.Detail.Type)
-	}
-	d := exitErr.Detail.Detail.(map[string]any)
-	if d["reason_code"] != "lifecycle_failed" {
-		t.Errorf("reason_code = %v, want lifecycle_failed", d["reason_code"])
-	}
-	if d["hook_name"] != "lc.start" {
-		t.Errorf("hook_name = %v, want lc.start", d["hook_name"])
-	}
-}
-
-// Same path but the handler panics -> reason_code lifecycle_panic.
-func TestPluginLifecycleGuard_StartupPanicAbortsCLI(t *testing.T) {
-	tmpHome(t)
-	platform.ResetForTesting()
-	t.Cleanup(platform.ResetForTesting)
-	cmdpolicy.ResetActiveForTesting()
-	t.Cleanup(cmdpolicy.ResetActiveForTesting)
-
-	platform.Register(&startupFailingPlugin{
-		name:     "lc",
-		doPanic:  true,
-		panicMsg: "kaboom",
-	})
-
-	_, root, reg := buildInternal(context.Background(), buildInvocationForTest(t))
-	if reg != nil {
-		t.Errorf("lifecycle guard path should yield nil registry")
-	}
-	leaf := findRunnableLeaf(root)
-	err := leaf.RunE(leaf, nil)
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T", err)
-	}
-	if rc := exitErr.Detail.Detail.(map[string]any)["reason_code"]; rc != "lifecycle_panic" {
-		t.Errorf("reason_code = %v, want lifecycle_panic", rc)
-	}
-}
-
-type startupFailingPlugin struct {
-	name     string
-	failErr  error // when set, handler returns this
-	doPanic  bool  // when true, handler panics with panicMsg
-	panicMsg string
-}
-
-func (p *startupFailingPlugin) Name() string    { return p.name }
-func (p *startupFailingPlugin) Version() string { return "0.0.1" }
-func (p *startupFailingPlugin) Capabilities() platform.Capabilities {
-	return platform.Capabilities{FailurePolicy: platform.FailClosed}
-}
-func (p *startupFailingPlugin) Install(r platform.Registrar) error {
-	r.On(platform.Startup, "start", func(context.Context, *platform.LifecycleContext) error {
-		if p.doPanic {
-			panic(p.panicMsg)
-		}
-		return p.failErr
-	})
-	return nil
-}
-
-// === Wrapper panic recovery ===
-//
-// A Wrapper that panics must NOT crash the process. The framework
-// recovers and converts to a structured envelope:
-//
-//	type="hook", reason_code="panic", hook_name=<namespaced>
-func TestWrapperPanic_BecomesHookPanicEnvelope(t *testing.T) {
-	platform.ResetForTesting()
-	t.Cleanup(platform.ResetForTesting)
-
-	platform.Register(&panickingWrapPlugin{name: "p"})
-
-	result, err := internalplatform.InstallAll(platform.RegisteredPlugins(), nil)
-	if err != nil {
-		t.Fatalf("InstallAll: %v", err)
-	}
-	root, leaf := syntheticTree()
-	if err := wireHooks(context.Background(), root, result.Registry); err != nil {
-		t.Fatalf("wireHooks: %v", err)
-	}
-
-	defer func() {
-		if r := recover(); r != nil {
-			t.Fatalf("Wrapper panic must be recovered, but it escaped: %v", r)
-		}
-	}()
-
-	err = leaf.RunE(leaf, nil)
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
-		t.Fatalf("expected *output.ExitError, got %T %+v", err, err)
-	}
-	if exitErr.Detail.Type != "hook" {
-		t.Errorf("envelope type = %q, want hook", exitErr.Detail.Type)
-	}
-	d := exitErr.Detail.Detail.(map[string]any)
-	if d["reason_code"] != "panic" {
-		t.Errorf("reason_code = %v, want panic", d["reason_code"])
-	}
-	if d["hook_name"] != "p.boom" {
-		t.Errorf("hook_name = %v, want p.boom (namespaced)", d["hook_name"])
-	}
-}
-
-type panickingWrapPlugin struct{ name string }
-
-func (p *panickingWrapPlugin) Name() string                        { return p.name }
-func (p *panickingWrapPlugin) Version() string                     { return "0.0.1" }
-func (p *panickingWrapPlugin) Capabilities() platform.Capabilities { return platform.Capabilities{} }
-func (p *panickingWrapPlugin) Install(r platform.Registrar) error {
-	r.Wrap("boom", platform.All(),
-		func(_ platform.Handler) platform.Handler {
-			return func(context.Context, platform.Invocation) error {
-				panic("intentional panic for test")
-			}
-		})
-	return nil
-}
-
-// findRunnableLeaf walks the tree and returns the first command with a
-// RunE so tests can synthesize a dispatch without going through cobra.
-func findRunnableLeaf(c *cobra.Command) *cobra.Command {
-	if c.RunE != nil && c.HasParent() {
-		return c
-	}
-	for _, child := range c.Commands() {
-		if l := findRunnableLeaf(child); l != nil {
-			return l
-		}
-	}
-	return nil
-}
-
-// B2 regression: a plugin Wrapper whose FACTORY function (the
-// `func(next Handler) Handler` itself) panics must not crash the
-// process. The framework recovers and returns the same panic envelope
-// it produces for runtime panics inside the inner Handler.
-//
-// Pre-fix code path: recoverWrap had `inner := w(next)` outside the
-// deferred recover, so a factory panic escaped.
-func TestWrapperFactoryPanic_BecomesHookPanicEnvelope(t *testing.T) {
-	platform.ResetForTesting()
-	t.Cleanup(platform.ResetForTesting)
-
-	platform.Register(&factoryPanicWrapPlugin{name: "fac"})
-
-	result, err := internalplatform.InstallAll(platform.RegisteredPlugins(), nil)
-	if err != nil {
-		t.Fatalf("InstallAll: %v", err)
-	}
-	root, leaf := syntheticTree()
-	if err := wireHooks(context.Background(), root, result.Registry); err != nil {
-		t.Fatalf("wireHooks: %v", err)
-	}
-
-	defer func() {
-		if r := recover(); r != nil {
-			t.Fatalf("factory panic must be recovered, but it escaped: %v", r)
-		}
-	}()
-
-	err = leaf.RunE(leaf, nil)
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
-		t.Fatalf("expected *output.ExitError, got %T %+v", err, err)
-	}
-	if exitErr.Detail.Type != "hook" {
-		t.Errorf("envelope type = %q, want hook", exitErr.Detail.Type)
-	}
-	d := exitErr.Detail.Detail.(map[string]any)
-	if d["reason_code"] != "panic" {
-		t.Errorf("reason_code = %v, want panic", d["reason_code"])
-	}
-	if d["hook_name"] != "fac.bad-factory" {
-		t.Errorf("hook_name = %v, want fac.bad-factory (namespaced)", d["hook_name"])
-	}
-}
-
-type factoryPanicWrapPlugin struct{ name string }
-
-func (p *factoryPanicWrapPlugin) Name() string                        { return p.name }
-func (p *factoryPanicWrapPlugin) Version() string                     { return "0.0.1" }
-func (p *factoryPanicWrapPlugin) Capabilities() platform.Capabilities { return platform.Capabilities{} }
-func (p *factoryPanicWrapPlugin) Install(r platform.Registrar) error {
-	r.Wrap("bad-factory", platform.All(),
-		// The factory itself panics; the returned Handler is never reached.
-		func(_ platform.Handler) platform.Handler {
-			panic("factory blew up")
-		})
-	return nil
-}
--- a/cmd/profile/add.go
+++ b/cmd/profile/add.go
@@ -14,7 +14,6 @@ import (

 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/output"
 )

@@ -41,12 +40,11 @@ func NewCmdProfileAdd(f *cmdutil.Factory) *cobra.Command {
 	cmd.Flags().StringVar(&appID, "app-id", "", "App ID (required)")
 	cmd.Flags().BoolVar(&appSecretStdin, "app-secret-stdin", false, "read App Secret from stdin")
 	cmd.Flags().StringVar(&brand, "brand", "feishu", "feishu or lark")
-	cmd.Flags().StringVar(&lang, "lang", "", "language preference (e.g. zh or zh_cn)")
+	cmd.Flags().StringVar(&lang, "lang", "zh", "language for interactive prompts (zh or en)")
 	cmd.Flags().BoolVar(&use, "use", false, "switch to this profile after adding")

 	_ = cmd.MarkFlagRequired("name")
 	_ = cmd.MarkFlagRequired("app-id")
-	cmdutil.SetRisk(cmd, "write")

 	return cmd
 }
@@ -56,12 +54,6 @@ func profileAddRun(f *cmdutil.Factory, name, appID string, appSecretStdin bool,
 		return output.ErrValidation("%v", err)
 	}

-	langPref, err := cmdutil.ParseLangFlag(lang)
-	if err != nil {
-		return err
-	}
-	lang = string(langPref)
-
 	// Read secret from stdin
 	if !appSecretStdin {
 		return output.ErrValidation("app secret must be provided via stdin: use --app-secret-stdin and pipe the secret")
@@ -122,7 +114,7 @@ func profileAddRun(f *cmdutil.Factory, name, appID string, appSecretStdin bool,
 		AppId:     appID,
 		AppSecret: secret,
 		Brand:     parsedBrand,
-		Lang:      i18n.Lang(lang),
+		Lang:      lang,
 		Users:     []core.AppUser{},
 	})

--- a/cmd/profile/list.go
+++ b/cmd/profile/list.go
@@ -34,7 +34,6 @@ func NewCmdProfileList(f *cmdutil.Factory) *cobra.Command {
 			return profileListRun(f)
 		},
 	}
-	cmdutil.SetRisk(cmd, "read")
 	return cmd
 }

--- a/cmd/profile/profile_test.go
+++ b/cmd/profile/profile_test.go
@@ -13,7 +13,6 @@ import (

 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/vfs"
 )
@@ -52,56 +51,6 @@ func TestProfileAddRun_InvalidExistingConfigReturnsError(t *testing.T) {
 	}
 }

-// TestProfileAddRun_Lang covers the unified --lang contract on profile add:
-// short codes and Feishu locales both canonicalize to the same stored locale,
-// empty stores no preference, and an unrecognized value errors.
-func TestProfileAddRun_Lang(t *testing.T) {
-	t.Run("short and locale canonicalize and persist alike", func(t *testing.T) {
-		for _, in := range []string{"ja", "ja_jp"} {
-			setupProfileConfigDir(t)
-			f, _, _, _ := cmdutil.TestFactory(t, nil)
-			f.IOStreams.In = strings.NewReader("secret\n")
-			if err := profileAddRun(f, "p", "app-p", true, "feishu", in, false); err != nil {
-				t.Fatalf("--lang %q: profileAddRun() error = %v", in, err)
-			}
-			saved, err := core.LoadMultiAppConfig()
-			if err != nil {
-				t.Fatalf("LoadMultiAppConfig() error = %v", err)
-			}
-			if app := saved.FindApp("p"); app == nil || app.Lang != i18n.LangJaJP {
-				t.Errorf("--lang %q: stored Lang = %v, want %q", in, app, i18n.LangJaJP)
-			}
-		}
-	})
-
-	t.Run("empty stores no preference", func(t *testing.T) {
-		setupProfileConfigDir(t)
-		f, _, _, _ := cmdutil.TestFactory(t, nil)
-		f.IOStreams.In = strings.NewReader("secret\n")
-		if err := profileAddRun(f, "p", "app-p", true, "feishu", "", false); err != nil {
-			t.Fatalf("profileAddRun() error = %v", err)
-		}
-		saved, _ := core.LoadMultiAppConfig()
-		if app := saved.FindApp("p"); app == nil || app.Lang != "" {
-			t.Errorf("stored Lang = %v, want \"\" (unset)", app)
-		}
-	})
-
-	t.Run("invalid lang errors", func(t *testing.T) {
-		setupProfileConfigDir(t)
-		f, _, _, _ := cmdutil.TestFactory(t, nil)
-		f.IOStreams.In = strings.NewReader("secret\n")
-		err := profileAddRun(f, "p", "app-p", true, "feishu", "ZH", false)
-		if err == nil {
-			t.Fatal("expected validation error for --lang ZH, got nil")
-		}
-		exitErr, ok := err.(*output.ExitError)
-		if !ok || exitErr.Code != output.ExitValidation {
-			t.Fatalf("expected ExitValidation, got %T: %v", err, err)
-		}
-	})
-}
-
 func TestProfileAddRun_UseAfterUpdatesCurrentAndPrevious(t *testing.T) {
 	setupProfileConfigDir(t)
 	multi := &core.MultiAppConfig{
--- a/cmd/profile/remove.go
+++ b/cmd/profile/remove.go
@@ -28,7 +28,6 @@ func NewCmdProfileRemove(f *cmdutil.Factory) *cobra.Command {
 	cmdutil.SetTips(cmd, []string{
 		"AI agents: Do NOT remove profiles unless the user explicitly asks. This is destructive and clears all associated credentials.",
 	})
-	cmdutil.SetRisk(cmd, "write")
 	return cmd
 }

--- a/cmd/profile/rename.go
+++ b/cmd/profile/rename.go
@@ -24,7 +24,6 @@ func NewCmdProfileRename(f *cmdutil.Factory) *cobra.Command {
 			return profileRenameRun(f, args[0], args[1])
 		},
 	}
-	cmdutil.SetRisk(cmd, "write")
 	return cmd
 }

--- a/cmd/profile/use.go
+++ b/cmd/profile/use.go
@@ -27,7 +27,6 @@ func NewCmdProfileUse(f *cmdutil.Factory) *cobra.Command {
 	cmdutil.SetTips(cmd, []string{
 		"AI agents: Do NOT switch profiles unless the user explicitly asks.",
 	})
-	cmdutil.SetRisk(cmd, "write")
 	return cmd
 }

--- a/cmd/prune.go
+++ b/cmd/prune.go
@@ -7,12 +7,10 @@ import (
 	"fmt"
 	"slices"

-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/internal/cmdpolicy"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
+	"github.com/spf13/cobra"
 )

 // pruneForStrictMode removes commands incompatible with the active strict mode.
@@ -45,80 +43,15 @@ func pruneIncompatible(parent *cobra.Command, mode core.StrictMode) {
 }

 func strictModeStubFrom(child *cobra.Command, mode core.StrictMode) *cobra.Command {
-	// The denial annotations let the hook layer's populateInvocationDenial
-	// recognise this command as denied, so the Wrap chain is physically
-	// isolated (wrapRunE takes the DeniedByPolicy branch and calls the
-	// stub RunE directly). Without these, a plugin Wrapper registered
-	// against platform.All() could intercept and silently swallow the
-	// strict-mode error -- breaking strict-mode's "hard boundary" contract.
-	//
-	// Args + PersistentPreRunE overrides mirror cmdpolicy/apply.go::installDenyStub:
-	//
-	//   - Args=ArbitraryArgs: with DisableFlagParsing the user's flags
-	//     look like positional args; the original child's Args validator
-	//     (e.g. cobra.NoArgs) would fire BEFORE RunE and produce a
-	//     cobra usage error instead of our strict_mode envelope.
-	//
-	//   - PersistentPreRunE no-op: cmd/auth/auth.go declares a parent
-	//     PersistentPreRunE that returns external_provider when env
-	//     credentials are set. Cobra's "first wins walking up" would
-	//     pick auth's instead of our denial. A leaf-level no-op makes
-	//     cobra stop here and proceed to the wrapped RunE.
-	//
-	// strict-mode keeps its short Message + independent Hint and
-	// composes the shared detail.* / wrapped-CommandDeniedError shape
-	// by hand; BuildDenialError would override Message with the
-	// CommandDeniedError.Error() long form.
-	stubMessage := fmt.Sprintf(
-		"strict mode is %q, only %s-identity commands are available",
-		mode, mode.ForcedIdentity())
-	const stubHint = "if the user explicitly wants to switch policy, see `lark-cli config strict-mode --help` (confirm with the user before switching; switching does NOT require re-bind)"
-	denial := cmdpolicy.Denial{
-		Layer:        cmdpolicy.LayerStrictMode,
-		PolicySource: "strict-mode",
-		ReasonCode:   "identity_not_supported",
-		Reason:       stubMessage,
-	}
-	// Preserve the original command's annotations (risk_level,
-	// lark:supportedIdentities, cmdmeta.domain, ...) and help text so
-	// audit / compliance observers can still see what was denied.
-	// Stamp the denial annotations on top.
-	annotations := make(map[string]string, len(child.Annotations)+2)
-	for k, v := range child.Annotations {
-		annotations[k] = v
-	}
-	annotations[cmdpolicy.AnnotationDenialLayer] = cmdpolicy.LayerStrictMode
-	annotations[cmdpolicy.AnnotationDenialSource] = "strict-mode"
-
 	return &cobra.Command{
 		Use:                child.Use,
 		Aliases:            append([]string(nil), child.Aliases...),
-		Short:              child.Short,
-		Long:               child.Long,
 		Hidden:             true,
 		DisableFlagParsing: true,
-		Args:               cobra.ArbitraryArgs,
-		Annotations:        annotations,
-		PersistentPreRunE: func(c *cobra.Command, _ []string) error {
-			c.SilenceUsage = true
-			return nil
-		},
-		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{
-					Type:    "command_denied",
-					Message: stubMessage,
-					Hint:    stubHint,
-					Detail:  cmdpolicy.DenialDetailMap(cd),
-				},
-				Err: cd,
-			}
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return output.ErrWithHint(output.ExitValidation, "strict_mode",
+				fmt.Sprintf("strict mode is %q, only %s-identity commands are available", mode, mode.ForcedIdentity()),
+				"if the user explicitly wants to switch policy, see `lark-cli config strict-mode --help` (confirm with the user before switching; switching does NOT require re-bind)")
 		},
 	}
 }
--- a/cmd/prune_test.go
+++ b/cmd/prune_test.go
@@ -4,15 +4,11 @@
 package cmd

 import (
-	"errors"
 	"strings"
 	"testing"

-	"github.com/larksuite/cli/extension/platform"
-	"github.com/larksuite/cli/internal/cmdpolicy"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/spf13/cobra"
 )

@@ -202,176 +198,3 @@ func TestPruneForStrictMode_User_DirectBotShortcutReturnsStrictMode(t *testing.T
 		t.Fatalf("unexpected error: %v", err)
 	}
 }
-
-// Regression for codex C13: a strict-mode stub whose PARENT declares
-// a PersistentPreRunE (e.g. cmd/auth/auth.go's external_provider
-// check on env credentials) must surface the strict_mode envelope,
-// not the parent's error. Cobra's "first PersistentPreRunE wins
-// walking up from leaf" semantics will pick the parent's unless the
-// stub itself carries its own.
-//
-// Fix: strictModeStubFrom installs a no-op PersistentPreRunE so cobra
-// stops at the stub and proceeds to its RunE.
-func TestStrictModeStub_BypassesParentPersistentPreRunE(t *testing.T) {
-	root := newTestTree()
-	pruneForStrictMode(root, core.StrictModeBot)
-	stub := findCmd(root, "auth", "login")
-	if stub == nil {
-		t.Fatal("auth/login stub should exist after StrictModeBot")
-	}
-	if stub.PersistentPreRunE == nil {
-		t.Fatal("strict-mode stub must declare PersistentPreRunE on leaf")
-	}
-	if err := stub.PersistentPreRunE(stub, nil); err != nil {
-		t.Errorf("strict-mode stub PersistentPreRunE should be no-op, got %v", err)
-	}
-}
-
-// Regression for codex H13: strict-mode stub must accept arbitrary
-// positional args. With DisableFlagParsing=true, a user passing
-// `auth login --scope ...` looks like 4 positional args; the original
-// cobra.Args validator would surface a usage error BEFORE strict-mode
-// stub's RunE.
-func TestStrictModeStub_BypassesArgsValidator(t *testing.T) {
-	root := newTestTree()
-	pruneForStrictMode(root, core.StrictModeBot)
-	stub := findCmd(root, "auth", "login")
-	if stub == nil {
-		t.Fatal("auth/login stub should exist after StrictModeBot")
-	}
-	if stub.Args == nil {
-		t.Fatal("strict-mode stub must declare Args validator")
-	}
-	if err := stub.Args(stub, []string{"--scope", "im.message", "--profile", "default"}); err != nil {
-		t.Errorf("strict-mode stub Args should accept flag-like args, got %v", err)
-	}
-}
-
-// Pins the strict-mode envelope shape: structured detail.* / wrapped
-// CommandDeniedError for external agents, AND the historical short
-// Message + independent Hint for existing consumers.
-func TestStrictModeStub_StructuredEnvelope(t *testing.T) {
-	root := newTestTree()
-	pruneForStrictMode(root, core.StrictModeBot)
-	stub := findCmd(root, "im", "+search")
-	if stub == nil {
-		t.Fatalf("expected im/+search stub")
-	}
-	err := stub.RunE(stub, nil)
-	if err == nil {
-		t.Fatalf("strict-mode stub RunE should return error")
-	}
-
-	var ee *output.ExitError
-	if !errors.As(err, &ee) {
-		t.Fatalf("err is not *output.ExitError: %T", err)
-	}
-	if ee.Detail == nil {
-		t.Fatalf("ExitError.Detail is nil; envelope writer cannot emit JSON")
-	}
-	if ee.Detail.Type != "command_denied" {
-		t.Errorf("Detail.Type = %q, want command_denied", ee.Detail.Type)
-	}
-	dm, ok := ee.Detail.Detail.(map[string]any)
-	if !ok {
-		t.Fatalf("Detail.Detail = %T, want map[string]any", ee.Detail.Detail)
-	}
-	if got, _ := dm["layer"].(string); got != cmdpolicy.LayerStrictMode {
-		t.Errorf("Detail.Detail[layer] = %q, want %q", got, cmdpolicy.LayerStrictMode)
-	}
-	if got, _ := dm["reason_code"].(string); got != "identity_not_supported" {
-		t.Errorf("Detail.Detail[reason_code] = %q, want identity_not_supported", got)
-	}
-	if got, _ := dm["policy_source"].(string); got != "strict-mode" {
-		t.Errorf("Detail.Detail[policy_source] = %q, want strict-mode", got)
-	}
-
-	var cd *platform.CommandDeniedError
-	if !errors.As(err, &cd) {
-		t.Fatalf("err does not unwrap to *platform.CommandDeniedError")
-	}
-	if cd.Layer != cmdpolicy.LayerStrictMode {
-		t.Errorf("CommandDeniedError.Layer = %q, want %q", cd.Layer, cmdpolicy.LayerStrictMode)
-	}
-	if cd.ReasonCode != "identity_not_supported" {
-		t.Errorf("CommandDeniedError.ReasonCode = %q, want identity_not_supported", cd.ReasonCode)
-	}
-	if !strings.Contains(cd.Reason, `strict mode is "bot"`) {
-		t.Errorf("CommandDeniedError.Reason = %q, want substring 'strict mode is \"bot\"'", cd.Reason)
-	}
-	if ee.Detail.Message != `strict mode is "bot", only bot-identity commands are available` {
-		t.Errorf("Detail.Message = %q, want short historical form", ee.Detail.Message)
-	}
-	if !strings.HasPrefix(ee.Detail.Hint, "if the user explicitly wants to switch policy") {
-		t.Errorf("Detail.Hint = %q, want historical hint", ee.Detail.Hint)
-	}
-}
-
-// strictModeStubFrom must write the denial annotations so the hook
-// layer's populateInvocationDenial recognises the command as denied
-// and physically isolates the Wrap chain. Without this, a plugin
-// Wrapper registered against platform.All() could intercept the stub
-// and silently return nil, swallowing the strict-mode error.
-func TestStrictModeStub_HasDenialAnnotation(t *testing.T) {
-	root := newTestTree()
-	pruneForStrictMode(root, core.StrictModeBot)
-
-	// im/+search is user-only -> replaced by a stub in StrictModeBot.
-	stub := findCmd(root, "im", "+search")
-	if stub == nil {
-		t.Fatalf("expected im/+search stub to exist")
-	}
-	got := stub.Annotations[cmdpolicy.AnnotationDenialLayer]
-	if got != cmdpolicy.LayerStrictMode {
-		t.Errorf("stub annotation %q = %q, want %q",
-			cmdpolicy.AnnotationDenialLayer, got, cmdpolicy.LayerStrictMode)
-	}
-	if src := stub.Annotations[cmdpolicy.AnnotationDenialSource]; src != "strict-mode" {
-		t.Errorf("stub annotation %q = %q, want %q",
-			cmdpolicy.AnnotationDenialSource, src, "strict-mode")
-	}
-}
-
-// Audit / compliance observers fire even for strict-mode-denied commands
-// and rely on CommandView.Risk() / Identities() / etc. The stub must
-// carry the original command's annotations so those accessors keep
-// returning meaningful values; the Short/Long are preserved so `--help`
-// on a denied command still describes the original intent (parity with
-// cmdpolicy/apply.go::installDenyStub).
-func TestStrictModeStub_PreservesOriginalMetadata(t *testing.T) {
-	root := &cobra.Command{Use: "root"}
-	svc := &cobra.Command{Use: "im"}
-	root.AddCommand(svc)
-	userOnly := &cobra.Command{
-		Use:   "+search",
-		Short: "search messages",
-		Long:  "Search across IM history.",
-		RunE:  func(*cobra.Command, []string) error { return nil },
-	}
-	cmdutil.SetSupportedIdentities(userOnly, []string{"user"})
-	cmdutil.SetRisk(userOnly, "read")
-	svc.AddCommand(userOnly)
-
-	pruneForStrictMode(root, core.StrictModeBot)
-
-	stub := findCmd(root, "im", "+search")
-	if stub == nil {
-		t.Fatalf("expected im/+search stub")
-	}
-	if got := stub.Annotations["risk_level"]; got != "read" {
-		t.Errorf("stub risk_level = %q, want %q (lost in replacement)", got, "read")
-	}
-	if got := stub.Annotations["lark:supportedIdentities"]; got != "user" {
-		t.Errorf("stub supportedIdentities = %q, want %q", got, "user")
-	}
-	if stub.Short != "search messages" {
-		t.Errorf("stub Short = %q, want preserved Short", stub.Short)
-	}
-	if stub.Long != "Search across IM history." {
-		t.Errorf("stub Long = %q, want preserved Long", stub.Long)
-	}
-	// Denial stamps must still be present.
-	if stub.Annotations[cmdpolicy.AnnotationDenialLayer] != cmdpolicy.LayerStrictMode {
-		t.Errorf("denial annotation overwritten or missing")
-	}
-}
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -4,23 +4,20 @@
 package cmd

 import (
+	"bytes"
 	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
+	"io"
+	"net/url"
 	"os"
-	"sort"
-	"strings"
+	"strconv"

-	"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"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/errclass"
-	"github.com/larksuite/cli/internal/errcompat"
-	"github.com/larksuite/cli/internal/hook"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/registry"
 	"github.com/larksuite/cli/internal/skillscheck"
@@ -48,6 +45,20 @@ EXAMPLES:
    # Generic API call
    lark-cli api GET /open-apis/calendar/v4/calendars

+FLAGS:
+    --params <json>       URL/query parameters JSON
+    --data <json>         request body JSON (POST/PATCH/PUT/DELETE)
+    --as <type>           identity type: user | bot
+    --format <fmt>        output format: json (default) | ndjson | table | csv | pretty
+    --page-all            automatically paginate through all pages
+    --page-size <N>       page size (0 = use API default)
+    --page-limit <N>      max pages to fetch with --page-all (default: 10, 0 for unlimited)
+    --page-delay <MS>     delay in ms between pages (default: 200, only with --page-all)
+    -o, --output <path>   output file path for binary responses
+    --jq <expr>           jq expression to filter JSON output
+    -q <expr>             shorthand for --jq
+    --dry-run             print request without executing
+
 AI AGENT SKILLS:
    lark-cli pairs with AI agent skills (Claude Code, etc.) that
    teach the agent Lark API patterns, best practices, and workflows.
@@ -77,9 +88,8 @@ func Execute() int {
 	}
 	configureFlagCompletions(os.Args)

-	ctx := context.Background()
-	f, rootCmd, reg := buildInternal(
-		ctx, inv,
+	f, rootCmd := buildInternal(
+		context.Background(), inv,
 		WithIO(os.Stdin, os.Stdout, os.Stderr),
 		HideProfile(isSingleAppMode()),
 	)
@@ -89,18 +99,8 @@ func Execute() int {
 		setupNotices()
 	}

-	runErr := rootCmd.Execute()
-
-	// Fire Shutdown lifecycle hooks regardless of run outcome.
-	// emitShutdown imposes a 2s total deadline and never propagates handler
-	// errors (Emit's documented Shutdown contract), so it cannot block exit
-	// or alter the user-visible exit code.
-	if reg != nil && !isCompletionCommand(os.Args) {
-		_ = hook.Emit(ctx, reg, platform.Shutdown, runErr)
-	}
-
-	if runErr != nil {
-		return handleRootError(f, runErr)
+	if err := rootCmd.Execute(); err != nil {
+		return handleRootError(f, err)
 	}
 	return 0
 }
@@ -159,17 +159,11 @@ func setupNotices() {
 }

 // isCompletionCommand returns true if args indicate a shell completion request.
-// Update notifications and Shutdown lifecycle emits must be suppressed for
-// these to avoid corrupting machine-parseable completion output and to avoid
-// firing plugin Shutdown handlers on every Tab keystroke.
-//
-// Cobra dispatches BOTH "__complete" and its alias "__completeNoDesc" through
-// the same hidden subcommand (see cobra/completions.go ShellCompRequestCmd /
-// ShellCompNoDescRequestCmd). Check both, otherwise bash/zsh completion
-// (which often uses NoDesc) silently bypasses the gate.
+// Update notifications must be suppressed for these to avoid corrupting
+// machine-parseable completion output.
 func isCompletionCommand(args []string) bool {
 	for _, arg := range args {
-		if arg == "completion" || arg == "__complete" || arg == "__completeNoDesc" {
+		if arg == "completion" || arg == "__complete" {
 			return true
 		}
 	}
@@ -184,75 +178,22 @@ func configureFlagCompletions(args []string) {

 // handleRootError dispatches a command error to the appropriate handler
 // and returns the process exit code.
-//
-// Dispatch order:
-//  1. Legacy shapes (*core.ConfigError, *internalauth.NeedAuthorizationError)
-//     are promoted via errcompat to their typed errs/ counterparts, with the
-//     original preserved in the Cause chain.
-//  2. Typed errors from errs/ (e.g. *errs.PermissionError, *errs.APIError,
-//     *errs.SecurityPolicyError, *errs.AuthenticationError): render via the
-//     typed envelope writer, which lifts extension fields (missing_scopes,
-//     console_url, challenge_url, ...) to the top level. Routed by
-//     errs.CategoryOf via ExitCodeOf.
-//  3. Legacy *output.ExitError: asExitError adapts it to the legacy
-//     envelope, written via WriteErrorEnvelope.
-//  4. Cobra errors (required flags, unknown commands, etc.): plain text.
 func handleRootError(f *cmdutil.Factory, err error) int {
 	errOut := f.IOStreams.ErrOut

-	// Promote legacy error shapes into typed errs/ before envelope marshal.
-	// NeedAuthorizationError check is first because it is the more specific
-	// shape; *core.ConfigError check follows. errors.As preserves the original
-	// in the Cause chain, so external errors.As(&core.ConfigError{}) consumers
-	// (cmd/auth/list.go, cmd/doctor/doctor.go, ...) still match.
-	//
-	// Outer-typed short-circuit: if err is already a typed *errs.* error,
-	// skip PromoteXxxError so the producer's Subtype / Hint / extension
-	// fields are not overwritten by a coarser promoted shape derived from a
-	// legacy error buried in its Cause chain. Promotion is only for legacy
-	// untyped entry points.
-	if !isOuterTypedError(err) {
-		var needAuthErr *internalauth.NeedAuthorizationError
-		if errors.As(err, &needAuthErr) {
-			err = errcompat.PromoteAuthError(needAuthErr)
-		} else {
-			var cfgErr *core.ConfigError
-			if errors.As(err, &cfgErr) {
-				err = errcompat.PromoteConfigError(cfgErr)
-			}
-		}
-	}
-
-	// 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)
-
-	// Staged dispatch: capture the typed exit code BEFORE attempting the
-	// envelope write. WriteTypedErrorEnvelope is best-effort on the wire
-	// (partial-write still returns true) so the exit code we read here is
-	// preserved even if stderr is torn — torn stderr must not downgrade
-	// typed exits 3/4/6/10 to the legacy "Error:" path with exit 1.
-	// WriteTypedErrorEnvelope still returns false when err carries no
-	// Problem; in that case we fall through to the legacy bridge below.
-	typedExit := output.ExitCodeOf(err)
-	if output.WriteTypedErrorEnvelope(errOut, err, string(f.ResolvedIdentity)) {
-		return typedExit
-	}
-
-	// Partial-failure (batch / multi-status): the ok:false result envelope is
-	// already on stdout; set the exit code and write nothing to stderr.
-	var pfErr *output.PartialFailureError
-	if errors.As(err, &pfErr) {
-		return pfErr.Code
+	// 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
 	}

+	// 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)
 		}
@@ -260,23 +201,13 @@ 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
 }

-// isOuterTypedError returns true if err is a typed *errs.* error AT THE
-// TOP OF THE CHAIN (not buried inside Unwrap). Used by handleRootError
-// to gate PromoteXxxError so a producer's outer typed envelope is never
-// overwritten by a coarser shape derived from its legacy Cause.
-func isOuterTypedError(err error) bool {
-	_, ok := err.(errs.TypedError)
-	return ok
-}
-
 // asExitError converts known structured error types to *output.ExitError.
 // Returns nil for unrecognized errors (e.g. cobra flag errors).
-//
-// Deprecated: legacy *output.ExitError bridge.
 func asExitError(err error) *output.ExitError {
 	var cfgErr *core.ConfigError
 	if errors.As(err, &cfgErr) {
@@ -289,75 +220,47 @@ func asExitError(err error) *output.ExitError {
 	return nil
 }

-// installUnknownSubcommandGuard replaces cobra's silent help fallback on
-// group commands (no Run/RunE) with an unknown_subcommand error.
-//
-// IMPORTANT: every command modified here is also tagged with
-// cmdpolicy.AnnotationPureGroup so the user-layer policy engine
-// continues to treat the command as a pure parent group. Without the
-// tag, the RunE injection here would flip Runnable()=true and a user
-// rule like `max_risk: read` would deny every `<group> --help` call
-// with reason_code=risk_not_annotated.
-func installUnknownSubcommandGuard(cmd *cobra.Command) {
-	if cmd.HasSubCommands() && cmd.Run == nil && cmd.RunE == nil {
-		cmd.RunE = unknownSubcommandRunE
-		if cmd.Annotations == nil {
-			cmd.Annotations = map[string]string{}
-		}
-		cmd.Annotations[cmdpolicy.AnnotationPureGroup] = "true"
+// 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.Code {
+	case internalauth.LarkErrBlockByPolicyTryAuth:
+		codeStr = "challenge_required"
+	case internalauth.LarkErrBlockByPolicy:
+		codeStr = "access_denied"
+	default:
+		codeStr = strconv.Itoa(spErr.Code)
 	}
-	for _, c := range cmd.Commands() {
-		installUnknownSubcommandGuard(c)
-	}
-}

-// 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()
+	errData := map[string]interface{}{
+		"type":      "auth_error",
+		"code":      codeStr,
+		"message":   spErr.Message,
+		"retryable": false,
 	}
-	unknown := args[0]
-	available := availableSubcommandNames(cmd)
-	msg := fmt.Sprintf("unknown subcommand %q for %q", unknown, cmd.CommandPath())
-	hint := fmt.Sprintf("run `%s --help` to see available subcommands", cmd.CommandPath())
-	if len(available) > 0 {
-		hint = fmt.Sprintf("available subcommands: %s", strings.Join(available, ", "))
+	if spErr.ChallengeURL != "" {
+		errData["challenge_url"] = spErr.ChallengeURL
 	}
-	return &output.ExitError{
-		Code: output.ExitValidation,
-		Detail: &output.ErrDetail{
-			Type:    "unknown_subcommand",
-			Message: msg,
-			Hint:    hint,
-			Detail: map[string]any{
-				"unknown":      unknown,
-				"command_path": cmd.CommandPath(),
-				"available":    available,
-			},
-		},
+	if spErr.CLIHint != "" {
+		errData["hint"] = spErr.CLIHint
 	}
-}

-func availableSubcommandNames(cmd *cobra.Command) []string {
-	subs := make([]string, 0, len(cmd.Commands()))
-	for _, c := range cmd.Commands() {
-		if c.Hidden || !c.IsAvailableCommand() {
-			continue
-		}
-		name := c.Name()
-		if name == "help" || name == "completion" {
-			continue
-		}
-		subs = append(subs, name)
+	env := map[string]interface{}{"ok": false, "error": errData}
+
+	buffer := &bytes.Buffer{}
+	encoder := json.NewEncoder(buffer)
+	encoder.SetEscapeHTML(false)
+	encoder.SetIndent("", "  ")
+	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
 	}
-	sort.Strings(subs)
-	return subs
+	fmt.Fprint(w, buffer.String())
 }

 // installTipsHelpFunc wraps the default help function to append a TIPS section
@@ -392,55 +295,97 @@ func installTipsHelpFunc(root *cobra.Command) {
 	})
 }

-// enrichPermissionError rewrites the legacy *output.ExitError envelope so its
-// Message + Hint match the per-subtype canonical text produced by the typed
-// dispatcher path (errclass.CanonicalPermissionMessage / errclass.PermissionHint).
-// This guarantees a caller observing the wire envelope cannot tell whether
-// the error reached the dispatcher via the legacy *ExitError bridge or via
-// the typed *errs.PermissionError fast path.
-//
-// Deprecated: legacy *output.ExitError enrichment; typed PermissionError
-// values produced by errclass.BuildAPIError already carry MissingScopes +
-// ConsoleURL directly.
+// 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 {
+	if exitErr.Detail == nil || exitErr.Detail.Type != "permission" {
 		return
 	}
-	// Only the legacy permission-class envelope types route here. "app_status"
-	// covers 99991662 (app_disabled) / 99991673 (app_unavailable); "permission"
-	// covers the four scope-class codes (99991672 / 99991676 / 99991679 / 230027).
-	if exitErr.Detail.Type != "permission" && exitErr.Detail.Type != "app_status" {
+	// Extract required scopes from API error detail
+	scopes := extractRequiredScopes(exitErr.Detail.Detail)
+	if len(scopes) == 0 {
 		return
 	}

-	larkCode := exitErr.Detail.Code
-	meta, ok := errclass.LookupCodeMeta(larkCode)
-	if !ok || meta.Category != errs.CategoryAuthorization {
-		return
-	}
-
-	// Extract required scopes from API error detail (shared helper). May be
-	// empty for app-status codes — canonical message + hint still apply.
-	missing := registry.ExtractRequiredScopes(exitErr.Detail.Detail)
-
 	cfg, err := f.Config()
 	if err != nil {
 		return
 	}

-	// Reuse the same console URL builder as the typed path so both wire
-	// envelopes carry identical console_url values for the same input.
-	consoleURL := errclass.ConsoleURL(string(cfg.Brand), cfg.AppID, missing)
-
-	// Clear raw API detail — useful info is now in message/hint/console_url.
-	exitErr.Detail.Detail = nil
-
-	identity := string(f.ResolvedIdentity)
-	if identity == "" {
-		identity = "user"
+	// Select the recommended (least-privilege) scope
+	scopeIfaces := make([]interface{}, len(scopes))
+	for i, s := range scopes {
+		scopeIfaces[i] = s
+	}
+	recommended := registry.SelectRecommendedScope(scopeIfaces, "tenant")
+	if recommended == "" {
+		recommended = scopes[0]
 	}

-	exitErr.Detail.Message = errclass.CanonicalPermissionMessage(meta.Subtype, cfg.AppID, missing, exitErr.Detail.Message)
-	exitErr.Detail.Hint = errclass.PermissionHint(missing, identity, meta.Subtype, consoleURL)
-	exitErr.Detail.ConsoleURL = consoleURL
+	// Build admin console URL with the recommended scope
+	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
+	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)"
+		} else {
+			exitErr.Detail.Hint = 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)
+		}
+		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)"
+		} else {
+			exitErr.Detail.Hint = fmt.Sprintf(
+				"enable scope in console (see console_url), or 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)
+		}
+		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
 }
--- a/cmd/root_integration_test.go
+++ b/cmd/root_integration_test.go
@@ -27,14 +27,6 @@ import (
 	"github.com/spf13/cobra"
 )

-// Canonical strict-mode envelope strings shared across fixtures
-// (reflect.DeepEqual pins them; keep in sync with strictModeStubFrom).
-const (
-	strictModeBotMessage  = `strict mode is "bot", only bot-identity commands are available`
-	strictModeUserMessage = `strict mode is "user", only user-identity commands are available`
-	strictModeHint        = "if the user explicitly wants to switch policy, see `lark-cli config strict-mode --help` (confirm with the user before switching; switching does NOT require re-bind)"
-)
-
 // buildIntegrationRootCmd creates a root command with api, service, and shortcut
 // subcommands wired to a test factory, simulating the real CLI command tree.
 func buildIntegrationRootCmd(t *testing.T, f *cmdutil.Factory) *cobra.Command {
@@ -161,8 +153,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)
@@ -209,17 +353,9 @@ func TestIntegration_StrictModeBot_ProfileOverride_DirectAuthLoginReturnsEnvelop
 	assertEnvelope(t, code, output.ExitValidation, stdout, stderr, output.ErrorEnvelope{
 		OK: false,
 		Error: &output.ErrDetail{
-			Type:    "command_denied",
-			Message: strictModeBotMessage,
-			Hint:    strictModeHint,
-			Detail: map[string]any{
-				"path":          "auth/login",
-				"layer":         "strict_mode",
-				"policy_source": "strict-mode",
-				"rule_name":     "",
-				"reason_code":   "identity_not_supported",
-				"reason":        strictModeBotMessage,
-			},
+			Type:    "strict_mode",
+			Message: `strict mode is "bot", only bot-identity commands are available`,
+			Hint:    "if the user explicitly wants to switch policy, see `lark-cli config strict-mode --help` (confirm with the user before switching; switching does NOT require re-bind)",
 		},
 	})
 }
@@ -235,17 +371,9 @@ func TestIntegration_StrictModeBot_ProfileOverride_DirectUserShortcutReturnsEnve
 	assertEnvelope(t, code, output.ExitValidation, stdout, stderr, output.ErrorEnvelope{
 		OK: false,
 		Error: &output.ErrDetail{
-			Type:    "command_denied",
-			Message: strictModeBotMessage,
-			Hint:    strictModeHint,
-			Detail: map[string]any{
-				"path":          "im/+messages-search",
-				"layer":         "strict_mode",
-				"policy_source": "strict-mode",
-				"rule_name":     "",
-				"reason_code":   "identity_not_supported",
-				"reason":        strictModeBotMessage,
-			},
+			Type:    "strict_mode",
+			Message: `strict mode is "bot", only bot-identity commands are available`,
+			Hint:    "if the user explicitly wants to switch policy, see `lark-cli config strict-mode --help` (confirm with the user before switching; switching does NOT require re-bind)",
 		},
 	})
 }
@@ -281,7 +409,7 @@ func TestIntegration_StrictModeUser_ProfileOverride_ShortcutExplicitBotReturnsEn
 		OK:       false,
 		Identity: "bot",
 		Error: &output.ErrDetail{
-			Type:    "validation",
+			Type:    "strict_mode",
 			Message: `strict mode is "user", only user-identity commands are available`,
 			Hint:    "if the user explicitly wants to switch policy, see `lark-cli config strict-mode --help` (confirm with the user before switching; switching does NOT require re-bind)",
 		},
@@ -300,7 +428,7 @@ func TestIntegration_StrictModeBot_ProfileOverride_ServiceExplicitUserReturnsEnv
 		OK:       false,
 		Identity: "user",
 		Error: &output.ErrDetail{
-			Type:    "validation",
+			Type:    "strict_mode",
 			Message: `strict mode is "bot", only bot-identity commands are available`,
 			Hint:    "if the user explicitly wants to switch policy, see `lark-cli config strict-mode --help` (confirm with the user before switching; switching does NOT require re-bind)",
 		},
@@ -318,17 +446,9 @@ func TestIntegration_StrictModeUser_ProfileOverride_ServiceBotOnlyMethodReturnsE
 	assertEnvelope(t, code, output.ExitValidation, stdout, stderr, output.ErrorEnvelope{
 		OK: false,
 		Error: &output.ErrDetail{
-			Type:    "command_denied",
-			Message: strictModeUserMessage,
-			Hint:    strictModeHint,
-			Detail: map[string]any{
-				"path":          "im/images/create",
-				"layer":         "strict_mode",
-				"policy_source": "strict-mode",
-				"rule_name":     "",
-				"reason_code":   "identity_not_supported",
-				"reason":        strictModeUserMessage,
-			},
+			Type:    "strict_mode",
+			Message: `strict mode is "user", only user-identity commands are available`,
+			Hint:    "if the user explicitly wants to switch policy, see `lark-cli config strict-mode --help` (confirm with the user before switching; switching does NOT require re-bind)",
 		},
 	})
 }
@@ -345,7 +465,7 @@ func TestIntegration_StrictModeBot_ProfileOverride_APIExplicitUserReturnsEnvelop
 		OK:       false,
 		Identity: "user",
 		Error: &output.ErrDetail{
-			Type:    "validation",
+			Type:    "strict_mode",
 			Message: `strict mode is "bot", only bot-identity commands are available`,
 			Hint:    "if the user explicitly wants to switch policy, see `lark-cli config strict-mode --help` (confirm with the user before switching; switching does NOT require re-bind)",
 		},
@@ -372,7 +492,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 +504,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 +539,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 +572,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 +627,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)
 	}

--- a/cmd/root_test.go
+++ b/cmd/root_test.go
@@ -4,25 +4,19 @@
 package cmd

 import (
-	"bytes"
-	"encoding/json"
-	"fmt"
-	"io"
 	"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
@@ -74,255 +68,130 @@ func TestPersistentPreRunE_ConfigSubcommands(t *testing.T) {
 	}
 }

-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)
-	}
-	if strings.Contains(rootLong, "https://github.com/larksuite/cli#install-ai-agent-skills") {
-		t.Fatalf("root help should not reference the removed install-ai-agent-skills anchor, got:\n%s", rootLong)
-	}
-}
-
-func TestConfigureFlagCompletions(t *testing.T) {
-	t.Cleanup(func() { cmdutil.SetFlagCompletionsEnabled(false) })
-
-	tests := []struct {
-		name         string
-		args         []string
-		wantDisabled bool
-	}{
-		{"plain command", []string{"im", "+send"}, true},
-		{"help flag", []string{"im", "--help"}, true},
-		{"no args", []string{}, true},
-		{"__complete request", []string{"__complete", "im", "+send", ""}, false},
-		{"__completeNoDesc request", []string{"__completeNoDesc", "im", "+send", ""}, false},
-		{"completion subcommand", []string{"completion", "bash"}, false},
-	}
-	for _, tc := range tests {
-		t.Run(tc.name, func(t *testing.T) {
-			cmdutil.SetFlagCompletionsEnabled(tc.wantDisabled)
-			configureFlagCompletions(tc.args)
-			if got := !cmdutil.FlagCompletionsEnabled(); got != tc.wantDisabled {
-				t.Fatalf("FlagCompletionsEnabled() = %v, want disabled=%v", !got, tc.wantDisabled)
-			}
-		})
-	}
-}
-
-// isCompletionCommand must classify BOTH cobra completion aliases as
-// completion requests so the Shutdown emit and update-notice paths skip
-// shell-completion invocations. __completeNoDesc is an Alias of
-// __complete (cobra/completions.go ShellCompNoDescRequestCmd) and
-// dispatches the same RunE; bash/zsh completion typically calls the
-// NoDesc variant.
-func TestIsCompletionCommand(t *testing.T) {
-	tests := []struct {
-		name string
-		args []string
-		want bool
-	}{
-		{"plain command", []string{"im", "+send"}, false},
-		{"__complete", []string{"__complete", "im"}, true},
-		{"__completeNoDesc", []string{"__completeNoDesc", "im"}, true},
-		{"completion subcommand", []string{"completion", "bash"}, true},
-		{"completion in tail", []string{"foo", "bar", "completion"}, true},
-	}
-	for _, tc := range tests {
-		t.Run(tc.name, func(t *testing.T) {
-			if got := isCompletionCommand(tc.args); got != tc.want {
-				t.Fatalf("isCompletionCommand(%v) = %v, want %v", tc.args, got, tc.want)
-			}
-		})
-	}
-}
-
-// TestPromoteConfigError_* lives with the implementation in
-// internal/errcompat/promote_test.go.
-
-// TestHandleRootError_SecurityPolicyCanonicalEnvelope verifies that
-// *errs.SecurityPolicyError flows through the canonical typed envelope
-// (output.WriteTypedErrorEnvelope) — type=policy, numeric code, subtype,
-// top-level identity, exit code 6 — after the dispatcher carve-out is removed.
-func TestHandleRootError_SecurityPolicyCanonicalEnvelope(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	t.Run("21000 challenge_required", 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:  errs.SubtypeChallengeRequired,
-				Code:     21000,
-				Message:  "blocked by access policy",
-				Hint:     "complete challenge in your browser",
-			},
-			ChallengeURL: "https://example.com/challenge",
-		}
-
-		gotExit := handleRootError(f, spErr)
-		if gotExit != int(output.ExitContentSafety) {
-			t.Errorf("exit code = %d, want %d (ExitContentSafety)", gotExit, output.ExitContentSafety)
-		}
-
-		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 != "policy" {
-			t.Errorf("error.type = %v, want %q", got, "policy")
-		}
-		if got := errObj["subtype"]; got != "challenge_required" {
-			t.Errorf("error.subtype = %v, want %q", got, "challenge_required")
-		}
-		if got, ok := errObj["code"].(float64); !ok || int(got) != 21000 {
-			t.Errorf("error.code = %v (%T), want 21000 (number)", errObj["code"], errObj["code"])
-		}
-		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)
-		}
-		if _, exists := errObj["retryable"]; exists {
-			t.Errorf("error.retryable leaked into canonical envelope: %v", errObj["retryable"])
-		}
+func TestHandleRootError_RawError_SkipsEnrichmentButWritesEnvelope(t *testing.T) {
+	f, _, stderr, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})

-	t.Run("21001 access_denied", 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:  errs.SubtypeAccessDenied,
-				Code:     21001,
-				Message:  "access denied",
-			},
-		}
-
-		gotExit := handleRootError(f, spErr)
-		if gotExit != int(output.ExitContentSafety) {
-			t.Errorf("exit code = %d, want %d", gotExit, output.ExitContentSafety)
-		}
-
-		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 := env["error"].(map[string]any)
-		if got := errObj["type"]; got != "policy" {
-			t.Errorf("error.type = %v, want %q", got, "policy")
-		}
-		if got := errObj["subtype"]; got != "access_denied" {
-			t.Errorf("error.subtype = %v, want %q", got, "access_denied")
-		}
-		if got, ok := errObj["code"].(float64); !ok || int(got) != 21001 {
-			t.Errorf("error.code = %v, want 21001 (number)", errObj["code"])
-		}
-	})
-}
-
-// 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),
+	// 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"},
 		},
-		Cause: cause,
+	})
+	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")
 	}
 }

-// failingWriter writes up to limit bytes then returns io.ErrShortWrite on
-// the write that would push past the limit. Used to simulate a stderr that
-// dies mid-envelope.
-type failingWriter struct {
-	limit int
-	n     int
-}
+func TestHandleRootError_NonRawError_EnrichesAndWritesEnvelope(t *testing.T) {
+	f, _, stderr, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})

-func (f *failingWriter) Write(p []byte) (int, error) {
-	if f.n+len(p) > f.limit {
-		canWrite := f.limit - f.n
-		if canWrite < 0 {
-			canWrite = 0
-		}
-		f.n += canWrite
-		return canWrite, io.ErrShortWrite
+	// 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)
 	}
-	f.n += len(p)
-	return len(p), nil
-}
-
-// TestHandleRootError_PartialWritePreservesExitCode pins that when the
-// stderr write fails mid-envelope, handleRootError still returns the typed
-// exit code (ExitAuth=3 for AuthenticationError), not fall through to the
-// plain "Error:" path with exit 1. ExitCodeOf is computed from the typed
-// err BEFORE the envelope write so the exit code is preserved even when
-// the consumer's stderr pipe dies.
-func TestHandleRootError_PartialWritePreservesExitCode(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-	w := &failingWriter{limit: 20}
-	f.IOStreams.ErrOut = w
-
-	err := errs.NewAuthenticationError(errs.SubtypeTokenExpired, "token expired")
-	exit := handleRootError(f, err)
-	if exit != int(output.ExitAuth) {
-		t.Errorf("exit = %d, want %d (typed exit code preserved despite write failure)", exit, int(output.ExitAuth))
+	// 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())
 	}
 }

-// TestHandleRootError_TypedOuterShortCircuitsPromote pins that when a typed
-// *errs.AuthenticationError carries a legacy *NeedAuthorizationError in its
-// Cause chain, the dispatcher does NOT run PromoteAuthError — doing so
-// would replace the producer's TokenExpired subtype + custom hint with the
-// promoted shape's TokenMissing.
-func TestHandleRootError_TypedOuterShortCircuitsPromote(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-	errOut := &bytes.Buffer{}
-	f.IOStreams.ErrOut = errOut
-
-	innerLegacy := &internalauth.NeedAuthorizationError{UserOpenId: "u_123"}
-	outer := errs.NewAuthenticationError(errs.SubtypeTokenExpired, "token expired").
-		WithHint("custom producer hint").
-		WithCause(innerLegacy)
-
-	exit := handleRootError(f, outer)
-	if exit != int(output.ExitAuth) {
-		t.Errorf("exit = %d, want %d (ExitAuth)", exit, int(output.ExitAuth))
+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",
+		},
 	}
-	got := errOut.String()
-	if !strings.Contains(got, `"subtype": "token_expired"`) {
-		t.Errorf("envelope lost producer Subtype TokenExpired; got %s", got)
-	}
-	if !strings.Contains(got, "custom producer hint") {
-		t.Errorf("envelope lost producer Hint; got %s", got)
+
+	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)
+			}
+		})
 	}
 }

-// 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) {
+func TestEnrichMissingScopeError_ServiceMethodUsesLocalScopesWhenNoUAT(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())

 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
@@ -354,23 +223,30 @@ func TestApplyNeedAuthorizationHint_ServiceMethodUsesLocalScopesWhenNoUAT(t *tes
 	resourceCmd.AddCommand(methodCmd)
 	f.CurrentCommand = methodCmd

-	authErr := newAuthErrorWithNeedAuthMarker()
-	applyNeedAuthorizationHint(f, authErr)
+	exitErr := output.Errorf(output.ExitAPI, "api_error", "API call failed: %s", &internalauth.NeedAuthorizationError{})
+	enrichMissingScopeError(f, exitErr)

-	if authErr.Category != errs.CategoryAuthentication {
-		t.Errorf("Category = %q, want authentication", authErr.Category)
+	if exitErr.Code != output.ExitAPI {
+		t.Fatalf("expected exit code %d, got %d", output.ExitAPI, exitErr.Code)
 	}
-	if !strings.Contains(authErr.Message, "need_user_authorization") {
-		t.Errorf("Message should preserve need_user_authorization marker; got %q", authErr.Message)
+	if exitErr.Detail == nil || exitErr.Detail.Type != "api_error" {
+		t.Fatalf("expected api_error detail, got %+v", exitErr.Detail)
 	}
-	if !strings.Contains(authErr.Hint, "current command requires scope(s): calendar:calendar.event:create") {
-		t.Errorf("expected declared-scope hint, got %q", authErr.Hint)
+	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)
 	}
 }

-// TestApplyNeedAuthorizationHint_ShortcutUsesDeclaredScopesWhenNoUAT pins the
-// same hint behavior for mounted shortcut commands.
-func TestApplyNeedAuthorizationHint_ShortcutUsesDeclaredScopesWhenNoUAT(t *testing.T) {
+func TestEnrichMissingScopeError_ShortcutUsesDeclaredScopesWhenNoUAT(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())

 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
@@ -385,17 +261,30 @@ func TestApplyNeedAuthorizationHint_ShortcutUsesDeclaredScopesWhenNoUAT(t *testi
 	serviceCmd.AddCommand(shortcutCmd)
 	f.CurrentCommand = shortcutCmd

-	authErr := newAuthErrorWithNeedAuthMarker()
-	applyNeedAuthorizationHint(f, authErr)
+	exitErr := output.ErrNetwork("API call failed: %s", &internalauth.NeedAuthorizationError{})
+	enrichMissingScopeError(f, exitErr)

-	if !strings.Contains(authErr.Hint, "current command requires scope(s): docx:document:create") {
-		t.Errorf("expected shortcut scope hint, got %q", authErr.Hint)
+	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)
 	}
 }

-// TestApplyNeedAuthorizationHint_ShortcutIncludesConditionalScopes pins that
-// conditional scopes declared on a shortcut surface in the hint.
-func TestApplyNeedAuthorizationHint_ShortcutIncludesConditionalScopes(t *testing.T) {
+func TestEnrichMissingScopeError_ShortcutIncludesConditionalScopes(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())

 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
@@ -410,18 +299,18 @@ func TestApplyNeedAuthorizationHint_ShortcutIncludesConditionalScopes(t *testing
 	serviceCmd.AddCommand(shortcutCmd)
 	f.CurrentCommand = shortcutCmd

-	authErr := newAuthErrorWithNeedAuthMarker()
-	applyNeedAuthorizationHint(f, authErr)
+	exitErr := output.ErrNetwork("API call failed: %s", &internalauth.NeedAuthorizationError{})
+	enrichMissingScopeError(f, exitErr)

-	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)
+	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)
 	}
 }

-// 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) {
+func TestEnrichMissingScopeError_AppendsExistingHint(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())

 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
@@ -436,145 +325,46 @@ func TestApplyNeedAuthorizationHint_AppendsExistingHint(t *testing.T) {
 	serviceCmd.AddCommand(shortcutCmd)
 	f.CurrentCommand = shortcutCmd

-	authErr := newAuthErrorWithNeedAuthMarker()
-	authErr.Hint = "existing hint"
-	applyNeedAuthorizationHint(f, authErr)
+	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 authErr.Hint != want {
-		t.Errorf("expected appended hint %q, got %q", want, authErr.Hint)
+	if exitErr.Detail.Hint != want {
+		t.Fatalf("expected appended hint %q, got %q", want, exitErr.Detail.Hint)
 	}
 }

-// TestEnrichPermissionError_CanonicalConvergence pins that the legacy
-// *output.ExitError dispatch path produces the same canonical Message + Hint
-// + ConsoleURL as the typed *errs.PermissionError dispatch path. Both paths
-// share errclass.CanonicalPermissionMessage / errclass.PermissionHint /
-// errclass.ConsoleURL — so a wire consumer cannot tell which path produced
-// the envelope.
-func TestEnrichPermissionError_CanonicalConvergence(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	cases := []struct {
-		name            string
-		larkCode        int
-		legacyErrType   string
-		wantMsgSubstrs  []string
-		wantHintSubstrs []string
-		wantConsoleURL  bool
-		wantNoAuthLogin bool // hint must not suggest `auth login`
-	}{
-		{
-			name:            "99991672 app_scope_not_applied",
-			larkCode:        99991672,
-			legacyErrType:   "permission",
-			wantMsgSubstrs:  []string{"access denied", "app cli_test", "drive:drive:read"},
-			wantHintSubstrs: []string{"developer console", "open.feishu.cn"},
-			wantConsoleURL:  true,
-			wantNoAuthLogin: true,
-		},
-		{
-			name:            "99991679 missing_scope",
-			larkCode:        99991679,
-			legacyErrType:   "permission",
-			wantMsgSubstrs:  []string{"unauthorized", "user authorization"},
-			wantHintSubstrs: []string{"lark-cli auth login"},
-		},
-		{
-			name:            "99991673 app_unavailable",
-			larkCode:        99991673,
-			legacyErrType:   "app_status",
-			wantMsgSubstrs:  []string{"unauthorized app", "app cli_test", "not properly installed"},
-			wantHintSubstrs: []string{"tenant admin", "install status"},
-		},
-		{
-			name:            "99991662 app_disabled",
-			larkCode:        99991662,
-			legacyErrType:   "app_status",
-			wantMsgSubstrs:  []string{"app cli_test", "not in use", "currently disabled"},
-			wantHintSubstrs: []string{"tenant admin", "re-enable"},
-		},
+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)
 	}
+	if strings.Contains(rootLong, "https://github.com/larksuite/cli#install-ai-agent-skills") {
+		t.Fatalf("root help should not reference the removed install-ai-agent-skills anchor, got:\n%s", rootLong)
+	}
+}

-	for _, tc := range cases {
+func TestConfigureFlagCompletions(t *testing.T) {
+	t.Cleanup(func() { cmdutil.SetFlagCompletionsEnabled(false) })
+
+	tests := []struct {
+		name         string
+		args         []string
+		wantDisabled bool
+	}{
+		{"plain command", []string{"im", "+send"}, true},
+		{"help flag", []string{"im", "--help"}, true},
+		{"no args", []string{}, true},
+		{"__complete request", []string{"__complete", "im", "+send", ""}, false},
+		{"completion subcommand", []string{"completion", "bash"}, false},
+	}
+	for _, tc := range tests {
 		t.Run(tc.name, func(t *testing.T) {
-			f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-				AppID: "cli_test", AppSecret: "s", Brand: core.BrandFeishu,
-			})
-			f.ResolvedIdentity = core.AsUser
-
-			// Mimic the wire shape ErrAPI produces: legacy *ExitError with
-			// Detail.Type populated by ClassifyLarkError, Detail.Detail
-			// carrying the permission_violations block so ExtractRequiredScopes
-			// can recover the missing scope.
-			scopeForDetail := "drive:drive:read"
-			exitErr := &output.ExitError{
-				Code: output.ExitAPI,
-				Detail: &output.ErrDetail{
-					Type:    tc.legacyErrType,
-					Code:    tc.larkCode,
-					Message: "upstream raw message — must be replaced",
-					Detail: map[string]interface{}{
-						"permission_violations": []interface{}{
-							map[string]interface{}{"subject": scopeForDetail},
-						},
-					},
-				},
-			}
-			enrichPermissionError(f, exitErr)
-
-			for _, sub := range tc.wantMsgSubstrs {
-				if !strings.Contains(exitErr.Detail.Message, sub) {
-					t.Errorf("Message %q missing substring %q", exitErr.Detail.Message, sub)
-				}
-			}
-			if exitErr.Detail.Message == "upstream raw message — must be replaced" {
-				t.Errorf("Message must be rewritten to canonical text; got upstream verbatim")
-			}
-			for _, sub := range tc.wantHintSubstrs {
-				if !strings.Contains(exitErr.Detail.Hint, sub) {
-					t.Errorf("Hint %q missing substring %q", exitErr.Detail.Hint, sub)
-				}
-			}
-			if tc.wantNoAuthLogin && strings.Contains(exitErr.Detail.Hint, "auth login") {
-				t.Errorf("Hint must not suggest `auth login` for this subtype; got %q", exitErr.Detail.Hint)
-			}
-			if tc.wantConsoleURL && exitErr.Detail.ConsoleURL == "" {
-				t.Error("ConsoleURL should be populated when missing scopes are present")
+			cmdutil.SetFlagCompletionsEnabled(tc.wantDisabled)
+			configureFlagCompletions(tc.args)
+			if got := !cmdutil.FlagCompletionsEnabled(); got != tc.wantDisabled {
+				t.Fatalf("FlagCompletionsEnabled() = %v, want disabled=%v", !got, tc.wantDisabled)
 			}
 		})
 	}
 }
-
-// TestEnrichPermissionError_SkipsUnrelatedTypes pins that an ExitError whose
-// Detail.Type is neither "permission" nor "app_status" is left untouched —
-// no Message rewrite, no Hint rewrite, no ConsoleURL injection.
-func TestEnrichPermissionError_SkipsUnrelatedTypes(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "cli_test", AppSecret: "s", Brand: core.BrandFeishu,
-	})
-	f.ResolvedIdentity = core.AsUser
-
-	for _, ty := range []string{"api_error", "validation", "rate_limit", "auth"} {
-		exitErr := &output.ExitError{
-			Code: output.ExitAPI,
-			Detail: &output.ErrDetail{
-				Type:    ty,
-				Code:    99991400,
-				Message: "untouched",
-				Hint:    "original hint",
-			},
-		}
-		enrichPermissionError(f, exitErr)
-		if exitErr.Detail.Message != "untouched" {
-			t.Errorf("type=%q: Message was rewritten unexpectedly: %q", ty, exitErr.Detail.Message)
-		}
-		if exitErr.Detail.Hint != "original hint" {
-			t.Errorf("type=%q: Hint was rewritten unexpectedly: %q", ty, exitErr.Detail.Hint)
-		}
-		if exitErr.Detail.ConsoleURL != "" {
-			t.Errorf("type=%q: ConsoleURL should not be injected; got %q", ty, exitErr.Detail.ConsoleURL)
-		}
-	}
-}
--- a/cmd/schema/schema.go
+++ b/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,59 @@ 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)

 	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 +468,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{} {
--- a/cmd/schema/schema_test.go
+++ b/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")
 	}
 }

--- a/cmd/service/service.go
+++ b/cmd/service/service.go
@@ -9,13 +9,11 @@ import (
 	"io"
 	"strings"

-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/client"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/credential"
-	"github.com/larksuite/cli/internal/errclass"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/registry"
 	"github.com/larksuite/cli/internal/util"
@@ -180,7 +178,6 @@ func NewCmdServiceMethodWithContext(ctx context.Context, f *cmdutil.Factory, spe
 	cmd.Flags().IntVar(&opts.PageLimit, "page-limit", 10, "max pages to fetch with --page-all (0 = unlimited)")
 	cmd.Flags().IntVar(&opts.PageDelay, "page-delay", 200, "delay in ms between pages")
 	cmd.Flags().StringVar(&opts.Format, "format", "json", "output format: json|ndjson|table|csv")
-	cmd.Flags().Bool("json", false, "shorthand for --format json")
 	cmd.Flags().StringVarP(&opts.JqExpr, "jq", "q", "", "jq expression to filter JSON output")
 	cmd.Flags().BoolVar(&opts.DryRun, "dry-run", false, "print request without executing")
 	if risk == "high-risk-write" {
@@ -225,7 +222,7 @@ func serviceMethodRun(opts *ServiceMethodOptions) error {
 	}

 	if opts.PageAll && opts.Output != "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--output and --page-all are mutually exclusive").WithParam("--output")
+		return output.ErrValidation("--output and --page-all are mutually exclusive")
 	}
 	if err := output.ValidateJqFlags(opts.JqExpr, opts.Output, opts.Format); err != nil {
 		return err
@@ -274,10 +271,7 @@ func serviceMethodRun(opts *ServiceMethodOptions) error {
 		fmt.Fprintf(f.IOStreams.ErrOut, "warning: unknown format %q, falling back to json\n", opts.Format)
 	}

-	// Scope-insufficient (99991679) and all other Lark API codes route through
-	// errclass.BuildAPIError via ac.CheckResponse, producing *errs.PermissionError
-	// with MissingScopes / Identity / ConsoleURL populated from the response.
-	checkErr := ac.CheckResponse
+	checkErr := scopeAwareChecker(scopes, opts.As.IsBot())

 	if opts.PageAll {
 		return servicePaginate(opts.Ctx, ac, request, format, opts.JqExpr, out, f.IOStreams.ErrOut,
@@ -286,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,
@@ -296,7 +290,6 @@ func serviceMethodRun(opts *ServiceMethodOptions) error {
 		ErrOut:      f.IOStreams.ErrOut,
 		FileIO:      f.ResolveFileIO(opts.Ctx),
 		CommandPath: opts.Cmd.CommandPath(),
-		Identity:    opts.As,
 		CheckError:  checkErr,
 	})
 }
@@ -322,7 +315,9 @@ func checkServiceScopes(ctx context.Context, cred *credential.CredentialProvider
 			}
 		}
 		if missing := auth.MissingScopes(result.Scopes, required); len(missing) > 0 {
-			return newPreflightMissingScopeError(string(config.Brand), config.AppID, string(identity), missing)
+			return output.ErrWithHint(output.ExitAuth, "missing_scope",
+				fmt.Sprintf("missing required scope(s): %s", strings.Join(missing, ", ")),
+				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.", strings.Join(missing, " ")))
 		}
 		return nil
 	}
@@ -342,24 +337,9 @@ func checkServiceScopes(ctx context.Context, cred *credential.CredentialProvider
 		}
 	}
 	recommended := registry.SelectRecommendedScope(scopes, "user")
-	return newPreflightMissingScopeError(string(config.Brand), config.AppID, string(identity), []string{recommended})
-}
-
-// newPreflightMissingScopeError constructs a PermissionError for the local
-// pre-flight scope check that converges byte-for-byte with the dispatcher's
-// BuildAPIError path. Uses the canonical helpers in internal/errclass so
-// Hint and Message stay in lock-step with the server-response classifier.
-// ConsoleURL is deliberately omitted: the dispatcher only sets it for
-// SubtypeAppScopeNotApplied (bot-perspective dev-action recovery), and this
-// pre-flight path is user-perspective SubtypeMissingScope whose recovery is
-// `lark-cli auth login --scope ...`, not a console deep-link.
-func newPreflightMissingScopeError(brand, appID, identity string, missing []string) *errs.PermissionError {
-	consoleURL := errclass.ConsoleURL(brand, appID, missing)
-	return errs.NewPermissionError(errs.SubtypeMissingScope,
-		"%s", errclass.CanonicalPermissionMessage(errs.SubtypeMissingScope, appID, missing, "")).
-		WithHint("%s", errclass.PermissionHint(missing, identity, errs.SubtypeMissingScope, consoleURL)).
-		WithMissingScopes(missing...).
-		WithIdentity(identity)
+	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))
 }

 // buildServiceRequest parses flags, builds the URL with path/query params, and returns a RawApiRequest.
@@ -381,7 +361,7 @@ func buildServiceRequest(opts *ServiceMethodOptions) (client.RawApiRequest, *cmd
 		return client.RawApiRequest{}, nil, err
 	}
 	if opts.Params == "-" && opts.Data == "-" {
-		return client.RawApiRequest{}, nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--params and --data cannot both read from stdin (-)").WithParam("--params")
+		return client.RawApiRequest{}, nil, output.ErrValidation("--params and --data cannot both read from stdin (-)")
 	}
 	params, err := cmdutil.ParseJSONMap(opts.Params, "--params", stdin, fileIO)
 	if err != nil {
@@ -398,14 +378,13 @@ func buildServiceRequest(opts *ServiceMethodOptions) (client.RawApiRequest, *cmd
 		}
 		val, ok := params[name]
 		if !ok || util.IsEmptyValue(val) {
-			return client.RawApiRequest{}, nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"missing required path parameter: %s", name).
-				WithHint("lark-cli schema %s", schemaPath).
-				WithParam(name)
+			return client.RawApiRequest{}, nil, output.ErrWithHint(output.ExitValidation, "validation",
+				fmt.Sprintf("missing required path parameter: %s", name),
+				fmt.Sprintf("lark-cli schema %s", schemaPath))
 		}
 		valStr := fmt.Sprintf("%v", val)
 		if err := validate.ResourceName(valStr, name); err != nil {
-			return client.RawApiRequest{}, nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam(name).WithCause(err)
+			return client.RawApiRequest{}, nil, output.ErrValidation("%s", err)
 		}
 		url = strings.Replace(url, "{"+name+"}", validate.EncodePathSegment(valStr), 1)
 		delete(params, name)
@@ -421,10 +400,9 @@ func buildServiceRequest(opts *ServiceMethodOptions) (client.RawApiRequest, *cmd
 		required, _ := p["required"].(bool)
 		isPaginationParam := opts.PageAll && (name == "page_token" || name == "page_size")
 		if required && !isPaginationParam && (!exists || util.IsEmptyValue(value)) {
-			return client.RawApiRequest{}, nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"missing required query parameter: %s", name).
-				WithHint("lark-cli schema %s", schemaPath).
-				WithParam(name)
+			return client.RawApiRequest{}, nil, output.ErrWithHint(output.ExitValidation, "validation",
+				fmt.Sprintf("missing required query parameter: %s", name),
+				fmt.Sprintf("lark-cli schema %s", schemaPath))
 		}
 		if exists && !util.IsEmptyValue(value) {
 			queryParams[name] = value
@@ -459,7 +437,7 @@ func buildServiceRequest(opts *ServiceMethodOptions) (client.RawApiRequest, *cmd
 				return client.RawApiRequest{}, nil, err
 			}
 			if _, ok := dataFields.(map[string]any); !ok {
-				return client.RawApiRequest{}, nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--data must be a JSON object when used with --file").WithParam("--data")
+				return client.RawApiRequest{}, nil, output.ErrValidation("--data must be a JSON object when used with --file")
 			}
 		}

@@ -496,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)
@@ -512,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 {
@@ -525,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)
--- a/cmd/service/service_test.go
+++ b/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{} {
@@ -766,21 +867,12 @@ func TestDetectFileFields(t *testing.T) {
 	}
 }

-func TestServiceMethod_JsonFlag_Accepted(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+// ── helpers ──

-	var captured *ServiceMethodOptions
-	cmd := NewCmdServiceMethod(f, driveSpec(),
-		map[string]interface{}{"description": "desc", "httpMethod": "GET"}, "list", "files",
-		func(opts *ServiceMethodOptions) error {
-			captured = opts
-			return nil
-		})
-	cmd.SetArgs([]string{"--json"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("--json should be accepted without error, got: %v", err)
-	}
-	if captured == nil {
-		t.Fatal("expected runF to be called")
+func isExitError(err error, target **output.ExitError) bool {
+	ee, ok := err.(*output.ExitError)
+	if ok && target != nil {
+		*target = ee
 	}
+	return ok
 }
--- a/cmd/unknown_subcommand_test.go
+++ b/cmd/unknown_subcommand_test.go
@@ -1,177 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd
-
-import (
-	"bytes"
-	"errors"
-	"strings"
-	"testing"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/internal/output"
-)
-
-func newGroupTree() (root, drive, files *cobra.Command) {
-	root = &cobra.Command{Use: "lark-cli"}
-	drive = &cobra.Command{Use: "drive", Short: "drive ops"}
-	root.AddCommand(drive)
-
-	search := &cobra.Command{Use: "+search", RunE: func(*cobra.Command, []string) error { return nil }}
-	upload := &cobra.Command{Use: "+upload", RunE: func(*cobra.Command, []string) error { return nil }}
-	hidden := &cobra.Command{Use: "+secret", Hidden: true, RunE: func(*cobra.Command, []string) error { return nil }}
-	drive.AddCommand(search, upload, hidden)
-
-	files = &cobra.Command{Use: "files", Short: "files ops"}
-	drive.AddCommand(files)
-	files.AddCommand(&cobra.Command{Use: "list", RunE: func(*cobra.Command, []string) error { return nil }})
-
-	return root, drive, files
-}
-
-func TestInstallUnknownSubcommandGuard_InstallsOnGroupsOnly(t *testing.T) {
-	root, drive, files := newGroupTree()
-	leaf := drive.Commands()[0] // +search
-
-	installUnknownSubcommandGuard(root)
-
-	if drive.RunE == nil {
-		t.Error("drive should have RunE installed")
-	}
-	if files.RunE == nil {
-		t.Error("files should have RunE installed")
-	}
-	if err := leaf.RunE(leaf, []string{"unexpected-arg"}); err != nil {
-		t.Errorf("leaf +search RunE should be untouched, got error %v", err)
-	}
-}
-
-func TestInstallUnknownSubcommandGuard_PreservesExistingRunE(t *testing.T) {
-	root := &cobra.Command{Use: "lark-cli"}
-	called := false
-	custom := &cobra.Command{
-		Use: "custom",
-		RunE: func(*cobra.Command, []string) error {
-			called = true
-			return nil
-		},
-	}
-	// Child makes custom a "group" command, exercising the Run/RunE override guard.
-	custom.AddCommand(&cobra.Command{Use: "leaf", RunE: func(*cobra.Command, []string) error { return nil }})
-	root.AddCommand(custom)
-
-	installUnknownSubcommandGuard(root)
-
-	if err := custom.RunE(custom, nil); err != nil {
-		t.Fatalf("preserved RunE returned error: %v", err)
-	}
-	if !called {
-		t.Error("guard must not overwrite a command that already defines Run/RunE")
-	}
-}
-
-func TestUnknownSubcommandRunE_NoArgsShowsHelp(t *testing.T) {
-	_, drive, _ := newGroupTree()
-	installUnknownSubcommandGuard(drive.Root())
-
-	var buf bytes.Buffer
-	drive.SetOut(&buf)
-	drive.SetErr(&buf)
-
-	if err := drive.RunE(drive, nil); err != nil {
-		t.Fatalf("expected no-args invocation to succeed, got: %v", err)
-	}
-	if !strings.Contains(buf.String(), "drive ops") {
-		t.Errorf("expected help output to include the command's Short, got:\n%s", buf.String())
-	}
-}
-
-func TestUnknownSubcommandRunE_UnknownReturnsStructuredError(t *testing.T) {
-	_, drive, _ := newGroupTree()
-	installUnknownSubcommandGuard(drive.Root())
-
-	err := drive.RunE(drive, []string{"+bogus"})
-	if err == nil {
-		t.Fatal("expected error for unknown subcommand")
-	}
-
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T", err)
-	}
-	if exitErr.Code != output.ExitValidation {
-		t.Errorf("expected exit code %d, got %d", output.ExitValidation, exitErr.Code)
-	}
-	if exitErr.Detail == nil {
-		t.Fatal("expected ExitError to carry Detail")
-	}
-	if exitErr.Detail.Type != "unknown_subcommand" {
-		t.Errorf("expected Detail.Type=unknown_subcommand, got %q", exitErr.Detail.Type)
-	}
-	if !strings.Contains(exitErr.Detail.Message, `"+bogus"`) {
-		t.Errorf("message should echo the unknown token, got %q", exitErr.Detail.Message)
-	}
-	if !strings.Contains(exitErr.Detail.Hint, "+search") || !strings.Contains(exitErr.Detail.Hint, "+upload") {
-		t.Errorf("hint should list available shortcuts, got %q", exitErr.Detail.Hint)
-	}
-	if strings.Contains(exitErr.Detail.Hint, "+secret") {
-		t.Error("hidden commands must not appear in the hint")
-	}
-
-	detail, ok := exitErr.Detail.Detail.(map[string]any)
-	if !ok {
-		t.Fatalf("expected Detail.Detail to be map[string]any, got %T", exitErr.Detail.Detail)
-	}
-	if detail["unknown"] != "+bogus" {
-		t.Errorf("detail.unknown should be +bogus, got %v", detail["unknown"])
-	}
-	if detail["command_path"] != "lark-cli drive" {
-		t.Errorf("detail.command_path should be %q, got %v", "lark-cli drive", detail["command_path"])
-	}
-	available, ok := detail["available"].([]string)
-	if !ok {
-		t.Fatalf("detail.available should be []string, got %T", detail["available"])
-	}
-	if len(available) != 3 {
-		t.Errorf("expected 3 available entries (hidden excluded), got %d: %v", len(available), available)
-	}
-}
-
-func TestUnknownSubcommandRunE_NestedResourceGroup(t *testing.T) {
-	root, _, files := newGroupTree()
-	installUnknownSubcommandGuard(root)
-
-	err := files.RunE(files, []string{"bogus"})
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError on nested group, got %T", err)
-	}
-	if exitErr.Detail.Detail.(map[string]any)["command_path"] != "lark-cli drive files" {
-		t.Errorf("command_path should reflect the nested resource, got %v",
-			exitErr.Detail.Detail.(map[string]any)["command_path"])
-	}
-}
-
-func TestAvailableSubcommandNames_FiltersHelpAndCompletion(t *testing.T) {
-	root := &cobra.Command{Use: "lark-cli"}
-	root.AddCommand(
-		&cobra.Command{Use: "alpha", RunE: func(*cobra.Command, []string) error { return nil }},
-		&cobra.Command{Use: "help", RunE: func(*cobra.Command, []string) error { return nil }},
-		&cobra.Command{Use: "completion", RunE: func(*cobra.Command, []string) error { return nil }},
-		&cobra.Command{Use: "beta", Hidden: true, RunE: func(*cobra.Command, []string) error { return nil }},
-		&cobra.Command{Use: "gamma", RunE: func(*cobra.Command, []string) error { return nil }},
-	)
-
-	got := availableSubcommandNames(root)
-	want := []string{"alpha", "gamma"}
-	if len(got) != len(want) {
-		t.Fatalf("expected %v, got %v", want, got)
-	}
-	for i, name := range want {
-		if got[i] != name {
-			t.Errorf("availableSubcommandNames[%d] = %q, want %q", i, got[i], name)
-		}
-	}
-}
--- a/cmd/update/update.go
+++ b/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 {
@@ -114,7 +111,6 @@ Use --check to only check for updates without installing.`,
 	cmd.Flags().BoolVar(&opts.JSON, "json", false, "structured JSON output")
 	cmd.Flags().BoolVar(&opts.Force, "force", false, "force reinstall even if already up to date")
 	cmd.Flags().BoolVar(&opts.Check, "check", false, "only check for updates, do not install")
-	cmdutil.SetRisk(cmd, "high-risk-write")

 	return cmd
 }
@@ -124,9 +120,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 +136,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 +184,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 +209,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 +287,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 +327,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 +355,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 +363,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 +386,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())
 	}
 }
--- a/cmd/update/update_test.go
+++ b/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
-}
--- a/errs/ERROR_CONTRACT.md
+++ b/errs/ERROR_CONTRACT.md
@@ -1,620 +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` — including `SecurityPolicyError`,
-   which exits `6` via `CategoryPolicy`. Unmigrated `*output.ExitError`
-   producers still carry a hand-set `Code` until they finish migrating.
-   `output.ErrBare(code)` is the lone exception: a deliberate
-   predicate-command signal that bypasses the envelope (see
-   **Predicate commands** below).
-
-## 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` |
-
-`SecurityPolicyError` renders through the same typed envelope as every
-other category. `error.type` is `"policy"`, `error.subtype` is one of
-`challenge_required` / `access_denied`, and process exit is `6` via
-`CategoryPolicy`. The legacy `auth_error` envelope at exit `1` has been
-retired.
-
-## 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:
-     ├─ output.ErrBare(code)      → no envelope (stdout already written); exit = code
-     ├─ typed (errs.ProblemOf)    → typed JSON envelope; exit = ExitCodeOf(err)
-     │     (includes *errs.SecurityPolicyError → policy envelope, exit 6)
-     ├─ *core.ConfigError         → promoted to typed via errcompat ↑
-     ├─ *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.
-
-### Predicate commands (`output.ErrBare`)
-
-A small class of commands is **predicates**: they answer a yes/no
-question and signal the answer through the shell exit code so callers
-can write `if cmd; then ... fi`. `lark-cli auth check` is the canonical
-example — its `README` contract is `exit 0 = ok, 1 = missing`.
-
-These commands deliberately:
-
-1. write a structured JSON answer to **stdout** themselves, and
-2. return `output.ErrBare(exitCode)` to communicate the exit code to
-   the dispatcher without producing a `stderr` envelope.
-
-`output.ErrBare` is **not** an error in the typed-envelope sense — it
-carries no category, subtype, or message. It is a one-bit output-
-control signal that lives outside the contract for the same reason
-`grep -q` / `diff` / `systemctl is-active` set non-zero exit codes
-without printing anything to stderr: pollution of stderr by a
-predicate's negative answer would break `2>/dev/null` log hygiene in
-caller scripts.
-
-New code should not reach for `ErrBare` unless the command is
-genuinely a predicate. Anything carrying recoverable error content
-belongs in a typed `*errs.XxxError` — or, for a batch result, in the
-partial-failure outcome below.
-
-### Partial failure (batch / multi-status)
-
-A batch command (e.g. `drive +push` / `+pull` / `+sync`) that processes
-many items can finish in a third state, neither full success nor a single
-error: some items succeeded and some failed. Its primary output is the
-per-item result, so it does **not** belong in a `stderr` error envelope.
-
-Such a command returns `runtime.OutPartialFailure(data, meta)`, which:
-
-1. writes the full result to **stdout** as an `ok:false` envelope — the
-   summary and every per-item outcome (succeeded *and* failed) stay
-   machine-readable, exactly as a successful `Out(...)` would carry them,
-   but with `ok` honestly reporting failure; and
-2. returns `*output.PartialFailureError`, a typed exit signal the
-   dispatcher maps to a non-zero exit code while writing nothing further
-   to `stderr`.
-
-This is distinct from `ErrBare` (a predicate's one-bit answer) and from a
-typed `*errs.XxxError` (a `stderr` error envelope): a partial failure is a
-*result*, reported on stdout, that also failed. Consumers branch on
-`ok == false` and then read `data.summary` / `data.items[]`.
-
-## 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
-
-The canonical producer surface is the **builder API in `errs/types.go`** (per type: struct + `NewXxxError` + chained `WithX` setters live in one place):
-each `NewXxxError(subtype, format, args...)` locks `Category` at the
-constructor name, requires `Subtype` + `Message` positionally, and exposes
-optional fields via chained `.WithX(...)` setters. Struct literals remain
-legal for framework dynamic paths (e.g. classifier fanout) but the lint
-`CheckTypedErrorCompleteness` still requires `Category` + `Subtype` +
-`Message` on any literal it sees.
-
-| Situation | Use |
-|-----------|-----|
-| Bad user input | `errs.NewValidationError(subtype, msg).WithParam("--flag")` |
-| Login required | `errs.NewAuthenticationError(errs.SubtypeTokenMissing, msg)` |
-| Token lacks scope | `errclass.BuildAPIError(resp, ctx)` |
-| Local config missing | `errs.NewConfigError(errs.SubtypeNotConfigured, msg)` |
-| Transport failure | `errs.NewNetworkError(errs.SubtypeNetworkTimeout, msg).WithCause(err)` (subtype: `timeout` / `tls` / `dns` / `server_error` / `transport`) |
-| Lark API error | `errclass.BuildAPIError(resp, ctx)` |
-| SDK / decode bug | `errs.NewInternalError(errs.SubtypeSDKError, msg).WithCause(err)` |
-| Policy block | `errs.NewSecurityPolicyError(subtype, msg).WithChallengeURL(url)` or `errs.NewContentSafetyError(subtype, msg).WithRules(...)` |
-| Needs `--yes` | `errs.NewConfirmationRequiredError(risk, action, msg)` |
-
-### 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` retains hand-set codes until removal;
-`SecurityPolicyError` retains a hand-set code on main until the framework
-migration PR retires the carve-out — see **Migration**.)
-
-#### 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.NewNetworkError(errs.SubtypeNetworkTransport,
-    "request to /open-apis failed after 3 retries").
-    WithHint("check connectivity and retry; set --log-level debug if it persists").
-    WithCause(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
-
-Prefer the **builder API**. The constructor pins `Category` + `Subtype` +
-`Message`, the chained setters fill optional fields, and the resulting
-value retains its concrete `*XxxError` pointer through the chain so
-type-specific setters remain reachable to the end:
-
-```go
-return errs.NewValidationError(errs.SubtypeInvalidArgument,
-    "--data must be a valid JSON object: %v", parseErr).
-    WithParam("--data")
-```
-
-Why builder over struct literal:
-
- `Category` is locked at the function name — caller cannot mis-specify it
- `Subtype` and `Message` are positional arguments — `go build` rejects
-  the call site if either is missing
- The chain reads top-down: required identity first, optional fields after
- Message is `fmt.Sprintf`-formatted from `(format, args...)`, matching
-  `fmt.Errorf` muscle memory and avoiding a separate `Sprintf` line
-
-Struct literals remain legal — `CheckTypedErrorCompleteness` continues to
-enforce `Category` + `Subtype` + `Message` on any literal it sees — and
-the framework classifier (`internal/errclass/classify.go`) still uses
-them on the dynamic dispatch path where a `Problem` value is composed
-once and wrapped per Category branch. Outside that pattern, new code
-should reach for the builder.
-
-Legacy helpers (`output.ErrValidation`, `output.ErrAuth`, `output.ErrNetwork`)
-remain callable during migration but are `// Deprecated:` — new code goes
-through the builder.
-
-#### 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 (builder form):
-
-```go
-Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
-    duration := runtime.Int("duration-minutes")
-    if duration < 1 || duration > 1440 {
-        return errs.NewValidationError(errs.SubtypeInvalidArgument,
-            "--duration-minutes must be between 1 and 1440, got %d", duration).
-            WithHint("pass a value in [1, 1440]").
-            WithParam("--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.NewValidationError(errs.SubtypeInvalidArgument, "invalid --data: %v", jsonErr).WithCause(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` under the right Category block.
-   Subtypes are framework-shared — service-specific Subtypes are an
-   anti-pattern (the wire `code` field already identifies the source
-   service; Subtype encodes cross-service semantics like `not_found`,
-   `quota_exceeded`).
-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. In `errs/types.go`, add a new section with: the struct embedding `errs.Problem`, a nil-receiver-safe `Unwrap()` if it carries `Cause`, a `NewXxxError(subtype, format, args...)` constructor, and one chained `WithX` setter per extension field.
-2. Add an `IsXxx` predicate in `errs/predicates.go`.
-3. Add a wire-format pin in `errs/marshal_test.go` and a builder-chain pin in `errs/types_builder_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
-
-**Strategy shift (2026-05-26).** The original plan (`docs/design/errors-refactor/spec.md` v2.12 §9) was a centrally-driven 4-PR rollout — framework → auth domain → multi-pilot → full-repo + legacy removal. That plan is **superseded** by a hybrid model: framework owner ships framework-level hardening (including a typed `*errs.*Error` migration of `internal/**`) as one focused PR; business-domain typed migration is **self-service** via [`docs/errors-guide.md`](../docs/errors-guide.md) and the builder API, with no central sweep timeline.
-
-Why the shift: 800+ legacy call sites split across 8+ business domains do not all share a single reviewer's bandwidth, and the contract is now expressive enough that each domain owner can migrate their own code from the guide without coordinating with framework owner.
-
-### Current state
-
-1. **Framework slice — ✅ shipped (PR #984).** The `errs/` typed taxonomy, classifier (`internal/errclass`), promotion stub (`internal/errcompat`, passthrough), dispatcher hook (`WriteTypedErrorEnvelope`), and the `lint/errscontract` AST guards. 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 framework migration can plug in without re-architecting.
-
-2. **Builder API — ✅ shipped (this branch).** `errs/types.go` adds the canonical producer surface (`errs.NewXxxError(subtype, format, args...).WithX(...)`) for all 10 typed types, alongside each struct declaration. Constructor signature pins `Category` (via function name) and `Subtype` + `Message` (positional), so the producer cannot mis-specify any of the three identity fields. Optional fields chain through `.WithX(...)` setters that preserve the concrete pointer type.
-
-### Next: framework migration PR (planned)
-
-A single PR consolidates the work the original §9 spec split across PRs 2–4 — restricted to framework code, no business sweep:
-
- **Migrate `internal/**` typed construction to the builder API.** ~16 call sites in `internal/errclass/classify.go` (BuildAPIError fanout), `internal/auth/transport.go` (SecurityPolicy), `internal/auth/uat_client.go`, `internal/errcompat/promote*.go`, `internal/client/client.go`, `internal/client/api_errors.go`.
- **Land the framework-side semantic changes** previously scoped to spec §9 PR 2: `SecurityPolicyError` exit `1→6`, `WrapDoAPIError` typed (`*NetworkError` with subtype timeout/tls/dns/server_error/transport, `*InternalError` for JSON-decode), `WrapJSONResponseParseError` typed, `errcompat.PromoteConfigError` real Type routing, `PromoteAuthError` helper + dispatcher wiring, 10 credential Lark codes registered in codeMeta, 99991543 config classification, `resolveAccessToken` typed `*AuthenticationError`, `BuildAPIError` filling `*PermissionError.MissingScopes` / `Identity` / `ConsoleURL`, deletion of `scopeAwareChecker`.
- **Add `forbidigo` rule** banning `output.Err*` constructors in `shortcuts/**` and `cmd/**` (mirrors the contract that new business code must use the builder).
- **CHANGELOG** lists the resulting ~10 shell-exit-code shifts in one release entry (vs the spec §1 spread of 11 — the remaining one site lives in `task` business code).
-
-### Business-domain migration (self-service, no central timeline)
-
-Each business package migrates its own `output.Err*` call sites to the builder when convenient — typically batched within one domain. The guide at [`docs/errors-guide.md`](../docs/errors-guide.md) walks owners through the 8 typical error modes (validation / authorization / authentication / config / network / api / internal / policy) with real `file:line` examples from main. The three-layer extension model (add Subtype / add field / add Category) handles cases the existing taxonomy does not cover.
-
-Helper assertions accept both shapes during migration (see `shortcuts/mail/mail_shortcut_validation_test.go` `assertValidationError`) so domain migrations stay green incrementally.
-
-### Legacy removal
-
-Deferred until business migration completion approaches the asymptote. `Errorf`, `ErrAPI`, `ErrAuth`, `ErrWithHint`, `ErrBare`, `ClassifyLarkError`, `ErrDetail`, `ExitError`, and `ErrorEnvelope` are `// Deprecated:` today and stay callable. No fixed removal date.
-
-### Before / after at a call site
-
-```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)
-```
-
-```go
-// before (legacy validation)
-return output.ErrValidation("--duration-minutes must be between 1 and 1440")
-
-// after (builder)
-return errs.NewValidationError(errs.SubtypeInvalidArgument,
-    "--duration-minutes must be between 1 and 1440, got %d", duration).
-    WithParam("--duration-minutes")
-```
-
-## 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`.
--- a/errs/category.go
+++ b/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"
-)
--- a/errs/category_test.go
+++ b/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)
-			}
-		})
-	}
-}
--- a/errs/doc.go
+++ b/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
--- a/errs/internal_carrier.go
+++ b/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
-}
--- a/errs/marshal_test.go
+++ b/errs/marshal_test.go
@@ -1,296 +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 TestPermissionError_RequestedGrantedMarshal(t *testing.T) {
-	err := NewPermissionError(SubtypeMissingScope, "partial grant").
-		WithRequestedScopes("docx:document", "im:message:send").
-		WithGrantedScopes("docx:document").
-		WithMissingScopes("im:message:send")
-
-	b, e := json.Marshal(err)
-	if e != nil {
-		t.Fatal(e)
-	}
-	got := string(b)
-	for _, want := range []string{
-		`"requested_scopes":["docx:document","im:message:send"]`,
-		`"granted_scopes":["docx:document"]`,
-		`"missing_scopes":["im:message:send"]`,
-	} {
-		if !strings.Contains(got, want) {
-			t.Errorf("envelope missing %s\nactual: %s", want, got)
-		}
-	}
-}
-
-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: SubtypeNetworkTimeout, Message: "dial timeout"},
-	}
-	b, _ := json.Marshal(ne)
-	s := string(b)
-	for _, want := range []string{
-		`"type":"network"`,
-		`"subtype":"timeout"`,
-	} {
-		if !strings.Contains(s, want) {
-			t.Errorf("missing %q in %s", want, s)
-		}
-	}
-	if strings.Contains(s, `"cause"`) {
-		t.Errorf("cause field should no longer be on the wire; got %s", s)
-	}
-}
-
-func TestAPIError_MarshalJSON(t *testing.T) {
-	ae := &APIError{
-		Problem: Problem{Category: CategoryAPI, Subtype: SubtypeRateLimit, Code: 99991400, Message: "slow", Retryable: true},
-	}
-	b, _ := json.Marshal(ae)
-	s := string(b)
-	for _, want := range []string{
-		`"type":"api"`,
-		`"subtype":"rate_limit"`,
-		`"code":99991400`,
-		`"retryable":true`,
-	} {
-		if !strings.Contains(s, want) {
-			t.Errorf("missing %q in %s", want, s)
-		}
-	}
-}
-
-// TestProblem_MarshalJSON_Troubleshooter pins the upstream Lark API
-// troubleshooter URL (resp.error.troubleshooter) surfacing on the wire under
-// "troubleshooter". Carried via Problem so any typed error that embeds it
-// inherits the field — populated by errclass.BuildAPIError before the
-// category switch.
-func TestProblem_MarshalJSON_Troubleshooter(t *testing.T) {
-	ae := &APIError{
-		Problem: Problem{
-			Category:       CategoryAPI,
-			Subtype:        SubtypeUnknown,
-			Code:           99991400,
-			Message:        "x",
-			Troubleshooter: "https://open.feishu.cn/document/troubleshoot/abc",
-		},
-	}
-	b, _ := json.Marshal(ae)
-	s := string(b)
-	if !strings.Contains(s, `"troubleshooter":"https://open.feishu.cn/document/troubleshoot/abc"`) {
-		t.Errorf("missing troubleshooter in %s", s)
-	}
-
-	// Absent Troubleshooter must omit the wire key.
-	bare := &APIError{Problem: Problem{Category: CategoryAPI, Message: "x"}}
-	b2, _ := json.Marshal(bare)
-	if strings.Contains(string(b2), `"troubleshooter"`) {
-		t.Errorf("absent Troubleshooter must omit wire key; got %s", string(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)
-		}
-	}
-}
-
-// Pin per-Subtype symmetry: SubtypeAccessDenied must serialize the same
-// envelope shape as SubtypeChallengeRequired so callers can switch on
-// subtype without conditional field probing. The constructor + builder
-// path (mirroring how callsites actually construct these) is exercised
-// here rather than the struct literal, since SubtypeAccessDenied is the
-// path threaded through cmd/* sites that surface policy-deny outcomes.
-func TestSecurityPolicyError_MarshalJSON_AccessDenied(t *testing.T) {
-	err := NewSecurityPolicyError(SubtypeAccessDenied, "user denied").
-		WithChallengeURL("https://chal.example/2")
-
-	b, e := json.Marshal(err)
-	if e != nil {
-		t.Fatal(e)
-	}
-	got := string(b)
-	for _, want := range []string{
-		`"type":"policy"`,
-		`"subtype":"access_denied"`,
-		`"challenge_url":"https://chal.example/2"`,
-	} {
-		if !strings.Contains(got, want) {
-			t.Errorf("envelope missing %s\nactual: %s", want, got)
-		}
-	}
-}
-
-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)
-		}
-	}
-}
--- a/errs/predicates.go
+++ b/errs/predicates.go
@@ -1,97 +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) }
-
-// IsTyped reports whether err is or wraps any of the typed *errs.* errors
-// in this package (i.e. implements the TypedError interface). Used by call
-// sites that need to pass already-classified errors through unchanged
-// instead of blanket-rewrapping them as a different category.
-func IsTyped(err error) bool {
-	var t TypedError
-	return errors.As(err, &t)
-}
--- a/errs/predicates_test.go
+++ b/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)
-			}
-		})
-	}
-}
--- a/errs/problem.go
+++ b/errs/problem.go
@@ -1,43 +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.
-//   - Troubleshooter is the upstream Lark API's diagnostic URL (resp.error.
-//     troubleshooter). Carried universally so any classified error can surface
-//     it; populated by errclass.BuildAPIError when the upstream response
-//     includes it, otherwise absent.
-//   - 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"`
-	Troubleshooter string   `json:"troubleshooter,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 }
--- a/errs/problem_test.go
+++ b/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")
-	}
-}
--- a/errs/subtypes.go
+++ b/errs/subtypes.go
@@ -1,90 +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)
-	SubtypeFailedPrecondition Subtype = "failed_precondition" // request is valid but the system/resource state is not in the state required to execute; caller must change state (not retry) — e.g. ambiguous remote mapping (gRPC FAILED_PRECONDITION 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
-	SubtypeAppDisabled            Subtype = "app_disabled"             // app currently disabled in this tenant (was installed/enabled before)
-	SubtypePermissionDenied       Subtype = "permission_denied"        // resource-level permission denial (authenticated but lacks rights for this resource, HTTP 403 / gRPC PERMISSION_DENIED alignment)
-)
-
-// 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"    // fallback when no more-specific network subtype matches
-	SubtypeNetworkTimeout   Subtype = "timeout"      // dial / read timeout
-	SubtypeNetworkTLS       Subtype = "tls"          // TLS handshake / cert failure
-	SubtypeNetworkDNS       Subtype = "dns"          // DNS resolution failure
-	SubtypeNetworkServer    Subtype = "server_error" // upstream HTTP 5xx
-)
-
-// 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
-	SubtypeNotFound          Subtype = "not_found"          // referenced resource does not exist (HTTP 404 alignment)
-	SubtypeServerError       Subtype = "server_error"       // upstream server-side transient error (HTTP 5xx alignment, retryable)
-	SubtypeQuotaExceeded     Subtype = "quota_exceeded"     // resource quota / collection size limit reached (assignees, followers, members, etc.)
-	SubtypeAlreadyExists     Subtype = "already_exists"     // idempotency violation: resource already exists in target state
-)
-
-// 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
-	SubtypeFileIO          Subtype = "file_io"          // local file I/O failure (mkdir / write / read)
-	SubtypeStorage         Subtype = "storage"          // local persistence failure (e.g. config file save)
-	// Generic untyped error lifted to InternalError uses SubtypeUnknown.
-)
-
-// CategoryConfirmation subtypes
-const (
-	SubtypeConfirmationRequired Subtype = "confirmation_required" // high-risk operation needs explicit --yes
-)
--- a/Show More
+++ b/Show More