docs: clarify doc block insert ordering

* feat(mail): auto-attach default signature on send/reply/forward

- Add exported PlainTextFromHTML wrapper in draft/htmltext.go
- Add DefaultSendID/DefaultReplyID in signature/provider.go
- Add noSignatureFlag, autoResolveSignatureID, validateNoSignatureConflict,
  injectPlainTextSignature in signature_compose.go; remove validateSignatureWithPlainText
- mail_send, mail_draft_create: add --no-signature flag, auto-resolve default
  signature when no --signature-id given, inject plain-text sig in plain-text branch
- mail_reply, mail_reply_all, mail_forward: same flag/validate changes + timing fix
  (resolveSignature moved to after senderEmail is finalized)
- Update 5 reference docs: add --no-signature row, update --plain-text and
  --signature-id descriptions

---------

Co-authored-by: xzcong0820 <278082089+xzcong0820@users.noreply.github.com>

.github/CODEOWNERS

@@ -0,0 +1,30 @@
+/internal/ @liangshuo-1
+
+# Last match wins: existing domains below are exempt, only new skills/ entries need review.
+/skills/ @liangshuo-1
+/skills/lark-approval/
+/skills/lark-apps/
+/skills/lark-attendance/
+/skills/lark-base/
+/skills/lark-calendar/
+/skills/lark-contact/
+/skills/lark-doc/
+/skills/lark-drive/
+/skills/lark-event/
+/skills/lark-im/
+/skills/lark-mail/
+/skills/lark-markdown/
+/skills/lark-minutes/
+/skills/lark-okr/
+/skills/lark-openapi-explorer/
+/skills/lark-shared/
+/skills/lark-sheets/
+/skills/lark-skill-maker/
+/skills/lark-slides/
+/skills/lark-task/
+/skills/lark-vc/
+/skills/lark-vc-agent/
+/skills/lark-whiteboard/
+/skills/lark-wiki/
+/skills/lark-workflow-meeting-summary/
+/skills/lark-workflow-standup-report/

.github/pull_request_template.md

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

.github/workflows/ci.yml

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

.gitignore

@@ -1,5 +1,5 @@
 # Build output
-/lark-cli
+/lark-cli*
 .cache/
 dist/
 bin/
@@ -35,6 +35,8 @@ tests/mail/reports/
 # Generated / test artifacts
 .hammer/
 .lark-slides/
+/notes/
+/minutes/
 internal/registry/meta_data.json
 cmd/api/download.bin
 app.log
@@ -42,3 +44,5 @@ app.log
 /server-demo
 .tmp/
 cover*.out
+
+lark-env.sh

.golangci.yml

@@ -49,18 +49,47 @@ linters:
           - gocritic
           - depguard
           - forbidigo
-      - path-except: (shortcuts/|internal/)
+      # 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/)
         linters:
           - forbidigo
       - path: internal/vfs/
         linters:
           - forbidigo
-      # The shortcuts-no-raw-http forbidigo rule below is shortcuts-only;
-      # internal/ legitimately wraps raw HTTP for the client / credential layer.
+      # internal/gen build-time generators (standalone `package main` run via
+      # go:generate) are not shortcut runtime code — no ctx/runtime/framework —
+      # so the shortcut forbidigo bans don't apply. Going "compliant" is also
+      # impossible here: a structured error return needs os.Exit (also banned),
+      # and the vfs.Xxx() alternative is blocked by depguard shortcuts-no-vfs.
+      - path: shortcuts/.*/internal/gen/
+        linters:
+          - forbidigo
+      # shortcuts-no-raw-http is shortcuts-only; internal/ 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/apps/|shortcuts/base/|shortcuts/calendar/|shortcuts/contact/|shortcuts/doc/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/markdown/|shortcuts/minutes/|shortcuts/okr/|shortcuts/sheets/|shortcuts/slides/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|shortcuts/wiki/|internal/event/consume/|cmd/event/|events/|shortcuts/event/)
+        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/apps/|shortcuts/base/|shortcuts/calendar/|shortcuts/contact/|shortcuts/doc/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/markdown/|shortcuts/minutes/|shortcuts/okr/|shortcuts/sheets/|shortcuts/slides/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|shortcuts/wiki/|shortcuts/common/mcp_client\.go|cmd/event/|events/|shortcuts/event/)
+        text: errs-no-bare-wrap
+        linters:
+          - forbidigo
+      # errs-no-legacy-helper enforced on domains whose shared validation/save
+      # helpers have migrated to typed final errors.
+      - path-except: (shortcuts/apps/|shortcuts/base/|shortcuts/calendar/|shortcuts/contact/|shortcuts/doc/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/markdown/|shortcuts/minutes/|shortcuts/okr/|shortcuts/sheets/|shortcuts/slides/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|shortcuts/wiki/|cmd/event/|events/|shortcuts/event/)
+        text: errs-no-legacy-helper
+        linters:
+          - forbidigo
 
   settings:
     depguard:
@@ -79,6 +108,28 @@ 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 migrated domains ──
+        # These helpers emit legacy output.Err* / bare error shapes or drop
+        # typed metadata such as Param/Cause. Migrated domains must use typed
+        # common replacements or local typed helpers instead.
+        - pattern: (common\.FlagErrorf|common\.RejectDangerousChars|common\.WrapInputStatError|common\.WrapSaveErrorByCategory)\b
+          msg: >-
+            [errs-no-legacy-helper] these shared helpers emit legacy or
+            metadata-poor error shapes. Use typed common replacements, typed
+            errs.NewXxxError builders, or domain-local typed helpers.
+        # ── 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

.goreleaser.yml

@@ -17,6 +17,7 @@ builds:
     goarch:
       - amd64
       - arm64
+      - riscv64
 
 archives:
   - name_template: "lark-cli-{{ .Version }}-{{ .Os }}-{{ .Arch }}"

AGENTS.md

@@ -11,7 +11,7 @@
 
 ```bash
 make build          # Build (runs fetch_meta first)
-make unit-test      # Required before PR (runs with -race)
+make unit-test      # Required before PR (runs with -race where supported, e.g. amd64/arm64)
 make test           # Full: vet + unit + integration
 ```
 
@@ -75,7 +75,31 @@ The one rule to internalize: **every error message you write will be parsed by a
 
 ### Structured errors in commands
 
-`RunE` functions must return `output.Errorf` / `output.ErrWithHint` — never bare `fmt.Errorf`. AI agents parse stderr as JSON; bare errors break this contract.
+Command-facing failures must be typed `errs.*` errors — never the legacy `output.Err*` helpers and never a final bare `fmt.Errorf`. AI agents parse the stderr envelope's `type` / `subtype` / `param` / `hint` fields to decide their next action; the full taxonomy lives in `errs/ERROR_CONTRACT.md`.
+
+Picking a constructor:
+
+| Failure | Constructor |
+|---------|-------------|
+| User flag/arg fails validation | `errs.NewValidationError(errs.SubtypeInvalidArgument, ...).WithParam("--flag")` |
+| Valid request, wrong system state | `errs.NewValidationError(errs.SubtypeFailedPrecondition, ...).WithHint(...)` |
+| Lark API returned `code != 0` | `runtime.CallAPITyped` (shortcuts) / `errclass.BuildAPIError` (raw responses) — never hand-build |
+| Network / transport failure | `errs.NewNetworkError(errs.SubtypeNetworkTransport, ...)` |
+| Local file I/O failure | `errs.NewInternalError(errs.SubtypeFileIO, ...)` — validate the path first (`validate.SafeInputPath` / `SafeOutputPath`) and use `vfs.*` |
+| Unclassified lower-layer error as final | `errs.NewInternalError(errs.SubtypeUnknown, ...).WithCause(err)` |
+| Lower layer already returned a typed error | pass it through unchanged — re-wrapping downgrades its classification |
+
+Signatures that are easy to guess wrong:
+
+- `runtime.CallAPITyped(method, url string, params map[string]interface{}, data interface{}) (map[string]interface{}, error)` — it performs the HTTP request itself and classifies `code != 0` into a typed error; just return the error it gives you.
+- Typed pass-through check: `if _, ok := errs.ProblemOf(err); ok { return err }` — `ProblemOf` returns `(*errs.Problem, bool)`, not a nilable pointer.
+- `.WithParam` exists only on `*errs.ValidationError`. `InternalError` / `NetworkError` have no param field — file or endpoint context goes in the message or `.WithHint(...)`.
+
+`forbidigo` + `lint/errscontract` reject the legacy `output.Err*` helpers, bare final `fmt.Errorf` / `errors.New`, and legacy envelope literals on migrated paths. Beyond what lint catches, three authoring conventions apply:
+
+- Preserve the underlying error with `.WithCause(err)` so `errors.Is` / `errors.Unwrap` keep working.
+- `param` names only the user input that actually failed. Recovery guidance goes in `.WithHint(...)`; machine-readable recovery fields (`missing_scopes`, `log_id`) carry server/system ground truth only — never caller-side guesses.
+- Error-path tests assert typed metadata via `errs.ProblemOf` (`category` / `subtype` / `param`) and cause preservation, not message substrings alone.
 
 ### stdout is data, stderr is everything else
 

CHANGELOG.md

@@ -2,6 +2,436 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.54] - 2026-06-15
+
+### Features
+
+- **mail**: Auto-attach default signature on send/reply/forward (#1415)
+- **drive**: Support `original_creator_ids` filter in search (#1046)
+- **cli**: Simplify proxy plugin warning and gate it on TTY (#1448)
+
+### Bug Fixes
+
+- **doc**: Fix docs fetch and update ergonomics (#1466)
+- **vfs**: Reject blank local paths (#1460)
+- **vfs**: Reject Windows absolute paths cross-platform (#1401)
+- **event**: Clarify remote bus blocker recovery (#1454)
+
+### Refactor
+
+- Converge command pipelines onto a typed metadata model + catalog (#1191)
+
+### Documentation
+
+- **im**: Document `@mention` format per message type (text/post/card) (#1419)
+- **doc**: Clarify lark-doc create title guidance (#1474)
+- **skills**: Add rename prompt for import without `--name` (#1461)
+- **apps**: Drop Miaoda brand word from apps command help text (#1399)
+
+## [v1.0.53] - 2026-06-12
+
+### Features
+
+- **auth**: Revoke user tokens server-side on `auth logout` (#1434)
+- **auth**: Add `--json` flag support to auth subcommands (#1431)
+- **token**: Mint TAT via unified OAuth v3 Token Endpoint (#1408)
+- **note**: Split note into a dedicated domain with `+detail` and `+transcript` flows (#1345, #1417, #1435)
+- **im**: Unify sort flags into `--sort` field and `--order` direction (#1302)
+
+### Bug Fixes
+
+- **apps**: Read release error_logs from `data.error_logs` in `+release-get` (#1436)
+
+### Documentation
+
+- **skills**: Optimize whiteboard skill (#1371)
+- **skills**: Optimize okr skill (#1368)
+
+## [v1.0.52] - 2026-06-11
+
+### Features
+
+- **events**: Per-resource subscription identity + Match hook (#1185)
+- **apps**: Emit typed error envelopes across the apps domain (#1288)
+- **wiki**: Emit typed error envelopes across the wiki domain (#1350)
+- **im**: Add `--chat-modes` filter to chat search (#1317)
+- **apps**: Exclude `.git` directory from `+html-publish` package (#1396)
+- **build**: Support riscv64 prebuilt binaries in release and install pipeline
+
+### Bug Fixes
+
+- **apps**: Support git credential dry-run (#1390)
+- **whiteboard**: Fix parsing empty whiteboard content (#1391)
+- **build**: Make `-race` flag arch-conditional to support riscv64
+
+### Documentation
+
+- **im**: Document `chat.user_setting` batch_query/batch_update (#1339)
+- **im**: Document `chat.managers` and `chat.moderation` API resources (#1294)
+- **skills**: Optimize lark-drive skill routing (#1284)
+- **skills**: Expand cite user guidance and fix typos (#1394)
+
+## [v1.0.51] - 2026-06-10
+
+### Features
+
+- **apps**: Support multi dev modes (#1175)
+- **im**: Complete audio/post rendering and add opt-in `--download-resources` (#1245)
+- **base**: Configure initial base table schema (#1377)
+- **vc**: Add recording event support (#1369)
+- **minutes**: Replace words for transcript (#1372)
+- **markdown**: Emit typed error envelopes across the markdown domain (#1347)
+- **sheets**: Emit typed error envelopes across the sheets domain (#1348)
+- **slides**: Emit typed error envelopes across the slides domain (#1349)
+
+### Documentation
+
+- **skills**: Warn about `@file` absolute path restriction in lark-doc skills (#1375)
+- **skills**: Remove unsupported ⚠️ from callout emoji list (#1374)
+
+## [v1.0.50] - 2026-06-09
+
+### Features
+
+- **doc**: Emit typed error envelopes across the doc domain (#1346)
+- **event**: Emit typed error envelopes across the event domain (#1289)
+- **contact**: Emit typed error envelopes across the contact domain (#1287)
+- **sheets**: Guard `+csv-put --csv` against a path passed without `@` (#1337)
+- **cli**: Adjust agent timeout hint output conditions (#1328)
+
+### Bug Fixes
+
+- **drive**: Add `@file`/stdin support to `+add-comment --content` (#1343)
+- **slides**: Build create URL locally instead of drive metas call (#1329)
+- **cli**: Clarify `--block-id` supports comma-separated batch delete in help text (#1336)
+
+### Documentation
+
+- **doc**: Replace append with `block_insert_after` in skeleton workflow guidance (#1340)
+- **doc**: Document `<folder-manager>` resource block (#1168)
+- **drive**: Add drive comment location guidance (#1258)
+
+## [v1.0.49] - 2026-06-08
+
+### Features
+
+- **events**: Add whiteboard event domain with per-board subscription (#1265)
+- **im**: Support feed group (#1102)
+- **im**: Add feed shortcut create, list, and remove shortcuts (#1273)
+- **im**: Format feed group error handling (#1308)
+- **im**: Return typed error envelopes across the im domain (#1230)
+- **base**: Emit typed error envelopes across the base domain (#1248)
+- **calendar**: Emit typed error envelopes across the calendar domain (#1232)
+- **task**: Emit typed error envelopes across the task domain (#1231)
+- **okr,whiteboard**: Emit typed error envelopes across both domains (#1236)
+- **minutes,vc**: Emit typed error envelopes across both domains (#1234)
+- **markdown**: Harden create upload failures (#1325)
+- **drive**: Harden inspect shortcut failures (#1324)
+- **slides**: Add IconPark lookup for Lark slides (#1123)
+- **doc**: Remove docs v1 API (#1291)
+- **cli**: Add `skills` command to read embedded skill content (#1318)
+- **cli**: Fetch official skills index (#1301)
+- **shared**: Document relative-path-only file arguments (#1319)
+- **scopes**: Clear `recommend.allow` scope auto-approve overrides (#1272)
+- **shortcuts**: Check shortcut example commands against the live CLI tree (#1244)
+
+### Bug Fixes
+
+- **events**: Keep bounded event consume runs alive after stdin EOF (#1285)
+- **drive**: Use docs secure label read scope (#1281)
+
+### Documentation
+
+- **approval**: Restructure skill with intent table and scope boundaries (#1307)
+- **skills**: Tighten drive and markdown guardrails (#1326)
+- **skills**: Optimize calendar, vc, and minutes skill guidance (#1269)
+- **markdown**: Add markdown domain template (#1293)
+- **markdown**: Improve lark-markdown skill guidance (#1279)
+- **doc**: Improve lark-doc skill guidance (#1283)
+- **wiki**: Optimize skill guidance and routing boundaries (#1275)
+- **slides**: Tighten routing/boundary and reconcile in-slide whiteboard (#1169)
+
+## [v1.0.48] - 2026-06-04
+
+### Features
+
+- **mail**: Preserve mailbox context in `+triage` output for public mailboxes (#1238)
+- **contact**: Add contact skill domain guidance (#1144)
+
+### Bug Fixes
+
+- **skills**: Use JSON skills list during update (#1251)
+
+### Documentation
+
+- **drive**: Refine lark-drive knowledge organize workflow (#1253)
+- **vc-agent**: Require explicit leave request (#1260)
+- **slides**: Add whiteboard element documentation and improve slide guidance (#1029)
+
+## [v1.0.47] - 2026-06-03
+
+### Features
+
+- **sheets**: Add spec-driven shortcut package with backward-compatible wrapper (#1220)
+- **base**: Add base block shortcuts (#1044)
+- **im**: Complete card message format (#1198)
+- **im**: Improve markdown guidance for messages (#1237)
+- **vc**: Forward invite call-id on meeting join (#1243)
+- **drive**: Emit typed error envelopes across the drive domain (#1205)
+- **common**: Emit typed validation errors from shared shortcut pre-checks (#1242)
+- **mail**: Validate `message_ids` in `+messages` before batch get (#1202)
+- **wiki**: Support `appid` member type (#1235)
+- **cli**: Add `--json` flag as no-op alias for `--format json` (#1104)
+- **config**: Validate credentials after `config init` (#1151)
+
+### Bug Fixes
+
+- **skills**: Recover empty fallback for skills to update (#1233)
+
+## [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
@@ -745,6 +1175,27 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.54]: https://github.com/larksuite/cli/releases/tag/v1.0.54
+[v1.0.53]: https://github.com/larksuite/cli/releases/tag/v1.0.53
+[v1.0.52]: https://github.com/larksuite/cli/releases/tag/v1.0.52
+[v1.0.51]: https://github.com/larksuite/cli/releases/tag/v1.0.51
+[v1.0.50]: https://github.com/larksuite/cli/releases/tag/v1.0.50
+[v1.0.49]: https://github.com/larksuite/cli/releases/tag/v1.0.49
+[v1.0.48]: https://github.com/larksuite/cli/releases/tag/v1.0.48
+[v1.0.47]: https://github.com/larksuite/cli/releases/tag/v1.0.47
+[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

Makefile

@@ -8,6 +8,13 @@ DATE     := $(shell date +%Y-%m-%d)
 LDFLAGS  := -s -w -X $(MODULE)/internal/build.Version=$(VERSION) -X $(MODULE)/internal/build.Date=$(DATE)
 PREFIX   ?= /usr/local
 
+# The repository's Go 1.23 CI toolchain does not support -race on riscv64.
+# Prefer GOARCH passed to make (for example, `make GOARCH=riscv64 unit-test`)
+# over `go env GOARCH`, because command-line make variables are not visible to
+# $(shell ...).
+TEST_GOARCH := $(or $(GOARCH),$(shell go env GOARCH))
+RACE_FLAG := $(if $(filter riscv64,$(TEST_GOARCH)),,-race)
+
 .PHONY: all build vet fmt-check test unit-test integration-test examples-build install uninstall clean fetch_meta gitleaks
 
 all: test
@@ -34,7 +41,7 @@ fmt-check:
 
 # ./extension/... keeps the public plugin SDK in the default test matrix.
 unit-test: fetch_meta
-	go test -race -gcflags="all=-N -l" -count=1 \
+	go test $(RACE_FLAG) -gcflags="all=-N -l" -count=1 \
 		./cmd/... ./internal/... ./shortcuts/... ./extension/...
 
 # examples-build keeps the shipped plugin-SDK examples compilable. If this

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 24 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 26 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** — 17 business domains, 200+ curated commands, 24 AI Agent [Skills](./skills/)
+- **Wide Coverage** — 18 business domains, 200+ curated commands, 26 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
@@ -41,6 +41,7 @@ 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       | Create Spark/Miaoda apps, publish HTML/static sites, run cloud generation, and manage access scope                                 |
 
 ## Installation & Quick Start
 
@@ -278,6 +279,8 @@ Community contributions are welcome! If you find a bug or have feature suggestio
 
 For major changes, we recommend discussing with us first via an Issue.
 
+Before opening a PR, see [AGENTS.md](./AGENTS.md) for the local build, test, and PR checklist used by contributors and AI agents.
+
 ## License
 
 This project is licensed under the **MIT License**.

README.zh.md

@@ -6,14 +6,14 @@
 
 [中文版](./README.zh.md) | [English](./README.md)
 
-飞书官方 CLI 工具，由 [larksuite](https://github.com/larksuite) 团队维护 — 让人类和 AI Agent 都能在终端中操作飞书。覆盖消息、文档、多维表格、电子表格、幻灯片、日历、邮箱、任务、会议、Markdown 等核心业务域，提供 200+ 命令及 24 个 AI Agent [Skills](./skills/)。
+飞书官方 CLI 工具，由 [larksuite](https://github.com/larksuite) 团队维护 — 让人类和 AI Agent 都能在终端中操作飞书。覆盖消息、文档、多维表格、电子表格、幻灯片、日历、邮箱、任务、会议、Markdown 等核心业务域，提供 200+ 命令及 26 个 AI Agent [Skills](./skills/)。
 
 [安装](#安装与快速开始) · [AI Agent Skills](#agent-skills) · [认证](#认证) · [命令](#三层命令调用) · [进阶用法](#进阶用法) · [安全](#安全与风险提示使用前必读) · [贡献](#贡献)
 
 ## 为什么选 lark-cli？
 
-- **为 Agent 原生设计** — 24 个 [Skills](./skills/) 开箱即用，适配主流 AI 工具，Agent 无需额外适配即可操作飞书
-- **覆盖面广** — 17 大业务域、200+ 精选命令、24 个 AI Agent [Skills](./skills/)
+- **为 Agent 原生设计** — 26 个 [Skills](./skills/) 开箱即用，适配主流 AI 工具，Agent 无需额外适配即可操作飞书
+- **覆盖面广** — 18 大业务域、200+ 精选命令、26 个 AI Agent [Skills](./skills/)
 - **AI 友好调优** — 每条命令经过 Agent 实测验证，提供更友好的参数、智能默认值和结构化输出，大幅提升 Agent 调用成功率
 - **开源零门槛** — MIT 协议，开箱即用，`npm install` 即可使用
 - **三分钟上手** — 一键创建应用、交互式登录授权，从安装到第一次 API 调用只需三步
@@ -41,6 +41,7 @@
 | ✍️ 审批     | 查询审批任务、同意/拒绝/转交审批任务、撤回与抄送审批实例              |
 | 🎯 OKR  | 查询、创建、更新 OKR，管理目标、关键结果、对齐、指标和进展记录        |
 | 📋 飞书项目 | 管理工作项、排期与数据 — 由独立的 [meegle-cli](https://github.com/larksuite/meegle-cli) 提供（需单独安装） |
+| 🔗 应用     | 创建妙搭（Spark/Miaoda）应用、发布 HTML/静态站点、云端生成迭代、管理可用范围                                                                                                   |
 
 ## 安装与快速开始
 
@@ -279,6 +280,8 @@ lark-cli schema im.messages.delete
 
 对于较大的改动，建议先通过 Issue 与我们讨论。
 
+提交 PR 前，请先阅读 [AGENTS.md](./AGENTS.md)，其中列出了贡献者和 AI Agent 使用的本地构建、测试和 PR 检查清单。
+
 ## 许可证
 
 本项目基于 **MIT 许可证** 开源。

cmd/api/api.go

@@ -90,6 +90,7 @@ 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)")
@@ -238,7 +239,11 @@ func apiRun(opts *APIOptions) error {
 
 	resp, err := ac.DoAPI(opts.Ctx, request)
 	if err != nil {
-		return output.MarkRaw(client.WrapDoAPIError(err))
+		// MarkRaw tells the dispatcher to skip 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)
 	}
 	err = client.HandleResponse(resp, client.ResponseOptions{
 		OutputPath:  opts.Output,
@@ -248,9 +253,15 @@ 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 tells root error handler to skip enrichPermissionError,
-	// preserving the original API error detail (log_id, troubleshooter, etc.).
+	// MarkRaw: see comment above on the DoAPI path. Skips legacy
+	// *ExitError enrichment; typed errors flow through unchanged.
 	if err != nil {
 		return output.MarkRaw(err)
 	}
@@ -262,9 +273,12 @@ func apiDryRun(f *cmdutil.Factory, request client.RawApiRequest, config *core.Cl
 }
 
 func apiPaginate(ctx context.Context, ac *client.APIClient, request client.RawApiRequest, format output.Format, jqExpr string, out, errOut io.Writer, pagOpts client.PaginationOptions) error {
+	if pagOpts.Identity == "" {
+		pagOpts.Identity = request.As
+	}
 	// When jq is set, always aggregate all pages then filter.
 	if jqExpr != "" {
-		if err := client.PaginateWithJq(ctx, ac, request, jqExpr, out, pagOpts, client.CheckLarkResponse); err != nil {
+		if err := client.PaginateWithJq(ctx, ac, request, jqExpr, out, pagOpts, ac.CheckResponse); err != nil {
 			return output.MarkRaw(err)
 		}
 		return nil
@@ -277,9 +291,9 @@ func apiPaginate(ctx context.Context, ac *client.APIClient, request client.RawAp
 			pf.FormatPage(items)
 		}, pagOpts)
 		if err != nil {
-			return output.MarkRaw(output.ErrNetwork("API call failed: %v", err))
+			return output.MarkRaw(err)
 		}
-		if apiErr := client.CheckLarkResponse(result); apiErr != nil {
+		if apiErr := ac.CheckResponse(result, pagOpts.Identity); apiErr != nil {
 			output.FormatValue(out, result, output.FormatJSON)
 			return output.MarkRaw(apiErr)
 		}
@@ -291,9 +305,9 @@ func apiPaginate(ctx context.Context, ac *client.APIClient, request client.RawAp
 	default:
 		result, err := ac.PaginateAll(ctx, request, pagOpts)
 		if err != nil {
-			return output.MarkRaw(output.ErrNetwork("API call failed: %v", err))
+			return output.MarkRaw(err)
 		}
-		if apiErr := client.CheckLarkResponse(result); apiErr != nil {
+		if apiErr := ac.CheckResponse(result, pagOpts.Identity); apiErr != nil {
 			output.FormatValue(out, result, output.FormatJSON)
 			return output.MarkRaw(apiErr)
 		}

cmd/api/api_test.go

@@ -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"
 )
 
@@ -66,6 +66,24 @@ func TestApiCmd_DryRun(t *testing.T) {
 	}
 }
 
+// Regression: --params null parses to a nil map; writing page_size onto it must
+// not panic. Symmetric to the typed-flag overlay path in cmd/service — both
+// write into the map ParseJSONMap returns.
+func TestApiCmd_NullParamsWithPageSize(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+
+	cmd := NewCmdApi(f, nil)
+	cmd.SetArgs([]string{"GET", "/open-apis/test", "--params", "null", "--page-size", "50", "--as", "bot", "--dry-run"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("--params null with --page-size should not error, got: %v", err)
+	}
+	if out := stdout.String(); !strings.Contains(out, "page_size") {
+		t.Errorf("expected page_size applied over null --params, got:\n%s", out)
+	}
+}
+
 func TestApiCmd_BotMode(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
@@ -399,154 +417,6 @@ func TestNormalisePath_StripsQueryAndFragment(t *testing.T) {
 	}
 }
 
-func TestApiCmd_APIError_IsRaw(t *testing.T) {
-	f, _, stderr, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app-raw", AppSecret: "test-secret-raw", Brand: core.BrandFeishu,
-	})
-
-	// Return a permission error from the API
-	reg.Register(&httpmock.Stub{
-		URL: "/open-apis/test/perm",
-		Body: map[string]interface{}{
-			"code": 99991672,
-			"msg":  "scope not enabled for this app",
-			"error": map[string]interface{}{
-				"permission_violations": []interface{}{
-					map[string]interface{}{"subject": "calendar:calendar:readonly"},
-				},
-			},
-		},
-	})
-
-	cmd := NewCmdApi(f, nil)
-	cmd.SetArgs([]string{"GET", "/open-apis/test/perm", "--as", "bot"})
-	err := cmd.Execute()
-	if err == nil {
-		t.Fatal("expected error for permission denied API response")
-	}
-
-	// Error should be marked Raw
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T", err)
-	}
-	if !exitErr.Raw {
-		t.Error("expected API error from api command to be marked Raw")
-	}
-
-	// Note: stderr envelope output is tested at the root level (TestHandleRootError_*)
-	// since WriteErrorEnvelope is called by handleRootError, not by cobra's Execute.
-	_ = stderr
-}
-
-func TestApiCmd_APIError_PreservesOriginalMessage(t *testing.T) {
-	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app-origmsg", AppSecret: "test-secret-origmsg", Brand: core.BrandFeishu,
-	})
-
-	reg.Register(&httpmock.Stub{
-		URL: "/open-apis/test/origmsg",
-		Body: map[string]interface{}{
-			"code": 99991672,
-			"msg":  "scope not enabled for this app",
-			"error": map[string]interface{}{
-				"permission_violations": []interface{}{
-					map[string]interface{}{"subject": "im:message:readonly"},
-				},
-			},
-		},
-	})
-
-	cmd := NewCmdApi(f, nil)
-	cmd.SetArgs([]string{"GET", "/open-apis/test/origmsg", "--as", "bot"})
-	err := cmd.Execute()
-	if err == nil {
-		t.Fatal("expected error")
-	}
-
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T", err)
-	}
-	// The message should NOT have been enriched (no "App scope not enabled" replacement)
-	if strings.Contains(exitErr.Error(), "App scope not enabled") {
-		t.Error("expected original message, not enriched message")
-	}
-	// Detail should still contain the raw API error detail
-	if exitErr.Detail == nil {
-		t.Fatal("expected non-nil Detail")
-	}
-	if exitErr.Detail.Detail == nil {
-		t.Error("expected raw Detail.Detail to be preserved (not cleared by enrichment)")
-	}
-}
-
-func TestApiCmd_InvalidJSONResponse_ShowsDiagnostic(t *testing.T) {
-	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app-invalidjson", AppSecret: "test-secret-invalidjson", Brand: core.BrandFeishu,
-	})
-
-	reg.Register(&httpmock.Stub{
-		URL:         "/open-apis/test/invalidjson",
-		RawBody:     []byte{},
-		ContentType: "application/json",
-	})
-
-	cmd := NewCmdApi(f, nil)
-	cmd.SetArgs([]string{"GET", "/open-apis/test/invalidjson", "--as", "bot"})
-	err := cmd.Execute()
-	if err == nil {
-		t.Fatal("expected error")
-	}
-
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T", err)
-	}
-	if exitErr.Code != output.ExitAPI {
-		t.Fatalf("expected ExitAPI, got %d", exitErr.Code)
-	}
-	if exitErr.Detail == nil {
-		t.Fatal("expected detail on exit error")
-	}
-	if !strings.Contains(exitErr.Detail.Message, "invalid JSON response") &&
-		!strings.Contains(exitErr.Detail.Message, "empty JSON response body") {
-		t.Fatalf("expected JSON diagnostic, got %q", exitErr.Detail.Message)
-	}
-	if !strings.Contains(exitErr.Detail.Hint, "--output") {
-		t.Fatalf("expected hint to mention --output, got %q", exitErr.Detail.Hint)
-	}
-}
-
-func TestApiCmd_PageAll_APIError_IsRaw(t *testing.T) {
-	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app-rawpage", AppSecret: "test-secret-rawpage", Brand: core.BrandFeishu,
-	})
-
-	reg.Register(&httpmock.Stub{
-		URL: "/open-apis/test/rawpage",
-		Body: map[string]interface{}{
-			"code": 99991672,
-			"msg":  "scope not enabled",
-		},
-	})
-
-	cmd := NewCmdApi(f, nil)
-	cmd.SetArgs([]string{"GET", "/open-apis/test/rawpage", "--as", "bot", "--page-all"})
-	err := cmd.Execute()
-	if err == nil {
-		t.Fatal("expected error")
-	}
-
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T", err)
-	}
-	if !exitErr.Raw {
-		t.Error("expected paginated API error to be marked Raw")
-	}
-}
-
 func TestApiCmd_JqFlag_Parsing(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
@@ -820,3 +690,69 @@ 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)
+	}
+}

cmd/auth/auth.go

@@ -17,6 +17,7 @@ import (
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/errclass"
 )
 
 // NewCmdAuth creates the auth command with subcommands.
@@ -43,6 +44,7 @@ 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
 }
 
@@ -69,7 +71,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: %v", err)
+		return "", "", fmt.Errorf("failed to parse user info: %w", err)
 	}
 	if resp.Code != 0 {
 		return "", "", fmt.Errorf("failed to get user info [%d]: %s", resp.Code, resp.Msg)
@@ -109,6 +111,11 @@ 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()
@@ -130,10 +137,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: %v", err)
+		return nil, fmt.Errorf("failed to parse response: %w", err)
 	}
 	if resp.Code != 0 {
-		return nil, fmt.Errorf("API error [%d]: %s", resp.Code, resp.Msg)
+		return nil, classifyAppInfoErr(apiResp.RawBody, resp.Code, resp.Msg, f, appId)
 	}
 
 	app := resp.Data.App
@@ -152,3 +159,21 @@ 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)
+}

cmd/auth/auth_test.go

@@ -12,6 +12,7 @@ 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"
@@ -61,7 +62,7 @@ func TestAuthLoginCmd_HelpGuidesNonStreamingAgentsToSplitFlow(t *testing.T) {
 	for _, want := range []string{
 		"only delivers final turn messages",
 		"--no-wait --json",
-		"send the verification URL to the user as your final message",
+		"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) {
@@ -90,6 +91,29 @@ func TestAuthCheckCmd_FlagParsing(t *testing.T) {
 	}
 }
 
+func TestAuthCheckCmd_AcceptsJSONFlag(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+
+	var gotOpts *CheckOptions
+	cmd := NewCmdAuthCheck(f, func(opts *CheckOptions) error {
+		gotOpts = opts
+		return nil
+	})
+	cmd.SetArgs([]string{"--scope", "calendar:calendar:read", "--json"})
+	err := cmd.Execute()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotOpts == nil {
+		t.Fatal("expected opts to be set")
+	}
+	if !gotOpts.JSON {
+		t.Error("expected JSON=true")
+	}
+}
+
 func TestAuthLogoutCmd_FlagParsing(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 
@@ -108,6 +132,27 @@ func TestAuthLogoutCmd_FlagParsing(t *testing.T) {
 	}
 }
 
+func TestAuthLogoutCmd_AcceptsJSONFlag(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+
+	var gotOpts *LogoutOptions
+	cmd := NewCmdAuthLogout(f, func(opts *LogoutOptions) error {
+		gotOpts = opts
+		return nil
+	})
+	cmd.SetArgs([]string{"--json"})
+	err := cmd.Execute()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotOpts == nil {
+		t.Fatal("expected opts to be set")
+	}
+	if !gotOpts.JSON {
+		t.Error("expected JSON=true")
+	}
+}
+
 func TestAuthListCmd_FlagParsing(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 
@@ -125,6 +170,27 @@ func TestAuthListCmd_FlagParsing(t *testing.T) {
 	}
 }
 
+func TestAuthListCmd_AcceptsJSONFlag(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+
+	var gotOpts *ListOptions
+	cmd := NewCmdAuthList(f, func(opts *ListOptions) error {
+		gotOpts = opts
+		return nil
+	})
+	cmd.SetArgs([]string{"--json"})
+	err := cmd.Execute()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotOpts == nil {
+		t.Error("expected opts to be set")
+	}
+	if !gotOpts.JSON {
+		t.Error("expected JSON=true")
+	}
+}
+
 func TestAuthStatusCmd_FlagParsing(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
@@ -144,6 +210,29 @@ func TestAuthStatusCmd_FlagParsing(t *testing.T) {
 	}
 }
 
+func TestAuthStatusCmd_AcceptsJSONFlag(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+
+	var gotOpts *StatusOptions
+	cmd := NewCmdAuthStatus(f, func(opts *StatusOptions) error {
+		gotOpts = opts
+		return nil
+	})
+	cmd.SetArgs([]string{"--json"})
+	err := cmd.Execute()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotOpts == nil {
+		t.Error("expected opts to be set")
+	}
+	if !gotOpts.JSON {
+		t.Error("expected JSON=true")
+	}
+}
+
 func TestAuthStatusCmd_VerifyFlag(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
@@ -266,6 +355,32 @@ func TestAuthScopesCmd_FlagParsing(t *testing.T) {
 	}
 }
 
+func TestAuthScopesCmd_JSONFlagForcesJSONFormat(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+
+	var gotOpts *ScopesOptions
+	cmd := NewCmdAuthScopes(f, func(opts *ScopesOptions) error {
+		gotOpts = opts
+		return nil
+	})
+	cmd.SetArgs([]string{"--format", "pretty", "--json"})
+	err := cmd.Execute()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotOpts == nil {
+		t.Fatal("expected opts to be set")
+	}
+	if !gotOpts.JSON {
+		t.Error("expected JSON=true")
+	}
+	if gotOpts.Format != "json" {
+		t.Errorf("expected format json, got %s", gotOpts.Format)
+	}
+}
+
 func TestAuthScopesRun_UsesTenantAccessTokenFromCredentialProvider(t *testing.T) {
 	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "", Brand: core.BrandFeishu,
@@ -318,6 +433,54 @@ 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
 }
@@ -389,15 +552,8 @@ func TestAuthBlockedByExternalProvider(t *testing.T) {
 			if matched != nil && matched != cmd && !matched.SilenceUsage {
 				t.Error("expected PersistentPreRunE to set SilenceUsage on matched subcommand")
 			}
-			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")
+			if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
+				t.Errorf("exit code = %d, want %d", gotCode, output.ExitValidation)
 			}
 		})
 	}

cmd/auth/check.go

@@ -9,6 +9,7 @@ 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"
@@ -18,6 +19,7 @@ import (
 type CheckOptions struct {
 	Factory *cmdutil.Factory
 	Scope   string
+	JSON    bool
 }
 
 // NewCmdAuthCheck creates the auth check subcommand.
@@ -36,6 +38,7 @@ func NewCmdAuthCheck(f *cmdutil.Factory, runF func(*CheckOptions) error) *cobra.
 	}
 
 	cmd.Flags().StringVar(&opts.Scope, "scope", "", "scopes to check (space-separated)")
+	cmd.Flags().BoolVar(&opts.JSON, "json", false, "structured JSON output")
 	cmd.MarkFlagRequired("scope")
 	cmdutil.SetRisk(cmd, "read")
 
@@ -47,8 +50,7 @@ func authCheckRun(opts *CheckOptions) error {
 
 	required := strings.Fields(opts.Scope)
 	if len(required) == 0 {
-		output.PrintJson(f.IOStreams.Out, map[string]interface{}{"ok": true, "granted": []string{}, "missing": []string{}})
-		return nil
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--scope cannot be empty").WithParam("--scope")
 	}
 
 	config, err := f.Config()

cmd/auth/check_test.go

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

cmd/auth/list.go

@@ -18,6 +18,7 @@ import (
 // ListOptions holds all inputs for auth list.
 type ListOptions struct {
 	Factory *cmdutil.Factory
+	JSON    bool
 }
 
 // NewCmdAuthList creates the auth list subcommand.
@@ -34,6 +35,7 @@ func NewCmdAuthList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Co
 			return authListRun(opts)
 		},
 	}
+	cmd.Flags().BoolVar(&opts.JSON, "json", false, "structured JSON output")
 	cmdutil.SetRisk(cmd, "read")
 
 	return cmd
@@ -44,6 +46,14 @@ func authListRun(opts *ListOptions) error {
 
 	multi, _ := core.LoadMultiAppConfig()
 	if multi == nil || len(multi.Apps) == 0 {
+		if opts.JSON {
+			output.PrintJson(f.IOStreams.Out, map[string]interface{}{
+				"ok":     true,
+				"users":  []map[string]interface{}{},
+				"reason": "not_configured",
+			})
+			return nil
+		}
 		// auth list is a read-only probe; the "configured but no users"
 		// branch below already returns exit 0 with a stderr hint, so we
 		// keep the same contract here. We still want the hint to be
@@ -61,6 +71,14 @@ func authListRun(opts *ListOptions) error {
 
 	app := multi.CurrentAppConfig(f.Invocation.Profile)
 	if app == nil || len(app.Users) == 0 {
+		if opts.JSON {
+			output.PrintJson(f.IOStreams.Out, map[string]interface{}{
+				"ok":     true,
+				"users":  []map[string]interface{}{},
+				"reason": "not_logged_in",
+			})
+			return nil
+		}
 		fmt.Fprintln(f.IOStreams.ErrOut, "No logged-in users. Run `lark-cli auth login` to log in.")
 		return nil
 	}

cmd/auth/list_test.go

@@ -4,6 +4,7 @@
 package auth
 
 import (
+	"encoding/json"
 	"strings"
 	"testing"
 
@@ -34,6 +35,33 @@ func TestAuthListRun_NotConfigured_ReturnsExitZero(t *testing.T) {
 	}
 }
 
+func TestAuthListRun_JSONMode_NotConfigured_WritesStdoutOnly(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
+	if err := authListRun(&ListOptions{Factory: f, JSON: true}); err != nil {
+		t.Fatalf("auth list should succeed when not configured (exit 0); got: %v", err)
+	}
+
+	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"])
+	}
+	users, ok := payload["users"].([]any)
+	if !ok || len(users) != 0 {
+		t.Errorf("stdout.users = %v, want empty array", payload["users"])
+	}
+	if payload["reason"] != "not_configured" {
+		t.Errorf("stdout.reason = %v, want not_configured", payload["reason"])
+	}
+	if stderr.Len() != 0 {
+		t.Errorf("stderr must stay empty in JSON mode, got:\n%s", stderr.String())
+	}
+}
+
 // TestAuthListRun_NotConfigured_AgentWorkspace_RoutesToBindHelp covers the
 // reason this hint exists workspace-aware in the first place: an AI agent
 // in OpenClaw / Hermes that probes auth list before binding gets routed to
@@ -57,3 +85,48 @@ func TestAuthListRun_NotConfigured_AgentWorkspace_RoutesToBindHelp(t *testing.T)
 		t.Errorf("agent hint must not mention config init: %s", out)
 	}
 }
+
+func TestAuthListRun_JSONMode_NoLoggedInUsers_WritesStdoutOnly(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	writeLogoutConfig(t, nil)
+
+	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
+	if err := authListRun(&ListOptions{Factory: f, JSON: true}); err != nil {
+		t.Fatalf("auth list should succeed when no users exist (exit 0); got: %v", err)
+	}
+
+	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"])
+	}
+	users, ok := payload["users"].([]any)
+	if !ok || len(users) != 0 {
+		t.Errorf("stdout.users = %v, want empty array", payload["users"])
+	}
+	if payload["reason"] != "not_logged_in" {
+		t.Errorf("stdout.reason = %v, want not_logged_in", payload["reason"])
+	}
+	if stderr.Len() != 0 {
+		t.Errorf("stderr must stay empty in JSON mode, got:\n%s", stderr.String())
+	}
+}
+
+func TestAuthListRun_DefaultMode_NoLoggedInUsers_KeepsTextOutput(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	writeLogoutConfig(t, nil)
+
+	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
+	if err := authListRun(&ListOptions{Factory: f}); err != nil {
+		t.Fatalf("auth list should succeed when no users exist (exit 0); got: %v", err)
+	}
+
+	if stdout.Len() != 0 {
+		t.Errorf("stdout must stay empty in default mode, got:\n%s", stdout.String())
+	}
+	if !strings.Contains(stderr.String(), "No logged-in users") {
+		t.Errorf("stderr = %q, want no-users hint", stderr.String())
+	}
+}

cmd/auth/login.go

@@ -13,9 +13,12 @@ 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"
@@ -47,14 +50,15 @@ 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 only delivers final turn messages, use --no-wait --json,
-send the verification URL to the user as your final message, end the turn, then
-run --device-code in a later step after the user confirms authorization.`,
+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).`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if mode := f.ResolveStrictMode(cmd.Context()); mode == core.StrictModeBot {
-				return output.ErrWithHint(output.ExitValidation, "command_denied",
-					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)")
+				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)")
 			}
 			opts.Ctx = cmd.Context()
 			if runF != nil {
@@ -68,7 +72,13 @@ run --device-code in a later step after the user confirms authorization.`,
 
 	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")
-	available := sortedKnownDomains()
+	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)
 	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,
@@ -114,7 +124,7 @@ func authLoginRun(opts *LoginOptions) error {
 	}
 
 	// Determine UI language from saved config
-	lang := "zh"
+	var lang i18n.Lang
 	if multi, _ := core.LoadMultiAppConfig(); multi != nil {
 		if app := multi.FindApp(config.ProfileName); app != nil {
 			lang = app.Lang
@@ -139,25 +149,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()
+			selectedDomains = sortedKnownDomains(config.Brand)
 			break
 		}
 	}
 
 	// Validate domain names and suggest corrections for unknown ones
 	if len(selectedDomains) > 0 {
-		knownDomains := allKnownDomains()
+		knownDomains := allKnownDomains(config.Brand)
 		for _, d := range selectedDomains {
 			if !knownDomains[d] {
 				if suggestion := suggestDomain(d, knownDomains); suggestion != "" {
-					return output.ErrValidation("unknown domain %q, did you mean %q?", d, suggestion)
+					return errs.NewValidationError(errs.SubtypeInvalidArgument, "unknown domain %q, did you mean %q?", d, suggestion).WithParam("--domain")
 				}
 				available := make([]string, 0, len(knownDomains))
 				for k := range knownDomains {
 					available = append(available, k)
 				}
 				sort.Strings(available)
-				return output.ErrValidation("unknown domain %q, available domains: %s", d, strings.Join(available, ", "))
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "unknown domain %q, available domains: %s", d, strings.Join(available, ", ")).WithParam("--domain")
 			}
 		}
 	}
@@ -165,17 +175,17 @@ func authLoginRun(opts *LoginOptions) error {
 	hasAnyOption := opts.Scope != "" || opts.Recommend || len(selectedDomains) > 0
 
 	if len(opts.Exclude) > 0 && !hasAnyOption {
-		return output.ErrValidation("--exclude requires --scope, --domain, or --recommend to be specified")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--exclude requires --scope, --domain, or --recommend to be specified").WithParam("--exclude")
 	}
 
 	if !hasAnyOption {
 		if !opts.JSON && f.IOStreams.IsTerminal {
-			result, err := runInteractiveLogin(f.IOStreams, lang, msg)
+			result, err := runInteractiveLogin(f.IOStreams, lang.Base(), msg, config.Brand)
 			if err != nil {
 				return err
 			}
 			if result == nil {
-				return output.ErrValidation("no login options selected")
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "no login options selected")
 			}
 			selectedDomains = result.Domains
 			scopeLevel = result.ScopeLevel
@@ -191,7 +201,7 @@ func authLoginRun(opts *LoginOptions) error {
 			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 output.ErrValidation("please specify the scopes to authorize")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "please specify the scopes to authorize").WithParam("--scope")
 		}
 	}
 
@@ -208,10 +218,10 @@ func authLoginRun(opts *LoginOptions) error {
 	if len(selectedDomains) > 0 || opts.Recommend {
 		var candidateScopes []string
 		if len(selectedDomains) > 0 {
-			candidateScopes = collectScopesForDomains(selectedDomains, "user")
+			candidateScopes = collectScopesForDomains(selectedDomains, "user", config.Brand)
 		} else {
 			// --recommend without --domain: all domains
-			candidateScopes = collectScopesForDomains(sortedKnownDomains(), "user")
+			candidateScopes = collectScopesForDomains(sortedKnownDomains(config.Brand), "user", config.Brand)
 		}
 
 		// Filter to auto-approve scopes if --recommend or interactive "common"
@@ -220,7 +230,7 @@ func authLoginRun(opts *LoginOptions) error {
 		}
 
 		if len(candidateScopes) == 0 && opts.Scope == "" {
-			return output.ErrValidation("no matching scopes found, check domain/scope options")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "no matching scopes found, check domain/scope options")
 		}
 
 		// Merge --scope additively with the resolved domain scopes.
@@ -240,13 +250,13 @@ func authLoginRun(opts *LoginOptions) error {
 	if len(opts.Exclude) > 0 {
 		excluded, unknown := applyExcludeScopes(finalScope, opts.Exclude)
 		if len(unknown) > 0 {
-			return output.ErrValidation(
+			return errs.NewValidationError(errs.SubtypeInvalidArgument,
 				"these --exclude scopes are not present in the requested set: %s",
-				strings.Join(unknown, ", "))
+				strings.Join(unknown, ", ")).WithParam("--exclude")
 		}
 		finalScope = excluded
 		if strings.TrimSpace(finalScope) == "" {
-			return output.ErrValidation("no scopes left after applying --exclude; nothing to authorize")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "no scopes left after applying --exclude; nothing to authorize").WithParam("--exclude")
 		}
 	}
 
@@ -257,7 +267,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 output.ErrAuth("device authorization failed: %v", err)
+		return errs.NewAuthenticationError(errs.SubtypeUnknown, "device authorization failed: %v", err).WithCause(err)
 	}
 
 	// --no-wait: return immediately with device code and URL
@@ -269,21 +279,28 @@ func authLoginRun(opts *LoginOptions) error {
 			"verification_url": authResp.VerificationUriComplete,
 			"device_code":      authResp.DeviceCode,
 			"expires_in":       authResp.ExpiresIn,
-			"hint":             fmt.Sprintf("Show verification_url to the user exactly as returned by the CLI and treat it as an opaque string. Do not URL-encode or decode it, do not normalize or rewrite it, do not add %%20, spaces, or punctuation, and do not wrap it as Markdown link text; prefer a fenced code block containing only the raw URL. For agent harnesses that only deliver final turn messages, make the URL the final message of the turn and return control to the user; do not block on --device-code in the same turn. After the user confirms authorization in a later step, run: lark-cli auth login --device-code %s", authResp.DeviceCode),
+			"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.",
 		}
 		encoder := json.NewEncoder(f.IOStreams.Out)
 		encoder.SetEscapeHTML(false)
 		if err := encoder.Encode(data); err != nil {
-			return output.Errorf(output.ExitInternal, "internal", "failed to write JSON output: %v", err)
+			return errs.NewInternalError(errs.SubtypeSDKError, "failed to write JSON output: %v", err).WithCause(err)
 		}
 		return nil
 	}
 
 	// Step 2: Show user code and verification URL.
-	// Both branches surface AgentTimeoutHint, but on different channels:
-	// JSON mode embeds it as a structured field (so an agent that captures
-	// stdout into a JSON parser sees it without stream-mixing surprises),
-	// text mode prints to stderr (alongside the URL prompt).
+	// JSON mode embeds AgentTimeoutHint as a structured field so agents that
+	// capture stdout into a JSON parser see it without stream-mixing surprises.
+	// Text mode prints the hint to stderr only when running under a non-TTY
+	// (i.e. piped / agent harness), since humans reading a terminal don't need
+	// the agent-oriented instructions.
 	if opts.JSON {
 		data := map[string]interface{}{
 			"event":                     "device_authorization",
@@ -296,12 +313,14 @@ func authLoginRun(opts *LoginOptions) error {
 		encoder := json.NewEncoder(f.IOStreams.Out)
 		encoder.SetEscapeHTML(false)
 		if err := encoder.Encode(data); err != nil {
-			return output.Errorf(output.ExitInternal, "internal", "failed to write JSON output: %v", err)
+			return errs.NewInternalError(errs.SubtypeSDKError, "failed to write JSON output: %v", err).WithCause(err)
 		}
 	} else {
 		fmt.Fprintf(f.IOStreams.ErrOut, msg.OpenURL)
 		fmt.Fprintf(f.IOStreams.ErrOut, "  %s\n\n", authResp.VerificationUriComplete)
-		fmt.Fprintln(f.IOStreams.ErrOut, msg.AgentTimeoutHint)
+		if f.IOStreams != nil && !f.IOStreams.IsTerminal {
+			fmt.Fprintln(f.IOStreams.ErrOut, msg.AgentTimeoutHint)
+		}
 	}
 
 	// Step 3: Poll for token
@@ -317,25 +336,25 @@ func authLoginRun(opts *LoginOptions) error {
 				"event": "authorization_failed",
 				"error": result.Message,
 			}); err != nil {
-				return output.Errorf(output.ExitInternal, "internal", "failed to write JSON output: %v", err)
+				return errs.NewInternalError(errs.SubtypeSDKError, "failed to write JSON output: %v", err).WithCause(err)
 			}
 			return output.ErrBare(output.ExitAuth)
 		}
-		return output.ErrAuth("authorization failed: %s", result.Message)
+		return errs.NewAuthenticationError(errs.SubtypeUnknown, "authorization failed: %s", result.Message)
 	}
 	if result.Token == nil {
-		return output.ErrAuth("authorization succeeded but no token returned")
+		return errs.NewAuthenticationError(errs.SubtypeTokenMissing, "authorization succeeded but no token returned")
 	}
 
 	// Step 6: Get user info
 	log(msg.AuthSuccess)
 	sdk, err := f.LarkClient()
 	if err != nil {
-		return output.ErrAuth("failed to get SDK: %v", err)
+		return errs.NewInternalError(errs.SubtypeSDKError, "failed to get SDK: %v", err).WithCause(err)
 	}
 	openId, userName, err := getUserInfo(opts.Ctx, sdk, result.Token.AccessToken)
 	if err != nil {
-		return output.ErrAuth("failed to get user info: %v", err)
+		return errs.NewAuthenticationError(errs.SubtypeUnknown, "failed to get user info: %v", err).WithCause(err)
 	}
 
 	scopeSummary := loadLoginScopeSummary(config.AppID, openId, finalScope, result.Token.Scope)
@@ -353,13 +372,13 @@ func authLoginRun(opts *LoginOptions) error {
 		GrantedAt:        now,
 	}
 	if err := larkauth.SetStoredToken(storedToken); err != nil {
-		return output.Errorf(output.ExitInternal, "internal", "failed to save token: %v", err)
+		return errs.NewInternalError(errs.SubtypeStorage, "failed to save token: %v", err).WithCause(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 output.Errorf(output.ExitInternal, "internal", "failed to update login profile: %v", err)
+		return err
 	}
 
 	if issue := ensureRequestedScopesGranted(finalScope, result.Token.Scope, msg, scopeSummary); issue != nil {
@@ -388,10 +407,11 @@ func authLoginPollDeviceCode(opts *LoginOptions, config *core.CliConfig, msg *lo
 			fmt.Fprintf(f.IOStreams.ErrOut, "[lark-cli] [WARN] auth login: failed to remove cached requested scopes: %v\n", err)
 		}
 	}
-	// Skip the stderr hint in JSON mode — the --no-wait call that issued the
-	// device_code already returned the hint as a JSON field, and writing
-	// text to stderr would pollute consumers that combine streams via 2>&1.
-	if !opts.JSON {
+	// Skip the stderr hint in JSON mode (the --no-wait call that issued
+	// the device_code already surfaced it as a JSON field), and also skip it
+	// when running on an interactive terminal — the agent-oriented
+	// instructions only matter for piped / harness environments.
+	if !opts.JSON && f.IOStreams != nil && !f.IOStreams.IsTerminal {
 		fmt.Fprintln(f.IOStreams.ErrOut, msg.AgentTimeoutHint)
 	}
 	log(msg.WaitingAuth)
@@ -402,22 +422,22 @@ func authLoginPollDeviceCode(opts *LoginOptions, config *core.CliConfig, msg *lo
 		if shouldRemoveLoginRequestedScope(result) {
 			cleanupRequestedScope()
 		}
-		return output.ErrAuth("authorization failed: %s", result.Message)
+		return errs.NewAuthenticationError(errs.SubtypeUnknown, "authorization failed: %s", result.Message)
 	}
 	defer cleanupRequestedScope()
 	if result.Token == nil {
-		return output.ErrAuth("authorization succeeded but no token returned")
+		return errs.NewAuthenticationError(errs.SubtypeTokenMissing, "authorization succeeded but no token returned")
 	}
 
 	// Get user info
 	log(msg.AuthSuccess)
 	sdk, err := f.LarkClient()
 	if err != nil {
-		return output.ErrAuth("failed to get SDK: %v", err)
+		return errs.NewInternalError(errs.SubtypeSDKError, "failed to get SDK: %v", err).WithCause(err)
 	}
 	openId, userName, err := getUserInfo(opts.Ctx, sdk, result.Token.AccessToken)
 	if err != nil {
-		return output.ErrAuth("failed to get user info: %v", err)
+		return errs.NewAuthenticationError(errs.SubtypeUnknown, "failed to get user info: %v", err).WithCause(err)
 	}
 
 	scopeSummary := loadLoginScopeSummary(config.AppID, openId, requestedScope, result.Token.Scope)
@@ -435,13 +455,13 @@ func authLoginPollDeviceCode(opts *LoginOptions, config *core.CliConfig, msg *lo
 		GrantedAt:        now,
 	}
 	if err := larkauth.SetStoredToken(storedToken); err != nil {
-		return output.Errorf(output.ExitInternal, "internal", "failed to save token: %v", err)
+		return errs.NewInternalError(errs.SubtypeSDKError, "failed to save token: %v", err).WithCause(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 output.Errorf(output.ExitInternal, "internal", "failed to update login profile: %v", err)
+		return errs.NewInternalError(errs.SubtypeSDKError, "failed to update login profile: %v", err).WithCause(err)
 	}
 
 	if issue := ensureRequestedScopesGranted(requestedScope, result.Token.Scope, msg, scopeSummary); issue != nil {
@@ -452,21 +472,22 @@ 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 fmt.Errorf("load config: %w", err)
+		return errs.NewInternalError(errs.SubtypeStorage, "load config: %v", err).WithCause(err)
 	}
 
 	app := findProfileByName(multi, profileName)
 	if app == nil {
-		return fmt.Errorf("profile %q not found in config", profileName)
+		return errs.NewConfigError(errs.SubtypeNotConfigured, "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 fmt.Errorf("save config: %w", err)
+		return errs.NewInternalError(errs.SubtypeStorage, "save config: %v", err).WithCause(err)
 	}
 
 	for _, oldUser := range oldUsers {
@@ -477,6 +498,7 @@ 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 {
@@ -490,7 +512,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) []string {
+func collectScopesForDomains(domains []string, identity string, brand core.LarkBrand) []string {
 	scopeSet := make(map[string]bool)
 
 	// 1. API scopes from from_meta projects
@@ -509,6 +531,9 @@ func collectScopesForDomains(domains []string, identity string) []string {
 
 	// 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
@@ -528,7 +553,7 @@ func collectScopesForDomains(domains []string, identity string) []string {
 // 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() map[string]bool {
+func allKnownDomains(brand core.LarkBrand) map[string]bool {
 	domains := make(map[string]bool)
 	for _, p := range registry.ListFromMetaProjects() {
 		if !registry.HasAuthDomain(p) {
@@ -536,6 +561,9 @@ func allKnownDomains() map[string]bool {
 		}
 	}
 	for _, sc := range shortcuts.AllShortcuts() {
+		if !shortcuts.IsShortcutServiceAvailable(sc.Service, brand) {
+			continue
+		}
 		if !registry.HasAuthDomain(sc.Service) {
 			domains[sc.Service] = true
 		}
@@ -544,8 +572,8 @@ func allKnownDomains() map[string]bool {
 }
 
 // sortedKnownDomains returns all valid domain names sorted alphabetically.
-func sortedKnownDomains() []string {
-	m := allKnownDomains()
+func sortedKnownDomains(brand core.LarkBrand) []string {
+	m := allKnownDomains(brand)
 	domains := make([]string, 0, len(m))
 	for d := range m {
 		domains = append(domains, d)

cmd/auth/login_brand_filter_test.go

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

cmd/auth/login_interactive.go

@@ -10,7 +10,9 @@ 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"
@@ -90,22 +92,17 @@ func buildDomainMeta(name, lang string) domainMeta {
 			Description: desc,
 		}
 	}
-	// Fallback: read from from_meta spec (legacy)
-	meta := registry.LoadFromMeta(name)
+	// Fallback: read from the typed service spec (legacy)
 	dm := domainMeta{Name: name}
-	if meta != nil {
-		if t, ok := meta["title"].(string); ok {
-			dm.Title = t
-		}
-		if d, ok := meta["description"].(string); ok {
-			dm.Description = d
-		}
+	if svc, ok := registry.ServiceTyped(name); ok {
+		dm.Title = svc.Title
+		dm.Description = svc.Description
 	}
 	return dm
 }
 
 // runInteractiveLogin shows an interactive TUI form for domain and permission selection.
-func runInteractiveLogin(ios *cmdutil.IOStreams, lang string, msg *loginMsg) (*interactiveResult, error) {
+func runInteractiveLogin(ios *cmdutil.IOStreams, lang string, msg *loginMsg, brand core.LarkBrand) (*interactiveResult, error) {
 	allDomains := getDomainMetadata(lang)
 
 	// Build multi-select options
@@ -161,11 +158,11 @@ func runInteractiveLogin(ios *cmdutil.IOStreams, lang string, msg *loginMsg) (*i
 	}
 
 	if len(selectedDomains) == 0 {
-		return nil, output.ErrValidation("no domains selected")
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "no domains selected").WithParam("--domain")
 	}
 
 	// Compute scope summary
-	scopes := collectScopesForDomains(selectedDomains, "user")
+	scopes := collectScopesForDomains(selectedDomains, "user", brand)
 	if permLevel == "common" {
 		scopes = registry.FilterAutoApproveScopes(scopes)
 	}

cmd/auth/login_messages.go

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

cmd/auth/login_messages_test.go

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

cmd/auth/login_result.go

@@ -8,6 +8,7 @@ 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"
@@ -171,20 +172,12 @@ func handleLoginScopeIssue(opts *LoginOptions, msg *loginMsg, f *cmdutil.Factory
 			fmt.Fprintln(f.IOStreams.Out, string(b))
 			return output.ErrBare(output.ExitAuth)
 		}
-		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,
-			},
-		}
+		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...)
 	}
 
 	fmt.Fprintln(f.IOStreams.ErrOut)

cmd/auth/login_result_test.go

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

cmd/auth/login_test.go

@@ -9,6 +9,7 @@ import (
 	"errors"
 	"io"
 	"net/http"
+	"slices"
 	"sort"
 	"strings"
 	"testing"
@@ -171,7 +172,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 +186,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 +196,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))
 	}
@@ -214,13 +215,19 @@ func TestGetShortcutOnlyDomainNames_HaveDescriptions(t *testing.T) {
 	}
 }
 
+func TestGetShortcutOnlyDomainNames_IncludesNote(t *testing.T) {
+	if !slices.Contains(getShortcutOnlyDomainNames(), "note") {
+		t.Fatal("shortcut-only domains must include note so auth login can select vc:note:read")
+	}
+}
+
 func TestCollectScopesForDomains(t *testing.T) {
 	projects := registry.ListFromMetaProjects()
 	if len(projects) == 0 {
 		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 +254,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))
 	}
@@ -400,12 +407,11 @@ func TestHandleLoginScopeIssue_NonJSONAlignsWithLoginSuccess(t *testing.T) {
 			Granted:   []string{"base:app:copy"},
 		},
 	}, "ou_user", "tester")
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected ExitError, got %v", err)
+	if err == nil {
+		t.Fatal("expected error, got nil")
 	}
-	if exitErr.Code != output.ExitAuth {
-		t.Fatalf("exit code = %d, want %d", exitErr.Code, output.ExitAuth)
+	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitAuth {
+		t.Fatalf("exit code = %d, want %d", gotCode, output.ExitAuth)
 	}
 	got := stderr.String()
 	for _, want := range []string{
@@ -443,12 +449,11 @@ func TestHandleLoginScopeIssue_JSONAlignsWithLoginSuccess(t *testing.T) {
 			Granted:   []string{"base:app:copy"},
 		},
 	}, "ou_user", "tester")
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected ExitError, got %v", err)
+	if err == nil {
+		t.Fatal("expected error, got nil")
 	}
-	if exitErr.Code != output.ExitAuth {
-		t.Fatalf("exit code = %d, want %d", exitErr.Code, output.ExitAuth)
+	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitAuth {
+		t.Fatalf("exit code = %d, want %d", gotCode, output.ExitAuth)
 	}
 
 	var data map[string]interface{}
@@ -653,12 +658,11 @@ func TestAuthLoginRun_MissingRequestedScopeAlignsWithLoginSuccess(t *testing.T)
 		Ctx:     context.Background(),
 		Scope:   "im:message:send",
 	})
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected ExitError, got %v", err)
+	if err == nil {
+		t.Fatal("expected error, got nil")
 	}
-	if exitErr.Code != output.ExitAuth {
-		t.Fatalf("exit code = %d, want %d", exitErr.Code, output.ExitAuth)
+	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitAuth {
+		t.Fatalf("exit code = %d, want %d", gotCode, output.ExitAuth)
 	}
 	got := stderr.String()
 	for _, want := range []string{
@@ -870,6 +874,90 @@ 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",
@@ -945,17 +1033,27 @@ func TestAuthLoginRun_NoWaitJSONHintIncludesRawURLGuidance(t *testing.T) {
 	}
 	hint, _ := data["hint"].(string)
 	for _, want := range []string{
-		"exactly as returned by the CLI",
+		"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",
 		"opaque string",
-		"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",
+		"cannot be modified",
 		"final message of the turn",
 		"return control to the user",
 		"do not block on --device-code in the same turn",
-		"After the user confirms authorization in a later step",
-		"lark-cli auth login --device-code device-code",
+		"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",
 	} {
 		if !strings.Contains(hint, want) {
 			t.Fatalf("hint missing %q, got:\n%s", want, hint)
@@ -1054,12 +1152,17 @@ func TestAuthLoginRun_JSONDeviceAuthorizationAgentHintIncludesRawURLGuidance(t *
 		"结束本轮",
 		"用户回复已完成授权",
 		"不要在同一轮里展示 URL 后立刻阻塞执行 --device-code",
-		"逐字原样转发 CLI 返回的 URL",
+		"必须生成二维码并展示",
+		"lark-cli auth qrcode",
+		"优先生成 PNG 二维码（--output）",
+		"仅当用户明确要求时才使用 ASCII（--ascii）",
+		"生成后必须在回复中展示图片",
+		"仅生成文件不算完成",
+		"image 标签或内联图片",
+		"二维码图片置于 URL 下方完整展示",
+		"URL 输出规则",
 		"opaque string",
-		"不要做 URL 编码或解码",
-		"不要补 `%20`、空格或标点",
-		"不要改写成 Markdown 链接",
-		"只包含该 URL 的代码块单独输出",
+		"不要做任何修改",
 	} {
 		if !strings.Contains(hint, want) {
 			t.Fatalf("agent_hint missing %q, got:\n%s", want, hint)
@@ -1077,7 +1180,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)")
 	}
@@ -1087,7 +1190,7 @@ func TestAllKnownDomains_ExcludesAuthDomainChildren(t *testing.T) {
 }
 
 func TestCollectScopesForDomains_ExpandsAuthDomainChildren(t *testing.T) {
-	scopes := collectScopesForDomains([]string{"docs"}, "user")
+	scopes := collectScopesForDomains([]string{"docs"}, "user", "")
 	// docs domain should include whiteboard shortcut scopes (board:whiteboard:*)
 	found := false
 	for _, s := range scopes {

cmd/auth/logout.go

@@ -8,6 +8,7 @@ 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"
@@ -17,6 +18,7 @@ import (
 // LogoutOptions holds all inputs for auth logout.
 type LogoutOptions struct {
 	Factory *cmdutil.Factory
+	JSON    bool
 }
 
 // NewCmdAuthLogout creates the auth logout subcommand.
@@ -33,6 +35,7 @@ func NewCmdAuthLogout(f *cmdutil.Factory, runF func(*LogoutOptions) error) *cobr
 			return authLogoutRun(opts)
 		},
 	}
+	cmd.Flags().BoolVar(&opts.JSON, "json", false, "structured JSON output")
 	cmdutil.SetRisk(cmd, "write")
 
 	return cmd
@@ -43,24 +46,64 @@ func authLogoutRun(opts *LogoutOptions) error {
 
 	multi, _ := core.LoadMultiAppConfig()
 	if multi == nil || len(multi.Apps) == 0 {
+		if opts.JSON {
+			output.PrintJson(f.IOStreams.Out, map[string]interface{}{
+				"ok":        true,
+				"loggedOut": false,
+				"reason":    "not_configured",
+			})
+			return nil
+		}
 		fmt.Fprintln(f.IOStreams.ErrOut, "No configuration found.")
 		return nil
 	}
 
 	app := multi.CurrentAppConfig(f.Invocation.Profile)
 	if app == nil || len(app.Users) == 0 {
+		if opts.JSON {
+			output.PrintJson(f.IOStreams.Out, map[string]interface{}{
+				"ok":        true,
+				"loggedOut": false,
+				"reason":    "not_logged_in",
+			})
+			return nil
+		}
 		fmt.Fprintln(f.IOStreams.ErrOut, "Not logged in.")
 		return nil
 	}
 
+	httpClient, httpErr := f.HttpClient()
+	appSecret, secretErr := core.ResolveSecretInput(app.AppSecret, f.Keychain)
+
 	for _, user := range app.Users {
+		if httpErr == nil && secretErr == nil {
+			if token := larkauth.GetStoredToken(app.AppId, user.UserOpenId); token != nil {
+				revokeToken := token.RefreshToken
+				tokenTypeHint := "refresh_token"
+				if revokeToken == "" {
+					revokeToken = token.AccessToken
+					tokenTypeHint = "access_token"
+				}
+				if revokeToken != "" {
+					_ = larkauth.RevokeToken(httpClient, app.AppId, appSecret, app.Brand, revokeToken, tokenTypeHint)
+				}
+			}
+		}
 		if err := larkauth.RemoveStoredToken(app.AppId, user.UserOpenId); err != nil {
 			fmt.Fprintf(f.IOStreams.ErrOut, "Warning: failed to remove token for %s: %v\n", user.UserOpenId, err)
 		}
 	}
+
 	app.Users = []core.AppUser{}
 	if err := core.SaveMultiAppConfig(multi); err != nil {
-		return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
+		return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+	}
+	if opts.JSON {
+		output.PrintJson(f.IOStreams.Out, map[string]interface{}{
+			"ok":        true,
+			"loggedOut": true,
+		})
+		return nil
 	}
 	output.PrintSuccess(f.IOStreams.ErrOut, "Logged out")
 	return nil

cmd/auth/logout_test.go

@@ -0,0 +1,356 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package auth
+
+import (
+	"encoding/json"
+	"net/url"
+	"strings"
+	"testing"
+
+	larkauth "github.com/larksuite/cli/internal/auth"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/zalando/go-keyring"
+)
+
+func writeLogoutConfig(t *testing.T, users []core.AppUser) {
+	t.Helper()
+	if err := core.SaveMultiAppConfig(&core.MultiAppConfig{
+		CurrentApp: "test-app",
+		Apps: []core.AppConfig{
+			{
+				AppId:     "test-app",
+				AppSecret: core.PlainSecret("test-secret"),
+				Brand:     core.BrandFeishu,
+				Users:     users,
+			},
+		},
+	}); err != nil {
+		t.Fatalf("SaveMultiAppConfig() error = %v", err)
+	}
+}
+
+func TestAuthLogoutRun_JSONMode_NotConfigured_WritesStdoutOnly(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
+	if err := authLogoutRun(&LogoutOptions{Factory: f, JSON: true}); err != nil {
+		t.Fatalf("authLogoutRun() error = %v", err)
+	}
+
+	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"])
+	}
+	if payload["loggedOut"] != false {
+		t.Errorf("stdout.loggedOut = %v, want false", payload["loggedOut"])
+	}
+	if payload["reason"] != "not_configured" {
+		t.Errorf("stdout.reason = %v, want not_configured", payload["reason"])
+	}
+	if stderr.Len() != 0 {
+		t.Errorf("stderr must stay empty in JSON mode, got:\n%s", stderr.String())
+	}
+}
+
+func TestAuthLogoutRun_JSONMode_NotLoggedIn_WritesStdoutOnly(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	writeLogoutConfig(t, nil)
+
+	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
+	if err := authLogoutRun(&LogoutOptions{Factory: f, JSON: true}); err != nil {
+		t.Fatalf("authLogoutRun() error = %v", err)
+	}
+
+	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"])
+	}
+	if payload["loggedOut"] != false {
+		t.Errorf("stdout.loggedOut = %v, want false", payload["loggedOut"])
+	}
+	if payload["reason"] != "not_logged_in" {
+		t.Errorf("stdout.reason = %v, want not_logged_in", payload["reason"])
+	}
+	if stderr.Len() != 0 {
+		t.Errorf("stderr must stay empty in JSON mode, got:\n%s", stderr.String())
+	}
+}
+
+func TestAuthLogoutRun_JSONMode_Success_WritesStdoutOnly(t *testing.T) {
+	keyring.MockInit()
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("LARKSUITE_CLI_DATA_DIR", t.TempDir())
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	writeLogoutConfig(t, []core.AppUser{{UserOpenId: "ou_user", UserName: "tester"}})
+	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
+		AppId:      "test-app",
+		UserOpenId: "ou_user",
+	}); err != nil {
+		t.Fatalf("SetStoredToken() error = %v", err)
+	}
+
+	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
+	if err := authLogoutRun(&LogoutOptions{Factory: f, JSON: true}); err != nil {
+		t.Fatalf("authLogoutRun() error = %v", err)
+	}
+
+	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"])
+	}
+	if payload["loggedOut"] != true {
+		t.Errorf("stdout.loggedOut = %v, want true", payload["loggedOut"])
+	}
+	if _, hasReason := payload["reason"]; hasReason {
+		t.Errorf("stdout.reason must be absent on success, got %v", payload["reason"])
+	}
+	if stderr.Len() != 0 {
+		t.Errorf("stderr must stay empty in JSON mode, got:\n%s", stderr.String())
+	}
+}
+
+func TestAuthLogoutRun_DefaultMode_KeepsTextOutput(t *testing.T) {
+	keyring.MockInit()
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("LARKSUITE_CLI_DATA_DIR", t.TempDir())
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	writeLogoutConfig(t, []core.AppUser{{UserOpenId: "ou_user", UserName: "tester"}})
+	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
+		AppId:      "test-app",
+		UserOpenId: "ou_user",
+	}); err != nil {
+		t.Fatalf("SetStoredToken() error = %v", err)
+	}
+
+	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
+	if err := authLogoutRun(&LogoutOptions{Factory: f}); err != nil {
+		t.Fatalf("authLogoutRun() error = %v", err)
+	}
+
+	if stdout.Len() != 0 {
+		t.Errorf("stdout must stay empty in default mode, got:\n%s", stdout.String())
+	}
+	if !strings.Contains(stderr.String(), "Logged out") {
+		t.Errorf("stderr = %q, want success text", stderr.String())
+	}
+}
+
+func TestAuthLogoutRun_RevokesTokenAndClearsLocalState(t *testing.T) {
+	keyring.MockInit()
+	setupLoginConfigDir(t)
+	t.Setenv("HOME", t.TempDir())
+
+	multi := &core.MultiAppConfig{
+		CurrentApp: "default",
+		Apps: []core.AppConfig{
+			{
+				Name:      "default",
+				AppId:     "cli_test",
+				AppSecret: core.PlainSecret("secret"),
+				Brand:     core.BrandFeishu,
+				Users:     []core.AppUser{{UserOpenId: "ou_user", UserName: "tester"}},
+			},
+		},
+	}
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		t.Fatalf("SaveMultiAppConfig() error = %v", err)
+	}
+	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
+		AppId:        "cli_test",
+		UserOpenId:   "ou_user",
+		AccessToken:  "user-access-token",
+		RefreshToken: "user-refresh-token",
+	}); err != nil {
+		t.Fatalf("SetStoredToken() error = %v", err)
+	}
+
+	f, _, 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.PathOAuthRevoke,
+		Body:   map[string]interface{}{"code": 0},
+		BodyFilter: func(body []byte) bool {
+			values, err := url.ParseQuery(string(body))
+			if err != nil {
+				return false
+			}
+			return values.Get("client_id") == "cli_test" &&
+				values.Get("client_secret") == "secret" &&
+				values.Get("token") == "user-refresh-token" &&
+				values.Get("token_type_hint") == "refresh_token"
+		},
+	})
+
+	if err := authLogoutRun(&LogoutOptions{Factory: f}); err != nil {
+		t.Fatalf("authLogoutRun() error = %v", err)
+	}
+
+	if got := stderr.String(); !strings.Contains(got, "Logged out") {
+		t.Fatalf("stderr = %q, want Logged out", got)
+	}
+	if got := larkauth.GetStoredToken("cli_test", "ou_user"); got != nil {
+		t.Fatalf("expected stored token removed, got %#v", got)
+	}
+	saved, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatalf("LoadMultiAppConfig() error = %v", err)
+	}
+	if len(saved.Apps) != 1 || len(saved.Apps[0].Users) != 0 {
+		t.Fatalf("expected users cleared, got %#v", saved.Apps)
+	}
+}
+
+func TestAuthLogoutRun_FallsBackToAccessTokenWhenRefreshTokenMissing(t *testing.T) {
+	keyring.MockInit()
+	setupLoginConfigDir(t)
+	t.Setenv("HOME", t.TempDir())
+
+	multi := &core.MultiAppConfig{
+		CurrentApp: "default",
+		Apps: []core.AppConfig{
+			{
+				Name:      "default",
+				AppId:     "cli_test",
+				AppSecret: core.PlainSecret("secret"),
+				Brand:     core.BrandFeishu,
+				Users:     []core.AppUser{{UserOpenId: "ou_user", UserName: "tester"}},
+			},
+		},
+	}
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		t.Fatalf("SaveMultiAppConfig() error = %v", err)
+	}
+	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
+		AppId:       "cli_test",
+		UserOpenId:  "ou_user",
+		AccessToken: "user-access-token",
+	}); err != nil {
+		t.Fatalf("SetStoredToken() error = %v", err)
+	}
+
+	f, _, 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.PathOAuthRevoke,
+		Body:   map[string]interface{}{"code": 0},
+		BodyFilter: func(body []byte) bool {
+			values, err := url.ParseQuery(string(body))
+			if err != nil {
+				return false
+			}
+			return values.Get("client_id") == "cli_test" &&
+				values.Get("client_secret") == "secret" &&
+				values.Get("token") == "user-access-token" &&
+				values.Get("token_type_hint") == "access_token"
+		},
+	})
+
+	if err := authLogoutRun(&LogoutOptions{Factory: f}); err != nil {
+		t.Fatalf("authLogoutRun() error = %v", err)
+	}
+
+	if got := stderr.String(); !strings.Contains(got, "Logged out") {
+		t.Fatalf("stderr = %q, want Logged out", got)
+	}
+	if got := larkauth.GetStoredToken("cli_test", "ou_user"); got != nil {
+		t.Fatalf("expected stored token removed, got %#v", got)
+	}
+	saved, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatalf("LoadMultiAppConfig() error = %v", err)
+	}
+	if len(saved.Apps) != 1 || len(saved.Apps[0].Users) != 0 {
+		t.Fatalf("expected users cleared, got %#v", saved.Apps)
+	}
+}
+
+func TestAuthLogoutRun_RevokeFailureStillClearsLocalState(t *testing.T) {
+	keyring.MockInit()
+	setupLoginConfigDir(t)
+	t.Setenv("HOME", t.TempDir())
+
+	multi := &core.MultiAppConfig{
+		CurrentApp: "default",
+		Apps: []core.AppConfig{
+			{
+				Name:      "default",
+				AppId:     "cli_test",
+				AppSecret: core.PlainSecret("secret"),
+				Brand:     core.BrandFeishu,
+				Users:     []core.AppUser{{UserOpenId: "ou_user", UserName: "tester"}},
+			},
+		},
+	}
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		t.Fatalf("SaveMultiAppConfig() error = %v", err)
+	}
+	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
+		AppId:        "cli_test",
+		UserOpenId:   "ou_user",
+		AccessToken:  "user-access-token",
+		RefreshToken: "user-refresh-token",
+	}); err != nil {
+		t.Fatalf("SetStoredToken() error = %v", err)
+	}
+
+	f, _, 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.PathOAuthRevoke,
+		Status: 500,
+		Body:   map[string]interface{}{"error": "server_error"},
+	})
+
+	if err := authLogoutRun(&LogoutOptions{Factory: f}); err != nil {
+		t.Fatalf("authLogoutRun() error = %v", err)
+	}
+
+	gotErr := stderr.String()
+	if strings.Contains(gotErr, "failed to revoke token for ou_user") {
+		t.Fatalf("stderr = %q, want no revoke warning", gotErr)
+	}
+	if !strings.Contains(gotErr, "Logged out") {
+		t.Fatalf("stderr = %q, want Logged out", gotErr)
+	}
+	if got := larkauth.GetStoredToken("cli_test", "ou_user"); got != nil {
+		t.Fatalf("expected stored token removed, got %#v", got)
+	}
+	saved, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatalf("LoadMultiAppConfig() error = %v", err)
+	}
+	if len(saved.Apps) != 1 || len(saved.Apps[0].Users) != 0 {
+		t.Fatalf("expected users cleared, got %#v", saved.Apps)
+	}
+}

cmd/auth/qrcode.go

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

cmd/auth/qrcode_test.go

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

cmd/auth/scopes.go

@@ -9,6 +9,7 @@ import (
 
 	"github.com/spf13/cobra"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/output"
 )
@@ -18,6 +19,7 @@ type ScopesOptions struct {
 	Factory *cmdutil.Factory
 	Ctx     context.Context
 	Format  string
+	JSON    bool
 }
 
 // NewCmdAuthScopes creates the auth scopes subcommand.
@@ -29,6 +31,9 @@ func NewCmdAuthScopes(f *cmdutil.Factory, runF func(*ScopesOptions) error) *cobr
 		Short: "Query scopes enabled for the app",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.Ctx = cmd.Context()
+			if opts.JSON {
+				opts.Format = "json"
+			}
 			if runF != nil {
 				return runF(opts)
 			}
@@ -37,6 +42,7 @@ func NewCmdAuthScopes(f *cmdutil.Factory, runF func(*ScopesOptions) error) *cobr
 	}
 
 	cmd.Flags().StringVar(&opts.Format, "format", "json", "output format: json (default) | pretty")
+	cmd.Flags().BoolVar(&opts.JSON, "json", false, "structured JSON output")
 	cmdutil.SetRisk(cmd, "read")
 
 	return cmd
@@ -50,11 +56,23 @@ func authScopesRun(opts *ScopesOptions) error {
 		return err
 	}
 	fmt.Fprintf(f.IOStreams.ErrOut, "Querying app scopes...\n\n")
-	appInfo, err := getAppInfo(opts.Ctx, f, config.AppID)
+	appInfo, err := getAppInfoFn(opts.Ctx, f, config.AppID)
 	if err != nil {
-		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.")
+		// 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)
 	}
 	if opts.Format == "pretty" {
 		fmt.Fprintf(f.IOStreams.ErrOut, "App ID: %s\n", config.AppID)

cmd/auth/scopes_test.go

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

cmd/auth/status.go

@@ -17,6 +17,7 @@ import (
 type StatusOptions struct {
 	Factory *cmdutil.Factory
 	Verify  bool
+	JSON    bool
 }
 
 // NewCmdAuthStatus creates the auth status subcommand.
@@ -35,6 +36,7 @@ func NewCmdAuthStatus(f *cmdutil.Factory, runF func(*StatusOptions) error) *cobr
 	}
 
 	cmd.Flags().BoolVar(&opts.Verify, "verify", false, "verify token against server (requires network)")
+	cmd.Flags().BoolVar(&opts.JSON, "json", false, "structured JSON output")
 	cmdutil.SetRisk(cmd, "read")
 
 	return cmd
@@ -61,7 +63,6 @@ func authStatusRun(opts *StatusOptions) error {
 	diagnostics := identitydiag.Diagnose(context.Background(), f, config, opts.Verify)
 	result["identities"] = diagnostics
 	result["identity"] = effectiveIdentity(diagnostics)
-	addLegacyUserFields(result, diagnostics.User)
 	addEffectiveVerification(result, diagnostics)
 	addStatusNote(result, diagnostics)
 
@@ -86,29 +87,6 @@ func effectiveIdentity(d identitydiag.Result) string {
 	}
 }
 
-func addLegacyUserFields(result map[string]interface{}, user identitydiag.Identity) {
-	if user.OpenID == "" {
-		return
-	}
-	result["userName"] = user.UserName
-	result["userOpenId"] = user.OpenID
-	if user.TokenStatus != "" {
-		result["tokenStatus"] = user.TokenStatus
-	}
-	if user.Scope != "" {
-		result["scope"] = user.Scope
-	}
-	if user.ExpiresAt != "" {
-		result["expiresAt"] = user.ExpiresAt
-	}
-	if user.RefreshExpiresAt != "" {
-		result["refreshExpiresAt"] = user.RefreshExpiresAt
-	}
-	if user.GrantedAt != "" {
-		result["grantedAt"] = user.GrantedAt
-	}
-}
-
 func addEffectiveVerification(result map[string]interface{}, d identitydiag.Result) {
 	switch result["identity"] {
 	case identityUser:

cmd/build.go

@@ -6,6 +6,7 @@ package cmd
 import (
 	"context"
 	"io"
+	"io/fs"
 
 	"github.com/larksuite/cli/cmd/api"
 	"github.com/larksuite/cli/cmd/auth"
@@ -16,6 +17,7 @@ import (
 	"github.com/larksuite/cli/cmd/profile"
 	"github.com/larksuite/cli/cmd/schema"
 	"github.com/larksuite/cli/cmd/service"
+	"github.com/larksuite/cli/cmd/skill"
 	cmdupdate "github.com/larksuite/cli/cmd/update"
 	_ "github.com/larksuite/cli/events"
 	"github.com/larksuite/cli/internal/build"
@@ -51,6 +53,18 @@ func WithKeychain(kc keychain.KeychainAccess) BuildOption {
 	}
 }
 
+// embeddedSkillContent is the skill tree wired into cmdutil.Factory.SkillContent
+// at build time. It is registered by the repo-root package main's init via
+// SetEmbeddedSkillContent — it cannot be threaded through main.go without
+// breaking the single-file preview build (see skills_embed.go). nil in builds
+// that embed no skills; the `skills` commands then return a typed internal error.
+var embeddedSkillContent fs.FS
+
+// SetEmbeddedSkillContent registers the embedded skill tree. Called from the
+// repo-root package main's init; a wrapper main can call it before Execute to
+// supply its own skill content.
+func SetEmbeddedSkillContent(fsys fs.FS) { embeddedSkillContent = fsys }
+
 // HideProfile sets the visibility policy for the root-level --profile flag.
 // When hide is true the flag stays registered (so existing invocations still
 // parse) but is omitted from help and shell completion. Typically called as
@@ -103,6 +117,7 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 	if cfg.keychain != nil {
 		f.Keychain = cfg.keychain
 	}
+	f.SkillContent = embeddedSkillContent
 	rootCmd := &cobra.Command{
 		Use:     "lark-cli",
 		Short:   "Lark/Feishu CLI — OAuth authorization, UAT management, API calls",
@@ -117,6 +132,13 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 
 	installTipsHelpFunc(rootCmd)
 	rootCmd.SilenceErrors = true
+	// SilenceUsage as a static field (not only in PersistentPreRun) so it also
+	// covers flag-parse errors, which fail before PreRun runs — otherwise cobra
+	// dumps usage instead of our structured error. SetFlagErrorFunc on root is
+	// inherited by every subcommand, turning unknown-flag errors into a
+	// structured "did you mean" envelope.
+	rootCmd.SilenceUsage = true
+	rootCmd.SetFlagErrorFunc(flagDidYouMean)
 
 	RegisterGlobalFlags(rootCmd.PersistentFlags(), &cfg.globals)
 	rootCmd.PersistentPreRun = func(cmd *cobra.Command, args []string) {
@@ -133,6 +155,7 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 	rootCmd.AddCommand(completion.NewCmdCompletion(f))
 	rootCmd.AddCommand(cmdupdate.NewCmdUpdate(f))
 	rootCmd.AddCommand(cmdevent.NewCmdEvents(f))
+	rootCmd.AddCommand(skill.NewCmdSkill(f))
 	service.RegisterServiceCommandsWithContext(ctx, rootCmd, f)
 	shortcuts.RegisterShortcutsWithContext(ctx, rootCmd, f)
 

cmd/cmdexample_catalog_test.go

@@ -0,0 +1,160 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd_test
+
+import (
+	"sort"
+	"strings"
+)
+
+// universalFlags are accepted by every command (cobra auto-injects help; the
+// root injects version). They are never reported as unknown.
+var universalFlags = map[string]bool{"--help": true, "-h": true, "--version": true}
+
+// catalog is the source-of-truth command catalog: command path -> accepted flag
+// tokens. A path is the command words WITHOUT the "lark-cli" root prefix, e.g.
+// "contact +search-user". The root command is the empty path "".
+type catalog struct {
+	flagsByPath map[string]map[string]bool
+	group       map[string]bool // paths that are parent groups (have subcommands)
+	sorted      []string        // cached sorted paths for suggestCommand; invalidated on addCommand
+}
+
+func newCatalog() *catalog {
+	return &catalog{
+		flagsByPath: map[string]map[string]bool{},
+		group:       map[string]bool{},
+	}
+}
+
+// setGroup records whether path is a parent group (has subcommands). Leftover
+// words after a group node are unknown subcommands; after a leaf they are
+// positionals (e.g. "api GET /path").
+func (c *catalog) setGroup(path string, isGroup bool) {
+	if isGroup {
+		c.group[path] = true
+	}
+}
+
+func (c *catalog) isGroup(path string) bool { return c.group[path] }
+
+// addCommand registers a command path and the flags it accepts. Repeated calls
+// for the same path union the flag sets. flags are full tokens ("--query", "-q").
+func (c *catalog) addCommand(path string, flags []string) {
+	set := c.flagsByPath[path]
+	if set == nil {
+		set = map[string]bool{}
+		c.flagsByPath[path] = set
+	}
+	for _, f := range flags {
+		set[f] = true
+	}
+	c.sorted = nil // invalidate cached suggestion list
+}
+
+func (c *catalog) hasCommand(path string) bool {
+	_, ok := c.flagsByPath[path]
+	return ok
+}
+
+// hasFlag reports whether flag is accepted by command path (universal flags
+// always pass).
+func (c *catalog) hasFlag(path, flag string) bool {
+	if universalFlags[flag] {
+		return true
+	}
+	set := c.flagsByPath[path]
+	return set[flag]
+}
+
+// longestPrefix returns the longest known command path that is a prefix of
+// words, plus how many words it consumed. This separates real subcommands from
+// trailing positionals (e.g. "api GET /path" resolves to "api"). When words is
+// empty it falls back to the root command. ok=false means not even the first
+// word names a command.
+func (c *catalog) longestPrefix(words []string) (path string, n int, ok bool) {
+	if len(words) == 0 {
+		if c.hasCommand("") {
+			return "", 0, true
+		}
+		return "", 0, false
+	}
+	for i := len(words); i >= 1; i-- {
+		cand := strings.Join(words[:i], " ")
+		if c.hasCommand(cand) {
+			return cand, i, true
+		}
+	}
+	return "", 0, false
+}
+
+// paths returns all known command paths, sorted.
+func (c *catalog) paths() []string {
+	out := make([]string, 0, len(c.flagsByPath))
+	for p := range c.flagsByPath {
+		out = append(out, p)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// suggestCommand returns the known command path closest to want (small edit
+// distance), for error hints. Returns "" when nothing is reasonably close.
+func (c *catalog) suggestCommand(want string) string {
+	if c.sorted == nil {
+		c.sorted = c.paths() // built once after the catalog is fully populated
+	}
+	return closest(want, c.sorted)
+}
+
+// suggestFlag returns the flag of path closest to flag, for error hints.
+func (c *catalog) suggestFlag(path, flag string) string {
+	set := c.flagsByPath[path]
+	cands := make([]string, 0, len(set))
+	for f := range set {
+		cands = append(cands, f)
+	}
+	sort.Strings(cands)
+	return closest(flag, cands)
+}
+
+// closest returns the candidate with the smallest Levenshtein distance to want,
+// but only if that distance is within a tolerance scaled to want's length
+// (avoids absurd suggestions).
+func closest(want string, cands []string) string {
+	best := ""
+	bestD := 1 << 30
+	for _, cand := range cands {
+		d := levenshtein(want, cand)
+		if d < bestD {
+			bestD, best = d, cand
+		}
+	}
+	tol := len(want)/2 + 1
+	if bestD > tol {
+		return ""
+	}
+	return best
+}
+
+func levenshtein(a, b string) int {
+	ra, rb := []rune(a), []rune(b)
+	prev := make([]int, len(rb)+1)
+	for j := range prev {
+		prev[j] = j
+	}
+	for i := 1; i <= len(ra); i++ {
+		cur := make([]int, len(rb)+1)
+		cur[0] = i
+		for j := 1; j <= len(rb); j++ {
+			cost := 1
+			if ra[i-1] == rb[j-1] {
+				cost = 0
+			}
+			cur[j] = min(prev[j]+1, cur[j-1]+1, prev[j-1]+cost)
+		}
+		prev = cur
+	}
+	return prev[len(rb)]
+}

cmd/cmdexample_check_test.go

@@ -0,0 +1,60 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd_test
+
+import "strings"
+
+// Finding kinds.
+const (
+	unknownCommand = "unknown_command"
+	unknownFlag    = "unknown_flag"
+)
+
+// finding is a single mismatch between an example command reference and the
+// catalog.
+type finding struct {
+	line    int
+	raw     string
+	kind    string // unknownCommand | unknownFlag
+	path    string // resolved command path (unknownFlag) or attempted path (unknownCommand)
+	flag    string // offending flag (unknownFlag only)
+	suggest string // nearest known command/flag, "" if none close
+}
+
+// checkRefs validates refs against cat and returns all mismatches in order.
+func checkRefs(cat *catalog, refs []ref) []finding {
+	var out []finding
+	for _, r := range refs {
+		path, n, ok := cat.longestPrefix(r.words)
+		if !ok {
+			attempted := strings.Join(r.words, " ")
+			out = append(out, finding{
+				line: r.line, raw: r.raw, kind: unknownCommand,
+				path: attempted, suggest: cat.suggestCommand(attempted),
+			})
+			continue
+		}
+		// Leftover words after a group node are an unknown subcommand (e.g. a
+		// mistyped method like "batch_modify_message"). After a leaf they are
+		// positionals (e.g. "api GET /path"), so only groups trigger this.
+		if n < len(r.words) && cat.isGroup(path) {
+			attempted := strings.Join(r.words, " ")
+			out = append(out, finding{
+				line: r.line, raw: r.raw, kind: unknownCommand,
+				path: attempted, suggest: cat.suggestCommand(attempted),
+			})
+			continue
+		}
+		for _, f := range r.flags {
+			if cat.hasFlag(path, f) {
+				continue
+			}
+			out = append(out, finding{
+				line: r.line, raw: r.raw, kind: unknownFlag,
+				path: path, flag: f, suggest: cat.suggestFlag(path, f),
+			})
+		}
+	}
+	return out
+}

cmd/cmdexample_parse_test.go

@@ -0,0 +1,222 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd_test
+
+import (
+	"regexp"
+	"strings"
+)
+
+// ref is one lark-cli command reference extracted from a shortcut example.
+type ref struct {
+	line  int      // 1-based line number (the line where the command starts)
+	raw   string   // reconstructed command text, for error display
+	words []string // command words before the first flag (subcommand candidates)
+	flags []string // flag tokens used, e.g. "--query", "-q"
+}
+
+const cliToken = "lark-cli"
+
+// subcommandStart guards against false positives from prose: a real command's
+// first word is ASCII (a service name or a +shortcut). A token starting with
+// CJK / punctuation is treated as narration, not a command.
+var subcommandStart = regexp.MustCompile(`^[A-Za-z+]`)
+
+// shellStops are standalone tokens that terminate a command (pipes, redirects,
+// separators). Separators glued to a token (`get;`, `foo|`) are handled inline.
+var shellStops = map[string]bool{
+	"|": true, "||": true, "&&": true, "&": true, ";": true,
+	">": true, ">>": true, "<": true, "2>": true, "2>&1": true,
+}
+
+// wordTrailPunct is sentence / CJK punctuation that can cling to a command word
+// in prose ("auth login." / "auth login，"); stripped so the word still resolves
+// instead of being dropped as an unknown command or non-ASCII narration.
+const wordTrailPunct = `.,;:!?"')]}，。、；：！？）】」』`
+
+// parseRefs extracts every lark-cli command reference from text (a shortcut's
+// Tips line, which may embed an "Example: lark-cli ..." command). It is
+// deliberately format-agnostic: it keys on the "lark-cli" token whether it sits
+// in a ```bash fence, an inline `code` span, or bare prose. Backslash
+// line-continuations are joined first so a multi-line invocation is parsed as
+// one command; inline-code backticks and trailing # comments terminate it.
+func parseRefs(content string) []ref {
+	var refs []ref
+	lines := strings.Split(content, "\n")
+	for i := 0; i < len(lines); i++ {
+		lineNo := i + 1
+		logical := lines[i]
+		// Shell line continuation: a trailing backslash joins the next physical
+		// line. Without this, flags on the continuation lines of a multi-line
+		// `lark-cli ... \` example are never seen by the checker.
+		for endsWithBackslash(logical) && i+1 < len(lines) {
+			logical = strings.TrimRight(logical, " \t")
+			logical = logical[:len(logical)-1] // drop the trailing backslash
+			i++
+			logical += " " + lines[i]
+		}
+		refs = append(refs, parseLine(logical, lineNo)...)
+	}
+	return refs
+}
+
+func endsWithBackslash(s string) bool {
+	return strings.HasSuffix(strings.TrimRight(s, " \t"), `\`)
+}
+
+func parseLine(line string, lineNo int) []ref {
+	var refs []ref
+	rest := line
+	for {
+		idx := strings.Index(rest, cliToken)
+		if idx < 0 {
+			break
+		}
+		after := rest[idx+len(cliToken):]
+		beforeOK := idx == 0 || isBoundary(rest[idx-1])
+		afterOK := after == "" || isBoundary(after[0])
+		if beforeOK && afterOK {
+			if words, flags, raw, ok := parseCmd(after); ok {
+				refs = append(refs, ref{line: lineNo, raw: cliToken + raw, words: words, flags: flags})
+			}
+		}
+		rest = after
+	}
+	return refs
+}
+
+// parseCmd tokenizes the text following "lark-cli" into leading command words
+// (the subcommand path, up to the first flag) and flag tokens. It stops at a
+// shell separator (standalone or glued), an inline-code backtick, a comment, or
+// a placeholder/prose word. ok=false filters out non-commands.
+func parseCmd(after string) (words, flags []string, raw string, ok bool) {
+	// An inline code span ends at the next backtick; a command never spans one.
+	if i := strings.IndexByte(after, '`'); i >= 0 {
+		after = after[:i]
+	}
+	// Drop $(...) command substitutions so flags belonging to the inner command
+	// (e.g. `--data "$(jq -n --arg x ...)"`) are not mistaken for lark-cli flags.
+	after = stripCmdSubst(after)
+
+	var kept []string
+	inFlags := false
+	for _, orig := range strings.Fields(after) {
+		tok := orig
+		if shellStops[tok] || strings.HasPrefix(tok, "#") {
+			break
+		}
+		// A shell separator glued to a token ends the command mid-token
+		// ("get;", "foo|next"): keep the part before it, handle it, then stop.
+		stop := false
+		if i := strings.IndexAny(tok, ";|"); i >= 0 {
+			tok, stop = tok[:i], true
+		}
+		switch {
+		case tok == "" || tok == "-":
+			// empty (after a glued separator) or a bare stdin marker — skip
+		case strings.HasPrefix(tok, "-"):
+			if f := normalizeFlag(tok); f != "" {
+				inFlags = true
+				flags = append(flags, f)
+				kept = append(kept, tok)
+			}
+		case inFlags:
+			// positional / flag value after the first flag — not a command word
+			kept = append(kept, tok)
+		default:
+			// Command-path word. ASCII placeholder markers (<x>, [x], {x|y},
+			// +<verb>, ...) end the command — checked on the RAW token so the
+			// trailing-punct stripping below cannot erase a "..." ellipsis
+			// ("base +..." must stay a placeholder, not become "+").
+			if strings.ContainsAny(tok, "<>[]{}|") || strings.Contains(tok, "...") {
+				stop = true
+				break
+			}
+			// Strip trailing sentence/CJK punctuation so "login." / "login，"
+			// resolve to "login"; non-ASCII narration ends the command.
+			w := strings.TrimRight(tok, wordTrailPunct)
+			if w == "" || hasNonASCII(w) {
+				stop = true
+				break
+			}
+			words = append(words, w)
+			kept = append(kept, tok)
+		}
+		if stop {
+			break
+		}
+	}
+	if len(kept) > 0 {
+		raw = " " + strings.Join(kept, " ")
+	}
+	// Keep root-only refs ("lark-cli --help") and refs whose first word looks
+	// like a subcommand; drop prose ("lark-cli 就能搞定 ...").
+	if len(words) == 0 {
+		return words, flags, raw, len(flags) > 0
+	}
+	if !subcommandStart.MatchString(words[0]) {
+		return nil, nil, "", false
+	}
+	return words, flags, raw, true
+}
+
+// stripCmdSubst removes $(...) command substitutions (including nested ones)
+// from s, leaving the surrounding text intact. Backtick substitutions are
+// already handled upstream (a command never spans a backtick).
+func stripCmdSubst(s string) string {
+	var b strings.Builder
+	depth := 0
+	for i := 0; i < len(s); i++ {
+		if depth == 0 && i+1 < len(s) && s[i] == '$' && s[i+1] == '(' {
+			depth = 1
+			i++ // skip '('
+			continue
+		}
+		if depth > 0 {
+			switch s[i] {
+			case '(':
+				depth++
+			case ')':
+				depth--
+			}
+			continue
+		}
+		b.WriteByte(s[i])
+	}
+	return b.String()
+}
+
+// isPlaceholderOrProse reports whether a command word is a doc placeholder
+// (<resource>, [flags], {a|b}, +<verb>, ...) or narration (CJK / other
+// non-ASCII), rather than a literal command token.
+func isPlaceholderOrProse(w string) bool {
+	if hasNonASCII(w) {
+		return true
+	}
+	return strings.ContainsAny(w, "<>[]{}|") || strings.Contains(w, "...")
+}
+
+func hasNonASCII(s string) bool {
+	return strings.IndexFunc(s, func(r rune) bool { return r > 127 }) >= 0
+}
+
+// flagShape matches the leading flag token, stripping any trailing junk such as
+// a "=value" suffix or punctuation that bled in from the surrounding markdown
+// ("--help\"", "--help;", "--params={}"). The underscore is allowed because
+// real flags use it ("--input_format", "--output_as"). Returns "" for non-flags.
+var flagShape = regexp.MustCompile(`^--?[A-Za-z][A-Za-z0-9_-]*`)
+
+// normalizeFlag extracts the canonical flag token from tok, or "" if tok is not
+// a real flag (e.g. a shell-string fragment like "-草稿'").
+func normalizeFlag(tok string) string {
+	return flagShape.FindString(tok)
+}
+
+func isBoundary(b byte) bool {
+	switch b {
+	case ' ', '\t', '`', '(', ')', '\'', '"', '*':
+		return true
+	}
+	return false
+}

cmd/cmdexample_test.go

@@ -0,0 +1,113 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// This file and its cmdexample_*_test.go siblings implement a test-only check:
+// the example commands embedded in shortcut definitions (the "Example: lark-cli
+// ..." lines in each shortcut's Tips, shown in --help) must match the real
+// command tree. It lives entirely in _test.go files (package cmd_test) so it
+// ships in no binary and is not importable by product code; the truth source is
+// cmd.Build, the same tree the binary uses, so the check cannot drift.
+//
+// It runs in the standard unit-test CI job (go test ./cmd/...). A mismatch — an
+// example using a renamed command or an unaccepted flag — fails that job.
+
+package cmd_test
+
+import (
+	"context"
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/cmd"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/shortcuts"
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+// TestShortcutExampleCommands checks the example commands embedded in every
+// shortcut's Tips against the live command tree. A shortcut that defines no
+// example is simply skipped.
+//
+// Because the examples and the command definitions live in the same Go code,
+// this is a self-consistency check: any mismatch (an example using a renamed
+// command or a flag the command doesn't accept) is a bug to fix at the source.
+// It runs over all shortcuts — no baseline, no diff — since a wrong example is
+// always a defect, never acceptable "pre-existing drift".
+func TestShortcutExampleCommands(t *testing.T) {
+	// Reproducibility: use the embedded API metadata (not a developer's stale
+	// ~/.lark-cli remote cache, which can miss commands) and an empty config
+	// dir so local strict mode / plugins / policy cannot reshape the tree.
+	// t.Setenv auto-restores after the test, so other cmd tests are unaffected.
+	t.Setenv("LARKSUITE_CLI_REMOTE_META", "off")
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	cat := buildCmdExampleCatalog()
+
+	type located struct {
+		shortcut string
+		f        finding
+	}
+	var findings []located
+	for _, sc := range shortcuts.AllShortcuts() {
+		var refs []ref
+		for _, tip := range sc.Tips {
+			refs = append(refs, parseRefs(tip)...)
+		}
+		label := strings.TrimSpace(sc.Service + " " + sc.Command)
+		for _, f := range checkRefs(cat, refs) {
+			findings = append(findings, located{shortcut: label, f: f})
+		}
+	}
+
+	if len(findings) == 0 {
+		return
+	}
+	sort.Slice(findings, func(i, j int) bool { return findings[i].shortcut < findings[j].shortcut })
+	for _, lf := range findings {
+		hint := ""
+		if lf.f.suggest != "" {
+			hint = "  (did you mean " + lf.f.suggest + "?)"
+		}
+		if lf.f.kind == unknownFlag {
+			t.Errorf("shortcut %q example uses unknown flag %s on %q%s\n      %s",
+				lf.shortcut, lf.f.flag, lf.f.path, hint, strings.TrimSpace(lf.f.raw))
+		} else {
+			t.Errorf("shortcut %q example uses unknown command %q%s\n      %s",
+				lf.shortcut, lf.f.path, hint, strings.TrimSpace(lf.f.raw))
+		}
+	}
+	t.Fatalf("%d shortcut example command(s) don't match the real CLI — "+
+		"fix the Example in the shortcut definition.", len(findings))
+}
+
+// buildCmdExampleCatalog walks the live cobra command tree and records every
+// command path (minus the "lark-cli" root prefix) with its accepted flags and
+// whether it is a parent group. This is the same Build() the binary uses, so
+// the catalog can never drift from the real commands.
+func buildCmdExampleCatalog() *catalog {
+	root := cmd.Build(context.Background(), cmdutil.InvocationContext{})
+	cat := newCatalog()
+	var walk func(c *cobra.Command)
+	walk = func(c *cobra.Command) {
+		path := strings.TrimSpace(strings.TrimPrefix(c.CommandPath(), "lark-cli"))
+		var flags []string
+		add := func(fl *pflag.Flag) {
+			flags = append(flags, "--"+fl.Name)
+			if fl.Shorthand != "" {
+				flags = append(flags, "-"+fl.Shorthand)
+			}
+		}
+		c.Flags().VisitAll(add)
+		c.InheritedFlags().VisitAll(add)
+		c.PersistentFlags().VisitAll(add) // root's own persistent flags (e.g. --profile)
+		cat.addCommand(path, flags)
+		cat.setGroup(path, c.HasSubCommands())
+		for _, sub := range c.Commands() {
+			walk(sub)
+		}
+	}
+	walk(root)
+	return cat
+}

cmd/cmdexample_units_test.go

@@ -0,0 +1,233 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd_test
+
+import (
+	"strings"
+	"testing"
+)
+
+func testCatalog() *catalog {
+	c := newCatalog()
+	c.addCommand("", []string{"--profile"}) // root
+	c.setGroup("", true)
+	c.addCommand("contact", []string{"--profile"})
+	c.setGroup("contact", true)
+	c.addCommand("contact +search-user", []string{"--query", "--as", "--format", "-q"})
+	c.addCommand("api", []string{"--params", "--data", "--as"}) // leaf (no subcommands)
+	c.addCommand("mail", nil)
+	c.setGroup("mail", true)
+	c.addCommand("mail user_mailbox.messages", []string{"--profile"})
+	c.setGroup("mail user_mailbox.messages", true)
+	c.addCommand("mail user_mailbox.messages batch_modify", []string{"--params", "--data"})
+	return c
+}
+
+func TestCmdExampleCatalogHasCommandAndFlag(t *testing.T) {
+	c := testCatalog()
+	if !c.hasCommand("contact +search-user") {
+		t.Fatal("expected contact +search-user to exist")
+	}
+	if c.hasCommand("contact +nope") {
+		t.Fatal("did not expect contact +nope")
+	}
+	if !c.hasFlag("contact +search-user", "--query") {
+		t.Fatal("--query should be valid")
+	}
+	if c.hasFlag("contact +search-user", "--nope") {
+		t.Fatal("--nope should be invalid")
+	}
+	// universal flags pass on any command
+	for _, f := range []string{"--help", "-h", "--version"} {
+		if !c.hasFlag("contact +search-user", f) {
+			t.Fatalf("universal flag %s should pass", f)
+		}
+	}
+}
+
+func TestCmdExampleLongestPrefix(t *testing.T) {
+	c := testCatalog()
+	tests := []struct {
+		words  []string
+		want   string
+		wantN  int
+		wantOK bool
+	}{
+		{[]string{"contact", "+search-user"}, "contact +search-user", 2, true},
+		{[]string{"api", "GET", "/open-apis/x"}, "api", 1, true}, // trailing positionals
+		{[]string{"nope"}, "", 0, false},
+		{nil, "", 0, true}, // empty -> root
+	}
+	for _, tt := range tests {
+		got, n, ok := c.longestPrefix(tt.words)
+		if got != tt.want || n != tt.wantN || ok != tt.wantOK {
+			t.Errorf("longestPrefix(%v) = (%q,%d,%v), want (%q,%d,%v)",
+				tt.words, got, n, ok, tt.want, tt.wantN, tt.wantOK)
+		}
+	}
+}
+
+func refWordsOf(refs []ref) [][]string {
+	var out [][]string
+	for _, r := range refs {
+		out = append(out, r.words)
+	}
+	return out
+}
+
+func TestCmdExampleParseRefsExtractsCommands(t *testing.T) {
+	content := strings.Join([]string{
+		"运行 `lark-cli contact +search-user --query 张三` 搜索", // inline code
+		"```bash",
+		"lark-cli api GET /open-apis/x --params '{}'", // bash block
+		"```",
+		"用 lark-cli mail user_mailbox.messages batch_modify 即可", // bare prose command
+		"npx foo | lark-cli api GET /y",                         // after a pipe
+	}, "\n")
+	refs := parseRefs(content)
+	if len(refs) != 4 {
+		t.Fatalf("expected 4 refs, got %d: %v", len(refs), refWordsOf(refs))
+	}
+	if got := refs[0]; strings.Join(got.words, " ") != "contact +search-user" ||
+		len(got.flags) != 1 || got.flags[0] != "--query" {
+		t.Errorf("ref0 = %+v", got)
+	}
+	if got := refs[1]; strings.Join(got.words, " ") != "api GET /open-apis/x" {
+		t.Errorf("ref1 words = %v", got.words)
+	}
+}
+
+func TestCmdExampleParseRefsFiltersPlaceholdersAndProse(t *testing.T) {
+	// A line whose first word is prose yields no command at all.
+	if refs := parseRefs("lark-cli 就能搞定这件事"); len(refs) != 0 {
+		t.Errorf("prose-first line should yield 0 refs, got %v", refWordsOf(refs))
+	}
+	// Syntax templates / trailing prose may leave a real leading word ("mail"),
+	// but no placeholder or CJK token may leak into the command words — that is
+	// what prevents false positives like an "<resource>" unknown-command report.
+	for _, line := range []string{
+		"lark-cli mail <resource> <method> [flags]",
+		"lark-cli apps +<verb> [flags]",
+		"lark-cli base +...",
+		"lark-cli mail 写信场景下的格式说明",
+	} {
+		for _, r := range parseRefs(line) {
+			for _, w := range r.words {
+				if isPlaceholderOrProse(w) {
+					t.Errorf("%q: placeholder/prose token %q leaked into words %v", line, w, r.words)
+				}
+			}
+		}
+	}
+}
+
+func TestCmdExampleParseRefsStripsTrailingJunk(t *testing.T) {
+	// frontmatter-style quoted value: the trailing quote must not bleed into the flag
+	refs := parseRefs(`cliHelp: "lark-cli contact --help"`)
+	if len(refs) != 1 {
+		t.Fatalf("expected 1 ref, got %d", len(refs))
+	}
+	if len(refs[0].flags) != 1 || refs[0].flags[0] != "--help" {
+		t.Errorf("expected flag --help, got %v", refs[0].flags)
+	}
+	// bare "-" (stdin marker) and "=value" suffix
+	refs = parseRefs("lark-cli api GET /x --params={} --data -")
+	if len(refs) != 1 {
+		t.Fatalf("expected 1 ref, got %d", len(refs))
+	}
+	flags := strings.Join(refs[0].flags, " ")
+	if flags != "--params --data" {
+		t.Errorf("expected '--params --data', got %q", flags)
+	}
+}
+
+func TestCmdExampleCheck(t *testing.T) {
+	c := testCatalog()
+	tests := []struct {
+		name     string
+		r        ref
+		wantKind string // "" = no finding
+		wantPath string
+	}{
+		{"valid shortcut", ref{words: []string{"contact", "+search-user"}, flags: []string{"--query"}}, "", ""},
+		{"valid leaf positional", ref{words: []string{"api", "GET", "/x"}}, "", ""},
+		{"unknown top command", ref{words: []string{"nope"}}, unknownCommand, "nope"},
+		{"group leftover = unknown subcommand",
+			ref{words: []string{"mail", "user_mailbox.messages", "batch_modify_message"}},
+			unknownCommand, "mail user_mailbox.messages batch_modify_message"},
+		{"unknown flag", ref{words: []string{"contact", "+search-user"}, flags: []string{"--nope"}}, unknownFlag, "contact +search-user"},
+		{"universal flag ok", ref{words: []string{"contact", "+search-user"}, flags: []string{"--help"}}, "", ""},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			fs := checkRefs(c, []ref{tt.r})
+			if tt.wantKind == "" {
+				if len(fs) != 0 {
+					t.Fatalf("expected no finding, got %+v", fs)
+				}
+				return
+			}
+			if len(fs) != 1 {
+				t.Fatalf("expected 1 finding, got %d: %+v", len(fs), fs)
+			}
+			if fs[0].kind != tt.wantKind || fs[0].path != tt.wantPath {
+				t.Errorf("got kind=%s path=%q, want kind=%s path=%q", fs[0].kind, fs[0].path, tt.wantKind, tt.wantPath)
+			}
+		})
+	}
+}
+
+func TestCmdExampleCheckSuggestsNearest(t *testing.T) {
+	c := testCatalog()
+	fs := checkRefs(c, []ref{{words: []string{"mail", "user_mailbox.messages", "batch_modify_message"}}})
+	if len(fs) != 1 || fs[0].suggest != "mail user_mailbox.messages batch_modify" {
+		t.Fatalf("expected suggestion 'mail user_mailbox.messages batch_modify', got %+v", fs)
+	}
+}
+
+// TestCmdExampleParseRefsRobustness covers the parser edge cases hardened after
+// review: backslash continuation, underscore flags, $(...) substitution, glued
+// separators, trailing punctuation, and the "..." placeholder.
+func TestCmdExampleParseRefsRobustness(t *testing.T) {
+	cases := []struct {
+		name, content, wantWords, wantFlags string
+		wantRefs                            int
+	}{
+		{"backslash continuation joins flags",
+			"lark-cli contact +search-user \\\n  --query foo \\\n  --as user",
+			"contact +search-user", "--query --as", 1},
+		{"underscore flag not truncated",
+			"lark-cli whiteboard +update --input_format mermaid",
+			"whiteboard +update", "--input_format", 1},
+		{"command-substitution flags ignored",
+			`lark-cli slides x create --data "$(jq -n --arg c '{}')" --as user`,
+			"slides x create", "--data --as", 1},
+		{"glued separator truncates",
+			"lark-cli auth login; echo done",
+			"auth login", "", 1},
+		{"trailing CJK punctuation stripped",
+			"用 lark-cli auth login。",
+			"auth login", "", 1},
+		{"ellipsis placeholder stays placeholder",
+			"lark-cli base +...",
+			"base", "", 1},
+	}
+	for _, tt := range cases {
+		t.Run(tt.name, func(t *testing.T) {
+			refs := parseRefs(tt.content)
+			if len(refs) != tt.wantRefs {
+				t.Fatalf("refs=%d want %d: %v", len(refs), tt.wantRefs, refWordsOf(refs))
+			}
+			if tt.wantRefs == 0 {
+				return
+			}
+			if got := strings.Join(refs[0].words, " "); got != tt.wantWords {
+				t.Errorf("words=%q want %q", got, tt.wantWords)
+			}
+			if got := strings.Join(refs[0].flags, " "); got != tt.wantFlags {
+				t.Errorf("flags=%q want %q", got, tt.wantFlags)
+			}
+		})
+	}
+}

cmd/command_catalog_path_test.go

@@ -0,0 +1,52 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd
+
+import (
+	"reflect"
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+// TestCommandCatalogPath pins that the auth-hint path reconstruction inverts the
+// service command tree for any depth — flat dotted resources AND genuinely
+// nested resources — so it round-trips through apicatalog.Resolve instead of
+// assuming a fixed root->service->resource->method shape.
+func TestCommandCatalogPath(t *testing.T) {
+	chain := func(names ...string) *cobra.Command {
+		var parent, leaf *cobra.Command
+		for _, n := range names {
+			c := &cobra.Command{Use: n}
+			if parent != nil {
+				parent.AddCommand(c)
+			}
+			parent = c
+			leaf = c
+		}
+		return leaf
+	}
+
+	tests := []struct {
+		name string
+		leaf *cobra.Command
+		want []string
+	}{
+		{"flat dotted resource", chain("lark-cli", "im", "chat.members", "create"), []string{"im", "chat.members", "create"}},
+		{"nested resources", chain("lark-cli", "im", "spaces", "items", "get"), []string{"im", "spaces", "items", "get"}},
+		{"service level", chain("lark-cli", "im"), []string{"im"}},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := commandCatalogPath(tt.leaf); !reflect.DeepEqual(got, tt.want) {
+				t.Errorf("commandCatalogPath = %v, want %v", got, tt.want)
+			}
+		})
+	}
+
+	// The root command (no parent) has no catalog path.
+	if got := commandCatalogPath(&cobra.Command{Use: "lark-cli"}); len(got) != 0 {
+		t.Errorf("root path = %v, want empty", got)
+	}
+}

cmd/config/bind.go

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

cmd/config/bind_messages.go

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

cmd/config/bind_test.go

@@ -13,30 +13,59 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/output"
 )
 
-// assertExitError checks the full structured error in one assertion.
+// assertExitError checks the full structured error in one assertion. It
+// accepts both *output.ExitError (used by output.ErrWithHint) and the
+// typed 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.).
 func assertExitError(t *testing.T, err error, wantCode int, wantDetail output.ErrDetail) {
 	t.Helper()
 	if err == nil {
 		t.Fatal("expected error, got nil")
 	}
 	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("error type = %T, want *output.ExitError; error = %v", err, err)
+	if errors.As(err, &exitErr) {
+		if exitErr.Code != wantCode {
+			t.Errorf("exit code = %d, want %d", exitErr.Code, wantCode)
+		}
+		if exitErr.Detail == nil {
+			t.Fatal("expected non-nil error detail")
+		}
+		if !reflect.DeepEqual(*exitErr.Detail, wantDetail) {
+			t.Errorf("error detail mismatch:\n  got:  %+v\n  want: %+v", *exitErr.Detail, wantDetail)
+		}
+		return
 	}
-	if exitErr.Code != wantCode {
-		t.Errorf("exit code = %d, want %d", exitErr.Code, wantCode)
+	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.Detail == nil {
-		t.Fatal("expected non-nil error detail")
-	}
-	if !reflect.DeepEqual(*exitErr.Detail, wantDetail) {
-		t.Errorf("error detail mismatch:\n  got:  %+v\n  want: %+v", *exitErr.Detail, wantDetail)
+	var 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
 	}
+	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
@@ -105,14 +134,229 @@ func TestConfigBindCmd_LangDefault(t *testing.T) {
 	if err := cmd.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	if gotOpts.Lang != "zh" {
-		t.Errorf("Lang = %q, want default %q", gotOpts.Lang, "zh")
+	if gotOpts.Lang != "" {
+		t.Errorf("Lang = %q, want default %q (unset)", gotOpts.Lang, "")
 	}
 	if gotOpts.langExplicit {
 		t.Error("expected langExplicit=false when --lang not passed")
 	}
 }
 
+// TestConfigBindRun_InvalidLang verifies a non-empty --lang is strictly
+// validated: wrong case, typos, and removed codes all exit with
+// ExitValidation (code 2) and a message identifying the offending value.
+// (Empty is not invalid — see TestConfigBindRun_EmptyLangIsNoOp.)
+func TestConfigBindRun_InvalidLang(t *testing.T) {
+	saveWorkspace(t)
+	configDir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", configDir)
+	hermesHome := t.TempDir()
+	t.Setenv("HERMES_HOME", hermesHome)
+	if err := os.WriteFile(filepath.Join(hermesHome, ".env"), []byte("FEISHU_APP_ID=cli_abc\nFEISHU_APP_SECRET=secret\n"), 0600); err != nil {
+		t.Fatalf("write .env: %v", err)
+	}
+
+	cases := []struct {
+		name string
+		lang string
+	}{
+		{"wrong case ZH", "ZH"},
+		{"typo frr", "frr"},
+		{"removed code ar", "ar"},
+		{"unknown xx", "xx"},
+		{"hyphen form zh-CN", "zh-CN"},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			f, _, _, _ := cmdutil.TestFactory(t, nil)
+			err := configBindRun(&BindOptions{
+				Factory:      f,
+				Source:       "hermes",
+				Lang:         tc.lang,
+				langExplicit: true,
+			})
+			if err == nil {
+				t.Fatalf("expected validation error for --lang %q, got nil", tc.lang)
+			}
+			exitErr, ok := err.(*output.ExitError)
+			if !ok {
+				t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+			}
+			if exitErr.Code != output.ExitValidation {
+				t.Errorf("exit code = %d, want %d (validation)", exitErr.Code, output.ExitValidation)
+			}
+			if !strings.Contains(exitErr.Error(), "invalid --lang") {
+				t.Errorf("error message %q does not contain 'invalid --lang'", exitErr.Error())
+			}
+		})
+	}
+}
+
+// TestConfigBindRun_EmptyLangIsNoOp verifies that an empty --lang (omitted or
+// explicit "") is unset: it neither errors nor persists a language, while a
+// non-empty short code or Feishu locale both canonicalize to the same locale.
+func TestConfigBindRun_EmptyLangIsNoOp(t *testing.T) {
+	cases := []struct {
+		name     string
+		lang     string
+		explicit bool
+		wantLang i18n.Lang
+	}{
+		{"omitted", "", false, ""},
+		{"explicit empty", "", true, ""},
+		{"short code", "ja", true, i18n.LangJaJP},
+		{"feishu locale", "ja_jp", true, i18n.LangJaJP},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			saveWorkspace(t)
+			t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+			hermesHome := t.TempDir()
+			t.Setenv("HERMES_HOME", hermesHome)
+			if err := os.WriteFile(filepath.Join(hermesHome, ".env"), []byte("FEISHU_APP_ID=cli_abc\nFEISHU_APP_SECRET=secret\n"), 0600); err != nil {
+				t.Fatalf("write .env: %v", err)
+			}
+
+			f, _, _, _ := cmdutil.TestFactory(t, nil)
+			if err := configBindRun(&BindOptions{
+				Factory:      f,
+				Source:       "hermes",
+				Lang:         tc.lang,
+				langExplicit: tc.explicit,
+			}); err != nil {
+				t.Fatalf("configBindRun(--lang %q) = %v, want nil", tc.lang, err)
+			}
+
+			multi, err := core.LoadMultiAppConfig()
+			if err != nil {
+				t.Fatalf("LoadMultiAppConfig: %v", err)
+			}
+			app := multi.CurrentAppConfig("")
+			if app == nil {
+				t.Fatal("no app persisted")
+			}
+			if app.Lang != tc.wantLang {
+				t.Errorf("persisted Lang = %q, want %q", app.Lang, tc.wantLang)
+			}
+		})
+	}
+}
+
+// TestConfigBindRun_OmitLangPreservesPrior guards against a re-bind without
+// --lang silently dropping a previously stored preference (appConfig is rebuilt
+// fresh, so commitBinding must inherit the prior Lang).
+func TestConfigBindRun_OmitLangPreservesPrior(t *testing.T) {
+	saveWorkspace(t)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	hermesHome := t.TempDir()
+	t.Setenv("HERMES_HOME", hermesHome)
+	if err := os.WriteFile(filepath.Join(hermesHome, ".env"), []byte("FEISHU_APP_ID=cli_abc\nFEISHU_APP_SECRET=secret\n"), 0600); err != nil {
+		t.Fatalf("write .env: %v", err)
+	}
+
+	f1, _, _, _ := cmdutil.TestFactory(t, nil)
+	if err := configBindRun(&BindOptions{Factory: f1, Source: "hermes", Lang: "ja", langExplicit: true}); err != nil {
+		t.Fatalf("first bind (--lang ja): %v", err)
+	}
+	f2, _, _, _ := cmdutil.TestFactory(t, nil)
+	if err := configBindRun(&BindOptions{Factory: f2, Source: "hermes", Lang: "", langExplicit: false}); err != nil {
+		t.Fatalf("re-bind (no --lang): %v", err)
+	}
+
+	multi, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatalf("LoadMultiAppConfig: %v", err)
+	}
+	if app := multi.CurrentAppConfig(""); app == nil || app.Lang != i18n.LangJaJP {
+		t.Errorf("Lang after re-bind = %v, want %q (preserved)", app, i18n.LangJaJP)
+	}
+}
+
+// TestPriorLang_RespectsCurrentApp guards against priorLang scanning all apps
+// and silently returning a non-current profile's Lang. In a multi-profile
+// workspace (set up via `profile add` before a re-bind), the active profile's
+// Lang must win over a sibling profile that happens to sit earlier in the slice.
+func TestPriorLang_RespectsCurrentApp(t *testing.T) {
+	multi := core.MultiAppConfig{
+		CurrentApp: "active",
+		Apps: []core.AppConfig{
+			{Name: "stale", AppId: "cli_stale", Lang: i18n.LangJaJP},
+			{Name: "active", AppId: "cli_active", Lang: i18n.LangEnUS},
+		},
+	}
+	bytes, err := json.Marshal(multi)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	if got := priorLang(bytes); got != i18n.LangEnUS {
+		t.Errorf("priorLang = %q, want %q (must follow CurrentApp, not Apps[0])", got, i18n.LangEnUS)
+	}
+}
+
+// TestPriorLang_FallsBackToFirstAppWhenCurrentUnset covers the legacy
+// single-app shape (no CurrentApp): CurrentAppConfig falls back to Apps[0],
+// so a bind-written config (which always has exactly one app and no
+// CurrentApp field) still inherits its Lang.
+func TestPriorLang_FallsBackToFirstAppWhenCurrentUnset(t *testing.T) {
+	multi := core.MultiAppConfig{
+		Apps: []core.AppConfig{
+			{AppId: "cli_only", Lang: i18n.LangJaJP},
+		},
+	}
+	bytes, err := json.Marshal(multi)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	if got := priorLang(bytes); got != i18n.LangJaJP {
+		t.Errorf("priorLang = %q, want %q", got, i18n.LangJaJP)
+	}
+}
+
+// TestPriorLang_MalformedReturnsEmpty exercises the unparseable-bytes branch.
+func TestPriorLang_MalformedReturnsEmpty(t *testing.T) {
+	if got := priorLang([]byte("not json")); got != "" {
+		t.Errorf("priorLang(malformed) = %q, want \"\"", got)
+	}
+}
+
+// TestConfigBindRun_EnvelopeMessageFollowsInheritedLang guards the JSON envelope
+// "message" field against regressing to opts.Lang: when --lang is omitted on
+// re-bind, the inherited preference (appConfig.Lang) must drive the message
+// language and the embedded brand display — otherwise an AI agent that set
+// English on first bind sees Chinese in every subsequent re-bind envelope.
+func TestConfigBindRun_EnvelopeMessageFollowsInheritedLang(t *testing.T) {
+	saveWorkspace(t)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	hermesHome := t.TempDir()
+	t.Setenv("HERMES_HOME", hermesHome)
+	if err := os.WriteFile(filepath.Join(hermesHome, ".env"), []byte("FEISHU_APP_ID=cli_abc\nFEISHU_APP_SECRET=secret\n"), 0600); err != nil {
+		t.Fatalf("write .env: %v", err)
+	}
+
+	f1, _, _, _ := cmdutil.TestFactory(t, nil)
+	if err := configBindRun(&BindOptions{Factory: f1, Source: "hermes", Lang: "en", langExplicit: true}); err != nil {
+		t.Fatalf("first bind (--lang en): %v", err)
+	}
+
+	f2, stdout, _, _ := cmdutil.TestFactory(t, nil)
+	if err := configBindRun(&BindOptions{Factory: f2, Source: "hermes", Lang: "", langExplicit: false}); err != nil {
+		t.Fatalf("re-bind (no --lang): %v", err)
+	}
+
+	envelope := map[string]any{}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("invalid JSON output: %v", err)
+	}
+	msg, _ := envelope["message"].(string)
+	enMsg := getBindMsg(i18n.LangEnUS)
+	wantMsg := fmt.Sprintf(enMsg.MessageBotOnly, "cli_abc", "Hermes", brandDisplay("feishu", i18n.LangEnUS))
+	if msg != wantMsg {
+		t.Errorf("envelope.message = %q,\nwant %q (must follow inherited appConfig.Lang=en_us, not raw opts.Lang)", msg, wantMsg)
+	}
+}
+
 // ── Run function tests (aligned with TestConfigShowRun pattern) ──
 
 func TestConfigBindRun_InvalidSource(t *testing.T) {
@@ -139,7 +383,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:    "bind",
+		Type:    "validation",
 		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",
 	})
@@ -178,7 +422,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:    "bind",
+		Type:    "validation",
 		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",
 	})
@@ -194,7 +438,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:    "bind",
+		Type:    "validation",
 		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",
 	})
@@ -322,8 +566,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.ExitValidation, output.ErrDetail{
-		Type:    "hermes",
+	assertExitError(t, err, output.ExitAuth, output.ErrDetail{
+		Type:    "config",
 		Message: "failed to read Hermes config: open " + envPath + ": no such file or directory",
 		Hint:    "verify Hermes is installed and configured at " + envPath,
 	})
@@ -340,8 +584,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.ExitValidation, output.ErrDetail{
-		Type:    "openclaw",
+	assertExitError(t, err, output.ExitAuth, output.ErrDetail{
+		Type:    "config",
 		Message: "cannot read " + configPath + ": open " + configPath + ": no such file or directory",
 		Hint:    "verify OpenClaw is installed and configured",
 	})
@@ -488,7 +732,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:    "bind",
+		Type:    "validation",
 		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",
 	})
@@ -506,8 +750,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.ExitValidation, output.ErrDetail{
-		Type:    "lark-channel",
+	assertExitError(t, err, output.ExitAuth, output.ErrDetail{
+		Type:    "config",
 		Message: "cannot read " + configPath + ": open " + configPath + ": no such file or directory",
 		Hint:    "verify lark-channel-bridge is installed and configured",
 	})
@@ -526,8 +770,8 @@ func TestConfigBindRun_LarkChannelEmptyAppID(t *testing.T) {
 
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "lark-channel"})
-	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
-		Type:    "lark-channel",
+	assertExitError(t, err, output.ExitAuth, output.ErrDetail{
+		Type:    "config",
 		Message: "accounts.app.id missing in " + configPath,
 		Hint:    "run lark-channel-bridge's setup to populate the app credential",
 	})
@@ -545,8 +789,8 @@ func TestConfigBindRun_LarkChannelEmptySecret(t *testing.T) {
 
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "lark-channel"})
-	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
-		Type:    "lark-channel",
+	assertExitError(t, err, output.ExitAuth, output.ErrDetail{
+		Type:    "config",
 		Message: "accounts.app.secret is empty in " + configPath,
 		Hint:    "run lark-channel-bridge's setup to populate the app credential",
 	})
@@ -595,8 +839,10 @@ func TestConfigShowRun_AgentWorkspaceNotBound(t *testing.T) {
 	if !errors.As(err, &cfgErr) {
 		t.Fatalf("error type = %T, want *core.ConfigError", err)
 	}
-	if cfgErr.Code != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", cfgErr.Code, output.ExitValidation)
+	// Config errors share ExitAuth (3); the workspace is detected but no
+	// binding exists yet, which is a config error.
+	if cfgErr.Code != output.ExitAuth {
+		t.Errorf("exit code = %d, want %d (config category → ExitAuth)", cfgErr.Code, output.ExitAuth)
 	}
 	if cfgErr.Type != "openclaw" {
 		t.Errorf("type = %q, want %q", cfgErr.Type, "openclaw")
@@ -895,12 +1141,8 @@ func TestConfigBindRun_OpenClawMultiAccount_MissingAppID(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected error for multi-account without --app-id, got nil")
 	}
-	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)
+	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
+		t.Errorf("exit code = %d, want %d", gotCode, output.ExitValidation)
 	}
 }
 
@@ -946,7 +1188,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:    "openclaw",
+		Type:    "validation",
 		Message: "multiple accounts in openclaw.json; pass --app-id <id>",
 	}
 	wantWorkFirst := base
@@ -954,20 +1196,17 @@ func TestConfigBindRun_OpenClawMultiAccount_TTYFlagMode(t *testing.T) {
 	wantPersonalFirst := base
 	wantPersonalFirst.Hint = "available app IDs:\n  cli_personal_222 (personal)\n  cli_work_111 (work)"
 
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("error type = %T, want *output.ExitError; err = %v", err, err)
+	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
+		t.Errorf("exit code = %d, want %d", gotCode, output.ExitValidation)
 	}
-	if exitErr.Code != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("error type = %T, want *errs.ValidationError; err = %v", err, err)
 	}
-	if exitErr.Detail == nil {
-		t.Fatal("expected non-nil error detail")
-	}
-	if !reflect.DeepEqual(*exitErr.Detail, wantWorkFirst) &&
-		!reflect.DeepEqual(*exitErr.Detail, wantPersonalFirst) {
+	got := output.ErrDetail{Type: string(ve.Category), Message: ve.Message, Hint: ve.Hint}
+	if !reflect.DeepEqual(got, wantWorkFirst) && !reflect.DeepEqual(got, wantPersonalFirst) {
 		t.Errorf("error detail did not match any accepted variant:\n  got:  %+v\n  want: %+v OR %+v",
-			*exitErr.Detail, wantWorkFirst, wantPersonalFirst)
+			got, wantWorkFirst, wantPersonalFirst)
 	}
 }
 
@@ -992,7 +1231,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:    "openclaw",
+		Type:    "validation",
 		Message: `--app-id "nonexistent" not found in openclaw.json`,
 		Hint:    "available app IDs:\n  cli_only_one",
 	})
@@ -1124,11 +1363,19 @@ func TestConfigBindRun_WarnsOnIdentityEscalationWithoutForce(t *testing.T) {
 		Identity: "user-default",
 	})
 	msg := getBindMsg("zh") // flag mode leaves Lang empty → zh default
-	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
-		Type:    "bind",
-		Message: msg.IdentityEscalationMessage,
-		Hint:    msg.IdentityEscalationHint,
-	})
+	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)
+	}
 
 	// Config on disk must remain untouched — the gate runs before
 	// commitBinding writes anything.
@@ -1289,8 +1536,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.ExitValidation, output.ErrDetail{
-		Type:    "hermes",
+	assertExitError(t, err, output.ExitAuth, output.ErrDetail{
+		Type:    "config",
 		Message: "FEISHU_APP_ID not found in " + envPath,
 		Hint:    "run 'hermes setup' to configure Feishu credentials",
 	})
@@ -1309,8 +1556,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.ExitValidation, output.ErrDetail{
-		Type:    "hermes",
+	assertExitError(t, err, output.ExitAuth, output.ErrDetail{
+		Type:    "config",
 		Message: "FEISHU_APP_SECRET not found in " + envPath,
 		Hint:    "run 'hermes setup' to configure Feishu credentials",
 	})
@@ -1335,8 +1582,8 @@ func TestConfigBindRun_OpenClawMissingFeishu(t *testing.T) {
 
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "openclaw"})
-	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
-		Type:    "openclaw",
+	assertExitError(t, err, output.ExitAuth, output.ErrDetail{
+		Type:    "config",
 		Message: "openclaw.json missing channels.feishu section",
 		Hint:    "configure Feishu in OpenClaw first",
 	})
@@ -1363,8 +1610,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.ExitValidation, output.ErrDetail{
-		Type:    "openclaw",
+	assertExitError(t, err, output.ExitAuth, output.ErrDetail{
+		Type:    "config",
 		Message: "appSecret is empty for app cli_no_secret in " + openclawPath,
 		Hint:    "configure channels.feishu.appSecret in openclaw.json",
 	})
@@ -1425,8 +1672,8 @@ func TestConfigBindRun_OpenClawDisabledAccount(t *testing.T) {
 
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	err := configBindRun(&BindOptions{Factory: f, Source: "openclaw"})
-	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
-		Type:    "openclaw",
+	assertExitError(t, err, output.ExitAuth, output.ErrDetail{
+		Type:    "config",
 		Message: "no Feishu app configured in openclaw.json",
 		Hint:    "configure channels.feishu.appId in openclaw.json",
 	})
@@ -1457,10 +1704,14 @@ func TestGetBindMsg_En(t *testing.T) {
 	}
 }
 
-func TestGetBindMsg_UnknownLang_DefaultsToZh(t *testing.T) {
-	msg := getBindMsg("fr")
-	if want := "你想在哪个 Agent 中使用 lark-cli?"; msg.SelectSource != want {
-		t.Errorf("fr (default) SelectSource = %q, want %q", msg.SelectSource, want)
+func TestGetBindMsg_NonEnLang_FallsBackToZh(t *testing.T) {
+	// Only zh and en TUI bundles exist; any non-English language (canonical
+	// locale, short code, or unrecognized value) falls back to zh.
+	for _, lang := range []i18n.Lang{"fr_fr", "ja_jp", "ko", "unknown", ""} {
+		msg := getBindMsg(lang)
+		if want := "你想在哪个 Agent 中使用 lark-cli?"; msg.SelectSource != want {
+			t.Errorf("getBindMsg(%q) SelectSource = %q, want %q (zh fallback)", lang, msg.SelectSource, want)
+		}
 	}
 }
 
@@ -1623,3 +1874,36 @@ func TestHasStrictBotLock(t *testing.T) {
 		})
 	}
 }
+
+// TestConfigBindRun_LangExplicit_PrintsConfirmation covers the flag-mode
+// confirmation line: when --lang is explicit, bind prints "language preference
+// set" to stderr (rendered in the TUI language, embedding the preference value).
+func TestConfigBindRun_LangExplicit_PrintsConfirmation(t *testing.T) {
+	saveWorkspace(t)
+	configDir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", configDir)
+
+	hermesHome := t.TempDir()
+	t.Setenv("HERMES_HOME", hermesHome)
+	if err := os.WriteFile(filepath.Join(hermesHome, ".env"), []byte("FEISHU_APP_ID=cli_abc\nFEISHU_APP_SECRET=secret\n"), 0600); err != nil {
+		t.Fatalf("write .env: %v", err)
+	}
+
+	f, _, stderr, _ := cmdutil.TestFactory(t, nil)
+	err := configBindRun(&BindOptions{
+		Factory:      f,
+		Source:       "hermes",
+		Identity:     "bot-only",
+		Lang:         "en",
+		langExplicit: true,
+	})
+	if err != nil {
+		t.Fatalf("expected success, got error: %v", err)
+	}
+	// The short --lang en is canonicalized to en_us before the confirmation
+	// echoes it back; the TUI language stays zh (flag mode, no picker).
+	want := fmt.Sprintf(getBindMsg(i18n.LangZhCN).LangPreferenceSet, "en_us")
+	if got := stderr.String(); !strings.Contains(got, want) {
+		t.Errorf("stderr = %q, want it to contain confirmation %q", got, want)
+	}
+}

cmd/config/binder.go

@@ -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, output.ErrValidation("unsupported source: %s", source)
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported source: %s", source).WithParam("--source")
 	}
 }
 
@@ -85,11 +85,10 @@ func selectCandidate(
 		// from ListCandidates itself and never reach here.
 		switch src {
 		case "openclaw":
-			return nil, output.ErrWithHint(output.ExitValidation, src,
-				"no Feishu app configured in openclaw.json",
-				"configure channels.feishu.appId in openclaw.json")
+			return nil, errs.NewConfigError(errs.SubtypeNotConfigured, "no Feishu app configured in openclaw.json").
+				WithHint("configure channels.feishu.appId in openclaw.json")
 		default:
-			return nil, output.ErrValidation("%s: no app configured", src)
+			return nil, errs.NewConfigError(errs.SubtypeNotConfigured, "%s: no app configured", src)
 		}
 	}
 
@@ -99,9 +98,9 @@ func selectCandidate(
 				return &candidates[i], nil
 			}
 		}
-		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)))
+		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")
 	}
 
 	if len(candidates) == 1 {
@@ -112,9 +111,9 @@ func selectCandidate(
 		return tuiPrompt(candidates)
 	}
 
-	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)))
+	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")
 }
 
 // formatCandidates renders candidates as "AppID (Label)" lines for error hints.
@@ -149,14 +148,13 @@ 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, output.ErrWithHint(output.ExitValidation, "openclaw",
-			fmt.Sprintf("cannot read %s: %v", b.path, err),
-			"verify OpenClaw is installed and configured")
+		return nil, errs.NewConfigError(errs.SubtypeInvalidConfig, "cannot read %s: %v", b.path, err).
+			WithHint("verify OpenClaw is installed and configured").
+			WithCause(err)
 	}
 	if cfg.Channels.Feishu == nil {
-		return nil, output.ErrWithHint(output.ExitValidation, "openclaw",
-			"openclaw.json missing channels.feishu section",
-			"configure Feishu in OpenClaw first")
+		return nil, errs.NewConfigError(errs.SubtypeNotConfigured, "openclaw.json missing channels.feishu section").
+			WithHint("configure Feishu in OpenClaw first")
 	}
 
 	raw := binding.ListCandidateApps(cfg.Channels.Feishu)
@@ -172,8 +170,7 @@ func (b *openclawBinder) ListCandidates() ([]Candidate, error) {
 
 func (b *openclawBinder) Build(appID string) (*core.AppConfig, error) {
 	if b.cfg == nil {
-		return nil, output.Errorf(output.ExitInternal, "openclaw",
-			"internal: Build called before ListCandidates")
+		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: Build called before ListCandidates")
 	}
 
 	var selected *binding.CandidateApp
@@ -184,26 +181,25 @@ func (b *openclawBinder) Build(appID string) (*core.AppConfig, error) {
 		}
 	}
 	if selected == nil {
-		return nil, output.Errorf(output.ExitInternal, "openclaw",
-			"internal: appID %q not in candidates", appID)
+		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: appID %q not in candidates", appID)
 	}
 
 	if selected.AppSecret.IsZero() {
-		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")
+		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")
 	}
 	secret, err := binding.ResolveSecretInput(selected.AppSecret, b.cfg.Secrets, os.Getenv)
 	if err != nil {
-		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))
+		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)
 	}
 
 	stored, err := core.ForStorage(selected.AppID, core.PlainSecret(secret), b.opts.Factory.Keychain)
 	if err != nil {
-		return nil, output.Errorf(output.ExitInternal, "openclaw",
-			"keychain unavailable: %v\nhint: use file: reference in config to bypass keychain", err)
+		return nil, errs.NewInternalError(errs.SubtypeStorage, "keychain unavailable: %v", err).
+			WithHint("use file: reference in config to bypass keychain").
+			WithCause(err)
 	}
 
 	return &core.AppConfig{
@@ -229,15 +225,14 @@ func (b *hermesBinder) ConfigPath() string { return b.path }
 func (b *hermesBinder) ListCandidates() ([]Candidate, error) {
 	envMap, err := readDotenv(b.path)
 	if err != nil {
-		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))
+		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)
 	}
 	appID := envMap["FEISHU_APP_ID"]
 	if appID == "" {
-		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")
+		return nil, errs.NewConfigError(errs.SubtypeNotConfigured, "FEISHU_APP_ID not found in %s", b.path).
+			WithHint("run 'hermes setup' to configure Feishu credentials")
 	}
 	b.envMap = envMap
 	return []Candidate{{AppID: appID, Label: "default"}}, nil
@@ -245,24 +240,22 @@ func (b *hermesBinder) ListCandidates() ([]Candidate, error) {
 
 func (b *hermesBinder) Build(appID string) (*core.AppConfig, error) {
 	if b.envMap == nil {
-		return nil, output.Errorf(output.ExitInternal, "hermes",
-			"internal: Build called before ListCandidates")
+		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: Build called before ListCandidates")
 	}
 	if b.envMap["FEISHU_APP_ID"] != appID {
-		return nil, output.Errorf(output.ExitInternal, "hermes",
-			"internal: appID %q does not match env", appID)
+		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: appID %q does not match env", appID)
 	}
 	appSecret := b.envMap["FEISHU_APP_SECRET"]
 	if appSecret == "" {
-		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")
+		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "FEISHU_APP_SECRET not found in %s", b.path).
+			WithHint("run 'hermes setup' to configure Feishu credentials")
 	}
 
 	stored, err := core.ForStorage(appID, core.PlainSecret(appSecret), b.opts.Factory.Keychain)
 	if err != nil {
-		return nil, output.Errorf(output.ExitInternal, "hermes",
-			"keychain unavailable: %v\nhint: use file: reference in config to bypass keychain", err)
+		return nil, errs.NewInternalError(errs.SubtypeStorage, "keychain unavailable: %v", err).
+			WithHint("use file: reference in config to bypass keychain").
+			WithCause(err)
 	}
 
 	return &core.AppConfig{
@@ -290,14 +283,13 @@ 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, output.ErrWithHint(output.ExitValidation, "lark-channel",
-			fmt.Sprintf("cannot read %s: %v", b.path, err),
-			"verify lark-channel-bridge is installed and configured")
+		return nil, errs.NewConfigError(errs.SubtypeInvalidConfig, "cannot read %s: %v", b.path, err).
+			WithHint("verify lark-channel-bridge is installed and configured").
+			WithCause(err)
 	}
 	if cfg.Accounts.App.ID == "" {
-		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")
+		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")
 	}
 	b.cfg = cfg
 	return []Candidate{{AppID: cfg.Accounts.App.ID, Label: "default"}}, nil
@@ -305,32 +297,30 @@ func (b *larkChannelBinder) ListCandidates() ([]Candidate, error) {
 
 func (b *larkChannelBinder) Build(appID string) (*core.AppConfig, error) {
 	if b.cfg == nil {
-		return nil, output.Errorf(output.ExitInternal, "lark-channel",
-			"internal: Build called before ListCandidates")
+		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: Build called before ListCandidates")
 	}
 	if b.cfg.Accounts.App.ID != appID {
-		return nil, output.Errorf(output.ExitInternal, "lark-channel",
-			"internal: appID %q does not match config", appID)
+		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: appID %q does not match config", appID)
 	}
 	if b.cfg.Accounts.App.Secret.IsZero() {
-		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")
+		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")
 	}
 
 	// 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)
 	if err != nil {
-		return nil, output.ErrWithHint(output.ExitValidation, "lark-channel",
-			fmt.Sprintf("failed to resolve appSecret for %s: %v", appID, err),
-			fmt.Sprintf("check appSecret configuration in %s", b.path))
+		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, output.Errorf(output.ExitInternal, "lark-channel",
-			"keychain unavailable: %v", err)
+		return nil, errs.NewInternalError(errs.SubtypeStorage, "keychain unavailable: %v", err).
+			WithHint("use file: reference in config to bypass keychain").
+			WithCause(err)
 	}
 
 	return &core.AppConfig{
@@ -389,10 +379,12 @@ func resolveHermesEnvPath() string {
 }
 
 // resolveLarkChannelConfigPath returns the path to lark-channel-bridge's
-// config.json. Mirrors the bridge's src/config/paths.ts which hardcodes
-// ~/.lark-channel/config.json with no env override — multi-instance is not
-// a supported scenario today.
+// source config. LARK_CHANNEL_CONFIG lets a host point bind at a projected
+// single-account config without changing lark-cli's target config directory.
 func resolveLarkChannelConfigPath() string {
+	if p := os.Getenv("LARK_CHANNEL_CONFIG"); strings.TrimSpace(p) != "" {
+		return expandHome(p)
+	}
 	home, err := vfs.UserHomeDir()
 	if err != nil || home == "" {
 		fmt.Fprintf(os.Stderr, "warning: unable to determine home directory: %v\n", err)

cmd/config/binder_test.go

@@ -4,6 +4,7 @@
 package config
 
 import (
+	"path/filepath"
 	"reflect"
 	"testing"
 
@@ -50,8 +51,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.ExitValidation, output.ErrDetail{
-		Type:    "openclaw",
+	assertExitError(t, err, output.ExitAuth, output.ErrDetail{
+		Type:    "config",
 		Message: "no Feishu app configured in openclaw.json",
 		Hint:    "configure channels.feishu.appId in openclaw.json",
 	})
@@ -63,8 +64,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.ExitValidation, output.ErrDetail{
-		Type:    "validation",
+	assertExitError(t, err, output.ExitAuth, output.ErrDetail{
+		Type:    "config",
 		Message: "hermes: no app configured",
 	})
 }
@@ -100,7 +101,7 @@ func TestSelectCandidate_AppIDFlag_NoMatch(t *testing.T) {
 	}
 	_, err := selectCandidate(b, candidates, "nonexistent", false, tuiUnreachable(t))
 	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
-		Type:    "openclaw",
+		Type:    "validation",
 		Message: `--app-id "nonexistent" not found in openclaw.json`,
 		Hint:    "available app IDs:\n  cli_work (work)\n  cli_home (home)",
 	})
@@ -117,7 +118,7 @@ func TestSelectCandidate_MultiCandidate_NoFlag_NonTUI(t *testing.T) {
 	}
 	_, err := selectCandidate(b, candidates, "", false, tuiUnreachable(t))
 	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
-		Type:    "openclaw",
+		Type:    "validation",
 		Message: "multiple accounts in openclaw.json; pass --app-id <id>",
 		Hint:    "available app IDs:\n  cli_work (work)\n  cli_home (home)",
 	})
@@ -152,7 +153,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:    "openclaw",
+		Type:    "validation",
 		Message: `--app-id "nonexistent" not found in openclaw.json`,
 		Hint:    "available app IDs:\n  cli_only",
 	})
@@ -173,3 +174,27 @@ func TestSelectCandidate_AppIDFlag_WinsOverTUI(t *testing.T) {
 	}
 	assertCandidate(t, got, Candidate{AppID: "cli_b"})
 }
+
+func TestResolveLarkChannelConfigPath_Default(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("LARK_CHANNEL_CONFIG", "")
+
+	got := resolveLarkChannelConfigPath()
+	want := filepath.Join(home, ".lark-channel", "config.json")
+	if got != want {
+		t.Fatalf("resolveLarkChannelConfigPath() = %q, want %q", got, want)
+	}
+}
+
+func TestResolveLarkChannelConfigPath_EnvOverride(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("LARK_CHANNEL_CONFIG", "~/bridge/projection.json")
+
+	got := resolveLarkChannelConfigPath()
+	want := filepath.Join(home, "bridge", "projection.json")
+	if got != want {
+		t.Fatalf("resolveLarkChannelConfigPath() = %q, want %q", got, want)
+	}
+}

cmd/config/config.go

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

cmd/config/config_test.go

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

cmd/config/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,12 +41,12 @@ func NewCmdConfigDefaultAs(f *cmdutil.Factory) *cobra.Command {
 
 			value := args[0]
 			if value != "user" && value != "bot" && value != "auto" {
-				return output.ErrValidation("invalid identity type %q, valid values: user | bot | auto", value)
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid identity type %q, valid values: user | bot | auto", value)
 			}
 
 			app.DefaultAs = core.Identity(value)
 			if err := core.SaveMultiAppConfig(multi); err != nil {
-				return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
+				return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
 			}
 			fmt.Fprintf(f.IOStreams.ErrOut, "Default identity set to: %s\n", value)
 			return nil

cmd/config/init.go

@@ -15,9 +15,11 @@ 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"
 )
@@ -31,9 +33,13 @@ type ConfigInitOptions struct {
 	AppSecretStdin bool   // read app-secret from stdin (avoids process list exposure)
 	Brand          string
 	New            bool
-	Lang           string
-	langExplicit   bool   // true when --lang was explicitly passed
-	ProfileName    string // when set, create/update a named profile instead of replacing Apps[0]
+
+	Lang         string // raw --lang (string for cobra); normalized to canonical/"" in validateInitLang
+	langExplicit bool   // true when --lang was explicitly passed
+
+	UILang i18n.Lang // TUI display language (picker-only); intentionally separate from --lang
+
+	ProfileName string // when set, create/update a named profile instead of replacing Apps[0]
 
 	// ForceInit overrides the agent-workspace guard. Without it, running
 	// init under OPENCLAW_HOME / HERMES_HOME refuses and points the caller
@@ -45,7 +51,7 @@ type ConfigInitOptions struct {
 
 // NewCmdConfigInit creates the config init subcommand.
 func NewCmdConfigInit(f *cmdutil.Factory, runF func(*ConfigInitOptions) error) *cobra.Command {
-	opts := &ConfigInitOptions{Factory: f}
+	opts := &ConfigInitOptions{Factory: f, UILang: i18n.LangZhCN}
 
 	cmd := &cobra.Command{
 		Use:   "init",
@@ -63,6 +69,9 @@ if the user explicitly wants a separate app inside the Agent workspace.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.Ctx = cmd.Context()
 			opts.langExplicit = cmd.Flags().Changed("lang")
+			if err := validateInitLang(opts); err != nil {
+				return err
+			}
 			if err := guardAgentWorkspace(opts); err != nil {
 				return err
 			}
@@ -77,7 +86,7 @@ if the user explicitly wants a separate app inside the Agent workspace.`,
 	cmd.Flags().StringVar(&opts.AppID, "app-id", "", "App ID (non-interactive)")
 	cmd.Flags().BoolVar(&opts.AppSecretStdin, "app-secret-stdin", false, "Read App Secret from stdin to avoid process list exposure")
 	cmd.Flags().StringVar(&opts.Brand, "brand", "feishu", "feishu or lark (non-interactive, default feishu)")
-	cmd.Flags().StringVar(&opts.Lang, "lang", "zh", "language for interactive prompts (zh or en)")
+	cmd.Flags().StringVar(&opts.Lang, "lang", "", "language preference (e.g. zh or zh_cn)")
 	cmd.Flags().StringVar(&opts.ProfileName, "name", "", "create or update a named profile (append instead of replace)")
 	cmd.Flags().BoolVar(&opts.ForceInit, "force-init", false, "allow init inside an Agent workspace (OPENCLAW_HOME / HERMES_HOME); use config bind instead unless you really want a separate app")
 	cmdutil.SetRisk(cmd, "write")
@@ -85,6 +94,25 @@ if the user explicitly wants a separate app inside the Agent workspace.`,
 	return cmd
 }
 
+// printLangPreferenceConfirmation echoes the set preference to stderr, only
+// when --lang explicitly set a non-empty value.
+func printLangPreferenceConfirmation(opts *ConfigInitOptions) {
+	if !opts.langExplicit || opts.Lang == "" {
+		return
+	}
+	msg := getInitMsg(opts.UILang)
+	fmt.Fprintln(opts.Factory.IOStreams.ErrOut, fmt.Sprintf(msg.LangPreferenceSet, opts.Lang))
+}
+
+func validateInitLang(opts *ConfigInitOptions) error {
+	lang, err := cmdutil.ParseLangFlag(opts.Lang)
+	if err != nil {
+		return err
+	}
+	opts.Lang = string(lang)
+	return nil
+}
+
 // guardAgentWorkspace refuses 'config init' when run inside an OpenClaw or
 // Hermes Agent context, because the Agent has already provisioned an app
 // and 'config bind' is the right tool for hooking lark-cli into it.
@@ -132,7 +160,7 @@ func cleanupOldConfig(existing *core.MultiAppConfig, f *cmdutil.Factory, skipApp
 func saveAsOnlyApp(appId string, secret core.SecretInput, brand core.LarkBrand, lang string) error {
 	config := &core.MultiAppConfig{
 		Apps: []core.AppConfig{{
-			AppId: appId, AppSecret: secret, Brand: brand, Lang: lang, Users: []core.AppUser{},
+			AppId: appId, AppSecret: secret, Brand: brand, Lang: i18n.Lang(lang), Users: []core.AppUser{},
 		}},
 	}
 	return core.SaveMultiAppConfig(config)
@@ -146,7 +174,13 @@ func saveInitConfig(profileName string, existing *core.MultiAppConfig, f *cmduti
 		return saveAsProfile(existing, f.Keychain, profileName, appId, secret, brand, lang)
 	}
 	cleanupOldConfig(existing, f, appId)
-	return saveAsOnlyApp(appId, secret, brand, lang)
+	var prior i18n.Lang
+	if existing != nil {
+		if app := existing.CurrentAppConfig(""); app != nil {
+			prior = app.Lang
+		}
+	}
+	return saveAsOnlyApp(appId, secret, brand, string(preferredLang(i18n.Lang(lang), prior)))
 }
 
 // saveAsProfile appends or updates a named profile in the config.
@@ -167,11 +201,10 @@ func saveAsProfile(existing *core.MultiAppConfig, kc keychain.KeychainAccess, pr
 			}
 			multi.Apps[idx].Users = []core.AppUser{}
 		}
-		// Update existing profile
 		multi.Apps[idx].AppId = appId
 		multi.Apps[idx].AppSecret = secret
 		multi.Apps[idx].Brand = brand
-		multi.Apps[idx].Lang = lang
+		multi.Apps[idx].Lang = preferredLang(i18n.Lang(lang), multi.Apps[idx].Lang)
 	} else {
 		if findAppIndexByAppID(multi, profileName) >= 0 {
 			return fmt.Errorf("profile name %q conflicts with existing appId", profileName)
@@ -182,7 +215,7 @@ func saveAsProfile(existing *core.MultiAppConfig, kc keychain.KeychainAccess, pr
 			AppId:     appId,
 			AppSecret: secret,
 			Brand:     brand,
-			Lang:      lang,
+			Lang:      i18n.Lang(lang),
 			Users:     []core.AppUser{},
 		})
 	}
@@ -213,9 +246,29 @@ 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 output.ErrValidation("App Secret cannot be empty for new configuration")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "App Secret cannot be empty for new configuration").
+			WithParam("--app-secret")
 	}
 
 	var app *core.AppConfig
@@ -223,22 +276,25 @@ func updateExistingProfileWithoutSecret(existing *core.MultiAppConfig, profileNa
 		if idx := findProfileIndexByName(existing, profileName); idx >= 0 {
 			app = &existing.Apps[idx]
 		} else {
-			return output.ErrValidation("App Secret cannot be empty for new profile")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "App Secret cannot be empty for new profile").
+				WithParam("--app-secret")
 		}
 	} else {
 		app = existing.CurrentAppConfig("")
 		if app == nil {
-			return output.ErrValidation("App Secret cannot be empty for new configuration")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "App Secret cannot be empty for new configuration").
+				WithParam("--app-secret")
 		}
 	}
 
 	if app.AppId != appID {
-		return output.ErrValidation("App Secret cannot be empty when changing App ID")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "App Secret cannot be empty when changing App ID").
+			WithParam("--app-secret")
 	}
 
 	app.AppId = appID
 	app.Brand = brand
-	app.Lang = lang
+	app.Lang = preferredLang(i18n.Lang(lang), app.Lang)
 	return core.SaveMultiAppConfig(existing)
 }
 
@@ -250,13 +306,13 @@ func configInitRun(opts *ConfigInitOptions) error {
 		scanner := bufio.NewScanner(f.IOStreams.In)
 		if !scanner.Scan() {
 			if err := scanner.Err(); err != nil {
-				return output.ErrValidation("failed to read secret from stdin: %v", err)
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "failed to read secret from stdin: %v", err).WithCause(err)
 			}
-			return output.ErrValidation("stdin is empty, expected app secret")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "stdin is empty, expected app secret")
 		}
 		opts.appSecret = strings.TrimSpace(scanner.Text())
 		if opts.appSecret == "" {
-			return output.ErrValidation("app secret read from stdin is empty")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "app secret read from stdin is empty")
 		}
 	}
 
@@ -268,7 +324,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 	// Validate --profile name if set
 	if opts.ProfileName != "" {
 		if err := core.ValidateProfileName(opts.ProfileName); err != nil {
-			return output.ErrValidation("%v", err)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "%v", err).WithCause(err)
 		}
 	}
 
@@ -277,35 +333,36 @@ 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 output.Errorf(output.ExitInternal, "internal", "%v", err)
+			return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
 		}
 		if err := saveInitConfig(opts.ProfileName, existing, f, opts.AppID, secret, brand, opts.Lang); err != nil {
-			return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
+			return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(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
+	// For interactive modes, prompt language selection if --lang was not explicitly set.
+	// Picker offers 2 options (中文 / English) and drives BOTH opts.Lang
+	// (preference) and opts.UILang (TUI rendering).
 	if f.IOStreams.IsTerminal && !opts.langExplicit && !opts.hasAnyNonInteractiveFlag() {
-		savedLang := ""
-		if existing != nil {
-			if app := existing.CurrentAppConfig(""); app != nil {
-				savedLang = app.Lang
-			}
-		}
-		lang, err := promptLangSelection(savedLang)
+		lang, err := promptLangSelection()
 		if err != nil {
 			if err == huh.ErrUserAborted {
 				return output.ErrBare(1)
 			}
-			return err
+			return output.Errorf(output.ExitInternal, "internal", "language selection failed: %v", err)
 		}
-		opts.Lang = lang
+		opts.Lang = string(lang)
+		opts.UILang = lang
 	}
 
-	msg := getInitMsg(opts.Lang)
+	msg := getInitMsg(opts.UILang)
 
 	// Mode 3: Create new app directly (--new)
 	if opts.New {
@@ -314,17 +371,21 @@ func configInitRun(opts *ConfigInitOptions) error {
 			return err
 		}
 		if result == nil {
-			return output.ErrValidation("app creation returned no result")
+			return errs.NewInternalError(errs.SubtypeSDKError, "app creation returned no result")
 		}
 		existing, _ := core.LoadMultiAppConfig()
 		secret, err := core.ForStorage(result.AppID, core.PlainSecret(result.AppSecret), f.Keychain)
 		if err != nil {
-			return output.Errorf(output.ExitInternal, "internal", "%v", err)
+			return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
 		}
 		if err := saveInitConfig(opts.ProfileName, existing, f, result.AppID, secret, result.Brand, opts.Lang); err != nil {
-			return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
+			return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(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
 	}
 
@@ -335,7 +396,8 @@ func configInitRun(opts *ConfigInitOptions) error {
 			return err
 		}
 		if result == nil {
-			return output.ErrValidation("App ID and App Secret cannot be empty")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "App ID and App Secret cannot be empty").
+				WithParam("--app-id")
 		}
 
 		existing, _ := core.LoadMultiAppConfig()
@@ -344,33 +406,36 @@ 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 output.Errorf(output.ExitInternal, "internal", "%v", err)
+				return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
 			}
 			if err := saveInitConfig(opts.ProfileName, existing, f, result.AppID, secret, result.Brand, opts.Lang); err != nil {
-				return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
+				return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
 			}
 		} else if result.Mode == "existing" && result.AppID != "" {
 			// Existing app with unchanged secret — update app ID and brand only
-			if err := updateExistingProfileWithoutSecret(existing, opts.ProfileName, result.AppID, result.Brand, opts.Lang); err != nil {
-				var exitErr *output.ExitError
-				if errors.As(err, &exitErr) {
-					return err
-				}
-				return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
+			if err := wrapUpdateExistingProfileErr(updateExistingProfileWithoutSecret(existing, opts.ProfileName, result.AppID, result.Brand, opts.Lang)); err != nil {
+				return err
 			}
 		} else {
-			return output.ErrValidation("App ID and App Secret cannot be empty")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "App ID and App Secret cannot be empty").
+				WithParam("--app-id")
 		}
 
 		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 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.")
+		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.")
 	}
 
 	// Mode 5: Legacy interactive (readline fallback)
@@ -398,7 +463,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 	}
 	appIdInput, err := readLine(prompt)
 	if err != nil {
-		return output.ErrValidation("%s", err)
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithCause(err)
 	}
 
 	prompt = "App Secret"
@@ -407,7 +472,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 	}
 	appSecretInput, err := readLine(prompt)
 	if err != nil {
-		return output.ErrValidation("%s", err)
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithCause(err)
 	}
 
 	prompt = "Brand (lark/feishu)"
@@ -418,7 +483,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 	}
 	brandInput, err := readLine(prompt)
 	if err != nil {
-		return output.ErrValidation("%s", err)
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithCause(err)
 	}
 
 	resolvedAppId := appIdInput
@@ -440,16 +505,23 @@ func configInitRun(opts *ConfigInitOptions) error {
 	}
 
 	if resolvedAppId == "" || resolvedSecret.IsZero() {
-		return output.ErrValidation("App ID and App Secret cannot be empty")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "App ID and App Secret cannot be empty").
+			WithParam("--app-id")
 	}
 
 	storedSecret, err := core.ForStorage(resolvedAppId, resolvedSecret, f.Keychain)
 	if err != nil {
-		return output.Errorf(output.ExitInternal, "internal", "%v", err)
+		return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
 	}
 	if err := saveInitConfig(opts.ProfileName, existing, f, resolvedAppId, storedSecret, parseBrand(resolvedBrand), opts.Lang); err != nil {
-		return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
+		return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(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
 }

cmd/config/init_interactive.go

@@ -6,16 +6,17 @@ 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.
@@ -125,8 +126,16 @@ func runExistingAppForm(f *cmdutil.Factory, msg *initMsg) (*configInitResult, er
 		}, nil
 	}
 
-	if appID == "" || appSecret == "" {
-		return nil, output.ErrValidation("App ID and App Secret cannot be empty")
+	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")
 	}
 
 	return &configInitResult{
@@ -168,10 +177,12 @@ func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride cor
 	}
 
 	// Step 1: Request app registration (begin)
-	httpClient := &http.Client{}
+	// Use the shared proxy-plugin-aware transport so registration traffic is not
+	// a bypass of proxy plugin mode.
+	httpClient := transport.NewHTTPClient(0)
 	authResp, err := larkauth.RequestAppRegistration(httpClient, larkBrand, f.IOStreams.ErrOut)
 	if err != nil {
-		return nil, output.ErrAuth("app registration failed: %v", err)
+		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "app registration failed: %v", err).WithCause(err)
 	}
 
 	// Step 2: Build and display verification URL + QR code
@@ -199,7 +210,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, output.ErrAuth("%v", err)
+		return nil, errs.NewAuthenticationError(errs.SubtypeUnknown, "%v", err).WithCause(err)
 	}
 
 	// Step 4: Handle Lark brand special case
@@ -208,12 +219,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, output.ErrAuth("lark endpoint retry failed: %v", err)
+			return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "lark endpoint retry failed: %v", err).WithCause(err)
 		}
 	}
 
 	if result.ClientID == "" || result.ClientSecret == "" {
-		return nil, output.ErrAuth("app registration succeeded but missing client_id or client_secret")
+		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "app registration succeeded but missing client_id or client_secret")
 	}
 
 	// Determine final brand from response

cmd/config/init_messages.go

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

cmd/config/init_messages_test.go

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

cmd/config/init_probe.go

@@ -0,0 +1,92 @@
+// 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 unified Token Endpoint deterministically rejected the
+//     credentials — an OAuth2 invalid_client / unauthorized_client classified as
+//     CategoryConfig / SubtypeInvalidClient, 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, transient 5xx/server_error, 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
+}

cmd/config/init_probe_test.go

@@ -0,0 +1,287 @@
+// 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, "/oauth/v3/token"):
+		f.tatCalls++
+		if f.tatHandler == nil {
+			return jsonResp(200, `{"code":0,"access_token":"t-ok","token_type":"Bearer"}`), 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). 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). The numeric code is not asserted: the unified v3 Token
+// Endpoint reports invalid_client via the OAuth2 error string, not a Lark code.
+func assertConfigRejection(t *testing.T, err error, errBuf *bytes.Buffer) {
+	t.Helper()
+	if err == nil {
+		t.Fatal("expected *errs.ConfigError, got nil")
+	}
+	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 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())
+	}
+}
+
+// invalid_client (bad / non-existent app_id or wrong secret) → the v3 Token
+// Endpoint returns HTTP 400 with the OAuth2 error → ConfigError/InvalidClient,
+// propagated. The probe endpoint must not be called when TAT fails.
+func TestRunProbe_TATInvalidClient_ReturnsConfigError(t *testing.T) {
+	rt := &fakeRT{
+		tatHandler: func(req *http.Request) (*http.Response, error) {
+			return jsonResp(400, `{"error":"invalid_client","error_description":"The client secret is invalid.","code":20002}`), 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)
+}
+
+// unauthorized_client is treated as the same credential rejection, propagated.
+func TestRunProbe_TATUnauthorizedClient_ReturnsConfigError(t *testing.T) {
+	rt := &fakeRT{
+		tatHandler: func(req *http.Request) (*http.Response, error) {
+			return jsonResp(401, `{"error":"unauthorized_client","error_description":"client not authorized"}`), nil
+		},
+	}
+	f, errBuf := fakeFactory(t, rt)
+	assertConfigRejection(t, runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu), errBuf)
+}
+
+// Any other deterministic client-side OAuth error (e.g. invalid_scope) falls
+// back to *errs.APIError via BuildAPIError — still typed, so the probe surfaces
+// it rather than swallowing — but is not a credential (ConfigError) rejection.
+func TestRunProbe_TATOtherClientError_Propagates(t *testing.T) {
+	rt := &fakeRT{
+		tatHandler: func(req *http.Request) (*http.Response, error) {
+			return jsonResp(400, `{"code":20068,"error":"invalid_scope","error_description":"unauthorized scope"}`), 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)
+}

cmd/config/init_test.go

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

cmd/config/keychain_downgrade.go

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

cmd/config/keychain_downgrade_other.go

@@ -0,0 +1,28 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build !darwin
+
+package config
+
+import (
+	"github.com/larksuite/cli/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
+}

cmd/config/plugins.go

@@ -82,8 +82,8 @@ func runConfigPluginsShow(f *cmdutil.Factory) error {
 			"version":      p.Version,
 			"capabilities": p.Capabilities,
 		}
-		if p.Rule != nil {
-			entry["rule"] = p.Rule
+		if len(p.Rules) > 0 {
+			entry["rules"] = p.Rules
 		}
 		entry["hooks"] = map[string]any{
 			"observers": p.Observers,

cmd/config/policy.go

@@ -59,16 +59,20 @@ func runConfigPolicyShow(f *cmdutil.Factory) error {
 		"source_name":  sourceName,
 		"denied_paths": active.DeniedPaths,
 	}
-	if active.Rule != nil {
-		out["rule"] = map[string]any{
-			"name":              active.Rule.Name,
-			"description":       active.Rule.Description,
-			"allow":             active.Rule.Allow,
-			"deny":              active.Rule.Deny,
-			"max_risk":          active.Rule.MaxRisk,
-			"identities":        active.Rule.Identities,
-			"allow_unannotated": active.Rule.AllowUnannotated,
+	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

cmd/config/policy_test.go

@@ -57,7 +57,7 @@ func TestConfigPolicyShow_PluginActive(t *testing.T) {
 		MaxRisk: "read",
 	}
 	cmdpolicy.SetActive(&cmdpolicy.ActivePolicy{
-		Rule: rule,
+		Rules: []*platform.Rule{rule},
 		Source: cmdpolicy.ResolveSource{
 			Kind: cmdpolicy.SourcePlugin,
 			Name: "secaudit",
@@ -83,12 +83,16 @@ func TestConfigPolicyShow_PluginActive(t *testing.T) {
 	if got["denied_paths"] != float64(42) {
 		t.Errorf("denied_paths = %v, want 42", got["denied_paths"])
 	}
-	ruleMap, ok := got["rule"].(map[string]any)
+	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("rule field missing or wrong type")
+		t.Fatalf("rules[0] wrong type")
 	}
 	if ruleMap["name"] != "secaudit" {
-		t.Errorf("rule.name = %v", ruleMap["name"])
+		t.Errorf("rules[0].name = %v", ruleMap["name"])
 	}
 }
 
@@ -101,7 +105,7 @@ func TestConfigPolicyShow_YamlSourceNameIsEmpty(t *testing.T) {
 	t.Cleanup(cmdpolicy.ResetActiveForTesting)
 
 	cmdpolicy.SetActive(&cmdpolicy.ActivePolicy{
-		Rule: &platform.Rule{Name: "my-yaml-rule"},
+		Rules: []*platform.Rule{{Name: "my-yaml-rule"}},
 		Source: cmdpolicy.ResolveSource{
 			Kind: cmdpolicy.SourceYAML,
 			Name: "/Users/alice/.lark-cli/policy.yml",

cmd/config/remove.go

@@ -6,6 +6,7 @@ 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"
@@ -42,14 +43,14 @@ func configRemoveRun(opts *ConfigRemoveOptions) error {
 
 	config, err := core.LoadMultiAppConfig()
 	if err != nil || config == nil || len(config.Apps) == 0 {
-		return output.ErrValidation("not configured yet")
+		return errs.NewConfigError(errs.SubtypeNotConfigured, "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 output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
+		return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
 	}
 
 	// Clean up keychain entries for all apps after config is cleared.

cmd/config/show.go

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

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

cmd/doctor/doctor.go

@@ -19,6 +19,7 @@ import (
 	"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"
 )
 
@@ -152,7 +153,9 @@ func networkChecks(ctx context.Context, opts *DoctorOptions, ep core.Endpoints)
 		}
 	}
 
-	httpClient := &http.Client{}
+	// 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)
 	mcpURL := ep.MCP + "/mcp"
 
 	type probeResult struct {

cmd/error_auth_hint.go

@@ -4,9 +4,14 @@
 package cmd
 
 import (
+	"errors"
 	"fmt"
 	"strings"
 
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/apicatalog"
 	internalauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
@@ -14,12 +19,43 @@ import (
 	"github.com/larksuite/cli/internal/registry"
 	"github.com/larksuite/cli/shortcuts"
 	shortcutcommon "github.com/larksuite/cli/shortcuts/common"
-	"github.com/spf13/cobra"
 )
 
-// enrichMissingScopeError preserves the original need_user_authorization
-// message and appends a scope hint when the current command declares the
-// required scopes locally.
+// applyNeedAuthorizationHint augments a typed *errs.AuthenticationError with a
+// "current command requires scope(s): X, Y" hint when the underlying error is
+// a need_user_authorization signal AND the current command declares scopes
+// locally (via shortcut registration or service-method metadata). 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.
 func enrichMissingScopeError(f *cmdutil.Factory, exitErr *output.ExitError) {
 	if exitErr == nil || exitErr.Detail == nil {
 		return
@@ -27,12 +63,10 @@ func enrichMissingScopeError(f *cmdutil.Factory, exitErr *output.ExitError) {
 	if !internalauth.IsNeedUserAuthorizationError(exitErr) {
 		return
 	}
-
 	scopes := resolveDeclaredScopesForCurrentCommand(f)
 	if len(scopes) == 0 {
 		return
 	}
-
 	scopeHint := fmt.Sprintf("current command requires scope(s): %s", strings.Join(scopes, ", "))
 	if exitErr.Detail.Hint == "" {
 		exitErr.Detail.Hint = scopeHint
@@ -85,78 +119,37 @@ func resolveDeclaredShortcutScopes(cmd *cobra.Command, identity string) []string
 }
 
 // resolveDeclaredServiceMethodScopes returns the scopes declared by a
-// service/resource/method command from the embedded from_meta registry.
+// service/resource/method command. It reconstructs the catalog path from the
+// command ancestry and resolves it through the same navigation Module the
+// command tree is built from (apicatalog), so it stays correct for nested
+// resources instead of hard-coding a root->service->resource->method depth.
+// Non-method commands (services, resources, shortcuts) resolve to a non-method
+// target and yield no scopes.
 func resolveDeclaredServiceMethodScopes(cmd *cobra.Command, identity string) []string {
-	// Service-method scope lookup only applies to commands mounted as
-	// root -> service -> resource -> method. Non-resource/method commands
-	// intentionally return no scopes here so auth-hint enrichment does not
-	// change runtime semantics for other command shapes.
-	if cmd == nil || cmd.Parent() == nil || cmd.Parent().Parent() == nil || cmd.Parent().Parent().Parent() == nil {
+	if cmd == nil || strings.HasPrefix(cmd.Name(), "+") {
 		return nil
 	}
-	if strings.HasPrefix(cmd.Name(), "+") {
+	path := commandCatalogPath(cmd)
+	if len(path) == 0 {
 		return nil
 	}
-
-	service := cmd.Parent().Parent().Name()
-	resource := cmd.Parent().Name()
-	method := cmd.Name()
-
-	spec := registry.LoadFromMeta(service)
-	if spec == nil {
+	target, err := registry.RuntimeCatalog().Resolve(path)
+	if err != nil || target.Kind != apicatalog.TargetMethod {
 		return nil
 	}
-	resources, _ := spec["resources"].(map[string]interface{})
-	resMap, _ := resources[resource].(map[string]interface{})
-	if resMap == nil {
-		return nil
-	}
-	methods, _ := resMap["methods"].(map[string]interface{})
-	methodMap, _ := methods[method].(map[string]interface{})
-	if methodMap == nil {
-		return nil
-	}
-	return declaredScopesForMethod(methodMap, identity)
+	return registry.DeclaredScopesForMethod(target.Method.Method, 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)
+// commandCatalogPath reconstructs the catalog path [service, resource..., method]
+// from a command's ancestry, excluding the root command. It is the inverse of
+// the service command tree's construction, so any depth (flat or nested)
+// round-trips through apicatalog.Resolve.
+func commandCatalogPath(cmd *cobra.Command) []string {
+	var path []string
+	for c := cmd; c != nil && c.Parent() != nil; c = c.Parent() {
+		path = append([]string{c.Name()}, path...)
 	}
-
-	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
+	return path
 }
 
 // shortcutSupportsIdentity reports whether a shortcut supports the requested

cmd/event/bus.go

@@ -12,6 +12,7 @@ import (
 
 	"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/event"
@@ -38,7 +39,8 @@ func NewCmdBus(f *cmdutil.Factory) *cobra.Command {
 
 			logger, err := bus.SetupBusLogger(eventsDir)
 			if err != nil {
-				return err
+				return errs.NewInternalError(errs.SubtypeFileIO,
+					"set up bus logger: %s", err).WithCause(err)
 			}
 
 			tr := transport.New()
@@ -58,7 +60,14 @@ func NewCmdBus(f *cmdutil.Factory) *cobra.Command {
 				}
 			}()
 
-			return b.Run(ctx)
+			if err := b.Run(ctx); err != nil {
+				if _, ok := errs.ProblemOf(err); ok {
+					return err
+				}
+				return errs.NewInternalError(errs.SubtypeUnknown,
+					"event bus daemon exited: %s", err).WithCause(err)
+			}
+			return nil
 		},
 	}
 

cmd/event/bus_test.go

@@ -0,0 +1,45 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package event
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+)
+
+// The hidden `event _bus` daemon command must exit with a typed file_io error
+// when its log directory cannot be created (the error is only visible in the
+// forked process's captured stderr / bus.log).
+func TestBusCommandLoggerSetupFailureIsTypedFileIO(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	// Block the events/ root with a regular file so MkdirAll fails.
+	if err := os.WriteFile(filepath.Join(dir, "events"), []byte("x"), 0600); err != nil {
+		t.Fatal(err)
+	}
+
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "cli_bus_test", AppSecret: "secret", Brand: core.BrandFeishu,
+	})
+	cmd := NewCmdBus(f)
+	cmd.SetArgs([]string{})
+
+	err := cmd.Execute()
+	if err == nil {
+		t.Fatal("expected logger setup error")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed errs error, got %T: %v", err, err)
+	}
+	if p.Category != errs.CategoryInternal || p.Subtype != errs.SubtypeFileIO {
+		t.Errorf("problem = %s/%s, want %s/%s", p.Category, p.Subtype,
+			errs.CategoryInternal, errs.SubtypeFileIO)
+	}
+}

cmd/event/consume.go

@@ -16,6 +16,7 @@ import (
 
 	"github.com/spf13/cobra"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/appmeta"
 	"github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
@@ -64,8 +65,8 @@ Use 'event schema <EventKey>' for parameter details.`,
 	cmd.Flags().StringVar(&o.jqExpr, "jq", "", "JQ expression to filter output")
 	cmd.Flags().BoolVar(&o.quiet, "quiet", false, "Suppress informational messages on stderr")
 	cmd.Flags().StringVar(&o.outputDir, "output-dir", "", "Write each event as a file in this directory (relative paths only; absolute paths and ~ are rejected to prevent path traversal)")
-	cmd.Flags().IntVar(&o.maxEvents, "max-events", 0, "Exit after N successful emits (0 = unlimited). Multi-worker EventKeys may emit up to workers-1 past N before all workers stop.")
-	cmd.Flags().DurationVar(&o.timeout, "timeout", 0, "Exit after DURATION (e.g. 30s, 2m). 0 = no timeout. Timeout is a normal exit (code 0; stderr 'reason: timeout').")
+	cmd.Flags().IntVar(&o.maxEvents, "max-events", 0, "Exit after N successful emits (0 = unlimited). Multi-worker EventKeys may emit up to workers-1 past N before all workers stop. Bounded runs ignore stdin EOF.")
+	cmd.Flags().DurationVar(&o.timeout, "timeout", 0, "Exit after DURATION (e.g. 30s, 2m). 0 = no timeout. Timeout is a normal exit (code 0; stderr 'reason: timeout'). Bounded runs ignore stdin EOF.")
 	cmd.Flags().String("as", "auto", "identity type: user | bot | auto (must match EventKey's declared AuthTypes)")
 	_ = cmd.RegisterFlagCompletionFunc("as", func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
 		return []string{"user", "bot", "auto"}, cobra.ShellCompDirectiveNoFileComp
@@ -101,11 +102,10 @@ func runConsume(cmd *cobra.Command, f *cmdutil.Factory, eventKey string, o consu
 
 	if o.jqExpr != "" {
 		if err := output.ValidateJqExpression(o.jqExpr); err != nil {
-			return output.ErrWithHint(
-				output.ExitValidation, "validation",
-				err.Error(),
-				fmt.Sprintf("see `lark-cli event consume --help` EXAMPLES for common patterns, or `lark-cli event schema %s` for valid field paths", eventKey),
-			)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).
+				WithParam("--jq").
+				WithCause(err).
+				WithHint("see `lark-cli event consume --help` EXAMPLES for common patterns, or `lark-cli event schema %s` for valid field paths", eventKey)
 		}
 	}
 
@@ -184,8 +184,9 @@ func runConsume(cmd *cobra.Command, f *cmdutil.Factory, eventKey string, o consu
 		errOut = io.Discard
 	}
 
-	// Non-TTY only: stdin EOF is shutdown for subprocess callers; in TTY Ctrl-D must not exit.
-	if !f.IOStreams.IsTerminal {
+	// Non-TTY unbounded consumers use stdin EOF as shutdown for subprocess callers.
+	// Bounded runs already have --max-events/--timeout as their lifecycle control.
+	if shouldWatchStdinEOF(f.IOStreams.IsTerminal, o.maxEvents, o.timeout) {
 		watchStdinEOF(os.Stdin, cancel, errOut)
 	}
 
@@ -260,12 +261,12 @@ func preflightScopes(ctx context.Context, pf *preflightCtx) error {
 	if len(missing) == 0 {
 		return nil
 	}
-	return output.ErrWithHint(
-		output.ExitAuth, "auth",
-		fmt.Sprintf("missing required scopes for EventKey %s (as %s): %s",
-			pf.eventKey, pf.identity, strings.Join(missing, ", ")),
-		scopeRemediationHint(pf.identity, missing, pf.appID, pf.brand),
-	)
+	return errs.NewPermissionError(errs.SubtypeMissingScope,
+		"missing required scopes for EventKey %s (as %s): %s",
+		pf.eventKey, pf.identity, strings.Join(missing, ", ")).
+		WithIdentity(string(pf.identity)).
+		WithMissingScopes(missing...).
+		WithHint("%s", scopeRemediationHint(pf.identity, missing, pf.appID, pf.brand))
 }
 
 // scopeRemediationHint returns an identity-appropriate fix for missing scopes.
@@ -300,23 +301,27 @@ func preflightEventTypes(pf *preflightCtx) error {
 	if len(missing) == 0 {
 		return nil
 	}
-	return output.ErrWithHint(
-		output.ExitValidation, "validation",
-		fmt.Sprintf("EventKey %s requires event types not subscribed in console: %s",
-			pf.keyDef.Key, strings.Join(missing, ", ")),
-		fmt.Sprintf("subscribe these events and publish a new app version at: %s",
-			consoleEventSubscriptionURL(pf.brand, pf.appID)),
-	)
+	return errs.NewValidationError(errs.SubtypeFailedPrecondition,
+		"EventKey %s requires event types not subscribed in console: %s",
+		pf.keyDef.Key, strings.Join(missing, ", ")).
+		WithHint("subscribe these events and publish a new app version at: %s",
+			consoleEventSubscriptionURL(pf.brand, pf.appID))
 }
 
 // sanitizeOutputDir rejects absolute/parent-escaping paths and ~ (SafeOutputPath treats it as a literal dir name).
 func sanitizeOutputDir(dir string) (string, error) {
 	if strings.HasPrefix(dir, "~") {
-		return "", output.ErrValidation("%s; use a relative path like ./output instead", errOutputDirTilde)
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
+			"%s; use a relative path like ./output instead", errOutputDirTilde).
+			WithParam("--output-dir").
+			WithCause(errOutputDirTilde)
 	}
 	safe, err := validate.SafeOutputPath(dir)
 	if err != nil {
-		return "", output.ErrValidation("%s %q: %s", errOutputDirUnsafe, dir, err)
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
+			"%s %q: %s", errOutputDirUnsafe, dir, err).
+			WithParam("--output-dir").
+			WithCause(errOutputDirUnsafe)
 	}
 	return safe, nil
 }
@@ -328,18 +333,21 @@ func resolveTenantToken(ctx context.Context, f *cmdutil.Factory, appID string) (
 	}
 	result, err := f.Credential.ResolveToken(ctx, credential.NewTokenSpec(core.AsBot, appID))
 	if err != nil {
-		return "", output.ErrAuth("resolve tenant access token: %s", err)
+		if _, ok := errs.ProblemOf(err); ok {
+			return "", err
+		}
+		return "", errs.NewAuthenticationError(errs.SubtypeTokenMissing,
+			"resolve tenant access token: %s", err).WithCause(err)
 	}
 	if result == nil || result.Token == "" {
-		return "", output.ErrWithHint(
-			output.ExitAuth, "auth",
-			fmt.Sprintf("no tenant access token available for app %s", appID),
-			"Check that app_secret is configured (lark-cli config show) and try 'lark-cli auth login'.",
-		)
+		return "", errs.NewAuthenticationError(errs.SubtypeTokenMissing,
+			"no tenant access token available for app %s", appID).
+			WithHint("Check that app_secret is configured (lark-cli config show) and try 'lark-cli auth login'.")
 	}
 	return result.Token, nil
 }
 
+// Sentinels for errors.Is checks; call sites wrap them as typed ValidationError causes.
 var (
 	errInvalidParamFormat = errors.New("invalid --param format")
 	errOutputDirTilde     = errors.New("--output-dir does not support ~ expansion")
@@ -351,7 +359,10 @@ func parseParams(raw []string) (map[string]string, error) {
 	for _, kv := range raw {
 		k, v, ok := strings.Cut(kv, "=")
 		if !ok || k == "" {
-			return nil, output.ErrValidation("%s %q: expected key=value", errInvalidParamFormat, kv)
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
+				"%s %q: expected key=value", errInvalidParamFormat, kv).
+				WithParam("--param").
+				WithCause(errInvalidParamFormat)
 		}
 		m[k] = v
 	}
@@ -370,3 +381,8 @@ func watchStdinEOF(r io.Reader, cancel context.CancelFunc, errOut io.Writer) {
 		cancel()
 	}()
 }
+
+// shouldWatchStdinEOF gates the stdin-EOF shutdown watcher: non-TTY unbounded runs only (<= 0 mirrors downstream's >0-is-bounded semantics, so negative bounds stay unbounded).
+func shouldWatchStdinEOF(isTerminal bool, maxEvents int, timeout time.Duration) bool {
+	return !isTerminal && maxEvents <= 0 && timeout <= 0
+}

cmd/event/consume_stdin_test.go

@@ -61,3 +61,70 @@ func TestWatchStdinEOF_DiagnosticMessage(t *testing.T) {
 		t.Fatal("watchStdinEOF did not cancel within 1s of EOF")
 	}
 }
+
+func TestShouldWatchStdinEOF(t *testing.T) {
+	tests := []struct {
+		name       string
+		isTerminal bool
+		maxEvents  int
+		timeout    time.Duration
+		want       bool
+	}{
+		{
+			name:       "terminal",
+			isTerminal: true,
+			want:       false,
+		},
+		{
+			name: "non terminal unbounded",
+			want: true,
+		},
+		{
+			name:      "non terminal negative max events is unbounded",
+			maxEvents: -1,
+			want:      true,
+		},
+		{
+			name:    "non terminal negative timeout is unbounded",
+			timeout: -1 * time.Second,
+			want:    true,
+		},
+		{
+			name:      "non terminal max events bounded",
+			maxEvents: 1,
+			want:      false,
+		},
+		{
+			name:    "non terminal timeout bounded",
+			timeout: 10 * time.Minute,
+			want:    false,
+		},
+		{
+			name:      "non terminal both bounds positive",
+			maxEvents: 1,
+			timeout:   10 * time.Minute,
+			want:      false,
+		},
+		{
+			name:      "non terminal bounded max events with negative timeout",
+			maxEvents: 1,
+			timeout:   -1 * time.Second,
+			want:      false,
+		},
+		{
+			name:      "non terminal bounded timeout with negative max events",
+			maxEvents: -1,
+			timeout:   10 * time.Minute,
+			want:      false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := shouldWatchStdinEOF(tt.isTerminal, tt.maxEvents, tt.timeout)
+			if got != tt.want {
+				t.Fatalf("shouldWatchStdinEOF() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}

cmd/event/consume_test.go

@@ -4,9 +4,14 @@
 package event
 
 import (
+	"context"
 	"errors"
 	"strings"
 	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/credential"
 )
 
 func TestParseParams(t *testing.T) {
@@ -73,6 +78,7 @@ func TestParseParams(t *testing.T) {
 				if tc.wantEcho != "" && !strings.Contains(err.Error(), tc.wantEcho) {
 					t.Errorf("err %q should echo %q so user sees the bad input", err.Error(), tc.wantEcho)
 				}
+				assertInvalidArgumentParam(t, err, "--param")
 				return
 			}
 			if err != nil {
@@ -90,6 +96,77 @@ func TestParseParams(t *testing.T) {
 	}
 }
 
+// emptyTokenResolver resolves to a result that carries no token.
+type emptyTokenResolver struct{}
+
+func (emptyTokenResolver) ResolveToken(_ context.Context, _ credential.TokenSpec) (*credential.TokenResult, error) {
+	return &credential.TokenResult{}, nil
+}
+
+// failingTokenResolver fails outright with an untyped error.
+type failingTokenResolver struct{}
+
+func (failingTokenResolver) ResolveToken(_ context.Context, _ credential.TokenSpec) (*credential.TokenResult, error) {
+	return nil, errors.New("backend unavailable")
+}
+
+func factoryWithResolver(r credential.DefaultTokenResolver) *cmdutil.Factory {
+	return &cmdutil.Factory{Credential: credential.NewCredentialProvider(nil, nil, r, nil)}
+}
+
+func TestResolveTenantToken_EmptyTokenResult(t *testing.T) {
+	_, err := resolveTenantToken(context.Background(), factoryWithResolver(emptyTokenResolver{}), "cli_x")
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed errs error, got %T: %v", err, err)
+	}
+	if p.Category != errs.CategoryAuthentication || p.Subtype != errs.SubtypeTokenMissing {
+		t.Errorf("problem = %s/%s, want %s/%s", p.Category, p.Subtype,
+			errs.CategoryAuthentication, errs.SubtypeTokenMissing)
+	}
+	var malformed *credential.MalformedTokenResultError
+	if !errors.As(err, &malformed) {
+		t.Error("empty-token failure should preserve the credential-layer cause")
+	}
+}
+
+func TestResolveTenantToken_ResolverFailure(t *testing.T) {
+	_, err := resolveTenantToken(context.Background(), factoryWithResolver(failingTokenResolver{}), "cli_x")
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed errs error, got %T: %v", err, err)
+	}
+	if p.Category != errs.CategoryAuthentication || p.Subtype != errs.SubtypeTokenMissing {
+		t.Errorf("problem = %s/%s, want %s/%s", p.Category, p.Subtype,
+			errs.CategoryAuthentication, errs.SubtypeTokenMissing)
+	}
+	if errors.Unwrap(err) == nil {
+		t.Error("resolver failure should preserve its cause")
+	}
+}
+
+// assertInvalidArgumentParam verifies err is a typed validation error with
+// subtype invalid_argument naming the given flag in its param field.
+func assertInvalidArgumentParam(t *testing.T, err error, param string) {
+	t.Helper()
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
+	}
+	if ve.Subtype != errs.SubtypeInvalidArgument {
+		t.Errorf("subtype = %s, want %s", ve.Subtype, errs.SubtypeInvalidArgument)
+	}
+	if ve.Param != param {
+		t.Errorf("param = %q, want %q", ve.Param, param)
+	}
+}
+
 func TestSanitizeOutputDir(t *testing.T) {
 	cases := []struct {
 		name       string
@@ -130,6 +207,7 @@ func TestSanitizeOutputDir(t *testing.T) {
 				if !errors.Is(err, tc.wantSentry) {
 					t.Fatalf("want errors.Is(err, %v), got %q", tc.wantSentry, err.Error())
 				}
+				assertInvalidArgumentParam(t, err, "--output-dir")
 				return
 			}
 			if err != nil {

cmd/event/format_helpers_test.go

@@ -143,6 +143,79 @@ func TestWriteStatusText_CoversAllStates(t *testing.T) {
 	}
 }
 
+func TestWriteStatusText_ShowsSubColumn(t *testing.T) {
+	var buf bytes.Buffer
+	writeStatusText(&buf, []appStatus{
+		{
+			AppID:     "cli_RUNNINGXXXXXXXXX",
+			State:     stateRunning,
+			PID:       1234,
+			UptimeSec: 60,
+			Active:    2,
+			Consumers: []protocol.ConsumerInfo{
+				{PID: 1001, EventKey: "mail.x", SubscriptionID: "mail.x:alice", Received: 5, Dropped: 0},
+				{PID: 1002, EventKey: "mail.x", SubscriptionID: "mail.x:bob", Received: 3, Dropped: 0},
+			},
+		},
+	})
+	out := buf.String()
+	if !strings.Contains(out, "SUB") {
+		t.Errorf("missing SUB column header: %s", out)
+	}
+	if !strings.Contains(out, "alice") {
+		t.Errorf("missing alice suffix in SUB column: %s", out)
+	}
+	if !strings.Contains(out, "bob") {
+		t.Errorf("missing bob suffix in SUB column: %s", out)
+	}
+}
+
+func TestWriteStatusText_LegacySubscriptionID_RendersDash(t *testing.T) {
+	var buf bytes.Buffer
+	writeStatusText(&buf, []appStatus{
+		{
+			AppID:     "cli_RUNNINGXXXXXXXXX",
+			State:     stateRunning,
+			PID:       1234,
+			UptimeSec: 60,
+			Active:    1,
+			Consumers: []protocol.ConsumerInfo{
+				{PID: 1001, EventKey: "im.x", SubscriptionID: "", Received: 5},
+			},
+		},
+	})
+	out := buf.String()
+	if !strings.Contains(out, "SUB") {
+		t.Errorf("missing SUB header: %s", out)
+	}
+	if !strings.Contains(out, "-") {
+		t.Errorf("missing dash placeholder for empty SubscriptionID: %s", out)
+	}
+}
+
+func TestWriteStatusText_EventKeyEqualSubscriptionID_RendersDash(t *testing.T) {
+	var buf bytes.Buffer
+	writeStatusText(&buf, []appStatus{
+		{
+			AppID:     "cli_RUNNINGXXXXXXXXX",
+			State:     stateRunning,
+			PID:       1234,
+			UptimeSec: 60,
+			Active:    1,
+			Consumers: []protocol.ConsumerInfo{
+				{PID: 1001, EventKey: "im.x", SubscriptionID: "im.x", Received: 5},
+			},
+		},
+	})
+	out := buf.String()
+	if !strings.Contains(out, "SUB") {
+		t.Errorf("missing SUB header: %s", out)
+	}
+	if !strings.Contains(out, "-") {
+		t.Errorf("missing dash placeholder when SubscriptionID==EventKey: %s", out)
+	}
+}
+
 func TestWriteStatusJSON_OrphanHint(t *testing.T) {
 	var buf bytes.Buffer
 	if err := writeStatusJSON(&buf, []appStatus{

cmd/event/preflight_test.go

@@ -8,10 +8,10 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/appmeta"
 	"github.com/larksuite/cli/internal/core"
 	eventlib "github.com/larksuite/cli/internal/event"
-	"github.com/larksuite/cli/internal/output"
 )
 
 func newPreflightCtx(appID string, brand core.LarkBrand, identity core.Identity, keyDef *eventlib.KeyDefinition, appVer *appmeta.AppVersion) *preflightCtx {
@@ -89,19 +89,17 @@ func TestPreflightEventTypes_MissingBlocks(t *testing.T) {
 	if !strings.Contains(err.Error(), "mail.user_mailbox.event.message_read_v1") {
 		t.Errorf("error should name the missing event type, got: %v", err)
 	}
-	var exit *output.ExitError
-	if !errors.As(err, &exit) {
-		t.Fatalf("expected output.ExitError, got %T: %v", err, err)
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed errs error, got %T: %v", err, err)
 	}
-	if exit.Code != output.ExitValidation {
-		t.Errorf("ExitCode = %d, want ExitValidation (%d)", exit.Code, output.ExitValidation)
-	}
-	if exit.Detail == nil {
-		t.Fatal("expected Detail with hint")
+	if p.Category != errs.CategoryValidation || p.Subtype != errs.SubtypeFailedPrecondition {
+		t.Errorf("problem = %s/%s, want %s/%s", p.Category, p.Subtype,
+			errs.CategoryValidation, errs.SubtypeFailedPrecondition)
 	}
 	wantURL := "https://open.feishu.cn/app/cli_XXXXXXXXXXXXXXXX/event"
-	if !strings.Contains(exit.Detail.Hint, wantURL) {
-		t.Errorf("hint missing subscription URL %q\ngot: %s", wantURL, exit.Detail.Hint)
+	if !strings.Contains(p.Hint, wantURL) {
+		t.Errorf("hint missing subscription URL %q\ngot: %s", wantURL, p.Hint)
 	}
 }
 
@@ -145,17 +143,19 @@ func TestPreflightScopes_Bot_MissingBlocks(t *testing.T) {
 	if !strings.Contains(err.Error(), "im:message.group_at_msg") {
 		t.Errorf("error should name missing scope, got: %v", err)
 	}
-	var exit *output.ExitError
-	if !errors.As(err, &exit) {
-		t.Fatalf("expected output.ExitError, got %T: %v", err, err)
+	var permErr *errs.PermissionError
+	if !errors.As(err, &permErr) {
+		t.Fatalf("expected *errs.PermissionError, got %T: %v", err, err)
 	}
-	if exit.Code != output.ExitAuth {
-		t.Errorf("ExitCode = %d, want ExitAuth (%d)", exit.Code, output.ExitAuth)
+	if permErr.Category != errs.CategoryAuthorization || permErr.Subtype != errs.SubtypeMissingScope {
+		t.Errorf("problem = %s/%s, want %s/%s", permErr.Category, permErr.Subtype,
+			errs.CategoryAuthorization, errs.SubtypeMissingScope)
 	}
-	if exit.Detail == nil {
-		t.Fatal("expected Detail with hint, got nil Detail")
+	wantMissing := []string{"im:message.group_at_msg"}
+	if len(permErr.MissingScopes) != 1 || permErr.MissingScopes[0] != wantMissing[0] {
+		t.Errorf("MissingScopes = %v, want %v", permErr.MissingScopes, wantMissing)
 	}
-	hint := exit.Detail.Hint
+	hint := permErr.Hint
 	wantSubstrings := []string{
 		"https://open.feishu.cn/app/cli_x/auth?q=",
 		"im:message.group_at_msg",

cmd/event/runtime.go

@@ -6,8 +6,8 @@ package event
 import (
 	"context"
 	"encoding/json"
-	"fmt"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/client"
 	"github.com/larksuite/cli/internal/core"
 )
@@ -26,7 +26,11 @@ func (r *consumeRuntime) CallAPI(ctx context.Context, method, path string, body
 		As:     r.accessIdentity,
 	})
 	if err != nil {
-		return nil, err
+		if _, ok := errs.ProblemOf(err); ok {
+			return nil, err
+		}
+		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport,
+			"api %s %s: %s", method, path, err).WithCause(err)
 	}
 	// Non-JSON HTTP errors (gateway text/plain 404 etc.) skip OAPI envelope parsing.
 	ct := resp.Header.Get("Content-Type")
@@ -36,13 +40,22 @@ func (r *consumeRuntime) CallAPI(ctx context.Context, method, path string, body
 		if len(body) > maxBodyEcho {
 			body = body[:maxBodyEcho] + "…(truncated)"
 		}
-		return nil, fmt.Errorf("api %s %s returned %d: %s", method, path, resp.StatusCode, body)
+		if resp.StatusCode >= 500 {
+			return nil, errs.NewNetworkError(errs.SubtypeNetworkServer,
+				"api %s %s returned %d: %s", method, path, resp.StatusCode, body).WithRetryable()
+		}
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse,
+			"api %s %s returned %d: %s", method, path, resp.StatusCode, body)
 	}
 	result, err := client.ParseJSONResponse(resp)
 	if err != nil {
-		return nil, err
+		if _, ok := errs.ProblemOf(err); ok {
+			return nil, err
+		}
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse,
+			"api %s %s: %s", method, path, err).WithCause(err)
 	}
-	if apiErr := client.CheckLarkResponse(result); apiErr != nil {
+	if apiErr := r.client.CheckResponse(result, r.accessIdentity); apiErr != nil {
 		return json.RawMessage(resp.RawBody), apiErr
 	}
 	return json.RawMessage(resp.RawBody), nil

cmd/event/runtime_test.go

@@ -0,0 +1,147 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package event
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+
+	lark "github.com/larksuite/oapi-sdk-go/v3"
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/client"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/credential"
+)
+
+// staticTokenResolver always returns a fixed token without any HTTP calls.
+type staticTokenResolver struct{}
+
+func (s *staticTokenResolver) ResolveToken(_ context.Context, _ credential.TokenSpec) (*credential.TokenResult, error) {
+	return &credential.TokenResult{Token: "test-token"}, nil
+}
+
+// stubRoundTripper intercepts every outgoing request with a canned response.
+type stubRoundTripper struct {
+	respond func(*http.Request) (*http.Response, error)
+}
+
+func (s stubRoundTripper) RoundTrip(r *http.Request) (*http.Response, error) { return s.respond(r) }
+
+func newTestConsumeRuntime(rt http.RoundTripper) *consumeRuntime {
+	sdk := lark.NewClient("test-app", "test-secret",
+		lark.WithEnableTokenCache(false),
+		lark.WithLogLevel(larkcore.LogLevelError),
+		lark.WithHttpClient(&http.Client{Transport: rt}),
+	)
+	return &consumeRuntime{
+		client: &client.APIClient{
+			SDK:        sdk,
+			ErrOut:     io.Discard,
+			Credential: credential.NewCredentialProvider(nil, nil, &staticTokenResolver{}, nil),
+			Config:     &core.CliConfig{AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu},
+		},
+		accessIdentity: core.AsBot,
+	}
+}
+
+func stubResponse(status int, contentType, body string) func(*http.Request) (*http.Response, error) {
+	return func(r *http.Request) (*http.Response, error) {
+		return &http.Response{
+			StatusCode: status,
+			Header:     http.Header{"Content-Type": []string{contentType}},
+			Body:       io.NopCloser(strings.NewReader(body)),
+			Request:    r,
+		}, nil
+	}
+}
+
+func requireCallAPIProblem(t *testing.T, err error, category errs.Category, subtype errs.Subtype) {
+	t.Helper()
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed errs error, got %T: %v", err, err)
+	}
+	if p.Category != category || p.Subtype != subtype {
+		t.Fatalf("problem = %s/%s, want %s/%s", p.Category, p.Subtype, category, subtype)
+	}
+}
+
+func TestConsumeRuntimeCallAPI_NonJSONHTTPError(t *testing.T) {
+	r := newTestConsumeRuntime(stubRoundTripper{respond: stubResponse(http.StatusNotFound, "text/plain", "gone")})
+	_, err := r.CallAPI(context.Background(), "GET", "/open-apis/event/v1/connection", nil)
+	requireCallAPIProblem(t, err, errs.CategoryInternal, errs.SubtypeInvalidResponse)
+	if !strings.Contains(err.Error(), "returned 404") {
+		t.Errorf("error should echo the HTTP status, got: %v", err)
+	}
+}
+
+func TestConsumeRuntimeCallAPI_NonJSONHTTPErrorTruncatesLongBody(t *testing.T) {
+	long := strings.Repeat("x", 300)
+	r := newTestConsumeRuntime(stubRoundTripper{respond: stubResponse(http.StatusBadGateway, "text/html", long)})
+	_, err := r.CallAPI(context.Background(), "GET", "/open-apis/event/v1/connection", nil)
+	requireCallAPIProblem(t, err, errs.CategoryNetwork, errs.SubtypeNetworkServer)
+	p, _ := errs.ProblemOf(err)
+	if !p.Retryable {
+		t.Fatal("5xx non-JSON response should be marked retryable")
+	}
+	if !strings.Contains(err.Error(), "…(truncated)") {
+		t.Errorf("long body should be truncated in the message, got: %v", err)
+	}
+}
+
+func TestConsumeRuntimeCallAPI_UnparsableJSONBody(t *testing.T) {
+	r := newTestConsumeRuntime(stubRoundTripper{respond: stubResponse(http.StatusOK, "application/json", "{not json")})
+	_, err := r.CallAPI(context.Background(), "GET", "/open-apis/event/v1/connection", nil)
+	requireCallAPIProblem(t, err, errs.CategoryInternal, errs.SubtypeInvalidResponse)
+}
+
+func TestConsumeRuntimeCallAPI_TransportFailure(t *testing.T) {
+	r := newTestConsumeRuntime(stubRoundTripper{respond: func(*http.Request) (*http.Response, error) {
+		return nil, errors.New("connection refused")
+	}})
+	_, err := r.CallAPI(context.Background(), "GET", "/open-apis/event/v1/connection", nil)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed errs error, got %T: %v", err, err)
+	}
+	if p.Category != errs.CategoryNetwork {
+		t.Fatalf("category = %s, want %s", p.Category, errs.CategoryNetwork)
+	}
+}
+
+func TestConsumeRuntimeCallAPI_EnvelopeErrorIsTyped(t *testing.T) {
+	r := newTestConsumeRuntime(stubRoundTripper{respond: stubResponse(http.StatusOK, "application/json",
+		`{"code":99991663,"msg":"app not found"}`)})
+	_, err := r.CallAPI(context.Background(), "GET", "/open-apis/event/v1/connection", nil)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	if _, ok := errs.ProblemOf(err); !ok {
+		t.Fatalf("envelope error should be typed via BuildAPIError, got %T: %v", err, err)
+	}
+}
+
+func TestConsumeRuntimeCallAPI_Success(t *testing.T) {
+	r := newTestConsumeRuntime(stubRoundTripper{respond: stubResponse(http.StatusOK, "application/json",
+		`{"code":0,"data":{"ok":true}}`)})
+	raw, err := r.CallAPI(context.Background(), "GET", "/open-apis/event/v1/connection", nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(string(raw), `"code":0`) {
+		t.Errorf("raw body should pass through, got: %s", raw)
+	}
+}

cmd/event/schema.go

@@ -11,6 +11,7 @@ import (
 
 	"github.com/spf13/cobra"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	eventlib "github.com/larksuite/cli/internal/event"
 	"github.com/larksuite/cli/internal/event/schemas"
@@ -39,12 +40,14 @@ func resolveSchemaJSON(def *eventlib.KeyDefinition) (json.RawMessage, []string,
 	if len(def.Schema.FieldOverrides) > 0 {
 		var parsed map[string]interface{}
 		if err := json.Unmarshal(base, &parsed); err != nil {
-			return nil, nil, err
+			return nil, nil, errs.NewInternalError(errs.SubtypeUnknown,
+				"parse base schema for field overrides: %s", err).WithCause(err)
 		}
 		orphans := schemas.ApplyFieldOverrides(parsed, def.Schema.FieldOverrides)
 		out, err := json.Marshal(parsed)
 		if err != nil {
-			return nil, nil, err
+			return nil, nil, errs.NewInternalError(errs.SubtypeUnknown,
+				"serialize schema with field overrides: %s", err).WithCause(err)
 		}
 		return out, orphans, nil
 	}
@@ -73,7 +76,7 @@ func renderSpec(s *eventlib.SchemaSpec) (json.RawMessage, error) {
 		copy(buf, s.Raw)
 		return buf, nil
 	}
-	return nil, fmt.Errorf("schemaSpec has neither Type nor Raw")
+	return nil, errs.NewInternalError(errs.SubtypeUnknown, "schemaSpec has neither Type nor Raw")
 }
 
 func NewCmdSchema(f *cmdutil.Factory) *cobra.Command {
@@ -131,12 +134,16 @@ func runSchema(f *cmdutil.Factory, key string, asJSON bool) error {
 	if len(def.Params) > 0 {
 		fmt.Fprintf(out, "\nParameters:\n")
 		w := tabwriter.NewWriter(out, 0, 4, 2, ' ', 0)
-		fmt.Fprintf(w, "  NAME\tTYPE\tREQUIRED\tDEFAULT\tDESCRIPTION\n")
+		fmt.Fprintf(w, "  NAME\tTYPE\tREQUIRED\tSUB-KEY\tDEFAULT\tDESCRIPTION\n")
 		for _, p := range def.Params {
 			required := "no"
 			if p.Required {
 				required = "yes"
 			}
+			subKey := "no"
+			if p.SubscriptionKey {
+				subKey = "yes"
+			}
 			defaultVal := p.Default
 			if defaultVal == "" {
 				defaultVal = "-"
@@ -145,7 +152,7 @@ func runSchema(f *cmdutil.Factory, key string, asJSON bool) error {
 			if desc == "" {
 				desc = "-"
 			}
-			fmt.Fprintf(w, "  %s\t%s\t%s\t%s\t%s\n", p.Name, p.Type, required, defaultVal, desc)
+			fmt.Fprintf(w, "  %s\t%s\t%s\t%s\t%s\t%s\n", p.Name, p.Type, required, subKey, defaultVal, desc)
 		}
 		w.Flush()
 
@@ -165,7 +172,7 @@ func runSchema(f *cmdutil.Factory, key string, asJSON bool) error {
 
 	resolved, _, err := resolveSchemaJSON(def)
 	if err != nil {
-		return output.Errorf(output.ExitInternal, "internal", "resolve schema: %v", err)
+		return err
 	}
 	if resolved != nil {
 		fmt.Fprintf(out, "\nOutput Schema:\n")

cmd/event/schema_test.go

@@ -10,6 +10,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	eventlib "github.com/larksuite/cli/internal/event"
@@ -95,6 +96,79 @@ func TestRunSchema_JSONOutput(t *testing.T) {
 	}
 }
 
+func TestSchema_RendersSubscriptionKeyMarker(t *testing.T) {
+	const syntheticKey = "test.evt_sub"
+	t.Cleanup(func() { eventlib.UnregisterKeyForTest(syntheticKey) })
+
+	eventlib.RegisterKey(eventlib.KeyDefinition{
+		Key:       syntheticKey,
+		EventType: syntheticKey,
+		Params: []eventlib.ParamDef{
+			{Name: "mailbox", SubscriptionKey: true, Description: "subscription id source"},
+			{Name: "folders", Description: "filter only"},
+		},
+		Schema: eventlib.SchemaDef{Native: &eventlib.SchemaSpec{Type: reflect.TypeOf(struct{ X string }{})}},
+	})
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "test"})
+	if err := runSchema(f, syntheticKey, false); err != nil {
+		t.Fatalf("runSchema: %v", err)
+	}
+
+	out := stdout.String()
+	if !strings.Contains(out, "SUB-KEY") {
+		t.Errorf("missing SUB-KEY column header in:\n%s", out)
+	}
+
+	// Find the mailbox row and verify "yes" is present
+	var mailboxRow string
+	for _, ln := range strings.Split(out, "\n") {
+		if strings.Contains(ln, "mailbox") && !strings.Contains(ln, "NAME") {
+			mailboxRow = ln
+			break
+		}
+	}
+	if !strings.Contains(mailboxRow, "yes") {
+		t.Errorf("mailbox row missing yes SUB-KEY marker: %q", mailboxRow)
+	}
+
+	// Find the folders row and verify "no" is present
+	var foldersRow string
+	for _, ln := range strings.Split(out, "\n") {
+		if strings.Contains(ln, "folders") && !strings.Contains(ln, "NAME") {
+			foldersRow = ln
+			break
+		}
+	}
+	if !strings.Contains(foldersRow, "no") {
+		t.Errorf("folders row missing no SUB-KEY marker: %q", foldersRow)
+	}
+}
+
+func TestSchema_JSON_IncludesSubscriptionKey(t *testing.T) {
+	const syntheticKey = "test.evt_json"
+	t.Cleanup(func() { eventlib.UnregisterKeyForTest(syntheticKey) })
+
+	eventlib.RegisterKey(eventlib.KeyDefinition{
+		Key:       syntheticKey,
+		EventType: syntheticKey,
+		Params:    []eventlib.ParamDef{{Name: "mailbox", SubscriptionKey: true}},
+		Schema:    eventlib.SchemaDef{Native: &eventlib.SchemaSpec{Type: reflect.TypeOf(struct{ X string }{})}},
+	})
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "test"})
+	if err := runSchema(f, syntheticKey, true); err != nil {
+		t.Fatalf("runSchema json: %v", err)
+	}
+
+	if !strings.Contains(stdout.String(), `"subscription_key"`) {
+		t.Errorf("JSON output missing subscription_key field: %s", stdout.String())
+	}
+	if !strings.Contains(stdout.String(), `true`) {
+		t.Errorf("JSON output missing subscription_key: true value: %s", stdout.String())
+	}
+}
+
 func TestResolveSchemaJSON_CustomWithOverlay(t *testing.T) {
 	const syntheticKey = "t.custom.overlay"
 	t.Cleanup(func() { eventlib.UnregisterKeyForTest(syntheticKey) })
@@ -129,3 +203,38 @@ func TestResolveSchemaJSON_CustomWithOverlay(t *testing.T) {
 		t.Errorf("overlay format = %v, want open_id", got)
 	}
 }
+
+func TestRenderSpec_EmptySpecIsTypedInternalError(t *testing.T) {
+	_, err := renderSpec(&eventlib.SchemaSpec{})
+	if err == nil {
+		t.Fatal("expected error for spec with neither Type nor Raw")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed errs error, got %T: %v", err, err)
+	}
+	if p.Category != errs.CategoryInternal {
+		t.Errorf("category = %s, want %s", p.Category, errs.CategoryInternal)
+	}
+}
+
+func TestResolveSchemaJSON_InvalidBaseWithOverridesIsTypedInternalError(t *testing.T) {
+	def := &eventlib.KeyDefinition{
+		Key: "synthetic.invalid.base",
+		Schema: eventlib.SchemaDef{
+			Custom:         &eventlib.SchemaSpec{Raw: json.RawMessage("{not json")},
+			FieldOverrides: map[string]schemas.FieldMeta{"x": {}},
+		},
+	}
+	_, _, err := resolveSchemaJSON(def)
+	if err == nil {
+		t.Fatal("expected error for unparsable base schema")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed errs error, got %T: %v", err, err)
+	}
+	if p.Category != errs.CategoryInternal {
+		t.Errorf("category = %s, want %s", p.Category, errs.CategoryInternal)
+	}
+}

cmd/event/status.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"io"
 	"sort"
+	"strings"
 	"sync"
 	"time"
 
@@ -242,12 +243,17 @@ func writeStatusText(out io.Writer, statuses []appStatus) {
 				s.PID, (time.Duration(s.UptimeSec) * time.Second).String())
 			fmt.Fprintf(out, "  Active consumers: %d\n", s.Active)
 			if len(s.Consumers) > 0 {
-				headers := []string{"CONSUMER", "EVENT KEY", "RECEIVED", "DROPPED"}
+				headers := []string{"CONSUMER", "EVENT KEY", "SUB", "RECEIVED", "DROPPED"}
 				rows := make([][]string, 0, len(s.Consumers))
 				for _, c := range s.Consumers {
+					subDisplay := "-"
+					if c.SubscriptionID != "" && c.SubscriptionID != c.EventKey {
+						subDisplay = strings.TrimPrefix(c.SubscriptionID, c.EventKey+":")
+					}
 					rows = append(rows, []string{
 						fmt.Sprintf("pid=%d", c.PID),
 						c.EventKey,
+						subDisplay,
 						fmt.Sprintf("%d", c.Received),
 						fmt.Sprintf("%d", c.Dropped),
 					})

cmd/event/suggestions.go

@@ -8,8 +8,9 @@ import (
 	"sort"
 	"strings"
 
+	"github.com/larksuite/cli/errs"
 	eventlib "github.com/larksuite/cli/internal/event"
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/suggest"
 )
 
 const maxSuggestions = 3
@@ -28,7 +29,7 @@ func suggestEventKeys(input string) []string {
 			hits = append(hits, match{def.Key, 0})
 			continue
 		}
-		if d := levenshtein(input, def.Key); d <= threshold {
+		if d := suggest.Levenshtein(input, def.Key); d <= threshold {
 			hits = append(hits, match{def.Key, d})
 		}
 	}
@@ -63,40 +64,6 @@ func unknownEventKeyErr(key string) error {
 	if guesses := suggestEventKeys(key); len(guesses) > 0 {
 		msg += " — did you mean " + formatSuggestions(guesses) + "?"
 	}
-	return output.ErrWithHint(
-		output.ExitValidation, "validation",
-		msg,
-		"Run 'lark-cli event list' to see available keys.",
-	)
-}
-
-// levenshtein computes classic edit distance (two-row DP).
-func levenshtein(a, b string) int {
-	if a == b {
-		return 0
-	}
-	ra, rb := []rune(a), []rune(b)
-	if len(ra) == 0 {
-		return len(rb)
-	}
-	if len(rb) == 0 {
-		return len(ra)
-	}
-	prev := make([]int, len(rb)+1)
-	curr := make([]int, len(rb)+1)
-	for j := range prev {
-		prev[j] = j
-	}
-	for i := 1; i <= len(ra); i++ {
-		curr[0] = i
-		for j := 1; j <= len(rb); j++ {
-			cost := 1
-			if ra[i-1] == rb[j-1] {
-				cost = 0
-			}
-			curr[j] = min(prev[j]+1, curr[j-1]+1, prev[j-1]+cost)
-		}
-		prev, curr = curr, prev
-	}
-	return prev[len(rb)]
+	return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", msg).
+		WithHint("Run 'lark-cli event list' to see available keys.")
 }

cmd/event/suggestions_test.go

@@ -10,27 +10,6 @@ import (
 	_ "github.com/larksuite/cli/events"
 )
 
-func TestLevenshtein(t *testing.T) {
-	cases := []struct {
-		a, b string
-		want int
-	}{
-		{"", "", 0},
-		{"a", "", 1},
-		{"", "abc", 3},
-		{"kitten", "kitten", 0},
-		{"kitten", "sitten", 1},
-		{"kitten", "sitting", 3},
-		{"飞书", "飞书", 0},
-		{"飞书", "飞s", 1},
-	}
-	for _, tc := range cases {
-		if got := levenshtein(tc.a, tc.b); got != tc.want {
-			t.Errorf("levenshtein(%q,%q) = %d, want %d", tc.a, tc.b, got, tc.want)
-		}
-	}
-}
-
 func TestSuggestEventKeys(t *testing.T) {
 	cases := []struct {
 		name              string

cmd/flag_suggest_test.go

@@ -0,0 +1,70 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd
+
+import (
+	"errors"
+	"slices"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/spf13/cobra"
+)
+
+func TestUnknownFlagName(t *testing.T) {
+	cases := []struct {
+		in   string
+		name string
+		ok   bool
+	}{
+		{"unknown flag: --query", "query", true},
+		{"unknown flag: --with-styles", "with-styles", true},
+		{"unknown shorthand flag: 'z' in -z", "", false},
+		{"flag needs an argument: --find", "", false},
+		{`invalid argument "x" for "--count"`, "", false},
+	}
+	for _, c := range cases {
+		name, ok := unknownFlagName(errors.New(c.in))
+		if name != c.name || ok != c.ok {
+			t.Errorf("unknownFlagName(%q) = (%q,%v), want (%q,%v)", c.in, name, ok, c.name, c.ok)
+		}
+	}
+}
+
+func TestFlagDidYouMean_UnknownFlagSuggestsAndListsValid(t *testing.T) {
+	c := &cobra.Command{Use: "demo"}
+	c.Flags().String("range", "", "")
+	c.Flags().String("find", "", "")
+	c.Flags().Bool("dry-run", false, "")
+
+	err := flagDidYouMean(c, errors.New("unknown flag: --rang")) // typo of --range
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T", err)
+	}
+	if exitErr.Detail.Type != "unknown_flag" {
+		t.Errorf("type = %q, want unknown_flag", exitErr.Detail.Type)
+	}
+	if !strings.Contains(exitErr.Detail.Hint, "--range") {
+		t.Errorf("hint should suggest --range, got %q", exitErr.Detail.Hint)
+	}
+	detail, _ := exitErr.Detail.Detail.(map[string]any)
+	valid, _ := detail["valid_flags"].([]string)
+	if !slices.Contains(valid, "find") || !slices.Contains(valid, "range") {
+		t.Errorf("valid_flags should list find & range, got %v", valid)
+	}
+}
+
+func TestFlagDidYouMean_OtherErrorStaysGeneric(t *testing.T) {
+	c := &cobra.Command{Use: "demo"}
+	err := flagDidYouMean(c, errors.New("flag needs an argument: --find"))
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T", err)
+	}
+	if exitErr.Detail.Type != "flag_error" {
+		t.Errorf("type = %q, want flag_error (non-unknown-flag errors stay generic)", exitErr.Detail.Type)
+	}
+}

cmd/notice_test.go

@@ -0,0 +1,61 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/deprecation"
+)
+
+// composePendingNotice must surface a deprecated-command alias under the
+// "deprecated_command" key, with the migration target and a skill-update hint,
+// so the JSON "_notice" envelope reaches users who run pre-refactor commands
+// without ever reading --help.
+func TestComposePendingNoticeDeprecatedCommand(t *testing.T) {
+	t.Cleanup(func() { deprecation.SetPending(nil) })
+
+	deprecation.SetPending(&deprecation.Notice{
+		Command:     "+read",
+		Replacement: "+cells-get",
+		Skill:       "lark-sheets",
+	})
+
+	got := composePendingNotice()
+	if got == nil {
+		t.Fatal("composePendingNotice() = nil, want deprecated_command entry")
+	}
+	entry, ok := got["deprecated_command"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("missing deprecated_command key: %#v", got)
+	}
+	if entry["command"] != "+read" {
+		t.Errorf("command = %v, want +read", entry["command"])
+	}
+	if entry["replacement"] != "+cells-get" {
+		t.Errorf("replacement = %v, want +cells-get", entry["replacement"])
+	}
+	if entry["skill"] != "lark-sheets" {
+		t.Errorf("skill = %v, want lark-sheets", entry["skill"])
+	}
+	if msg, _ := entry["message"].(string); !strings.Contains(msg, "update your lark-sheets skill") {
+		t.Errorf("message missing skill-update hint: %q", msg)
+	}
+}
+
+// With nothing pending, the provider returns nil so no "_notice" field is
+// emitted on a clean run.
+func TestComposePendingNoticeEmpty(t *testing.T) {
+	t.Cleanup(func() { deprecation.SetPending(nil) })
+	deprecation.SetPending(nil)
+
+	if got := composePendingNotice(); got != nil {
+		// update/skills pending are process-global; only assert the absence of
+		// our own key to stay robust against unrelated pending state.
+		if _, ok := got["deprecated_command"]; ok {
+			t.Fatalf("deprecated_command present after clear: %#v", got)
+		}
+	}
+}

cmd/platform_bootstrap.go

@@ -36,47 +36,71 @@ const userPolicyFileName = "policy.yml"
 // pluginRules carries Plugin.Restrict() contributions collected from
 // the InstallAll phase; nil/empty is fine.
 func applyUserPolicyPruning(rootCmd *cobra.Command, pluginRules []cmdpolicy.PluginRule) error {
-	yamlPath, err := userPolicyPath()
-	if err != 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.
-		yamlPath = ""
+	// 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
 	}
 
-	yamlRule, err := cmdpolicy.LoadYAMLPolicy(yamlPath)
-	if err != 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 err
-	}
-
-	rule, source, err := cmdpolicy.Resolve(cmdpolicy.Sources{
+	rules, source, err := cmdpolicy.Resolve(cmdpolicy.Sources{
 		PluginRules: pluginRules,
-		YAMLRule:    yamlRule,
+		YAMLRules:   yamlRules,
 		YAMLPath:    yamlPath,
 	})
 	if err != nil {
 		cmdpolicy.SetActive(nil)
 		return err
 	}
-	if rule == nil {
+	if len(rules) == 0 {
 		cmdpolicy.SetActive(&cmdpolicy.ActivePolicy{Source: source})
 		return nil
 	}
 
-	engine := cmdpolicy.New(rule)
+	// 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, rule.Name)
+	denied := cmdpolicy.BuildDeniedByPath(rootCmd, decisions, source, ruleName)
 	cmdpolicy.Apply(rootCmd, denied)
 
 	cmdpolicy.SetActive(&cmdpolicy.ActivePolicy{
-		Rule:        rule,
+		Rules:       rules,
 		Source:      source,
 		DeniedPaths: len(denied),
 	})

cmd/platform_bootstrap_test.go

@@ -13,6 +13,8 @@ import (
 
 	"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"
 )
@@ -184,6 +186,39 @@ func TestApplyUserPolicyPruning_malformedYamlReturnsError(t *testing.T) {
 	}
 }
 
+// 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.

cmd/platform_guards.go

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

cmd/profile/add.go

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

cmd/profile/profile_test.go

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

cmd/prune.go

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

cmd/root.go

@@ -4,30 +4,31 @@
 package cmd
 
 import (
-	"bytes"
 	"context"
-	"encoding/json"
 	"errors"
 	"fmt"
-	"io"
-	"net/url"
 	"os"
 	"sort"
-	"strconv"
 	"strings"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/platform"
 	internalauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/build"
 	"github.com/larksuite/cli/internal/cmdpolicy"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/deprecation"
+	"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"
+	"github.com/larksuite/cli/internal/suggest"
 	"github.com/larksuite/cli/internal/update"
 	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
 )
 
 const rootLong = `lark-cli — Lark/Feishu CLI tool.
@@ -35,7 +36,7 @@ const rootLong = `lark-cli — Lark/Feishu CLI tool.
 USAGE:
     lark-cli <command> [subcommand] [method] [options]
     lark-cli api <method> <path> [--params <json>] [--data <json>]
-    lark-cli schema <service.resource.method> [--format pretty]
+    lark-cli schema <service.resource.method>
 
 EXAMPLES:
     # View upcoming events
@@ -50,20 +51,6 @@ 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.
@@ -85,7 +72,15 @@ COMMUNITY:
 More help: lark-cli <command> --help`
 
 // Execute runs the root command and returns the process exit code.
+// rawInvocationArgs holds os.Args[1:] captured at Execute() entry. cobra's
+// UnknownFlags whitelist (installUnknownSubcommandGuard) swallows unknown flags
+// before they reach a group's RunE, so unknownSubcommandRunE re-derives them
+// from here. It stays nil in unit tests that invoke a RunE directly with
+// explicit args — correct, since those don't exercise the whitelist path.
+var rawInvocationArgs []string
+
 func Execute() int {
+	rawInvocationArgs = os.Args[1:]
 	inv, err := BootstrapInvocationContext(os.Args[1:])
 	if err != nil {
 		fmt.Fprintln(os.Stderr, "Error:", err)
@@ -149,29 +144,49 @@ func setupNotices() {
 	skillscheck.Init(build.Version)
 
 	// Composed notice provider — emits keys only when each pending is set.
-	output.PendingNotice = func() map[string]interface{} {
-		notice := map[string]interface{}{}
-		if info := update.GetPending(); info != nil {
-			notice["update"] = map[string]interface{}{
-				"current": info.Current,
-				"latest":  info.Latest,
-				"message": info.Message(),
-				"command": "lark-cli update",
-			}
+	output.PendingNotice = composePendingNotice
+}
+
+// composePendingNotice merges all process-level pending notices (available
+// update, skills/binary drift, deprecated-command alias) into the map surfaced
+// as the JSON "_notice" envelope field. Returns nil when nothing is pending.
+// Extracted from Execute so the composition is unit-testable.
+func composePendingNotice() map[string]interface{} {
+	notice := map[string]interface{}{}
+	if info := update.GetPending(); info != nil {
+		notice["update"] = map[string]interface{}{
+			"current": info.Current,
+			"latest":  info.Latest,
+			"message": info.Message(),
+			"command": "lark-cli update",
 		}
-		if stale := skillscheck.GetPending(); stale != nil {
-			notice["skills"] = map[string]interface{}{
-				"current": stale.Current,
-				"target":  stale.Target,
-				"message": stale.Message(),
-				"command": "lark-cli update",
-			}
-		}
-		if len(notice) == 0 {
-			return nil
-		}
-		return notice
 	}
+	if stale := skillscheck.GetPending(); stale != nil {
+		notice["skills"] = map[string]interface{}{
+			"current": stale.Current,
+			"target":  stale.Target,
+			"message": stale.Message(),
+			"command": "lark-cli update",
+		}
+	}
+	if dep := deprecation.GetPending(); dep != nil {
+		entry := map[string]interface{}{
+			"command": dep.Command,
+			"message": dep.Message(),
+			"action":  "lark-cli update",
+		}
+		if dep.Replacement != "" {
+			entry["replacement"] = dep.Replacement
+		}
+		if dep.Skill != "" {
+			entry["skill"] = dep.Skill
+		}
+		notice["deprecated_command"] = entry
+	}
+	if len(notice) == 0 {
+		return nil
+	}
+	return notice
 }
 
 // isCompletionCommand returns true if args indicate a shell completion request.
@@ -200,22 +215,75 @@ 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
 
-	// 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
+	// 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
 	}
 
-	// All other structured errors normalize to ExitError.
 	if exitErr := asExitError(err); exitErr != nil {
 		if !exitErr.Raw {
-			// Raw errors (e.g. from `api` command) preserve the original API
-			// error detail; skip enrichment which would clear it.
+			// Raw errors (e.g. from `api` command via output.MarkRaw)
+			// preserve the original API error detail; skip enrichment
+			// which would clear it.
 			enrichMissingScopeError(f, exitErr)
 			enrichPermissionError(f, exitErr)
 		}
@@ -223,13 +291,36 @@ func handleRootError(f *cmdutil.Factory, err error) int {
 		return exitErr.Code
 	}
 
-	// Cobra errors (required flags, unknown commands, etc.)
+	// A backward-compat alias records its deprecation notice in PreRunE, which
+	// runs before cobra's required-flag validation — but a missing required flag
+	// fails before RunE and lands here, where the bare "Error:" line would drop
+	// the notice. When a deprecation is pending, route through the structured
+	// envelope so the migration hint still reaches the caller; all other errors
+	// keep the existing plain output.
+	if deprecation.GetPending() != nil {
+		output.WriteErrorEnvelope(errOut, &output.ExitError{
+			Code:   1,
+			Detail: &output.ErrDetail{Type: "validation", Message: err.Error()},
+		}, string(f.ResolvedIdentity))
+		return 1
+	}
 	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) {
@@ -242,49 +333,6 @@ func asExitError(err error) *output.ExitError {
 	return nil
 }
 
-// writeSecurityPolicyError writes the security-policy-specific JSON envelope to w.
-// This format intentionally differs from the standard ErrDetail envelope:
-// it uses string codes ("challenge_required"/"access_denied") and extra fields
-// (retryable, challenge_url) for machine-readable policy error handling.
-func writeSecurityPolicyError(w io.Writer, spErr *internalauth.SecurityPolicyError) {
-	var codeStr string
-	switch spErr.Code {
-	case internalauth.LarkErrBlockByPolicyTryAuth:
-		codeStr = "challenge_required"
-	case internalauth.LarkErrBlockByPolicy:
-		codeStr = "access_denied"
-	default:
-		codeStr = strconv.Itoa(spErr.Code)
-	}
-
-	errData := map[string]interface{}{
-		"type":      "auth_error",
-		"code":      codeStr,
-		"message":   spErr.Message,
-		"retryable": false,
-	}
-	if spErr.ChallengeURL != "" {
-		errData["challenge_url"] = spErr.ChallengeURL
-	}
-	if spErr.CLIHint != "" {
-		errData["hint"] = spErr.CLIHint
-	}
-
-	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
-	}
-	fmt.Fprint(w, buffer.String())
-}
-
 // installUnknownSubcommandGuard replaces cobra's silent help fallback on
 // group commands (no Run/RunE) with an unknown_subcommand error.
 //
@@ -297,6 +345,12 @@ func writeSecurityPolicyError(w io.Writer, spErr *internalauth.SecurityPolicyErr
 func installUnknownSubcommandGuard(cmd *cobra.Command) {
 	if cmd.HasSubCommands() && cmd.Run == nil && cmd.RunE == nil {
 		cmd.RunE = unknownSubcommandRunE
+		// Route an unknown subcommand to unknownSubcommandRunE even when flags
+		// are also present (e.g. `sheets +cells-find --url ...`). A pure group
+		// consumes no flags itself, so unknown flags belong to the (missing)
+		// subcommand; whitelisting them here prevents cobra from erroring on the
+		// flag first and printing usage instead of our structured suggestion.
+		cmd.FParseErrWhitelist.UnknownFlags = true
 		if cmd.Annotations == nil {
 			cmd.Annotations = map[string]string{}
 		}
@@ -307,16 +361,98 @@ func installUnknownSubcommandGuard(cmd *cobra.Command) {
 	}
 }
 
+// Deprecated: unknownSubcommandRunE produces a legacy *output.ExitError that
+// predates the typed error contract introduced by errs/. New code MUST NOT
+// add producers of this shape — unknown-subcommand signals should move to
+// a typed *errs.ValidationError (or a dedicated typed error) carrying the
+// agent-protocol metadata as typed extension fields. This helper is retained
+// only while existing dispatch sites are migrated; it will be removed once
+// they have moved to the typed surface.
 func unknownSubcommandRunE(cmd *cobra.Command, args []string) error {
 	if len(args) == 0 {
-		return cmd.Help()
+		// A bare group (e.g. `sheets`), or one carrying only group-valid flags
+		// like the global --profile, legitimately prints help. But a flag that
+		// belongs to a (missing) subcommand is a user error: the guard's
+		// FParseErrWhitelist swallows such flags and leaves args empty, so without
+		// the checks below they would silently fall through to help + exit 0 —
+		// letting an agent mistake a malformed call (`im --format json`,
+		// `sheets --badflag`) for success. Recover the swallowed tokens from the
+		// raw invocation and fail structured instead.
+		flags := flagTokensInArgs(rawInvocationArgs)
+		if len(flags) == 0 {
+			return cmd.Help()
+		}
+		if unknown := unknownFlagTokens(cmd, rawInvocationArgs); len(unknown) > 0 {
+			return &output.ExitError{
+				Code: output.ExitValidation,
+				Detail: &output.ErrDetail{
+					Type:    "unknown_flag",
+					Message: fmt.Sprintf("unknown flag %s before a subcommand for %q", strings.Join(unknown, ", "), cmd.CommandPath()),
+					Hint:    fmt.Sprintf("flags belong to a subcommand; run `%s --help` to list subcommands and their flags", cmd.CommandPath()),
+					Detail: map[string]any{
+						// Keep the same detail keys as flagDidYouMean's unknown_flag
+						// so a consumer keyed on Type can read a stable shape. The
+						// subcommand isn't resolved here, so suggestions/valid_flags
+						// have no meaningful universe to draw from — emit empty
+						// rather than the group's own (misleading) flags. unknown is
+						// the back-compat singular field; unknown_flags carries the
+						// full list when more than one flag was supplied.
+						"unknown":       strings.Join(unknown, ", "),
+						"unknown_flags": unknown,
+						"command_path":  cmd.CommandPath(),
+						"suggestions":   []string{},
+						"valid_flags":   []string{},
+					},
+				},
+			}
+		}
+		// The remaining flags are all defined somewhere in the tree. Those valid
+		// on the group itself or inherited (e.g. the global --profile) do not
+		// require a subcommand, so a bare group carrying only those still prints
+		// help. Anything left belongs to a subcommand that was omitted
+		// (e.g. `im --format json`): distinct from unknown_flag — the flags are
+		// real, the subcommand is what's missing.
+		misplaced := subcommandOnlyFlagTokens(cmd, rawInvocationArgs)
+		if len(misplaced) == 0 {
+			return cmd.Help()
+		}
+		return &output.ExitError{
+			Code: output.ExitValidation,
+			Detail: &output.ErrDetail{
+				Type:    "missing_subcommand",
+				Message: fmt.Sprintf("missing subcommand for %q; flag %s belongs to a subcommand, not the group", cmd.CommandPath(), strings.Join(misplaced, ", ")),
+				Hint:    fmt.Sprintf("run `%s --help` to list subcommands and their flags", cmd.CommandPath()),
+				Detail: map[string]any{
+					"command_path": cmd.CommandPath(),
+					"flags":        misplaced,
+					"suggestions":  []string{},
+				},
+			},
+		}
 	}
 	unknown := args[0]
-	available := availableSubcommandNames(cmd)
+	available, deprecated := availableSubcommandNames(cmd)
+	// Rank suggestions across both current and deprecated names so a mistyped
+	// legacy command (e.g. +raed → +read) still resolves; the alias stays
+	// runnable and self-flags via the _notice on execution.
+	suggestions := suggest.Closest(unknown, append(append([]string{}, available...), deprecated...), 6)
 	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 len(suggestions) > 0 {
+		hint = fmt.Sprintf("did you mean one of: %s? (run `%s --help` for the full list)",
+			strings.Join(suggestions, ", "), cmd.CommandPath())
+	}
+	detail := map[string]any{
+		"unknown":      unknown,
+		"command_path": cmd.CommandPath(),
+		"suggestions":  suggestions,
+		"available":    available,
+	}
+	// Only services with backward-compat aliases (currently sheets) carry a
+	// deprecated bucket; omit the key elsewhere so every other service's
+	// envelope is unchanged.
+	if len(deprecated) > 0 {
+		detail["deprecated"] = deprecated
 	}
 	return &output.ExitError{
 		Code: output.ExitValidation,
@@ -324,17 +460,114 @@ func unknownSubcommandRunE(cmd *cobra.Command, args []string) error {
 			Type:    "unknown_subcommand",
 			Message: msg,
 			Hint:    hint,
-			Detail: map[string]any{
-				"unknown":      unknown,
-				"command_path": cmd.CommandPath(),
-				"available":    available,
-			},
+			Detail:  detail,
 		},
 	}
 }
 
-func availableSubcommandNames(cmd *cobra.Command) []string {
-	subs := make([]string, 0, len(cmd.Commands()))
+// flagTokensInArgs returns the flag-like tokens (-x, --foo, --foo=bar) in
+// rawArgs, stopping at the "--" positional terminator. Whether a flag is
+// defined is not considered (see unknownFlagTokens for that). A pure group
+// with any flag token but no subcommand is a user error — a pure group
+// consumes no flags of its own, so the flag must belong to a subcommand — so
+// the caller fails structured instead of falling through to help.
+func flagTokensInArgs(rawArgs []string) []string {
+	var toks []string
+	for _, a := range rawArgs {
+		if a == "--" {
+			break // everything after -- is positional
+		}
+		if len(a) < 2 || a[0] != '-' {
+			continue
+		}
+		toks = append(toks, a)
+	}
+	return toks
+}
+
+// unknownFlagTokens returns the flag tokens in rawArgs that cmd does not define
+// (on itself, inherited, or any direct subcommand). installUnknownSubcommandGuard
+// whitelists unknown flags on pure groups so a mistyped subcommand still reaches
+// the suggestion path; the side effect is that flags before a subcommand are
+// swallowed. This recovers the genuinely-unknown ones so the caller can name
+// them in a "did you mean" envelope.
+func unknownFlagTokens(cmd *cobra.Command, rawArgs []string) []string {
+	var unknown []string
+	for _, a := range flagTokensInArgs(rawArgs) {
+		name := strings.SplitN(strings.TrimLeft(a, "-"), "=", 2)[0]
+		if name != "" && !flagDefinedInTree(cmd, name) {
+			unknown = append(unknown, a)
+		}
+	}
+	return unknown
+}
+
+// flagKnownOnGroup reports whether name is a flag defined on cmd itself or
+// inherited (a global persistent flag like --profile) — i.e. valid on the bare
+// group and therefore not requiring a subcommand.
+func flagKnownOnGroup(cmd *cobra.Command, name string) bool {
+	short := len(name) == 1
+	lookup := func(fs *pflag.FlagSet) bool {
+		if short {
+			return fs.ShorthandLookup(name) != nil
+		}
+		return fs.Lookup(name) != nil
+	}
+	return lookup(cmd.Flags()) || lookup(cmd.InheritedFlags())
+}
+
+// subcommandOnlyFlagTokens returns the flag tokens in rawArgs that are valid on
+// a subcommand of cmd but not on cmd itself/inherited — flags supplied while
+// omitting the subcommand they belong to (`im --format json`). Global flags
+// valid on the bare group (e.g. --profile) are excluded so
+// `lark-cli --profile p im` still prints help rather than erroring.
+func subcommandOnlyFlagTokens(cmd *cobra.Command, rawArgs []string) []string {
+	var misplaced []string
+	for _, a := range flagTokensInArgs(rawArgs) {
+		name := strings.SplitN(strings.TrimLeft(a, "-"), "=", 2)[0]
+		if name == "" || flagKnownOnGroup(cmd, name) {
+			continue
+		}
+		if flagDefinedInTree(cmd, name) {
+			misplaced = append(misplaced, a)
+		}
+	}
+	return misplaced
+}
+
+// flagDefinedInTree reports whether name is defined on cmd, its inherited
+// (persistent) flags, or any direct subcommand. The subcommand case covers a
+// user who merely omitted the subcommand — e.g. `sheets --format json`, where
+// --format is injected on every leaf shortcut, not on the group — so only a
+// genuinely unknown flag like `sheets --badflag` is reported.
+func flagDefinedInTree(cmd *cobra.Command, name string) bool {
+	short := len(name) == 1
+	known := func(c *cobra.Command, inherited bool) bool {
+		fs := c.Flags()
+		if inherited {
+			fs = c.InheritedFlags()
+		}
+		if short {
+			return fs.ShorthandLookup(name) != nil
+		}
+		return fs.Lookup(name) != nil
+	}
+	if known(cmd, false) || known(cmd, true) {
+		return true
+	}
+	for _, c := range cmd.Commands() {
+		if known(c, false) {
+			return true
+		}
+	}
+	return false
+}
+
+// availableSubcommandNames returns the invokable subcommand names of cmd, split
+// into current commands and backward-compatibility aliases (those tagged into
+// the deprecated cobra group via cmdutil.DeprecatedGroupID). Both slices are
+// sorted; hidden commands plus help/completion are omitted.
+func availableSubcommandNames(cmd *cobra.Command) (available, deprecated []string) {
 	for _, c := range cmd.Commands() {
 		if c.Hidden || !c.IsAvailableCommand() {
 			continue
@@ -343,10 +576,95 @@ func availableSubcommandNames(cmd *cobra.Command) []string {
 		if name == "help" || name == "completion" {
 			continue
 		}
-		subs = append(subs, name)
+		if cmdutil.IsDeprecatedCommand(c) {
+			deprecated = append(deprecated, name)
+		} else {
+			available = append(available, name)
+		}
 	}
-	sort.Strings(subs)
-	return subs
+	sort.Strings(available)
+	sort.Strings(deprecated)
+	return available, deprecated
+}
+
+// flagDidYouMean is the root FlagErrorFunc (inherited by all subcommands). It
+// converts cobra's flag-parse errors into the structured ErrorEnvelope: an
+// unknown flag gets a focused "did you mean" hint plus the full valid-flag list
+// in detail (so agents recover even when the typo is semantic, e.g. --query vs
+// --find, where edit distance alone finds nothing). Other flag errors stay
+// structured but generic.
+func flagDidYouMean(c *cobra.Command, ferr error) error {
+	name, isUnknown := unknownFlagName(ferr)
+	if !isUnknown {
+		return &output.ExitError{
+			Code: output.ExitValidation,
+			Detail: &output.ErrDetail{
+				Type:    "flag_error",
+				Message: ferr.Error(),
+				Hint:    fmt.Sprintf("run `%s --help` for valid flags", c.CommandPath()),
+			},
+		}
+	}
+	valid := visibleFlagNames(c)
+	suggestions := suggest.Closest(name, valid, 3)
+	hint := fmt.Sprintf("run `%s --help` to see valid flags", c.CommandPath())
+	if len(suggestions) > 0 {
+		for i := range suggestions {
+			suggestions[i] = "--" + suggestions[i]
+		}
+		hint = fmt.Sprintf("did you mean %s? (run `%s --help` for all flags)",
+			strings.Join(suggestions, ", "), c.CommandPath())
+	}
+	return &output.ExitError{
+		Code: output.ExitValidation,
+		Detail: &output.ErrDetail{
+			Type:    "unknown_flag",
+			Message: fmt.Sprintf("unknown flag %q for %q", "--"+name, c.CommandPath()),
+			Hint:    hint,
+			Detail: map[string]any{
+				"unknown":      "--" + name,
+				"command_path": c.CommandPath(),
+				"suggestions":  suggestions,
+				"valid_flags":  valid,
+			},
+		},
+	}
+}
+
+// unknownFlagName extracts the offending long-flag name from cobra's flag-parse
+// error text ("unknown flag: --query" → "query"). Returns ok=false for anything
+// else (missing argument, invalid value, unknown shorthand) so the caller keeps
+// those structured but generic — hallucinated flags are essentially always long.
+//
+// CONTRACT: this matches cobra's English wording "unknown flag: --" (go.mod
+// pins github.com/spf13/cobra). If cobra rewords this or gains i18n the match
+// silently fails and unknown flags degrade to a generic flag_error — re-verify
+// this prefix when bumping cobra.
+func unknownFlagName(err error) (string, bool) {
+	const p = "unknown flag: --"
+	msg := err.Error()
+	i := strings.Index(msg, p)
+	if i < 0 {
+		return "", false
+	}
+	rest := msg[i+len(p):]
+	if j := strings.IndexAny(rest, " \t"); j >= 0 {
+		rest = rest[:j]
+	}
+	return rest, true
+}
+
+// visibleFlagNames lists the non-hidden flag names of c (for suggestions and
+// the valid_flags detail).
+func visibleFlagNames(c *cobra.Command) []string {
+	var names []string
+	c.Flags().VisitAll(func(f *pflag.Flag) {
+		if !f.Hidden {
+			names = append(names, f.Name)
+		}
+	})
+	sort.Strings(names)
+	return names
 }
 
 // installTipsHelpFunc wraps the default help function to append a TIPS section
@@ -381,97 +699,55 @@ func installTipsHelpFunc(root *cobra.Command) {
 	})
 }
 
-// enrichPermissionError adds console_url and improves the hint for permission errors.
-// It differentiates between:
-//   - LarkErrAppScopeNotEnabled (99991672): app has not enabled the API scope → hint to admin console
-//   - LarkErrUserScopeInsufficient (99991679): user has not authorized the scope → hint to auth login --scope
+// enrichPermissionError 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.
 func enrichPermissionError(f *cmdutil.Factory, exitErr *output.ExitError) {
-	if exitErr.Detail == nil || exitErr.Detail.Type != "permission" {
+	if exitErr.Detail == nil {
 		return
 	}
-	// Extract required scopes from API error detail
-	scopes := extractRequiredScopes(exitErr.Detail.Detail)
-	if len(scopes) == 0 {
+	// 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" {
 		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
 	}
 
-	// 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]
-	}
+	// 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)
 
-	// 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
+	// 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
+	identity := string(f.ResolvedIdentity)
+	if identity == "" {
+		identity = "user"
 	}
-}
-
-// 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
+
+	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
 }

cmd/root_integration_test.go

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

cmd/root_test.go

@@ -4,19 +4,26 @@
 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/deprecation"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/registry"
-	"github.com/spf13/cobra"
 )
 
 // TestPersistentPreRunE_AuthCheckDisabledAnnotations verifies that
@@ -68,273 +75,6 @@ func TestPersistentPreRunE_ConfigSubcommands(t *testing.T) {
 	}
 }
 
-func TestHandleRootError_RawError_SkipsEnrichmentButWritesEnvelope(t *testing.T) {
-	f, _, stderr, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-
-	// Create a permission error (would normally be enriched) and mark it Raw
-	err := output.ErrAPI(output.LarkErrAppScopeNotEnabled, "API error: [99991672] scope not enabled", map[string]interface{}{
-		"permission_violations": []interface{}{
-			map[string]interface{}{"subject": "calendar:calendar:readonly"},
-		},
-	})
-	err.Raw = true
-
-	code := handleRootError(f, err)
-	if code != output.ExitAPI {
-		t.Errorf("expected exit code %d, got %d", output.ExitAPI, code)
-	}
-	// stderr should contain the error envelope
-	if stderr.Len() == 0 {
-		t.Error("expected non-empty stderr for Raw error — WriteErrorEnvelope should always run")
-	}
-	// The message should NOT have been enriched by enrichPermissionError
-	// (ErrAPI sets "Permission denied [code]" but enrichment would replace it with "App scope not enabled: ...")
-	if strings.Contains(err.Error(), "App scope not enabled") {
-		t.Errorf("expected message not enriched, got: %s", err.Error())
-	}
-	// Detail.Detail should be preserved (enrichPermissionError clears it to nil)
-	if err.Detail != nil && err.Detail.Detail == nil {
-		t.Error("expected Detail.Detail to be preserved, but it was cleared")
-	}
-}
-
-func TestHandleRootError_NonRawError_EnrichesAndWritesEnvelope(t *testing.T) {
-	f, _, stderr, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-
-	// Create a permission error without Raw — should be enriched
-	err := output.ErrAPI(output.LarkErrAppScopeNotEnabled, "API error: [99991672] scope not enabled", map[string]interface{}{
-		"permission_violations": []interface{}{
-			map[string]interface{}{"subject": "calendar:calendar:readonly"},
-		},
-	})
-
-	code := handleRootError(f, err)
-	if code != output.ExitAPI {
-		t.Errorf("expected exit code %d, got %d", output.ExitAPI, code)
-	}
-	// stderr should contain the error envelope
-	if stderr.Len() == 0 {
-		t.Error("expected non-empty stderr for non-Raw error")
-	}
-	// The message should have been enriched
-	if !strings.Contains(err.Error(), "App scope not enabled") {
-		t.Errorf("expected enriched message, got: %s", err.Error())
-	}
-}
-
-func TestEnrichPermissionError_SpecialCharsEscaped(t *testing.T) {
-	tests := []struct {
-		name      string
-		appID     string
-		scope     string
-		wantInURL string // substring that must appear in console_url
-		denyInURL string // substring that must NOT appear raw in console_url
-	}{
-		{
-			name:      "ampersand in scope",
-			appID:     "cli_good",
-			scope:     "scope&evil=injected",
-			wantInURL: "scopes=scope%26evil%3Dinjected",
-			denyInURL: "scopes=scope&evil=injected",
-		},
-		{
-			name:      "hash in scope",
-			appID:     "cli_good",
-			scope:     "scope#fragment",
-			wantInURL: "scopes=scope%23fragment",
-			denyInURL: "scopes=scope#fragment",
-		},
-		{
-			name:      "space in scope",
-			appID:     "cli_good",
-			scope:     "scope with spaces",
-			wantInURL: "scopes=scope+with+spaces",
-		},
-		{
-			name:      "special chars in appID",
-			appID:     "app&id=bad",
-			scope:     "calendar:calendar:readonly",
-			wantInURL: "clientID=app%26id%3Dbad",
-			denyInURL: "clientID=app&id=bad",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-				AppID: tt.appID, AppSecret: "test-secret", Brand: core.BrandFeishu,
-			})
-
-			exitErr := output.ErrAPI(output.LarkErrAppScopeNotEnabled, "scope not enabled", map[string]interface{}{
-				"permission_violations": []interface{}{
-					map[string]interface{}{"subject": tt.scope},
-				},
-			})
-
-			handleRootError(f, exitErr)
-
-			consoleURL := exitErr.Detail.ConsoleURL
-			if consoleURL == "" {
-				t.Fatal("expected console_url to be set")
-			}
-			if !strings.Contains(consoleURL, tt.wantInURL) {
-				t.Errorf("console_url missing expected escaped value\n  want substring: %s\n  got url:        %s", tt.wantInURL, consoleURL)
-			}
-			if tt.denyInURL != "" && strings.Contains(consoleURL, tt.denyInURL) {
-				t.Errorf("console_url contains unescaped dangerous value\n  deny substring: %s\n  got url:        %s", tt.denyInURL, consoleURL)
-			}
-		})
-	}
-}
-
-func TestEnrichMissingScopeError_ServiceMethodUsesLocalScopesWhenNoUAT(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-	f.ResolvedIdentity = core.AsUser
-
-	var target registry.CommandEntry
-	for _, entry := range registry.CollectCommandScopes([]string{"calendar"}, "user") {
-		if len(entry.Scopes) == 1 && entry.Scopes[0] == "calendar:calendar.event:create" {
-			target = entry
-			break
-		}
-	}
-	if target.Command == "" {
-		t.Fatal("failed to locate a calendar create command in local registry metadata")
-	}
-	parts := strings.Split(target.Command, " ")
-	if len(parts) != 2 {
-		t.Fatalf("expected resource/method command, got %q", target.Command)
-	}
-
-	root := &cobra.Command{Use: "lark-cli"}
-	serviceCmd := &cobra.Command{Use: "calendar"}
-	resourceCmd := &cobra.Command{Use: parts[0]}
-	methodCmd := &cobra.Command{Use: parts[1]}
-	root.AddCommand(serviceCmd)
-	serviceCmd.AddCommand(resourceCmd)
-	resourceCmd.AddCommand(methodCmd)
-	f.CurrentCommand = methodCmd
-
-	exitErr := output.Errorf(output.ExitAPI, "api_error", "API call failed: %s", &internalauth.NeedAuthorizationError{})
-	enrichMissingScopeError(f, exitErr)
-
-	if exitErr.Code != output.ExitAPI {
-		t.Fatalf("expected exit code %d, got %d", output.ExitAPI, exitErr.Code)
-	}
-	if exitErr.Detail == nil || exitErr.Detail.Type != "api_error" {
-		t.Fatalf("expected api_error detail, got %+v", exitErr.Detail)
-	}
-	if !strings.Contains(exitErr.Detail.Message, "need_user_authorization") {
-		t.Fatalf("expected original need_user_authorization message, got %q", exitErr.Detail.Message)
-	}
-	if !strings.Contains(exitErr.Detail.Hint, "current command requires scope(s): calendar:calendar.event:create") {
-		t.Fatalf("expected scope guidance in hint, got %q", exitErr.Detail.Hint)
-	}
-	if strings.Contains(exitErr.Detail.Hint, "lark-cli auth login --scope") {
-		t.Fatalf("expected hint without auth login command, got %q", exitErr.Detail.Hint)
-	}
-	if exitErr.Detail.Detail != nil {
-		t.Fatalf("expected detail to remain nil, got %#v", exitErr.Detail.Detail)
-	}
-}
-
-func TestEnrichMissingScopeError_ShortcutUsesDeclaredScopesWhenNoUAT(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-	f.ResolvedIdentity = core.AsUser
-
-	root := &cobra.Command{Use: "lark-cli"}
-	serviceCmd := &cobra.Command{Use: "docs"}
-	shortcutCmd := &cobra.Command{Use: "+create"}
-	root.AddCommand(serviceCmd)
-	serviceCmd.AddCommand(shortcutCmd)
-	f.CurrentCommand = shortcutCmd
-
-	exitErr := output.ErrNetwork("API call failed: %s", &internalauth.NeedAuthorizationError{})
-	enrichMissingScopeError(f, exitErr)
-
-	if exitErr.Code != output.ExitNetwork {
-		t.Fatalf("expected exit code %d, got %d", output.ExitNetwork, exitErr.Code)
-	}
-	if exitErr.Detail == nil || exitErr.Detail.Type != "network" {
-		t.Fatalf("expected network detail, got %+v", exitErr.Detail)
-	}
-	if !strings.Contains(exitErr.Detail.Message, "need_user_authorization") {
-		t.Fatalf("expected original need_user_authorization message, got %q", exitErr.Detail.Message)
-	}
-	if !strings.Contains(exitErr.Detail.Hint, "current command requires scope(s): docx:document:create") {
-		t.Fatalf("expected shortcut scope hint, got %q", exitErr.Detail.Hint)
-	}
-	if strings.Contains(exitErr.Detail.Hint, "lark-cli auth login --scope") {
-		t.Fatalf("expected hint without auth login command, got %q", exitErr.Detail.Hint)
-	}
-	if exitErr.Detail.Detail != nil {
-		t.Fatalf("expected detail to remain nil, got %#v", exitErr.Detail.Detail)
-	}
-}
-
-func TestEnrichMissingScopeError_ShortcutIncludesConditionalScopes(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-	f.ResolvedIdentity = core.AsUser
-
-	root := &cobra.Command{Use: "lark-cli"}
-	serviceCmd := &cobra.Command{Use: "drive"}
-	shortcutCmd := &cobra.Command{Use: "+status"}
-	root.AddCommand(serviceCmd)
-	serviceCmd.AddCommand(shortcutCmd)
-	f.CurrentCommand = shortcutCmd
-
-	exitErr := output.ErrNetwork("API call failed: %s", &internalauth.NeedAuthorizationError{})
-	enrichMissingScopeError(f, exitErr)
-
-	if exitErr.Detail == nil {
-		t.Fatal("expected error detail")
-	}
-	if !strings.Contains(exitErr.Detail.Hint, "current command requires scope(s): drive:drive.metadata:readonly, drive:file:download") {
-		t.Fatalf("expected conditional scope hint for drive +status, got %q", exitErr.Detail.Hint)
-	}
-}
-
-func TestEnrichMissingScopeError_AppendsExistingHint(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-	f.ResolvedIdentity = core.AsUser
-
-	root := &cobra.Command{Use: "lark-cli"}
-	serviceCmd := &cobra.Command{Use: "docs"}
-	shortcutCmd := &cobra.Command{Use: "+create"}
-	root.AddCommand(serviceCmd)
-	serviceCmd.AddCommand(shortcutCmd)
-	f.CurrentCommand = shortcutCmd
-
-	exitErr := output.ErrNetwork("API call failed: %s", &internalauth.NeedAuthorizationError{})
-	exitErr.Detail.Hint = "existing hint"
-	enrichMissingScopeError(f, exitErr)
-
-	want := "existing hint\ncurrent command requires scope(s): docx:document:create"
-	if exitErr.Detail.Hint != want {
-		t.Fatalf("expected appended hint %q, got %q", want, exitErr.Detail.Hint)
-	}
-}
-
 func TestRootLong_AgentSkillsLinkTargetsReadmeSection(t *testing.T) {
 	if !strings.Contains(rootLong, "https://github.com/larksuite/cli#agent-skills") {
 		t.Fatalf("root help should link to the README Agent Skills section, got:\n%s", rootLong)
@@ -396,3 +136,494 @@ func TestIsCompletionCommand(t *testing.T) {
 		})
 	}
 }
+
+// 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"])
+		}
+	})
+
+	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),
+		},
+		Cause: cause,
+	}
+}
+
+// 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 (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
+	}
+	f.n += len(p)
+	return len(p), nil
+}
+
+// TestHandleRootError_DeprecatedAliasMissingFlagStructured pins issue #4: a
+// backward-compat alias that fails on a cobra-level required flag (which
+// short-circuits before RunE) still routes through the structured envelope,
+// because OnInvoke records the deprecation in PreRunE and the legacy fallback
+// switches to WriteErrorEnvelope when a deprecation is pending — so the
+// migration notice is no longer dropped on the plain "Error:" line.
+func TestHandleRootError_DeprecatedAliasMissingFlagStructured(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	t.Cleanup(func() { deprecation.SetPending(nil) })
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	errOut := &bytes.Buffer{}
+	f.IOStreams.ErrOut = errOut
+
+	deprecation.SetPending(&deprecation.Notice{
+		Command: "+write", Replacement: "+cells-set", Skill: "lark-sheets",
+	})
+	// The bare error shape cobra's ValidateRequiredFlags produces: neither typed
+	// nor an *output.ExitError, so it reaches the legacy fallback.
+	handleRootError(f, fmt.Errorf(`required flag(s) %q not set`, "values"))
+
+	out := errOut.String()
+	if strings.HasPrefix(strings.TrimSpace(out), "Error:") {
+		t.Fatalf("deprecation pending: want a structured envelope, got a plain Error: line:\n%s", out)
+	}
+	if !strings.Contains(out, `"message"`) || !strings.Contains(out, "values") {
+		t.Errorf("expected a JSON error envelope carrying the failure message; got:\n%s", out)
+	}
+}
+
+// TestHandleRootError_NoDeprecationKeepsPlainError pins the other half: with no
+// deprecation pending, the legacy fallback stays a plain "Error:" line, so the
+// fix does not reshape every unrecognized cobra error.
+func TestHandleRootError_NoDeprecationKeepsPlainError(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	t.Cleanup(func() { deprecation.SetPending(nil) })
+	deprecation.SetPending(nil)
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	errOut := &bytes.Buffer{}
+	f.IOStreams.ErrOut = errOut
+
+	handleRootError(f, fmt.Errorf(`required flag(s) %q not set`, "values"))
+	if !strings.HasPrefix(errOut.String(), "Error:") {
+		t.Errorf("no deprecation pending: want a plain 'Error:' line, got:\n%s", errOut.String())
+	}
+}
+
+// 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))
+	}
+}
+
+// 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))
+	}
+	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)
+	}
+}
+
+// TestApplyNeedAuthorizationHint_ServiceMethodUsesLocalScopesWhenNoUAT pins
+// that a typed AuthenticationError carrying the need_user_authorization marker gets a
+// declared-scopes Hint appended when the current command is a registered
+// service method.
+func TestApplyNeedAuthorizationHint_ServiceMethodUsesLocalScopesWhenNoUAT(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+	f.ResolvedIdentity = core.AsUser
+
+	var target registry.CommandEntry
+	for _, entry := range registry.CollectCommandScopes([]string{"calendar"}, "user") {
+		if len(entry.Scopes) == 1 && entry.Scopes[0] == "calendar:calendar.event:create" {
+			target = entry
+			break
+		}
+	}
+	if target.Command == "" {
+		t.Fatal("failed to locate a calendar create command in local registry metadata")
+	}
+	parts := strings.Split(target.Command, " ")
+	if len(parts) != 2 {
+		t.Fatalf("expected resource/method command, got %q", target.Command)
+	}
+
+	root := &cobra.Command{Use: "lark-cli"}
+	serviceCmd := &cobra.Command{Use: "calendar"}
+	resourceCmd := &cobra.Command{Use: parts[0]}
+	methodCmd := &cobra.Command{Use: parts[1]}
+	root.AddCommand(serviceCmd)
+	serviceCmd.AddCommand(resourceCmd)
+	resourceCmd.AddCommand(methodCmd)
+	f.CurrentCommand = methodCmd
+
+	authErr := newAuthErrorWithNeedAuthMarker()
+	applyNeedAuthorizationHint(f, authErr)
+
+	if authErr.Category != errs.CategoryAuthentication {
+		t.Errorf("Category = %q, want authentication", authErr.Category)
+	}
+	if !strings.Contains(authErr.Message, "need_user_authorization") {
+		t.Errorf("Message should preserve need_user_authorization marker; got %q", authErr.Message)
+	}
+	if !strings.Contains(authErr.Hint, "current command requires scope(s): calendar:calendar.event:create") {
+		t.Errorf("expected declared-scope hint, got %q", authErr.Hint)
+	}
+}
+
+// TestApplyNeedAuthorizationHint_ShortcutUsesDeclaredScopesWhenNoUAT pins the
+// same hint behavior for mounted shortcut commands.
+func TestApplyNeedAuthorizationHint_ShortcutUsesDeclaredScopesWhenNoUAT(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+	f.ResolvedIdentity = core.AsUser
+
+	root := &cobra.Command{Use: "lark-cli"}
+	serviceCmd := &cobra.Command{Use: "docs"}
+	shortcutCmd := &cobra.Command{Use: "+create"}
+	root.AddCommand(serviceCmd)
+	serviceCmd.AddCommand(shortcutCmd)
+	f.CurrentCommand = shortcutCmd
+
+	authErr := newAuthErrorWithNeedAuthMarker()
+	applyNeedAuthorizationHint(f, authErr)
+
+	if !strings.Contains(authErr.Hint, "current command requires scope(s): docx:document:create") {
+		t.Errorf("expected shortcut scope hint, got %q", authErr.Hint)
+	}
+}
+
+// TestApplyNeedAuthorizationHint_ShortcutIncludesConditionalScopes pins that
+// conditional scopes declared on a shortcut surface in the hint.
+func TestApplyNeedAuthorizationHint_ShortcutIncludesConditionalScopes(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+	f.ResolvedIdentity = core.AsUser
+
+	root := &cobra.Command{Use: "lark-cli"}
+	serviceCmd := &cobra.Command{Use: "drive"}
+	shortcutCmd := &cobra.Command{Use: "+status"}
+	root.AddCommand(serviceCmd)
+	serviceCmd.AddCommand(shortcutCmd)
+	f.CurrentCommand = shortcutCmd
+
+	authErr := newAuthErrorWithNeedAuthMarker()
+	applyNeedAuthorizationHint(f, authErr)
+
+	if !strings.Contains(authErr.Hint, "current command requires scope(s): drive:drive.metadata:readonly, drive:file:download") {
+		t.Errorf("expected conditional scope hint for drive +status, got %q", authErr.Hint)
+	}
+}
+
+// TestApplyNeedAuthorizationHint_AppendsExistingHint pins that the
+// declared-scopes guidance is appended (separated by newline) when the typed
+// AuthenticationError already carries a Hint from elsewhere.
+func TestApplyNeedAuthorizationHint_AppendsExistingHint(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+	f.ResolvedIdentity = core.AsUser
+
+	root := &cobra.Command{Use: "lark-cli"}
+	serviceCmd := &cobra.Command{Use: "docs"}
+	shortcutCmd := &cobra.Command{Use: "+create"}
+	root.AddCommand(serviceCmd)
+	serviceCmd.AddCommand(shortcutCmd)
+	f.CurrentCommand = shortcutCmd
+
+	authErr := newAuthErrorWithNeedAuthMarker()
+	authErr.Hint = "existing hint"
+	applyNeedAuthorizationHint(f, authErr)
+
+	want := "existing hint\ncurrent command requires scope(s): docx:document:create"
+	if authErr.Hint != want {
+		t.Errorf("expected appended hint %q, got %q", want, authErr.Hint)
+	}
+}
+
+// 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"},
+		},
+	}
+
+	for _, tc := range cases {
+		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")
+			}
+		})
+	}
+}
+
+// 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)
+		}
+	}
+}

cmd/schema/schema.go

@@ -5,16 +5,17 @@ package schema
 
 import (
 	"context"
-	"fmt"
+	"errors"
 	"io"
-	"sort"
 	"strings"
 
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/apicatalog"
 	"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/internal/util"
+	"github.com/larksuite/cli/internal/schema"
 	"github.com/spf13/cobra"
 )
 
@@ -23,335 +24,10 @@ type SchemaOptions struct {
 	Factory *cmdutil.Factory
 	Ctx     context.Context
 
-	// Positional args
-	Path string
-
-	// Flags
-	Format string
-}
-
-func printServices(w io.Writer) {
-	services := registry.ListFromMetaProjects()
-	fmt.Fprintf(w, "%sAvailable services:%s\n\n", output.Bold, output.Reset)
-	for _, s := range services {
-		spec := registry.LoadFromMeta(s)
-		title := registry.GetStrFromMap(spec, "title")
-		if title == "" {
-			title = registry.GetStrFromMap(spec, "description")
-		}
-		fmt.Fprintf(w, "  %s%s%s  %s%s%s\n", output.Cyan, s, output.Reset, output.Dim, title, output.Reset)
-	}
-	fmt.Fprintf(w, "\n%sUsage: lark-cli schema <service>.<resource>.<method>%s\n", output.Dim, output.Reset)
-}
-
-func printResourceList(w io.Writer, spec map[string]interface{}, mode core.StrictMode) {
-	name := registry.GetStrFromMap(spec, "name")
-	version := registry.GetStrFromMap(spec, "version")
-	title := registry.GetStrFromMap(spec, "title")
-	if title == "" {
-		title = registry.GetStrFromMap(spec, "description")
-	}
-	servicePath := registry.GetStrFromMap(spec, "servicePath")
-
-	fmt.Fprintf(w, "%s%s%s (%s) — %s\n\n", output.Bold, name, output.Reset, version, title)
-	fmt.Fprintf(w, "%sBase path: %s%s\n\n", output.Dim, servicePath, output.Reset)
-
-	resources, _ := spec["resources"].(map[string]interface{})
-	for _, resName := range sortedKeys(resources) {
-		resMap, _ := resources[resName].(map[string]interface{})
-		methods, _ := resMap["methods"].(map[string]interface{})
-		methods = filterMethodsByStrictMode(methods, mode)
-		if len(methods) == 0 {
-			continue
-		}
-		fmt.Fprintf(w, "  %s%s%s\n", output.Cyan, resName, output.Reset)
-		for _, methodName := range sortedKeys(methods) {
-			m, _ := methods[methodName].(map[string]interface{})
-			httpMethod := registry.GetStrFromMap(m, "httpMethod")
-			desc := registry.GetStrFromMap(m, "description")
-			danger := ""
-			if d, _ := m["danger"].(bool); d {
-				danger = fmt.Sprintf(" %s[danger]%s", output.Red, output.Reset)
-			}
-			fmt.Fprintf(w, "    %-7s %s%s%s  %s%s%s%s\n", httpMethod, output.Bold, methodName, output.Reset, output.Dim, desc, output.Reset, danger)
-		}
-		fmt.Fprintln(w)
-	}
-	fmt.Fprintf(w, "%sUsage: lark-cli schema %s.<resource>.<method>%s\n", output.Dim, name, output.Reset)
-}
-
-// hasFileFields returns true if any requestBody field has type "file".
-func hasFileFields(method map[string]interface{}) (bool, []string) {
-	names := cmdutil.DetectFileFields(method)
-	return len(names) > 0, names
-}
-
-func printMethodDetail(w io.Writer, spec map[string]interface{}, resName, methodName string, method map[string]interface{}) {
-	servicePath := registry.GetStrFromMap(spec, "servicePath")
-	specName := registry.GetStrFromMap(spec, "name")
-	methodPath := registry.GetStrFromMap(method, "path")
-	fullPath := servicePath + "/" + methodPath
-	httpMethod := registry.GetStrFromMap(method, "httpMethod")
-	desc := registry.GetStrFromMap(method, "description")
-	isFileUpload, fileFieldNames := hasFileFields(method)
-
-	fmt.Fprintf(w, "%s%s.%s.%s%s\n\n", output.Bold, specName, resName, methodName, output.Reset)
-
-	httpColor := output.Yellow
-	if httpMethod == "GET" {
-		httpColor = output.Green
-	} else if httpMethod == "DELETE" {
-		httpColor = output.Red
-	}
-	fmt.Fprintf(w, "  %s%s%s %s\n", httpColor, httpMethod, output.Reset, fullPath)
-	if desc != "" {
-		fmt.Fprintf(w, "  %s\n", desc)
-	}
-	fmt.Fprintln(w)
-
-	// Parameters
-	params, _ := method["parameters"].(map[string]interface{})
-	if len(params) > 0 {
-		fmt.Fprintf(w, "%sParameters:%s\n\n", output.Bold, output.Reset)
-		fmt.Fprintf(w, "  %s--params%s  <json>  %soptional%s\n", output.Cyan, output.Reset, output.Dim, output.Reset)
-		for _, paramName := range sortedParamKeys(params) {
-			p, _ := params[paramName].(map[string]interface{})
-			pType := registry.GetStrFromMap(p, "type")
-			if pType == "" {
-				pType = "string"
-			}
-			location := registry.GetStrFromMap(p, "location")
-			required, _ := p["required"].(bool)
-			reqStr := fmt.Sprintf("%soptional%s", output.Dim, output.Reset)
-			if required {
-				reqStr = fmt.Sprintf("%srequired%s", output.Red, output.Reset)
-			}
-			locColor := output.Dim
-			if location == "path" {
-				locColor = output.Yellow
-			}
-			// Options (enum values)
-			optStr := formatOptions(p)
-			fmt.Fprintf(w, "      - %s%s%s (%s, %s%s%s, %s)%s\n", output.Cyan, paramName, output.Reset, pType, locColor, location, output.Reset, reqStr, optStr)
-			if pdesc := registry.GetStrFromMap(p, "description"); pdesc != "" {
-				pdesc = util.TruncateStrWithEllipsis(pdesc, 100)
-				fmt.Fprintf(w, "        %s%s%s\n", output.Dim, pdesc, output.Reset)
-			}
-			if ex := registry.GetStrFromMap(p, "example"); ex != "" {
-				fmt.Fprintf(w, "        %se.g. %s%s\n", output.Dim, ex, output.Reset)
-			}
-			if rangeStr := formatRange(p); rangeStr != "" {
-				fmt.Fprintf(w, "        %srange: %s%s\n", output.Dim, rangeStr, output.Reset)
-			}
-		}
-		fmt.Fprintln(w)
-	}
-
-	// --data for write methods
-	if httpMethod == "POST" || httpMethod == "PUT" || httpMethod == "PATCH" || httpMethod == "DELETE" {
-		if len(params) == 0 {
-			fmt.Fprintf(w, "%sParameters:%s\n\n", output.Bold, output.Reset)
-		}
-		fileUploadTag := ""
-		if isFileUpload {
-			fileUploadTag = fmt.Sprintf("  %s[file upload]%s", output.Yellow, output.Reset)
-		}
-		fmt.Fprintf(w, "  %s--data%s  <json>  %soptional%s%s\n", output.Cyan, output.Reset, output.Dim, output.Reset, fileUploadTag)
-		requestBody, _ := method["requestBody"].(map[string]interface{})
-		if len(requestBody) > 0 {
-			printNestedFields(w, requestBody, "      ", "")
-		}
-
-		if isFileUpload {
-			if len(fileFieldNames) == 1 {
-				fmt.Fprintf(w, "\n  %s--file%s  <[field=]path>  %sfile upload%s\n", output.Cyan, output.Reset, output.Dim, output.Reset)
-				fmt.Fprintf(w, "      Upload file as multipart/form-data. Default field: %q\n", fileFieldNames[0])
-			} else {
-				fmt.Fprintf(w, "\n  %s--file%s  <field=path>  %sfile upload%s\n", output.Cyan, output.Reset, output.Dim, output.Reset)
-				fmt.Fprintf(w, "      Upload file as multipart/form-data. Fields: %s\n", strings.Join(fileFieldNames, ", "))
-			}
-		}
-		fmt.Fprintln(w)
-	}
-
-	// Response
-	responseBody, _ := method["responseBody"].(map[string]interface{})
-	if len(responseBody) > 0 {
-		fmt.Fprintf(w, "%sResponse:%s\n\n", output.Bold, output.Reset)
-		printNestedFields(w, responseBody, "  ", "")
-		fmt.Fprintln(w)
-	}
-
-	// Identity
-	if tokens, ok := method["accessTokens"].([]interface{}); ok && len(tokens) > 0 {
-		var identities []string
-		for _, t := range tokens {
-			if s, ok := t.(string); ok {
-				switch s {
-				case "user":
-					identities = append(identities, "user")
-				case "tenant":
-					identities = append(identities, "bot")
-				}
-			}
-		}
-		if len(identities) > 0 {
-			fmt.Fprintf(w, "%sIdentity:%s %s\n", output.Bold, output.Reset, strings.Join(identities, ", "))
-		}
-	}
-
-	// Scopes (all)
-	if scopes, ok := method["scopes"].([]interface{}); ok && len(scopes) > 0 {
-		var scopeStrs []string
-		for _, s := range scopes {
-			if str, ok := s.(string); ok {
-				scopeStrs = append(scopeStrs, str)
-			}
-		}
-		fmt.Fprintf(w, "%sScopes:%s   %s\n", output.Bold, output.Reset, strings.Join(scopeStrs, ", "))
-	}
-
-	// CLI example
-	if isFileUpload && len(fileFieldNames) == 1 {
-		fmt.Fprintf(w, "%sCLI:%s      lark-cli %s %s %s --file <path>\n", output.Bold, output.Reset, specName, resName, methodName)
-	} else if isFileUpload {
-		fmt.Fprintf(w, "%sCLI:%s      lark-cli %s %s %s --file <field=path>\n", output.Bold, output.Reset, specName, resName, methodName)
-	} else {
-		fmt.Fprintf(w, "%sCLI:%s      lark-cli %s %s %s\n", output.Bold, output.Reset, specName, resName, methodName)
-	}
-
-	// Docs
-	if docUrl := registry.GetStrFromMap(method, "docUrl"); docUrl != "" {
-		fmt.Fprintf(w, "%sDocs:%s     %s\n", output.Bold, output.Reset, docUrl)
-	}
-}
-
-func printNestedFields(w io.Writer, fields map[string]interface{}, indent, prefix string) {
-	for _, fieldName := range sortedFieldKeys(fields) {
-		f, _ := fields[fieldName].(map[string]interface{})
-		fullName := fieldName
-		if prefix != "" {
-			fullName = prefix + "." + fieldName
-		}
-		fType := registry.GetStrFromMap(f, "type")
-		required, _ := f["required"].(bool)
-		reqStr := fmt.Sprintf("%soptional%s", output.Dim, output.Reset)
-		if required {
-			reqStr = fmt.Sprintf("%srequired%s", output.Red, output.Reset)
-		}
-		optStr := formatOptions(f)
-		fmt.Fprintf(w, "%s- %s%s%s (%s, %s)%s\n", indent, output.Cyan, fullName, output.Reset, fType, reqStr, optStr)
-		desc := registry.GetStrFromMap(f, "description")
-		if desc != "" {
-			desc = util.TruncateStrWithEllipsis(desc, 100)
-			fmt.Fprintf(w, "%s  %s%s%s\n", indent, output.Dim, desc, output.Reset)
-		}
-		if ex := registry.GetStrFromMap(f, "example"); ex != "" {
-			fmt.Fprintf(w, "%s  %se.g. %s%s\n", indent, output.Dim, ex, output.Reset)
-		}
-		if rangeStr := formatRange(f); rangeStr != "" {
-			fmt.Fprintf(w, "%s  %srange: %s%s\n", indent, output.Dim, rangeStr, output.Reset)
-		}
-		if props, ok := f["properties"].(map[string]interface{}); ok && len(props) > 0 {
-			printNestedFields(w, props, indent+"  ", fullName)
-		}
-	}
-}
-
-// formatOptions returns " — val1 | val2 | ..." if field has options, else "".
-func formatOptions(f map[string]interface{}) string {
-	opts, ok := f["options"].([]interface{})
-	if !ok || len(opts) == 0 {
-		return ""
-	}
-	var vals []string
-	for _, o := range opts {
-		if om, ok := o.(map[string]interface{}); ok {
-			if v := registry.GetStrFromMap(om, "value"); v != "" {
-				vals = append(vals, v)
-			}
-		}
-	}
-	if len(vals) == 0 {
-		return ""
-	}
-	return fmt.Sprintf(" %s— %s%s", output.Dim, strings.Join(vals, " | "), output.Reset)
-}
-
-// formatRange returns "min..max" if field has min/max, else "".
-func formatRange(f map[string]interface{}) string {
-	minVal := registry.GetStrFromMap(f, "min")
-	maxVal := registry.GetStrFromMap(f, "max")
-	if minVal == "" && maxVal == "" {
-		return ""
-	}
-	if minVal != "" && maxVal != "" {
-		return minVal + ".." + maxVal
-	}
-	if minVal != "" {
-		return ">=" + minVal
-	}
-	return "<=" + maxVal
-}
-
-// sortedKeys returns map keys in alphabetical order.
-func sortedKeys(m map[string]interface{}) []string {
-	keys := make([]string, 0, len(m))
-	for k := range m {
-		keys = append(keys, k)
-	}
-	sort.Strings(keys)
-	return keys
-}
-
-// sortedParamKeys returns parameter keys sorted: required first, then alphabetical.
-func sortedParamKeys(params map[string]interface{}) []string {
-	keys := make([]string, 0, len(params))
-	for k := range params {
-		keys = append(keys, k)
-	}
-	sort.Slice(keys, func(i, j int) bool {
-		pi, _ := params[keys[i]].(map[string]interface{})
-		pj, _ := params[keys[j]].(map[string]interface{})
-		ri, _ := pi["required"].(bool)
-		rj, _ := pj["required"].(bool)
-		if ri != rj {
-			return ri
-		}
-		return keys[i] < keys[j]
-	})
-	return keys
-}
-
-// sortedFieldKeys returns field keys sorted: required first, then alphabetical.
-func sortedFieldKeys(fields map[string]interface{}) []string {
-	keys := make([]string, 0, len(fields))
-	for k := range fields {
-		keys = append(keys, k)
-	}
-	sort.Slice(keys, func(i, j int) bool {
-		fi, _ := fields[keys[i]].(map[string]interface{})
-		fj, _ := fields[keys[j]].(map[string]interface{})
-		ri, _ := fi["required"].(bool)
-		rj, _ := fj["required"].(bool)
-		if ri != rj {
-			return ri
-		}
-		return keys[i] < keys[j]
-	})
-	return keys
-}
-
-func findResourceByPath(resources map[string]interface{}, parts []string) (map[string]interface{}, string, []string) {
-	for i := len(parts); i >= 1; i-- {
-		candidateName := strings.Join(parts[:i], ".")
-		if res, ok := resources[candidateName]; ok {
-			if resMap, ok := res.(map[string]interface{}); ok {
-				return resMap, candidateName, parts[i:]
-			}
-		}
-	}
-	return nil, "", nil
+	// Args are the positional path segments, in either the dotted single-arg
+	// form ("im.messages.reply") or the space-separated form ("im messages
+	// reply"); apicatalog.ParsePath normalizes both.
+	Args []string
 }
 
 // NewCmdSchema creates the schema command. If runF is non-nil it is called instead of schemaRun (test hook).
@@ -359,13 +35,11 @@ func NewCmdSchema(f *cmdutil.Factory, runF func(*SchemaOptions) error) *cobra.Co
 	opts := &SchemaOptions{Factory: f}
 
 	cmd := &cobra.Command{
-		Use:   "schema [path]",
+		Use:   "schema [path | service resource method]",
 		Short: "View API method parameters, types, and scopes",
-		Args:  cobra.MaximumNArgs(1),
+		Args:  cobra.MaximumNArgs(8),
 		RunE: func(cmd *cobra.Command, args []string) error {
-			if len(args) > 0 {
-				opts.Path = args[0]
-			}
+			opts.Args = append([]string(nil), args...)
 			opts.Ctx = cmd.Context()
 			if runF != nil {
 				return runF(opts)
@@ -375,248 +49,89 @@ func NewCmdSchema(f *cmdutil.Factory, runF func(*SchemaOptions) error) *cobra.Co
 	}
 	cmdutil.DisableAuthCheck(cmd)
 
+	// Tolerated for agent compatibility; ignored — schema only emits the JSON
+	// envelope, and its output is identity-independent (strict-mode filtering
+	// comes from ResolveStrictMode, never from --as).
+	cmd.Flags().String("format", "json", "")
+	cmd.Flags().Bool("json", true, "")
+	cmd.Flags().String("as", "", "")
+	_ = cmd.Flags().MarkHidden("format")
+	_ = cmd.Flags().MarkHidden("json")
+	_ = cmd.Flags().MarkHidden("as")
+
 	cmd.ValidArgsFunction = completeSchemaPath(f)
-	cmd.Flags().StringVar(&opts.Format, "format", "json", "output format: json (default) | pretty")
-	cmdutil.RegisterFlagCompletion(cmd, "format", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
-		return []string{"json", "pretty"}, cobra.ShellCompDirectiveNoFileComp
-	})
-	cmdutil.SetRisk(cmd, "read")
+	cmdutil.SetRisk(cmd, cmdutil.RiskRead)
 
 	return cmd
 }
 
-// completeSchemaPath provides tab-completion for the schema path argument.
-// It handles dotted resource names (e.g. app.table.fields) by iterating all
-// resources and classifying each as a prefix-match or fully-matched.
+// completeSchemaPath is a thin adapter over the embedded catalog's Complete.
+// It uses the embedded source so completion candidates match what `schema`
+// execution can resolve (both overlay-free).
 func completeSchemaPath(f *cmdutil.Factory) func(*cobra.Command, []string, string) ([]string, cobra.ShellCompDirective) {
 	return func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
-		if len(args) > 0 {
-			return nil, cobra.ShellCompDirectiveNoFileComp
-		}
-
-		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
-		}
-
-		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
-			}
-		}
+		completions, noSpace := registry.EmbeddedCatalog().Complete(args, toComplete, registry.FilterForStrictMode(mode))
 		directive := cobra.ShellCompDirectiveNoFileComp
-		if allTrailingDot {
+		if noSpace {
 			directive |= cobra.ShellCompDirectiveNoSpace
 		}
 		return completions, directive
 	}
 }
 
-func completeSchemaPathForSpec(serviceName string, resources map[string]interface{}, afterService string) []string {
-	var completions []string
-
-	for resName, resVal := range resources {
-		if strings.HasPrefix(resName, afterService) {
-			completions = append(completions, serviceName+"."+resName+".")
-			continue
-		}
-		if !strings.HasPrefix(afterService, resName+".") {
-			continue
-		}
-		methodPrefix := afterService[len(resName)+1:]
-		resMap, _ := resVal.(map[string]interface{})
-		if resMap == nil {
-			continue
-		}
-		methods, _ := resMap["methods"].(map[string]interface{})
-		for methodName := range methods {
-			if strings.HasPrefix(methodName, methodPrefix) {
-				completions = append(completions, serviceName+"."+resName+"."+methodName)
-			}
-		}
-	}
-
-	sort.Strings(completions)
-	return completions
-}
-
 func schemaRun(opts *SchemaOptions) error {
 	out := opts.Factory.IOStreams.Out
 	mode := opts.Factory.ResolveStrictMode(opts.Ctx)
+	return runSchema(out, apicatalog.ParsePath(opts.Args), mode)
+}
 
-	if opts.Path == "" {
-		printServices(out)
+// runSchema resolves the path through the embedded catalog and renders the
+// matching envelope(s). The catalog owns navigation (Resolve + MethodRefs) and
+// schema owns rendering (Envelope/Envelopes); this adapter only chooses the
+// output shape — a single resolved method renders as one envelope object,
+// anything broader as an array — and maps resolve failures to hints.
+func runSchema(out io.Writer, parts []string, mode core.StrictMode) error {
+	catalog := registry.EmbeddedCatalog()
+	target, err := catalog.Resolve(parts)
+	if err != nil {
+		return resolveError(err)
+	}
+	refs := catalog.MethodRefs(target, registry.FilterForStrictMode(mode))
+	if target.Kind == apicatalog.TargetMethod {
+		if len(refs) == 0 {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument,
+				"Method %s not available in current identity mode", target.Method.SchemaPath()).
+				WithHint("strict mode hides methods the active account identity cannot call; it is shown for an identity (user or bot) that has the required access token")
+		}
+		output.PrintJson(out, schema.EnvelopeOf(refs[0]))
 		return nil
 	}
-
-	parts := strings.Split(opts.Path, ".")
-
-	serviceName := parts[0]
-	spec := registry.LoadFromMeta(serviceName)
-	if spec == nil {
-		return output.ErrWithHint(output.ExitValidation, "validation",
-			fmt.Sprintf("Unknown service: %s", serviceName),
-			fmt.Sprintf("Available: %s", strings.Join(registry.ListFromMetaProjects(), ", ")))
-	}
-
-	if len(parts) == 1 {
-		if opts.Format == "pretty" {
-			printResourceList(out, spec, mode)
-		} 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 resNames []string
-		for k := range resources {
-			resNames = append(resNames, k)
-		}
-		return output.ErrWithHint(output.ExitValidation, "validation",
-			fmt.Sprintf("Unknown resource: %s.%s", serviceName, strings.Join(parts[1:], ".")),
-			fmt.Sprintf("Available: %s", strings.Join(resNames, ", ")))
-	}
-
-	if len(remaining) == 0 {
-		if opts.Format == "pretty" {
-			fmt.Fprintf(out, "%s%s.%s%s\n\n", output.Bold, serviceName, resName, output.Reset)
-			methods, _ := resource["methods"].(map[string]interface{})
-			methods = filterMethodsByStrictMode(methods, mode)
-			for _, mName := range sortedKeys(methods) {
-				m, _ := methods[mName].(map[string]interface{})
-				httpMethod := registry.GetStrFromMap(m, "httpMethod")
-				desc := registry.GetStrFromMap(m, "description")
-				fmt.Fprintf(out, "  %-7s %s%s%s  %s%s%s\n", httpMethod, output.Bold, mName, output.Reset, output.Dim, desc, output.Reset)
-			}
-			fmt.Fprintf(out, "\n%sUsage: lark-cli schema %s.%s.<method>%s\n", output.Dim, serviceName, resName, output.Reset)
-		} else {
-			// For JSON output, filter methods in a copy to avoid mutating the registry.
-			if mode.IsActive() {
-				filtered := make(map[string]interface{})
-				for k, v := range resource {
-					filtered[k] = v
-				}
-				if methods, ok := resource["methods"].(map[string]interface{}); ok {
-					filtered["methods"] = filterMethodsByStrictMode(methods, mode)
-				}
-				output.PrintJson(out, filtered)
-			} else {
-				output.PrintJson(out, resource)
-			}
-		}
-		return nil
-	}
-
-	methodName := remaining[0]
-	methods, _ := resource["methods"].(map[string]interface{})
-	methods = filterMethodsByStrictMode(methods, mode)
-	method, ok := methods[methodName].(map[string]interface{})
-	if !ok {
-		var mNames []string
-		for k := range methods {
-			mNames = append(mNames, k)
-		}
-		return output.ErrWithHint(output.ExitValidation, "validation",
-			fmt.Sprintf("Unknown method: %s.%s.%s", serviceName, resName, methodName),
-			fmt.Sprintf("Available: %s", strings.Join(mNames, ", ")))
-	}
-
-	if opts.Format == "pretty" {
-		printMethodDetail(out, spec, resName, methodName, method)
-	} else {
-		output.PrintJson(out, method)
-	}
+	output.PrintJson(out, schema.Envelopes(refs))
 	return nil
 }
 
-// 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{} {
-	if !mode.IsActive() {
-		return spec
+// resolveError maps a catalog *ResolveError to a typed *errs.ValidationError
+// (CategoryValidation drives the exit code; Hint promotes to the envelope),
+// preserving the historical message + hint text.
+func resolveError(err error) error {
+	var re *apicatalog.ResolveError
+	if !errors.As(err, &re) {
+		return err
 	}
-	result := make(map[string]interface{}, len(spec))
-	for k, v := range spec {
-		result[k] = v
+	switch re.Kind {
+	case apicatalog.ErrService:
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "Unknown service: %s", re.Subject).
+			WithHint("Available: %s", strings.Join(re.Candidates, ", "))
+	case apicatalog.ErrResource:
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "Unknown resource: %s", re.Subject).
+			WithHint("Available: %s", strings.Join(re.Candidates, ", "))
+	case apicatalog.ErrMethod:
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "Unknown method: %s", re.Subject).
+			WithHint("Available: %s", strings.Join(re.Candidates, ", "))
+	case apicatalog.ErrPath:
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "Unknown path: %s", re.Subject).
+			WithHint("Method %q exists but the trailing segments %q do not resolve", re.Method, re.Trailing)
 	}
-	resources, _ := spec["resources"].(map[string]interface{})
-	if resources == nil {
-		return result
-	}
-	filteredRes := make(map[string]interface{}, len(resources))
-	for resName, resVal := range resources {
-		resMap, ok := resVal.(map[string]interface{})
-		if !ok {
-			continue
-		}
-		methods, _ := resMap["methods"].(map[string]interface{})
-		filtered := filterMethodsByStrictMode(methods, mode)
-		if len(filtered) == 0 {
-			continue
-		}
-		resCopy := make(map[string]interface{}, len(resMap))
-		for k, v := range resMap {
-			resCopy[k] = v
-		}
-		resCopy["methods"] = filtered
-		filteredRes[resName] = resCopy
-	}
-	result["resources"] = filteredRes
-	return result
-}
-
-// filterMethodsByStrictMode removes methods incompatible with the active strict mode.
-// Returns the original map unmodified when strict mode is off.
-func filterMethodsByStrictMode(methods map[string]interface{}, mode core.StrictMode) map[string]interface{} {
-	if !mode.IsActive() || methods == nil {
-		return methods
-	}
-	token := registry.IdentityToAccessToken(string(mode.ForcedIdentity()))
-	filtered := make(map[string]interface{}, len(methods))
-	for name, val := range methods {
-		m, ok := val.(map[string]interface{})
-		if !ok {
-			continue
-		}
-		tokens, _ := m["accessTokens"].([]interface{})
-		if tokens == nil {
-			filtered[name] = val
-			continue
-		}
-		for _, t := range tokens {
-			if ts, ok := t.(string); ok && ts == token {
-				filtered[name] = val
-				break
-			}
-		}
-	}
-	return filtered
+	return err
 }

cmd/schema/schema_test.go

@@ -4,7 +4,7 @@
 package schema
 
 import (
-	"bytes"
+	"encoding/json"
 	"strings"
 	"testing"
 
@@ -20,30 +20,178 @@ func TestSchemaCmd_FlagParsing(t *testing.T) {
 		gotOpts = opts
 		return nil
 	})
-	cmd.SetArgs([]string{"calendar.events.list", "--format", "pretty"})
+	cmd.SetArgs([]string{"calendar.events.list"})
 	err := cmd.Execute()
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	if gotOpts.Path != "calendar.events.list" {
-		t.Errorf("expected path calendar.events.list, got %s", gotOpts.Path)
-	}
-	if gotOpts.Format != "pretty" {
-		t.Errorf("expected Format=pretty, got %s", gotOpts.Format)
+	if len(gotOpts.Args) != 1 || gotOpts.Args[0] != "calendar.events.list" {
+		t.Errorf("expected args [calendar.events.list], got %v", gotOpts.Args)
 	}
 }
 
-func TestSchemaCmd_NoArgs(t *testing.T) {
+func TestSchemaCmd_OutputFlagsAcceptedForCompat(t *testing.T) {
+	// Agents are habituated to --format/--json/--as from api/service commands.
+	// schema must accept them without erroring and always emit the JSON envelope —
+	// its output is structured JSON and identity-independent, so the values have
+	// no effect.
+	argSets := [][]string{
+		{"--format", "json"},
+		{"--format", "pretty"},
+		{"--format", "table"}, // no table rendering for a nested schema -> JSON
+		{"--format", "csv"},
+		{"--json"},
+		{"--json", "--format", "ndjson"},
+		{"--as", "user"},
+		{"--as", "bot"},
+		{"--as", "user", "--json"},
+	}
+	for _, extra := range argSets {
+		f, stdout, _, _ := cmdutil.TestFactory(t, nil)
+		cmd := NewCmdSchema(f, nil)
+		cmd.SetArgs(append([]string{"im.images.create"}, extra...))
+		if err := cmd.Execute(); err != nil {
+			t.Fatalf("args %v should be accepted, got error: %v", extra, err)
+		}
+		var env map[string]interface{}
+		if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+			t.Fatalf("args %v: output is not a JSON envelope: %v\n%s", extra, err, stdout.String())
+		}
+		if env["name"] != "im images create" {
+			t.Errorf("args %v: expected the im images create envelope, got name=%v", extra, env["name"])
+		}
+	}
+}
+
+func TestSchemaCmd_NoArgs_JSON_IsArray(t *testing.T) {
 	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
 
 	cmd := NewCmdSchema(f, nil)
 	cmd.SetArgs([]string{})
-	err := cmd.Execute()
-	if err != nil {
+	if err := cmd.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	if !strings.Contains(stdout.String(), "Available services") {
-		t.Error("expected service list output")
+	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"})
+	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")
 	}
 }
 
@@ -63,168 +211,6 @@ func TestSchemaCmd_UnknownService(t *testing.T) {
 	}
 }
 
-func TestPrintMethodDetail_FileUpload(t *testing.T) {
-	spec := map[string]interface{}{
-		"name":        "im",
-		"servicePath": "/open-apis/im/v1",
-	}
-	method := map[string]interface{}{
-		"path":        "images",
-		"httpMethod":  "POST",
-		"description": "Upload an image",
-		"requestBody": map[string]interface{}{
-			"image_type": map[string]interface{}{
-				"type":     "string",
-				"required": true,
-			},
-			"image": map[string]interface{}{
-				"type":     "file",
-				"required": true,
-			},
-		},
-		"accessTokens": []interface{}{"user", "tenant"},
-	}
-
-	var buf bytes.Buffer
-	printMethodDetail(&buf, spec, "images", "create", method)
-	out := buf.String()
-
-	if !strings.Contains(out, "file upload") {
-		t.Errorf("expected 'file upload' marker in output, got:\n%s", out)
-	}
-	if !strings.Contains(out, "--file") {
-		t.Errorf("expected '--file' in output, got:\n%s", out)
-	}
-	if !strings.Contains(out, `"image"`) {
-		t.Errorf("expected default field name 'image' in output, got:\n%s", out)
-	}
-	if !strings.Contains(out, "--file <path>") {
-		t.Errorf("expected CLI example with --file <path>, got:\n%s", out)
-	}
-}
-
-func TestPrintMethodDetail_NoFileUpload(t *testing.T) {
-	spec := map[string]interface{}{
-		"name":        "calendar",
-		"servicePath": "/open-apis/calendar/v4",
-	}
-	method := map[string]interface{}{
-		"path":        "events",
-		"httpMethod":  "POST",
-		"description": "Create an event",
-		"requestBody": map[string]interface{}{
-			"summary": map[string]interface{}{
-				"type":     "string",
-				"required": true,
-			},
-		},
-	}
-
-	var buf bytes.Buffer
-	printMethodDetail(&buf, spec, "events", "create", method)
-	out := buf.String()
-
-	if strings.Contains(out, "file upload") {
-		t.Errorf("did not expect 'file upload' marker for non-file method, got:\n%s", out)
-	}
-	if strings.Contains(out, "--file") {
-		t.Errorf("did not expect '--file' for non-file method, got:\n%s", out)
-	}
-}
-
-func TestHasFileFields(t *testing.T) {
-	tests := []struct {
-		name       string
-		method     map[string]interface{}
-		wantBool   bool
-		wantFields []string
-	}{
-		{
-			name: "has file field",
-			method: map[string]interface{}{
-				"requestBody": map[string]interface{}{
-					"image": map[string]interface{}{"type": "file"},
-					"name":  map[string]interface{}{"type": "string"},
-				},
-			},
-			wantBool:   true,
-			wantFields: []string{"image"},
-		},
-		{
-			name: "no file field",
-			method: map[string]interface{}{
-				"requestBody": map[string]interface{}{
-					"name": map[string]interface{}{"type": "string"},
-				},
-			},
-			wantBool:   false,
-			wantFields: nil,
-		},
-		{
-			name:       "no requestBody",
-			method:     map[string]interface{}{},
-			wantBool:   false,
-			wantFields: nil,
-		},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got, names := hasFileFields(tt.method)
-			if got != tt.wantBool {
-				t.Errorf("hasFileFields() = %v, want %v", got, tt.wantBool)
-			}
-			if tt.wantFields == nil && names != nil {
-				t.Errorf("expected nil names, got %v", names)
-			}
-			if tt.wantFields != nil && len(names) != len(tt.wantFields) {
-				t.Errorf("expected %d field names, got %d", len(tt.wantFields), len(names))
-			}
-		})
-	}
-}
-
-func TestCompleteSchemaPathForSpec(t *testing.T) {
-	resources := map[string]interface{}{
-		"records": map[string]interface{}{
-			"methods": map[string]interface{}{
-				"create": map[string]interface{}{},
-				"list":   map[string]interface{}{},
-			},
-		},
-		"record_permissions": map[string]interface{}{
-			"methods": map[string]interface{}{
-				"get": map[string]interface{}{},
-			},
-		},
-	}
-
-	got := completeSchemaPathForSpec("base", resources, "records.cr")
-	if len(got) != 1 || got[0] != "base.records.create" {
-		t.Fatalf("completions = %v, want [base.records.create]", got)
-	}
-
-	got = completeSchemaPathForSpec("base", resources, "record")
-	if len(got) != 2 || got[0] != "base.record_permissions." || got[1] != "base.records." {
-		t.Fatalf("resource completions = %v", got)
-	}
-}
-
-func TestFilterSpecByStrictMode_RemovesIncompatibleMethodsFromCompletionSource(t *testing.T) {
-	spec := map[string]interface{}{
-		"resources": map[string]interface{}{
-			"records": map[string]interface{}{
-				"methods": map[string]interface{}{
-					"list":   map[string]interface{}{"accessTokens": []interface{}{"tenant"}},
-					"create": map[string]interface{}{"accessTokens": []interface{}{"user"}},
-				},
-			},
-		},
-	}
-
-	filtered := filterSpecByStrictMode(spec, core.StrictModeBot)
-	resources, _ := filtered["resources"].(map[string]interface{})
-	got := completeSchemaPathForSpec("base", resources, "records.")
-	if len(got) != 1 || got[0] != "base.records.list" {
-		t.Fatalf("filtered completions = %v, want [base.records.list]", got)
-	}
-}
+// Completion candidate generation (dotted + space forms, strict-mode filtering,
+// dotted-resource handling) now lives in internal/apicatalog and is covered by
+// apicatalog's TestComplete. cmd/schema only adapts catalog.Complete to cobra.

cmd/service/affordance.go

@@ -0,0 +1,80 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package service
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/larksuite/cli/internal/meta"
+)
+
+// methodLong composes a method command's long help in one place: the
+// description, the affordance guidance block (when the method has one), the
+// pointer to the full schema, and the params-only addendum (params whose flag
+// name is taken — paramFlagBinder.paramsOnlyHelp, "" when none). Affordance
+// sits near the top so an agent sees when-to-use and few-shot examples before
+// the flag list.
+func methodLong(description, affordance, schemaPath, paramsOnly string) string {
+	var b strings.Builder
+	b.WriteString(description)
+	if affordance != "" {
+		b.WriteString("\n\n")
+		b.WriteString(affordance)
+	}
+	fmt.Fprintf(&b, "\n\nView parameter definitions before calling:\n  lark-cli schema %s", schemaPath)
+	b.WriteString(paramsOnly)
+	return b.String()
+}
+
+// renderAffordance renders a method's affordance as a help block — when to use,
+// prerequisites, and (most importantly for agents) few-shot Examples — or "" when
+// the method carries no affordance. It reads the single typed model
+// (meta.Method.ParsedAffordance) so the help and the envelope agree on shape.
+func renderAffordance(m meta.Method) string {
+	a, ok := m.ParsedAffordance()
+	if !ok {
+		return ""
+	}
+
+	var b strings.Builder
+	bullets := func(title string, items []string) {
+		var nonEmpty []string
+		for _, it := range items {
+			if strings.TrimSpace(it) != "" {
+				nonEmpty = append(nonEmpty, it)
+			}
+		}
+		if len(nonEmpty) == 0 {
+			return
+		}
+		fmt.Fprintf(&b, "%s:\n", title)
+		for _, it := range nonEmpty {
+			fmt.Fprintf(&b, "  • %s\n", it)
+		}
+	}
+
+	bullets("When to use", a.UseWhen)
+	bullets("Avoid when", a.DoNotUseWhen)
+	bullets("Prerequisites", a.Prerequisites)
+	if len(a.Examples) > 0 {
+		var lines []string
+		for _, ex := range a.Examples {
+			if ex.Command == "" {
+				continue
+			}
+			if ex.Description != "" {
+				lines = append(lines, fmt.Sprintf("  • %s\n      %s", ex.Description, ex.Command))
+			} else {
+				lines = append(lines, fmt.Sprintf("  • %s", ex.Command))
+			}
+		}
+		if len(lines) > 0 {
+			fmt.Fprintf(&b, "Examples:\n%s\n", strings.Join(lines, "\n"))
+		}
+	}
+	bullets("Related", a.Related)
+
+	return strings.TrimRight(b.String(), "\n")
+}

cmd/service/affordance_test.go

@@ -0,0 +1,72 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package service
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/meta"
+)
+
+func TestRenderAffordance(t *testing.T) {
+	raw := json.RawMessage(`{
+		"use_when": ["发送文本消息"],
+		"do_not_use_when": ["群已解散"],
+		"prerequisites": ["已获取 chat_id"],
+		"examples": [
+			{"description":"发一条文本","command":"lark-cli im messages create --params '{...}'"},
+			{"command":"lark-cli im messages list"},
+			{"description":"no command, skipped","command":""}
+		],
+		"related": ["im.messages.list"]
+	}`)
+	out := renderAffordance(meta.Method{Affordance: raw})
+	for _, want := range []string{
+		"When to use:", "发送文本消息",
+		"Avoid when:", "群已解散",
+		"Prerequisites:", "已获取 chat_id",
+		"Examples:", "发一条文本", "lark-cli im messages create --params '{...}'",
+		"lark-cli im messages list", // example with no description -> bare command line
+		"Related:", "im.messages.list",
+	} {
+		if !strings.Contains(out, want) {
+			t.Errorf("renderAffordance missing %q in:\n%s", want, out)
+		}
+	}
+	if strings.Contains(out, "no command, skipped") {
+		t.Errorf("example with empty command should be skipped:\n%s", out)
+	}
+
+	// Absent or empty affordance renders nothing (so methods without an overlay
+	// add nothing to their help).
+	if renderAffordance(meta.Method{}) != "" || renderAffordance(meta.Method{Affordance: json.RawMessage(`{}`)}) != "" {
+		t.Error("empty affordance should render nothing")
+	}
+}
+
+func TestServiceMethod_AffordanceInLong(t *testing.T) {
+	withAff := map[string]interface{}{
+		"path": "messages", "httpMethod": "POST", "description": "发送消息",
+		"affordance": map[string]interface{}{
+			"examples": []interface{}{
+				map[string]interface{}{"description": "发文本", "command": "lark-cli im messages create ..."},
+			},
+		},
+	}
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(withAff), "create", "messages", nil)
+	if !strings.Contains(cmd.Long, "Examples:") || !strings.Contains(cmd.Long, "lark-cli im messages create ...") {
+		t.Errorf("affordance examples not in command Long:\n%s", cmd.Long)
+	}
+
+	// A method with no affordance adds no guidance block.
+	plain := map[string]interface{}{"path": "x", "httpMethod": "GET", "description": "d"}
+	cmd2 := NewCmdServiceMethod(f, imSpec(), meta.FromMap(plain), "list", "x", nil)
+	if strings.Contains(cmd2.Long, "Examples:") {
+		t.Errorf("no-affordance method should have no Examples in Long:\n%s", cmd2.Long)
+	}
+}

cmd/service/flaggroups.go

@@ -0,0 +1,211 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package service
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+// Flag annotations the grouped service-method help renderer reads.
+const (
+	flagGroupAnnotation = "lark_flag_group" // display group key
+	flagSubAnnotation   = "lark_flag_sub"   // "required" | "optional" within API Parameters
+	flagNoteAnnotation  = "lark_flag_note"  // extra lines shown indented under a flag
+
+	groupParams    = "params"    // typed path/query flags
+	groupBody      = "body"      // --data, --file
+	groupRaw       = "raw"       // --params
+	groupExecution = "execution" // --as/--dry-run/--page-*/--yes
+	groupOutput    = "output"    // --output/--format/--jq
+
+	subRequired = "required"
+	subOptional = "optional"
+)
+
+// serviceFlagGroupOrder is the display order + titles of the flag groups. API
+// Parameters carries only typed path/query flags; raw --params, request body and
+// execution/output controls each get their own group so an agent can tell the
+// distinct input kinds apart.
+var serviceFlagGroupOrder = []struct{ key, title string }{
+	{groupParams, "API Parameters"},
+	{groupBody, "Request Body"},
+	{groupRaw, "Raw Parameter Input"},
+	{groupExecution, "Execution"},
+	{groupOutput, "Output"},
+}
+
+// applyGroupedUsage installs the grouped usage renderer on a service method
+// cmd: local flags via the grouped renderer instead of cobra's flat Flags:
+// list; global (inherited) flags and the Risk/Tips sections appended by the
+// root help func are unaffected. Rendered by hand rather than via
+// cmd.SetUsageTemplate: cobra lazy-links text/template on the first
+// SetUsageTemplate call, whose executor reaches reflect.Value.MethodByName —
+// that disables the linker's method-level dead-code elimination and costs
+// ~19 MB of binary size.
+func applyGroupedUsage(cmd *cobra.Command) {
+	cmd.SetUsageFunc(func(c *cobra.Command) error {
+		w := c.OutOrStderr()
+		fmt.Fprintf(w, "Usage:\n  %s\n", c.UseLine())
+		if c.HasAvailableLocalFlags() {
+			fmt.Fprintf(w, "\n%s\n", renderServiceFlagGroups(c))
+		}
+		if c.HasAvailableInheritedFlags() {
+			fmt.Fprintf(w, "\nGlobal Flags:\n%s\n", strings.TrimRight(c.InheritedFlags().FlagUsages(), " \t\n"))
+		}
+		return nil
+	})
+}
+
+func annotate(f *pflag.Flag, key string, vals []string) {
+	if f.Annotations == nil {
+		f.Annotations = map[string][]string{}
+	}
+	f.Annotations[key] = vals
+}
+
+// tagFlagGroup records a flag's display group (no-op if the flag is absent).
+func tagFlagGroup(fs *pflag.FlagSet, name, group string) {
+	if f := fs.Lookup(name); f != nil {
+		annotate(f, flagGroupAnnotation, []string{group})
+	}
+}
+
+func annotationOf(f *pflag.Flag, key string) []string {
+	if f.Annotations != nil {
+		return f.Annotations[key]
+	}
+	return nil
+}
+
+func flagGroupOf(f *pflag.Flag) string {
+	if v := annotationOf(f, flagGroupAnnotation); len(v) > 0 {
+		return v[0]
+	}
+	return ""
+}
+
+func flagSubOf(f *pflag.Flag) string {
+	if v := annotationOf(f, flagSubAnnotation); len(v) > 0 {
+		return v[0]
+	}
+	return ""
+}
+
+// renderServiceFlagGroups renders the command's local flags into ordered,
+// titled groups; the API Parameters group is further split into Required /
+// Optional. It is the body of the usage func applyGroupedUsage installs.
+func renderServiceFlagGroups(cmd *cobra.Command) string {
+	var b strings.Builder
+	seen := map[*pflag.Flag]bool{}
+	for _, g := range serviceFlagGroupOrder {
+		flags := groupFlags(cmd, g.key, seen)
+		if len(flags) == 0 {
+			continue
+		}
+		fmt.Fprintf(&b, "%s:\n", g.title)
+		if g.key == groupParams {
+			writeSection(&b, "  Required:", subFlags(flags, subRequired))
+			writeSection(&b, "  Optional:", subFlags(flags, subOptional))
+		} else {
+			writeSection(&b, "", flags)
+		}
+		fmt.Fprintln(&b)
+	}
+	// Anything untagged (e.g. -h/--help) goes last under "Other".
+	var other []*pflag.Flag
+	cmd.LocalFlags().VisitAll(func(f *pflag.Flag) {
+		if f.Hidden || seen[f] {
+			return
+		}
+		other = append(other, f)
+	})
+	if len(other) > 0 {
+		fmt.Fprintln(&b, "Other:")
+		writeSection(&b, "", other)
+	}
+	return strings.TrimRight(b.String(), "\n")
+}
+
+// groupFlags returns the visible local flags tagged with group key, marking them
+// seen so the trailing "Other" bucket only catches genuinely untagged flags.
+func groupFlags(cmd *cobra.Command, key string, seen map[*pflag.Flag]bool) []*pflag.Flag {
+	var flags []*pflag.Flag
+	cmd.LocalFlags().VisitAll(func(f *pflag.Flag) {
+		if f.Hidden || flagGroupOf(f) != key {
+			return
+		}
+		flags = append(flags, f)
+		seen[f] = true
+	})
+	return flags
+}
+
+func subFlags(flags []*pflag.Flag, sub string) []*pflag.Flag {
+	var out []*pflag.Flag
+	for _, f := range flags {
+		s := flagSubOf(f)
+		// Untagged subgroup defaults to Optional so nothing is dropped.
+		if s == sub || (s == "" && sub == subOptional) {
+			out = append(out, f)
+		}
+	}
+	return out
+}
+
+// writeSection prints an optional (sub)header and the flags, aligned in a
+// column, each flag row followed by its note lines indented under the usage.
+func writeSection(b *strings.Builder, header string, flags []*pflag.Flag) {
+	if len(flags) == 0 {
+		return
+	}
+	if header != "" {
+		fmt.Fprintf(b, "%s\n", header)
+	}
+	specs := make([]string, len(flags))
+	maxSpec := 0
+	for i, f := range flags {
+		specs[i] = flagSpec(f)
+		if len(specs[i]) > maxSpec {
+			maxSpec = len(specs[i])
+		}
+	}
+	for i, f := range flags {
+		_, usage := pflag.UnquoteUsage(f)
+		if showsDefault(f) {
+			usage += fmt.Sprintf(" (default %s)", f.DefValue)
+		}
+		fmt.Fprintf(b, "%-*s   %s\n", maxSpec, specs[i], strings.TrimSpace(usage))
+		for _, note := range annotationOf(f, flagNoteAnnotation) {
+			fmt.Fprintf(b, "%*s%s\n", maxSpec+3+4, "", note)
+		}
+	}
+}
+
+// flagSpec is pflag's "      --name type" / "  -x, --name type" left column.
+func flagSpec(f *pflag.Flag) string {
+	typeName, _ := pflag.UnquoteUsage(f)
+	spec := "      --" + f.Name
+	if f.Shorthand != "" && f.ShorthandDeprecated == "" {
+		spec = "  -" + f.Shorthand + ", --" + f.Name
+	}
+	if typeName != "" {
+		spec += " " + typeName
+	}
+	return spec
+}
+
+// showsDefault mirrors pflag's "non-zero default" rule for the flag types these
+// commands use, so the grouped rendering shows the same "(default x)" hints as
+// cobra's flat list.
+func showsDefault(f *pflag.Flag) bool {
+	switch f.DefValue {
+	case "", "0", "false", "[]":
+		return false
+	}
+	return true
+}

cmd/service/flaggroups_test.go

@@ -0,0 +1,115 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package service
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/meta"
+)
+
+func TestServiceFlagGroups_AgentContract(t *testing.T) {
+	method := map[string]interface{}{
+		"path":       "chats/:chat_id/members",
+		"httpMethod": "POST",
+		"parameters": map[string]interface{}{
+			"chat_id": map[string]interface{}{"type": "string", "location": "path", "required": true},
+			"member_id_type": map[string]interface{}{
+				"type": "string", "location": "query",
+				"options": []interface{}{
+					map[string]interface{}{"value": "open_id", "description": "以 open_id 标识用户"},
+					map[string]interface{}{"value": "user_id", "description": "以 user_id 标识用户"},
+				},
+			},
+		},
+		// Documented body field -> --data belongs under Request Body.
+		"requestBody": map[string]interface{}{
+			"id_list": map[string]interface{}{"type": "list", "required": true},
+		},
+	}
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(method), "create", "chat.members", nil)
+	out := renderServiceFlagGroups(cmd)
+
+	idx := func(s string) int { return strings.Index(out, s) }
+
+	// Section order: API Parameters → Request Body → Raw Parameter Input → Execution → Output.
+	iParams, iBody, iRaw, iExec, iOut := idx("API Parameters:"), idx("Request Body:"), idx("Raw Parameter Input:"), idx("Execution:"), idx("Output:")
+	for name, i := range map[string]int{"API Parameters": iParams, "Request Body": iBody, "Raw Parameter Input": iRaw, "Execution": iExec, "Output": iOut} {
+		if i < 0 {
+			t.Fatalf("missing section %q in:\n%s", name, out)
+		}
+	}
+	if !(iParams < iBody && iBody < iRaw && iRaw < iExec && iExec < iOut) {
+		t.Errorf("section order wrong:\n%s", out)
+	}
+
+	// Required/Optional subsections under API Parameters.
+	if i := idx("  Required:"); i < iParams || i > iBody {
+		t.Errorf("Required subsection misplaced:\n%s", out)
+	}
+	if i := idx("  Optional:"); i < iParams || i > iBody {
+		t.Errorf("Optional subsection misplaced:\n%s", out)
+	}
+
+	// Typed flags are API Parameters; required path flag under Required, enum
+	// flag under Optional with an inline "enum: ..." (not multi-line meanings).
+	if i := idx("--chat-id"); i < iParams || i > iBody {
+		t.Errorf("--chat-id not under API Parameters:\n%s", out)
+	}
+	if !strings.Contains(out, "chat_id, required") {
+		t.Errorf("typed flag help format wrong:\n%s", out)
+	}
+	if !strings.Contains(out, "enum: open_id=以 open_id 标识用户|user_id=以 user_id 标识用户") {
+		t.Errorf("expected compact enum value=meaning inline:\n%s", out)
+	}
+
+	// --data is Request Body; --params is Raw Parameter Input (NOT API Parameters)
+	// and carries the precedence rule.
+	if i := idx("--data"); i < iBody || i > iRaw {
+		t.Errorf("--data not under Request Body:\n%s", out)
+	}
+	if i := idx("--params"); i < iRaw || i > iExec {
+		t.Errorf("--params not under Raw Parameter Input:\n%s", out)
+	}
+	if !strings.Contains(out, "typed flags override matching keys in --params") {
+		t.Errorf("missing --params precedence rule:\n%s", out)
+	}
+
+	// Control flags land in Execution/Output.
+	if i := idx("--dry-run"); i < iExec || i > iOut {
+		t.Errorf("--dry-run not under Execution:\n%s", out)
+	}
+	if idx("--format") < iOut {
+		t.Errorf("--format not under Output:\n%s", out)
+	}
+
+	// The usage template is wired to the grouped renderer (no flat Flags: list).
+	if u := cmd.UsageString(); !strings.Contains(u, "API Parameters:") || strings.Contains(u, "\nFlags:\n") {
+		t.Errorf("usage template not grouped:\n%s", u)
+	}
+}
+
+// TestServiceFlagGroups_UndocumentedBodyIsRaw: a POST with no documented body
+// fields still offers --data (escape hatch) but must NOT imply a declared body —
+// it goes under Raw Parameter Input, not "Request Body".
+func TestServiceFlagGroups_UndocumentedBodyIsRaw(t *testing.T) {
+	method := map[string]interface{}{"path": "things/do", "httpMethod": "POST"} // POST, no requestBody, no params
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(method), "do", "things", nil)
+	out := renderServiceFlagGroups(cmd)
+
+	if strings.Contains(out, "Request Body:") {
+		t.Errorf("undocumented body must not render a Request Body section:\n%s", out)
+	}
+	iRaw, iData := strings.Index(out, "Raw Parameter Input:"), strings.Index(out, "--data")
+	if iRaw < 0 || iData < iRaw {
+		t.Errorf("--data not under Raw Parameter Input:\n%s", out)
+	}
+	if !strings.Contains(out, "no documented fields") {
+		t.Errorf("--data should be labeled a raw escape hatch:\n%s", out)
+	}
+}

cmd/service/paramflags.go

@@ -0,0 +1,166 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package service
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/meta"
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+type boundParamFlag struct {
+	field meta.Field
+	read  func() interface{}
+}
+
+// paramsOnlyField is a path/query parameter that got no typed flag because its
+// kebab name is already taken by another flag (a standard flag like --format, or
+// a root persistent flag). It stays reachable via --params; the binder keeps it,
+// with the flag that claimed the name, so --help can show the exact --params form
+// and steer the reader off the wrong flag.
+type paramsOnlyField struct {
+	field   meta.Field
+	claimed *pflag.Flag
+}
+
+// paramFlagBinder owns one service method's generated typed param flags: it
+// registers them (kind, help, enum completion, reserved-name skip) and applies
+// the --params overlay, where a changed typed flag overrides its key in the
+// --params JSON. Holding the field<->flag binding here keeps the request builder
+// from re-deriving which flags map to which param keys.
+type paramFlagBinder struct {
+	bound      []boundParamFlag
+	paramsOnly []paramsOnlyField
+}
+
+// newParamFlagBinder registers one typed kebab flag per path/query parameter on
+// cmd and returns a binder for the --params overlay. A name already taken by
+// another flag is skipped — pflag panics on a local duplicate and a generated
+// flag would silently shadow a persistent one — and recorded as paramsOnly so
+// the parameter stays reachable (and discoverable) via --params. The taken set
+// is derived, not hand-listed: local flags (the standard set, registered before
+// this runs) via cmd, the lazily-added --help materialized here, and the root's
+// persistent flags via reserved (nil for direct callers that have no root).
+func newParamFlagBinder(cmd *cobra.Command, params []meta.Field, reserved *pflag.FlagSet) *paramFlagBinder {
+	cmd.InitDefaultHelpFlag() // materialize --help/-h so the local guard below sees it
+	b := &paramFlagBinder{}
+	for _, f := range params {
+		name := f.FlagName()
+		if claimed := flagClaiming(cmd, reserved, name); claimed != nil {
+			b.paramsOnly = append(b.paramsOnly, paramsOnlyField{field: f, claimed: claimed})
+			continue
+		}
+		read := registerTypedFlag(cmd.Flags(), name, f.CanonicalType(), paramFlagUsage(f))
+		if values := enumStrings(f.EnumValues()); len(values) > 0 {
+			cmdutil.RegisterFlagCompletion(cmd, name, func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+				return values, cobra.ShellCompDirectiveNoFileComp
+			})
+		}
+		// Group as an API parameter and mark required/optional for the
+		// Required/Optional subsections of the grouped --help renderer.
+		if fl := cmd.Flags().Lookup(name); fl != nil {
+			annotate(fl, flagGroupAnnotation, []string{groupParams})
+			sub := subOptional
+			if f.Required {
+				sub = subRequired
+			}
+			annotate(fl, flagSubAnnotation, []string{sub})
+		}
+		b.bound = append(b.bound, boundParamFlag{field: f, read: read})
+	}
+	return b
+}
+
+// flagClaiming returns the flag already occupying name (so a typed param flag
+// would collide), or nil when the name is free. It checks the command's own
+// flags (the standard set + the materialized --help) and the root's persistent
+// flags — so the reserved set is whatever is actually registered, never a
+// hand-kept list that drifts when a global flag is added.
+func flagClaiming(cmd *cobra.Command, reserved *pflag.FlagSet, name string) *pflag.Flag {
+	if fl := cmd.Flags().Lookup(name); fl != nil {
+		return fl
+	}
+	if reserved != nil {
+		return reserved.Lookup(name)
+	}
+	return nil
+}
+
+// paramsOnlyHelp renders the --help addendum for parameters that have no typed
+// flag, or "" when there are none. Per field: a copy-pasteable --params form,
+// the same fieldFacts a typed flag would show on its usage line, and what the
+// colliding flag actually does — so neither a human nor an agent sets the
+// wrong one (e.g. --format, which is the output format, not the API parameter).
+func (b *paramFlagBinder) paramsOnlyHelp() string {
+	if len(b.paramsOnly) == 0 {
+		return ""
+	}
+	var sb strings.Builder
+	sb.WriteString("\nParameters set via --params (no typed flag; the name is taken by another flag):\n")
+	for _, p := range b.paramsOnly {
+		name := p.field.Name
+		fmt.Fprintf(&sb, "  %s: --params '{%q: %s}'\n", name, name, paramExample(p.field))
+		for _, fact := range fieldFacts(p.field) {
+			fmt.Fprintf(&sb, "      %s\n", fact)
+		}
+		if p.claimed != nil {
+			fmt.Fprintf(&sb, "      do not use --%s (%s)\n", p.claimed.Name, p.claimed.Usage)
+		}
+	}
+	return sb.String()
+}
+
+// hasTypedFlag reports whether the binder registered a typed flag for the
+// param named name. False for params-only fields — a flag with the same kebab
+// name may exist (that's the collision), but it is not this param's input.
+// Nil-safe for direct buildServiceRequest callers that have no binder.
+func (b *paramFlagBinder) hasTypedFlag(name string) bool {
+	if b == nil {
+		return false
+	}
+	for _, pf := range b.bound {
+		if pf.field.Name == name {
+			return true
+		}
+	}
+	return false
+}
+
+// overlay lets an explicit typed flag override the same key in --params
+// (--params is the base). Only changed flags apply, so the --params-only path is
+// unchanged. A nil binder or cmd is a no-op.
+func (b *paramFlagBinder) overlay(cmd *cobra.Command, params map[string]interface{}) {
+	if b == nil || cmd == nil {
+		return
+	}
+	for _, pf := range b.bound {
+		if cmd.Flags().Changed(pf.field.FlagName()) {
+			params[pf.field.Name] = pf.read()
+		}
+	}
+}
+
+// registerTypedFlag registers one flag of the given canonical JSON-Schema kind
+// and returns a reader for its parsed value; the kind→pflag-type switch lives
+// only here.
+func registerTypedFlag(fs *pflag.FlagSet, name, kind, usage string) func() interface{} {
+	switch kind {
+	case "integer":
+		return flagReader(fs.Int(name, 0, usage))
+	case "boolean":
+		return flagReader(fs.Bool(name, false, usage))
+	case "array":
+		return flagReader(fs.StringArray(name, nil, usage))
+	default:
+		return flagReader(fs.String(name, "", usage))
+	}
+}
+
+func flagReader[T any](p *T) func() interface{} {
+	return func() interface{} { return *p }
+}

cmd/service/paramflags_test.go

@@ -0,0 +1,626 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package service
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/meta"
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+// imChatMembersCreate: POST chats/{chat_id}/members with one path param and one
+// optional enum query param — the canonical case from the screenshot feedback.
+func imChatMembersCreate() meta.Method {
+	return meta.FromMap(map[string]interface{}{
+		"path":       "chats/{chat_id}/members",
+		"httpMethod": "POST",
+		"parameters": map[string]interface{}{
+			"chat_id": map[string]interface{}{
+				"type": "string", "location": "path", "required": true,
+			},
+			"member_id_type": map[string]interface{}{
+				"type": "string", "location": "query", "required": false,
+				"options": []interface{}{
+					map[string]interface{}{"value": "open_id"},
+					map[string]interface{}{"value": "user_id"},
+				},
+			},
+		},
+	})
+}
+
+func TestServiceMethod_TypedFlagRegistered(t *testing.T) {
+	f := &cmdutil.Factory{}
+	cmd := NewCmdServiceMethod(f, imSpec(), imChatMembersCreate(), "create", "chat.members", nil)
+
+	if cmd.Flags().Lookup("chat-id") == nil {
+		t.Error("expected generated --chat-id flag for path param chat_id")
+	}
+	if cmd.Flags().Lookup("member-id-type") == nil {
+		t.Error("expected generated --member-id-type flag for query param member_id_type")
+	}
+}
+
+// A query param literally named "format" kebab-collides with the global
+// --format flag. Generation must skip it (never re-register, never panic) and
+// leave the standard --format flag intact.
+func TestServiceMethod_TypedFlagReservedCollisionSkipped(t *testing.T) {
+	method := map[string]interface{}{
+		"path":       "messages",
+		"httpMethod": "GET",
+		"parameters": map[string]interface{}{
+			"format": map[string]interface{}{"type": "string", "location": "query"},
+		},
+	}
+
+	var cmd *cobra.Command
+	func() {
+		defer func() {
+			if r := recover(); r != nil {
+				t.Fatalf("flag generation panicked on reserved-name collision: %v", r)
+			}
+		}()
+		cmd = NewCmdServiceMethod(&cmdutil.Factory{}, imSpec(), meta.FromMap(method), "list", "messages", nil)
+	}()
+
+	fl := cmd.Flags().Lookup("format")
+	if fl == nil || fl.DefValue != "json" {
+		t.Fatalf("standard --format flag must be preserved, got %+v", fl)
+	}
+}
+
+func TestServiceMethod_TypedFlag_DrivesPathParam(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), imChatMembersCreate(), "create", "chat.members", nil)
+	cmd.SetArgs([]string{"--chat-id", "oc_abc123", "--data", `{"id_list":["ou_x"]}`, "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "chats/oc_abc123/members") {
+		t.Errorf("expected URL with chat_id substituted from --chat-id, got:\n%s", stdout.String())
+	}
+}
+
+func TestServiceMethod_TypedFlag_DrivesQueryParam(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), imChatMembersCreate(), "create", "chat.members", nil)
+	cmd.SetArgs([]string{"--chat-id", "oc_abc123", "--member-id-type", "open_id", "--data", `{}`, "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "member_id_type") || !strings.Contains(out, "open_id") {
+		t.Errorf("expected query param member_id_type=open_id from flag, got:\n%s", out)
+	}
+}
+
+func TestServiceMethod_TypedFlag_AgreesWithParams(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), imChatMembersCreate(), "create", "chat.members", nil)
+	cmd.SetArgs([]string{"--chat-id", "oc_abc123", "--params", `{"chat_id":"oc_abc123"}`, "--data", `{}`, "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("same value via flag and --params should be accepted, got: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "chats/oc_abc123/members") {
+		t.Errorf("expected URL with chat_id, got:\n%s", stdout.String())
+	}
+}
+
+// --params is the base; an explicit typed flag overrides the same key.
+func TestServiceMethod_TypedFlag_OverridesParams(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), imChatMembersCreate(), "create", "chat.members", nil)
+	cmd.SetArgs([]string{"--chat-id", "oc_flag", "--params", `{"chat_id":"oc_params"}`, "--data", `{}`, "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "chats/oc_flag/members") {
+		t.Errorf("expected --chat-id to override --params chat_id, got:\n%s", out)
+	}
+	if strings.Contains(out, "oc_params") {
+		t.Errorf("--params value should have been overridden by the flag, got:\n%s", out)
+	}
+}
+
+// Override works for a non-string (integer) param too, exercising the int
+// register/read path end to end.
+func TestServiceMethod_TypedFlag_IntegerOverridesParams(t *testing.T) {
+	method := map[string]interface{}{
+		"path":       "messages",
+		"httpMethod": "GET",
+		"parameters": map[string]interface{}{
+			"page_size": map[string]interface{}{"type": "integer", "location": "query"},
+		},
+	}
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(method), "list", "messages", nil)
+	cmd.SetArgs([]string{"--page-size", "100", "--params", `{"page_size":5}`, "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "page_size") || !strings.Contains(out, "100") {
+		t.Errorf("expected --page-size 100 to override --params page_size=5, got:\n%s", out)
+	}
+}
+
+// Regression: with no typed flags passed, behavior is byte-identical to today.
+func TestServiceMethod_TypedFlag_OnlyParamsStillWorks(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), imChatMembersCreate(), "create", "chat.members", nil)
+	cmd.SetArgs([]string{"--params", `{"chat_id":"oc_abc123"}`, "--data", `{}`, "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "chats/oc_abc123/members") {
+		t.Errorf("expected URL with chat_id from --params, got:\n%s", stdout.String())
+	}
+}
+
+// Regression: --params null is valid JSON that unmarshals to a nil map. A typed
+// flag overlaying onto it must not panic (assignment to a nil map) — null is
+// treated as "no base params", with the flag value applied on top.
+func TestServiceMethod_TypedFlag_OverridesNullParams(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), imChatMembersCreate(), "create", "chat.members", nil)
+	cmd.SetArgs([]string{"--chat-id", "oc_abc123", "--params", "null", "--data", `{}`, "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("--params null with a typed flag should not error, got: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "chats/oc_abc123/members") {
+		t.Errorf("expected chat_id from --chat-id over null --params, got:\n%s", stdout.String())
+	}
+}
+
+// Startup smoke test: registering every embedded method must not panic on a
+// generated-flag name collision (pflag panics on duplicate registration, which
+// would crash the whole CLI at startup), and a known path param must surface as
+// a typed flag end to end.
+func TestRegisterServiceCommands_GeneratesFlagsNoPanic(t *testing.T) {
+	root := &cobra.Command{Use: "lark-cli"}
+	f := &cmdutil.Factory{}
+
+	defer func() {
+		if r := recover(); r != nil {
+			t.Fatalf("registering all service commands panicked: %v", r)
+		}
+	}()
+	RegisterServiceCommands(root, f)
+
+	create, _, err := root.Find([]string{"im", "chat.members", "create"})
+	if err != nil {
+		t.Fatalf("im chat.members create not registered: %v", err)
+	}
+	if create.Flags().Lookup("chat-id") == nil {
+		t.Error("expected generated --chat-id flag on im chat.members create")
+	}
+}
+
+// Locks the boolean and array branches of bindParamFlag end to end (string and
+// integer are covered above): a bool flag yields true and a repeatable array
+// flag yields all its elements in the request.
+func TestServiceMethod_TypedFlag_BoolAndArrayKinds(t *testing.T) {
+	method := map[string]interface{}{
+		"path":       "items",
+		"httpMethod": "GET",
+		"parameters": map[string]interface{}{
+			"with_deleted": map[string]interface{}{"type": "boolean", "location": "query"},
+			"ids":          map[string]interface{}{"type": "list", "location": "query"},
+		},
+	}
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(method), "list", "items", nil)
+	cmd.SetArgs([]string{"--with-deleted", "--ids", "a", "--ids", "b", "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	for _, want := range []string{"with_deleted", "true", "ids", "\"a\"", "\"b\""} {
+		if !strings.Contains(out, want) {
+			t.Errorf("expected dry-run output to contain %q, got:\n%s", want, out)
+		}
+	}
+}
+
+// Override (--params base, typed flag wins) is covered for string and integer
+// above; this locks the same semantics for the boolean and array kinds.
+func TestServiceMethod_TypedFlag_BoolAndArrayOverrideParams(t *testing.T) {
+	method := map[string]interface{}{
+		"path":       "items",
+		"httpMethod": "GET",
+		"parameters": map[string]interface{}{
+			"with_deleted": map[string]interface{}{"type": "boolean", "location": "query"},
+			"ids":          map[string]interface{}{"type": "list", "location": "query"},
+		},
+	}
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(method), "list", "items", nil)
+	cmd.SetArgs([]string{
+		"--params", `{"with_deleted":false,"ids":["from_params"]}`,
+		"--with-deleted", "--ids", "a", "--ids", "b",
+		"--dry-run",
+	})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	for _, want := range []string{"with_deleted", "true", "\"a\"", "\"b\""} {
+		if !strings.Contains(out, want) {
+			t.Errorf("expected flag to override --params (want %q), got:\n%s", want, out)
+		}
+	}
+	if strings.Contains(out, "from_params") {
+		t.Errorf("--params array value should have been overridden by --ids, got:\n%s", out)
+	}
+}
+
+// A param whose kebab name collides with a global flag (here "format" vs the
+// global --format) gets no typed flag, but the collision is no longer silent:
+// non-colliding params still get flags, the global --format is untouched, and
+// --help shows the exact --params form and steers the reader off --format.
+func TestServiceMethod_ParamsOnly_HelpSteersToParams(t *testing.T) {
+	method := map[string]interface{}{
+		"path":       "things/{thing_id}",
+		"httpMethod": "GET",
+		"parameters": map[string]interface{}{
+			"thing_id": map[string]interface{}{"type": "string", "location": "path", "required": true},
+			"format": map[string]interface{}{"type": "string", "location": "query", "min": "1", "max": "64", "description": "返回的消息体格式。", "options": []interface{}{
+				map[string]interface{}{"value": "full"},
+				map[string]interface{}{"value": "metadata"},
+			}},
+		},
+	}
+	cmd := NewCmdServiceMethod(&cmdutil.Factory{}, imSpec(), meta.FromMap(method), "get", "things", nil)
+
+	if cmd.Flags().Lookup("thing-id") == nil {
+		t.Error("non-colliding param should still get a typed --thing-id flag")
+	}
+	if fl := cmd.Flags().Lookup("format"); fl == nil || fl.DefValue != "json" {
+		t.Fatalf("global --format must be preserved (not shadowed), got %+v", fl)
+	}
+	for _, want := range []string{`--params '{"format"`, "返回的消息体格式", "full", "metadata", "min: 1, max: 64", "do not use --format"} {
+		if !strings.Contains(cmd.Long, want) {
+			t.Errorf("help should contain %q so the reader uses --params, not --format; got:\n%s", want, cmd.Long)
+		}
+	}
+}
+
+// The collision guard derives reserved names from the actual flag sets — local
+// flags plus the root's persistent flags passed in — so a future persistent
+// flag is covered with no hand-maintained list. Here a param named "profile"
+// (a root persistent flag) is skipped while a normal param is bound.
+func TestParamFlagBinder_PersistentFlagReserved(t *testing.T) {
+	cmd := &cobra.Command{Use: "x"}
+	reserved := pflag.NewFlagSet("root", pflag.ContinueOnError)
+	reserved.String("profile", "", "use a specific profile")
+
+	m := meta.FromMap(map[string]interface{}{"parameters": map[string]interface{}{
+		"profile": map[string]interface{}{"type": "string", "location": "query"},
+		"id":      map[string]interface{}{"type": "string", "location": "path"},
+	}})
+	b := newParamFlagBinder(cmd, m.Params(), reserved)
+
+	if cmd.Flags().Lookup("id") == nil {
+		t.Error("non-colliding param should get a typed flag")
+	}
+	if cmd.Flags().Lookup("profile") != nil {
+		t.Error("param colliding with a reserved persistent flag must not be registered")
+	}
+	found := false
+	for _, p := range b.paramsOnly {
+		if p.field.Name == "profile" {
+			found = true
+		}
+	}
+	if !found {
+		t.Error("colliding param should be recorded for the --params help note")
+	}
+}
+
+// boolIntQueryMethod is the fixture for the zero-value semantics tests: one
+// boolean and one integer query param, where false and 0 are meaningful values.
+func boolIntQueryMethod(required bool) meta.Method {
+	return meta.FromMap(map[string]interface{}{
+		"path":       "items",
+		"httpMethod": "GET",
+		"parameters": map[string]interface{}{
+			"with_deleted": map[string]interface{}{"type": "boolean", "location": "query", "required": required},
+			"page_size":    map[string]interface{}{"type": "integer", "location": "query"},
+		},
+	})
+}
+
+// Presence is intent: a typed flag is only overlaid when explicitly Changed,
+// so --flag=false / --flag 0 are real values and must be sent — not silently
+// dropped as "empty", which would let the API default win over an explicit
+// user choice.
+func TestServiceMethod_TypedFlag_ExplicitFalseAndZeroAreSent(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), boolIntQueryMethod(false), "list", "items", nil)
+	cmd.SetArgs([]string{"--with-deleted=false", "--page-size", "0", "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	for _, want := range []string{`"with_deleted": false`, `"page_size": 0`} {
+		if !strings.Contains(out, want) {
+			t.Errorf("explicit zero value must be sent (want %s), got:\n%s", want, out)
+		}
+	}
+}
+
+// An explicitly provided false satisfies a required query parameter — the
+// pre-flight must not report "missing" for a value the user just set.
+func TestServiceMethod_TypedFlag_ExplicitFalseSatisfiesRequired(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), boolIntQueryMethod(true), "list", "items", nil)
+	cmd.SetArgs([]string{"--with-deleted=false", "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("required param explicitly set to false must pass pre-flight, got: %v", err)
+	}
+	if !strings.Contains(stdout.String(), `"with_deleted": false`) {
+		t.Errorf("explicit false must be sent, got:\n%s", stdout.String())
+	}
+}
+
+// The same presence-is-intent rule applies to the --params JSON base: a key
+// deliberately written as false/0 is sent. (Zero values used to be silently
+// dropped; this locks the corrected semantics as the contract.)
+func TestServiceMethod_Params_JSONZeroValuesAreSent(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), boolIntQueryMethod(false), "list", "items", nil)
+	cmd.SetArgs([]string{"--params", `{"with_deleted":false,"page_size":0}`, "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	for _, want := range []string{`"with_deleted": false`, `"page_size": 0`} {
+		if !strings.Contains(out, want) {
+			t.Errorf("--params zero value must be sent (want %s), got:\n%s", want, out)
+		}
+	}
+}
+
+// "" stays unusable: a required parameter fed an empty-string placeholder is
+// still caught by the friendly pre-flight error, not sent as an empty value.
+func TestServiceMethod_Params_EmptyStringStillMissing(t *testing.T) {
+	method := meta.FromMap(map[string]interface{}{
+		"path":       "items",
+		"httpMethod": "GET",
+		"parameters": map[string]interface{}{
+			"user_id_type": map[string]interface{}{"type": "string", "location": "query", "required": true},
+		},
+	})
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), method, "list", "items", nil)
+	cmd.SetArgs([]string{"--params", `{"user_id_type":""}`, "--dry-run"})
+
+	err := cmd.Execute()
+	if err == nil || !strings.Contains(err.Error(), "missing required query parameter") {
+		t.Fatalf("empty string for a required param should still pre-flight error, got: %v", err)
+	}
+}
+
+// A declared optional query param fed "" is dropped (unusable value), not sent
+// as an empty query value — the declared-param loop owns the decision and the
+// undeclared passthrough must not resurrect it. Undeclared keys stay the
+// verbatim raw escape hatch.
+func TestServiceMethod_Params_EmptyOptionalDroppedUndeclaredKept(t *testing.T) {
+	method := meta.FromMap(map[string]interface{}{
+		"path":       "items",
+		"httpMethod": "GET",
+		"parameters": map[string]interface{}{
+			"user_id_type": map[string]interface{}{"type": "string", "location": "query"},
+		},
+	})
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), method, "list", "items", nil)
+	cmd.SetArgs([]string{"--params", `{"user_id_type":"","custom_key":"v1"}`, "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	if strings.Contains(out, "user_id_type") {
+		t.Errorf("declared optional param with empty value must be dropped, got:\n%s", out)
+	}
+	if !strings.Contains(out, `"custom_key": "v1"`) {
+		t.Errorf("undeclared key must pass through verbatim, got:\n%s", out)
+	}
+}
+
+// min/max from the metadata surface on the typed flag's help line, in the same
+// vocabulary as the envelope's minimum/maximum.
+func TestParamFlagUsage_Bounds(t *testing.T) {
+	cases := []struct{ name, min, max, want string }{
+		{"both", "1", "100", "min: 1, max: 100"},
+		{"min only", "1", "", "min: 1"},
+		{"max only", "", "64", "max: 64"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			fields := meta.FromMap(map[string]interface{}{"parameters": map[string]interface{}{
+				"page_size": map[string]interface{}{"type": "integer", "location": "query", "min": tc.min, "max": tc.max},
+			}}).Params()
+			if usage := paramFlagUsage(fields[0]); !strings.Contains(usage, tc.want) {
+				t.Errorf("usage = %q, want contains %q", usage, tc.want)
+			}
+		})
+	}
+	t.Run("no bounds, no clause", func(t *testing.T) {
+		fields := meta.FromMap(map[string]interface{}{"parameters": map[string]interface{}{
+			"page_token": map[string]interface{}{"type": "string", "location": "query"},
+		}}).Params()
+		if usage := paramFlagUsage(fields[0]); strings.Contains(usage, "min:") || strings.Contains(usage, "max:") {
+			t.Errorf("usage without bounds should not mention min/max, got %q", usage)
+		}
+	})
+}
+
+// The sanitized field description rides the help line — a bare name like
+// user_mailbox_id carries no meaning. The cut is at note separators (;), NOT
+// at sentence ends (。): the later sentence often holds the key affordance.
+func TestParamFlagUsage_Description(t *testing.T) {
+	fields := meta.FromMap(map[string]interface{}{"parameters": map[string]interface{}{
+		"user_mailbox_id": map[string]interface{}{
+			"type": "string", "location": "path", "required": true,
+			"description": `用户邮箱地址。当使用用户身份访问时，可以输入"me"代表当前调用接口用户;后续补充说明不该出现`,
+		},
+	}}).Params()
+	usage := paramFlagUsage(fields[0])
+	if !strings.Contains(usage, `可以输入"me"代表当前调用接口用户`) {
+		t.Errorf("description must keep full sentences up to the note separator, got %q", usage)
+	}
+	if strings.Contains(usage, "补充说明") {
+		t.Errorf("text after the note separator must be cut, got %q", usage)
+	}
+
+	t.Run("long description truncated", func(t *testing.T) {
+		fields := meta.FromMap(map[string]interface{}{"parameters": map[string]interface{}{
+			"x": map[string]interface{}{
+				"type": "string", "location": "query",
+				"description": strings.Repeat("长", 80),
+			},
+		}}).Params()
+		usage := paramFlagUsage(fields[0])
+		if !strings.Contains(usage, "...") {
+			t.Errorf("long description should be truncated with ellipsis, got %q", usage)
+		}
+		if strings.Contains(usage, strings.Repeat("长", 61)) {
+			t.Errorf("description should not exceed the cap, got %q", usage)
+		}
+	})
+
+	t.Run("trailing sentence punctuation trimmed", func(t *testing.T) {
+		fields := meta.FromMap(map[string]interface{}{"parameters": map[string]interface{}{
+			"x": map[string]interface{}{
+				"type": "string", "location": "query", "description": "返回格式。",
+			},
+		}}).Params()
+		if usage := paramFlagUsage(fields[0]); strings.Contains(usage, "。.") {
+			t.Errorf("clause join must not double the punctuation, got %q", usage)
+		}
+	})
+}
+
+// Pins the convergence contract: the params-only addendum renders the SAME
+// fieldFacts list the typed flag's usage line joins inline — a fact added to
+// fieldFacts reaches both surfaces, and neither can drift over what a param's
+// help says (the addendum once rendered values-only enums and silently lacked
+// the API default).
+func TestParamHelp_BothSurfacesRenderFieldFacts(t *testing.T) {
+	f := meta.FromMap(map[string]interface{}{"parameters": map[string]interface{}{
+		"mode": map[string]interface{}{
+			"type": "string", "location": "query",
+			"description": "模式选择。",
+			"default":     "fast",
+			"min":         "1", "max": "8",
+			"options": []interface{}{
+				map[string]interface{}{"value": "fast", "description": "快速"},
+				map[string]interface{}{"value": "full"},
+			},
+		},
+	}}).Params()[0]
+
+	facts := fieldFacts(f)
+	if len(facts) != 4 { // description, enum, bounds, API default
+		t.Fatalf("fieldFacts = %v, want 4 facts", facts)
+	}
+	usage := paramFlagUsage(f)
+	help := (&paramFlagBinder{paramsOnly: []paramsOnlyField{{field: f}}}).paramsOnlyHelp()
+	for _, fact := range facts {
+		if !strings.Contains(usage, fact) {
+			t.Errorf("usage line missing fact %q: %q", fact, usage)
+		}
+		if !strings.Contains(help, fact) {
+			t.Errorf("params-only addendum missing fact %q:\n%s", fact, help)
+		}
+	}
+}
+
+// Bounds reach the registered flag's help end to end.
+func TestServiceMethod_TypedFlag_HelpShowsBounds(t *testing.T) {
+	method := meta.FromMap(map[string]interface{}{
+		"path":       "items",
+		"httpMethod": "GET",
+		"parameters": map[string]interface{}{
+			"page_size": map[string]interface{}{"type": "integer", "location": "query", "min": "1", "max": "100", "default": "20"},
+		},
+	})
+	cmd := NewCmdServiceMethod(&cmdutil.Factory{}, imSpec(), method, "list", "items", nil)
+	fl := cmd.Flags().Lookup("page-size")
+	if fl == nil {
+		t.Fatal("expected generated --page-size flag")
+	}
+	if !strings.Contains(fl.Usage, "min: 1, max: 100") {
+		t.Errorf("flag usage should carry bounds, got %q", fl.Usage)
+	}
+}
+
+// The missing-required hint must name both recovery paths — the typed flag and
+// the --params fallback — so a reader who only knows one input style can
+// proceed without a round-trip through schema.
+func TestServiceMethod_MissingRequired_HintNamesFlagAndParams(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), imChatMembersCreate(), "create", "chat.members", nil)
+	cmd.SetArgs([]string{"--data", `{"id_list":["ou_x"]}`, "--dry-run"})
+
+	err := cmd.Execute()
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
+	}
+	for _, want := range []string{"--chat-id", `--params '{"chat_id": "<value>"}'`, "lark-cli schema im.chat.members.create"} {
+		if !strings.Contains(ve.Hint, want) {
+			t.Errorf("hint %q should contain %q", ve.Hint, want)
+		}
+	}
+}
+
+// A params-only required field (kebab name claimed by the standard --format
+// flag) has no typed flag to offer: the hint must give only the --params form,
+// never steer the reader to the colliding flag.
+func TestServiceMethod_MissingRequired_ParamsOnlyHintSkipsFlag(t *testing.T) {
+	method := meta.FromMap(map[string]interface{}{
+		"path":       "messages",
+		"httpMethod": "GET",
+		"parameters": map[string]interface{}{
+			"format": map[string]interface{}{"type": "string", "location": "query", "required": true},
+		},
+	})
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), method, "list", "messages", nil)
+	cmd.SetArgs([]string{"--dry-run"})
+
+	err := cmd.Execute()
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
+	}
+	if !strings.Contains(ve.Hint, `--params '{"format": "<value>"}'`) {
+		t.Errorf("hint %q should carry the --params form", ve.Hint)
+	}
+	if strings.Contains(ve.Hint, "set --format") {
+		t.Errorf("hint %q must not steer to the colliding --format flag", ve.Hint)
+	}
+}

cmd/service/paramhelp.go

@@ -0,0 +1,162 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Help rendering for generated param flags. fieldFacts is the single list of
+// agent-relevant facts a param exposes; every help surface (the typed flag's
+// usage line, the params-only --params addendum) renders that one list, so the
+// surfaces cannot drift over which facts exist. Values come from the
+// meta.Field accessors, so nothing here depends on internal/schema.
+
+package service
+
+import (
+	"fmt"
+	"regexp"
+	"strconv"
+	"strings"
+
+	"github.com/larksuite/cli/internal/meta"
+	"github.com/larksuite/cli/internal/util"
+)
+
+// fieldFacts returns a param field's facts in display order, each as a compact
+// one-line clause: the sanitized description, the allowed enum values (with
+// meanings), the min/max constraint, and the API default. This is the ONE
+// place that decides what a param's help says — add a fact here (e.g. a future
+// deprecation marker) and every surface shows it. Unabridged prose and
+// per-option detail stay in `lark-cli schema`.
+func fieldFacts(f meta.Field) []string {
+	var facts []string
+	if d := sanitizeFieldDesc(f.Description); d != "" {
+		facts = append(facts, d)
+	}
+	if opts := f.EnumOptions(); len(opts) > 0 {
+		facts = append(facts, "enum: "+formatEnumInline(opts))
+	}
+	if b := formatBoundsInline(f); b != "" {
+		facts = append(facts, b)
+	}
+	if s := literalStr(f.CoercedDefault()); s != "" {
+		facts = append(facts, "API default: "+s)
+	}
+	return facts
+}
+
+// paramFlagUsage renders the typed param flag's help line:
+//
+//	<param_name>, required|optional[. <fact>]...
+//
+// It leads with the canonical underscore param name (the key this flag
+// overrides in --params) and required/optional, then joins the field's facts
+// inline.
+func paramFlagUsage(f meta.Field) string {
+	req := "optional"
+	if f.Required {
+		req = "required"
+	}
+	parts := append([]string{fmt.Sprintf("%s, %s", f.Name, req)}, fieldFacts(f)...)
+	return strings.Join(parts, ". ") + "."
+}
+
+// paramExample picks a concrete sample for a params-only field's --help snippet:
+// its first allowed enum value, else its example, else a placeholder.
+func paramExample(f meta.Field) string {
+	if vals := enumStrings(f.EnumValues()); len(vals) > 0 {
+		return fmt.Sprintf("%q", vals[0])
+	}
+	if s := literalStr(f.CoercedExample()); s != "" {
+		return fmt.Sprintf("%q", s)
+	}
+	return `"<value>"`
+}
+
+var markdownLinkRe = regexp.MustCompile(`\[([^\]]*)\]\([^)]*\)`)
+
+// inlineClause compresses metadata prose into one help clause: markdown links
+// keep their text, the clause cuts at the first rune in stops, whitespace
+// collapses, trailing punctuation goes — sentence enders (the clause join adds
+// its own) and connectors a cut can strand, like a colon introducing a list the
+// newline cut dropped — and the result caps at max runes. The two policies
+// below differ only in where they cut and how much they keep.
+func inlineClause(s, stops string, max int) string {
+	if s == "" {
+		return ""
+	}
+	s = markdownLinkRe.ReplaceAllString(s, "$1")
+	// Backquotes must go: pflag's UnquoteUsage treats a backquoted word in a
+	// flag's usage string as the flag's metavar, so a description like wiki
+	// space_id's "可替换为`my_library`" would render the flag as
+	// "--space-id my_library" instead of "--space-id string".
+	s = strings.ReplaceAll(s, "`", "")
+	if i := strings.IndexAny(s, stops); i >= 0 {
+		s = s[:i]
+	}
+	s = strings.Join(strings.Fields(s), " ")
+	s = strings.TrimRight(s, "。.：:，,、")
+	return util.TruncateStrWithEllipsis(s, max)
+}
+
+// sanitizeOptionDesc is the enum-option policy: many values share one line, so
+// keep only the first clause (cut at 。 too) and stay ultra-compact.
+func sanitizeOptionDesc(s string) string { return inlineClause(s, "。；;\n\r", 40) }
+
+// sanitizeFieldDesc is the field-description policy: one line per field, so
+// keep full sentences and cut only at note separators (meta_data appends
+// bullet notes after ;/；) — the later sentence often carries the key
+// affordance, e.g. user_mailbox_id's `可以输入"me"`.
+func sanitizeFieldDesc(s string) string { return inlineClause(s, "；;\n\r", 60) }
+
+// formatEnumInline renders allowed values for the help line: "v=meaning" when
+// the value carries a (sanitized, truncated) description — so opaque numeric
+// enums like succeed_type read as "0=…|1=…|2=…" — else just "v". Full meanings
+// live in the envelope's enumDescriptions / `lark-cli schema`.
+func formatEnumInline(opts []meta.EnumOption) string {
+	items := make([]string, len(opts))
+	for i, o := range opts {
+		if d := sanitizeOptionDesc(o.Description); d != "" {
+			items[i] = fmt.Sprintf("%v=%s", o.Value, d)
+		} else {
+			items[i] = fmt.Sprintf("%v", o.Value)
+		}
+	}
+	return strings.Join(items, "|")
+}
+
+// formatBoundsInline renders the field's min/max constraint ("min: 1, max:
+// 100", or the single declared side), or "" when the field declares neither.
+// The vocabulary matches the envelope's minimum/maximum, so help and `lark-cli
+// schema` state the same constraint.
+func formatBoundsInline(f meta.Field) string {
+	min, max := f.MinBound(), f.MaxBound()
+	switch {
+	case min != nil && max != nil:
+		return fmt.Sprintf("min: %s, max: %s", formatBound(*min), formatBound(*max))
+	case min != nil:
+		return "min: " + formatBound(*min)
+	case max != nil:
+		return "max: " + formatBound(*max)
+	}
+	return ""
+}
+
+// formatBound renders a bound without a float artifact (100 not 100.000000).
+func formatBound(v float64) string {
+	return strconv.FormatFloat(v, 'f', -1, 64)
+}
+
+// literalStr renders a coerced literal (default/example) for flag help,
+// returning "" for a nil or empty value so the caller can omit the clause.
+func literalStr(v interface{}) string {
+	if v == nil {
+		return ""
+	}
+	return fmt.Sprintf("%v", v)
+}
+
+func enumStrings(enum []interface{}) []string {
+	out := make([]string, 0, len(enum))
+	for _, e := range enum {
+		out = append(out, fmt.Sprintf("%v", e))
+	}
+	return out
+}