docs: add drive knowledge asset workflow guidance

Change-Id: I2431a436e79d5a0e62501fb51aad4bde83f393b8

.github/CODEOWNERS

@@ -1,30 +0,0 @@
-/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-cli <domain> <command>` flow works as expected
+- [ ] Manual local verification confirms the `lark xxx` command works as expected
 
 ## Related Issues
 <!-- Link related issues. Use Closes/Fixes to close them automatically. -->

.github/workflows/ci.yml

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

.gitignore

@@ -1,5 +1,5 @@
 # Build output
-/lark-cli*
+/lark-cli
 .cache/
 dist/
 bin/
@@ -35,8 +35,6 @@ tests/mail/reports/
 # Generated / test artifacts
 .hammer/
 .lark-slides/
-/notes/
-/minutes/
 internal/registry/meta_data.json
 cmd/api/download.bin
 app.log

.golangci.yml

@@ -49,47 +49,18 @@ linters:
           - gocritic
           - depguard
           - forbidigo
-      # Paths that run forbidigo. Add an entry when a path joins one of
-      # the rules below.
-      - path-except: (shortcuts/|internal/|cmd/auth/|cmd/config/|cmd/service/)
+      - path-except: (shortcuts/|internal/)
         linters:
           - forbidigo
       - path: internal/vfs/
         linters:
           - forbidigo
-      # 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.
+      # The shortcuts-no-raw-http forbidigo rule below is shortcuts-only;
+      # internal/ legitimately wraps raw HTTP for the client / credential layer.
       - path-except: shortcuts/
         text: shortcuts-no-raw-http
         linters:
           - forbidigo
-      # errs-typed-only enforced on paths already migrated to errs.NewXxxError.
-      # Add a path when its migration is complete.
-      - path-except: (internal/auth/|internal/errcompat/|internal/errclass/|internal/client/|internal/cmdutil/factory\.go|cmd/auth/|cmd/config/|cmd/service/|shortcuts/common/mcp_client\.go|shortcuts/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:
@@ -108,28 +79,6 @@ linters:
                 Use runtime.FileIO() for file operations or runtime.ValidatePath() for path validation.
     forbidigo:
       forbid:
-        # ── legacy output.Err* helpers banned on migrated paths ──
-        # output.ErrBare is intentionally not listed — it is the predicate-
-        # command silent-exit signal, outside the typed envelope contract.
-        - pattern: output\.(ErrValidation|ErrAuth|ErrNetwork|ErrAPI|ErrWithHint|Errorf)\b
-          msg: >-
-            [errs-typed-only] use errs.NewXxxError(...) builder
-            (see errs/types.go).
-        # ── legacy shared error helpers banned on 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,7 +17,6 @@ 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 where supported, e.g. amd64/arm64)
+make unit-test      # Required before PR (runs with -race)
 make test           # Full: vet + unit + integration
 ```
 
@@ -75,31 +75,7 @@ The one rule to internalize: **every error message you write will be parsed by a
 
 ### Structured errors in commands
 
-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.
+`RunE` functions must return `output.Errorf` / `output.ErrWithHint` — never bare `fmt.Errorf`. AI agents parse stderr as JSON; bare errors break this contract.
 
 ### stdout is data, stderr is everything else
 

CHANGELOG.md

@@ -2,321 +2,6 @@
 
 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
@@ -1175,20 +860,6 @@ 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

Makefile

@@ -8,13 +8,6 @@ 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
@@ -41,7 +34,7 @@ fmt-check:
 
 # ./extension/... keeps the public plugin SDK in the default test matrix.
 unit-test: fetch_meta
-	go test $(RACE_FLAG) -gcflags="all=-N -l" -count=1 \
+	go test -race -gcflags="all=-N -l" -count=1 \
 		./cmd/... ./internal/... ./shortcuts/... ./extension/...
 
 # examples-build keeps the shipped plugin-SDK examples compilable. If this

README.md

@@ -41,7 +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                                 |
+| 🔗 Apps       | Develop, deploy HTML, web pages and applications                                                                                  |
 
 ## Installation & Quick Start
 
@@ -279,8 +279,6 @@ Community contributions are welcome! If you find a bug or have feature suggestio
 
 For major changes, we recommend discussing with us first via an Issue.
 
-Before opening a PR, see [AGENTS.md](./AGENTS.md) for the local build, test, and PR checklist used by contributors and AI agents.
-
 ## License
 
 This project is licensed under the **MIT License**.

README.zh.md

@@ -41,7 +41,7 @@
 | ✍️ 审批     | 查询审批任务、同意/拒绝/转交审批任务、撤回与抄送审批实例              |
 | 🎯 OKR  | 查询、创建、更新 OKR，管理目标、关键结果、对齐、指标和进展记录        |
 | 📋 飞书项目 | 管理工作项、排期与数据 — 由独立的 [meegle-cli](https://github.com/larksuite/meegle-cli) 提供（需单独安装） |
-| 🔗 应用     | 创建妙搭（Spark/Miaoda）应用、发布 HTML/静态站点、云端生成迭代、管理可用范围                                                                                                   |
+| 🔗 应用     | 开发、部署 HTML、Web 页面和应用                                                                                                          |
 
 ## 安装与快速开始
 
@@ -280,8 +280,6 @@ lark-cli schema im.messages.delete
 
 对于较大的改动，建议先通过 Issue 与我们讨论。
 
-提交 PR 前，请先阅读 [AGENTS.md](./AGENTS.md)，其中列出了贡献者和 AI Agent 使用的本地构建、测试和 PR 检查清单。
-
 ## 许可证
 
 本项目基于 **MIT 许可证** 开源。

cmd/api/api.go

@@ -90,7 +90,6 @@ func NewCmdApiWithContext(ctx context.Context, f *cmdutil.Factory, runF func(*AP
 	cmd.Flags().IntVar(&opts.PageLimit, "page-limit", 10, "max pages to fetch with --page-all (0 = unlimited)")
 	cmd.Flags().IntVar(&opts.PageDelay, "page-delay", 200, "delay in ms between pages")
 	cmd.Flags().StringVar(&opts.Format, "format", "json", "output format: json|ndjson|table|csv")
-	cmd.Flags().Bool("json", false, "shorthand for --format json")
 	cmd.Flags().StringVarP(&opts.JqExpr, "jq", "q", "", "jq expression to filter JSON output")
 	cmd.Flags().BoolVar(&opts.DryRun, "dry-run", false, "print request without executing")
 	cmd.Flags().StringVar(&opts.File, "file", "", "file to upload as multipart/form-data ([field=]path, supports - for stdin)")
@@ -239,10 +238,10 @@ func apiRun(opts *APIOptions) error {
 
 	resp, err := ac.DoAPI(opts.Ctx, request)
 	if err != nil {
-		// MarkRaw tells the dispatcher to skip the legacy enrichPermissionError
-		// pass on *output.ExitError values. Typed *errs.* errors that flow
-		// through here keep their canonical message / hint from BuildAPIError;
-		// MarkRaw is a no-op on those (it only flips a flag on *ExitError).
+		// MarkRaw tells the dispatcher to skip enrichPermissionError so the
+		// raw API error detail (log_id, troubleshooter, permission_violations)
+		// stays on the wire — `lark-cli api` callers explicitly want the raw
+		// envelope.
 		return output.MarkRaw(err)
 	}
 	err = client.HandleResponse(resp, client.ResponseOptions{
@@ -254,14 +253,14 @@ func apiRun(opts *APIOptions) error {
 		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.).
+		// Stage 1: CheckResponse emits the legacy *output.ExitError envelope.
+		// Per-domain migration in stage 2+ will route through
+		// errclass.BuildAPIError to populate identity-aware fields
+		// (PermissionError.ConsoleURL needs Brand+AppID from the client).
 		CheckError: ac.CheckResponse,
 	})
-	// MarkRaw: see comment above on the DoAPI path. Skips legacy
-	// *ExitError enrichment; typed errors flow through unchanged.
+	// MarkRaw: see comment above on the DoAPI path. Applies equally to
+	// HandleResponse failures so the raw API error survives to the wire.
 	if err != nil {
 		return output.MarkRaw(err)
 	}

cmd/api/api_test.go

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

cmd/auth/auth.go

@@ -17,7 +17,6 @@ import (
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/errclass"
 )
 
 // NewCmdAuth creates the auth command with subcommands.
@@ -71,7 +70,7 @@ func getUserInfo(ctx context.Context, sdk *lark.Client, accessToken string) (ope
 
 	var resp userInfoResponse
 	if err := json.Unmarshal(apiResp.RawBody, &resp); err != nil {
-		return "", "", fmt.Errorf("failed to parse user info: %w", err)
+		return "", "", fmt.Errorf("failed to parse user info: %v", err)
 	}
 	if resp.Code != 0 {
 		return "", "", fmt.Errorf("failed to get user info [%d]: %s", resp.Code, resp.Msg)
@@ -111,11 +110,6 @@ type appInfoResponse struct {
 	} `json:"data"`
 }
 
-// getAppInfoFn is the package-level seam used by callers (scopes.go) so tests
-// can substitute a fake without standing up a full SDK + httpmock pipeline.
-// Mirrors the pollDeviceToken pattern in login.go.
-var getAppInfoFn = getAppInfo
-
 // getAppInfo queries app info from the Lark API.
 func getAppInfo(ctx context.Context, f *cmdutil.Factory, appId string) (*appInfo, error) {
 	ac, err := f.NewAPIClient()
@@ -137,10 +131,10 @@ func getAppInfo(ctx context.Context, f *cmdutil.Factory, appId string) (*appInfo
 
 	var resp appInfoResponse
 	if err := json.Unmarshal(apiResp.RawBody, &resp); err != nil {
-		return nil, fmt.Errorf("failed to parse response: %w", err)
+		return nil, fmt.Errorf("failed to parse response: %v", err)
 	}
 	if resp.Code != 0 {
-		return nil, classifyAppInfoErr(apiResp.RawBody, resp.Code, resp.Msg, f, appId)
+		return nil, fmt.Errorf("API error [%d]: %s", resp.Code, resp.Msg)
 	}
 
 	app := resp.Data.App
@@ -159,21 +153,3 @@ func getAppInfo(ctx context.Context, f *cmdutil.Factory, appId string) (*appInfo
 
 	return &appInfo{OwnerOpenId: ownerOpenId, UserScopes: userScopes}, nil
 }
-
-// classifyAppInfoErr re-decodes the raw body so BuildAPIError sees the
-// upstream `error` block — the typed appInfoResponse shape drops it.
-func classifyAppInfoErr(rawBody []byte, code int, msg string, f *cmdutil.Factory, appId string) error {
-	var raw map[string]any
-	_ = json.Unmarshal(rawBody, &raw)
-	if raw == nil {
-		raw = map[string]any{}
-	}
-	raw["code"] = code
-	raw["msg"] = msg
-	cc := errclass.ClassifyContext{Identity: string(core.AsBot)}
-	if cfg, _ := f.Config(); cfg != nil {
-		cc.Brand = string(cfg.Brand)
-		cc.AppID = appId
-	}
-	return errclass.BuildAPIError(raw, cc)
-}

cmd/auth/auth_test.go

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

cmd/auth/check.go

@@ -9,7 +9,6 @@ import (
 
 	"github.com/spf13/cobra"
 
-	"github.com/larksuite/cli/errs"
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/output"
@@ -19,7 +18,6 @@ import (
 type CheckOptions struct {
 	Factory *cmdutil.Factory
 	Scope   string
-	JSON    bool
 }
 
 // NewCmdAuthCheck creates the auth check subcommand.
@@ -38,7 +36,6 @@ 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")
 
@@ -50,7 +47,7 @@ func authCheckRun(opts *CheckOptions) error {
 
 	required := strings.Fields(opts.Scope)
 	if len(required) == 0 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--scope cannot be empty").WithParam("--scope")
+		return output.ErrValidation("--scope cannot be empty")
 	}
 
 	config, err := f.Config()

cmd/auth/check_test.go

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

cmd/auth/list.go

@@ -18,7 +18,6 @@ import (
 // ListOptions holds all inputs for auth list.
 type ListOptions struct {
 	Factory *cmdutil.Factory
-	JSON    bool
 }
 
 // NewCmdAuthList creates the auth list subcommand.
@@ -35,7 +34,6 @@ 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
@@ -46,14 +44,6 @@ 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
@@ -71,14 +61,6 @@ 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,7 +4,6 @@
 package auth
 
 import (
-	"encoding/json"
 	"strings"
 	"testing"
 
@@ -35,33 +34,6 @@ 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
@@ -85,48 +57,3 @@ 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,12 +13,9 @@ import (
 
 	"github.com/spf13/cobra"
 
-	"github.com/larksuite/cli/errs"
-
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/registry"
 	"github.com/larksuite/cli/shortcuts"
@@ -56,9 +53,9 @@ run --device-code in a later step after the user confirms authorization. Use 'la
 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 errs.NewValidationError(errs.SubtypeInvalidArgument,
-					"strict mode is %q, user login is disabled in this profile", mode).
-					WithHint("if the user explicitly wants to switch to user identity, see `lark-cli config strict-mode --help` (confirm with the user before switching; switching does NOT require re-bind)")
+				return output.ErrWithHint(output.ExitValidation, "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)")
 			}
 			opts.Ctx = cmd.Context()
 			if runF != nil {
@@ -124,7 +121,7 @@ func authLoginRun(opts *LoginOptions) error {
 	}
 
 	// Determine UI language from saved config
-	var lang i18n.Lang
+	lang := "zh"
 	if multi, _ := core.LoadMultiAppConfig(); multi != nil {
 		if app := multi.FindApp(config.ProfileName); app != nil {
 			lang = app.Lang
@@ -160,14 +157,14 @@ func authLoginRun(opts *LoginOptions) error {
 		for _, d := range selectedDomains {
 			if !knownDomains[d] {
 				if suggestion := suggestDomain(d, knownDomains); suggestion != "" {
-					return errs.NewValidationError(errs.SubtypeInvalidArgument, "unknown domain %q, did you mean %q?", d, suggestion).WithParam("--domain")
+					return output.ErrValidation("unknown domain %q, did you mean %q?", d, suggestion)
 				}
 				available := make([]string, 0, len(knownDomains))
 				for k := range knownDomains {
 					available = append(available, k)
 				}
 				sort.Strings(available)
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "unknown domain %q, available domains: %s", d, strings.Join(available, ", ")).WithParam("--domain")
+				return output.ErrValidation("unknown domain %q, available domains: %s", d, strings.Join(available, ", "))
 			}
 		}
 	}
@@ -175,17 +172,17 @@ func authLoginRun(opts *LoginOptions) error {
 	hasAnyOption := opts.Scope != "" || opts.Recommend || len(selectedDomains) > 0
 
 	if len(opts.Exclude) > 0 && !hasAnyOption {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--exclude requires --scope, --domain, or --recommend to be specified").WithParam("--exclude")
+		return output.ErrValidation("--exclude requires --scope, --domain, or --recommend to be specified")
 	}
 
 	if !hasAnyOption {
 		if !opts.JSON && f.IOStreams.IsTerminal {
-			result, err := runInteractiveLogin(f.IOStreams, lang.Base(), msg, config.Brand)
+			result, err := runInteractiveLogin(f.IOStreams, lang, msg, config.Brand)
 			if err != nil {
 				return err
 			}
 			if result == nil {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "no login options selected")
+				return output.ErrValidation("no login options selected")
 			}
 			selectedDomains = result.Domains
 			scopeLevel = result.ScopeLevel
@@ -201,7 +198,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 errs.NewValidationError(errs.SubtypeInvalidArgument, "please specify the scopes to authorize").WithParam("--scope")
+			return output.ErrValidation("please specify the scopes to authorize")
 		}
 	}
 
@@ -230,7 +227,7 @@ func authLoginRun(opts *LoginOptions) error {
 		}
 
 		if len(candidateScopes) == 0 && opts.Scope == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "no matching scopes found, check domain/scope options")
+			return output.ErrValidation("no matching scopes found, check domain/scope options")
 		}
 
 		// Merge --scope additively with the resolved domain scopes.
@@ -250,13 +247,13 @@ func authLoginRun(opts *LoginOptions) error {
 	if len(opts.Exclude) > 0 {
 		excluded, unknown := applyExcludeScopes(finalScope, opts.Exclude)
 		if len(unknown) > 0 {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument,
+			return output.ErrValidation(
 				"these --exclude scopes are not present in the requested set: %s",
-				strings.Join(unknown, ", ")).WithParam("--exclude")
+				strings.Join(unknown, ", "))
 		}
 		finalScope = excluded
 		if strings.TrimSpace(finalScope) == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "no scopes left after applying --exclude; nothing to authorize").WithParam("--exclude")
+			return output.ErrValidation("no scopes left after applying --exclude; nothing to authorize")
 		}
 	}
 
@@ -267,7 +264,7 @@ func authLoginRun(opts *LoginOptions) error {
 	}
 	authResp, err := larkauth.RequestDeviceAuthorization(httpClient, config.AppID, config.AppSecret, config.Brand, finalScope, f.IOStreams.ErrOut)
 	if err != nil {
-		return errs.NewAuthenticationError(errs.SubtypeUnknown, "device authorization failed: %v", err).WithCause(err)
+		return output.ErrAuth("device authorization failed: %v", err)
 	}
 
 	// --no-wait: return immediately with device code and URL
@@ -279,28 +276,21 @@ func authLoginRun(opts *LoginOptions) error {
 			"verification_url": authResp.VerificationUriComplete,
 			"device_code":      authResp.DeviceCode,
 			"expires_in":       authResp.ExpiresIn,
-			"hint": "**MUST generate QR code AND display it:** You MUST call lark-cli auth qrcode to convert verification_url into a QR code. This is a required step, do NOT skip it. Prefer PNG QR code (--output); use ASCII (--ascii) only when the user explicitly requests it." +
-				"**CRITICAL: You MUST include the QR image in your response.** Generating the file alone is NOT enough—use image tags, inline images, or file attachments to display it." +
-				"**Display order:** Output the URL first, then place the QR code image below the URL." +
-				"**URL Output Rules:** Treat verification_url as an opaque string that cannot be modified. Do NOT URL-encode/decode or add spaces/punctuation." +
-				"For agent harnesses that only deliver final turn messages, make the QR code image (or URL) the final message of the turn and return control to the user; do not block on --device-code in the same turn. **Before ending the turn, tell the user to come back and notify you after completing authorization.**" +
-				"**After the user confirms authorization:** YOU must execute `lark-cli auth login --device-code <device_code>` yourself." +
-				"**Do NOT cache verification_url or device_code for future use.** Always run `lark-cli auth login --no-wait --json` fresh when authorization is needed.",
+			"hint":             fmt.Sprintf("**MUST generate QR code AND display it:** You MUST call lark-cli auth qrcode to convert verification_url into a QR code. This is a required step, do NOT skip it. Prefer PNG QR code (--output); use ASCII (--ascii) only when the user explicitly requests it.**CRITICAL: You MUST include the QR image in your response.** Generating the file alone is NOT enough—use image tags, inline images, or file attachments to display it.**Display order:** Output the URL first, then place the QR code image below the URL.**URL Output Rules:** Treat verification_url as an opaque string that cannot be modified. Do NOT URL-encode/decode or add spaces/punctuation. For agent harnesses that only deliver final turn messages, make the QR code image (or URL) the final message of the turn and return control to the user; do not block on --device-code in the same turn. After the user confirms authorization in a later step, run: lark-cli auth login --device-code %s", authResp.DeviceCode),
 		}
 		encoder := json.NewEncoder(f.IOStreams.Out)
 		encoder.SetEscapeHTML(false)
 		if err := encoder.Encode(data); err != nil {
-			return errs.NewInternalError(errs.SubtypeSDKError, "failed to write JSON output: %v", err).WithCause(err)
+			return output.Errorf(output.ExitInternal, "internal", "failed to write JSON output: %v", err)
 		}
 		return nil
 	}
 
 	// Step 2: Show user code and verification URL.
-	// 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.
+	// 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).
 	if opts.JSON {
 		data := map[string]interface{}{
 			"event":                     "device_authorization",
@@ -313,14 +303,12 @@ func authLoginRun(opts *LoginOptions) error {
 		encoder := json.NewEncoder(f.IOStreams.Out)
 		encoder.SetEscapeHTML(false)
 		if err := encoder.Encode(data); err != nil {
-			return errs.NewInternalError(errs.SubtypeSDKError, "failed to write JSON output: %v", err).WithCause(err)
+			return output.Errorf(output.ExitInternal, "internal", "failed to write JSON output: %v", err)
 		}
 	} else {
 		fmt.Fprintf(f.IOStreams.ErrOut, msg.OpenURL)
 		fmt.Fprintf(f.IOStreams.ErrOut, "  %s\n\n", authResp.VerificationUriComplete)
-		if f.IOStreams != nil && !f.IOStreams.IsTerminal {
-			fmt.Fprintln(f.IOStreams.ErrOut, msg.AgentTimeoutHint)
-		}
+		fmt.Fprintln(f.IOStreams.ErrOut, msg.AgentTimeoutHint)
 	}
 
 	// Step 3: Poll for token
@@ -336,25 +324,25 @@ func authLoginRun(opts *LoginOptions) error {
 				"event": "authorization_failed",
 				"error": result.Message,
 			}); err != nil {
-				return errs.NewInternalError(errs.SubtypeSDKError, "failed to write JSON output: %v", err).WithCause(err)
+				return output.Errorf(output.ExitInternal, "internal", "failed to write JSON output: %v", err)
 			}
 			return output.ErrBare(output.ExitAuth)
 		}
-		return errs.NewAuthenticationError(errs.SubtypeUnknown, "authorization failed: %s", result.Message)
+		return output.ErrAuth("authorization failed: %s", result.Message)
 	}
 	if result.Token == nil {
-		return errs.NewAuthenticationError(errs.SubtypeTokenMissing, "authorization succeeded but no token returned")
+		return output.ErrAuth("authorization succeeded but no token returned")
 	}
 
 	// Step 6: Get user info
 	log(msg.AuthSuccess)
 	sdk, err := f.LarkClient()
 	if err != nil {
-		return errs.NewInternalError(errs.SubtypeSDKError, "failed to get SDK: %v", err).WithCause(err)
+		return output.ErrAuth("failed to get SDK: %v", err)
 	}
 	openId, userName, err := getUserInfo(opts.Ctx, sdk, result.Token.AccessToken)
 	if err != nil {
-		return errs.NewAuthenticationError(errs.SubtypeUnknown, "failed to get user info: %v", err).WithCause(err)
+		return output.ErrAuth("failed to get user info: %v", err)
 	}
 
 	scopeSummary := loadLoginScopeSummary(config.AppID, openId, finalScope, result.Token.Scope)
@@ -372,13 +360,13 @@ func authLoginRun(opts *LoginOptions) error {
 		GrantedAt:        now,
 	}
 	if err := larkauth.SetStoredToken(storedToken); err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "failed to save token: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "internal", "failed to save token: %v", err)
 	}
 
 	// Step 8: Update config — overwrite Users to single user, clean old tokens
 	if err := syncLoginUserToProfile(config.ProfileName, config.AppID, openId, userName); err != nil {
 		_ = larkauth.RemoveStoredToken(config.AppID, openId)
-		return err
+		return output.Errorf(output.ExitInternal, "internal", "failed to update login profile: %v", err)
 	}
 
 	if issue := ensureRequestedScopesGranted(finalScope, result.Token.Scope, msg, scopeSummary); issue != nil {
@@ -407,11 +395,10 @@ 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 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 {
+	// 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 {
 		fmt.Fprintln(f.IOStreams.ErrOut, msg.AgentTimeoutHint)
 	}
 	log(msg.WaitingAuth)
@@ -422,22 +409,22 @@ func authLoginPollDeviceCode(opts *LoginOptions, config *core.CliConfig, msg *lo
 		if shouldRemoveLoginRequestedScope(result) {
 			cleanupRequestedScope()
 		}
-		return errs.NewAuthenticationError(errs.SubtypeUnknown, "authorization failed: %s", result.Message)
+		return output.ErrAuth("authorization failed: %s", result.Message)
 	}
 	defer cleanupRequestedScope()
 	if result.Token == nil {
-		return errs.NewAuthenticationError(errs.SubtypeTokenMissing, "authorization succeeded but no token returned")
+		return output.ErrAuth("authorization succeeded but no token returned")
 	}
 
 	// Get user info
 	log(msg.AuthSuccess)
 	sdk, err := f.LarkClient()
 	if err != nil {
-		return errs.NewInternalError(errs.SubtypeSDKError, "failed to get SDK: %v", err).WithCause(err)
+		return output.ErrAuth("failed to get SDK: %v", err)
 	}
 	openId, userName, err := getUserInfo(opts.Ctx, sdk, result.Token.AccessToken)
 	if err != nil {
-		return errs.NewAuthenticationError(errs.SubtypeUnknown, "failed to get user info: %v", err).WithCause(err)
+		return output.ErrAuth("failed to get user info: %v", err)
 	}
 
 	scopeSummary := loadLoginScopeSummary(config.AppID, openId, requestedScope, result.Token.Scope)
@@ -455,13 +442,13 @@ func authLoginPollDeviceCode(opts *LoginOptions, config *core.CliConfig, msg *lo
 		GrantedAt:        now,
 	}
 	if err := larkauth.SetStoredToken(storedToken); err != nil {
-		return errs.NewInternalError(errs.SubtypeSDKError, "failed to save token: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "internal", "failed to save token: %v", err)
 	}
 
 	// Update config — overwrite Users to single user, clean old tokens
 	if err := syncLoginUserToProfile(config.ProfileName, config.AppID, openId, userName); err != nil {
 		_ = larkauth.RemoveStoredToken(config.AppID, openId)
-		return errs.NewInternalError(errs.SubtypeSDKError, "failed to update login profile: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "internal", "failed to update login profile: %v", err)
 	}
 
 	if issue := ensureRequestedScopesGranted(requestedScope, result.Token.Scope, msg, scopeSummary); issue != nil {
@@ -476,18 +463,18 @@ func authLoginPollDeviceCode(opts *LoginOptions, config *core.CliConfig, msg *lo
 func syncLoginUserToProfile(profileName, appID, openID, userName string) error {
 	multi, err := core.LoadMultiAppConfig()
 	if err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "load config: %v", err).WithCause(err)
+		return fmt.Errorf("load config: %w", err)
 	}
 
 	app := findProfileByName(multi, profileName)
 	if app == nil {
-		return errs.NewConfigError(errs.SubtypeNotConfigured, "profile %q not found in config", profileName)
+		return fmt.Errorf("profile %q not found in config", profileName)
 	}
 
 	oldUsers := append([]core.AppUser(nil), app.Users...)
 	app.Users = []core.AppUser{{UserOpenId: openID, UserName: userName}}
 	if err := core.SaveMultiAppConfig(multi); err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "save config: %v", err).WithCause(err)
+		return fmt.Errorf("save config: %w", err)
 	}
 
 	for _, oldUser := range oldUsers {

cmd/auth/login_interactive.go

@@ -10,7 +10,6 @@ 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"
@@ -92,11 +91,16 @@ func buildDomainMeta(name, lang string) domainMeta {
 			Description: desc,
 		}
 	}
-	// Fallback: read from the typed service spec (legacy)
+	// Fallback: read from from_meta spec (legacy)
+	meta := registry.LoadFromMeta(name)
 	dm := domainMeta{Name: name}
-	if svc, ok := registry.ServiceTyped(name); ok {
-		dm.Title = svc.Title
-		dm.Description = svc.Description
+	if meta != nil {
+		if t, ok := meta["title"].(string); ok {
+			dm.Title = t
+		}
+		if d, ok := meta["description"].(string); ok {
+			dm.Description = d
+		}
 	}
 	return dm
 }
@@ -158,7 +162,7 @@ func runInteractiveLogin(ios *cmdutil.IOStreams, lang string, msg *loginMsg, bra
 	}
 
 	if len(selectedDomains) == 0 {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "no domains selected").WithParam("--domain")
+		return nil, output.ErrValidation("no domains selected")
 	}
 
 	// Compute scope summary

cmd/auth/login_messages.go

@@ -3,8 +3,6 @@
 
 package auth
 
-import "github.com/larksuite/cli/internal/i18n"
-
 type loginMsg struct {
 	// Interactive UI (login_interactive.go)
 	SelectDomains   string
@@ -117,8 +115,8 @@ var loginMsgEn = &loginMsg{
 }
 
 // getLoginMsg returns the login message bundle for the given language.
-func getLoginMsg(lang i18n.Lang) *loginMsg {
-	if lang.IsEnglish() {
+func getLoginMsg(lang string) *loginMsg {
+	if lang == "en" {
 		return loginMsgEn
 	}
 	return loginMsgZh
@@ -128,5 +126,5 @@ func getLoginMsg(lang i18n.Lang) *loginMsg {
 // (not backed by from_meta service specs). Descriptions are now centralized in
 // service_descriptions.json.
 func getShortcutOnlyDomainNames() []string {
-	return []string{"base", "contact", "docs", "markdown", "apps", "note"}
+	return []string{"base", "contact", "docs", "markdown", "apps"}
 }

cmd/auth/login_messages_test.go

@@ -8,8 +8,6 @@ import (
 	"reflect"
 	"strings"
 	"testing"
-
-	"github.com/larksuite/cli/internal/i18n"
 )
 
 func TestGetLoginMsg_Zh(t *testing.T) {
@@ -33,7 +31,7 @@ func TestGetLoginMsg_En(t *testing.T) {
 }
 
 func TestGetLoginMsg_DefaultsToZh(t *testing.T) {
-	for _, lang := range []i18n.Lang{"", "fr_fr", "ja_jp", "unknown"} {
+	for _, lang := range []string{"", "fr", "ja", "unknown"} {
 		msg := getLoginMsg(lang)
 		if msg != loginMsgZh {
 			t.Errorf("getLoginMsg(%q) should default to zh", lang)
@@ -63,7 +61,7 @@ func assertLoginMsgAllFieldsNonEmpty(t *testing.T, msg *loginMsg, label string)
 }
 
 func TestLoginMsg_FormatStrings(t *testing.T) {
-	for _, lang := range []i18n.Lang{i18n.LangZhCN, i18n.LangEnUS} {
+	for _, lang := range []string{"zh", "en"} {
 		msg := getLoginMsg(lang)
 
 		// LoginSuccess should contain two %s placeholders (userName, openId)
@@ -104,10 +102,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 []i18n.Lang{i18n.LangZhCN, i18n.LangEnUS} {
+	for _, lang := range []string{"zh", "en"} {
 		hint := getLoginMsg(lang).AgentTimeoutHint
 		for _, want := range []string{"--no-wait", "--device-code", "turn"} {
-			if lang == i18n.LangZhCN && want == "turn" {
+			if lang == "zh" && want == "turn" {
 				want = "本轮"
 			}
 			if !strings.Contains(hint, want) {

cmd/auth/login_result.go

@@ -8,7 +8,6 @@ import (
 	"fmt"
 	"strings"
 
-	"github.com/larksuite/cli/errs"
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/output"
@@ -172,12 +171,25 @@ func handleLoginScopeIssue(opts *LoginOptions, msg *loginMsg, f *cmdutil.Factory
 			fmt.Fprintln(f.IOStreams.Out, string(b))
 			return output.ErrBare(output.ExitAuth)
 		}
-		return errs.NewPermissionError(errs.SubtypeMissingScope, "%s", issue.Message).
-			WithHint("%s", issue.Hint).
-			WithIdentity("user").
-			WithRequestedScopes(issue.Summary.Requested...).
-			WithGrantedScopes(issue.Summary.Granted...).
-			WithMissingScopes(issue.Summary.Missing...)
+		detail := map[string]interface{}{
+			"requested": issue.Summary.Requested,
+			"granted":   issue.Summary.Granted,
+			"missing":   issue.Summary.Missing,
+		}
+		// Legacy *output.ExitError producer: this literal predates the typed
+		// error contract introduced by errs/. New code MUST NOT construct
+		// *output.ExitError directly — missing-scope signals should move to
+		// *errs.PermissionError (with MissingScopes/ConsoleURL as typed
+		// extension fields) when the login flow migrates to typed errors.
+		return &output.ExitError{
+			Code: output.ExitAuth,
+			Detail: &output.ErrDetail{
+				Type:    "missing_scope",
+				Message: issue.Message,
+				Hint:    issue.Hint,
+				Detail:  detail,
+			},
+		}
 	}
 
 	fmt.Fprintln(f.IOStreams.ErrOut)

cmd/auth/login_result_test.go

@@ -1,61 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package auth
-
-import (
-	"errors"
-	"reflect"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-)
-
-// TestHandleLoginScopeIssue_FailedJSON_PreservesScopeTriple asserts that the
-// failed-login JSON branch (loginSucceeded == false, opts.JSON == true) wires
-// requested + granted + missing scopes into the typed *PermissionError
-// envelope. Consumers need the full triple to render actionable diagnostics,
-// not just the missing set.
-func TestHandleLoginScopeIssue_FailedJSON_PreservesScopeTriple(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-
-	requested := []string{"docx:document", "im:message:send"}
-	granted := []string{"docx:document"}
-	missing := []string{"im:message:send"}
-
-	err := handleLoginScopeIssue(
-		&LoginOptions{JSON: true},
-		getLoginMsg("en"),
-		f,
-		&loginScopeIssue{
-			Message: "scope insufficient",
-			Hint:    "re-login with --scope im:message:send",
-			Summary: &loginScopeSummary{
-				Requested: requested,
-				Granted:   granted,
-				Missing:   missing,
-			},
-		},
-		"", // openId empty -> loginSucceeded = false
-		"tester",
-	)
-
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-	var permErr *errs.PermissionError
-	if !errors.As(err, &permErr) {
-		t.Fatalf("expected *errs.PermissionError, got %T: %v", err, err)
-	}
-	if !reflect.DeepEqual(permErr.RequestedScopes, requested) {
-		t.Errorf("RequestedScopes = %v, want %v", permErr.RequestedScopes, requested)
-	}
-	if !reflect.DeepEqual(permErr.GrantedScopes, granted) {
-		t.Errorf("GrantedScopes = %v, want %v", permErr.GrantedScopes, granted)
-	}
-	if !reflect.DeepEqual(permErr.MissingScopes, missing) {
-		t.Errorf("MissingScopes = %v, want %v", permErr.MissingScopes, missing)
-	}
-}

cmd/auth/login_test.go

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

cmd/auth/logout.go

@@ -8,7 +8,6 @@ import (
 
 	"github.com/spf13/cobra"
 
-	"github.com/larksuite/cli/errs"
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
@@ -18,7 +17,6 @@ import (
 // LogoutOptions holds all inputs for auth logout.
 type LogoutOptions struct {
 	Factory *cmdutil.Factory
-	JSON    bool
 }
 
 // NewCmdAuthLogout creates the auth logout subcommand.
@@ -35,7 +33,6 @@ 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
@@ -46,64 +43,24 @@ 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 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
+		return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 	}
 	output.PrintSuccess(f.IOStreams.ErrOut, "Logged out")
 	return nil

cmd/auth/logout_test.go

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

@@ -13,8 +13,8 @@ import (
 	"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/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/internal/vfs"
 )
@@ -63,7 +63,7 @@ For ASCII output, the result is printed to stdout with fixed size.`,
 // runQRCode executes the auth qrcode command.
 func runQRCode(opts *QRCodeOptions) error {
 	if opts.URL == "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "url is required").WithParam("--url")
+		return output.Errorf(output.ExitValidation, "missing_url", "url is required")
 	}
 
 	if opts.ASCII {
@@ -75,20 +75,20 @@ func runQRCode(opts *QRCodeOptions) error {
 	}
 
 	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")
+		return output.Errorf(output.ExitValidation, "missing_output", "output file path is required for PNG mode. Use --output or -o flag to specify the output file path.")
 	}
 
 	if opts.Size < 32 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "size must be at least 32, got %d", opts.Size).WithParam("--size")
+		return output.Errorf(output.ExitValidation, "invalid_size", fmt.Sprintf("size must be at least 32, got %d", opts.Size))
 	}
 
 	if opts.Size > 1024 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "size must be at most 1024, got %d", opts.Size).WithParam("--size")
+		return output.Errorf(output.ExitValidation, "invalid_size", fmt.Sprintf("size must be at most 1024, got %d", opts.Size))
 	}
 
 	safePath, err := validate.SafeOutputPath(opts.Output)
 	if err != nil {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe output path: %s", err).WithParam("--output").WithCause(err)
+		return output.ErrValidation("unsafe output path: %s", err)
 	}
 
 	if err := generateImageQRCode(opts.URL, opts.Size, safePath); err != nil {
@@ -108,7 +108,7 @@ func runQRCode(opts *QRCodeOptions) error {
 	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 output.Errorf(output.ExitInternal, "internal", "failed to write output: %v", err)
 	}
 
 	return nil
@@ -118,12 +118,12 @@ func runQRCode(opts *QRCodeOptions) error {
 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)
+		return output.Errorf(output.ExitInternal, "encode_error", fmt.Sprintf("failed to encode QR code: %v", err))
 	}
 
 	err = vfs.WriteFile(outputPath, png, 0644)
 	if err != nil {
-		return errs.NewInternalError(errs.SubtypeSDKError, "failed to write QR code to %s: %v", outputPath, err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "write_error", fmt.Sprintf("failed to write QR code to %s: %v", outputPath, err))
 	}
 
 	return nil
@@ -133,7 +133,7 @@ func generateImageQRCode(url string, size int, outputPath string) error {
 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)
+		return output.Errorf(output.ExitInternal, "encode_error", fmt.Sprintf("failed to create QR code: %v", err))
 	}
 
 	fmt.Fprint(w, q.ToSmallString(false))

cmd/auth/qrcode_test.go

@@ -5,6 +5,7 @@ package auth
 
 import (
 	"encoding/json"
+	"errors"
 	"io"
 	"os"
 	"path/filepath"
@@ -170,15 +171,29 @@ func TestNewCmdAuthQRCode_HelpText(t *testing.T) {
 
 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)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+	}
+	if exitErr.Code != output.ExitValidation {
+		t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
+	}
+	if exitErr.Detail.Type != "missing_url" {
+		t.Errorf("error type = %q, want %q", exitErr.Detail.Type, "missing_url")
 	}
 }
 
 func TestRunQRCode_MissingOutput(t *testing.T) {
 	err := runQRCode(&QRCodeOptions{URL: "https://example.com", Size: 256})
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", gotCode, output.ExitValidation)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+	}
+	if exitErr.Code != output.ExitValidation {
+		t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
+	}
+	if exitErr.Detail.Type != "missing_output" {
+		t.Errorf("error type = %q, want %q", exitErr.Detail.Type, "missing_output")
 	}
 }
 
@@ -188,8 +203,15 @@ func TestRunQRCode_InvalidSize(t *testing.T) {
 		Size:   16,
 		Output: "qr.png",
 	})
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", gotCode, output.ExitValidation)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+	}
+	if exitErr.Code != output.ExitValidation {
+		t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
+	}
+	if exitErr.Detail.Type != "invalid_size" {
+		t.Errorf("error type = %q, want %q", exitErr.Detail.Type, "invalid_size")
 	}
 }
 
@@ -199,8 +221,15 @@ func TestRunQRCode_SizeTooLarge(t *testing.T) {
 		Size:   2048,
 		Output: "qr.png",
 	})
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", gotCode, output.ExitValidation)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+	}
+	if exitErr.Code != output.ExitValidation {
+		t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
+	}
+	if exitErr.Detail.Type != "invalid_size" {
+		t.Errorf("error type = %q, want %q", exitErr.Detail.Type, "invalid_size")
 	}
 }
 
@@ -210,8 +239,12 @@ func TestRunQRCode_UnsafeOutputPath(t *testing.T) {
 		Size:   256,
 		Output: "/etc/passwd",
 	})
-	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitValidation {
-		t.Errorf("exit code = %d, want %d", gotCode, output.ExitValidation)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+	}
+	if exitErr.Code != output.ExitValidation {
+		t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
 	}
 }
 
@@ -296,8 +329,15 @@ func TestGenerateImageQRCode_WriteError(t *testing.T) {
 	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)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+	}
+	if exitErr.Code != output.ExitInternal {
+		t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitInternal)
+	}
+	if exitErr.Detail.Type != "write_error" {
+		t.Errorf("error type = %q, want %q", exitErr.Detail.Type, "write_error")
 	}
 }
 
@@ -318,7 +358,11 @@ func TestGenerateASCIIQRCode_EmptyString(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected error for empty string")
 	}
-	if err == nil {
-		t.Fatal("expected error, got nil")
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+	}
+	if exitErr.Detail.Type != "encode_error" {
+		t.Errorf("error type = %q, want %q", exitErr.Detail.Type, "encode_error")
 	}
 }

cmd/auth/scopes.go

@@ -9,7 +9,6 @@ import (
 
 	"github.com/spf13/cobra"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/output"
 )
@@ -19,7 +18,6 @@ type ScopesOptions struct {
 	Factory *cmdutil.Factory
 	Ctx     context.Context
 	Format  string
-	JSON    bool
 }
 
 // NewCmdAuthScopes creates the auth scopes subcommand.
@@ -31,9 +29,6 @@ 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)
 			}
@@ -42,7 +37,6 @@ func NewCmdAuthScopes(f *cmdutil.Factory, runF func(*ScopesOptions) error) *cobr
 	}
 
 	cmd.Flags().StringVar(&opts.Format, "format", "json", "output format: json (default) | pretty")
-	cmd.Flags().BoolVar(&opts.JSON, "json", false, "structured JSON output")
 	cmdutil.SetRisk(cmd, "read")
 
 	return cmd
@@ -56,23 +50,11 @@ func authScopesRun(opts *ScopesOptions) error {
 		return err
 	}
 	fmt.Fprintf(f.IOStreams.ErrOut, "Querying app scopes...\n\n")
-	appInfo, err := getAppInfoFn(opts.Ctx, f, config.AppID)
+	appInfo, err := getAppInfo(opts.Ctx, f, config.AppID)
 	if err != nil {
-		// Discriminate by error type so transport / parse failures are not
-		// reclassified as PermissionError(MissingScope) — re-auth does not
-		// fix network / 5xx / JSON parse errors and misclassifying them
-		// here would mislead agents into re-auth loops.
-		//   - typed errors pass through unchanged
-		//   - bare errors become InternalError(SubtypeSDKError) with Cause
-		//     preserved so callers (errors.Is) can still see the underlying
-		//     transport/parse failure.
-		// Genuine permission failures are surfaced from appInfo *content*,
-		// not from this transport-level error path.
-		if errs.IsTyped(err) {
-			return err
-		}
-		return errs.NewInternalError(errs.SubtypeSDKError,
-			"failed to get app scope info: %v", err).WithCause(err)
+		return output.ErrWithHint(output.ExitAPI, "permission",
+			fmt.Sprintf("failed to get app scope info: %v", err),
+			"ensure the app has enabled the application:application:self_manage scope.")
 	}
 	if opts.Format == "pretty" {
 		fmt.Fprintf(f.IOStreams.ErrOut, "App ID: %s\n", config.AppID)

cmd/auth/scopes_test.go

@@ -1,121 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package auth
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-)
-
-// stubGetAppInfoErr swaps getAppInfoFn for the duration of t so authScopesRun
-// observes a fixed error from the dependency. t.Cleanup restores the prior
-// value so tests cannot leak through the package-level seam.
-func stubGetAppInfoErr(t *testing.T, errToReturn error) {
-	t.Helper()
-	prev := getAppInfoFn
-	getAppInfoFn = func(ctx context.Context, f *cmdutil.Factory, appId string) (*appInfo, error) {
-		return nil, errToReturn
-	}
-	t.Cleanup(func() { getAppInfoFn = prev })
-}
-
-// scopesTestFactory builds a Factory + ScopesOptions pair sufficient to drive
-// authScopesRun. Config has a non-empty AppID so we get past the config gate
-// and reach the getAppInfoFn call.
-func scopesTestFactory(t *testing.T) *ScopesOptions {
-	t.Helper()
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID:     "test-app",
-		AppSecret: "test-secret",
-		Brand:     core.BrandFeishu,
-	})
-	return &ScopesOptions{
-		Factory: f,
-		Ctx:     context.Background(),
-		Format:  "json",
-	}
-}
-
-// TestAuthScopesRun_NetworkErrorPassedThrough pins that a typed NetworkError
-// surfaced by the dependency is not re-classified as PermissionError —
-// re-auth does not fix DNS / transport failures and blanket-wrapping them
-// would mislead agents into infinite re-auth loops.
-func TestAuthScopesRun_NetworkErrorPassedThrough(t *testing.T) {
-	netErr := errs.NewNetworkError(errs.SubtypeNetworkDNS, "DNS lookup failed")
-	stubGetAppInfoErr(t, netErr)
-
-	err := authScopesRun(scopesTestFactory(t))
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-
-	var permErr *errs.PermissionError
-	if errors.As(err, &permErr) {
-		t.Errorf("network failure must not be classified as PermissionError; got %v", permErr)
-	}
-	var gotNet *errs.NetworkError
-	if !errors.As(err, &gotNet) {
-		t.Fatalf("network failure not preserved through authScopesRun; got %T: %v", err, err)
-	}
-	if gotNet != netErr {
-		t.Errorf("typed network error should pass through identity-stable; got %p, want %p", gotNet, netErr)
-	}
-}
-
-// TestAuthScopesRun_PermissionErrorPassedThrough pins that typed permission
-// failures from the dependency also pass through — IsTyped() must not single
-// out one category.
-func TestAuthScopesRun_PermissionErrorPassedThrough(t *testing.T) {
-	permErr := errs.NewPermissionError(errs.SubtypeMissingScope, "scope X missing").
-		WithMissingScopes("im:message")
-	stubGetAppInfoErr(t, permErr)
-
-	err := authScopesRun(scopesTestFactory(t))
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-	var got *errs.PermissionError
-	if !errors.As(err, &got) {
-		t.Fatalf("expected *PermissionError pass-through, got %T: %v", err, err)
-	}
-	if got != permErr {
-		t.Errorf("typed permission error should pass through identity-stable; got %p, want %p", got, permErr)
-	}
-}
-
-// TestAuthScopesRun_BareErrorWrappedAsInternal pins the unclassified branch:
-// a bare error (e.g. json.Unmarshal failure inside getAppInfo) surfaces as
-// *InternalError{SubtypeSDKError} with the original error preserved on
-// Cause so errors.Is still walks to it.
-func TestAuthScopesRun_BareErrorWrappedAsInternal(t *testing.T) {
-	bareErr := fmt.Errorf("failed to parse response: unexpected EOF")
-	stubGetAppInfoErr(t, bareErr)
-
-	err := authScopesRun(scopesTestFactory(t))
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-
-	var permErr *errs.PermissionError
-	if errors.As(err, &permErr) {
-		t.Errorf("bare getAppInfo error must not be classified as PermissionError; got %v", permErr)
-	}
-
-	var intErr *errs.InternalError
-	if !errors.As(err, &intErr) {
-		t.Fatalf("expected *InternalError, got %T: %v", err, err)
-	}
-	if intErr.Subtype != errs.SubtypeSDKError {
-		t.Errorf("InternalError.Subtype = %q, want %q", intErr.Subtype, errs.SubtypeSDKError)
-	}
-	if !errors.Is(err, bareErr) {
-		t.Error("InternalError must carry bareErr via WithCause so errors.Is walks to it")
-	}
-}

cmd/auth/status.go

@@ -17,7 +17,6 @@ import (
 type StatusOptions struct {
 	Factory *cmdutil.Factory
 	Verify  bool
-	JSON    bool
 }
 
 // NewCmdAuthStatus creates the auth status subcommand.
@@ -36,7 +35,6 @@ 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
@@ -63,6 +61,7 @@ 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)
 
@@ -87,6 +86,29 @@ 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,7 +6,6 @@ package cmd
 import (
 	"context"
 	"io"
-	"io/fs"
 
 	"github.com/larksuite/cli/cmd/api"
 	"github.com/larksuite/cli/cmd/auth"
@@ -17,7 +16,6 @@ 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"
@@ -53,18 +51,6 @@ 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
@@ -117,7 +103,6 @@ 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",
@@ -132,13 +117,6 @@ 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) {
@@ -155,7 +133,6 @@ 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

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

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

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

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

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

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

cmd/config/bind_messages.go

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

cmd/config/bind_test.go

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

cmd/config/binder.go

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

cmd/config/binder_test.go

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

cmd/config/config.go

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

cmd/config/config_test.go

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

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 errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid identity type %q, valid values: user | bot | auto", value)
+				return output.ErrValidation("invalid identity type %q, valid values: user | bot | auto", value)
 			}
 
 			app.DefaultAs = core.Identity(value)
 			if err := core.SaveMultiAppConfig(multi); err != nil {
-				return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+				return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 			}
 			fmt.Fprintf(f.IOStreams.ErrOut, "Default identity set to: %s\n", value)
 			return nil

cmd/config/init.go

@@ -15,11 +15,9 @@ import (
 	"github.com/charmbracelet/huh"
 	"github.com/spf13/cobra"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/output"
 )
@@ -33,13 +31,9 @@ type ConfigInitOptions struct {
 	AppSecretStdin bool   // read app-secret from stdin (avoids process list exposure)
 	Brand          string
 	New            bool
-
-	Lang         string // raw --lang (string for cobra); normalized to canonical/"" in validateInitLang
-	langExplicit bool   // true when --lang was explicitly passed
-
-	UILang i18n.Lang // TUI display language (picker-only); intentionally separate from --lang
-
-	ProfileName string // when set, create/update a named profile instead of replacing Apps[0]
+	Lang           string
+	langExplicit   bool   // true when --lang was explicitly passed
+	ProfileName    string // when set, create/update a named profile instead of replacing Apps[0]
 
 	// ForceInit overrides the agent-workspace guard. Without it, running
 	// init under OPENCLAW_HOME / HERMES_HOME refuses and points the caller
@@ -51,7 +45,7 @@ type ConfigInitOptions struct {
 
 // NewCmdConfigInit creates the config init subcommand.
 func NewCmdConfigInit(f *cmdutil.Factory, runF func(*ConfigInitOptions) error) *cobra.Command {
-	opts := &ConfigInitOptions{Factory: f, UILang: i18n.LangZhCN}
+	opts := &ConfigInitOptions{Factory: f}
 
 	cmd := &cobra.Command{
 		Use:   "init",
@@ -69,9 +63,6 @@ if the user explicitly wants a separate app inside the Agent workspace.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.Ctx = cmd.Context()
 			opts.langExplicit = cmd.Flags().Changed("lang")
-			if err := validateInitLang(opts); err != nil {
-				return err
-			}
 			if err := guardAgentWorkspace(opts); err != nil {
 				return err
 			}
@@ -86,7 +77,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", "", "language preference (e.g. zh or zh_cn)")
+	cmd.Flags().StringVar(&opts.Lang, "lang", "zh", "language for interactive prompts (zh or en)")
 	cmd.Flags().StringVar(&opts.ProfileName, "name", "", "create or update a named profile (append instead of replace)")
 	cmd.Flags().BoolVar(&opts.ForceInit, "force-init", false, "allow init inside an Agent workspace (OPENCLAW_HOME / HERMES_HOME); use config bind instead unless you really want a separate app")
 	cmdutil.SetRisk(cmd, "write")
@@ -94,25 +85,6 @@ 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.
@@ -160,7 +132,7 @@ func cleanupOldConfig(existing *core.MultiAppConfig, f *cmdutil.Factory, skipApp
 func saveAsOnlyApp(appId string, secret core.SecretInput, brand core.LarkBrand, lang string) error {
 	config := &core.MultiAppConfig{
 		Apps: []core.AppConfig{{
-			AppId: appId, AppSecret: secret, Brand: brand, Lang: i18n.Lang(lang), Users: []core.AppUser{},
+			AppId: appId, AppSecret: secret, Brand: brand, Lang: lang, Users: []core.AppUser{},
 		}},
 	}
 	return core.SaveMultiAppConfig(config)
@@ -174,13 +146,7 @@ func saveInitConfig(profileName string, existing *core.MultiAppConfig, f *cmduti
 		return saveAsProfile(existing, f.Keychain, profileName, appId, secret, brand, lang)
 	}
 	cleanupOldConfig(existing, f, appId)
-	var prior i18n.Lang
-	if existing != nil {
-		if app := existing.CurrentAppConfig(""); app != nil {
-			prior = app.Lang
-		}
-	}
-	return saveAsOnlyApp(appId, secret, brand, string(preferredLang(i18n.Lang(lang), prior)))
+	return saveAsOnlyApp(appId, secret, brand, lang)
 }
 
 // saveAsProfile appends or updates a named profile in the config.
@@ -201,10 +167,11 @@ func saveAsProfile(existing *core.MultiAppConfig, kc keychain.KeychainAccess, pr
 			}
 			multi.Apps[idx].Users = []core.AppUser{}
 		}
+		// Update existing profile
 		multi.Apps[idx].AppId = appId
 		multi.Apps[idx].AppSecret = secret
 		multi.Apps[idx].Brand = brand
-		multi.Apps[idx].Lang = preferredLang(i18n.Lang(lang), multi.Apps[idx].Lang)
+		multi.Apps[idx].Lang = lang
 	} else {
 		if findAppIndexByAppID(multi, profileName) >= 0 {
 			return fmt.Errorf("profile name %q conflicts with existing appId", profileName)
@@ -215,7 +182,7 @@ func saveAsProfile(existing *core.MultiAppConfig, kc keychain.KeychainAccess, pr
 			AppId:     appId,
 			AppSecret: secret,
 			Brand:     brand,
-			Lang:      i18n.Lang(lang),
+			Lang:      lang,
 			Users:     []core.AppUser{},
 		})
 	}
@@ -246,29 +213,9 @@ func findAppIndexByAppID(multi *core.MultiAppConfig, appID string) int {
 	return -1
 }
 
-// wrapUpdateExistingProfileErr classifies the error returned by
-// updateExistingProfileWithoutSecret. Typed errors (e.g. *errs.ValidationError
-// for blank-input) pass through unchanged so their exit code semantics
-// survive; legacy *output.ExitError also passes through; everything else
-// (filesystem, keychain, etc.) is wrapped as InternalError.
-func wrapUpdateExistingProfileErr(err error) error {
-	if err == nil {
-		return nil
-	}
-	if errs.IsTyped(err) {
-		return err
-	}
-	var exitErr *output.ExitError
-	if errors.As(err, &exitErr) {
-		return err
-	}
-	return errs.NewInternalError(errs.SubtypeSDKError, "failed to save config: %v", err).WithCause(err)
-}
-
 func updateExistingProfileWithoutSecret(existing *core.MultiAppConfig, profileName, appID string, brand core.LarkBrand, lang string) error {
 	if existing == nil {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "App Secret cannot be empty for new configuration").
-			WithParam("--app-secret")
+		return output.ErrValidation("App Secret cannot be empty for new configuration")
 	}
 
 	var app *core.AppConfig
@@ -276,25 +223,22 @@ func updateExistingProfileWithoutSecret(existing *core.MultiAppConfig, profileNa
 		if idx := findProfileIndexByName(existing, profileName); idx >= 0 {
 			app = &existing.Apps[idx]
 		} else {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "App Secret cannot be empty for new profile").
-				WithParam("--app-secret")
+			return output.ErrValidation("App Secret cannot be empty for new profile")
 		}
 	} else {
 		app = existing.CurrentAppConfig("")
 		if app == nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "App Secret cannot be empty for new configuration").
-				WithParam("--app-secret")
+			return output.ErrValidation("App Secret cannot be empty for new configuration")
 		}
 	}
 
 	if app.AppId != appID {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "App Secret cannot be empty when changing App ID").
-			WithParam("--app-secret")
+		return output.ErrValidation("App Secret cannot be empty when changing App ID")
 	}
 
 	app.AppId = appID
 	app.Brand = brand
-	app.Lang = preferredLang(i18n.Lang(lang), app.Lang)
+	app.Lang = lang
 	return core.SaveMultiAppConfig(existing)
 }
 
@@ -306,13 +250,13 @@ func configInitRun(opts *ConfigInitOptions) error {
 		scanner := bufio.NewScanner(f.IOStreams.In)
 		if !scanner.Scan() {
 			if err := scanner.Err(); err != nil {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "failed to read secret from stdin: %v", err).WithCause(err)
+				return output.ErrValidation("failed to read secret from stdin: %v", err)
 			}
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "stdin is empty, expected app secret")
+			return output.ErrValidation("stdin is empty, expected app secret")
 		}
 		opts.appSecret = strings.TrimSpace(scanner.Text())
 		if opts.appSecret == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "app secret read from stdin is empty")
+			return output.ErrValidation("app secret read from stdin is empty")
 		}
 	}
 
@@ -324,7 +268,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 	// Validate --profile name if set
 	if opts.ProfileName != "" {
 		if err := core.ValidateProfileName(opts.ProfileName); err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "%v", err).WithCause(err)
+			return output.ErrValidation("%v", err)
 		}
 	}
 
@@ -333,36 +277,35 @@ func configInitRun(opts *ConfigInitOptions) error {
 		brand := parseBrand(opts.Brand)
 		secret, err := core.ForStorage(opts.AppID, core.PlainSecret(opts.appSecret), f.Keychain)
 		if err != nil {
-			return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
+			return output.Errorf(output.ExitInternal, "internal", "%v", err)
 		}
 		if err := saveInitConfig(opts.ProfileName, existing, f, opts.AppID, secret, brand, opts.Lang); err != nil {
-			return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+			return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 		}
 		output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf("Configuration saved to %s", core.GetConfigPath()))
-		printLangPreferenceConfirmation(opts)
 		output.PrintJson(f.IOStreams.Out, map[string]interface{}{"appId": opts.AppID, "appSecret": "****", "brand": brand})
-		if err := runProbe(opts.Ctx, f, opts.AppID, opts.appSecret, brand); err != nil {
-			return err
-		}
 		return nil
 	}
 
-	// For interactive modes, prompt language selection if --lang was not explicitly set.
-	// Picker offers 2 options (中文 / English) and drives BOTH opts.Lang
-	// (preference) and opts.UILang (TUI rendering).
+	// For interactive modes, prompt language selection if --lang was not explicitly set
 	if f.IOStreams.IsTerminal && !opts.langExplicit && !opts.hasAnyNonInteractiveFlag() {
-		lang, err := promptLangSelection()
+		savedLang := ""
+		if existing != nil {
+			if app := existing.CurrentAppConfig(""); app != nil {
+				savedLang = app.Lang
+			}
+		}
+		lang, err := promptLangSelection(savedLang)
 		if err != nil {
 			if err == huh.ErrUserAborted {
 				return output.ErrBare(1)
 			}
-			return output.Errorf(output.ExitInternal, "internal", "language selection failed: %v", err)
+			return err
 		}
-		opts.Lang = string(lang)
-		opts.UILang = lang
+		opts.Lang = lang
 	}
 
-	msg := getInitMsg(opts.UILang)
+	msg := getInitMsg(opts.Lang)
 
 	// Mode 3: Create new app directly (--new)
 	if opts.New {
@@ -371,21 +314,17 @@ func configInitRun(opts *ConfigInitOptions) error {
 			return err
 		}
 		if result == nil {
-			return errs.NewInternalError(errs.SubtypeSDKError, "app creation returned no result")
+			return output.ErrValidation("app creation returned no result")
 		}
 		existing, _ := core.LoadMultiAppConfig()
 		secret, err := core.ForStorage(result.AppID, core.PlainSecret(result.AppSecret), f.Keychain)
 		if err != nil {
-			return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
+			return output.Errorf(output.ExitInternal, "internal", "%v", err)
 		}
 		if err := saveInitConfig(opts.ProfileName, existing, f, result.AppID, secret, result.Brand, opts.Lang); err != nil {
-			return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+			return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 		}
-		printLangPreferenceConfirmation(opts)
 		output.PrintJson(f.IOStreams.Out, map[string]interface{}{"appId": result.AppID, "appSecret": "****", "brand": result.Brand})
-		if err := runProbe(opts.Ctx, f, result.AppID, result.AppSecret, result.Brand); err != nil {
-			return err
-		}
 		return nil
 	}
 
@@ -396,8 +335,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 			return err
 		}
 		if result == nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "App ID and App Secret cannot be empty").
-				WithParam("--app-id")
+			return output.ErrValidation("App ID and App Secret cannot be empty")
 		}
 
 		existing, _ := core.LoadMultiAppConfig()
@@ -406,36 +344,34 @@ func configInitRun(opts *ConfigInitOptions) error {
 			// New secret provided (either from "create" or "existing" with input)
 			secret, err := core.ForStorage(result.AppID, core.PlainSecret(result.AppSecret), f.Keychain)
 			if err != nil {
-				return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
+				return output.Errorf(output.ExitInternal, "internal", "%v", err)
 			}
 			if err := saveInitConfig(opts.ProfileName, existing, f, result.AppID, secret, result.Brand, opts.Lang); err != nil {
-				return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+				return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 			}
 		} else if result.Mode == "existing" && result.AppID != "" {
 			// Existing app with unchanged secret — update app ID and brand only
-			if err := wrapUpdateExistingProfileErr(updateExistingProfileWithoutSecret(existing, opts.ProfileName, result.AppID, result.Brand, opts.Lang)); err != nil {
-				return err
+			if err := updateExistingProfileWithoutSecret(existing, opts.ProfileName, result.AppID, result.Brand, opts.Lang); err != nil {
+				// Deprecated: legacy *output.ExitError passthrough; removed after typed migration.
+				var exitErr *output.ExitError
+				if errors.As(err, &exitErr) {
+					return err
+				}
+				return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 			}
 		} else {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "App ID and App Secret cannot be empty").
-				WithParam("--app-id")
+			return output.ErrValidation("App ID and App Secret cannot be empty")
 		}
 
 		if result.Mode == "existing" {
 			output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf(msg.ConfigSaved, result.AppID))
 		}
-		printLangPreferenceConfirmation(opts)
-		if result.AppSecret != "" {
-			if err := runProbe(opts.Ctx, f, result.AppID, result.AppSecret, result.Brand); err != nil {
-				return err
-			}
-		}
 		return nil
 	}
 
 	// Non-terminal: cannot run interactive mode, guide user to --new
 	if !f.IOStreams.IsTerminal {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "config init requires a terminal for interactive mode. Run with --new to create a new app:\n  lark-cli config init --new\nThis command blocks until setup is complete and outputs a verification URL. Run it in the background, then retrieve the URL from its output.")
+		return output.ErrValidation("config init requires a terminal for interactive mode. Run with --new to create a new app:\n  lark-cli config init --new\nThis command blocks until setup is complete and outputs a verification URL. Run it in the background, then retrieve the URL from its output.")
 	}
 
 	// Mode 5: Legacy interactive (readline fallback)
@@ -463,7 +399,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 	}
 	appIdInput, err := readLine(prompt)
 	if err != nil {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithCause(err)
+		return output.ErrValidation("%s", err)
 	}
 
 	prompt = "App Secret"
@@ -472,7 +408,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 	}
 	appSecretInput, err := readLine(prompt)
 	if err != nil {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithCause(err)
+		return output.ErrValidation("%s", err)
 	}
 
 	prompt = "Brand (lark/feishu)"
@@ -483,7 +419,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 	}
 	brandInput, err := readLine(prompt)
 	if err != nil {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithCause(err)
+		return output.ErrValidation("%s", err)
 	}
 
 	resolvedAppId := appIdInput
@@ -505,23 +441,16 @@ func configInitRun(opts *ConfigInitOptions) error {
 	}
 
 	if resolvedAppId == "" || resolvedSecret.IsZero() {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "App ID and App Secret cannot be empty").
-			WithParam("--app-id")
+		return output.ErrValidation("App ID and App Secret cannot be empty")
 	}
 
 	storedSecret, err := core.ForStorage(resolvedAppId, resolvedSecret, f.Keychain)
 	if err != nil {
-		return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "internal", "%v", err)
 	}
 	if err := saveInitConfig(opts.ProfileName, existing, f, resolvedAppId, storedSecret, parseBrand(resolvedBrand), opts.Lang); err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 	}
 	output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf("Configuration saved to %s", core.GetConfigPath()))
-	printLangPreferenceConfirmation(opts)
-	if appSecretInput != "" {
-		if err := runProbe(opts.Ctx, f, resolvedAppId, appSecretInput, parseBrand(resolvedBrand)); err != nil {
-			return err
-		}
-	}
 	return nil
 }

cmd/config/init_interactive.go

@@ -6,17 +6,16 @@ package config
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"github.com/charmbracelet/huh"
 	"github.com/larksuite/cli/internal/build"
 	qrcode "github.com/skip2/go-qrcode"
 
-	"github.com/larksuite/cli/errs"
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/transport"
 )
 
 // configInitResult holds the result of the interactive config init flow.
@@ -126,16 +125,8 @@ func runExistingAppForm(f *cmdutil.Factory, msg *initMsg) (*configInitResult, er
 		}, nil
 	}
 
-	switch {
-	case appID == "" && appSecret == "":
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "App ID and App Secret cannot be empty").
-			WithParam("--app-id")
-	case appID == "":
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "App ID cannot be empty").
-			WithParam("--app-id")
-	case appSecret == "":
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "App Secret cannot be empty").
-			WithParam("--app-secret")
+	if appID == "" || appSecret == "" {
+		return nil, output.ErrValidation("App ID and App Secret cannot be empty")
 	}
 
 	return &configInitResult{
@@ -177,12 +168,10 @@ func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride cor
 	}
 
 	// Step 1: Request app registration (begin)
-	// Use the shared proxy-plugin-aware transport so registration traffic is not
-	// a bypass of proxy plugin mode.
-	httpClient := transport.NewHTTPClient(0)
+	httpClient := &http.Client{}
 	authResp, err := larkauth.RequestAppRegistration(httpClient, larkBrand, f.IOStreams.ErrOut)
 	if err != nil {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "app registration failed: %v", err).WithCause(err)
+		return nil, output.ErrAuth("app registration failed: %v", err)
 	}
 
 	// Step 2: Build and display verification URL + QR code
@@ -210,7 +199,7 @@ func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride cor
 	}
 	result, err := larkauth.PollAppRegistration(ctx, httpClient, core.BrandFeishu, authResp.DeviceCode, authResp.Interval, authResp.ExpiresIn, f.IOStreams.ErrOut)
 	if err != nil {
-		return nil, errs.NewAuthenticationError(errs.SubtypeUnknown, "%v", err).WithCause(err)
+		return nil, output.ErrAuth("%v", err)
 	}
 
 	// Step 4: Handle Lark brand special case
@@ -219,12 +208,12 @@ func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride cor
 		// fmt.Fprintf(f.IOStreams.ErrOut, "%s\n", msg.DetectedLarkTenant)
 		result, err = larkauth.PollAppRegistration(ctx, httpClient, core.BrandLark, authResp.DeviceCode, authResp.Interval, authResp.ExpiresIn, f.IOStreams.ErrOut)
 		if err != nil {
-			return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "lark endpoint retry failed: %v", err).WithCause(err)
+			return nil, output.ErrAuth("lark endpoint retry failed: %v", err)
 		}
 	}
 
 	if result.ClientID == "" || result.ClientSecret == "" {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "app registration succeeded but missing client_id or client_secret")
+		return nil, output.ErrAuth("app registration succeeded but missing client_id or client_secret")
 	}
 
 	// Determine final brand from response

cmd/config/init_messages.go

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

cmd/config/init_messages_test.go

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

cmd/config/init_probe.go

@@ -1,92 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package config
-
-import (
-	"bytes"
-	"context"
-	"fmt"
-	"io"
-	"net/http"
-	"time"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/build"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/credential"
-)
-
-// probeTimeout is the total wall-clock budget for the credential probe step
-// (covering both TAT acquisition and the subsequent probe request).
-const probeTimeout = 3 * time.Second
-
-// runProbe runs a best-effort credential validation after config init has
-// persisted the App ID and App Secret. It returns a non-nil error only for a
-// deterministic credential-rejection signal; every other outcome returns nil
-// so that valid configurations and transient/upstream noise never block the
-// command.
-//
-// The function performs up to two HTTP calls in series, bounded by
-// probeTimeout:
-//
-//  1. A TAT request using the just-saved credentials. credential.FetchTAT
-//     returns a typed errs.* error (via the shared classifyTATResponseCode)
-//     only when the 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

@@ -1,287 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package config
-
-import (
-	"bytes"
-	"context"
-	"errors"
-	"io"
-	"net/http"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/build"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-)
-
-// fakeRT routes requests to per-path handlers and records what it saw.
-type fakeRT struct {
-	tatHandler   func(req *http.Request) (*http.Response, error)
-	probeHandler func(req *http.Request) (*http.Response, error)
-	tatCalls     int
-	probeCalls   int
-	probeReq     *http.Request
-	probeBody    string
-}
-
-func (f *fakeRT) RoundTrip(req *http.Request) (*http.Response, error) {
-	switch {
-	case strings.HasSuffix(req.URL.Path, "/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

@@ -1,133 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package config
-
-import (
-	"errors"
-	"fmt"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// updateExistingProfileWithoutSecret guards four blank-input scenarios. Each
-// must surface as *ValidationError(SubtypeInvalidArgument) per RFC 6749 §5.2:
-// SubtypeInvalidClient is reserved for IAM rejection of malformed credentials,
-// not for missing user input.
-
-func TestUpdateExistingProfileWithoutSecret_NilConfig_EmitsValidationError(t *testing.T) {
-	err := updateExistingProfileWithoutSecret(nil, "", "cli_test", core.BrandFeishu, "en")
-	assertValidationParam(t, err, "--app-secret")
-}
-
-func TestUpdateExistingProfileWithoutSecret_UnknownProfile_EmitsValidationError(t *testing.T) {
-	existing := &core.MultiAppConfig{
-		Apps: []core.AppConfig{{
-			Name:      "default",
-			AppId:     "app-default",
-			AppSecret: core.PlainSecret("secret-default"),
-			Brand:     core.BrandFeishu,
-		}},
-	}
-	err := updateExistingProfileWithoutSecret(existing, "missing-profile", "cli_test", core.BrandFeishu, "en")
-	assertValidationParam(t, err, "--app-secret")
-}
-
-func TestUpdateExistingProfileWithoutSecret_NoCurrentApp_EmitsValidationError(t *testing.T) {
-	existing := &core.MultiAppConfig{
-		CurrentApp: "missing",
-		Apps: []core.AppConfig{{
-			Name:      "default",
-			AppId:     "app-default",
-			AppSecret: core.PlainSecret("secret-default"),
-			Brand:     core.BrandFeishu,
-		}},
-	}
-	err := updateExistingProfileWithoutSecret(existing, "", "cli_test", core.BrandFeishu, "en")
-	assertValidationParam(t, err, "--app-secret")
-}
-
-func TestUpdateExistingProfileWithoutSecret_AppIdMismatch_EmitsValidationError(t *testing.T) {
-	existing := &core.MultiAppConfig{
-		Apps: []core.AppConfig{{
-			Name:      "default",
-			AppId:     "app-default",
-			AppSecret: core.PlainSecret("secret-default"),
-			Brand:     core.BrandFeishu,
-		}},
-	}
-	err := updateExistingProfileWithoutSecret(existing, "", "cli_different", core.BrandFeishu, "en")
-	assertValidationParam(t, err, "--app-secret")
-}
-
-// wrapUpdateExistingProfileErr is the caller-side classifier for the error
-// returned by updateExistingProfileWithoutSecret. It must preserve typed-error
-// exit semantics (regression: typed ValidationError was being downgraded to
-// InternalError by the legacy *output.ExitError-only passthrough).
-
-func TestWrapUpdateExistingProfileErr_NilPassesThrough(t *testing.T) {
-	if got := wrapUpdateExistingProfileErr(nil); got != nil {
-		t.Fatalf("expected nil, got %v", got)
-	}
-}
-
-func TestWrapUpdateExistingProfileErr_TypedValidationErrorPreserved(t *testing.T) {
-	in := errs.NewValidationError(errs.SubtypeInvalidArgument, "App Secret cannot be empty for new profile").
-		WithParam("--app-secret")
-	got := wrapUpdateExistingProfileErr(in)
-	assertValidationParam(t, got, "--app-secret")
-	// Exit code must remain ExitValidation (2), not ExitInternal (5).
-	if code := output.ExitCodeOf(got); code != output.ExitValidation {
-		t.Errorf("ExitCodeOf = %d, want %d (ExitValidation)", code, output.ExitValidation)
-	}
-	// Must NOT be wrapped as *InternalError.
-	var intErr *errs.InternalError
-	if errors.As(got, &intErr) {
-		t.Errorf("typed ValidationError was downgraded to *InternalError: %v", got)
-	}
-}
-
-func TestWrapUpdateExistingProfileErr_LegacyExitErrorPreserved(t *testing.T) {
-	in := &output.ExitError{Code: 7, Err: errors.New("legacy")}
-	got := wrapUpdateExistingProfileErr(in)
-	var exitErr *output.ExitError
-	if !errors.As(got, &exitErr) {
-		t.Fatalf("expected *output.ExitError to pass through, got %T: %v", got, got)
-	}
-	if exitErr.Code != 7 {
-		t.Errorf("Code = %d, want 7", exitErr.Code)
-	}
-}
-
-func TestWrapUpdateExistingProfileErr_UntypedErrorBecomesInternal(t *testing.T) {
-	in := fmt.Errorf("disk full")
-	got := wrapUpdateExistingProfileErr(in)
-	var intErr *errs.InternalError
-	if !errors.As(got, &intErr) {
-		t.Fatalf("expected *errs.InternalError, got %T: %v", got, got)
-	}
-	if intErr.Subtype != errs.SubtypeSDKError {
-		t.Errorf("Subtype = %q, want %q", intErr.Subtype, errs.SubtypeSDKError)
-	}
-}
-
-// assertValidationParam asserts err is *ValidationError with the given Param.
-func assertValidationParam(t *testing.T, err error, wantParam string) {
-	t.Helper()
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-	var valErr *errs.ValidationError
-	if !errors.As(err, &valErr) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if valErr.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("Subtype = %q, want %q", valErr.Subtype, errs.SubtypeInvalidArgument)
-	}
-	if valErr.Param != wantParam {
-		t.Errorf("Param = %q, want %q", valErr.Param, wantParam)
-	}
-}

cmd/config/keychain_downgrade.go

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

cmd/config/keychain_downgrade_other.go

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

cmd/config/plugins.go

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

cmd/config/policy.go

@@ -59,20 +59,16 @@ func runConfigPolicyShow(f *cmdutil.Factory) error {
 		"source_name":  sourceName,
 		"denied_paths": active.DeniedPaths,
 	}
-	if len(active.Rules) > 0 {
-		rules := make([]map[string]any, 0, len(active.Rules))
-		for _, r := range active.Rules {
-			rules = append(rules, map[string]any{
-				"name":              r.Name,
-				"description":       r.Description,
-				"allow":             r.Allow,
-				"deny":              r.Deny,
-				"max_risk":          r.MaxRisk,
-				"identities":        r.Identities,
-				"allow_unannotated": r.AllowUnannotated,
-			})
+	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,
 		}
-		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{
-		Rules: []*platform.Rule{rule},
+		Rule: rule,
 		Source: cmdpolicy.ResolveSource{
 			Kind: cmdpolicy.SourcePlugin,
 			Name: "secaudit",
@@ -83,16 +83,12 @@ func TestConfigPolicyShow_PluginActive(t *testing.T) {
 	if got["denied_paths"] != float64(42) {
 		t.Errorf("denied_paths = %v, want 42", got["denied_paths"])
 	}
-	rulesAny, ok := got["rules"].([]any)
-	if !ok || len(rulesAny) != 1 {
-		t.Fatalf("rules field missing or wrong shape: %v", got["rules"])
-	}
-	ruleMap, ok := rulesAny[0].(map[string]any)
+	ruleMap, ok := got["rule"].(map[string]any)
 	if !ok {
-		t.Fatalf("rules[0] wrong type")
+		t.Fatalf("rule field missing or wrong type")
 	}
 	if ruleMap["name"] != "secaudit" {
-		t.Errorf("rules[0].name = %v", ruleMap["name"])
+		t.Errorf("rule.name = %v", ruleMap["name"])
 	}
 }
 
@@ -105,7 +101,7 @@ func TestConfigPolicyShow_YamlSourceNameIsEmpty(t *testing.T) {
 	t.Cleanup(cmdpolicy.ResetActiveForTesting)
 
 	cmdpolicy.SetActive(&cmdpolicy.ActivePolicy{
-		Rules: []*platform.Rule{{Name: "my-yaml-rule"}},
+		Rule: &platform.Rule{Name: "my-yaml-rule"},
 		Source: cmdpolicy.ResolveSource{
 			Kind: cmdpolicy.SourceYAML,
 			Name: "/Users/alice/.lark-cli/policy.yml",

cmd/config/remove.go

@@ -6,7 +6,6 @@ package config
 import (
 	"fmt"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
@@ -43,14 +42,14 @@ func configRemoveRun(opts *ConfigRemoveOptions) error {
 
 	config, err := core.LoadMultiAppConfig()
 	if err != nil || config == nil || len(config.Apps) == 0 {
-		return errs.NewConfigError(errs.SubtypeNotConfigured, "not configured yet")
+		return output.ErrValidation("not configured yet")
 	}
 
 	// Save empty config first. If this fails, keep secrets and tokens intact so the
 	// existing config can still be retried instead of ending up half-removed.
 	empty := &core.MultiAppConfig{Apps: []core.AppConfig{}}
 	if err := core.SaveMultiAppConfig(empty); err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 	}
 
 	// Clean up keychain entries for all apps after config is cleared.

cmd/config/show.go

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

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 errs.NewValidationError(errs.SubtypeInvalidArgument, "--reset cannot be used with --global").WithParam("--reset")
+		return output.ErrValidation("--reset cannot be used with --global")
 	}
 	if len(args) > 0 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--reset cannot be used with a value argument").WithParam("--reset")
+		return output.ErrValidation("--reset cannot be used with a value argument")
 	}
 	app.StrictMode = nil
 	if err := core.SaveMultiAppConfig(multi); err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 	}
 	fmt.Fprintln(f.IOStreams.ErrOut, "Profile strict-mode reset (inherits global)")
 	return nil
@@ -104,7 +104,7 @@ func setStrictMode(f *cmdutil.Factory, multi *core.MultiAppConfig, app *core.App
 	switch mode {
 	case core.StrictModeBot, core.StrictModeUser, core.StrictModeOff:
 	default:
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid value %q, valid values: bot | user | off", value)
+		return output.ErrValidation("invalid value %q, valid values: bot | user | off", value)
 	}
 
 	// Capture the old mode at the SAME scope being changed, so we can warn
@@ -144,7 +144,7 @@ func setStrictMode(f *cmdutil.Factory, multi *core.MultiAppConfig, app *core.App
 	}
 
 	if err := core.SaveMultiAppConfig(multi); err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+		return output.Errorf(output.ExitInternal, "internal", "failed to save config: %v", err)
 	}
 
 	if oldMode == core.StrictModeBot && (mode == core.StrictModeUser || mode == core.StrictModeOff) {

cmd/doctor/doctor.go

@@ -19,7 +19,6 @@ 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"
 )
 
@@ -153,9 +152,7 @@ func networkChecks(ctx context.Context, opts *DoctorOptions, ep core.Endpoints)
 		}
 	}
 
-	// Use the shared proxy-plugin-aware transport so connectivity checks reflect
-	// the real egress path (and are blocked when proxy plugin fails closed).
-	httpClient := transport.NewHTTPClient(0)
+	httpClient := &http.Client{}
 	mcpURL := ep.MCP + "/mcp"
 
 	type probeResult struct {

cmd/error_auth_hint.go

@@ -11,7 +11,6 @@ import (
 	"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"
@@ -24,8 +23,12 @@ import (
 // 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.
+// locally (via shortcut registration or service-method metadata).
+//
+// Stage-1: this typed path is dormant — no production code returns a typed
+// *errs.AuthenticationError. Kept so per-domain stage-2 migrations can plug
+// in without re-architecting. The active stage-1 path is
+// enrichMissingScopeError below, which operates on legacy *output.ExitError.
 func applyNeedAuthorizationHint(f *cmdutil.Factory, err error) {
 	if err == nil || f == nil {
 		return
@@ -52,10 +55,12 @@ func applyNeedAuthorizationHint(f *cmdutil.Factory, err error) {
 // 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.
+// locally. Matches pre-PR behaviour byte-for-byte; lives on the legacy
+// envelope path until per-domain stage-2 typed migration.
 //
-// Deprecated: enrichment for the legacy envelope; the typed path is
-// applyNeedAuthorizationHint above.
+// Deprecated: stage-1 enrichment for the legacy *output.ExitError surface.
+// Stage-2 typed migration will lift this into AuthenticationError.Hint on
+// the typed envelope via applyNeedAuthorizationHint and remove this helper.
 func enrichMissingScopeError(f *cmdutil.Factory, exitErr *output.ExitError) {
 	if exitErr == nil || exitErr.Detail == nil {
 		return
@@ -119,37 +124,78 @@ func resolveDeclaredShortcutScopes(cmd *cobra.Command, identity string) []string
 }
 
 // resolveDeclaredServiceMethodScopes returns the scopes declared by a
-// 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.
+// service/resource/method command from the embedded from_meta registry.
 func resolveDeclaredServiceMethodScopes(cmd *cobra.Command, identity string) []string {
-	if cmd == nil || strings.HasPrefix(cmd.Name(), "+") {
+	// 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 {
 		return nil
 	}
-	path := commandCatalogPath(cmd)
-	if len(path) == 0 {
+	if strings.HasPrefix(cmd.Name(), "+") {
 		return nil
 	}
-	target, err := registry.RuntimeCatalog().Resolve(path)
-	if err != nil || target.Kind != apicatalog.TargetMethod {
+
+	service := cmd.Parent().Parent().Name()
+	resource := cmd.Parent().Name()
+	method := cmd.Name()
+
+	spec := registry.LoadFromMeta(service)
+	if spec == nil {
 		return nil
 	}
-	return registry.DeclaredScopesForMethod(target.Method.Method, identity)
+	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)
 }
 
-// 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...)
+// 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)
 	}
-	return 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
 }
 
 // shortcutSupportsIdentity reports whether a shortcut supports the requested

cmd/event/bus.go

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

cmd/event/bus_test.go

@@ -1,45 +0,0 @@
-// 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,7 +16,6 @@ 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"
@@ -65,8 +64,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. 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().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().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
@@ -102,10 +101,11 @@ func runConsume(cmd *cobra.Command, f *cmdutil.Factory, eventKey string, o consu
 
 	if o.jqExpr != "" {
 		if err := output.ValidateJqExpression(o.jqExpr); err != nil {
-			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)
+			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),
+			)
 		}
 	}
 
@@ -184,9 +184,8 @@ func runConsume(cmd *cobra.Command, f *cmdutil.Factory, eventKey string, o consu
 		errOut = io.Discard
 	}
 
-	// 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) {
+	// Non-TTY only: stdin EOF is shutdown for subprocess callers; in TTY Ctrl-D must not exit.
+	if !f.IOStreams.IsTerminal {
 		watchStdinEOF(os.Stdin, cancel, errOut)
 	}
 
@@ -261,12 +260,12 @@ func preflightScopes(ctx context.Context, pf *preflightCtx) error {
 	if len(missing) == 0 {
 		return nil
 	}
-	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))
+	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),
+	)
 }
 
 // scopeRemediationHint returns an identity-appropriate fix for missing scopes.
@@ -301,27 +300,23 @@ func preflightEventTypes(pf *preflightCtx) error {
 	if len(missing) == 0 {
 		return nil
 	}
-	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))
+	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)),
+	)
 }
 
 // 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 "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"%s; use a relative path like ./output instead", errOutputDirTilde).
-			WithParam("--output-dir").
-			WithCause(errOutputDirTilde)
+		return "", output.ErrValidation("%s; use a relative path like ./output instead", errOutputDirTilde)
 	}
 	safe, err := validate.SafeOutputPath(dir)
 	if err != nil {
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"%s %q: %s", errOutputDirUnsafe, dir, err).
-			WithParam("--output-dir").
-			WithCause(errOutputDirUnsafe)
+		return "", output.ErrValidation("%s %q: %s", errOutputDirUnsafe, dir, err)
 	}
 	return safe, nil
 }
@@ -333,21 +328,18 @@ func resolveTenantToken(ctx context.Context, f *cmdutil.Factory, appID string) (
 	}
 	result, err := f.Credential.ResolveToken(ctx, credential.NewTokenSpec(core.AsBot, appID))
 	if err != nil {
-		if _, ok := errs.ProblemOf(err); ok {
-			return "", err
-		}
-		return "", errs.NewAuthenticationError(errs.SubtypeTokenMissing,
-			"resolve tenant access token: %s", err).WithCause(err)
+		return "", output.ErrAuth("resolve tenant access token: %s", err)
 	}
 	if result == nil || result.Token == "" {
-		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 "", 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 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")
@@ -359,10 +351,7 @@ func parseParams(raw []string) (map[string]string, error) {
 	for _, kv := range raw {
 		k, v, ok := strings.Cut(kv, "=")
 		if !ok || k == "" {
-			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"%s %q: expected key=value", errInvalidParamFormat, kv).
-				WithParam("--param").
-				WithCause(errInvalidParamFormat)
+			return nil, output.ErrValidation("%s %q: expected key=value", errInvalidParamFormat, kv)
 		}
 		m[k] = v
 	}
@@ -381,8 +370,3 @@ 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,70 +61,3 @@ 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,14 +4,9 @@
 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) {
@@ -78,7 +73,6 @@ 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 {
@@ -96,77 +90,6 @@ 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
@@ -207,7 +130,6 @@ 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,79 +143,6 @@ 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,17 +89,19 @@ 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)
 	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed errs error, got %T: %v", err, err)
+	var exit *output.ExitError
+	if !errors.As(err, &exit) {
+		t.Fatalf("expected output.ExitError, got %T: %v", err, err)
 	}
-	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)
+	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")
 	}
 	wantURL := "https://open.feishu.cn/app/cli_XXXXXXXXXXXXXXXX/event"
-	if !strings.Contains(p.Hint, wantURL) {
-		t.Errorf("hint missing subscription URL %q\ngot: %s", wantURL, p.Hint)
+	if !strings.Contains(exit.Detail.Hint, wantURL) {
+		t.Errorf("hint missing subscription URL %q\ngot: %s", wantURL, exit.Detail.Hint)
 	}
 }
 
@@ -143,19 +145,17 @@ 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 permErr *errs.PermissionError
-	if !errors.As(err, &permErr) {
-		t.Fatalf("expected *errs.PermissionError, got %T: %v", err, err)
+	var exit *output.ExitError
+	if !errors.As(err, &exit) {
+		t.Fatalf("expected output.ExitError, got %T: %v", err, err)
 	}
-	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.Code != output.ExitAuth {
+		t.Errorf("ExitCode = %d, want ExitAuth (%d)", exit.Code, output.ExitAuth)
 	}
-	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)
+	if exit.Detail == nil {
+		t.Fatal("expected Detail with hint, got nil Detail")
 	}
-	hint := permErr.Hint
+	hint := exit.Detail.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,11 +26,7 @@ func (r *consumeRuntime) CallAPI(ctx context.Context, method, path string, body
 		As:     r.accessIdentity,
 	})
 	if err != nil {
-		if _, ok := errs.ProblemOf(err); ok {
-			return nil, err
-		}
-		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport,
-			"api %s %s: %s", method, path, err).WithCause(err)
+		return nil, err
 	}
 	// Non-JSON HTTP errors (gateway text/plain 404 etc.) skip OAPI envelope parsing.
 	ct := resp.Header.Get("Content-Type")
@@ -40,20 +36,11 @@ func (r *consumeRuntime) CallAPI(ctx context.Context, method, path string, body
 		if len(body) > maxBodyEcho {
 			body = body[:maxBodyEcho] + "…(truncated)"
 		}
-		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)
+		return nil, fmt.Errorf("api %s %s returned %d: %s", method, path, resp.StatusCode, body)
 	}
 	result, err := client.ParseJSONResponse(resp)
 	if err != nil {
-		if _, ok := errs.ProblemOf(err); ok {
-			return nil, err
-		}
-		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse,
-			"api %s %s: %s", method, path, err).WithCause(err)
+		return nil, err
 	}
 	if apiErr := r.client.CheckResponse(result, r.accessIdentity); apiErr != nil {
 		return json.RawMessage(resp.RawBody), apiErr

cmd/event/runtime_test.go

@@ -1,147 +0,0 @@
-// 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,7 +11,6 @@ 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"
@@ -40,14 +39,12 @@ 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, errs.NewInternalError(errs.SubtypeUnknown,
-				"parse base schema for field overrides: %s", err).WithCause(err)
+			return nil, nil, err
 		}
 		orphans := schemas.ApplyFieldOverrides(parsed, def.Schema.FieldOverrides)
 		out, err := json.Marshal(parsed)
 		if err != nil {
-			return nil, nil, errs.NewInternalError(errs.SubtypeUnknown,
-				"serialize schema with field overrides: %s", err).WithCause(err)
+			return nil, nil, err
 		}
 		return out, orphans, nil
 	}
@@ -76,7 +73,7 @@ func renderSpec(s *eventlib.SchemaSpec) (json.RawMessage, error) {
 		copy(buf, s.Raw)
 		return buf, nil
 	}
-	return nil, errs.NewInternalError(errs.SubtypeUnknown, "schemaSpec has neither Type nor Raw")
+	return nil, fmt.Errorf("schemaSpec has neither Type nor Raw")
 }
 
 func NewCmdSchema(f *cmdutil.Factory) *cobra.Command {
@@ -134,16 +131,12 @@ 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\tSUB-KEY\tDEFAULT\tDESCRIPTION\n")
+		fmt.Fprintf(w, "  NAME\tTYPE\tREQUIRED\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 = "-"
@@ -152,7 +145,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\t%s\n", p.Name, p.Type, required, subKey, defaultVal, desc)
+			fmt.Fprintf(w, "  %s\t%s\t%s\t%s\t%s\n", p.Name, p.Type, required, defaultVal, desc)
 		}
 		w.Flush()
 
@@ -172,7 +165,7 @@ func runSchema(f *cmdutil.Factory, key string, asJSON bool) error {
 
 	resolved, _, err := resolveSchemaJSON(def)
 	if err != nil {
-		return err
+		return output.Errorf(output.ExitInternal, "internal", "resolve schema: %v", err)
 	}
 	if resolved != nil {
 		fmt.Fprintf(out, "\nOutput Schema:\n")

cmd/event/schema_test.go

@@ -10,7 +10,6 @@ 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"
@@ -96,79 +95,6 @@ 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) })
@@ -203,38 +129,3 @@ 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,7 +7,6 @@ import (
 	"fmt"
 	"io"
 	"sort"
-	"strings"
 	"sync"
 	"time"
 
@@ -243,17 +242,12 @@ 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", "SUB", "RECEIVED", "DROPPED"}
+				headers := []string{"CONSUMER", "EVENT KEY", "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,9 +8,8 @@ import (
 	"sort"
 	"strings"
 
-	"github.com/larksuite/cli/errs"
 	eventlib "github.com/larksuite/cli/internal/event"
-	"github.com/larksuite/cli/internal/suggest"
+	"github.com/larksuite/cli/internal/output"
 )
 
 const maxSuggestions = 3
@@ -29,7 +28,7 @@ func suggestEventKeys(input string) []string {
 			hits = append(hits, match{def.Key, 0})
 			continue
 		}
-		if d := suggest.Levenshtein(input, def.Key); d <= threshold {
+		if d := levenshtein(input, def.Key); d <= threshold {
 			hits = append(hits, match{def.Key, d})
 		}
 	}
@@ -64,6 +63,40 @@ func unknownEventKeyErr(key string) error {
 	if guesses := suggestEventKeys(key); len(guesses) > 0 {
 		msg += " — did you mean " + formatSuggestions(guesses) + "?"
 	}
-	return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", msg).
-		WithHint("Run 'lark-cli event list' to see available keys.")
+	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)]
 }

cmd/event/suggestions_test.go

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

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

@@ -1,61 +0,0 @@
-// 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,71 +36,47 @@ 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 {
-	// 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
+	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 = ""
 	}
 
-	rules, source, err := cmdpolicy.Resolve(cmdpolicy.Sources{
+	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{
 		PluginRules: pluginRules,
-		YAMLRules:   yamlRules,
+		YAMLRule:    yamlRule,
 		YAMLPath:    yamlPath,
 	})
 	if err != nil {
 		cmdpolicy.SetActive(nil)
 		return err
 	}
-	if len(rules) == 0 {
+	if rule == nil {
 		cmdpolicy.SetActive(&cmdpolicy.ActivePolicy{Source: source})
 		return nil
 	}
 
-	// RuleName attributes a denial to a specific rule in the envelope.
-	// With a single rule that is unambiguous and preserves the legacy
-	// envelope verbatim; with several rules a denial means "no rule
-	// granted it", which has no single owner, so the field is left empty
-	// and reason_code=no_matching_rule carries the meaning instead.
-	ruleName := ""
-	if len(rules) == 1 {
-		ruleName = rules[0].Name
-	}
-
-	engine := cmdpolicy.NewSet(rules)
+	engine := cmdpolicy.New(rule)
 	decisions := engine.EvaluateAll(rootCmd)
-	denied := cmdpolicy.BuildDeniedByPath(rootCmd, decisions, source, ruleName)
+	denied := cmdpolicy.BuildDeniedByPath(rootCmd, decisions, source, rule.Name)
 	cmdpolicy.Apply(rootCmd, denied)
 
 	cmdpolicy.SetActive(&cmdpolicy.ActivePolicy{
-		Rules:       rules,
+		Rule:        rule,
 		Source:      source,
 		DeniedPaths: len(denied),
 	})

cmd/platform_bootstrap_test.go

@@ -13,8 +13,6 @@ 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"
 )
@@ -186,39 +184,6 @@ 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/profile/add.go

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

cmd/profile/profile_test.go

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

cmd/root.go

@@ -4,31 +4,29 @@
 package cmd
 
 import (
+	"bytes"
 	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
+	"io"
 	"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.
@@ -36,7 +34,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>
+    lark-cli schema <service.resource.method> [--format pretty]
 
 EXAMPLES:
     # View upcoming events
@@ -51,6 +49,20 @@ EXAMPLES:
     # Generic API call
     lark-cli api GET /open-apis/calendar/v4/calendars
 
+FLAGS:
+    --params <json>       URL/query parameters JSON
+    --data <json>         request body JSON (POST/PATCH/PUT/DELETE)
+    --as <type>           identity type: user | bot
+    --format <fmt>        output format: json (default) | ndjson | table | csv | pretty
+    --page-all            automatically paginate through all pages
+    --page-size <N>       page size (0 = use API default)
+    --page-limit <N>      max pages to fetch with --page-all (default: 10, 0 for unlimited)
+    --page-delay <MS>     delay in ms between pages (default: 200, only with --page-all)
+    -o, --output <path>   output file path for binary responses
+    --jq <expr>           jq expression to filter JSON output
+    -q <expr>             shorthand for --jq
+    --dry-run             print request without executing
+
 AI AGENT SKILLS:
     lark-cli pairs with AI agent skills (Claude Code, etc.) that
     teach the agent Lark API patterns, best practices, and workflows.
@@ -72,15 +84,7 @@ 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)
@@ -144,49 +148,29 @@ func setupNotices() {
 	skillscheck.Init(build.Version)
 
 	// Composed notice provider — emits keys only when each pending is set.
-	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",
+	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",
+			}
 		}
+		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.
@@ -217,66 +201,43 @@ func configureFlagCompletions(args []string) {
 // 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
+//  1. *errs.SecurityPolicyError: keeps the legacy custom envelope
+//     (type=auth_error, string code, retryable, challenge_url) and exit 1.
+//     Carve-out from the typed taxonomy — wire migration deferred to a later PR.
+//  2. Typed errors from errs/ (e.g. *errs.PermissionError, *errs.APIError):
+//     render via the typed envelope writer, which lifts extension fields
+//     (missing_scopes, console_url, ...) to the top level. Routed by
 //     errs.CategoryOf via ExitCodeOf.
-//  3. Legacy *output.ExitError: asExitError adapts it to the legacy
-//     envelope, written via WriteErrorEnvelope.
+//  3. *core.ConfigError + Legacy *output.ExitError: asExitError adapts them
+//     to a legacy envelope; written via WriteErrorEnvelope. Stage-1 keeps
+//     this path so existing wire shapes are preserved byte-for-byte until
+//     per-domain typed migration in stage 2+.
 //  4. Cobra errors (required flags, unknown commands, etc.): plain text.
 func handleRootError(f *cmdutil.Factory, err error) int {
 	errOut := f.IOStreams.ErrOut
 
-	// 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)
-			}
-		}
+	// SecurityPolicyError keeps the legacy custom envelope (string codes,
+	// challenge_url, retryable) and exit code 1 — its wire shape predates the
+	// typed taxonomy and downstream OAuth/policy consumers depend on it.
+	// The taxonomy migration for this category is deferred to a later PR.
+	var spErr *errs.SecurityPolicyError
+	if errors.As(err, &spErr) {
+		writeSecurityPolicyError(errOut, spErr)
+		return 1
 	}
 
+	// *core.ConfigError flows raw to the legacy envelope path in stage 1
+	// (asExitError → output.ErrWithHint). Typed migration via
+	// errcompat.PromoteConfigError happens in stage 2+.
+
 	// When the typed error is a need_user_authorization signal, fold in the
 	// current command's declared scopes as a Hint so the user/AI sees the
 	// concrete scope(s) to re-auth with. The hint is computed on the fly from
 	// local shortcut/service metadata — it never depends on server state.
 	applyNeedAuthorizationHint(f, err)
 
-	// 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
+		return output.ExitCodeOf(err)
 	}
 
 	if exitErr := asExitError(err); exitErr != nil {
@@ -291,36 +252,56 @@ func handleRootError(f *cmdutil.Factory, err error) int {
 		return exitErr.Code
 	}
 
-	// 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
+// writeSecurityPolicyError writes the security-policy-specific JSON envelope.
+// This wire format intentionally differs from the typed envelope writer: it
+// uses string codes ("challenge_required"/"access_denied"), a "auth_error"
+// type literal, and a top-level "retryable" field — the shape OAuth/policy
+// consumers have been parsing since before the typed taxonomy existed.
+func writeSecurityPolicyError(w io.Writer, spErr *errs.SecurityPolicyError) {
+	var codeStr string
+	switch spErr.Subtype {
+	case errs.SubtypeChallengeRequired:
+		codeStr = "challenge_required"
+	case errs.SubtypeAccessDenied:
+		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.Hint != "" {
+		errData["hint"] = spErr.Hint
+	}
+
+	env := map[string]interface{}{"ok": false, "error": errData}
+
+	buffer := &bytes.Buffer{}
+	encoder := json.NewEncoder(buffer)
+	encoder.SetEscapeHTML(false)
+	encoder.SetIndent("", "  ")
+	if encErr := encoder.Encode(env); encErr != nil {
+		fmt.Fprintln(w, `{"ok":false,"error":{"type":"internal_error","code":"marshal_error","message":"failed to marshal error"}}`)
+		return
+	}
+	fmt.Fprint(w, buffer.String())
 }
 
 // asExitError converts known structured error types to *output.ExitError.
 // Returns nil for unrecognized errors (e.g. cobra flag errors).
 //
-// Deprecated: legacy *output.ExitError bridge.
+// Deprecated: legacy *output.ExitError bridge; removed after typed migration.
 func asExitError(err error) *output.ExitError {
 	var cfgErr *core.ConfigError
 	if errors.As(err, &cfgErr) {
@@ -345,12 +326,6 @@ func asExitError(err error) *output.ExitError {
 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{}
 		}
@@ -370,89 +345,14 @@ func installUnknownSubcommandGuard(cmd *cobra.Command) {
 // they have moved to the typed surface.
 func unknownSubcommandRunE(cmd *cobra.Command, args []string) error {
 	if len(args) == 0 {
-		// 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{},
-				},
-			},
-		}
+		return cmd.Help()
 	}
 	unknown := args[0]
-	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)
+	available := availableSubcommandNames(cmd)
 	msg := fmt.Sprintf("unknown subcommand %q for %q", unknown, cmd.CommandPath())
 	hint := fmt.Sprintf("run `%s --help` to see available subcommands", cmd.CommandPath())
-	if len(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
+	if len(available) > 0 {
+		hint = fmt.Sprintf("available subcommands: %s", strings.Join(available, ", "))
 	}
 	return &output.ExitError{
 		Code: output.ExitValidation,
@@ -460,114 +360,17 @@ func unknownSubcommandRunE(cmd *cobra.Command, args []string) error {
 			Type:    "unknown_subcommand",
 			Message: msg,
 			Hint:    hint,
-			Detail:  detail,
+			Detail: map[string]any{
+				"unknown":      unknown,
+				"command_path": cmd.CommandPath(),
+				"available":    available,
+			},
 		},
 	}
 }
 
-// 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) {
+func availableSubcommandNames(cmd *cobra.Command) []string {
+	subs := make([]string, 0, len(cmd.Commands()))
 	for _, c := range cmd.Commands() {
 		if c.Hidden || !c.IsAvailableCommand() {
 			continue
@@ -576,95 +379,10 @@ func availableSubcommandNames(cmd *cobra.Command) (available, deprecated []strin
 		if name == "help" || name == "completion" {
 			continue
 		}
-		if cmdutil.IsDeprecatedCommand(c) {
-			deprecated = append(deprecated, name)
-		} else {
-			available = append(available, name)
-		}
+		subs = append(subs, name)
 	}
-	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
+	sort.Strings(subs)
+	return subs
 }
 
 // installTipsHelpFunc wraps the default help function to append a TIPS section
@@ -699,55 +417,65 @@ func installTipsHelpFunc(root *cobra.Command) {
 	})
 }
 
-// enrichPermissionError rewrites the legacy *output.ExitError envelope so its
-// Message + Hint match the per-subtype canonical text produced by the typed
-// dispatcher path (errclass.CanonicalPermissionMessage / errclass.PermissionHint).
-// This guarantees a caller observing the wire envelope cannot tell whether
-// the error reached the dispatcher via the legacy *ExitError bridge or via
-// the typed *errs.PermissionError fast path.
+// enrichPermissionError adds console_url and improves the hint for legacy
+// *output.ExitError permission errors. Differentiates between:
+//   - LarkErrAppScopeNotEnabled (99991672): app has not enabled the scope
+//   - LarkErrUserScopeInsufficient (99991679) / LarkErrUserNotAuthorized:
+//     user has not authorized the scope → hint to auth login
+//   - default: other permission errors → console + auth-login fallback
 //
-// Deprecated: legacy *output.ExitError enrichment; typed PermissionError
-// values produced by errclass.BuildAPIError already carry MissingScopes +
-// ConsoleURL directly.
+// Deprecated: stage-1 enrichment for the legacy *output.ExitError envelope.
+// Stage-2 typed migration will lift this into PermissionError.MissingScopes
+// + ConsoleURL on the typed envelope and remove this helper.
 func enrichPermissionError(f *cmdutil.Factory, exitErr *output.ExitError) {
-	if exitErr.Detail == nil {
+	if exitErr.Detail == nil || exitErr.Detail.Type != "permission" {
 		return
 	}
-	// Only the legacy permission-class envelope types route here. "app_status"
-	// covers 99991662 (app_disabled) / 99991673 (app_unavailable); "permission"
-	// covers the four scope-class codes (99991672 / 99991676 / 99991679 / 230027).
-	if exitErr.Detail.Type != "permission" && exitErr.Detail.Type != "app_status" {
+	// Extract required scopes from API error detail (shared helper)
+	scopes := registry.ExtractRequiredScopes(exitErr.Detail.Detail)
+	if len(scopes) == 0 {
 		return
 	}
 
-	larkCode := exitErr.Detail.Code
-	meta, ok := errclass.LookupCodeMeta(larkCode)
-	if !ok || meta.Category != errs.CategoryAuthorization {
-		return
-	}
-
-	// Extract required scopes from API error detail (shared helper). May be
-	// empty for app-status codes — canonical message + hint still apply.
-	missing := registry.ExtractRequiredScopes(exitErr.Detail.Detail)
-
 	cfg, err := f.Config()
 	if err != nil {
 		return
 	}
 
-	// Reuse the same console URL builder as the typed path so both wire
-	// envelopes carry identical console_url values for the same input.
-	consoleURL := errclass.ConsoleURL(string(cfg.Brand), cfg.AppID, missing)
+	// Select the recommended (least-privilege) scope
+	recommended := registry.SelectRecommendedScopeFromStrings(scopes, "tenant")
+
+	// Build admin console URL with the recommended scope
+	consoleURL := registry.BuildConsoleScopeURL(cfg.Brand, cfg.AppID, recommended)
 
 	// Clear raw API detail — useful info is now in message/hint/console_url.
 	exitErr.Detail.Detail = nil
 
-	identity := string(f.ResolvedIdentity)
-	if identity == "" {
-		identity = "user"
-	}
+	isBot := f.ResolvedIdentity.IsBot()
+	larkCode := exitErr.Detail.Code
+	switch larkCode {
+	case output.LarkErrUserScopeInsufficient, output.LarkErrUserNotAuthorized:
+		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
 
-	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
+	case output.LarkErrAppScopeNotEnabled:
+		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:
+		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
+	}
 }

cmd/root_integration_test.go

@@ -281,7 +281,7 @@ func TestIntegration_StrictModeUser_ProfileOverride_ShortcutExplicitBotReturnsEn
 		OK:       false,
 		Identity: "bot",
 		Error: &output.ErrDetail{
-			Type:    "validation",
+			Type:    "command_denied",
 			Message: `strict mode is "user", only user-identity commands are available`,
 			Hint:    "if the user explicitly wants to switch policy, see `lark-cli config strict-mode --help` (confirm with the user before switching; switching does NOT require re-bind)",
 		},
@@ -300,7 +300,7 @@ func TestIntegration_StrictModeBot_ProfileOverride_ServiceExplicitUserReturnsEnv
 		OK:       false,
 		Identity: "user",
 		Error: &output.ErrDetail{
-			Type:    "validation",
+			Type:    "command_denied",
 			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)",
 		},
@@ -345,7 +345,7 @@ func TestIntegration_StrictModeBot_ProfileOverride_APIExplicitUserReturnsEnvelop
 		OK:       false,
 		Identity: "user",
 		Error: &output.ErrDetail{
-			Type:    "validation",
+			Type:    "command_denied",
 			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)",
 		},
@@ -377,15 +377,18 @@ func TestIntegration_Shortcut_BusinessError_OutputsEnvelope(t *testing.T) {
 		OK:       false,
 		Identity: "bot",
 		Error: &output.ErrDetail{
-			Type:    "api",
+			Type:    "api_error",
 			Code:    230002,
-			Message: "Bot/User can NOT be out of the chat.",
+			Message: "HTTP 400: Bot/User can NOT be out of the chat.",
 		},
 	})
 }
 
-// TestSetupNotices_ColdStart_NoNotice verifies that missing state
-// produces no skills key in the composed notice.
+// TestSetupNotices_ColdStart_NoNotice verifies that a missing stamp
+// produces no skills key in the composed notice. Users who installed
+// skills via `npx skills add` (no stamp) must not see the misleading
+// "not installed" notice — only `lark-cli update` users opt into the
+// drift tracker.
 func TestSetupNotices_ColdStart_NoNotice(t *testing.T) {
 	clearNoticeEnv(t)
 	dir := t.TempDir()
@@ -416,13 +419,13 @@ func TestSetupNotices_ColdStart_NoNotice(t *testing.T) {
 	}
 }
 
-// TestSetupNotices_InSync verifies that matching state produces no
+// TestSetupNotices_InSync verifies that a matching stamp produces no
 // skills key in the composed notice.
 func TestSetupNotices_InSync(t *testing.T) {
 	clearNoticeEnv(t)
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.21"}); err != nil {
+	if err := skillscheck.WriteStamp("1.0.21"); err != nil {
 		t.Fatal(err)
 	}
 
@@ -449,13 +452,13 @@ func TestSetupNotices_InSync(t *testing.T) {
 	}
 }
 
-// TestSetupNotices_Drift verifies mismatching state produces the
+// TestSetupNotices_Drift verifies a mismatching stamp produces the
 // drift message with both current and target populated.
 func TestSetupNotices_Drift(t *testing.T) {
 	clearNoticeEnv(t)
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.20"}); err != nil {
+	if err := skillscheck.WriteStamp("1.0.20"); err != nil {
 		t.Fatal(err)
 	}
 
@@ -504,7 +507,7 @@ func TestSetupNotices_BothUpdateAndSkills(t *testing.T) {
 	clearNoticeEnv(t)
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.20"}); err != nil {
+	if err := skillscheck.WriteStamp("1.0.20"); err != nil {
 		t.Fatal(err)
 	}
 

cmd/root_test.go

@@ -7,7 +7,6 @@ import (
 	"bytes"
 	"encoding/json"
 	"fmt"
-	"io"
 	"strings"
 	"testing"
 
@@ -21,8 +20,6 @@ import (
 	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"
 )
 
@@ -140,96 +137,81 @@ 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) {
+// TestHandleRootError_SecurityPolicyKeepsLegacyEnvelope pins the carve-out
+// for *errs.SecurityPolicyError: it does NOT go through the typed envelope
+// writer. Downstream OAuth/policy consumers parse a wire format that
+// predates the typed taxonomy and depend on:
+//   - error.type == "auth_error" (not the Category literal "policy")
+//   - error.code is a string ("challenge_required" / "access_denied"), not a number
+//   - error.retryable is present at the top of the error object
+//   - exit code 1 (not ExitContentSafety 6)
+//
+// Migration of this category to the typed envelope is deferred to a later PR.
+func TestHandleRootError_SecurityPolicyKeepsLegacyEnvelope(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	cases := []struct {
+		name     string
+		subtype  errs.Subtype
+		code     int
+		wantCode string
+	}{
+		{"challenge_required", errs.SubtypeChallengeRequired, 21000, "challenge_required"},
+		{"access_denied", errs.SubtypeAccessDenied, 21001, "access_denied"},
+	}
 
-	t.Run("21000 challenge_required", func(t *testing.T) {
-		f, _, _, _ := cmdutil.TestFactory(t, nil)
-		errOut := &bytes.Buffer{}
-		f.IOStreams.ErrOut = errOut
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			f, _, _, _ := cmdutil.TestFactory(t, nil)
+			errOut := &bytes.Buffer{}
+			f.IOStreams.ErrOut = errOut
 
-		spErr := &errs.SecurityPolicyError{
-			Problem: errs.Problem{
-				Category: errs.CategoryPolicy,
-				Subtype:  errs.SubtypeChallengeRequired,
-				Code:     21000,
-				Message:  "blocked by access policy",
-				Hint:     "complete challenge in your browser",
-			},
-			ChallengeURL: "https://example.com/challenge",
-		}
+			spErr := &errs.SecurityPolicyError{
+				Problem: errs.Problem{
+					Category: errs.CategoryPolicy,
+					Subtype:  tc.subtype,
+					Code:     tc.code,
+					Message:  "blocked by access policy",
+					Hint:     "complete challenge in your browser",
+				},
+				ChallengeURL: "https://example.com/challenge",
+			}
 
-		gotExit := handleRootError(f, spErr)
-		if gotExit != int(output.ExitContentSafety) {
-			t.Errorf("exit code = %d, want %d (ExitContentSafety)", gotExit, output.ExitContentSafety)
-		}
+			gotExit := handleRootError(f, spErr)
+			if gotExit != 1 {
+				t.Errorf("exit code = %d, want 1 (legacy carve-out)", gotExit)
+			}
 
-		var env map[string]any
-		if err := json.Unmarshal(errOut.Bytes(), &env); err != nil {
-			t.Fatalf("envelope is not valid JSON: %v\n%s", err, errOut.String())
-		}
-		errObj, ok := env["error"].(map[string]any)
-		if !ok {
-			t.Fatalf("envelope missing top-level error object: %s", errOut.String())
-		}
-		if got := errObj["type"]; got != "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"])
-		}
-	})
+			var env map[string]any
+			if err := json.Unmarshal(errOut.Bytes(), &env); err != nil {
+				t.Fatalf("envelope is not valid JSON: %v\n%s", err, errOut.String())
+			}
+			errObj, ok := env["error"].(map[string]any)
+			if !ok {
+				t.Fatalf("envelope missing top-level error object: %s", errOut.String())
+			}
+			if got := errObj["type"]; got != "auth_error" {
+				t.Errorf("error.type = %v, want %q", got, "auth_error")
+			}
+			if got := errObj["code"]; got != tc.wantCode {
+				t.Errorf("error.code = %v (%T), want %q (string)", got, got, tc.wantCode)
+			}
+			if got, ok := errObj["retryable"].(bool); !ok || got {
+				t.Errorf("error.retryable = %v (%T), want false (bool)", errObj["retryable"], errObj["retryable"])
+			}
+			if got := errObj["challenge_url"]; got != "https://example.com/challenge" {
+				t.Errorf("error.challenge_url = %v, want challenge url", got)
+			}
+			if got := errObj["hint"]; got != "complete challenge in your browser" {
+				t.Errorf("error.hint = %v, want hint message", got)
+			}
+			// And the typed-only fields must NOT appear on this envelope.
+			for _, leaked := range []string{"subtype", "missing_scopes", "console_url"} {
+				if _, exists := errObj[leaked]; exists {
+					t.Errorf("error.%s leaked into legacy security envelope: %v", leaked, errObj[leaked])
+				}
+			}
+		})
+	}
 }
 
 // newAuthErrorWithNeedAuthMarker builds a typed *errs.AuthenticationError whose Message
@@ -248,125 +230,6 @@ func newAuthErrorWithNeedAuthMarker() *errs.AuthenticationError {
 	}
 }
 
-// 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
@@ -494,136 +357,3 @@ func TestApplyNeedAuthorizationHint_AppendsExistingHint(t *testing.T) {
 		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,17 +5,16 @@ package schema
 
 import (
 	"context"
-	"errors"
+	"fmt"
 	"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/schema"
+	"github.com/larksuite/cli/internal/util"
 	"github.com/spf13/cobra"
 )
 
@@ -24,10 +23,335 @@ type SchemaOptions struct {
 	Factory *cmdutil.Factory
 	Ctx     context.Context
 
-	// 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
+	// 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
 }
 
 // NewCmdSchema creates the schema command. If runF is non-nil it is called instead of schemaRun (test hook).
@@ -35,11 +359,13 @@ func NewCmdSchema(f *cmdutil.Factory, runF func(*SchemaOptions) error) *cobra.Co
 	opts := &SchemaOptions{Factory: f}
 
 	cmd := &cobra.Command{
-		Use:   "schema [path | service resource method]",
+		Use:   "schema [path]",
 		Short: "View API method parameters, types, and scopes",
-		Args:  cobra.MaximumNArgs(8),
+		Args:  cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
-			opts.Args = append([]string(nil), args...)
+			if len(args) > 0 {
+				opts.Path = args[0]
+			}
 			opts.Ctx = cmd.Context()
 			if runF != nil {
 				return runF(opts)
@@ -49,89 +375,248 @@ 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)
-	cmdutil.SetRisk(cmd, cmdutil.RiskRead)
+	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")
 
 	return cmd
 }
 
-// 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).
+// 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.
 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())
-		completions, noSpace := registry.EmbeddedCatalog().Complete(args, toComplete, registry.FilterForStrictMode(mode))
+		spec = filterSpecByStrictMode(spec, mode)
+		resources, _ := spec["resources"].(map[string]interface{})
+		if resources == nil {
+			return nil, cobra.ShellCompDirectiveNoFileComp
+		}
+
+		afterService := strings.Join(parts[1:], ".")
+		completions := completeSchemaPathForSpec(serviceName, resources, afterService)
+
+		allTrailingDot := len(completions) > 0
+		for _, c := range completions {
+			if !strings.HasSuffix(c, ".") {
+				allTrailingDot = false
+				break
+			}
+		}
 		directive := cobra.ShellCompDirectiveNoFileComp
-		if noSpace {
+		if allTrailingDot {
 			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)
-}
 
-// 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]))
+	if opts.Path == "" {
+		printServices(out)
 		return nil
 	}
-	output.PrintJson(out, schema.Envelopes(refs))
+
+	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)
+	}
 	return nil
 }
 
-// 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
+// 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
 	}
-	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)
+	result := make(map[string]interface{}, len(spec))
+	for k, v := range spec {
+		result[k] = v
 	}
-	return err
+	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
 }

cmd/schema/schema_test.go

@@ -4,7 +4,7 @@
 package schema
 
 import (
-	"encoding/json"
+	"bytes"
 	"strings"
 	"testing"
 
@@ -20,178 +20,30 @@ func TestSchemaCmd_FlagParsing(t *testing.T) {
 		gotOpts = opts
 		return nil
 	})
-	cmd.SetArgs([]string{"calendar.events.list"})
+	cmd.SetArgs([]string{"calendar.events.list", "--format", "pretty"})
 	err := cmd.Execute()
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	if len(gotOpts.Args) != 1 || gotOpts.Args[0] != "calendar.events.list" {
-		t.Errorf("expected args [calendar.events.list], got %v", gotOpts.Args)
+	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)
 	}
 }
 
-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) {
+func TestSchemaCmd_NoArgs(t *testing.T) {
 	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
 
 	cmd := NewCmdSchema(f, nil)
 	cmd.SetArgs([]string{})
-	if err := cmd.Execute(); err != nil {
+	err := cmd.Execute()
+	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	out := strings.TrimSpace(stdout.String())
-	if !strings.HasPrefix(out, "[") {
-		head := out
-		if len(head) > 80 {
-			head = head[:80]
-		}
-		t.Errorf("expected JSON array root, first 80 chars:\n%s", head)
-	}
-	var envs []map[string]interface{}
-	if err := json.Unmarshal([]byte(out), &envs); err != nil {
-		t.Fatalf("unmarshal failed: %v", err)
-	}
-	if len(envs) < 193 {
-		t.Errorf("envelopes count = %d, want >= 193", len(envs))
-	}
-}
-
-func TestSchemaCmd_JSONIsEnvelope(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
-
-	cmd := NewCmdSchema(f, nil)
-	cmd.SetArgs([]string{"im.images.create"})
-	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")
+	if !strings.Contains(stdout.String(), "Available services") {
+		t.Error("expected service list output")
 	}
 }
 
@@ -211,6 +63,168 @@ func TestSchemaCmd_UnknownService(t *testing.T) {
 	}
 }
 
-// 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.
+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)
+	}
+}

cmd/service/affordance.go

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

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

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

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

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

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

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

cmd/service/sanitize_test.go

@@ -1,61 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package service
-
-import (
-	"strings"
-	"testing"
-)
-
-func TestSanitizeOptionDesc(t *testing.T) {
-	cases := map[string]string{
-		"":                         "",
-		"以 open_id 标识用户":           "以 open_id 标识用户",
-		"中文。English second clause": "中文",         // first clause only (。)
-		"head；tail":                "head",       // first clause (；)
-		"line one\nline two":       "line one",   // first clause (newline)
-		"  spaced   out  ":         "spaced out", // whitespace collapsed
-		"see [飞书后台](https://x/admin) 详情": "see 飞书后台 详情", // markdown link -> text, url dropped
-	}
-	for in, want := range cases {
-		if got := sanitizeOptionDesc(in); got != want {
-			t.Errorf("sanitizeOptionDesc(%q) = %q, want %q", in, got, want)
-		}
-	}
-
-	// Truncation: a long single clause is cut to 40 runes with an ellipsis,
-	// rune-safe (no split mid-character).
-	long := strings.Repeat("文", 60)
-	got := sanitizeOptionDesc(long)
-	if r := []rune(got); len(r) != 40 || !strings.HasSuffix(got, "...") {
-		t.Errorf("truncation = %q (%d runes), want 40 runes ending in ...", got, len(r))
-	}
-}
-
-func TestSanitizeFieldDesc_TrimsDanglingPunctuation(t *testing.T) {
-	// A clause cut can strand a connector (e.g. a colon introducing a list the
-	// newline cut drops, as in im.reactions.list's message_id); the help line
-	// joiner then renders "…获取方式：." — so dangling punctuation must go too.
-	cases := map[string]string{
-		"待查询的消息ID。ID 获取方式：\n- 调用接口获取": "待查询的消息ID。ID 获取方式",
-		"see the list below:\nitem":   "see the list below",
-		"逗号结尾，\n下一行":                  "逗号结尾",
-	}
-	for in, want := range cases {
-		if got := sanitizeFieldDesc(in); got != want {
-			t.Errorf("sanitizeFieldDesc(%q) = %q, want %q", in, got, want)
-		}
-	}
-}
-
-func TestSanitizeFieldDesc_StripsBackquotes(t *testing.T) {
-	// pflag's UnquoteUsage takes a backquoted word in a flag's usage string as
-	// the flag's metavar: wiki space_id's description rendered the flag as
-	// "--space-id my_library" instead of "--space-id string".
-	in := "[知识空间id](https://x/wiki)，如果查询我的文档库可替换为`my_library`"
-	want := "知识空间id，如果查询我的文档库可替换为my_library"
-	if got := sanitizeFieldDesc(in); got != want {
-		t.Errorf("sanitizeFieldDesc(%q) = %q, want %q", in, got, want)
-	}
-}

cmd/service/service.go

@@ -9,21 +9,17 @@ import (
 	"io"
 	"strings"
 
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/apicatalog"
 	"github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/client"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/credential"
-	"github.com/larksuite/cli/internal/errclass"
-	"github.com/larksuite/cli/internal/meta"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/registry"
+	"github.com/larksuite/cli/internal/util"
 	"github.com/larksuite/cli/internal/validate"
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 	"github.com/spf13/cobra"
-	"github.com/spf13/pflag"
 )
 
 // RegisterServiceCommands registers all service commands from from_meta specs.
@@ -32,74 +28,85 @@ func RegisterServiceCommands(parent *cobra.Command, f *cmdutil.Factory) {
 }
 
 func RegisterServiceCommandsWithContext(ctx context.Context, parent *cobra.Command, f *cmdutil.Factory) {
-	// Drive the service list from the same navigation catalog the method walk
-	// uses — RuntimeCatalog().Services() is the deterministic, sorted view of the
-	// merged metadata — so registration is catalog-sourced end to end. Kept as a
-	// per-service loop rather than a flat WalkMethods(nil) drive precisely so a
-	// service with no methods still gets its bare command (WalkMethods yields one
-	// ref per method, so empty services would vanish).
-	for _, svc := range registry.RuntimeCatalog().Services() {
-		if svc.Name == "" || svc.ServicePath == "" {
+	for _, project := range registry.ListFromMetaProjects() {
+		spec := registry.LoadFromMeta(project)
+		if spec == nil {
 			continue
 		}
-		registerServiceWithContext(ctx, parent, svc, f)
-	}
-}
-
-func registerService(parent *cobra.Command, svc meta.Service, f *cmdutil.Factory) {
-	registerServiceWithContext(context.Background(), parent, svc, f)
-}
-
-func registerServiceWithContext(ctx context.Context, parent *cobra.Command, svc meta.Service, f *cmdutil.Factory) {
-	svcCmd := ensureChildCommand(parent, svc.Name, serviceShort(svc))
-
-	// Build the service's subtree from the catalog's method walk
-	// (apicatalog.ServiceMethods recurses nested resources), so the command tree
-	// is sourced from the same navigation Module as schema/scope rather than a
-	// hand-rolled resource/method walk. Each ref's ResourcePath becomes the
-	// resource-command chain — one level for a flat dotted resource like
-	// "chat.members", deeper for genuinely nested resources. A service with no
-	// methods keeps its bare command (svcCmd is created above regardless).
-	for _, ref := range apicatalog.ServiceMethods(svc, nil) {
-		resCmd := svcCmd
-		for _, seg := range ref.ResourcePath {
-			resCmd = ensureChildCommand(resCmd, seg, seg+" operations")
+		specName := registry.GetStrFromMap(spec, "name")
+		servicePath := registry.GetStrFromMap(spec, "servicePath")
+		if specName == "" || servicePath == "" {
+			continue
 		}
-		resCmd.AddCommand(buildMethodCommand(ctx, f, newMethodCommandSpec(ref), nil, parent.PersistentFlags()))
+		resources, _ := spec["resources"].(map[string]interface{})
+		if resources == nil {
+			continue
+		}
+		registerServiceWithContext(ctx, parent, spec, resources, f)
 	}
 }
 
-// serviceShort is the service command's help summary: the localized description
-// from the registry, falling back to the metadata's own description.
-func serviceShort(svc meta.Service) string {
-	if d := registry.GetServiceDescription(svc.Name, "en"); d != "" {
-		return d
-	}
-	return svc.Description
+func registerService(parent *cobra.Command, spec map[string]interface{}, resources map[string]interface{}, f *cmdutil.Factory) {
+	registerServiceWithContext(context.Background(), parent, spec, resources, f)
 }
 
-// ensureChildCommand returns the child of parent named name, creating it (with
-// short) when absent — so re-registration merges into an existing command tree
-// instead of duplicating a level.
-func ensureChildCommand(parent *cobra.Command, name, short string) *cobra.Command {
+func registerServiceWithContext(ctx context.Context, parent *cobra.Command, spec map[string]interface{}, resources map[string]interface{}, f *cmdutil.Factory) {
+	specName := registry.GetStrFromMap(spec, "name")
+	specDesc := registry.GetServiceDescription(specName, "en")
+	if specDesc == "" {
+		specDesc = registry.GetStrFromMap(spec, "description")
+	}
+
+	// Find existing service command or create one
+	var svc *cobra.Command
 	for _, c := range parent.Commands() {
-		if c.Name() == name {
-			return c
+		if c.Name() == specName {
+			svc = c
+			break
 		}
 	}
-	cmd := &cobra.Command{Use: name, Short: short}
-	parent.AddCommand(cmd)
-	return cmd
+	if svc == nil {
+		svc = &cobra.Command{
+			Use:   specName,
+			Short: specDesc,
+		}
+		parent.AddCommand(svc)
+	}
+
+	for resName, resource := range resources {
+		resMap, _ := resource.(map[string]interface{})
+		if resMap == nil {
+			continue
+		}
+		registerResourceWithContext(ctx, svc, spec, resName, resMap, f)
+	}
+}
+
+func registerResourceWithContext(ctx context.Context, parent *cobra.Command, spec map[string]interface{}, name string, resource map[string]interface{}, f *cmdutil.Factory) {
+	res := &cobra.Command{
+		Use:   name,
+		Short: name + " operations",
+	}
+	parent.AddCommand(res)
+
+	methods, _ := resource["methods"].(map[string]interface{})
+	for methodName, method := range methods {
+		methodMap, _ := method.(map[string]interface{})
+		if methodMap == nil {
+			continue
+		}
+		registerMethodWithContext(ctx, res, spec, methodMap, methodName, name, f)
+	}
 }
 
 // ServiceMethodOptions holds all inputs for a dynamically registered service method command.
 type ServiceMethodOptions struct {
-	Factory     *cmdutil.Factory
-	Cmd         *cobra.Command
-	Ctx         context.Context
-	ServicePath string
-	Method      meta.Method
-	SchemaPath  string
+	Factory    *cmdutil.Factory
+	Cmd        *cobra.Command
+	Ctx        context.Context
+	Spec       map[string]interface{}
+	Method     map[string]interface{}
+	SchemaPath string
 
 	// Flags
 	Params     string
@@ -114,113 +121,41 @@ type ServiceMethodOptions struct {
 	DryRun     bool
 	File       string   // --file flag value
 	FileFields []string // auto-detected file field names from metadata
-
-	// binder owns the generated typed param flags — registration and the
-	// --params overlay — replacing the raw paramFlags side-channel.
-	binder *paramFlagBinder
 }
 
-// detectFileFields returns the request-body file-upload field names.
-func detectFileFields(m meta.Method) []string {
-	files := m.Files()
-	if len(files) == 0 {
-		return nil
-	}
-	names := make([]string, len(files))
-	for i, f := range files {
-		names[i] = f.Name
-	}
-	return names
+// detectFileFields delegates to the shared cmdutil.DetectFileFields helper.
+func detectFileFields(method map[string]interface{}) []string {
+	return cmdutil.DetectFileFields(method)
+}
+
+func registerMethodWithContext(ctx context.Context, parent *cobra.Command, spec map[string]interface{}, method map[string]interface{}, name string, resName string, f *cmdutil.Factory) {
+	parent.AddCommand(NewCmdServiceMethodWithContext(ctx, f, spec, method, name, resName, nil))
 }
 
 // NewCmdServiceMethod creates a command for a dynamically registered service method.
-func NewCmdServiceMethod(f *cmdutil.Factory, svc meta.Service, m meta.Method, name, resName string, runF func(*ServiceMethodOptions) error) *cobra.Command {
-	return NewCmdServiceMethodWithContext(context.Background(), f, svc, m, name, resName, runF)
+func NewCmdServiceMethod(f *cmdutil.Factory, spec, method map[string]interface{}, name, resName string, runF func(*ServiceMethodOptions) error) *cobra.Command {
+	return NewCmdServiceMethodWithContext(context.Background(), f, spec, method, name, resName, runF)
 }
 
-// NewCmdServiceMethodWithContext builds the command for one service method from
-// its (service, resource, method) coordinates, deriving the methodCommandSpec
-// via an apicatalog.MethodRef so direct callers and the catalog-driven
-// registration assemble the command identically.
-func NewCmdServiceMethodWithContext(ctx context.Context, f *cmdutil.Factory, svc meta.Service, m meta.Method, name, resName string, runF func(*ServiceMethodOptions) error) *cobra.Command {
-	m.Name = name
-	ref := apicatalog.MethodRef{Service: svc, ResourcePath: []string{resName}, Method: m}
-	// No root in scope here; persistent-flag collisions don't apply to a
-	// standalone command, and local/standard-flag collisions are still caught.
-	return buildMethodCommand(ctx, f, newMethodCommandSpec(ref), runF, nil)
-}
+func NewCmdServiceMethodWithContext(ctx context.Context, f *cmdutil.Factory, spec, method map[string]interface{}, name, resName string, runF func(*ServiceMethodOptions) error) *cobra.Command {
+	desc := registry.GetStrFromMap(method, "description")
+	httpMethod := registry.GetStrFromMap(method, "httpMethod")
+	risk := registry.GetStrFromMap(method, "risk")
+	specName := registry.GetStrFromMap(spec, "name")
+	schemaPath := fmt.Sprintf("%s.%s.%s", specName, resName, name)
 
-// methodCommandSpec is the static description of one generated service method
-// command, read off an apicatalog.MethodRef — the single place command
-// construction gets the method's facts (schema path, HTTP base path, risk,
-// identities, params, file fields, request-body support), so the cobra command
-// is assembled from a typed spec rather than recomputing paths/flags inline.
-type methodCommandSpec struct {
-	method      meta.Method
-	schemaPath  string       // "service.resource.method", for the --help hint
-	servicePath string       // service HTTP base path
-	risk        string       // RiskRead | RiskWrite | RiskHighRiskWrite
-	restricts   bool         // method declares accessTokens (identity-restricted)
-	identities  []string     // permitted --as values; empty when unrestricted
-	params      []meta.Field // path/query params -> typed flags
-	fileFields  []string     // request-body file-upload field names
-	// acceptsBody is whether the HTTP method allows a request body at all (so
-	// --data is offered as a raw escape hatch). declaresBody is whether the
-	// metadata documents body fields (data or file). They differ for e.g. a POST
-	// with no documented requestBody: --data still works, but help must not imply
-	// the API declares a body.
-	acceptsBody  bool
-	declaresBody bool
-	affordance   string // rendered hand-authored usage guidance (when-to-use, examples); "" if none
-}
-
-func newMethodCommandSpec(ref apicatalog.MethodRef) methodCommandSpec {
-	m := ref.Method
-	return methodCommandSpec{
-		method:       m,
-		schemaPath:   ref.SchemaPath(),
-		servicePath:  ref.Service.ServicePath,
-		risk:         m.Risk,
-		restricts:    m.RestrictsIdentity(),
-		identities:   m.Identities(),
-		params:       m.Params(),
-		fileFields:   detectFileFields(m),
-		acceptsBody:  methodTakesBody(m.HTTPMethod),
-		declaresBody: len(m.Data()) > 0 || len(m.Files()) > 0,
-		affordance:   renderAffordance(m),
-	}
-}
-
-// methodTakesBody reports whether the HTTP method allows a request body, i.e.
-// whether --data applies (as a raw escape hatch even when no body is declared).
-func methodTakesBody(httpMethod string) bool {
-	switch httpMethod {
-	case "POST", "PUT", "PATCH", "DELETE":
-		return true
-	}
-	return false
-}
-
-// buildMethodCommand assembles the cobra command for a service method from its
-// static spec: the standard flags, the conditional --data/--file/--yes flags,
-// the generated typed param flags (via paramFlagBinder), and the risk/identity
-// policy annotations.
-func buildMethodCommand(ctx context.Context, f *cmdutil.Factory, spec methodCommandSpec, runF func(*ServiceMethodOptions) error, reserved *pflag.FlagSet) *cobra.Command {
-	m := spec.method
 	opts := &ServiceMethodOptions{
-		Factory:     f,
-		ServicePath: spec.servicePath,
-		Method:      m,
-		SchemaPath:  spec.schemaPath,
-		FileFields:  spec.fileFields,
+		Factory:    f,
+		Spec:       spec,
+		Method:     method,
+		SchemaPath: schemaPath,
 	}
 	var asStr string
 
 	cmd := &cobra.Command{
-		Use:   m.Name,
-		Short: m.Description,
-		// Long is assembled below, once the binder knows which params got no
-		// typed flag.
+		Use:   name,
+		Short: desc,
+		Long:  fmt.Sprintf("%s\n\nView parameter definitions before calling:\n  lark-cli schema %s", desc, schemaPath),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.Cmd = cmd
 			opts.Ctx = cmd.Context()
@@ -232,15 +167,10 @@ func buildMethodCommand(ctx context.Context, f *cmdutil.Factory, spec methodComm
 		},
 	}
 
-	cmd.Flags().StringVar(&opts.Params, "params", "", "Raw URL/query params JSON. Supports - and @file.")
-	if spec.acceptsBody {
-		dataUsage := "JSON request body. Supports - and @file."
-		if !spec.declaresBody {
-			// POST/etc. with no documented body fields: --data is a raw escape
-			// hatch, not a declared body — say so rather than imply structure.
-			dataUsage = "Raw JSON request body (no documented fields; see schema). Supports - and @file."
-		}
-		cmd.Flags().StringVar(&opts.Data, "data", "", dataUsage)
+	cmd.Flags().StringVar(&opts.Params, "params", "", "URL/query parameters JSON (supports - for stdin, @file for file input)")
+	switch httpMethod {
+	case "POST", "PUT", "PATCH", "DELETE":
+		cmd.Flags().StringVar(&opts.Data, "data", "", "request body JSON (supports - for stdin, @file for file input)")
 	}
 	cmdutil.AddAPIIdentityFlag(ctx, cmd, f, &asStr)
 	cmd.Flags().StringVarP(&opts.Output, "output", "o", "", "output file path for binary responses")
@@ -248,64 +178,29 @@ func buildMethodCommand(ctx context.Context, f *cmdutil.Factory, spec methodComm
 	cmd.Flags().IntVar(&opts.PageLimit, "page-limit", 10, "max pages to fetch with --page-all (0 = unlimited)")
 	cmd.Flags().IntVar(&opts.PageDelay, "page-delay", 200, "delay in ms between pages")
 	cmd.Flags().StringVar(&opts.Format, "format", "json", "output format: json|ndjson|table|csv")
-	cmd.Flags().Bool("json", false, "shorthand for --format json")
 	cmd.Flags().StringVarP(&opts.JqExpr, "jq", "q", "", "jq expression to filter JSON output")
 	cmd.Flags().BoolVar(&opts.DryRun, "dry-run", false, "print request without executing")
-	if spec.risk == cmdutil.RiskHighRiskWrite {
+	if risk == "high-risk-write" {
 		cmd.Flags().Bool("yes", false, "confirm high-risk operation")
 	}
-	// --file only for body methods that actually declare file-type fields.
-	if len(spec.fileFields) > 0 && spec.acceptsBody {
-		cmd.Flags().StringVar(&opts.File, "file", "", "File upload [field=]path. Supports - and stdin.")
+
+	// Conditionally register --file for methods with file-type fields.
+	fileFields := detectFileFields(method)
+	opts.FileFields = fileFields
+	if len(fileFields) > 0 {
+		switch httpMethod {
+		case "POST", "PUT", "PATCH", "DELETE":
+			cmd.Flags().StringVar(&opts.File, "file", "", "file to upload ([field=]path, supports - for stdin)")
+		}
 	}
 	cmdutil.RegisterFlagCompletion(cmd, "format", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
 		return []string{"json", "ndjson", "table", "csv"}, cobra.ShellCompDirectiveNoFileComp
 	})
 
-	// Registered last so the collision guard sees the standard flags above.
-	opts.binder = newParamFlagBinder(cmd, spec.params, reserved)
-	// Single composition point for Long: description, affordance, schema
-	// pointer, and the binder's params-only addendum (params whose flag name is
-	// taken, reachable via --params only).
-	cmd.Long = methodLong(m.Description, spec.affordance, spec.schemaPath, opts.binder.paramsOnlyHelp())
-
-	// Group flags for the grouped --help renderer (typed param flags are grouped
-	// as API Parameters by the binder). tagFlagGroup is a no-op for flags not
-	// registered above (e.g. --data/--file/--yes only exist for some methods).
-	// --data sits under Request Body only when the metadata documents body
-	// fields; otherwise it's a raw escape hatch, grouped with --params so help
-	// doesn't imply a declared body the API doesn't have.
-	if fl := cmd.Flags().Lookup("data"); fl != nil {
-		if spec.declaresBody {
-			annotate(fl, flagGroupAnnotation, []string{groupBody})
-		} else {
-			annotate(fl, flagGroupAnnotation, []string{groupRaw})
-		}
-	}
-	tagFlagGroup(cmd.Flags(), "file", groupBody)
-	if fl := cmd.Flags().Lookup("params"); fl != nil {
-		annotate(fl, flagGroupAnnotation, []string{groupRaw})
-		// State the precedence rule where the agent reads it: --params is the
-		// base, typed flags override. Only meaningful when typed flags exist.
-		if len(spec.params) > 0 {
-			annotate(fl, flagNoteAnnotation, []string{
-				"Typed API parameter flags above are preferred.",
-				"If both are set, typed flags override matching keys in --params.",
-			})
-		}
-	}
-	for _, name := range []string{"as", "dry-run", "page-all", "page-limit", "page-delay", "yes"} {
-		tagFlagGroup(cmd.Flags(), name, groupExecution)
-	}
-	for _, name := range []string{"output", "format", "jq"} {
-		tagFlagGroup(cmd.Flags(), name, groupOutput)
-	}
-	applyGroupedUsage(cmd)
-
-	cmdutil.SetTips(cmd, m.Tips)
-	cmdutil.SetRisk(cmd, spec.risk)
-	if spec.restricts {
-		cmdutil.SetSupportedIdentities(cmd, spec.identities)
+	cmdutil.SetTips(cmd, registry.GetStrSliceFromMap(method, "tips"))
+	cmdutil.SetRisk(cmd, risk)
+	if tokens, ok := method["accessTokens"].([]interface{}); ok && len(tokens) > 0 {
+		cmdutil.SetSupportedIdentities(cmd, cmdutil.AccessTokensToIdentities(tokens))
 	}
 
 	return cmd
@@ -320,14 +215,14 @@ func serviceMethodRun(opts *ServiceMethodOptions) error {
 	}
 
 	// Check if this API method supports the resolved identity.
-	if opts.Method.RestrictsIdentity() {
-		if err := f.CheckIdentity(opts.As, opts.Method.Identities()); err != nil {
+	if tokens, ok := opts.Method["accessTokens"].([]interface{}); ok && len(tokens) > 0 {
+		if err := f.CheckIdentity(opts.As, cmdutil.AccessTokensToIdentities(tokens)); err != nil {
 			return err
 		}
 	}
 
 	if opts.PageAll && opts.Output != "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--output and --page-all are mutually exclusive").WithParam("--output")
+		return output.ErrValidation("--output and --page-all are mutually exclusive")
 	}
 	if err := output.ValidateJqFlags(opts.JqExpr, opts.Output, opts.Format); err != nil {
 		return err
@@ -337,10 +232,12 @@ func serviceMethodRun(opts *ServiceMethodOptions) error {
 	if err != nil {
 		return err
 	}
-	// Identity is not printed to stderr here: it is part of the JSON envelope.
+	// Identity info is now included in the JSON envelope; skip stderr printing.
+	// cmdutil.PrintIdentity(f.IOStreams.ErrOut, opts.As, config, f.IdentityAutoDetected)
 
+	scopes, _ := opts.Method["scopes"].([]interface{})
 	if !opts.As.IsBot() {
-		if err := checkServiceScopes(opts.Ctx, f.Credential, opts.As, config, opts.Method); err != nil {
+		if err := checkServiceScopes(opts.Ctx, f.Credential, opts.As, config, opts.Method, scopes); err != nil {
 			return err
 		}
 	}
@@ -357,7 +254,7 @@ func serviceMethodRun(opts *ServiceMethodOptions) error {
 		return serviceDryRun(f, request, config, opts.Format)
 	}
 
-	if opts.Method.Risk == cmdutil.RiskHighRiskWrite {
+	if registry.GetStrFromMap(opts.Method, "risk") == "high-risk-write" {
 		if yes, _ := opts.Cmd.Flags().GetBool("yes"); !yes {
 			return cmdutil.RequireConfirmation(opts.SchemaPath)
 		}
@@ -374,10 +271,12 @@ func serviceMethodRun(opts *ServiceMethodOptions) error {
 		fmt.Fprintf(f.IOStreams.ErrOut, "warning: unknown format %q, falling back to json\n", opts.Format)
 	}
 
-	// Scope-insufficient (99991679) and all other Lark API codes route through
-	// errclass.BuildAPIError via ac.CheckResponse, producing *errs.PermissionError
-	// with MissingScopes / Identity / ConsoleURL populated from the response.
-	checkErr := ac.CheckResponse
+	// Stage 1: enrich the 99991679 (LarkErrUserScopeInsufficient) response
+	// with a per-method recommended `--scope` hint, matching the pre-PR
+	// behaviour. Per-domain typed migration in stage 2+ will lift this
+	// into PermissionError.MissingScopes / ConsoleURL on the typed
+	// envelope; until then the legacy ExitError envelope is preserved.
+	checkErr := scopeAwareChecker(scopes, opts.As.IsBot())
 
 	if opts.PageAll {
 		return servicePaginate(opts.Ctx, ac, request, format, opts.JqExpr, out, f.IOStreams.ErrOut,
@@ -401,8 +300,53 @@ func serviceMethodRun(opts *ServiceMethodOptions) error {
 	})
 }
 
+// scopeAwareChecker returns an error checker that enriches the
+// LarkErrUserScopeInsufficient (99991679) business error with a
+// per-method recommended `--scope` hint. All other non-zero codes fall
+// through to legacy output.ErrAPI (matching pre-PR behaviour). The
+// identity parameter is accepted to match the client.ResponseOptions
+// CheckError signature; isBotMode is captured from the enclosing call so
+// the recommended scope reflects the caller's identity at request time.
+//
+// Deprecated: stage-1 enrichment for the legacy *output.ExitError envelope.
+// Stage-2 typed migration will lift this into PermissionError.MissingScopes
+// + ConsoleURL on the typed envelope and remove this helper.
+func scopeAwareChecker(scopes []interface{}, isBotMode bool) func(interface{}, core.Identity) error {
+	return func(result interface{}, _ core.Identity) error {
+		resultMap, ok := result.(map[string]interface{})
+		if !ok || resultMap == nil {
+			return nil
+		}
+		code, _ := util.ToFloat64(resultMap["code"])
+		if code == 0 {
+			return nil
+		}
+		larkCode := int(code)
+		msg := registry.GetStrFromMap(resultMap, "msg")
+
+		if larkCode == output.LarkErrUserScopeInsufficient && len(scopes) > 0 {
+			identity := "user"
+			if isBotMode {
+				identity = "tenant"
+			}
+			recommended := registry.SelectRecommendedScope(scopes, identity)
+			// Stage-1 carve-out: this restores the pre-PR scope-insufficient
+			// enrichment (recommended scope + auth-login hint) on the legacy
+			// envelope. The typed migration in stage 2+ will lift this into
+			// PermissionError.MissingScopes / ConsoleURL on the typed wire.
+			return output.ErrWithHint(output.ExitAPI, "permission",
+				fmt.Sprintf("insufficient permissions: [%d] %s", larkCode, msg),
+				fmt.Sprintf("run `lark-cli auth login --scope \"%s\"` in the background. It blocks and outputs a verification URL — retrieve the URL and open it in a browser to complete login.", recommended))
+		}
+
+		// Stage-1 carve-out: matches pre-PR behaviour (legacy ExitError +
+		// ClassifyLarkError). Typed migration is stage-2+.
+		return output.ErrAPI(larkCode, fmt.Sprintf("API error: [%d] %s", larkCode, msg), resultMap["error"])
+	}
+}
+
 // checkServiceScopes pre-checks user scopes before making the API call.
-func checkServiceScopes(ctx context.Context, cred *credential.CredentialProvider, identity core.Identity, config *core.CliConfig, method meta.Method) error {
+func checkServiceScopes(ctx context.Context, cred *credential.CredentialProvider, identity core.Identity, config *core.CliConfig, method map[string]interface{}, scopes []interface{}) error {
 	if ctx.Err() != nil {
 		return ctx.Err()
 	}
@@ -411,15 +355,25 @@ func checkServiceScopes(ctx context.Context, cred *credential.CredentialProvider
 		return nil //nolint:nilerr // skip scope check when token resolution fails or has no scopes
 	}
 
-	if len(method.RequiredScopes) > 0 {
+	requiredScopes, hasRequired := method["requiredScopes"].([]interface{})
+
+	if hasRequired && len(requiredScopes) > 0 {
 		// Strict: ALL requiredScopes must be present
-		if missing := auth.MissingScopes(result.Scopes, method.RequiredScopes); len(missing) > 0 {
-			return newPreflightMissingScopeError(string(config.Brand), config.AppID, string(identity), missing)
+		required := make([]string, 0, len(requiredScopes))
+		for _, s := range requiredScopes {
+			if str, ok := s.(string); ok {
+				required = append(required, str)
+			}
+		}
+		if missing := auth.MissingScopes(result.Scopes, required); len(missing) > 0 {
+			return output.ErrWithHint(output.ExitAuth, "missing_scope",
+				fmt.Sprintf("missing required scope(s): %s", strings.Join(missing, ", ")),
+				fmt.Sprintf("run `lark-cli auth login --scope \"%s\"` in the background. It blocks and outputs a verification URL — retrieve the URL and open it in a browser to complete login.", strings.Join(missing, " ")))
 		}
 		return nil
 	}
 
-	if len(method.Scopes) == 0 {
+	if len(scopes) == 0 {
 		return nil
 	}
 
@@ -428,70 +382,25 @@ func checkServiceScopes(ctx context.Context, cred *credential.CredentialProvider
 	for _, s := range strings.Fields(result.Scopes) {
 		grantedSet[s] = true
 	}
-	for _, s := range method.Scopes {
-		if grantedSet[s] {
+	for _, s := range scopes {
+		if str, ok := s.(string); ok && grantedSet[str] {
 			return nil
 		}
 	}
-	recommended := registry.SelectRecommendedScopeFromStrings(method.Scopes, "user")
-	return newPreflightMissingScopeError(string(config.Brand), config.AppID, string(identity), []string{recommended})
-}
-
-// newPreflightMissingScopeError constructs a PermissionError for the local
-// pre-flight scope check that converges byte-for-byte with the dispatcher's
-// BuildAPIError path. Uses the canonical helpers in internal/errclass so
-// Hint and Message stay in lock-step with the server-response classifier.
-// ConsoleURL is deliberately omitted: the dispatcher only sets it for
-// SubtypeAppScopeNotApplied (bot-perspective dev-action recovery), and this
-// pre-flight path is user-perspective SubtypeMissingScope whose recovery is
-// `lark-cli auth login --scope ...`, not a console deep-link.
-func newPreflightMissingScopeError(brand, appID, identity string, missing []string) *errs.PermissionError {
-	consoleURL := errclass.ConsoleURL(brand, appID, missing)
-	return errs.NewPermissionError(errs.SubtypeMissingScope,
-		"%s", errclass.CanonicalPermissionMessage(errs.SubtypeMissingScope, appID, missing, "")).
-		WithHint("%s", errclass.PermissionHint(missing, identity, errs.SubtypeMissingScope, consoleURL)).
-		WithMissingScopes(missing...).
-		WithIdentity(identity)
-}
-
-// unusableParamValue reports whether a provided path/query parameter value
-// cannot form a usable request value: nil or an empty string. A key's presence
-// in params is the intent signal — a typed flag is overlaid only when
-// explicitly Changed, and a --params JSON key is deliberately written — so
-// false and 0 are real values and must not be conflated with "unset"
-// (reflect.IsZero would drop an explicit --with-deleted=false or --foo 0).
-// Only nil/"" stay treated as missing: that keeps the friendly pre-flight
-// error when a required param is fed an empty placeholder, and never emits a
-// declared param as an empty path segment or query value. Undeclared keys are
-// not judged by this rule — they pass through verbatim as the raw escape hatch.
-func unusableParamValue(v interface{}) bool {
-	if v == nil {
-		return true
-	}
-	s, ok := v.(string)
-	return ok && s == ""
-}
-
-// missingParamHint is the recovery hint for a missing required parameter. It
-// names both input paths — the typed flag when the binder registered one, and
-// the --params fallback — plus the schema pointer. A params-only field gets
-// only the --params form: a flag with its kebab name exists but belongs to
-// something else (e.g. the output --format), and the hint must not steer
-// there. Asking the binder, not cmd.Flags(), is what tells those apart.
-func missingParamHint(opts *ServiceMethodOptions, f meta.Field) string {
-	paramsForm := fmt.Sprintf("--params '{%q: \"<value>\"}'", f.Name)
-	if opts.binder.hasTypedFlag(f.Name) {
-		return fmt.Sprintf("set --%s <value> (or %s); see: lark-cli schema %s", f.FlagName(), paramsForm, opts.SchemaPath)
-	}
-	return fmt.Sprintf("set %s; see: lark-cli schema %s", paramsForm, opts.SchemaPath)
+	recommended := registry.SelectRecommendedScope(scopes, "user")
+	return output.ErrWithHint(output.ExitAPI, "permission",
+		fmt.Sprintf("insufficient permissions (required scope: %s)", recommended),
+		fmt.Sprintf("run `lark-cli auth login --scope \"%s\"` in the background. It blocks and outputs a verification URL — retrieve the URL and open it in a browser to complete login.", recommended))
 }
 
 // buildServiceRequest parses flags, builds the URL with path/query params, and returns a RawApiRequest.
 // When dryRun is true and a file is provided, file reading is skipped and
 // FileUploadMeta is returned instead so the caller can render dry-run output.
 func buildServiceRequest(opts *ServiceMethodOptions) (client.RawApiRequest, *cmdutil.FileUploadMeta, error) {
+	spec := opts.Spec
 	method := opts.Method
-	httpMethod := method.HTTPMethod
+	schemaPath := opts.SchemaPath
+	httpMethod := registry.GetStrFromMap(method, "httpMethod")
 
 	// stdin is an io.Reader consumed at most once. Only one of --params/--data
 	// may use "-" (stdin); the conflict check below prevents silent data loss.
@@ -503,61 +412,57 @@ func buildServiceRequest(opts *ServiceMethodOptions) (client.RawApiRequest, *cmd
 		return client.RawApiRequest{}, nil, err
 	}
 	if opts.Params == "-" && opts.Data == "-" {
-		return client.RawApiRequest{}, nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--params and --data cannot both read from stdin (-)").WithParam("--params")
+		return client.RawApiRequest{}, nil, output.ErrValidation("--params and --data cannot both read from stdin (-)")
 	}
 	params, err := cmdutil.ParseJSONMap(opts.Params, "--params", stdin, fileIO)
 	if err != nil {
 		return client.RawApiRequest{}, nil, err
 	}
-	opts.binder.overlay(opts.Cmd, params)
 
-	url := opts.ServicePath + "/" + method.Path
+	url := registry.GetStrFromMap(spec, "servicePath") + "/" + registry.GetStrFromMap(method, "path")
 
-	specs := method.Params()
-	for _, s := range specs {
-		if s.Location != "path" {
+	parameters, _ := method["parameters"].(map[string]interface{})
+	for name, param := range parameters {
+		p, _ := param.(map[string]interface{})
+		if registry.GetStrFromMap(p, "location") != "path" {
 			continue
 		}
-		val, ok := params[s.Name]
-		if !ok || unusableParamValue(val) {
-			return client.RawApiRequest{}, nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"missing required path parameter: %s", s.Name).
-				WithHint("%s", missingParamHint(opts, s)).
-				WithParam(s.Name)
+		val, ok := params[name]
+		if !ok || util.IsEmptyValue(val) {
+			return client.RawApiRequest{}, nil, output.ErrWithHint(output.ExitValidation, "validation",
+				fmt.Sprintf("missing required path parameter: %s", name),
+				fmt.Sprintf("lark-cli schema %s", schemaPath))
 		}
 		valStr := fmt.Sprintf("%v", val)
-		if err := validate.ResourceName(valStr, s.Name); err != nil {
-			return client.RawApiRequest{}, nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam(s.Name).WithCause(err)
+		if err := validate.ResourceName(valStr, name); err != nil {
+			return client.RawApiRequest{}, nil, output.ErrValidation("%s", err)
 		}
-		url = strings.Replace(url, "{"+s.Name+"}", validate.EncodePathSegment(valStr), 1)
-		delete(params, s.Name)
+		url = strings.Replace(url, "{"+name+"}", validate.EncodePathSegment(valStr), 1)
+		delete(params, name)
 	}
 
 	queryParams := map[string]interface{}{}
-	for _, s := range specs {
-		if s.Location != "query" {
+	for name, param := range parameters {
+		p, _ := param.(map[string]interface{})
+		if registry.GetStrFromMap(p, "location") != "query" {
 			continue
 		}
-		value, exists := params[s.Name]
-		isPaginationParam := opts.PageAll && (s.Name == "page_token" || s.Name == "page_size")
-		if s.Required && !isPaginationParam && (!exists || unusableParamValue(value)) {
-			return client.RawApiRequest{}, nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"missing required query parameter: %s", s.Name).
-				WithHint("%s", missingParamHint(opts, s)).
-				WithParam(s.Name)
+		value, exists := params[name]
+		required, _ := p["required"].(bool)
+		isPaginationParam := opts.PageAll && (name == "page_token" || name == "page_size")
+		if required && !isPaginationParam && (!exists || util.IsEmptyValue(value)) {
+			return client.RawApiRequest{}, nil, output.ErrWithHint(output.ExitValidation, "validation",
+				fmt.Sprintf("missing required query parameter: %s", name),
+				fmt.Sprintf("lark-cli schema %s", schemaPath))
 		}
-		if exists && !unusableParamValue(value) {
-			queryParams[s.Name] = value
+		if exists && !util.IsEmptyValue(value) {
+			queryParams[name] = value
 		}
-		// This loop owns declared query params: consume the key so the
-		// passthrough below can't resurrect a value the gate dropped (an
-		// unusable "" would otherwise be sent as an empty query value).
-		delete(params, s.Name)
 	}
-	// Whatever remains is undeclared — the raw escape hatch for params the
-	// metadata doesn't (yet) describe; passed through verbatim, no filtering.
 	for name, value := range params {
-		queryParams[name] = value
+		if _, ok := queryParams[name]; !ok {
+			queryParams[name] = value
+		}
 	}
 
 	request := client.RawApiRequest{
@@ -583,7 +488,7 @@ func buildServiceRequest(opts *ServiceMethodOptions) (client.RawApiRequest, *cmd
 				return client.RawApiRequest{}, nil, err
 			}
 			if _, ok := dataFields.(map[string]any); !ok {
-				return client.RawApiRequest{}, nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--data must be a JSON object when used with --file").WithParam("--data")
+				return client.RawApiRequest{}, nil, output.ErrValidation("--data must be a JSON object when used with --file")
 			}
 		}
 

cmd/service/service_risk_test.go

@@ -8,14 +8,13 @@ import (
 	"testing"
 
 	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/meta"
 )
 
 // highRiskDeleteMethod mirrors a simple DELETE API with a required path
-// parameter and risk metadata. The test exercises --yes registration and the
-// gate behavior.
-func highRiskDeleteMethod() meta.Method {
-	return meta.FromMap(map[string]interface{}{
+// parameter and risk metadata. The returned map is what service registration
+// reads; the test exercises --yes registration and the gate behavior.
+func highRiskDeleteMethod() map[string]interface{} {
+	return map[string]interface{}{
 		"path":       "files/{file_token}",
 		"httpMethod": "DELETE",
 		"risk":       "high-risk-write",
@@ -24,11 +23,11 @@ func highRiskDeleteMethod() meta.Method {
 				"type": "string", "location": "path", "required": true,
 			},
 		},
-	})
+	}
 }
 
-func writeMethodNoRisk() meta.Method {
-	return meta.FromMap(map[string]interface{}{
+func writeMethodNoRisk() map[string]interface{} {
+	return map[string]interface{}{
 		"path":       "files/{file_token}",
 		"httpMethod": "DELETE",
 		"parameters": map[string]interface{}{
@@ -36,7 +35,7 @@ func writeMethodNoRisk() meta.Method {
 				"type": "string", "location": "path", "required": true,
 			},
 		},
-	})
+	}
 }
 
 func TestServiceMethod_YesFlagRegisteredForHighRisk(t *testing.T) {