perf(startup): resolve brand & strict-mode without decrypting the app secret

Building the command tree resolved brand (auth login --domain help) and
strict mode (per-command identity-flag registration via ResolveStrictMode)
through f.Config(), which decrypts the app secret. On macOS that is a
Keychain (securityd IPC) read on every invocation -- even --help/--version/
schema/completion, which never use the secret.

brand and strict mode are plain config.json fields, so route them through a
secret-free metadata path:
- credential: add (*DefaultAccountProvider).ResolveMeta and a cached
  (*CredentialProvider).ResolveMeta returning brand + SupportedIdentities,
  via an optional metaResolver capability; external providers fall back to
  ResolveAccount (they do not touch the keychain).
- cmdutil: ResolveStrictMode now uses ResolveMeta; add Factory.ConfigBrand.
- auth login help text and shortcut registration read ConfigBrand.

The app secret is still decrypted on demand when a command actually calls
the API (auth status etc. unchanged). Measured on macOS (GOMAXPROCS=1):
lark-cli --help 35.4ms -> 21.4ms (-40%); no behavior change on Linux/Windows
(local secret backends are cheap).

.gitignore

@@ -36,6 +36,7 @@ tests/mail/reports/
 .hammer/
 .lark-slides/
 internal/registry/meta_data.json
+internal/registry/metastatic/meta_data_gen.go
 cmd/api/download.bin
 app.log
 /sidecar-server-demo

.golangci.yml

@@ -57,6 +57,14 @@ linters:
       - 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.
       - path-except: shortcuts/
@@ -65,10 +73,23 @@ linters:
           - forbidigo
       # errs-typed-only enforced on paths already migrated to errs.NewXxxError.
       # Add a path when its migration is complete.
-      - path-except: (internal/auth/|internal/errcompat/|internal/errclass/|internal/client/|internal/cmdutil/factory\.go|cmd/auth/|cmd/config/|cmd/service/|shortcuts/common/mcp_client\.go|shortcuts/calendar/helpers\.go)
+      - 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/base/|shortcuts/calendar/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/minutes/|shortcuts/okr/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/)
         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/base/|shortcuts/calendar/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/minutes/|shortcuts/okr/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|shortcuts/common/mcp_client\.go)
+        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/base/|shortcuts/calendar/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/minutes/|shortcuts/okr/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/)
+        text: errs-no-legacy-helper
+        linters:
+          - forbidigo
 
   settings:
     depguard:
@@ -94,6 +115,21 @@ linters:
           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

@@ -2,6 +2,8 @@ version: 2
 
 before:
   hooks:
+    # fetch_meta.py also regenerates the static Go registry (meta_data_gen.go),
+    # the sole source of the embedded command tree.
     - python3 scripts/fetch_meta.py
 
 builds:

CHANGELOG.md

@@ -2,6 +2,68 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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
@@ -964,6 +1026,9 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[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

Makefile

@@ -12,6 +12,9 @@ PREFIX   ?= /usr/local
 
 all: test
 
+# fetch_meta fetches meta_data.json AND regenerates the static Go registry
+# (internal/registry/metastatic/meta_data_gen.go) — the sole build-time source
+# of the embedded command tree. Both are gitignored; build/vet/test depend on it.
 fetch_meta:
 	python3 scripts/fetch_meta.py
 

cmd/api/api.go

@@ -90,6 +90,7 @@ func NewCmdApiWithContext(ctx context.Context, f *cmdutil.Factory, runF func(*AP
 	cmd.Flags().IntVar(&opts.PageLimit, "page-limit", 10, "max pages to fetch with --page-all (0 = unlimited)")
 	cmd.Flags().IntVar(&opts.PageDelay, "page-delay", 200, "delay in ms between pages")
 	cmd.Flags().StringVar(&opts.Format, "format", "json", "output format: json|ndjson|table|csv")
+	cmd.Flags().Bool("json", false, "shorthand for --format json")
 	cmd.Flags().StringVarP(&opts.JqExpr, "jq", "q", "", "jq expression to filter JSON output")
 	cmd.Flags().BoolVar(&opts.DryRun, "dry-run", false, "print request without executing")
 	cmd.Flags().StringVar(&opts.File, "file", "", "file to upload as multipart/form-data ([field=]path, supports - for stdin)")

cmd/api/api_test.go

@@ -718,3 +718,23 @@ func TestApiCmd_PermissionError_DerivesFirstClassFields(t *testing.T) {
 		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/login.go

@@ -72,10 +72,12 @@ to generate QR codes (supports ASCII and PNG formats).`,
 
 	cmd.Flags().StringVar(&opts.Scope, "scope", "", "scopes to request (space- or comma-separated). Combines additively with --domain/--recommend")
 	cmd.Flags().BoolVar(&opts.Recommend, "recommend", false, "request only recommended (auto-approve) scopes")
+	// Brand only — never decrypt the app secret just to build help text
+	// (avoids a keychain read on every `auth login --help` / completion).
 	var helpBrand core.LarkBrand
-	if f != nil && f.Config != nil {
-		if cfg, err := f.Config(); err == nil && cfg != nil {
-			helpBrand = cfg.Brand
+	if f != nil && f.ConfigBrand != nil {
+		if b, ok := f.ConfigBrand(); ok {
+			helpBrand = b
 		}
 	}
 	available := sortedKnownDomains(helpBrand)

cmd/build.go

@@ -6,6 +6,7 @@ package cmd
 import (
 	"context"
 	"io"
+	"io/fs"
 
 	"github.com/larksuite/cli/cmd/api"
 	"github.com/larksuite/cli/cmd/auth"
@@ -16,6 +17,7 @@ import (
 	"github.com/larksuite/cli/cmd/profile"
 	"github.com/larksuite/cli/cmd/schema"
 	"github.com/larksuite/cli/cmd/service"
+	"github.com/larksuite/cli/cmd/skill"
 	cmdupdate "github.com/larksuite/cli/cmd/update"
 	_ "github.com/larksuite/cli/events"
 	"github.com/larksuite/cli/internal/build"
@@ -51,6 +53,18 @@ func WithKeychain(kc keychain.KeychainAccess) BuildOption {
 	}
 }
 
+// embeddedSkillContent is the skill tree wired into cmdutil.Factory.SkillContent
+// at build time. It is registered by the repo-root package main's init via
+// SetEmbeddedSkillContent — it cannot be threaded through main.go without
+// breaking the single-file preview build (see skills_embed.go). nil in builds
+// that embed no skills; the `skills` commands then return a typed internal error.
+var embeddedSkillContent fs.FS
+
+// SetEmbeddedSkillContent registers the embedded skill tree. Called from the
+// repo-root package main's init; a wrapper main can call it before Execute to
+// supply its own skill content.
+func SetEmbeddedSkillContent(fsys fs.FS) { embeddedSkillContent = fsys }
+
 // HideProfile sets the visibility policy for the root-level --profile flag.
 // When hide is true the flag stays registered (so existing invocations still
 // parse) but is omitted from help and shell completion. Typically called as
@@ -103,6 +117,7 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 	if cfg.keychain != nil {
 		f.Keychain = cfg.keychain
 	}
+	f.SkillContent = embeddedSkillContent
 	rootCmd := &cobra.Command{
 		Use:     "lark-cli",
 		Short:   "Lark/Feishu CLI — OAuth authorization, UAT management, API calls",
@@ -140,6 +155,7 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 	rootCmd.AddCommand(completion.NewCmdCompletion(f))
 	rootCmd.AddCommand(cmdupdate.NewCmdUpdate(f))
 	rootCmd.AddCommand(cmdevent.NewCmdEvents(f))
+	rootCmd.AddCommand(skill.NewCmdSkill(f))
 	service.RegisterServiceCommandsWithContext(ctx, rootCmd, f)
 	shortcuts.RegisterShortcutsWithContext(ctx, rootCmd, f)
 

cmd/cmdexample_catalog_test.go

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

cmd/cmdexample_check_test.go

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

cmd/cmdexample_parse_test.go

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

cmd/cmdexample_test.go

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

cmd/cmdexample_units_test.go

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

cmd/command_tree_dump_test.go

@@ -0,0 +1,87 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Tree-dump tool: dumps the full command tree (paths, flags, descriptions,
+// annotations) in a canonical, line-stable form so two builds can be diffed
+// byte-for-byte (e.g. before/after a registry change). Set LARK_TREE_DUMP=<path>
+// to write the dump; otherwise the test is a no-op. Not a committed golden — the
+// meta data is fetched/gitignored and drifts.
+package cmd_test
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/cmd"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+func esc(s string) string {
+	s = strings.ReplaceAll(s, "\\", "\\\\")
+	s = strings.ReplaceAll(s, "\n", "\\n")
+	s = strings.ReplaceAll(s, "\t", "\\t")
+	s = strings.ReplaceAll(s, "\r", "\\r")
+	return s
+}
+
+func dumpCommandTree(root *cobra.Command) string {
+	var lines []string
+	var walk func(c *cobra.Command)
+	walk = func(c *cobra.Command) {
+		path := strings.TrimSpace(strings.TrimPrefix(c.CommandPath(), "lark-cli"))
+		head := fmt.Sprintf("CMD %q use=%q short=%q long=%q runnable=%t hidden=%t",
+			path, esc(c.Use), esc(c.Short), esc(c.Long), c.Runnable(), c.Hidden)
+		lines = append(lines, head)
+
+		if len(c.Annotations) > 0 {
+			keys := make([]string, 0, len(c.Annotations))
+			for k := range c.Annotations {
+				keys = append(keys, k)
+			}
+			sort.Strings(keys)
+			for _, k := range keys {
+				lines = append(lines, fmt.Sprintf("  ann %s=%q", k, esc(c.Annotations[k])))
+			}
+		}
+
+		var flags []string
+		c.Flags().VisitAll(func(f *pflag.Flag) {
+			flags = append(flags, fmt.Sprintf("  flag --%s -%s type=%s def=%q usage=%q",
+				f.Name, f.Shorthand, f.Value.Type(), esc(f.DefValue), esc(f.Usage)))
+		})
+		sort.Strings(flags)
+		lines = append(lines, flags...)
+
+		subs := c.Commands()
+		sort.Slice(subs, func(i, j int) bool { return subs[i].Name() < subs[j].Name() })
+		for _, sub := range subs {
+			walk(sub)
+		}
+	}
+	walk(root)
+	return strings.Join(lines, "\n") + "\n"
+}
+
+func TestDumpCommandTree(t *testing.T) {
+	out := os.Getenv("LARK_TREE_DUMP")
+	if out == "" {
+		t.Skip("set LARK_TREE_DUMP=<path> to dump the command tree")
+	}
+	// Deterministic: embedded meta only (no remote cache), empty config dir so
+	// strict-mode/plugins/policy cannot reshape the tree.
+	t.Setenv("LARKSUITE_CLI_REMOTE_META", "off")
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	root := cmd.Build(context.Background(), cmdutil.InvocationContext{})
+	dump := dumpCommandTree(root)
+	if err := os.WriteFile(out, []byte(dump), 0644); err != nil {
+		t.Fatal(err)
+	}
+	t.Logf("wrote %d bytes, %d lines to %s", len(dump), strings.Count(dump, "\n"), out)
+}

cmd/config/init.go

@@ -341,6 +341,9 @@ func configInitRun(opts *ConfigInitOptions) error {
 		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
 	}
 
@@ -380,6 +383,9 @@ func configInitRun(opts *ConfigInitOptions) error {
 		}
 		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
 	}
 
@@ -419,6 +425,11 @@ func configInitRun(opts *ConfigInitOptions) error {
 			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
 	}
 
@@ -507,5 +518,10 @@ func configInitRun(opts *ConfigInitOptions) error {
 	}
 	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

@@ -16,7 +16,7 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/util"
+	"github.com/larksuite/cli/internal/transport"
 )
 
 // configInitResult holds the result of the interactive config init flow.
@@ -179,7 +179,7 @@ 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 := util.NewHTTPClient(0)
+	httpClient := transport.NewHTTPClient(0)
 	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)

cmd/config/init_probe.go

@@ -0,0 +1,91 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package config
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"time"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/build"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/credential"
+)
+
+// probeTimeout is the total wall-clock budget for the credential probe step
+// (covering both TAT acquisition and the subsequent probe request).
+const probeTimeout = 3 * time.Second
+
+// runProbe runs a best-effort credential validation after config init has
+// persisted the App ID and App Secret. It returns a non-nil error only for a
+// deterministic credential-rejection signal; every other outcome returns nil
+// so that valid configurations and transient/upstream noise never block the
+// command.
+//
+// The function performs up to two HTTP calls in series, bounded by
+// probeTimeout:
+//
+//  1. A TAT request using the just-saved credentials. credential.FetchTAT
+//     returns a typed errs.* error (via the shared classifyTATResponseCode)
+//     only when the server deterministically rejected the credentials — a
+//     non-zero TAT body code, classified as CategoryConfig / SubtypeInvalidClient
+//     (10003 / 10014) or whatever codemeta maps. That typed error is propagated
+//     so the root dispatcher renders the canonical envelope and `config init`
+//     exits non-zero — identical to how every other token-resolving command
+//     reports the same bad credentials. Ambiguous failures (transport errors,
+//     HTTP non-200, JSON parse errors, timeouts) come back as raw untyped
+//     errors and are swallowed (return nil), so valid configurations are never
+//     disturbed by upstream noise. errs.IsTyped is the discriminator.
+//
+//  2. If TAT succeeded, a POST to the probe endpoint is fired. The outcome of
+//     that call (success, server error, timeout, parse failure) is always
+//     ignored — return nil regardless.
+func runProbe(parent context.Context, factory *cmdutil.Factory, appID, appSecret string, brand core.LarkBrand) error {
+	if factory == nil {
+		return nil
+	}
+	httpClient, err := factory.HttpClient()
+	if err != nil {
+		return nil
+	}
+
+	ctx, cancel := context.WithTimeout(parent, probeTimeout)
+	defer cancel()
+
+	token, err := credential.FetchTAT(ctx, httpClient, brand, appID, appSecret)
+	if err != nil {
+		// A typed error from FetchTAT is a deterministic credential rejection
+		// (classifyTATResponseCode). Propagate it so config init exits with the
+		// same envelope the rest of the CLI uses for bad credentials. Untyped
+		// errors are ambiguous (transport / HTTP / parse / timeout) — stay
+		// silent and let the command succeed.
+		if errs.IsTyped(err) {
+			return err
+		}
+		return nil
+	}
+
+	// TAT succeeded — fire the probe call. Any outcome is ignored.
+	url := core.ResolveEndpoints(brand).Open + "/open-apis/application/v6/larksuite_cli_app/probe"
+	body := []byte(fmt.Sprintf(`{"from":"lark-cli/%s"}`, build.Version))
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body))
+	if err != nil {
+		return nil
+	}
+	req.Header.Set("Authorization", "Bearer "+token)
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := httpClient.Do(req)
+	if err != nil {
+		return nil
+	}
+	defer resp.Body.Close()
+	_, _ = io.Copy(io.Discard, resp.Body)
+	return nil
+}

cmd/config/init_probe_test.go

@@ -0,0 +1,288 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package config
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/build"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+)
+
+// fakeRT routes requests to per-path handlers and records what it saw.
+type fakeRT struct {
+	tatHandler   func(req *http.Request) (*http.Response, error)
+	probeHandler func(req *http.Request) (*http.Response, error)
+	tatCalls     int
+	probeCalls   int
+	probeReq     *http.Request
+	probeBody    string
+}
+
+func (f *fakeRT) RoundTrip(req *http.Request) (*http.Response, error) {
+	switch {
+	case strings.HasSuffix(req.URL.Path, "/auth/v3/tenant_access_token/internal"):
+		f.tatCalls++
+		if f.tatHandler == nil {
+			return jsonResp(200, `{"code":0,"tenant_access_token":"t-ok"}`), nil
+		}
+		return f.tatHandler(req)
+	case strings.HasSuffix(req.URL.Path, "/application/v6/larksuite_cli_app/probe"):
+		f.probeCalls++
+		f.probeReq = req
+		if req.Body != nil {
+			b, _ := io.ReadAll(req.Body)
+			f.probeBody = string(b)
+		}
+		if f.probeHandler == nil {
+			return jsonResp(200, `{"code":0,"data":{},"msg":"success"}`), nil
+		}
+		return f.probeHandler(req)
+	}
+	return nil, errors.New("unexpected URL: " + req.URL.String())
+}
+
+func jsonResp(code int, body string) *http.Response {
+	return &http.Response{
+		StatusCode: code,
+		Body:       io.NopCloser(strings.NewReader(body)),
+		Header:     make(http.Header),
+	}
+}
+
+// fakeFactory builds a test Factory whose HttpClient is overridden to use
+// the caller-supplied RoundTripper.
+//
+// Wired through cmdutil.TestFactory(t, nil) so the canonical IOStreams,
+// Credential, Keychain and FileIO wiring is in place (per repo test-factory
+// guidance). The HttpClient is then swapped to our stub so we can drive
+// exact HTTP responses for the probe. Config-dir isolation is set up via
+// t.Setenv(LARKSUITE_CLI_CONFIG_DIR, t.TempDir()) so any incidental config
+// touch lands in a temp dir rather than the developer's real config.
+//
+// The returned buffer is the Factory's stderr. runProbe never writes to
+// stderr (it propagates a typed error or stays silent), so every test asserts
+// this buffer stays empty as an invariant.
+func fakeFactory(t *testing.T, rt http.RoundTripper) (*cmdutil.Factory, *bytes.Buffer) {
+	t.Helper()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, errBuf, _ := cmdutil.TestFactory(t, nil)
+	f.HttpClient = func() (*http.Client, error) {
+		return &http.Client{Transport: rt}, nil
+	}
+	return f, errBuf
+}
+
+// assertConfigRejection asserts runProbe propagated a deterministic credential
+// rejection: a *errs.ConfigError (CategoryConfig / SubtypeInvalidClient) with
+// the expected upstream code. This is the same typed error every other
+// token-resolving command returns for the same bad credentials, and nothing is
+// written to stderr (the root dispatcher renders the envelope).
+func assertConfigRejection(t *testing.T, err error, errBuf *bytes.Buffer, wantCode int) {
+	t.Helper()
+	if err == nil {
+		t.Fatalf("expected *errs.ConfigError (code %d), got nil", wantCode)
+	}
+	var cfgErr *errs.ConfigError
+	if !errors.As(err, &cfgErr) {
+		t.Fatalf("expected *errs.ConfigError, got %T: %v", err, err)
+	}
+	if cfgErr.Category != errs.CategoryConfig {
+		t.Errorf("Category = %q, want %q", cfgErr.Category, errs.CategoryConfig)
+	}
+	if cfgErr.Subtype != errs.SubtypeInvalidClient {
+		t.Errorf("Subtype = %q, want %q", cfgErr.Subtype, errs.SubtypeInvalidClient)
+	}
+	if cfgErr.Code != wantCode {
+		t.Errorf("Code = %d, want %d", cfgErr.Code, wantCode)
+	}
+	if errBuf.Len() != 0 {
+		t.Errorf("runProbe must not write to stderr, got: %q", errBuf.String())
+	}
+}
+
+// assertSilent asserts runProbe stayed quiet: no propagated error and nothing
+// written to stderr. Used for every ambiguous (non-credential) outcome.
+func assertSilent(t *testing.T, err error, errBuf *bytes.Buffer) {
+	t.Helper()
+	if err != nil {
+		t.Errorf("expected nil (silent), got error: %v", err)
+	}
+	if errBuf.Len() != 0 {
+		t.Errorf("expected no stderr output, got: %q", errBuf.String())
+	}
+}
+
+// 10003 (bad / non-existent app_id) → ConfigError/InvalidClient, propagated.
+func TestRunProbe_TATCode10003_ReturnsConfigError(t *testing.T) {
+	rt := &fakeRT{
+		tatHandler: func(req *http.Request) (*http.Response, error) {
+			return jsonResp(200, `{"code":10003,"msg":"invalid param"}`), nil
+		},
+	}
+	f, errBuf := fakeFactory(t, rt)
+
+	err := runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu)
+
+	if rt.probeCalls != 0 {
+		t.Error("probe endpoint must not be called when TAT fails")
+	}
+	assertConfigRejection(t, err, errBuf, 10003)
+}
+
+// 10014 (real app_id + wrong secret) → ConfigError/InvalidClient via codemeta —
+// the most common real-world rejection, propagated.
+func TestRunProbe_TATCode10014_ReturnsConfigError(t *testing.T) {
+	rt := &fakeRT{
+		tatHandler: func(req *http.Request) (*http.Response, error) {
+			return jsonResp(200, `{"code":10014,"msg":"app secret invalid"}`), nil
+		},
+	}
+	f, errBuf := fakeFactory(t, rt)
+	assertConfigRejection(t, runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu), errBuf, 10014)
+}
+
+// Any non-zero body code is a deterministic rejection and propagates (typed).
+// An unrecognized code falls back to *errs.APIError via BuildAPIError — still
+// typed, so the probe still surfaces it rather than swallowing.
+func TestRunProbe_TATUnknownBodyCode_Propagates(t *testing.T) {
+	rt := &fakeRT{
+		tatHandler: func(req *http.Request) (*http.Response, error) {
+			return jsonResp(200, `{"code":99999,"msg":"future-unknown"}`), nil
+		},
+	}
+	f, errBuf := fakeFactory(t, rt)
+	err := runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu)
+	if err == nil || !errs.IsTyped(err) {
+		t.Fatalf("expected a propagated typed error, got %T: %v", err, err)
+	}
+	if errBuf.Len() != 0 {
+		t.Errorf("runProbe must not write to stderr, got: %q", errBuf.String())
+	}
+}
+
+// Non-200 HTTP at the TAT endpoint is ambiguous (not a payload credential
+// rejection) → silent, exit 0.
+func TestRunProbe_TATHTTPNon200_Silent(t *testing.T) {
+	for _, code := range []int{401, 403, 500} {
+		rt := &fakeRT{
+			tatHandler: func(req *http.Request) (*http.Response, error) {
+				return jsonResp(code, `nope`), nil
+			},
+		}
+		f, errBuf := fakeFactory(t, rt)
+		assertSilent(t, runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu), errBuf)
+	}
+}
+
+func TestRunProbe_TATTransportError_Silent(t *testing.T) {
+	rt := &fakeRT{
+		tatHandler: func(req *http.Request) (*http.Response, error) {
+			return nil, errors.New("network down")
+		},
+	}
+	f, errBuf := fakeFactory(t, rt)
+	assertSilent(t, runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu), errBuf)
+}
+
+func TestRunProbe_TATSuccess_ProbeFails_Silent(t *testing.T) {
+	rt := &fakeRT{
+		probeHandler: func(req *http.Request) (*http.Response, error) {
+			return jsonResp(500, `server error`), nil
+		},
+	}
+	f, errBuf := fakeFactory(t, rt)
+	err := runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu)
+	if rt.probeCalls != 1 {
+		t.Errorf("probe should be called once, got %d", rt.probeCalls)
+	}
+	assertSilent(t, err, errBuf)
+}
+
+func TestRunProbe_TATSuccess_ProbeOK_Silent(t *testing.T) {
+	rt := &fakeRT{}
+	f, errBuf := fakeFactory(t, rt)
+	err := runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu)
+	if rt.tatCalls != 1 || rt.probeCalls != 1 {
+		t.Errorf("expected 1/1 calls, got tat=%d probe=%d", rt.tatCalls, rt.probeCalls)
+	}
+	assertSilent(t, err, errBuf)
+}
+
+func TestRunProbe_ProbeRequestShape(t *testing.T) {
+	rt := &fakeRT{}
+	f, _ := fakeFactory(t, rt)
+	if err := runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if rt.probeReq == nil {
+		t.Fatal("probe request not captured")
+	}
+	if rt.probeReq.Method != http.MethodPost {
+		t.Errorf("probe method = %s, want POST", rt.probeReq.Method)
+	}
+	if got := rt.probeReq.URL.String(); got != "https://open.feishu.cn/open-apis/application/v6/larksuite_cli_app/probe" {
+		t.Errorf("probe URL = %s", got)
+	}
+	if got := rt.probeReq.Header.Get("Authorization"); got != "Bearer t-ok" {
+		t.Errorf("Authorization = %q, want Bearer t-ok", got)
+	}
+	if !strings.Contains(rt.probeBody, `"from":"lark-cli/`+build.Version+`"`) {
+		t.Errorf("probe body missing from field: %s", rt.probeBody)
+	}
+}
+
+func TestRunProbe_LarkBrand_HostRoutedCorrectly(t *testing.T) {
+	rt := &fakeRT{}
+	f, _ := fakeFactory(t, rt)
+	if err := runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandLark); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if rt.probeReq == nil {
+		t.Fatal("probe request not captured")
+	}
+	if !strings.Contains(rt.probeReq.URL.Host, "larksuite.com") {
+		t.Errorf("probe host = %s, want larksuite.com", rt.probeReq.URL.Host)
+	}
+}
+
+func TestRunProbe_HTTPClientError_Silent(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, errBuf, _ := cmdutil.TestFactory(t, nil)
+	f.HttpClient = func() (*http.Client, error) {
+		return nil, errors.New("client init failed")
+	}
+	assertSilent(t, runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu), errBuf)
+}
+
+func TestRunProbe_TimeoutHonored(t *testing.T) {
+	rt := &fakeRT{
+		tatHandler: func(req *http.Request) (*http.Response, error) {
+			<-req.Context().Done()
+			return nil, req.Context().Err()
+		},
+	}
+	f, errBuf := fakeFactory(t, rt)
+
+	start := time.Now()
+	err := runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu)
+	elapsed := time.Since(start)
+
+	if elapsed > 4*time.Second {
+		t.Errorf("runProbe took %v, expected <= ~3s", elapsed)
+	}
+	// A timeout is an ambiguous failure (context deadline → untyped), so it
+	// must stay silent and not block.
+	assertSilent(t, err, errBuf)
+}

cmd/doctor/doctor.go

@@ -19,8 +19,8 @@ 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"
-	"github.com/larksuite/cli/internal/util"
 )
 
 // DoctorOptions holds inputs for the doctor command.
@@ -155,7 +155,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 := util.NewHTTPClient(0)
+	httpClient := transport.NewHTTPClient(0)
 	mcpURL := ep.MCP + "/mcp"
 
 	type probeResult struct {

cmd/event/consume.go

@@ -64,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.")
-	cmd.Flags().DurationVar(&o.timeout, "timeout", 0, "Exit after DURATION (e.g. 30s, 2m). 0 = no timeout. Timeout is a normal exit (code 0; stderr 'reason: timeout').")
+	cmd.Flags().IntVar(&o.maxEvents, "max-events", 0, "Exit after N successful emits (0 = unlimited). Multi-worker EventKeys may emit up to workers-1 past N before all workers stop. Bounded runs ignore stdin EOF.")
+	cmd.Flags().DurationVar(&o.timeout, "timeout", 0, "Exit after DURATION (e.g. 30s, 2m). 0 = no timeout. Timeout is a normal exit (code 0; stderr 'reason: timeout'). Bounded runs ignore stdin EOF.")
 	cmd.Flags().String("as", "auto", "identity type: user | bot | auto (must match EventKey's declared AuthTypes)")
 	_ = cmd.RegisterFlagCompletionFunc("as", func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
 		return []string{"user", "bot", "auto"}, cobra.ShellCompDirectiveNoFileComp
@@ -184,8 +184,9 @@ func runConsume(cmd *cobra.Command, f *cmdutil.Factory, eventKey string, o consu
 		errOut = io.Discard
 	}
 
-	// Non-TTY only: stdin EOF is shutdown for subprocess callers; in TTY Ctrl-D must not exit.
-	if !f.IOStreams.IsTerminal {
+	// Non-TTY unbounded consumers use stdin EOF as shutdown for subprocess callers.
+	// Bounded runs already have --max-events/--timeout as their lifecycle control.
+	if shouldWatchStdinEOF(f.IOStreams.IsTerminal, o.maxEvents, o.timeout) {
 		watchStdinEOF(os.Stdin, cancel, errOut)
 	}
 
@@ -370,3 +371,8 @@ func watchStdinEOF(r io.Reader, cancel context.CancelFunc, errOut io.Writer) {
 		cancel()
 	}()
 }
+
+// shouldWatchStdinEOF gates the stdin-EOF shutdown watcher: non-TTY unbounded runs only (<= 0 mirrors downstream's >0-is-bounded semantics, so negative bounds stay unbounded).
+func shouldWatchStdinEOF(isTerminal bool, maxEvents int, timeout time.Duration) bool {
+	return !isTerminal && maxEvents <= 0 && timeout <= 0
+}

cmd/event/consume_stdin_test.go

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

cmd/notice_test.go

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

cmd/root.go

@@ -18,6 +18,7 @@ import (
 	"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"
@@ -50,20 +51,6 @@ EXAMPLES:
     # Generic API call
     lark-cli api GET /open-apis/calendar/v4/calendars
 
-FLAGS:
-    --params <json>       URL/query parameters JSON
-    --data <json>         request body JSON (POST/PATCH/PUT/DELETE)
-    --as <type>           identity type: user | bot
-    --format <fmt>        output format: json (default) | ndjson | table | csv | pretty
-    --page-all            automatically paginate through all pages
-    --page-size <N>       page size (0 = use API default)
-    --page-limit <N>      max pages to fetch with --page-all (default: 10, 0 for unlimited)
-    --page-delay <MS>     delay in ms between pages (default: 200, only with --page-all)
-    -o, --output <path>   output file path for binary responses
-    --jq <expr>           jq expression to filter JSON output
-    -q <expr>             shorthand for --jq
-    --dry-run             print request without executing
-
 AI AGENT SKILLS:
     lark-cli pairs with AI agent skills (Claude Code, etc.) that
     teach the agent Lark API patterns, best practices, and workflows.
@@ -85,7 +72,15 @@ COMMUNITY:
 More help: lark-cli <command> --help`
 
 // Execute runs the root command and returns the process exit code.
+// rawInvocationArgs holds os.Args[1:] captured at Execute() entry. cobra's
+// UnknownFlags whitelist (installUnknownSubcommandGuard) swallows unknown flags
+// before they reach a group's RunE, so unknownSubcommandRunE re-derives them
+// from here. It stays nil in unit tests that invoke a RunE directly with
+// explicit args — correct, since those don't exercise the whitelist path.
+var rawInvocationArgs []string
+
 func Execute() int {
+	rawInvocationArgs = os.Args[1:]
 	inv, err := BootstrapInvocationContext(os.Args[1:])
 	if err != nil {
 		fmt.Fprintln(os.Stderr, "Error:", err)
@@ -149,29 +144,49 @@ func setupNotices() {
 	skillscheck.Init(build.Version)
 
 	// Composed notice provider — emits keys only when each pending is set.
-	output.PendingNotice = func() map[string]interface{} {
-		notice := map[string]interface{}{}
-		if info := update.GetPending(); info != nil {
-			notice["update"] = map[string]interface{}{
-				"current": info.Current,
-				"latest":  info.Latest,
-				"message": info.Message(),
-				"command": "lark-cli update",
-			}
+	output.PendingNotice = composePendingNotice
+}
+
+// composePendingNotice merges all process-level pending notices (available
+// update, skills/binary drift, deprecated-command alias) into the map surfaced
+// as the JSON "_notice" envelope field. Returns nil when nothing is pending.
+// Extracted from Execute so the composition is unit-testable.
+func composePendingNotice() map[string]interface{} {
+	notice := map[string]interface{}{}
+	if info := update.GetPending(); info != nil {
+		notice["update"] = map[string]interface{}{
+			"current": info.Current,
+			"latest":  info.Latest,
+			"message": info.Message(),
+			"command": "lark-cli update",
 		}
-		if stale := skillscheck.GetPending(); stale != nil {
-			notice["skills"] = map[string]interface{}{
-				"current": stale.Current,
-				"target":  stale.Target,
-				"message": stale.Message(),
-				"command": "lark-cli update",
-			}
-		}
-		if len(notice) == 0 {
-			return nil
-		}
-		return notice
 	}
+	if stale := skillscheck.GetPending(); stale != nil {
+		notice["skills"] = map[string]interface{}{
+			"current": stale.Current,
+			"target":  stale.Target,
+			"message": stale.Message(),
+			"command": "lark-cli update",
+		}
+	}
+	if dep := deprecation.GetPending(); dep != nil {
+		entry := map[string]interface{}{
+			"command": dep.Command,
+			"message": dep.Message(),
+			"action":  "lark-cli update",
+		}
+		if dep.Replacement != "" {
+			entry["replacement"] = dep.Replacement
+		}
+		if dep.Skill != "" {
+			entry["skill"] = dep.Skill
+		}
+		notice["deprecated_command"] = entry
+	}
+	if len(notice) == 0 {
+		return nil
+	}
+	return notice
 }
 
 // isCompletionCommand returns true if args indicate a shell completion request.
@@ -257,6 +272,13 @@ func handleRootError(f *cmdutil.Factory, err error) int {
 		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
+	}
+
 	if exitErr := asExitError(err); exitErr != nil {
 		if !exitErr.Raw {
 			// Raw errors (e.g. from `api` command via output.MarkRaw)
@@ -269,6 +291,19 @@ 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
 }
@@ -335,35 +370,204 @@ func installUnknownSubcommandGuard(cmd *cobra.Command) {
 // they have moved to the typed surface.
 func unknownSubcommandRunE(cmd *cobra.Command, args []string) error {
 	if len(args) == 0 {
-		return cmd.Help()
+		// A bare group (e.g. `sheets`), or one carrying only group-valid flags
+		// like the global --profile, legitimately prints help. But a flag that
+		// belongs to a (missing) subcommand is a user error: the guard's
+		// FParseErrWhitelist swallows such flags and leaves args empty, so without
+		// the checks below they would silently fall through to help + exit 0 —
+		// letting an agent mistake a malformed call (`im --format json`,
+		// `sheets --badflag`) for success. Recover the swallowed tokens from the
+		// raw invocation and fail structured instead.
+		flags := flagTokensInArgs(rawInvocationArgs)
+		if len(flags) == 0 {
+			return cmd.Help()
+		}
+		if unknown := unknownFlagTokens(cmd, rawInvocationArgs); len(unknown) > 0 {
+			return &output.ExitError{
+				Code: output.ExitValidation,
+				Detail: &output.ErrDetail{
+					Type:    "unknown_flag",
+					Message: fmt.Sprintf("unknown flag %s before a subcommand for %q", strings.Join(unknown, ", "), cmd.CommandPath()),
+					Hint:    fmt.Sprintf("flags belong to a subcommand; run `%s --help` to list subcommands and their flags", cmd.CommandPath()),
+					Detail: map[string]any{
+						// Keep the same detail keys as flagDidYouMean's unknown_flag
+						// so a consumer keyed on Type can read a stable shape. The
+						// subcommand isn't resolved here, so suggestions/valid_flags
+						// have no meaningful universe to draw from — emit empty
+						// rather than the group's own (misleading) flags. unknown is
+						// the back-compat singular field; unknown_flags carries the
+						// full list when more than one flag was supplied.
+						"unknown":       strings.Join(unknown, ", "),
+						"unknown_flags": unknown,
+						"command_path":  cmd.CommandPath(),
+						"suggestions":   []string{},
+						"valid_flags":   []string{},
+					},
+				},
+			}
+		}
+		// The remaining flags are all defined somewhere in the tree. Those valid
+		// on the group itself or inherited (e.g. the global --profile) do not
+		// require a subcommand, so a bare group carrying only those still prints
+		// help. Anything left belongs to a subcommand that was omitted
+		// (e.g. `im --format json`): distinct from unknown_flag — the flags are
+		// real, the subcommand is what's missing.
+		misplaced := subcommandOnlyFlagTokens(cmd, rawInvocationArgs)
+		if len(misplaced) == 0 {
+			return cmd.Help()
+		}
+		return &output.ExitError{
+			Code: output.ExitValidation,
+			Detail: &output.ErrDetail{
+				Type:    "missing_subcommand",
+				Message: fmt.Sprintf("missing subcommand for %q; flag %s belongs to a subcommand, not the group", cmd.CommandPath(), strings.Join(misplaced, ", ")),
+				Hint:    fmt.Sprintf("run `%s --help` to list subcommands and their flags", cmd.CommandPath()),
+				Detail: map[string]any{
+					"command_path": cmd.CommandPath(),
+					"flags":        misplaced,
+					"suggestions":  []string{},
+				},
+			},
+		}
 	}
 	unknown := args[0]
-	available := availableSubcommandNames(cmd)
-	suggestions := suggest.Closest(unknown, available, 6)
+	available, deprecated := availableSubcommandNames(cmd)
+	// Rank suggestions across both current and deprecated names so a mistyped
+	// legacy command (e.g. +raed → +read) still resolves; the alias stays
+	// runnable and self-flags via the _notice on execution.
+	suggestions := suggest.Closest(unknown, append(append([]string{}, available...), deprecated...), 6)
 	msg := fmt.Sprintf("unknown subcommand %q for %q", unknown, cmd.CommandPath())
 	hint := fmt.Sprintf("run `%s --help` to see available subcommands", cmd.CommandPath())
 	if len(suggestions) > 0 {
 		hint = fmt.Sprintf("did you mean one of: %s? (run `%s --help` for the full list)",
 			strings.Join(suggestions, ", "), cmd.CommandPath())
 	}
+	detail := map[string]any{
+		"unknown":      unknown,
+		"command_path": cmd.CommandPath(),
+		"suggestions":  suggestions,
+		"available":    available,
+	}
+	// Only services with backward-compat aliases (currently sheets) carry a
+	// deprecated bucket; omit the key elsewhere so every other service's
+	// envelope is unchanged.
+	if len(deprecated) > 0 {
+		detail["deprecated"] = deprecated
+	}
 	return &output.ExitError{
 		Code: output.ExitValidation,
 		Detail: &output.ErrDetail{
 			Type:    "unknown_subcommand",
 			Message: msg,
 			Hint:    hint,
-			Detail: map[string]any{
-				"unknown":      unknown,
-				"command_path": cmd.CommandPath(),
-				"suggestions":  suggestions,
-				"available":    available,
-			},
+			Detail:  detail,
 		},
 	}
 }
 
-func availableSubcommandNames(cmd *cobra.Command) []string {
-	subs := make([]string, 0, len(cmd.Commands()))
+// flagTokensInArgs returns the flag-like tokens (-x, --foo, --foo=bar) in
+// rawArgs, stopping at the "--" positional terminator. Whether a flag is
+// defined is not considered (see unknownFlagTokens for that). A pure group
+// with any flag token but no subcommand is a user error — a pure group
+// consumes no flags of its own, so the flag must belong to a subcommand — so
+// the caller fails structured instead of falling through to help.
+func flagTokensInArgs(rawArgs []string) []string {
+	var toks []string
+	for _, a := range rawArgs {
+		if a == "--" {
+			break // everything after -- is positional
+		}
+		if len(a) < 2 || a[0] != '-' {
+			continue
+		}
+		toks = append(toks, a)
+	}
+	return toks
+}
+
+// unknownFlagTokens returns the flag tokens in rawArgs that cmd does not define
+// (on itself, inherited, or any direct subcommand). installUnknownSubcommandGuard
+// whitelists unknown flags on pure groups so a mistyped subcommand still reaches
+// the suggestion path; the side effect is that flags before a subcommand are
+// swallowed. This recovers the genuinely-unknown ones so the caller can name
+// them in a "did you mean" envelope.
+func unknownFlagTokens(cmd *cobra.Command, rawArgs []string) []string {
+	var unknown []string
+	for _, a := range flagTokensInArgs(rawArgs) {
+		name := strings.SplitN(strings.TrimLeft(a, "-"), "=", 2)[0]
+		if name != "" && !flagDefinedInTree(cmd, name) {
+			unknown = append(unknown, a)
+		}
+	}
+	return unknown
+}
+
+// flagKnownOnGroup reports whether name is a flag defined on cmd itself or
+// inherited (a global persistent flag like --profile) — i.e. valid on the bare
+// group and therefore not requiring a subcommand.
+func flagKnownOnGroup(cmd *cobra.Command, name string) bool {
+	short := len(name) == 1
+	lookup := func(fs *pflag.FlagSet) bool {
+		if short {
+			return fs.ShorthandLookup(name) != nil
+		}
+		return fs.Lookup(name) != nil
+	}
+	return lookup(cmd.Flags()) || lookup(cmd.InheritedFlags())
+}
+
+// subcommandOnlyFlagTokens returns the flag tokens in rawArgs that are valid on
+// a subcommand of cmd but not on cmd itself/inherited — flags supplied while
+// omitting the subcommand they belong to (`im --format json`). Global flags
+// valid on the bare group (e.g. --profile) are excluded so
+// `lark-cli --profile p im` still prints help rather than erroring.
+func subcommandOnlyFlagTokens(cmd *cobra.Command, rawArgs []string) []string {
+	var misplaced []string
+	for _, a := range flagTokensInArgs(rawArgs) {
+		name := strings.SplitN(strings.TrimLeft(a, "-"), "=", 2)[0]
+		if name == "" || flagKnownOnGroup(cmd, name) {
+			continue
+		}
+		if flagDefinedInTree(cmd, name) {
+			misplaced = append(misplaced, a)
+		}
+	}
+	return misplaced
+}
+
+// flagDefinedInTree reports whether name is defined on cmd, its inherited
+// (persistent) flags, or any direct subcommand. The subcommand case covers a
+// user who merely omitted the subcommand — e.g. `sheets --format json`, where
+// --format is injected on every leaf shortcut, not on the group — so only a
+// genuinely unknown flag like `sheets --badflag` is reported.
+func flagDefinedInTree(cmd *cobra.Command, name string) bool {
+	short := len(name) == 1
+	known := func(c *cobra.Command, inherited bool) bool {
+		fs := c.Flags()
+		if inherited {
+			fs = c.InheritedFlags()
+		}
+		if short {
+			return fs.ShorthandLookup(name) != nil
+		}
+		return fs.Lookup(name) != nil
+	}
+	if known(cmd, false) || known(cmd, true) {
+		return true
+	}
+	for _, c := range cmd.Commands() {
+		if known(c, false) {
+			return true
+		}
+	}
+	return false
+}
+
+// availableSubcommandNames returns the invokable subcommand names of cmd, split
+// into current commands and backward-compatibility aliases (those tagged into
+// the deprecated cobra group via cmdutil.DeprecatedGroupID). Both slices are
+// sorted; hidden commands plus help/completion are omitted.
+func availableSubcommandNames(cmd *cobra.Command) (available, deprecated []string) {
 	for _, c := range cmd.Commands() {
 		if c.Hidden || !c.IsAvailableCommand() {
 			continue
@@ -372,10 +576,15 @@ func availableSubcommandNames(cmd *cobra.Command) []string {
 		if name == "help" || name == "completion" {
 			continue
 		}
-		subs = append(subs, name)
+		if cmdutil.IsDeprecatedCommand(c) {
+			deprecated = append(deprecated, name)
+		} else {
+			available = append(available, name)
+		}
 	}
-	sort.Strings(subs)
-	return subs
+	sort.Strings(available)
+	sort.Strings(deprecated)
+	return available, deprecated
 }
 
 // flagDidYouMean is the root FlagErrorFunc (inherited by all subcommands). It
@@ -426,6 +635,11 @@ func flagDidYouMean(c *cobra.Command, ferr error) error {
 // 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()

cmd/root_integration_test.go

@@ -377,9 +377,9 @@ func TestIntegration_Shortcut_BusinessError_OutputsEnvelope(t *testing.T) {
 		OK:       false,
 		Identity: "bot",
 		Error: &output.ErrDetail{
-			Type:    "api_error",
+			Type:    "api",
 			Code:    230002,
-			Message: "HTTP 400: Bot/User can NOT be out of the chat.",
+			Message: "Bot/User can NOT be out of the chat.",
 		},
 	})
 }

cmd/root_test.go

@@ -21,6 +21,7 @@ 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"
 )
@@ -268,6 +269,54 @@ func (f *failingWriter) Write(p []byte) (int, error) {
 	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

cmd/service/service.go

@@ -18,6 +18,7 @@ import (
 	"github.com/larksuite/cli/internal/errclass"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/registry"
+	"github.com/larksuite/cli/internal/registry/metaschema"
 	"github.com/larksuite/cli/internal/util"
 	"github.com/larksuite/cli/internal/validate"
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
@@ -30,74 +31,56 @@ func RegisterServiceCommands(parent *cobra.Command, f *cmdutil.Factory) {
 }
 
 func RegisterServiceCommandsWithContext(ctx context.Context, parent *cobra.Command, f *cmdutil.Factory) {
-	for _, project := range registry.ListFromMetaProjects() {
-		spec := registry.LoadFromMeta(project)
-		if spec == nil {
+	for _, spec := range registry.TypedServices() {
+		if spec.Name == "" || spec.ServicePath == "" || len(spec.Resources) == 0 {
 			continue
 		}
-		specName := registry.GetStrFromMap(spec, "name")
-		servicePath := registry.GetStrFromMap(spec, "servicePath")
-		if specName == "" || servicePath == "" {
-			continue
-		}
-		resources, _ := spec["resources"].(map[string]interface{})
-		if resources == nil {
-			continue
-		}
-		registerServiceWithContext(ctx, parent, spec, resources, f)
+		registerServiceWithContext(ctx, parent, spec, f)
 	}
 }
 
 func registerService(parent *cobra.Command, spec map[string]interface{}, resources map[string]interface{}, f *cmdutil.Factory) {
-	registerServiceWithContext(context.Background(), parent, spec, resources, f)
+	svc := registry.MapToService(spec)
+	svc.Resources = registry.MapToResources(resources)
+	registerServiceWithContext(context.Background(), parent, svc, f)
 }
 
-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")
+func registerServiceWithContext(ctx context.Context, parent *cobra.Command, spec metaschema.Service, f *cmdutil.Factory) {
+	specDesc := registry.GetServiceDescription(spec.Name, "en")
 	if specDesc == "" {
-		specDesc = registry.GetStrFromMap(spec, "description")
+		specDesc = spec.Description
 	}
 
 	// Find existing service command or create one
 	var svc *cobra.Command
 	for _, c := range parent.Commands() {
-		if c.Name() == specName {
+		if c.Name() == spec.Name {
 			svc = c
 			break
 		}
 	}
 	if svc == nil {
 		svc = &cobra.Command{
-			Use:   specName,
+			Use:   spec.Name,
 			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)
+	for _, resource := range spec.Resources {
+		registerResourceWithContext(ctx, svc, spec, resource, f)
 	}
 }
 
-func registerResourceWithContext(ctx context.Context, parent *cobra.Command, spec map[string]interface{}, name string, resource map[string]interface{}, f *cmdutil.Factory) {
+func registerResourceWithContext(ctx context.Context, parent *cobra.Command, spec metaschema.Service, resource metaschema.Resource, f *cmdutil.Factory) {
 	res := &cobra.Command{
-		Use:   name,
-		Short: name + " operations",
+		Use:   resource.Name,
+		Short: resource.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)
+	for _, method := range resource.Methods {
+		registerMethodWithContext(ctx, res, spec, method, method.Name, resource.Name, f)
 	}
 }
 
@@ -125,31 +108,36 @@ type ServiceMethodOptions struct {
 	FileFields []string // auto-detected file field names from metadata
 }
 
-// detectFileFields delegates to the shared cmdutil.DetectFileFields helper.
-func detectFileFields(method map[string]interface{}) []string {
-	return cmdutil.DetectFileFields(method)
+// detectFileFieldsTyped returns the names of file-type fields in the method's
+// request body (used to decide whether to register --file).
+func detectFileFieldsTyped(m metaschema.Method) []string {
+	var fields []string
+	for _, fld := range m.RequestBody {
+		if fld.Type == "file" {
+			fields = append(fields, fld.Name)
+		}
+	}
+	return fields
 }
 
-func registerMethodWithContext(ctx context.Context, parent *cobra.Command, spec map[string]interface{}, method map[string]interface{}, name string, resName string, f *cmdutil.Factory) {
+func registerMethodWithContext(ctx context.Context, parent *cobra.Command, spec metaschema.Service, method metaschema.Method, 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.
+// NewCmdServiceMethod creates a command for a dynamically registered service
+// method from map specs (kept for tests; converts to typed internally).
 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)
+	return NewCmdServiceMethodWithContext(context.Background(), f, registry.MapToService(spec), registry.MapToMethod(name, method), name, resName, runF)
 }
 
-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)
+func NewCmdServiceMethodWithContext(ctx context.Context, f *cmdutil.Factory, spec metaschema.Service, method metaschema.Method, name, resName string, runF func(*ServiceMethodOptions) error) *cobra.Command {
+	desc := method.Description
+	httpMethod := method.HTTPMethod
+	risk := method.Risk
+	schemaPath := fmt.Sprintf("%s.%s.%s", spec.Name, resName, name)
 
 	opts := &ServiceMethodOptions{
 		Factory:    f,
-		Spec:       spec,
-		Method:     method,
 		SchemaPath: schemaPath,
 	}
 	var asStr string
@@ -159,6 +147,10 @@ func NewCmdServiceMethodWithContext(ctx context.Context, f *cmdutil.Factory, spe
 		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 {
+			// Materialize the maps the execution path still reads lazily — only
+			// when THIS command actually runs, never at startup.
+			opts.Spec = registry.ServiceToMap(spec)
+			opts.Method = registry.MethodToMap(method)
 			opts.Cmd = cmd
 			opts.Ctx = cmd.Context()
 			opts.As = core.Identity(asStr)
@@ -180,6 +172,7 @@ func NewCmdServiceMethodWithContext(ctx context.Context, f *cmdutil.Factory, spe
 	cmd.Flags().IntVar(&opts.PageLimit, "page-limit", 10, "max pages to fetch with --page-all (0 = unlimited)")
 	cmd.Flags().IntVar(&opts.PageDelay, "page-delay", 200, "delay in ms between pages")
 	cmd.Flags().StringVar(&opts.Format, "format", "json", "output format: json|ndjson|table|csv")
+	cmd.Flags().Bool("json", false, "shorthand for --format json")
 	cmd.Flags().StringVarP(&opts.JqExpr, "jq", "q", "", "jq expression to filter JSON output")
 	cmd.Flags().BoolVar(&opts.DryRun, "dry-run", false, "print request without executing")
 	if risk == "high-risk-write" {
@@ -187,7 +180,7 @@ func NewCmdServiceMethodWithContext(ctx context.Context, f *cmdutil.Factory, spe
 	}
 
 	// Conditionally register --file for methods with file-type fields.
-	fileFields := detectFileFields(method)
+	fileFields := detectFileFieldsTyped(method)
 	opts.FileFields = fileFields
 	if len(fileFields) > 0 {
 		switch httpMethod {
@@ -199,10 +192,15 @@ func NewCmdServiceMethodWithContext(ctx context.Context, f *cmdutil.Factory, spe
 		return []string{"json", "ndjson", "table", "csv"}, cobra.ShellCompDirectiveNoFileComp
 	})
 
-	cmdutil.SetTips(cmd, registry.GetStrSliceFromMap(method, "tips"))
+	// meta_data.json carries no per-method tips; SetTips(nil) matches prior behavior.
+	cmdutil.SetTips(cmd, nil)
 	cmdutil.SetRisk(cmd, risk)
-	if tokens, ok := method["accessTokens"].([]interface{}); ok && len(tokens) > 0 {
-		cmdutil.SetSupportedIdentities(cmd, cmdutil.AccessTokensToIdentities(tokens))
+	if len(method.AccessTokens) > 0 {
+		toks := make([]interface{}, len(method.AccessTokens))
+		for i, t := range method.AccessTokens {
+			toks[i] = t
+		}
+		cmdutil.SetSupportedIdentities(cmd, cmdutil.AccessTokensToIdentities(toks))
 	}
 
 	return cmd

cmd/service/service_test.go

@@ -11,6 +11,7 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/registry"
 	"github.com/spf13/cobra"
 )
 
@@ -752,7 +753,7 @@ func TestDetectFileFields(t *testing.T) {
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			got := detectFileFields(tt.method)
+			got := detectFileFieldsTyped(registry.MapToMethod("", tt.method))
 			if len(got) != len(tt.want) {
 				t.Errorf("detectFileFields() = %v, want %v", got, tt.want)
 				return
@@ -765,3 +766,22 @@ func TestDetectFileFields(t *testing.T) {
 		})
 	}
 }
+
+func TestServiceMethod_JsonFlag_Accepted(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+
+	var captured *ServiceMethodOptions
+	cmd := NewCmdServiceMethod(f, driveSpec(),
+		map[string]interface{}{"description": "desc", "httpMethod": "GET"}, "list", "files",
+		func(opts *ServiceMethodOptions) error {
+			captured = opts
+			return nil
+		})
+	cmd.SetArgs([]string{"--json"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("--json should be accepted without error, got: %v", err)
+	}
+	if captured == nil {
+		t.Fatal("expected runF to be called")
+	}
+}

cmd/skill/skill.go

@@ -0,0 +1,183 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package skill implements the `lark-cli skills` command group, which serves
+// binary-embedded skill content to AI agents. The package is "skill"; the
+// user-facing verb is "skills".
+package skill
+
+import (
+	"fmt"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/skillcontent"
+	"github.com/spf13/cobra"
+)
+
+func newReader(f *cmdutil.Factory) (*skillcontent.Reader, error) {
+	if f.SkillContent == nil {
+		return nil, errs.NewInternalError(errs.SubtypeFileIO,
+			"skill content not embedded in this build")
+	}
+	return skillcontent.New(f.SkillContent), nil
+}
+
+type readEnvelope struct {
+	Skill    string `json:"skill"`
+	Path     string `json:"path"`
+	Content  string `json:"content"`
+	Guidance string `json:"guidance,omitempty"`
+}
+
+type listEnvelope struct {
+	OK     bool                     `json:"ok"`
+	Skills []skillcontent.SkillInfo `json:"skills"`
+	Count  int                      `json:"count"`
+}
+
+type listPathEnvelope struct {
+	OK      bool                    `json:"ok"`
+	Path    string                  `json:"path"`
+	Entries []skillcontent.DirEntry `json:"entries"`
+	Count   int                     `json:"count"`
+}
+
+func NewCmdSkill(f *cmdutil.Factory) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "skills",
+		Short: "Read embedded skill content (list / read)",
+		Long: "Read agent-readable skill content (SKILL.md and reference files) embedded in " +
+			"the CLI binary at build time, so it stays in sync with the CLI version. " +
+			"Machine resources such as assets/ and scripts/ are not embedded.",
+	}
+	// Risk is set on each leaf (GetRisk does not walk parents); the group has none.
+	cmdutil.DisableAuthCheck(cmd)
+	cmd.AddCommand(newListCmd(f), newReadCmd(f))
+	return cmd
+}
+
+func newListCmd(f *cmdutil.Factory) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "list [name[/path]]",
+		Short: "List skills, or list one layer under a skill path (like ls)",
+		Example: `  lark-cli skills list                      # all skills: name, description, version
+  lark-cli skills list lark-doc             # one layer under a skill (like ls)
+  lark-cli skills list lark-doc/references  # one layer under a subdirectory`,
+		Args: cobra.ArbitraryArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if len(args) > 1 {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument,
+					"list takes at most 1 argument: [name[/path]]").
+					WithHint("run 'lark-cli skills list --help'")
+			}
+			r, err := newReader(f)
+			if err != nil {
+				return err
+			}
+			if len(args) == 0 {
+				skills, err := r.List()
+				if err != nil {
+					return err
+				}
+				output.PrintJson(f.IOStreams.Out, listEnvelope{OK: true, Skills: skills, Count: len(skills)})
+				return nil
+			}
+			entries, listed, err := r.ListPath(args[0])
+			if err != nil {
+				return err
+			}
+			output.PrintJson(f.IOStreams.Out, listPathEnvelope{OK: true, Path: listed, Entries: entries, Count: len(entries)})
+			return nil
+		},
+	}
+	// --json is a no-op (list is always JSON), accepted only to stay symmetric with read.
+	cmd.Flags().Bool("json", false, "no-op (list output is always JSON)")
+	cmdutil.SetRisk(cmd, "read")
+	cmdutil.DisableAuthCheck(cmd)
+	return cmd
+}
+
+func newReadCmd(f *cmdutil.Factory) *cobra.Command {
+	var asJSON bool
+	cmd := &cobra.Command{
+		Use:   "read <name>[/<path>] [path]",
+		Short: "Print a skill's SKILL.md, or a file under the skill (raw markdown by default)",
+		Example: `  lark-cli skills read lark-doc                             # the skill's SKILL.md
+  lark-cli skills read lark-doc references/lark-doc-fetch.md  # a file under the skill
+  lark-cli skills read lark-doc/references/lark-doc-fetch.md  # same, slash form
+  lark-cli skills read lark-doc --json                      # JSON envelope`,
+		Args: cobra.ArbitraryArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			name, relpath, err := parseReadTarget(args)
+			if err != nil {
+				return err
+			}
+			r, err := newReader(f)
+			if err != nil {
+				return err
+			}
+
+			var content []byte
+			var pathOut string
+			if relpath == "" {
+				content, err = r.ReadSkill(name)
+				pathOut = "SKILL.md"
+			} else {
+				content, pathOut, err = r.ReadReference(name, relpath)
+			}
+			if err != nil {
+				return err
+			}
+
+			isMain := pathOut == "SKILL.md"
+			if asJSON {
+				env := readEnvelope{Skill: name, Path: pathOut, Content: string(content)}
+				if isMain {
+					env.Guidance = readGuidance(name)
+				}
+				output.PrintJson(f.IOStreams.Out, env)
+				return nil
+			}
+			// Raw stdout stays byte-identical to the file; guidance goes to stderr.
+			if _, err := f.IOStreams.Out.Write(content); err != nil {
+				return errs.NewInternalError(errs.SubtypeFileIO, "failed to write output: %v", err)
+			}
+			if isMain {
+				fmt.Fprintln(f.IOStreams.ErrOut, readGuidance(name))
+			}
+			return nil
+		},
+	}
+	cmd.Flags().BoolVar(&asJSON, "json", false, "output as a JSON envelope instead of raw markdown")
+	cmdutil.SetRisk(cmd, "read")
+	cmdutil.DisableAuthCheck(cmd)
+	return cmd
+}
+
+// parseReadTarget maps 1-or-2 positional args to (name, relpath); a lone
+// "<a>/<b>" splits on the first '/', and relpath "" reads the main SKILL.md.
+func parseReadTarget(args []string) (name, relpath string, err error) {
+	switch len(args) {
+	case 1:
+		name, relpath = skillcontent.SplitArg(args[0])
+		return name, relpath, nil
+	case 2:
+		return args[0], args[1], nil
+	default:
+		return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument,
+			"read requires 1 or 2 arguments: <name>[/<path>] [path]").
+			WithHint("run 'lark-cli skills read --help'")
+	}
+}
+
+// readGuidance routes cross-skill "../lark-foo/..." references back through
+// `skills read lark-foo/...`: the path guard rejects a literal "../", so the
+// relative form must be rewritten.
+func readGuidance(name string) string {
+	return fmt.Sprintf("> Tip: read this skill's own files (e.g. `references/...`) with "+
+		"`lark-cli skills read %s <relative-path>` to keep them in sync with this CLI version. "+
+		"A reference to another skill (`../lark-foo/...`) uses the same command with the "+
+		"leading `../` removed: `lark-cli skills read lark-foo/...`.", name)
+}

cmd/skill/skill_test.go

@@ -0,0 +1,306 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package skill
+
+import (
+	"encoding/json"
+	"io"
+	"io/fs"
+	"strings"
+	"testing"
+	"testing/fstest"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+)
+
+// calFS is the default single-skill content tree for these tests. The embedded
+// FS is now injected through the Factory (no package global), so tests pass it
+// explicitly to run() — nothing is shared, so they are safe under -parallel.
+func calFS() fstest.MapFS {
+	return fstest.MapFS{
+		"lark-calendar/SKILL.md":             {Data: []byte("---\nname: lark-calendar\nversion: 1.0.0\ndescription: \"Cal\"\nmetadata:\n  cliHelp: \"lark-cli calendar --help\"\n---\nbody")},
+		"lark-calendar/references/agenda.md": {Data: []byte("# Agenda")},
+	}
+}
+
+// run executes the skills command tree against the given content FS (may be nil
+// to exercise the not-embedded path) and returns stdout/stderr/err.
+func run(t *testing.T, fsys fs.FS, args ...string) (stdout, stderr string, err error) {
+	t.Helper()
+	// Isolate CLI config state so tests never read/write the real config dir
+	// (repo convention).
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, out, errOut, _ := cmdutil.TestFactory(t, nil)
+	f.SkillContent = fsys
+	cmd := NewCmdSkill(f)
+	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
+	cmd.SetArgs(args)
+	err = cmd.Execute()
+	return out.String(), errOut.String(), err
+}
+
+func TestSkillList(t *testing.T) {
+	stdout, _, err := run(t, calFS(), "list")
+	if err != nil {
+		t.Fatalf("list error: %v", err)
+	}
+	var got struct {
+		OK     bool             `json:"ok"`
+		Skills []map[string]any `json:"skills"`
+		Count  int              `json:"count"`
+	}
+	if e := json.Unmarshal([]byte(stdout), &got); e != nil {
+		t.Fatalf("invalid JSON: %v\n%s", e, stdout)
+	}
+	// "ok" is an explicit success marker (the list envelope is a typed struct;
+	// no automatic _notice attaches).
+	if !got.OK {
+		t.Error("expected ok=true in list envelope")
+	}
+	if got.Count != 1 || len(got.Skills) != 1 {
+		t.Fatalf("count: got %d", got.Count)
+	}
+	if got.Skills[0]["name"] != "lark-calendar" {
+		t.Errorf("name: got %v", got.Skills[0]["name"])
+	}
+	// Top-level list carries version + metadata, not a references list.
+	if _, ok := got.Skills[0]["references"]; ok {
+		t.Error("top-level list must not include references")
+	}
+	if got.Skills[0]["version"] != "1.0.0" {
+		t.Errorf("version: got %v, want 1.0.0", got.Skills[0]["version"])
+	}
+	if _, ok := got.Skills[0]["metadata"]; !ok {
+		t.Error("expected metadata in list entry")
+	}
+}
+
+func TestSkillListJSONFlagAccepted(t *testing.T) {
+	// `list --json` must be accepted (no-op), not rejected as an unknown flag,
+	// so it stays symmetric with read --json.
+	stdout, _, err := run(t, calFS(), "list", "--json")
+	if err != nil {
+		t.Fatalf("list --json error: %v", err)
+	}
+	var got struct {
+		OK    bool `json:"ok"`
+		Count int  `json:"count"`
+	}
+	if e := json.Unmarshal([]byte(stdout), &got); e != nil {
+		t.Fatalf("invalid JSON: %v\n%s", e, stdout)
+	}
+	if !got.OK || got.Count != 1 {
+		t.Errorf("envelope: %+v", got)
+	}
+}
+
+func TestSkillListPath(t *testing.T) {
+	stdout, _, err := run(t, calFS(), "list", "lark-calendar")
+	if err != nil {
+		t.Fatalf("list <name> error: %v", err)
+	}
+	var got struct {
+		OK      bool   `json:"ok"`
+		Path    string `json:"path"`
+		Entries []struct {
+			Path  string `json:"path"`
+			IsDir bool   `json:"is_dir"`
+		} `json:"entries"`
+		Count int `json:"count"`
+	}
+	if e := json.Unmarshal([]byte(stdout), &got); e != nil {
+		t.Fatalf("invalid JSON: %v\n%s", e, stdout)
+	}
+	if !got.OK || got.Path != "lark-calendar" {
+		t.Errorf("envelope: %+v", got)
+	}
+	// One layer under the skill root: SKILL.md (file) + references (dir).
+	if got.Count != 2 || len(got.Entries) != 2 {
+		t.Fatalf("entries: got %+v", got.Entries)
+	}
+	if got.Entries[0].Path != "lark-calendar/SKILL.md" || got.Entries[0].IsDir {
+		t.Errorf("entry[0]: got %+v", got.Entries[0])
+	}
+	if got.Entries[1].Path != "lark-calendar/references" || !got.Entries[1].IsDir {
+		t.Errorf("entry[1]: got %+v", got.Entries[1])
+	}
+}
+
+func TestSkillListPathUnknown(t *testing.T) {
+	_, _, err := run(t, calFS(), "list", "no-such-skill")
+	if err == nil || !strings.Contains(err.Error(), "unknown skill") {
+		t.Fatalf("expected 'unknown skill' error, got %v", err)
+	}
+}
+
+func TestSkillListPathTraversal(t *testing.T) {
+	stdout, _, err := run(t, calFS(), "list", "lark-calendar/../../etc")
+	if err == nil || !strings.Contains(err.Error(), "invalid path") {
+		t.Fatalf("expected 'invalid path' error, got %v", err)
+	}
+	if stdout != "" {
+		t.Errorf("stdout must be empty on rejection, got %q", stdout)
+	}
+}
+
+func TestSkillListTooManyArgs(t *testing.T) {
+	_, _, err := run(t, calFS(), "list", "a", "b")
+	if err == nil || !strings.Contains(err.Error(), "at most 1 argument") {
+		t.Fatalf("expected 'at most 1 argument' error, got %v", err)
+	}
+}
+
+// TestSkillListSkipsDirWithoutSKILLmd proves a top-level dir lacking SKILL.md is
+// omitted from the catalog (no blank entry).
+func TestSkillListSkipsDirWithoutSKILLmd(t *testing.T) {
+	fsys := fstest.MapFS{
+		"lark-calendar/SKILL.md": {Data: []byte("---\nname: lark-calendar\ndescription: \"Cal\"\n---\nb")},
+		"not-a-skill/readme.txt": {Data: []byte("junk")}, // dir without SKILL.md
+	}
+	stdout, _, err := run(t, fsys, "list")
+	if err != nil {
+		t.Fatalf("list error: %v", err)
+	}
+	var got struct {
+		Skills []map[string]any `json:"skills"`
+		Count  int              `json:"count"`
+	}
+	if e := json.Unmarshal([]byte(stdout), &got); e != nil {
+		t.Fatalf("invalid JSON: %v\n%s", e, stdout)
+	}
+	if got.Count != 1 || got.Skills[0]["name"] != "lark-calendar" {
+		t.Fatalf("expected only lark-calendar, got %+v", got.Skills)
+	}
+}
+
+func TestSkillReadRaw(t *testing.T) {
+	stdout, stderr, err := run(t, calFS(), "read", "lark-calendar")
+	if err != nil {
+		t.Fatalf("read error: %v", err)
+	}
+	if !strings.HasPrefix(stdout, "---\nname: lark-calendar") {
+		t.Errorf("raw output: got %q", stdout)
+	}
+	// Raw stdout is byte-pure SKILL.md — the guidance tip must NOT be appended.
+	if strings.Contains(stdout, "Tip:") {
+		t.Errorf("raw stdout must not carry the guidance tip: got %q", stdout)
+	}
+	// Guidance goes to stderr: own files via `skills read <name> ...`, and
+	// cross-skill refs routed to `skills read <other-skill> ...` (version-
+	// consistent), not "read directly".
+	if !strings.Contains(stderr, "lark-cli skills read lark-calendar <relative-path>") {
+		t.Errorf("expected own-files guidance on stderr: got %q", stderr)
+	}
+	if !strings.Contains(stderr, "lark-cli skills read lark-foo/...") {
+		t.Errorf("expected cross-skill refs routed to skills read: got %q", stderr)
+	}
+	if strings.Contains(stderr, "instead of opening them directly") ||
+		strings.Contains(stderr, "read those directly") {
+		t.Errorf("guidance must not steer cross-skill refs to direct reads: got %q", stderr)
+	}
+}
+
+func TestSkillReadJSON(t *testing.T) {
+	stdout, _, err := run(t, calFS(), "read", "lark-calendar", "--json")
+	if err != nil {
+		t.Fatalf("read --json error: %v", err)
+	}
+	var got struct {
+		Skill, Path, Content, Guidance string
+	}
+	if e := json.Unmarshal([]byte(stdout), &got); e != nil {
+		t.Fatalf("invalid JSON: %v", e)
+	}
+	if got.Skill != "lark-calendar" || got.Path != "SKILL.md" || got.Content == "" {
+		t.Errorf("envelope: %+v", got)
+	}
+	// Guidance is a separate field, not merged into content.
+	if got.Guidance == "" {
+		t.Error("expected guidance field for main SKILL.md")
+	}
+	if strings.Contains(got.Content, "Tip:") {
+		t.Error("guidance must not be merged into content")
+	}
+}
+
+func TestSkillReadFile(t *testing.T) {
+	// Both the 2-arg and slash forms read the same file, with no guidance tip.
+	for _, args := range [][]string{
+		{"read", "lark-calendar", "references/agenda.md"},
+		{"read", "lark-calendar/references/agenda.md"},
+	} {
+		stdout, stderr, err := run(t, calFS(), args...)
+		if err != nil {
+			t.Fatalf("read %v error: %v", args, err)
+		}
+		if stdout != "# Agenda" {
+			t.Errorf("read %v output: got %q", args, stdout)
+		}
+		// Reference reads carry no guidance on either stream.
+		if strings.Contains(stderr, "Tip:") {
+			t.Errorf("read %v must not emit guidance on stderr: got %q", args, stderr)
+		}
+	}
+}
+
+func TestSkillReadFileJSON(t *testing.T) {
+	stdout, _, err := run(t, calFS(), "read", "lark-calendar", "references/agenda.md", "--json")
+	if err != nil {
+		t.Fatalf("read file --json error: %v", err)
+	}
+	var got struct {
+		Skill, Path, Content, Guidance string
+	}
+	if e := json.Unmarshal([]byte(stdout), &got); e != nil {
+		t.Fatalf("invalid JSON: %v\n%s", e, stdout)
+	}
+	if got.Skill != "lark-calendar" || got.Path != "references/agenda.md" || got.Content != "# Agenda" {
+		t.Errorf("envelope: %+v", got)
+	}
+	// Reference reads do not carry the guidance tip.
+	if got.Guidance != "" {
+		t.Errorf("reference read must not include guidance, got %q", got.Guidance)
+	}
+}
+
+func TestSkillReadUnknown(t *testing.T) {
+	_, _, err := run(t, calFS(), "read", "no-such")
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	if !strings.Contains(err.Error(), "unknown skill") {
+		t.Errorf("err: %v", err)
+	}
+}
+
+func TestSkillReadMissingArg(t *testing.T) {
+	_, _, err := run(t, calFS(), "read")
+	if err == nil || !strings.Contains(err.Error(), "requires 1 or 2 arguments") {
+		t.Fatalf("expected arg error, got %v", err)
+	}
+}
+
+func TestSkillReadTraversal(t *testing.T) {
+	stdout, _, err := run(t, calFS(), "read", "lark-calendar", "../../etc/passwd")
+	if err == nil {
+		t.Fatal("expected rejection")
+	}
+	if !strings.Contains(err.Error(), "invalid path") {
+		t.Errorf("err: %v", err)
+	}
+	if stdout != "" {
+		t.Errorf("stdout must be empty on rejection, got %q", stdout)
+	}
+}
+
+func TestSkillNilContentFS(t *testing.T) {
+	_, _, err := run(t, nil, "list")
+	if err == nil {
+		t.Fatal("expected error when SkillContent is nil")
+	}
+	if !strings.Contains(err.Error(), "not embedded") {
+		t.Errorf("err: %v", err)
+	}
+}

cmd/unknown_subcommand_test.go

@@ -11,6 +11,7 @@ import (
 
 	"github.com/spf13/cobra"
 
+	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/output"
 )
 
@@ -72,6 +73,149 @@ func TestInstallUnknownSubcommandGuard_PreservesExistingRunE(t *testing.T) {
 	}
 }
 
+func TestUnknownFlagTokens(t *testing.T) {
+	_, drive, _ := newGroupTree()
+	// Give a subcommand a flag so a misplaced-but-known flag (the user omitted
+	// the subcommand) is distinguished from a genuinely unknown one.
+	for _, c := range drive.Commands() {
+		if c.Name() == "+search" {
+			c.Flags().String("query", "", "")
+		}
+	}
+	cases := []struct {
+		name    string
+		rawArgs []string
+		want    []string
+	}{
+		{"genuinely unknown long flag", []string{"drive", "--badflag"}, []string{"--badflag"}},
+		{"flag known on a subcommand (misplaced)", []string{"drive", "--query", "x"}, nil},
+		{"no flags at all", []string{"drive"}, nil},
+		{"tokens after -- are positional", []string{"drive", "--", "--badflag"}, nil},
+		{"unknown shorthand", []string{"drive", "-Z"}, []string{"-Z"}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := unknownFlagTokens(drive, tc.rawArgs)
+			if len(got) != len(tc.want) {
+				t.Fatalf("unknownFlagTokens(%v) = %v, want %v", tc.rawArgs, got, tc.want)
+			}
+			for i := range got {
+				if got[i] != tc.want[i] {
+					t.Errorf("token[%d] = %q, want %q", i, got[i], tc.want[i])
+				}
+			}
+		})
+	}
+}
+
+func TestUnknownSubcommandRunE_FlagBeforeSubcommandIsStructured(t *testing.T) {
+	_, drive, _ := newGroupTree()
+	installUnknownSubcommandGuard(drive.Root())
+
+	// Simulate `lark-cli drive --badflag`: the UnknownFlags whitelist swallows
+	// --badflag, so RunE sees no args; the guard must recover it from
+	// rawInvocationArgs and fail structured rather than print help + exit 0.
+	rawInvocationArgs = []string{"drive", "--badflag"}
+	t.Cleanup(func() { rawInvocationArgs = nil })
+
+	err := drive.RunE(drive, nil)
+	if err == nil {
+		t.Fatal("expected a structured unknown_flag error, got nil (help fallthrough)")
+	}
+	if !strings.Contains(err.Error(), "unknown flag") {
+		t.Errorf("error = %q, want it to mention an unknown flag", err.Error())
+	}
+
+	// The detail must stay schema-compatible with flagDidYouMean's unknown_flag
+	// (same Type → same keys), so a consumer keyed on Type reads a stable shape.
+	exitErr, ok := err.(*output.ExitError)
+	if !ok || exitErr.Detail == nil {
+		t.Fatalf("expected *output.ExitError with Detail, got %T", err)
+	}
+	if exitErr.Detail.Type != "unknown_flag" {
+		t.Errorf("detail.Type = %q, want unknown_flag", exitErr.Detail.Type)
+	}
+	detail, ok := exitErr.Detail.Detail.(map[string]any)
+	if !ok {
+		t.Fatalf("expected detail to be map[string]any, got %T", exitErr.Detail.Detail)
+	}
+	if detail["unknown"] != "--badflag" {
+		t.Errorf("detail.unknown = %v, want --badflag", detail["unknown"])
+	}
+	if got, _ := detail["unknown_flags"].([]string); len(got) != 1 || got[0] != "--badflag" {
+		t.Errorf("detail.unknown_flags = %v, want [--badflag]", detail["unknown_flags"])
+	}
+	for _, key := range []string{"suggestions", "valid_flags"} {
+		if _, present := detail[key]; !present {
+			t.Errorf("detail.%s missing; must be present (empty) to match the unknown_flag schema", key)
+		}
+	}
+}
+
+func TestUnknownSubcommandRunE_ValidFlagWithoutSubcommandIsStructured(t *testing.T) {
+	_, drive, _ := newGroupTree()
+	// --query is defined on the +search subcommand, so it is a *valid* flag that
+	// was placed before the (omitted) subcommand. Unlike an unknown flag, this
+	// must still fail structured (missing_subcommand) rather than fall through to
+	// help + exit 0 — `drive --query x` is a malformed call, not a help request.
+	for _, c := range drive.Commands() {
+		if c.Name() == "+search" {
+			c.Flags().String("query", "", "")
+		}
+	}
+	installUnknownSubcommandGuard(drive.Root())
+
+	rawInvocationArgs = []string{"drive", "--query", "x"}
+	t.Cleanup(func() { rawInvocationArgs = nil })
+
+	err := drive.RunE(drive, nil)
+	if err == nil {
+		t.Fatal("expected a structured missing_subcommand error, got nil (help fallthrough)")
+	}
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T", err)
+	}
+	if exitErr.Code != output.ExitValidation {
+		t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
+	}
+	if exitErr.Detail == nil || exitErr.Detail.Type != "missing_subcommand" {
+		t.Fatalf("detail.Type = %v, want missing_subcommand", exitErr.Detail)
+	}
+	detail, ok := exitErr.Detail.Detail.(map[string]any)
+	if !ok {
+		t.Fatalf("detail is not a map: %#v", exitErr.Detail.Detail)
+	}
+	if flags, _ := detail["flags"].([]string); len(flags) != 1 || flags[0] != "--query" {
+		t.Errorf("detail.flags = %v, want [--query]", detail["flags"])
+	}
+	if detail["command_path"] != "lark-cli drive" {
+		t.Errorf("detail.command_path = %v, want lark-cli drive", detail["command_path"])
+	}
+}
+
+// A bare group carrying only a group-valid global flag (e.g. the inherited
+// --profile) is not missing a subcommand — those flags do not belong to a
+// subcommand — so it must print help, not fail with missing_subcommand.
+func TestUnknownSubcommandRunE_GroupValidGlobalFlagShowsHelp(t *testing.T) {
+	_, drive, _ := newGroupTree()
+	drive.Root().PersistentFlags().String("profile", "", "") // global, inherited by drive
+	installUnknownSubcommandGuard(drive.Root())
+
+	rawInvocationArgs = []string{"--profile", "p", "drive"}
+	t.Cleanup(func() { rawInvocationArgs = nil })
+
+	var buf bytes.Buffer
+	drive.SetOut(&buf)
+	drive.SetErr(&buf)
+	if err := drive.RunE(drive, nil); err != nil {
+		t.Fatalf("bare group with only a global flag should print help, got error: %v", err)
+	}
+	if !strings.Contains(buf.String(), "drive ops") {
+		t.Errorf("expected help output, got:\n%s", buf.String())
+	}
+}
+
 func TestUnknownSubcommandRunE_NoArgsShowsHelp(t *testing.T) {
 	_, drive, _ := newGroupTree()
 	installUnknownSubcommandGuard(drive.Root())
@@ -164,7 +308,7 @@ func TestAvailableSubcommandNames_FiltersHelpAndCompletion(t *testing.T) {
 		&cobra.Command{Use: "gamma", RunE: func(*cobra.Command, []string) error { return nil }},
 	)
 
-	got := availableSubcommandNames(root)
+	got, _ := availableSubcommandNames(root)
 	want := []string{"alpha", "gamma"}
 	if len(got) != len(want) {
 		t.Fatalf("expected %v, got %v", want, got)
@@ -175,3 +319,61 @@ func TestAvailableSubcommandNames_FiltersHelpAndCompletion(t *testing.T) {
 		}
 	}
 }
+
+func TestAvailableSubcommandNames_SplitsDeprecatedGroup(t *testing.T) {
+	root := &cobra.Command{Use: "lark-cli"}
+	root.AddGroup(&cobra.Group{ID: cmdutil.DeprecatedGroupID, Title: "Deprecated"})
+	root.AddCommand(
+		&cobra.Command{Use: "+new-cmd", RunE: func(*cobra.Command, []string) error { return nil }},
+		&cobra.Command{Use: "+old-cmd", GroupID: cmdutil.DeprecatedGroupID, RunE: func(*cobra.Command, []string) error { return nil }},
+	)
+
+	available, deprecated := availableSubcommandNames(root)
+	if len(available) != 1 || available[0] != "+new-cmd" {
+		t.Errorf("available = %v, want [+new-cmd]", available)
+	}
+	if len(deprecated) != 1 || deprecated[0] != "+old-cmd" {
+		t.Errorf("deprecated = %v, want [+old-cmd]", deprecated)
+	}
+}
+
+// unknownSubcommandRunE must split current vs deprecated subcommands into
+// separate detail buckets, while suggestions still rank across both so a
+// mistyped legacy alias resolves.
+func TestUnknownSubcommandRunE_SplitsDeprecatedBucket(t *testing.T) {
+	svc := &cobra.Command{Use: "sheets"}
+	svc.AddGroup(&cobra.Group{ID: cmdutil.DeprecatedGroupID, Title: "Deprecated"})
+	svc.AddCommand(
+		&cobra.Command{Use: "+cells-get", RunE: func(*cobra.Command, []string) error { return nil }},
+		&cobra.Command{Use: "+read", GroupID: cmdutil.DeprecatedGroupID, RunE: func(*cobra.Command, []string) error { return nil }},
+	)
+
+	err := unknownSubcommandRunE(svc, []string{"+reat"})
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T", err)
+	}
+	detail, ok := exitErr.Detail.Detail.(map[string]any)
+	if !ok {
+		t.Fatalf("detail is not a map: %#v", exitErr.Detail.Detail)
+	}
+
+	if available, _ := detail["available"].([]string); len(available) != 1 || available[0] != "+cells-get" {
+		t.Errorf("available = %v, want [+cells-get]", available)
+	}
+	deprecated, ok := detail["deprecated"].([]string)
+	if !ok || len(deprecated) != 1 || deprecated[0] != "+read" {
+		t.Errorf("deprecated = %v, want [+read]", deprecated)
+	}
+	// suggestions rank across both buckets: "+reat" is closest to +read.
+	suggestions, _ := detail["suggestions"].([]string)
+	found := false
+	for _, s := range suggestions {
+		if s == "+read" {
+			found = true
+		}
+	}
+	if !found {
+		t.Errorf("suggestions %v should include +read (typo target)", suggestions)
+	}
+}

cmd/update/update_test.go

@@ -49,18 +49,29 @@ func mockDetectAndNpm(t *testing.T, result selfupdate.DetectResult, npmFn func(s
 		u.DetectOverride = func() selfupdate.DetectResult { return result }
 		u.NpmInstallOverride = npmFn
 		u.VerifyOverride = func(string) error { return nil }
+		u.SkillsIndexFetchOverride = successfulSkillsIndexFetch()
 		u.SkillsCommandOverride = successfulSkillsCommand()
 		return u
 	}
 	t.Cleanup(func() { newUpdater = origNew })
 }
 
+func successfulSkillsIndexFetch() func() *selfupdate.NpmResult {
+	return func() *selfupdate.NpmResult {
+		r := &selfupdate.NpmResult{}
+		r.Stdout.WriteString(`{"skills":[{"name":"lark-calendar"},{"name":"lark-mail"}]}`)
+		return r
+	}
+}
+
 func successfulSkillsCommand() func(args ...string) *selfupdate.NpmResult {
 	return func(args ...string) *selfupdate.NpmResult {
 		r := &selfupdate.NpmResult{}
 		switch strings.Join(args, " ") {
 		case "-y skills add https://open.feishu.cn --list":
 			r.Stdout.WriteString("Available Skills\n │    lark-calendar\n │    lark-mail\n")
+		case "-y skills ls -g --json":
+			r.Stdout.WriteString(`[{"name":"lark-calendar","path":"/tmp/lark-calendar","scope":"global","agents":["Codex"]},{"name":"custom-skill","path":"/tmp/custom-skill","scope":"global","agents":["Codex"]}]`)
 		case "-y skills ls -g":
 			r.Stdout.WriteString("Global Skills\nlark-calendar /tmp/lark-calendar\ncustom-skill /tmp/custom-skill\n")
 		default:
@@ -476,6 +487,10 @@ func TestUpdateNpmVerifyFail_JSON_NoRestoreHintWhenBackupUnavailable(t *testing.
 		u.NpmInstallOverride = func(version string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} }
 		u.VerifyOverride = func(string) error { return errors.New("bad binary") }
 		u.RestoreAvailableOverride = func() bool { return false }
+		u.SkillsIndexFetchOverride = func() *selfupdate.NpmResult {
+			t.Fatal("skills sync should not run when binary verification fails")
+			return nil
+		}
 		u.SkillsCommandOverride = func(args ...string) *selfupdate.NpmResult {
 			t.Fatal("skills sync should not run when binary verification fails")
 			return nil
@@ -808,6 +823,11 @@ func TestUpdateNpm_SkillsFail_JSON(t *testing.T) {
 		}
 		u.NpmInstallOverride = func(version string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} }
 		u.VerifyOverride = func(string) error { return nil }
+		u.SkillsIndexFetchOverride = func() *selfupdate.NpmResult {
+			r := &selfupdate.NpmResult{}
+			r.Err = fmt.Errorf("index unavailable")
+			return r
+		}
 		u.SkillsCommandOverride = func(args ...string) *selfupdate.NpmResult {
 			r := &selfupdate.NpmResult{}
 			r.Stderr.WriteString("npx: command not found")
@@ -860,6 +880,11 @@ func TestUpdateNpm_SkillsFail_Human(t *testing.T) {
 		}
 		u.NpmInstallOverride = func(version string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} }
 		u.VerifyOverride = func(string) error { return nil }
+		u.SkillsIndexFetchOverride = func() *selfupdate.NpmResult {
+			r := &selfupdate.NpmResult{}
+			r.Err = fmt.Errorf("index unavailable")
+			return r
+		}
 		u.SkillsCommandOverride = func(args ...string) *selfupdate.NpmResult {
 			r := &selfupdate.NpmResult{}
 			r.Stderr.WriteString("npx: command not found")
@@ -1004,6 +1029,7 @@ func TestUpdateRun_AlreadyLatest_RunsSkillsSync(t *testing.T) {
 	t.Cleanup(func() { newUpdater = origNew })
 	newUpdater = func() *selfupdate.Updater {
 		return &selfupdate.Updater{
+			SkillsIndexFetchOverride: successfulSkillsIndexFetch(),
 			SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
 				skillsCalled = true
 				return successfulSkillsCommand()(args...)
@@ -1042,6 +1068,7 @@ func TestUpdateRun_Manual_RunsSkillsSync(t *testing.T) {
 	t.Cleanup(func() { newUpdater = origNew })
 	newUpdater = func() *selfupdate.Updater {
 		return &selfupdate.Updater{
+			SkillsIndexFetchOverride: successfulSkillsIndexFetch(),
 			DetectOverride: func() selfupdate.DetectResult {
 				return selfupdate.DetectResult{
 					Method:       selfupdate.InstallManual,
@@ -1086,6 +1113,7 @@ func TestUpdateRun_Npm_RunsSkillsSync_WritesLatestState(t *testing.T) {
 	t.Cleanup(func() { newUpdater = origNew })
 	newUpdater = func() *selfupdate.Updater {
 		return &selfupdate.Updater{
+			SkillsIndexFetchOverride: successfulSkillsIndexFetch(),
 			DetectOverride: func() selfupdate.DetectResult {
 				return selfupdate.DetectResult{
 					Method: selfupdate.InstallNpm, NpmAvailable: true,
@@ -1145,6 +1173,10 @@ func TestUpdateRun_CheckIncludesSkillsStatus(t *testing.T) {
 			DetectOverride: func() selfupdate.DetectResult {
 				return selfupdate.DetectResult{Method: selfupdate.InstallNpm, NpmAvailable: true}
 			},
+			SkillsIndexFetchOverride: func() *selfupdate.NpmResult {
+				skillsCalled = true
+				return successfulSkillsIndexFetch()()
+			},
 			SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
 				skillsCalled = true
 				return successfulSkillsCommand()(args...)
@@ -1194,6 +1226,10 @@ func TestUpdateRun_CheckAlreadyLatest_NoSideEffect(t *testing.T) {
 	t.Cleanup(func() { newUpdater = origNew })
 	newUpdater = func() *selfupdate.Updater {
 		return &selfupdate.Updater{
+			SkillsIndexFetchOverride: func() *selfupdate.NpmResult {
+				skillsCalled = true
+				return successfulSkillsIndexFetch()()
+			},
 			SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
 				skillsCalled = true
 				return successfulSkillsCommand()(args...)

errs/ERROR_CONTRACT.md

@@ -155,7 +155,30 @@ caller scripts.
 
 New code should not reach for `ErrBare` unless the command is
 genuinely a predicate. Anything carrying recoverable error content
-belongs in a typed `*errs.XxxError`.
+belongs in a typed `*errs.XxxError` — or, for a batch result, in the
+partial-failure outcome below.
+
+### Partial failure (batch / multi-status)
+
+A batch command (e.g. `drive +push` / `+pull` / `+sync`) that processes
+many items can finish in a third state, neither full success nor a single
+error: some items succeeded and some failed. Its primary output is the
+per-item result, so it does **not** belong in a `stderr` error envelope.
+
+Such a command returns `runtime.OutPartialFailure(data, meta)`, which:
+
+1. writes the full result to **stdout** as an `ok:false` envelope — the
+   summary and every per-item outcome (succeeded *and* failed) stay
+   machine-readable, exactly as a successful `Out(...)` would carry them,
+   but with `ok` honestly reporting failure; and
+2. returns `*output.PartialFailureError`, a typed exit signal the
+   dispatcher maps to a non-zero exit code while writing nothing further
+   to `stderr`.
+
+This is distinct from `ErrBare` (a predicate's one-bit answer) and from a
+typed `*errs.XxxError` (a `stderr` error envelope): a partial failure is a
+*result*, reported on stdout, that also failed. Consumers branch on
+`ok == false` and then read `data.summary` / `data.items[]`.
 
 ## Consumers
 

errs/subtypes.go

@@ -12,7 +12,8 @@ const (
 
 // CategoryValidation subtypes
 const (
-	SubtypeInvalidArgument Subtype = "invalid_argument" // user-supplied flag / arg failed validation (gRPC INVALID_ARGUMENT alignment)
+	SubtypeInvalidArgument    Subtype = "invalid_argument"    // user-supplied flag / arg failed validation (gRPC INVALID_ARGUMENT alignment)
+	SubtypeFailedPrecondition Subtype = "failed_precondition" // request is valid but the system/resource state is not in the state required to execute; caller must change state (not retry) — e.g. ambiguous remote mapping (gRPC FAILED_PRECONDITION alignment)
 )
 
 // CategoryAuthentication subtypes

errs/types.go

@@ -61,8 +61,22 @@ type TypedError interface {
 // it is intentionally not serialized.
 type ValidationError struct {
 	Problem
-	Param string `json:"param,omitempty"`
-	Cause error  `json:"-"`
+	Param  string         `json:"param,omitempty"`
+	Params []InvalidParam `json:"params,omitempty"`
+	Cause  error          `json:"-"`
+}
+
+// InvalidParam is one structured validation diagnostic: the parameter that
+// failed (Name) and why (Reason). It mirrors an RFC 7807 "invalid-params"
+// item (RFC 7807 §3.1 extension members).
+//
+// The wire key on ValidationError is "params" rather than "invalid_params"
+// because the enclosing envelope already carries type:"validation", so the
+// "invalid" qualifier would be redundant on the wire. The Go type keeps the
+// InvalidParam prefix because, at package level, the name must self-describe.
+type InvalidParam struct {
+	Name   string `json:"name"`
+	Reason string `json:"reason"`
 }
 
 // Unwrap exposes the wrapped cause so errors.Unwrap / errors.Is can traverse
@@ -122,6 +136,11 @@ func (e *ValidationError) WithParam(param string) *ValidationError {
 	return e
 }
 
+func (e *ValidationError) WithParams(params ...InvalidParam) *ValidationError {
+	e.Params = append(e.Params, params...)
+	return e
+}
+
 func (e *ValidationError) WithCause(cause error) *ValidationError {
 	e.Cause = cause
 	return e

errs/types_test.go

@@ -558,6 +558,71 @@ func TestTypedError_UnwrapSymmetry(t *testing.T) {
 	})
 }
 
+// TestValidationError_WithParams covers the structured-validation extension:
+// WithParams appends InvalidParam items, the scalar Param setter is unaffected,
+// and the wire shape nests {name, reason} under "params" (omitted when empty).
+func TestValidationError_WithParams(t *testing.T) {
+	t.Run("appends and exposes fields", func(t *testing.T) {
+		e := errs.NewValidationError(errs.SubtypeInvalidArgument, "duplicate rel_path").
+			WithParams(errs.InvalidParam{Name: "a.md", Reason: "duplicate"})
+		if len(e.Params) != 1 {
+			t.Fatalf("len(Params) = %d, want 1", len(e.Params))
+		}
+		if e.Params[0].Name != "a.md" {
+			t.Errorf("Params[0].Name = %q, want %q", e.Params[0].Name, "a.md")
+		}
+		if e.Params[0].Reason != "duplicate" {
+			t.Errorf("Params[0].Reason = %q, want %q", e.Params[0].Reason, "duplicate")
+		}
+	})
+
+	t.Run("appends across multiple calls and returns receiver", func(t *testing.T) {
+		e := errs.NewValidationError(errs.SubtypeInvalidArgument, "x")
+		returned := e.WithParams(errs.InvalidParam{Name: "a.md", Reason: "dup"})
+		if returned != e {
+			t.Errorf("WithParams returned different pointer; want same as receiver")
+		}
+		e.WithParams(
+			errs.InvalidParam{Name: "b.md", Reason: "dup"},
+			errs.InvalidParam{Name: "c.md", Reason: "dup"},
+		)
+		if len(e.Params) != 3 {
+			t.Fatalf("len(Params) = %d after two calls, want 3", len(e.Params))
+		}
+	})
+
+	t.Run("wire shape nests name and reason under params", func(t *testing.T) {
+		e := errs.NewValidationError(errs.SubtypeInvalidArgument, "duplicate rel_path").
+			WithParam("--rel-path").
+			WithParams(errs.InvalidParam{Name: "a.md", Reason: "duplicate"})
+		b, err := json.Marshal(e)
+		if err != nil {
+			t.Fatalf("marshal failed: %v", err)
+		}
+		got := string(b)
+		for _, want := range []string{
+			`"type":"validation"`,
+			`"param":"--rel-path"`,
+			`"params":[{"name":"a.md","reason":"duplicate"}]`,
+		} {
+			if !strings.Contains(got, want) {
+				t.Errorf("missing %q in %s", want, got)
+			}
+		}
+	})
+
+	t.Run("empty Params omitted from wire", func(t *testing.T) {
+		e := errs.NewValidationError(errs.SubtypeInvalidArgument, "x")
+		b, err := json.Marshal(e)
+		if err != nil {
+			t.Fatalf("marshal failed: %v", err)
+		}
+		if strings.Contains(string(b), `"params"`) {
+			t.Errorf("empty Params should be omitted from wire; got %s", b)
+		}
+	})
+}
+
 func TestBuilderSetter_DefensiveCopy(t *testing.T) {
 	t.Run("WithMissingScopes clones input", func(t *testing.T) {
 		scopes := []string{"docx:document", "im:message:send"}

events/register.go

@@ -8,6 +8,7 @@ import (
 	"github.com/larksuite/cli/events/im"
 	"github.com/larksuite/cli/events/minutes"
 	"github.com/larksuite/cli/events/vc"
+	"github.com/larksuite/cli/events/whiteboard"
 	"github.com/larksuite/cli/internal/event"
 )
 
@@ -17,6 +18,7 @@ func init() {
 		im.Keys(),
 		minutes.Keys(),
 		vc.Keys(),
+		whiteboard.Keys(),
 	}
 	for _, keys := range all {
 		for _, k := range keys {

events/whiteboard/native.go

@@ -0,0 +1,23 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package whiteboard
+
+// BoardWhiteboardUpdatedV1Data is the flattened whiteboard updated source payload.
+type BoardWhiteboardUpdatedV1Data struct {
+	// WhiteboardID is the id of the whiteboard whose content was updated.
+	WhiteboardID string `json:"whiteboard_id"`
+	// OperatorIDs lists the operators that produced this update batch.
+	OperatorIDs []OperatorID `json:"operator_ids"`
+}
+
+// OperatorID identifies an operator that produced the whiteboard update,
+// expressed in the three Lark identity formats.
+type OperatorID struct {
+	// OpenID is the operator's open_id within the current app.
+	OpenID string `json:"open_id"`
+	// UnionID is the operator's union_id across apps under the same ISV.
+	UnionID string `json:"union_id"`
+	// UserID is the operator's user_id within the tenant.
+	UserID string `json:"user_id"`
+}

events/whiteboard/preconsume.go

@@ -0,0 +1,48 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package whiteboard
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/larksuite/cli/internal/event"
+	"github.com/larksuite/cli/internal/validate"
+)
+
+// cleanupTimeout bounds how long the unsubscribe call has to finish during
+// PreConsume cleanup so a stuck OAPI cannot block process shutdown.
+const cleanupTimeout = 5 * time.Second
+
+// whiteboardSubscriptionPreConsume calls the whiteboard event subscribe OAPI
+// and returns a cleanup that invokes the matching unsubscribe.
+//
+// board.whiteboard.updated_v1 is subscribed per-whiteboard (by whiteboard_id),
+// so the path contains a :whiteboard_id placeholder that must be supplied via params.
+func whiteboardSubscriptionPreConsume(eventType string) func(context.Context, event.APIClient, map[string]string) (func(), error) {
+	return func(ctx context.Context, rt event.APIClient, params map[string]string) (func(), error) {
+		if rt == nil {
+			return nil, fmt.Errorf("runtime API client is required for pre-consume subscription")
+		}
+		whiteboardID := params["whiteboard_id"]
+		if whiteboardID == "" {
+			return nil, fmt.Errorf("param whiteboard_id is required for %s", eventType)
+		}
+		encoded := validate.EncodePathSegment(whiteboardID)
+		subscribePath := fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/subscribe", encoded)
+		unsubscribePath := fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/unsubscribe", encoded)
+
+		body := map[string]string{"event_type": eventType}
+		if _, err := rt.CallAPI(ctx, "POST", subscribePath, body); err != nil {
+			return nil, err
+		}
+
+		return func() {
+			cleanupCtx, cancel := context.WithTimeout(context.Background(), cleanupTimeout)
+			defer cancel()
+			_, _ = rt.CallAPI(cleanupCtx, "POST", unsubscribePath, body)
+		}, nil
+	}
+}

events/whiteboard/preconsume_test.go

@@ -0,0 +1,198 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package whiteboard
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/larksuite/cli/internal/event"
+)
+
+// recordedCall captures a single APIClient invocation for assertion.
+type recordedCall struct {
+	method string
+	path   string
+	body   interface{}
+}
+
+// fakeAPIClient is a minimal event.APIClient stub that records calls and
+// can be configured to fail when the request path matches errOnPath.
+type fakeAPIClient struct {
+	mu        sync.Mutex
+	calls     []recordedCall
+	errOnPath string
+}
+
+// CallAPI records the invocation and optionally returns a simulated error
+// when the path contains the configured errOnPath substring.
+func (f *fakeAPIClient) CallAPI(_ context.Context, method, path string, body interface{}) (json.RawMessage, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.calls = append(f.calls, recordedCall{method: method, path: path, body: body})
+	if f.errOnPath != "" && strings.Contains(path, f.errOnPath) {
+		return nil, errors.New("simulated subscribe failure")
+	}
+	return json.RawMessage(`{}`), nil
+}
+
+// TestWhiteboardSubscriptionPreConsume_MissingWhiteboardID verifies that the
+// PreConsume hook fails fast with an actionable error when whiteboard_id
+// is absent from the params map.
+func TestWhiteboardSubscriptionPreConsume_MissingWhiteboardID(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	pc := whiteboardSubscriptionPreConsume(eventTypeWhiteboardUpdated)
+	cleanup, err := pc(context.Background(), &fakeAPIClient{}, map[string]string{})
+	if err == nil {
+		t.Fatalf("expected error when whiteboard_id missing")
+	}
+	if cleanup != nil {
+		t.Fatalf("expected nil cleanup on error")
+	}
+	if !strings.Contains(err.Error(), "whiteboard_id") {
+		t.Fatalf("error should mention whiteboard_id, got: %v", err)
+	}
+}
+
+// TestWhiteboardSubscriptionPreConsume_NilRuntime verifies that PreConsume
+// returns an error when the runtime APIClient dependency is missing.
+func TestWhiteboardSubscriptionPreConsume_NilRuntime(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	pc := whiteboardSubscriptionPreConsume(eventTypeWhiteboardUpdated)
+	_, err := pc(context.Background(), nil, map[string]string{"whiteboard_id": "wb1"})
+	if err == nil {
+		t.Fatalf("expected error when runtime client is nil")
+	}
+}
+
+// TestWhiteboardSubscriptionPreConsume_SubscribeError verifies that a
+// failed subscribe call surfaces the error and skips registering a cleanup,
+// so no spurious unsubscribe is invoked.
+func TestWhiteboardSubscriptionPreConsume_SubscribeError(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	pc := whiteboardSubscriptionPreConsume(eventTypeWhiteboardUpdated)
+	rt := &fakeAPIClient{errOnPath: "/subscribe"}
+	cleanup, err := pc(context.Background(), rt, map[string]string{"whiteboard_id": "wb1"})
+	if err == nil {
+		t.Fatalf("expected error from subscribe call")
+	}
+	if cleanup != nil {
+		t.Fatalf("expected nil cleanup when subscribe fails")
+	}
+	// only the failed subscribe call should have been made; no unsubscribe.
+	if len(rt.calls) != 1 {
+		t.Fatalf("expected exactly 1 call (subscribe), got %d", len(rt.calls))
+	}
+}
+
+// TestWhiteboardSubscriptionPreConsume_SubscribeAndCleanup verifies the full
+// happy-path: subscribe is called once with the correct method/path/body,
+// and the returned cleanup invokes the matching unsubscribe.
+func TestWhiteboardSubscriptionPreConsume_SubscribeAndCleanup(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	pc := whiteboardSubscriptionPreConsume(eventTypeWhiteboardUpdated)
+	rt := &fakeAPIClient{}
+	cleanup, err := pc(context.Background(), rt, map[string]string{"whiteboard_id": "wb1"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if cleanup == nil {
+		t.Fatalf("expected non-nil cleanup")
+	}
+
+	if len(rt.calls) != 1 {
+		t.Fatalf("expected 1 call after subscribe, got %d", len(rt.calls))
+	}
+	got := rt.calls[0]
+	if got.method != "POST" {
+		t.Errorf("subscribe method: got %q, want POST", got.method)
+	}
+	wantSubPath := "/open-apis/board/v1/whiteboards/wb1/subscribe"
+	if got.path != wantSubPath {
+		t.Errorf("subscribe path: got %q, want %q", got.path, wantSubPath)
+	}
+	body, _ := got.body.(map[string]string)
+	if body["event_type"] != eventTypeWhiteboardUpdated {
+		t.Errorf("subscribe body event_type: got %q, want %q", body["event_type"], eventTypeWhiteboardUpdated)
+	}
+
+	cleanup()
+	if len(rt.calls) != 2 {
+		t.Fatalf("expected 2 calls after cleanup, got %d", len(rt.calls))
+	}
+	got2 := rt.calls[1]
+	if got2.method != "POST" {
+		t.Errorf("unsubscribe method: got %q, want POST", got2.method)
+	}
+	wantUnsubPath := "/open-apis/board/v1/whiteboards/wb1/unsubscribe"
+	if got2.path != wantUnsubPath {
+		t.Errorf("unsubscribe path: got %q, want %q", got2.path, wantUnsubPath)
+	}
+	body2, _ := got2.body.(map[string]string)
+	if body2["event_type"] != eventTypeWhiteboardUpdated {
+		t.Errorf("unsubscribe body event_type: got %q, want %q", body2["event_type"], eventTypeWhiteboardUpdated)
+	}
+}
+
+// TestWhiteboardSubscriptionPreConsume_PathSegmentEncoded verifies that
+// whiteboard_id values containing reserved URL characters are properly
+// path-segment encoded so they cannot escape into adjacent path segments.
+func TestWhiteboardSubscriptionPreConsume_PathSegmentEncoded(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	pc := whiteboardSubscriptionPreConsume(eventTypeWhiteboardUpdated)
+	rt := &fakeAPIClient{}
+	// 含特殊字符的 whiteboard_id 应被 path-segment 编码，避免越界到其他 path 段。
+	_, err := pc(context.Background(), rt, map[string]string{"whiteboard_id": "wb/1?evil"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rt.calls) != 1 {
+		t.Fatalf("expected 1 call, got %d", len(rt.calls))
+	}
+	if strings.Contains(rt.calls[0].path, "wb/1?evil") {
+		t.Errorf("whiteboard_id was not encoded; path: %s", rt.calls[0].path)
+	}
+}
+
+// TestWhiteboardUpdatedV1HasPreConsume ensures the registered EventKey for
+// board.whiteboard.updated_v1 wires the PreConsume hook and declares the
+// required whiteboard_id parameter.
+func TestWhiteboardUpdatedV1HasPreConsume(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	keys := Keys()
+	for _, k := range keys {
+		if k.Key == eventTypeWhiteboardUpdated {
+			if k.PreConsume == nil {
+				t.Fatalf("EventKey %s should have PreConsume hook", eventTypeWhiteboardUpdated)
+			}
+			if len(k.Params) == 0 {
+				t.Fatalf("EventKey %s should declare whiteboard_id param", eventTypeWhiteboardUpdated)
+			}
+			var found bool
+			for _, p := range k.Params {
+				if p.Name == "whiteboard_id" && p.Required {
+					found = true
+				}
+			}
+			if !found {
+				t.Fatalf("EventKey %s must declare required whiteboard_id param", eventTypeWhiteboardUpdated)
+			}
+			return
+		}
+	}
+	t.Fatalf("EventKey %s not registered", eventTypeWhiteboardUpdated)
+}
+
+// 确保 event.APIClient 接口与本测试 mock 一致。
+var _ event.APIClient = (*fakeAPIClient)(nil)

events/whiteboard/register.go

@@ -0,0 +1,48 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package whiteboard registers Board-domain EventKeys.
+package whiteboard
+
+import (
+	"reflect"
+
+	"github.com/larksuite/cli/internal/event"
+	"github.com/larksuite/cli/internal/event/schemas"
+)
+
+// eventTypeWhiteboardUpdated is the OAPI event type for whiteboard content updates.
+const eventTypeWhiteboardUpdated = "board.whiteboard.updated_v1"
+
+// Keys returns all Board-domain EventKey definitions.
+func Keys() []event.KeyDefinition {
+	return []event.KeyDefinition{
+		{
+			Key:         eventTypeWhiteboardUpdated,
+			DisplayName: "Whiteboard updated",
+			Description: "Pushed when the whiteboard content is updated.",
+			EventType:   eventTypeWhiteboardUpdated,
+			Params: []event.ParamDef{
+				{
+					Name:        "whiteboard_id",
+					Type:        event.ParamString,
+					Required:    true,
+					Description: "Whiteboard id to subscribe; subscription is per-whiteboard.",
+				},
+			},
+			Schema: event.SchemaDef{
+				Native: &event.SchemaSpec{Type: reflect.TypeOf(BoardWhiteboardUpdatedV1Data{})},
+				FieldOverrides: map[string]schemas.FieldMeta{
+					"/event/whiteboard_id":           {Kind: "whiteboard_id", Description: "whiteboard id to subscribe"},
+					"/event/operator_ids/*/open_id":  {Kind: "open_id"},
+					"/event/operator_ids/*/union_id": {Kind: "union_id"},
+					"/event/operator_ids/*/user_id":  {Kind: "user_id"},
+				},
+			},
+			PreConsume:            whiteboardSubscriptionPreConsume(eventTypeWhiteboardUpdated),
+			Scopes:                []string{"board:whiteboard:node:read"},
+			AuthTypes:             []string{"user", "bot"},
+			RequiredConsoleEvents: []string{eventTypeWhiteboardUpdated},
+		},
+	}
+}

go.mod

@@ -14,7 +14,7 @@ require (
 	github.com/sergi/go-diff v1.4.0
 	github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e
 	github.com/smartystreets/goconvey v1.8.1
-	github.com/spf13/cobra v1.10.2
+	github.com/spf13/cobra v1.10.2 // flag-error-text contract: see cmd/root.go unknownFlagName
 	github.com/spf13/pflag v1.0.9
 	github.com/stretchr/testify v1.11.1
 	github.com/tidwall/gjson v1.18.0

internal/auth/transport.go

@@ -14,7 +14,7 @@ import (
 
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/errclass"
-	"github.com/larksuite/cli/internal/util"
+	"github.com/larksuite/cli/internal/transport"
 )
 
 // SecurityPolicyTransport is an http.RoundTripper that intercepts all responses
@@ -28,7 +28,7 @@ func (t *SecurityPolicyTransport) base() http.RoundTripper {
 	if t.Base != nil {
 		return t.Base
 	}
-	return util.FallbackTransport()
+	return transport.Fallback()
 }
 
 // RoundTrip implements http.RoundTripper.

internal/cmdutil/factory.go

@@ -6,6 +6,7 @@ package cmdutil
 import (
 	"context"
 	"io"
+	"io/fs"
 	"net/http"
 	"strings"
 
@@ -29,10 +30,11 @@ type InvocationContext struct {
 }
 
 type Factory struct {
-	Config     func() (*core.CliConfig, error) // lazily loads app config from Credential
-	HttpClient func() (*http.Client, error)    // HTTP client for non-Lark API calls (with retry and security headers)
-	LarkClient func() (*lark.Client, error)    // Lark SDK client for all Open API calls
-	IOStreams  *IOStreams                      // stdin/stdout/stderr streams
+	Config      func() (*core.CliConfig, error) // lazily loads app config from Credential
+	ConfigBrand func() (core.LarkBrand, bool)   // brand only, no secret decryption — for startup help/registration (avoids keychain)
+	HttpClient  func() (*http.Client, error)    // HTTP client for non-Lark API calls (with retry and security headers)
+	LarkClient  func() (*lark.Client, error)    // Lark SDK client for all Open API calls
+	IOStreams   *IOStreams                      // stdin/stdout/stderr streams
 
 	Invocation           InvocationContext       // Immutable call context; do not mutate after Factory construction.
 	Keychain             keychain.KeychainAccess // secret storage (real keychain in prod, mock in tests)
@@ -43,6 +45,8 @@ type Factory struct {
 	Credential *credential.CredentialProvider
 
 	FileIOProvider fileio.Provider // file transfer provider (default: local filesystem)
+
+	SkillContent fs.FS // embedded skill tree (rooted at the skill list); nil when the build embeds no skills
 }
 
 // ResolveFileIO resolves a FileIO instance using the current execution context.
@@ -148,11 +152,14 @@ func (f *Factory) ResolveStrictMode(ctx context.Context) core.StrictMode {
 	if f.Credential == nil {
 		return core.StrictModeOff
 	}
-	acct, err := f.Credential.ResolveAccount(ctx)
-	if err != nil || acct == nil {
+	// Strict mode is plain config metadata; resolve it WITHOUT decrypting the
+	// app secret so identity-flag registration at startup never touches the
+	// keychain (ResolveStrictMode is called per command during Build).
+	_, supported, ok := f.Credential.ResolveMeta(ctx)
+	if !ok {
 		return core.StrictModeOff
 	}
-	ids := extcred.IdentitySupport(acct.SupportedIdentities)
+	ids := extcred.IdentitySupport(supported)
 	switch {
 	case ids.BotOnly():
 		return core.StrictModeBot

internal/cmdutil/factory_default.go

@@ -23,7 +23,7 @@ import (
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/registry"
 	_ "github.com/larksuite/cli/internal/security/contentsafety" // register content safety provider
-	"github.com/larksuite/cli/internal/util"
+	"github.com/larksuite/cli/internal/transport"
 	_ "github.com/larksuite/cli/internal/vfs/localfileio" // register default FileIO provider
 )
 
@@ -78,6 +78,18 @@ func NewDefault(streams *IOStreams, inv InvocationContext) *Factory {
 		return cfg, nil
 	})
 
+	// ConfigBrand resolves just the brand without decrypting the app secret, so
+	// brand-aware help and shortcut registration at startup do not touch the
+	// keychain. It still initializes the registry with the resolved brand — the
+	// same side effect Config has, minus the secret.
+	f.ConfigBrand = sync.OnceValues(func() (core.LarkBrand, bool) {
+		brand, _, ok := f.Credential.ResolveMeta(context.Background())
+		if ok {
+			registry.InitWithBrand(brand)
+		}
+		return brand, ok
+	})
+
 	// Phase 4: LarkClient from Credential (placeholder AppSecret)
 	f.LarkClient = cachedLarkClientFunc(f)
 
@@ -102,15 +114,15 @@ func safeRedirectPolicy(req *http.Request, via []*http.Request) error {
 
 func cachedHttpClientFunc(f *Factory) func() (*http.Client, error) {
 	return sync.OnceValues(func() (*http.Client, error) {
-		util.WarnIfProxied(f.IOStreams.ErrOut, f.IOStreams.IsTerminal)
+		transport.WarnIfProxied(f.IOStreams.ErrOut)
 
-		var transport http.RoundTripper = util.SharedTransport()
-		transport = &RetryTransport{Base: transport}
-		transport = &SecurityHeaderTransport{Base: transport}
-		transport = &auth.SecurityPolicyTransport{Base: transport} // Add our global response interceptor
-		transport = wrapWithExtension(transport)
+		var rt http.RoundTripper = transport.Shared()
+		rt = &RetryTransport{Base: rt}
+		rt = &SecurityHeaderTransport{Base: rt}
+		rt = &auth.SecurityPolicyTransport{Base: rt} // Add our global response interceptor
+		rt = wrapWithExtension(rt)
 		client := &http.Client{
-			Transport:     transport,
+			Transport:     rt,
 			Timeout:       30 * time.Second,
 			CheckRedirect: safeRedirectPolicy,
 		}
@@ -129,7 +141,7 @@ func cachedLarkClientFunc(f *Factory) func() (*lark.Client, error) {
 			lark.WithLogLevel(larkcore.LogLevelError),
 			lark.WithHeaders(BaseSecurityHeaders()),
 		}
-		util.WarnIfProxied(f.IOStreams.ErrOut, f.IOStreams.IsTerminal)
+		transport.WarnIfProxied(f.IOStreams.ErrOut)
 		opts = append(opts, lark.WithHttpClient(&http.Client{
 			Transport:     buildSDKTransport(),
 			CheckRedirect: safeRedirectPolicy,
@@ -141,7 +153,7 @@ func cachedLarkClientFunc(f *Factory) func() (*lark.Client, error) {
 }
 
 func buildSDKTransport() http.RoundTripper {
-	var sdkTransport http.RoundTripper = util.SharedTransport()
+	var sdkTransport http.RoundTripper = transport.Shared()
 	sdkTransport = &RetryTransport{Base: sdkTransport}
 	sdkTransport = &UserAgentTransport{Base: sdkTransport}
 	sdkTransport = &BuildHeaderTransport{Base: sdkTransport}

internal/cmdutil/groups.go

@@ -0,0 +1,18 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmdutil
+
+import "github.com/spf13/cobra"
+
+// DeprecatedGroupID is the cobra GroupID that marks a backward-compatibility
+// command — one kept alive for users whose skill predates a refactor. Service
+// registration assigns it (e.g. the sheets pre-refactor aliases); both --help
+// rendering and unknown-subcommand suggestions read it to separate these
+// aliases from the current commands.
+const DeprecatedGroupID = "deprecated"
+
+// IsDeprecatedCommand reports whether c was tagged into the deprecated group.
+func IsDeprecatedCommand(c *cobra.Command) bool {
+	return c != nil && c.GroupID == DeprecatedGroupID
+}

internal/cmdutil/testing.go

@@ -65,7 +65,13 @@ func TestFactory(t *testing.T, config *core.CliConfig) (*Factory, *bytes.Buffer,
 	)
 
 	f := &Factory{
-		Config:         func() (*core.CliConfig, error) { return config, nil },
+		Config: func() (*core.CliConfig, error) { return config, nil },
+		ConfigBrand: func() (core.LarkBrand, bool) {
+			if config != nil {
+				return config.Brand, true
+			}
+			return "", false
+		},
 		HttpClient:     func() (*http.Client, error) { return mockClient, nil },
 		LarkClient:     func() (*lark.Client, error) { return testLarkClient, nil },
 		IOStreams:      &IOStreams{In: nil, Out: stdoutBuf, ErrOut: stderrBuf},

internal/cmdutil/transport.go

@@ -9,7 +9,7 @@ import (
 	"time"
 
 	exttransport "github.com/larksuite/cli/extension/transport"
-	"github.com/larksuite/cli/internal/util"
+	"github.com/larksuite/cli/internal/transport"
 )
 
 // RetryTransport is an http.RoundTripper that retries on 5xx responses
@@ -24,7 +24,7 @@ func (t *RetryTransport) base() http.RoundTripper {
 	if t.Base != nil {
 		return t.Base
 	}
-	return util.FallbackTransport()
+	return transport.Fallback()
 }
 
 func (t *RetryTransport) delay() time.Duration {
@@ -69,7 +69,7 @@ func (t *UserAgentTransport) RoundTrip(req *http.Request) (*http.Response, error
 	if t.Base != nil {
 		return t.Base.RoundTrip(req)
 	}
-	return util.FallbackTransport().RoundTrip(req)
+	return transport.Fallback().RoundTrip(req)
 }
 
 // BuildHeaderTransport is an http.RoundTripper that force-writes the
@@ -87,7 +87,7 @@ func (t *BuildHeaderTransport) RoundTrip(req *http.Request) (*http.Response, err
 	if t.Base != nil {
 		return t.Base.RoundTrip(req)
 	}
-	return util.FallbackTransport().RoundTrip(req)
+	return transport.Fallback().RoundTrip(req)
 }
 
 // SecurityHeaderTransport is an http.RoundTripper that injects CLI security
@@ -100,7 +100,7 @@ func (t *SecurityHeaderTransport) base() http.RoundTripper {
 	if t.Base != nil {
 		return t.Base
 	}
-	return util.FallbackTransport()
+	return transport.Fallback()
 }
 
 // RoundTrip implements http.RoundTripper.

internal/cmdutil/transport_test.go

@@ -332,7 +332,7 @@ func TestBuildHeaderTransport_OverridesEvenWithoutTamper(t *testing.T) {
 
 // TestBuildHeaderTransport_NilBase_UsesFallback verifies that when Base is nil,
 // the transport still sets X-Cli-Build and routes the request through
-// util.FallbackTransport rather than panicking. This covers the fallback
+// transport.Fallback rather than panicking. This covers the fallback
 // branch in RoundTrip that is otherwise unreachable with a non-nil Base.
 func TestBuildHeaderTransport_NilBase_UsesFallback(t *testing.T) {
 	var receivedBuild string

internal/credential/credential_provider.go

@@ -21,6 +21,14 @@ type DefaultAccountResolver interface {
 	ResolveAccount(ctx context.Context) (*Account, error)
 }
 
+// metaResolver is an optional capability: resolve config metadata (brand +
+// strict-mode identity support) without resolving the app secret (no keychain
+// access). Providers that don't implement it fall back to ResolveAccount inside
+// CredentialProvider.ResolveMeta.
+type metaResolver interface {
+	ResolveMeta(ctx context.Context) (core.LarkBrand, uint8, bool)
+}
+
 // DefaultTokenResolver is implemented by the default token provider.
 type DefaultTokenResolver interface {
 	ResolveToken(ctx context.Context, req TokenSpec) (*TokenResult, error)
@@ -141,6 +149,11 @@ type CredentialProvider struct {
 	accountErr     error
 	selectedSource credentialSource
 
+	metaOnce   sync.Once
+	metaBrand  core.LarkBrand
+	metaIdents uint8
+	metaOK     bool
+
 	hintOnce sync.Once
 	hint     *IdentityHint
 	hintErr  error
@@ -172,6 +185,44 @@ func (p *CredentialProvider) ResolveAccount(ctx context.Context) (*Account, erro
 	return p.account, p.accountErr
 }
 
+// ResolveMeta resolves config metadata — brand and strict-mode identity support
+// — cheaply, WITHOUT decrypting the app secret for the default
+// (config.json/keychain) provider. It mirrors doResolveAccount's provider
+// selection: external providers (env/sidecar) are asked first via ResolveAccount
+// (they do not touch the keychain), then the default provider's keychain-free
+// metaResolver path. Cached after first call. Best-effort: returns ok=false when
+// nothing is configured, so callers keep their defaults. Used for brand-aware
+// help text, shortcut registration, and strict-mode checks at startup, where
+// decrypting the secret would be wasteful.
+func (p *CredentialProvider) ResolveMeta(ctx context.Context) (core.LarkBrand, uint8, bool) {
+	p.metaOnce.Do(func() {
+		p.metaBrand, p.metaIdents, p.metaOK = p.doResolveMeta(ctx)
+	})
+	return p.metaBrand, p.metaIdents, p.metaOK
+}
+
+func (p *CredentialProvider) doResolveMeta(ctx context.Context) (core.LarkBrand, uint8, bool) {
+	for _, prov := range p.providers {
+		acct, err := prov.ResolveAccount(ctx)
+		if err != nil {
+			return "", 0, false
+		}
+		if acct != nil {
+			internal := convertAccount(acct)
+			return internal.Brand, internal.SupportedIdentities, true
+		}
+	}
+	if p.defaultAcct != nil {
+		if mr, ok := p.defaultAcct.(metaResolver); ok {
+			return mr.ResolveMeta(ctx)
+		}
+		if acct, err := p.defaultAcct.ResolveAccount(ctx); err == nil && acct != nil {
+			return acct.Brand, acct.SupportedIdentities, true
+		}
+	}
+	return "", 0, false
+}
+
 func (p *CredentialProvider) doResolveAccount(ctx context.Context) (*Account, error) {
 	for _, prov := range p.providers {
 		acct, err := prov.ResolveAccount(ctx)

internal/credential/default_provider.go

@@ -4,9 +4,7 @@
 package credential
 
 import (
-	"bytes"
 	"context"
-	"encoding/json"
 	"fmt"
 	"io"
 	"net/http"
@@ -78,6 +76,23 @@ func (p *DefaultAccountProvider) ResolveAccount(ctx context.Context) (*Account,
 	return AccountFromCliConfig(cfg), nil
 }
 
+// ResolveMeta returns config metadata — brand and the strict-mode identity
+// support — from config.json WITHOUT resolving the app secret (no keychain
+// access). Both are plain config fields, so brand-aware help, shortcut
+// registration, and strict-mode checks at startup need not decrypt the secret.
+// Returns ok=false when no config exists, so callers keep their defaults.
+func (p *DefaultAccountProvider) ResolveMeta(_ context.Context) (core.LarkBrand, uint8, bool) {
+	multi, err := core.LoadMultiAppConfig()
+	if err != nil {
+		return "", 0, false
+	}
+	app := multi.CurrentAppConfig(p.profile)
+	if app == nil {
+		return "", 0, false
+	}
+	return app.Brand, strictModeToIdentitySupport(multi, p.profile), true
+}
+
 // strictModeToIdentitySupport maps the config-level strict mode to
 // the SupportedIdentities bitflag using an already-loaded MultiAppConfig.
 func strictModeToIdentitySupport(multi *core.MultiAppConfig, profileOverride string) uint8 {
@@ -166,42 +181,9 @@ func (p *DefaultTokenProvider) doResolveTAT(ctx context.Context) (*TokenResult,
 	if err != nil {
 		return nil, err
 	}
-	ep := core.ResolveEndpoints(acct.Brand)
-	url := ep.Open + "/open-apis/auth/v3/tenant_access_token/internal"
-
-	body, err := json.Marshal(map[string]string{
-		"app_id":     acct.AppID,
-		"app_secret": acct.AppSecret,
-	})
-	if err != nil {
-		return nil, fmt.Errorf("failed to marshal TAT request: %w", err)
-	}
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body))
+	token, err := FetchTAT(ctx, httpClient, acct.Brand, acct.AppID, acct.AppSecret)
 	if err != nil {
 		return nil, err
 	}
-	req.Header.Set("Content-Type", "application/json")
-
-	resp, err := httpClient.Do(req)
-	if err != nil {
-		return nil, err
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != http.StatusOK {
-		return nil, fmt.Errorf("TAT API returned HTTP %d", resp.StatusCode)
-	}
-
-	var result struct {
-		Code              int    `json:"code"`
-		Msg               string `json:"msg"`
-		TenantAccessToken string `json:"tenant_access_token"`
-	}
-	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
-		return nil, fmt.Errorf("failed to parse TAT response: %w", err)
-	}
-	if result.Code != 0 {
-		return nil, classifyTATResponseCode(result.Code, result.Msg, string(acct.Brand), acct.AppID)
-	}
-	return &TokenResult{Token: result.TenantAccessToken}, nil
+	return &TokenResult{Token: token}, nil
 }

internal/credential/tat_fetch.go

@@ -0,0 +1,70 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package credential
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+
+	"github.com/larksuite/cli/internal/core"
+)
+
+// FetchTAT performs a single HTTP POST to mint a tenant access token with the
+// given credentials. It does not read configuration or keychain, so callers
+// that already hold plaintext credentials (e.g. the post-`config init` probe)
+// can validate them without a second keychain round-trip.
+//
+// A non-zero TAT response code means the server inspected the payload and
+// rejected the credentials; FetchTAT returns the canonical typed error from
+// classifyTATResponseCode — the SAME classification doResolveTAT (and thus
+// every token-resolving command) produces, so callers see one consistent
+// envelope (CategoryConfig / SubtypeInvalidClient for 10003 / 10014, etc.).
+// Transport, HTTP-status and JSON-parse failures are returned raw (untyped),
+// leaving them ambiguous; a caller can use errs.IsTyped to tell a deterministic
+// credential rejection apart from upstream/transport noise.
+//
+// The caller owns the context timeout.
+func FetchTAT(ctx context.Context, httpClient *http.Client, brand core.LarkBrand, appID, appSecret string) (string, error) {
+	ep := core.ResolveEndpoints(brand)
+	url := ep.Open + "/open-apis/auth/v3/tenant_access_token/internal"
+
+	body, err := json.Marshal(map[string]string{
+		"app_id":     appID,
+		"app_secret": appSecret,
+	})
+	if err != nil {
+		return "", fmt.Errorf("failed to marshal TAT request: %w", err)
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body))
+	if err != nil {
+		return "", err
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := httpClient.Do(req)
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("TAT API returned HTTP %d", resp.StatusCode)
+	}
+
+	var result struct {
+		Code              int    `json:"code"`
+		Msg               string `json:"msg"`
+		TenantAccessToken string `json:"tenant_access_token"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+		return "", fmt.Errorf("failed to parse TAT response: %w", err)
+	}
+	if result.Code != 0 {
+		return "", classifyTATResponseCode(result.Code, result.Msg, string(brand), appID)
+	}
+	return result.TenantAccessToken, nil
+}

internal/credential/tat_fetch_test.go

@@ -0,0 +1,237 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package credential
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/core"
+)
+
+// stubRoundTripper lets us assert request shape and return canned responses.
+type stubRoundTripper struct {
+	gotReq   *http.Request
+	gotBody  string
+	respCode int
+	respBody string
+	err      error
+}
+
+func (s *stubRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) {
+	s.gotReq = req
+	if req.Body != nil {
+		b, _ := io.ReadAll(req.Body)
+		s.gotBody = string(b)
+	}
+	if s.err != nil {
+		return nil, s.err
+	}
+	return &http.Response{
+		StatusCode: s.respCode,
+		Body:       io.NopCloser(strings.NewReader(s.respBody)),
+		Header:     make(http.Header),
+	}, nil
+}
+
+func TestFetchTAT_Success(t *testing.T) {
+	rt := &stubRoundTripper{
+		respCode: 200,
+		respBody: `{"code":0,"tenant_access_token":"t-abc","msg":"ok"}`,
+	}
+	hc := &http.Client{Transport: rt}
+
+	token, err := FetchTAT(context.Background(), hc, core.BrandFeishu, "cli_app", "secret_x")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if token != "t-abc" {
+		t.Errorf("token = %q, want t-abc", token)
+	}
+	if rt.gotReq.URL.String() != "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" {
+		t.Errorf("url = %s", rt.gotReq.URL.String())
+	}
+	if !strings.Contains(rt.gotBody, `"app_id":"cli_app"`) || !strings.Contains(rt.gotBody, `"app_secret":"secret_x"`) {
+		t.Errorf("request body missing credentials: %s", rt.gotBody)
+	}
+}
+
+// 10003 (bad / non-existent app_id, "invalid param") is classified locally by
+// classifyTATResponseCode as CategoryConfig / SubtypeInvalidClient — the same
+// typed error doResolveTAT (and thus every token-resolving command) returns.
+func TestFetchTAT_Code10003_ConfigInvalidClient(t *testing.T) {
+	rt := &stubRoundTripper{respCode: 200, respBody: `{"code":10003,"msg":"invalid param"}`}
+	hc := &http.Client{Transport: rt}
+
+	token, err := FetchTAT(context.Background(), hc, core.BrandFeishu, "cli_app", "secret_x")
+	if err == nil {
+		t.Fatal("expected error for code 10003")
+	}
+	if token != "" {
+		t.Errorf("token = %q, want empty", token)
+	}
+	var cfgErr *errs.ConfigError
+	if !errors.As(err, &cfgErr) {
+		t.Fatalf("error not *errs.ConfigError: %T %v", err, err)
+	}
+	if cfgErr.Category != errs.CategoryConfig {
+		t.Errorf("Category = %q, want %q", cfgErr.Category, errs.CategoryConfig)
+	}
+	if cfgErr.Subtype != errs.SubtypeInvalidClient {
+		t.Errorf("Subtype = %q, want %q", cfgErr.Subtype, errs.SubtypeInvalidClient)
+	}
+	if cfgErr.Code != 10003 {
+		t.Errorf("Code = %d, want 10003", cfgErr.Code)
+	}
+}
+
+// 10014 ("app secret invalid") — the most common real-world rejection (real
+// app_id + wrong secret) — is globally mapped in codemeta to
+// CategoryConfig / SubtypeInvalidClient via BuildAPIError.
+func TestFetchTAT_Code10014_ConfigInvalidClient(t *testing.T) {
+	rt := &stubRoundTripper{respCode: 200, respBody: `{"code":10014,"msg":"app secret invalid"}`}
+	hc := &http.Client{Transport: rt}
+
+	_, err := FetchTAT(context.Background(), hc, core.BrandFeishu, "cli_app", "secret_x")
+	var cfgErr *errs.ConfigError
+	if !errors.As(err, &cfgErr) {
+		t.Fatalf("error not *errs.ConfigError: %T %v", err, err)
+	}
+	if cfgErr.Subtype != errs.SubtypeInvalidClient || cfgErr.Code != 10014 {
+		t.Errorf("got Subtype=%q Code=%d, want invalid_client/10014", cfgErr.Subtype, cfgErr.Code)
+	}
+}
+
+// Any non-zero body code is a deterministic server-side rejection, so it
+// always yields a typed error (errs.IsTyped). An unrecognized code falls back
+// to CategoryAPI / SubtypeUnknown via BuildAPIError — still typed, so a probe
+// caller still surfaces it rather than silently swallowing.
+func TestFetchTAT_UnknownBodyCode_Typed(t *testing.T) {
+	rt := &stubRoundTripper{respCode: 200, respBody: `{"code":99999,"msg":"future-unknown"}`}
+	hc := &http.Client{Transport: rt}
+
+	_, err := FetchTAT(context.Background(), hc, core.BrandFeishu, "cli_app", "secret_x")
+	if err == nil {
+		t.Fatal("expected error for code 99999")
+	}
+	if !errs.IsTyped(err) {
+		t.Fatalf("expected a typed errs.* error, got %T %v", err, err)
+	}
+	var apiErr *errs.APIError
+	if !errors.As(err, &apiErr) {
+		t.Errorf("unknown code should fall back to *errs.APIError, got %T", err)
+	}
+}
+
+// Non-2xx HTTP is ambiguous (not a payload-level credential rejection) — it
+// must stay UNTYPED so a probe caller treats it as upstream noise and stays
+// silent.
+func TestFetchTAT_HTTPNon200_Untyped(t *testing.T) {
+	for _, code := range []int{401, 403, 500, 503} {
+		rt := &stubRoundTripper{respCode: code, respBody: `whatever`}
+		hc := &http.Client{Transport: rt}
+		_, err := FetchTAT(context.Background(), hc, core.BrandFeishu, "cli_app", "secret_x")
+		if err == nil {
+			t.Fatalf("HTTP %d: expected error", code)
+		}
+		if errs.IsTyped(err) {
+			t.Errorf("HTTP %d: must be UNTYPED (ambiguous), got typed %T %v", code, err, err)
+		}
+	}
+}
+
+func TestFetchTAT_TransportError_Untyped(t *testing.T) {
+	sentinel := errors.New("network down")
+	rt := &stubRoundTripper{err: sentinel}
+	hc := &http.Client{Transport: rt}
+
+	_, err := FetchTAT(context.Background(), hc, core.BrandFeishu, "cli_app", "secret_x")
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	if errs.IsTyped(err) {
+		t.Errorf("transport error must be UNTYPED, got typed %T", err)
+	}
+	if !errors.Is(err, sentinel) {
+		t.Errorf("error chain missing sentinel: %v", err)
+	}
+}
+
+func TestFetchTAT_ParseError_Untyped(t *testing.T) {
+	rt := &stubRoundTripper{respCode: 200, respBody: `not json`}
+	hc := &http.Client{Transport: rt}
+
+	_, err := FetchTAT(context.Background(), hc, core.BrandFeishu, "cli_app", "secret_x")
+	if err == nil {
+		t.Fatal("expected parse error")
+	}
+	if errs.IsTyped(err) {
+		t.Errorf("parse error must be UNTYPED, got typed %T", err)
+	}
+}
+
+func TestFetchTAT_BrandRouting(t *testing.T) {
+	tests := []struct {
+		brand   core.LarkBrand
+		wantURL string
+	}{
+		{core.BrandFeishu, "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal"},
+		{core.BrandLark, "https://open.larksuite.com/open-apis/auth/v3/tenant_access_token/internal"},
+	}
+	for _, tc := range tests {
+		t.Run(string(tc.brand), func(t *testing.T) {
+			rt := &stubRoundTripper{respCode: 200, respBody: `{"code":0,"tenant_access_token":"t"}`}
+			hc := &http.Client{Transport: rt}
+			if _, err := FetchTAT(context.Background(), hc, tc.brand, "a", "b"); err != nil {
+				t.Fatal(err)
+			}
+			if got := rt.gotReq.URL.String(); got != tc.wantURL {
+				t.Errorf("url = %s, want %s", got, tc.wantURL)
+			}
+		})
+	}
+}
+
+func TestFetchTAT_ContextCanceled(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		<-r.Context().Done()
+	}))
+	defer srv.Close()
+
+	rt := &urlRewriteRT{base: srv.URL}
+	hc := &http.Client{Transport: rt}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel() // pre-canceled
+
+	_, err := FetchTAT(ctx, hc, core.BrandFeishu, "a", "b")
+	if err == nil {
+		t.Fatal("expected error for canceled context")
+	}
+	if errs.IsTyped(err) {
+		t.Errorf("canceled context must be UNTYPED, got typed %T", err)
+	}
+	if !errors.Is(err, context.Canceled) {
+		t.Errorf("error chain missing context.Canceled: %v", err)
+	}
+}
+
+// urlRewriteRT forwards requests to a fixed base URL (test server).
+type urlRewriteRT struct{ base string }
+
+func (r *urlRewriteRT) RoundTrip(req *http.Request) (*http.Response, error) {
+	newURL := r.base + req.URL.Path
+	req2, err := http.NewRequestWithContext(req.Context(), req.Method, newURL, req.Body)
+	if err != nil {
+		return nil, err
+	}
+	req2.Header = req.Header
+	return http.DefaultTransport.RoundTrip(req2)
+}

internal/deprecation/deprecation.go

@@ -0,0 +1,57 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package deprecation carries a process-level notice that the command currently
+// being executed is a backward-compatibility alias, kept alive for users whose
+// skill predates a refactor. The notice is surfaced in JSON output envelopes via
+// output.PendingNotice (wired in cmd/root.go), mirroring internal/skillscheck.
+//
+// A CLI process runs exactly one shortcut, so a single process-level slot is
+// sufficient: the command's Execute records the notice before producing output,
+// and the output layer reads it back when building the envelope.
+package deprecation
+
+import (
+	"strings"
+	"sync/atomic"
+)
+
+// Notice describes a deprecated command alias and the current command that
+// replaces it. Replacement and Skill are optional.
+type Notice struct {
+	Command     string `json:"command"`
+	Replacement string `json:"replacement,omitempty"`
+	Skill       string `json:"skill,omitempty"`
+}
+
+// Message returns a single-line, AI-agent-parseable description of the alias
+// plus the canonical fix (update the skill). Mirrors the style of
+// internal/skillscheck.StaleNotice.Message ("..., run: lark-cli update").
+func (n *Notice) Message() string {
+	var b strings.Builder
+	b.WriteString(n.Command)
+	b.WriteString(" is a pre-refactor compatibility alias")
+	if n.Replacement != "" {
+		b.WriteString("; use ")
+		b.WriteString(n.Replacement)
+		b.WriteString(" instead")
+	}
+	if n.Skill != "" {
+		b.WriteString("; update your ")
+		b.WriteString(n.Skill)
+		b.WriteString(" skill, run: lark-cli update")
+	} else {
+		b.WriteString("; update your skill, run: lark-cli update")
+	}
+	return b.String()
+}
+
+// pending stores the latest deprecation notice for the current process.
+var pending atomic.Pointer[Notice]
+
+// SetPending stores the notice for consumption by output decorators.
+// Pass nil to clear.
+func SetPending(n *Notice) { pending.Store(n) }
+
+// GetPending returns the pending deprecation notice, or nil.
+func GetPending() *Notice { return pending.Load() }

internal/deprecation/deprecation_test.go

@@ -0,0 +1,58 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package deprecation
+
+import "testing"
+
+func TestNoticeMessage(t *testing.T) {
+	tests := []struct {
+		name   string
+		notice Notice
+		want   string
+	}{
+		{
+			name:   "replacement and skill",
+			notice: Notice{Command: "+read", Replacement: "+cells-get", Skill: "lark-sheets"},
+			want:   "+read is a pre-refactor compatibility alias; use +cells-get instead; update your lark-sheets skill, run: lark-cli update",
+		},
+		{
+			name:   "no replacement",
+			notice: Notice{Command: "+read", Skill: "lark-sheets"},
+			want:   "+read is a pre-refactor compatibility alias; update your lark-sheets skill, run: lark-cli update",
+		},
+		{
+			name:   "no skill",
+			notice: Notice{Command: "+read", Replacement: "+cells-get"},
+			want:   "+read is a pre-refactor compatibility alias; use +cells-get instead; update your skill, run: lark-cli update",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := tt.notice.Message(); got != tt.want {
+				t.Errorf("Message() =\n  %q\nwant\n  %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestSetGetPending(t *testing.T) {
+	t.Cleanup(func() { SetPending(nil) })
+
+	SetPending(nil)
+	if got := GetPending(); got != nil {
+		t.Fatalf("expected nil pending after clear, got %#v", got)
+	}
+
+	n := &Notice{Command: "+write", Replacement: "+cells-set", Skill: "lark-sheets"}
+	SetPending(n)
+	got := GetPending()
+	if got == nil || got.Command != "+write" || got.Replacement != "+cells-set" {
+		t.Fatalf("GetPending() = %#v, want %#v", got, n)
+	}
+
+	SetPending(nil)
+	if GetPending() != nil {
+		t.Fatal("expected nil after clearing")
+	}
+}

internal/errclass/classify.go

@@ -92,6 +92,18 @@ func BuildAPIError(resp map[string]any, cc ClassifyContext) error {
 			base.Troubleshooter = ts
 		}
 	}
+	// Upstream-provided field-level reasons (resp.error.details[].value). Lark
+	// returns these as free-text reason strings with no machine-readable field
+	// name (verified for code 190014:
+	// {"error":{"details":[{"value":"end_time should be later than start_time"}]}}),
+	// so they are lifted into Problem.Hint — the sanctioned free-text recovery
+	// prompt — rather than fabricated structured params. Lifted before the
+	// category switch so any classified arm inherits it; the CategoryAPI arm
+	// below prefers this server detail over the context-free APIHint default.
+	detailHint := liftErrorDetailValues(resp)
+	if detailHint != "" {
+		base.Hint = detailHint
+	}
 
 	switch meta.Category {
 	case errs.CategoryAuthorization:
@@ -129,6 +141,11 @@ func BuildAPIError(resp map[string]any, cc ClassifyContext) error {
 			Action:  action,
 		}
 	case errs.CategoryAPI:
+		// A server-supplied detail (lifted into base.Hint above) wins over the
+		// context-free APIHint default; only fall back to APIHint when absent.
+		if base.Hint == "" {
+			base.Hint = APIHint(base.Subtype) // "" for subtypes without a context-free default
+		}
 		return &errs.APIError{Problem: base}
 	default:
 		// Fail closed: an unrecognized Category routes to InternalError
@@ -213,6 +230,10 @@ func stringFromAny(v any) string {
 // per-subtype recovery hint before returning it, so the wire envelope
 // emitted via BuildAPIError always carries a hint for known config subtypes.
 func buildConfigError(p errs.Problem) *errs.ConfigError {
+	// Config categories have authoritative recovery guidance, so the curated
+	// ConfigHint deliberately overrides any server detail lifted into p.Hint
+	// (the opposite precedence from the CategoryAPI arm, where the lifted
+	// detail wins).
 	p.Hint = ConfigHint(p.Subtype)
 	return &errs.ConfigError{Problem: p}
 }
@@ -231,6 +252,24 @@ func ConfigHint(subtype errs.Subtype) string {
 	return ""
 }
 
+// APIHint returns the canonical per-subtype recovery hint for a typed APIError
+// emitted via BuildAPIError, for API subtypes whose recovery is context-free.
+// Context-specific guidance (e.g. a command's flags, an API's own quota) is
+// layered on by the caller after BuildAPIError returns and overrides this.
+func APIHint(subtype errs.Subtype) string {
+	switch subtype {
+	case errs.SubtypeConflict:
+		return "retry later and avoid concurrent duplicate requests on the same resource"
+	case errs.SubtypeCrossTenant:
+		return "operate on source and target within the same tenant and region/unit"
+	case errs.SubtypeCrossBrand:
+		return "operate on source and target within the same brand environment"
+	case errs.SubtypeQuotaExceeded:
+		return "reduce the request volume or free quota, then retry after the relevant quota resets"
+	}
+	return ""
+}
+
 func buildPermissionError(p errs.Problem, resp map[string]any, cc ClassifyContext) *errs.PermissionError {
 	missing := extractMissingScopes(resp)
 	identity := cc.Identity
@@ -239,6 +278,10 @@ func buildPermissionError(p errs.Problem, resp map[string]any, cc ClassifyContex
 	}
 	consoleURL := ConsoleURL(cc.Brand, cc.AppID, missing)
 	p.Message = CanonicalPermissionMessage(p.Subtype, cc.AppID, missing, p.Message)
+	// Permission categories have authoritative recovery guidance (scopes to
+	// grant, console URL), so the curated PermissionHint deliberately overrides
+	// any server detail lifted into p.Hint (the opposite precedence from the
+	// CategoryAPI arm, where the lifted detail wins).
 	p.Hint = PermissionHint(missing, identity, p.Subtype, consoleURL)
 	permErr := &errs.PermissionError{
 		Problem:       p,
@@ -347,6 +390,32 @@ func PermissionHint(missing []string, identity string, subtype errs.Subtype, con
 	return "check the calling identity has the required scope"
 }
 
+// liftErrorDetailValues collects the non-empty resp.error.details[].value reason
+// strings and joins them with "; ". Returns "" when the structure is absent or
+// carries no non-empty value. The shape (verified for code 190014) is
+// {"error":{"details":[{"value":"<reason>"}]}}.
+func liftErrorDetailValues(resp map[string]any) string {
+	errBlock, ok := resp["error"].(map[string]any)
+	if !ok {
+		return ""
+	}
+	details, ok := errBlock["details"].([]any)
+	if !ok || len(details) == 0 {
+		return ""
+	}
+	var values []string
+	for _, d := range details {
+		m, ok := d.(map[string]any)
+		if !ok {
+			continue
+		}
+		if v, _ := m["value"].(string); v != "" {
+			values = append(values, v)
+		}
+	}
+	return strings.Join(values, "; ")
+}
+
 // extractMissingScopes walks resp["error"]["permission_violations"][].subject.
 // Returns nil when the structure is absent.
 func extractMissingScopes(resp map[string]any) []string {

internal/errclass/classify_test.go

@@ -220,6 +220,111 @@ func TestBuildAPIError_TroubleshooterLiftedOnPermissionArm(t *testing.T) {
 	}
 }
 
+// TestBuildAPIError_DetailsLiftedToHintOnAPIArm pins that BuildAPIError lifts
+// resp.error.details[].value into Problem.Hint when the response routes to the
+// catch-all CategoryAPI arm. The real Lark shape (verified for code 190014) is
+// {"error":{"details":[{"value":"end_time should be later than start_time"}]}}
+// — only a human-readable reason string, no machine-readable field name. It is
+// lifted into Hint (sanctioned free-text recovery prompt) rather than fabricated
+// structured params.
+func TestBuildAPIError_DetailsLiftedToHintOnAPIArm(t *testing.T) {
+	resp := map[string]any{
+		"code": 190014,
+		"msg":  "invalid params",
+		"error": map[string]any{
+			"details": []any{
+				map[string]any{"value": "end_time should be later than start_time"},
+			},
+		},
+	}
+	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{})
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatal("ProblemOf returned !ok")
+	}
+	if !strings.Contains(p.Hint, "end_time should be later than start_time") {
+		t.Errorf("Hint = %q, want it to contain the server detail value", p.Hint)
+	}
+}
+
+// TestBuildAPIError_MultipleDetailsJoinedIntoHint pins that multiple non-empty
+// detail values are joined with "; " into a single Hint, and empty values are
+// skipped.
+func TestBuildAPIError_MultipleDetailsJoinedIntoHint(t *testing.T) {
+	resp := map[string]any{
+		"code": 190014,
+		"msg":  "invalid params",
+		"error": map[string]any{
+			"details": []any{
+				map[string]any{"value": "first reason"},
+				map[string]any{"value": ""},
+				map[string]any{"value": "second reason"},
+			},
+		},
+	}
+	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{})
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatal("ProblemOf returned !ok")
+	}
+	if p.Hint != "first reason; second reason" {
+		t.Errorf("Hint = %q, want %q", p.Hint, "first reason; second reason")
+	}
+}
+
+// TestBuildAPIError_DetailsSkipsNonMapEntries pins that malformed entries in
+// the details array (not a JSON object) are skipped rather than panicking, and
+// well-formed siblings still surface in the Hint.
+func TestBuildAPIError_DetailsSkipsNonMapEntries(t *testing.T) {
+	resp := map[string]any{
+		"code": 190014,
+		"msg":  "invalid params",
+		"error": map[string]any{
+			"details": []any{
+				"i am a bare string, not an object",
+				map[string]any{"value": "the real reason"},
+				42,
+			},
+		},
+	}
+	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{})
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatal("ProblemOf returned !ok")
+	}
+	if p.Hint != "the real reason" {
+		t.Errorf("Hint = %q, want %q", p.Hint, "the real reason")
+	}
+}
+
+// TestBuildAPIError_DetailsMalformedShapesNoHint pins that a missing error
+// block, a non-array details field, and an empty details array all leave the
+// Hint untouched (no lifted detail) instead of erroring.
+func TestBuildAPIError_DetailsMalformedShapesNoHint(t *testing.T) {
+	cases := []struct {
+		name string
+		resp map[string]any
+	}{
+		{"no error block", map[string]any{"code": 190014, "msg": "invalid params"}},
+		{"details not array", map[string]any{"code": 190014, "msg": "invalid params", "error": map[string]any{"details": "nope"}}},
+		{"empty details", map[string]any{"code": 190014, "msg": "invalid params", "error": map[string]any{"details": []any{}}}},
+		{"detail values all empty", map[string]any{"code": 190014, "msg": "invalid params", "error": map[string]any{"details": []any{map[string]any{"value": ""}}}}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := errclass.BuildAPIError(tc.resp, errclass.ClassifyContext{})
+			p, ok := errs.ProblemOf(err)
+			if !ok {
+				t.Fatal("ProblemOf returned !ok")
+			}
+			// With no liftable detail, the Hint must not echo a server detail.
+			if strings.Contains(p.Hint, "nope") {
+				t.Errorf("Hint should not lift a non-array details field, got %q", p.Hint)
+			}
+		})
+	}
+}
+
 // TestBuildAPIError_TroubleshooterAbsent pins that Troubleshooter stays empty
 // when the upstream response omits it — wire envelope must omit the field.
 func TestBuildAPIError_TroubleshooterAbsent(t *testing.T) {

internal/errclass/codemeta_calendar.go

@@ -0,0 +1,16 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errclass
+
+import "github.com/larksuite/cli/errs"
+
+// calendarCodeMeta holds calendar-service Lark code → CodeMeta mappings.
+// Only codes whose meaning is verifiable from repo evidence are registered;
+// ambiguous codes fall back to CategoryAPI via BuildAPIError.
+// BuildAPIError consumes this map via mergeCodeMeta + LookupCodeMeta.
+var calendarCodeMeta = map[int]CodeMeta{
+	190014: {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters}, // invalid params (carries a field-level detail lifted into Hint)
+}
+
+func init() { mergeCodeMeta(calendarCodeMeta, "calendar") }

internal/errclass/codemeta_calendar_test.go

@@ -0,0 +1,39 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errclass
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+)
+
+// TestLookupCodeMeta_CalendarCodes pins each calendar-service code registered
+// via the codemeta_calendar.go init() merge to its expected
+// Category/Subtype/Retryable.
+func TestLookupCodeMeta_CalendarCodes(t *testing.T) {
+	cases := []struct {
+		code        int
+		wantCat     errs.Category
+		wantSubtype errs.Subtype
+		wantRetry   bool
+	}{
+		// 190014: calendar "invalid params" with a field-level detail
+		// (error.details[].value) lifted into Hint by BuildAPIError.
+		{190014, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
+	}
+	for _, tc := range cases {
+		t.Run(fmt.Sprintf("%d", tc.code), func(t *testing.T) {
+			meta, ok := LookupCodeMeta(tc.code)
+			if !ok {
+				t.Fatalf("code %d not registered in codeMeta", tc.code)
+			}
+			if meta.Category != tc.wantCat || meta.Subtype != tc.wantSubtype || meta.Retryable != tc.wantRetry {
+				t.Errorf("code %d: got %+v, want Category=%v Subtype=%v Retryable=%v",
+					tc.code, meta, tc.wantCat, tc.wantSubtype, tc.wantRetry)
+			}
+		})
+	}
+}

internal/errclass/codemeta_drive.go

@@ -0,0 +1,17 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errclass
+
+import "github.com/larksuite/cli/errs"
+
+// driveCodeMeta holds drive/docs-service Lark code → CodeMeta mappings.
+// Only codes whose meaning is verifiable from repo evidence are registered;
+// ambiguous codes fall back to CategoryAPI via BuildAPIError.
+// BuildAPIError consumes this map via mergeCodeMeta + LookupCodeMeta.
+var driveCodeMeta = map[int]CodeMeta{
+	1061044: {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},          // parent folder does not exist (upload)
+	1069302: {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters}, // comment endpoint "Invalid or missing parameters"
+}
+
+func init() { mergeCodeMeta(driveCodeMeta, "drive") }

internal/errclass/codemeta_drive_test.go

@@ -0,0 +1,43 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errclass
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+)
+
+// TestLookupCodeMeta_DriveCodes pins each drive-service code registered via the
+// codemeta_drive.go init() merge to its expected Category/Subtype/Retryable.
+// Each case traces to repo evidence (see codemeta_drive.go comments).
+func TestLookupCodeMeta_DriveCodes(t *testing.T) {
+	cases := []struct {
+		code        int
+		wantCat     errs.Category
+		wantSubtype errs.Subtype
+		wantRetry   bool
+	}{
+		// 1061044: upload with a nonexistent parent folder token. The drive E2E
+		// (tests_e2e/drive/2026_06_01_errs_migrate_drive_test.go) drives this
+		// producer via a nonexistent parent folder → referenced resource missing.
+		{1061044, errs.CategoryAPI, errs.SubtypeNotFound, false},
+		// 1069302: comment endpoint's opaque "Invalid or missing parameters"
+		// (shortcuts/drive/drive_add_comment.go) → API-side parameter rejection.
+		{1069302, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
+	}
+	for _, tc := range cases {
+		t.Run(fmt.Sprintf("%d", tc.code), func(t *testing.T) {
+			meta, ok := LookupCodeMeta(tc.code)
+			if !ok {
+				t.Fatalf("code %d not registered in codeMeta", tc.code)
+			}
+			if meta.Category != tc.wantCat || meta.Subtype != tc.wantSubtype || meta.Retryable != tc.wantRetry {
+				t.Errorf("code %d: got %+v, want Category=%v Subtype=%v Retryable=%v",
+					tc.code, meta, tc.wantCat, tc.wantSubtype, tc.wantRetry)
+			}
+		})
+	}
+}

internal/errclass/codemeta_mail.go

@@ -0,0 +1,20 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errclass
+
+import "github.com/larksuite/cli/errs"
+
+// mailCodeMeta holds mail-service Lark code -> CodeMeta mappings.
+// Only codes whose meaning is verifiable from repo evidence are registered;
+// ambiguous codes fall back to CategoryAPI via BuildAPIError.
+var mailCodeMeta = map[int]CodeMeta{
+	1234013: {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},      // mailbox not found or not active
+	1236007: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded}, // user daily send count exceeded
+	1236008: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded}, // user daily external recipient count exceeded
+	1236009: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded}, // tenant daily external recipient count exceeded
+	1236010: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded}, // mail quota limit
+	1236013: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded}, // tenant storage limit exceeded
+}
+
+func init() { mergeCodeMeta(mailCodeMeta, "mail") }

internal/errclass/codemeta_minutes.go

@@ -0,0 +1,18 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errclass
+
+import "github.com/larksuite/cli/errs"
+
+// minutesCodeMeta holds minutes-service Lark code → CodeMeta mappings.
+// Only codes whose meaning is stable across minutes endpoints are registered;
+// endpoint-specific codes fall back to CategoryAPI via BuildAPIError.
+// Command-specific messages, hints, and subtypes are layered on top via
+// per-command enrichment.
+// BuildAPIError consumes this map via mergeCodeMeta + LookupCodeMeta.
+var minutesCodeMeta = map[int]CodeMeta{
+	2091005: {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied}, // caller lacks edit/read permission for the minute
+}
+
+func init() { mergeCodeMeta(minutesCodeMeta, "minutes") }

internal/errclass/codemeta_test.go

@@ -70,6 +70,12 @@ func TestLookupCodeMeta_TaskPermissionDenied_MergedViaInit(t *testing.T) {
 	}
 }
 
+func TestLookupCodeMeta_MinutesEndpointSpecificCode_NotGlobal(t *testing.T) {
+	if got, ok := LookupCodeMeta(2091001); ok {
+		t.Fatalf("LookupCodeMeta(2091001) = %+v, want unregistered; minutes endpoints use this code for different failures", got)
+	}
+}
+
 func TestLookupCodeMeta_RetryableAuthCode(t *testing.T) {
 	got, ok := LookupCodeMeta(20050)
 	if !ok {

internal/errclass/codemeta_vc.go

@@ -0,0 +1,19 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errclass
+
+import "github.com/larksuite/cli/errs"
+
+// vcCodeMeta holds vc-service Lark code → CodeMeta mappings.
+// Only codes whose meaning is verifiable from repo evidence are registered;
+// ambiguous codes (e.g. 124002 "recording still generating", which has no
+// precise taxonomy fit) fall back to CategoryAPI via BuildAPIError and rely on
+// per-command enrichment for a retry hint.
+// BuildAPIError consumes this map via mergeCodeMeta + LookupCodeMeta.
+var vcCodeMeta = map[int]CodeMeta{
+	121004: {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},                   // meeting has no minute file
+	121005: {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied}, // caller is not a participant / lacks view permission
+}
+
+func init() { mergeCodeMeta(vcCodeMeta, "vc") }

internal/event/consume/consume.go

@@ -130,7 +130,7 @@ func Run(ctx context.Context, tr transport.IPC, appID, profileName, domain strin
 	if !opts.Quiet {
 		fmt.Fprintln(errOut, listeningText(opts))
 		if !opts.IsTTY {
-			fmt.Fprintln(errOut, stopHintText())
+			fmt.Fprintln(errOut, stopHintText(opts))
 		}
 	}
 
@@ -213,7 +213,11 @@ func exitReason(ctx context.Context, emitted int64, opts Options) string {
 	return "signal"
 }
 
-func stopHintText() string {
+func stopHintText(opts Options) string {
+	if opts.MaxEvents > 0 || opts.Timeout > 0 {
+		return "[event] to stop gracefully: send SIGTERM (kill <pid>). " +
+			"Avoid kill -9 — it skips cleanup and may leak server-side subscriptions."
+	}
 	return "[event] to stop gracefully: send SIGTERM (kill <pid>) or close stdin. " +
 		"Avoid kill -9 — it skips cleanup and may leak server-side subscriptions."
 }

internal/event/consume/listening_text_test.go

@@ -50,12 +50,32 @@ func TestListeningText_NonTTY_MaxEventsAndTimeout(t *testing.T) {
 }
 
 // AI-facing contract: must name "kill -9" + "cleanup" so agents parsing stderr are steered away from SIGKILL.
-func TestStopHintText_Content(t *testing.T) {
-	got := stopHintText()
-	mustContain := []string{"SIGTERM", "kill -9", "cleanup"}
+func TestStopHintText_Unbounded(t *testing.T) {
+	got := stopHintText(Options{})
+	mustContain := []string{"SIGTERM", "kill -9", "cleanup", "close stdin"}
 	for _, s := range mustContain {
 		if !bytes.Contains([]byte(got), []byte(s)) {
-			t.Errorf("stopHintText missing %q; got %q", s, got)
+			t.Errorf("stopHintText(unbounded) missing %q; got %q", s, got)
+		}
+	}
+}
+
+// AI-facing contract: must name "kill -9" + "cleanup" so agents parsing stderr are steered away from SIGKILL.
+func TestStopHintText_Bounded(t *testing.T) {
+	cases := []Options{
+		{MaxEvents: 1},
+		{Timeout: 30 * time.Second},
+	}
+	for _, opts := range cases {
+		got := stopHintText(opts)
+		mustContain := []string{"SIGTERM", "kill -9", "cleanup"}
+		for _, s := range mustContain {
+			if !bytes.Contains([]byte(got), []byte(s)) {
+				t.Errorf("stopHintText(bounded) missing %q; got %q", s, got)
+			}
+		}
+		if bytes.Contains([]byte(got), []byte("close stdin")) {
+			t.Errorf("stopHintText(bounded) must not contain \"close stdin\"; got %q", got)
 		}
 	}
 }

internal/output/errors.go

@@ -170,6 +170,28 @@ func ErrBare(code int) *ExitError {
 	return &ExitError{Code: code}
 }
 
+// PartialFailureError is the exit signal for a batch / multi-status command that
+// has already written an ok:false result envelope to stdout. The per-item
+// outcomes are the primary, machine-readable output and live on stdout, so the
+// dispatcher sets only the exit code and writes nothing to stderr.
+//
+// It is deliberately distinct from ErrBare (the predicate silent-exit signal)
+// so the predicate contract stays narrow, and from a typed *errs.XxxError
+// (which owns the stderr error envelope): a partial failure is a result, not an
+// error envelope.
+type PartialFailureError struct {
+	Code int
+}
+
+func (e *PartialFailureError) Error() string {
+	return fmt.Sprintf("partial failure (exit %d)", e.Code)
+}
+
+// PartialFailure builds the partial-failure exit signal with the given code.
+func PartialFailure(code int) *PartialFailureError {
+	return &PartialFailureError{Code: code}
+}
+
 // WriteTypedErrorEnvelope writes the JSON error envelope for a typed error.
 // Each typed error owns its wire shape via its own struct tags: Problem fields
 // are promoted to the top level through embedding, and extension fields

internal/output/exitcode.go

@@ -61,6 +61,10 @@ func ExitCodeOf(err error) int {
 	if _, ok := errs.ProblemOf(err); ok {
 		return ExitCodeForCategory(errs.CategoryOf(err))
 	}
+	var pfErr *PartialFailureError
+	if errors.As(err, &pfErr) {
+		return pfErr.Code
+	}
 	var exitErr *ExitError
 	if errors.As(err, &exitErr) {
 		return exitErr.Code

internal/registry/loader.go

@@ -19,72 +19,32 @@ import (
 //go:embed scope_priorities.json scope_overrides.json
 var registryFS embed.FS
 
-// embeddedMetaJSON is set by loader_embedded.go when meta_data.json is compiled in.
-var embeddedMetaJSON []byte
-
-// EmbeddedMetaJSON returns the raw embedded meta_data.json bytes for callers
-// that need to parse key order or other JSON-level structure not exposed by
-// LoadFromMeta (which loses map insertion order).
-func EmbeddedMetaJSON() []byte {
-	return embeddedMetaJSON
-}
-
-var (
-	embeddedServicesMap  map[string]map[string]interface{} // service name -> spec
-	embeddedServiceNames []string                          // sorted
-	embeddedParseOnce    sync.Once
-)
-
-// parseEmbeddedServices parses embeddedMetaJSON into a service name → spec map
-// without touching mergedServices. Safe to call multiple times (sync.Once).
-func parseEmbeddedServices() {
-	embeddedParseOnce.Do(func() {
-		embeddedServicesMap = make(map[string]map[string]interface{})
-		if len(embeddedMetaJSON) == 0 {
-			return
-		}
-		var wrapper struct {
-			Services []map[string]interface{} `json:"services"`
-		}
-		if err := json.Unmarshal(embeddedMetaJSON, &wrapper); err != nil {
-			return
-		}
-		for _, svc := range wrapper.Services {
-			name, _ := svc["name"].(string)
-			if name == "" {
-				continue
-			}
-			embeddedServicesMap[name] = svc
-		}
-		embeddedServiceNames = make([]string, 0, len(embeddedServicesMap))
-		for name := range embeddedServicesMap {
-			embeddedServiceNames = append(embeddedServiceNames, name)
-		}
-		sort.Strings(embeddedServiceNames)
-	})
-}
-
-// EmbeddedSpec returns the embedded spec for one service, or nil if unknown.
-// Bypasses remote overlay — used for deterministic envelope output.
+// EmbeddedSpec returns the embedded baseline spec for one service as a map, or
+// nil if the service is unknown. It reads the static compile-time registry
+// (metastatic.Registry) and bypasses the remote overlay, so envelope output is
+// deterministic across machines.
 func EmbeddedSpec(serviceName string) map[string]interface{} {
-	parseEmbeddedServices()
-	return embeddedServicesMap[serviceName]
+	if svc, ok := baselineServiceByName(serviceName); ok {
+		return ServiceToMap(svc)
+	}
+	return nil
 }
 
-// EmbeddedServiceNames returns sorted embedded service names (no overlay).
-// Returns a defensive copy — callers must not mutate the package-level slice.
+// EmbeddedServiceNames returns the embedded baseline service names, sorted
+// (no remote overlay).
 func EmbeddedServiceNames() []string {
-	parseEmbeddedServices()
-	out := make([]string, len(embeddedServiceNames))
-	copy(out, embeddedServiceNames)
+	svcs := baselineServices()
+	out := make([]string, 0, len(svcs))
+	for _, s := range svcs {
+		out = append(out, s.Name)
+	}
+	sort.Strings(out)
 	return out
 }
 
 var (
-	mergedServices    = make(map[string]map[string]interface{}) // project name → parsed spec
-	mergedProjectList []string                                  // sorted project names
-	embeddedVersion   string                                    // version from embedded meta_data.json
-	initOnce          sync.Once
+	embeddedVersion string // baseline data version (from the static registry)
+	initOnce        sync.Once
 )
 
 // Init initializes the registry with default brand (feishu).
@@ -101,55 +61,27 @@ func Init() {
 func InitWithBrand(brand core.LarkBrand) {
 	initOnce.Do(func() {
 		configuredBrand = brand
-		// 1. Load embedded meta_data.json as baseline (no-op if not compiled in)
-		loadEmbeddedIntoMerged()
-		// 2. Remote overlay
+		// 1. Baseline version: the static compile-time registry (metastatic).
+		embeddedVersion = baselineVersion()
+		// 2. Remote overlay — still fetched/refreshed at runtime, decoded into
+		//    the same typed shape and merged over the baseline.
 		if remoteEnabled() && cacheWritable() {
-			// Check if brand changed since last cache
 			meta, metaErr := loadCacheMeta()
 			brandChanged := metaErr == nil && meta.Brand != "" && meta.Brand != string(brand)
 
 			if !brandChanged {
-				if cached, err := loadCachedMerged(); err == nil {
-					overlayMergedServices(cached)
-				}
+				_ = loadCachedTyped()
 			}
-			if len(mergedServices) == 0 || brandChanged {
-				// No data at all or brand changed — must sync fetch
+			if !hasTypedData() || brandChanged {
+				// No data at all (e.g. stub build, no cache) or brand changed.
 				doSyncFetch()
 			} else if shouldRefresh(meta) || metaErr != nil {
-				// Have embedded/cached data; refresh in background if TTL expired or first run
 				triggerBackgroundRefresh()
 			}
 		}
-		// 3. Build sorted project list
-		rebuildProjectList()
 	})
 }
 
-// loadEmbeddedIntoMerged parses the embedded meta_data.json and populates
-// mergedServices. No-op if meta_data.json is not compiled in.
-func loadEmbeddedIntoMerged() {
-	if len(embeddedMetaJSON) == 0 {
-		return
-	}
-	var reg MergedRegistry
-	if err := json.Unmarshal(embeddedMetaJSON, &reg); err != nil {
-		return
-	}
-	embeddedVersion = reg.Version
-	overlayMergedServices(&reg)
-}
-
-// rebuildProjectList rebuilds the sorted list of project names from mergedServices.
-func rebuildProjectList() {
-	mergedProjectList = make([]string, 0, len(mergedServices))
-	for name := range mergedServices {
-		mergedProjectList = append(mergedProjectList, name)
-	}
-	sort.Strings(mergedProjectList)
-}
-
 var cachedAllScopes map[string][]string
 
 // CollectAllScopesFromMeta collects all unique scopes from from_meta/*.json
@@ -226,7 +158,11 @@ func CollectAllScopesFromMeta(identity string) []string {
 // It returns data from the merged registry (embedded + cached remote overlay).
 func LoadFromMeta(project string) map[string]interface{} {
 	Init()
-	return mergedServices[project]
+	svc, ok := typedServiceByName(project)
+	if !ok {
+		return nil
+	}
+	return ServiceToMap(svc)
 }
 
 // ListFromMetaProjects lists available service project names (sorted).
@@ -234,7 +170,7 @@ func LoadFromMeta(project string) map[string]interface{} {
 //go:noinline
 func ListFromMetaProjects() []string {
 	Init()
-	return mergedProjectList
+	return typedServiceNames()
 }
 
 // DefaultScopeScore is the score assigned to scopes not in the priorities table.

internal/registry/loader_embedded.go

@@ -1,20 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package registry
-
-import "embed"
-
-//go:embed meta_data*.json
-var metaFS embed.FS
-
-//go:embed meta_data_default.json
-var embeddedMetaDataDefaultJSON []byte
-
-func init() {
-	if data, err := metaFS.ReadFile("meta_data.json"); err == nil && len(data) > 0 {
-		embeddedMetaJSON = data
-	} else {
-		embeddedMetaJSON = embeddedMetaDataDefaultJSON
-	}
-}

internal/registry/meta_data_default.json

@@ -1 +0,0 @@
-{"version":"0.0.0","services":[]}

internal/registry/metaschema/types.go

@@ -0,0 +1,99 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package metaschema defines the typed shape of the command-spec registry
+// (meta_data.json). The embedded baseline is emitted as static Go data in
+// package metastatic (no runtime JSON parse, no startup allocation); the remote
+// overlay is decoded into these same types at runtime.
+//
+// All container fields are slices (never maps): a package-level slice literal is
+// laid out in the binary's data section and costs zero heap allocation at
+// startup, whereas a map literal builds an hmap at init time. Map keys from the
+// JSON (resource/method/field names) are preserved in the Name field.
+package metaschema
+
+// Registry is the top level of meta_data.json: {version, services:[...]}.
+type Registry struct {
+	Version  string
+	Services []Service
+}
+
+// Service is one API domain (e.g. "im", "calendar").
+type Service struct {
+	Name        string
+	Version     string
+	Title       string
+	Description string
+	ServicePath string
+	Resources   []Resource // JSON "resources" map, keyed by Resource.Name
+}
+
+// Resource groups methods under a service (e.g. "messages").
+type Resource struct {
+	Name    string
+	Methods []Method // JSON "methods" map, keyed by Method.Name
+}
+
+// Method is a single API call.
+type Method struct {
+	Name           string // JSON map key
+	ID             string
+	Path           string
+	HTTPMethod     string
+	Description    string
+	Risk           string
+	DocURL         string
+	Danger         bool
+	Scopes         []string
+	AccessTokens   []string
+	ParameterOrder []string
+	RequiredScopes []string
+	Parameters     []Field     // JSON "parameters" map, keyed by Field.Name
+	RequestBody    []Field     // JSON "requestBody" map
+	ResponseBody   []Field     // JSON "responseBody" map
+	Affordance     *Affordance // optional AI-facing usage overlay; nil on most methods
+}
+
+// Field is one parameter / request-body / response-body entry. Nested object
+// fields recurse via Properties.
+type Field struct {
+	Name        string // JSON map key
+	Type        string
+	Location    string
+	Description string
+	Default     string
+	Example     string
+	EnumName    string
+	Min         string
+	Max         string
+	Ref         string
+	Required    bool
+	Options     []Option
+	Enum        []string
+	Annotations []string
+	Properties  []Field
+}
+
+// Option is one allowed value for a field with an enum-like option list.
+type Option struct {
+	Value       string
+	Description string
+}
+
+// Affordance is the optional AI-facing usage overlay for a method, surfaced in
+// the schema envelope as _meta.affordance. Absent (nil) on most methods; it is
+// authored upstream in registry-config.yaml and merged into meta_data.json.
+type Affordance struct {
+	UseWhen       []string
+	DoNotUseWhen  []string
+	Prerequisites []string
+	Examples      []AffordanceExample
+	Related       []string
+}
+
+// AffordanceExample is one ready-to-run example: a one-line description plus a
+// complete lark-cli command string.
+type AffordanceExample struct {
+	Description string
+	Command     string
+}

internal/registry/metastatic/gen.go

@@ -0,0 +1,255 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build ignore
+
+// Command gen reads internal/registry/meta_data.json and emits
+// meta_data_gen.go: the embedded command spec as a single static
+// metaschema.Registry literal (zero runtime JSON parse, zero startup heap
+// allocation). Run via: go run internal/registry/metastatic/gen.go
+//
+// Maps in the JSON (resources/methods/fields) are emitted as slices sorted by
+// key so generation is deterministic.
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"go/format"
+	"os"
+	"sort"
+	"strings"
+)
+
+const (
+	inPath  = "internal/registry/meta_data.json"
+	outPath = "internal/registry/metastatic/meta_data_gen.go"
+)
+
+func gs(m map[string]any, k string) string {
+	if v, ok := m[k].(string); ok {
+		return v
+	}
+	return ""
+}
+func gb(m map[string]any, k string) bool {
+	if v, ok := m[k].(bool); ok {
+		return v
+	}
+	return false
+}
+func gss(m map[string]any, k string) []string {
+	raw, _ := m[k].([]any)
+	out := make([]string, 0, len(raw))
+	for _, e := range raw {
+		if s, ok := e.(string); ok {
+			out = append(out, s)
+		}
+	}
+	return out
+}
+func gm(m map[string]any, k string) map[string]any {
+	if v, ok := m[k].(map[string]any); ok {
+		return v
+	}
+	return nil
+}
+func sortedKeys(m map[string]any) []string {
+	ks := make([]string, 0, len(m))
+	for k := range m {
+		ks = append(ks, k)
+	}
+	sort.Strings(ks)
+	return ks
+}
+
+func emitStrSlice(b *strings.Builder, name string, vs []string) {
+	if len(vs) == 0 {
+		return
+	}
+	fmt.Fprintf(b, "%s: []string{", name)
+	for _, v := range vs {
+		fmt.Fprintf(b, "%q, ", v)
+	}
+	b.WriteString("},\n")
+}
+
+func emitOptions(b *strings.Builder, raw []any) {
+	if len(raw) == 0 {
+		return
+	}
+	b.WriteString("Options: []metaschema.Option{")
+	for _, e := range raw {
+		o, _ := e.(map[string]any)
+		fmt.Fprintf(b, "{Value: %q, Description: %q}, ", gs(o, "value"), gs(o, "description"))
+	}
+	b.WriteString("},\n")
+}
+
+// emitFields emits a metaschema.Field slice from a JSON map[fieldName]fieldSpec.
+func emitFields(b *strings.Builder, label string, fm map[string]any) {
+	if len(fm) == 0 {
+		return
+	}
+	fmt.Fprintf(b, "%s: []metaschema.Field{\n", label)
+	for _, name := range sortedKeys(fm) {
+		f, _ := fm[name].(map[string]any)
+		if f == nil {
+			continue
+		}
+		b.WriteString("{")
+		fmt.Fprintf(b, "Name: %q, ", name)
+		for _, kv := range []struct{ k, field string }{
+			{"type", "Type"}, {"location", "Location"}, {"description", "Description"},
+			{"default", "Default"}, {"example", "Example"}, {"enumName", "EnumName"},
+			{"min", "Min"}, {"max", "Max"}, {"ref", "Ref"},
+		} {
+			if v := gs(f, kv.k); v != "" {
+				fmt.Fprintf(b, "%s: %q, ", kv.field, v)
+			}
+		}
+		if gb(f, "required") {
+			b.WriteString("Required: true, ")
+		}
+		emitStrSlice(b, "Enum", gss(f, "enum"))
+		emitStrSlice(b, "Annotations", gss(f, "annotations"))
+		if opts, ok := f["options"].([]any); ok {
+			emitOptions(b, opts)
+		}
+		if props := gm(f, "properties"); props != nil {
+			emitFields(b, "Properties", props)
+		}
+		b.WriteString("},\n")
+	}
+	b.WriteString("},\n")
+}
+
+// emitAffordance emits a metaschema.Affordance literal from a method's
+// "affordance" JSON object, or nothing when absent/empty.
+func emitAffordance(b *strings.Builder, raw map[string]any) {
+	if raw == nil {
+		return
+	}
+	useWhen := gss(raw, "use_when")
+	doNot := gss(raw, "do_not_use_when")
+	prereq := gss(raw, "prerequisites")
+	related := gss(raw, "related")
+	examples, _ := raw["examples"].([]any)
+	if len(useWhen) == 0 && len(doNot) == 0 && len(prereq) == 0 && len(related) == 0 && len(examples) == 0 {
+		return
+	}
+	b.WriteString("Affordance: &metaschema.Affordance{")
+	emitStrSlice(b, "UseWhen", useWhen)
+	emitStrSlice(b, "DoNotUseWhen", doNot)
+	emitStrSlice(b, "Prerequisites", prereq)
+	if len(examples) > 0 {
+		b.WriteString("Examples: []metaschema.AffordanceExample{")
+		for _, e := range examples {
+			ex, _ := e.(map[string]any)
+			fmt.Fprintf(b, "{Description: %q, Command: %q}, ", gs(ex, "description"), gs(ex, "command"))
+		}
+		b.WriteString("},\n")
+	}
+	emitStrSlice(b, "Related", related)
+	b.WriteString("},\n")
+}
+
+func emitMethods(b *strings.Builder, mm map[string]any) {
+	b.WriteString("Methods: []metaschema.Method{\n")
+	for _, name := range sortedKeys(mm) {
+		m, _ := mm[name].(map[string]any)
+		if m == nil {
+			continue
+		}
+		b.WriteString("{")
+		fmt.Fprintf(b, "Name: %q, ID: %q, Path: %q, HTTPMethod: %q, Description: %q, ",
+			name, gs(m, "id"), gs(m, "path"), gs(m, "httpMethod"), gs(m, "description"))
+		if v := gs(m, "risk"); v != "" {
+			fmt.Fprintf(b, "Risk: %q, ", v)
+		}
+		if v := gs(m, "docUrl"); v != "" {
+			fmt.Fprintf(b, "DocURL: %q, ", v)
+		}
+		if gb(m, "danger") {
+			b.WriteString("Danger: true, ")
+		}
+		b.WriteString("\n")
+		emitStrSlice(b, "Scopes", gss(m, "scopes"))
+		emitStrSlice(b, "AccessTokens", gss(m, "accessTokens"))
+		emitStrSlice(b, "ParameterOrder", gss(m, "parameterOrder"))
+		emitStrSlice(b, "RequiredScopes", gss(m, "requiredScopes"))
+		emitFields(b, "Parameters", gm(m, "parameters"))
+		emitFields(b, "RequestBody", gm(m, "requestBody"))
+		emitFields(b, "ResponseBody", gm(m, "responseBody"))
+		emitAffordance(b, gm(m, "affordance"))
+		b.WriteString("},\n")
+	}
+	b.WriteString("},\n")
+}
+
+func main() {
+	data, err := os.ReadFile(inPath)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "read:", err)
+		os.Exit(1)
+	}
+	var reg map[string]any
+	if err := json.Unmarshal(data, &reg); err != nil {
+		fmt.Fprintln(os.Stderr, "unmarshal:", err)
+		os.Exit(1)
+	}
+
+	var b strings.Builder
+	b.WriteString("// Code generated from meta_data.json by gen.go. DO NOT EDIT.\n")
+	b.WriteString("// Gitignored; produced at build time by `make fetch_meta`.\n\n")
+	b.WriteString("package metastatic\n\n")
+	b.WriteString("import \"github.com/larksuite/cli/internal/registry/metaschema\"\n\n")
+	b.WriteString("// registryData holds the command spec as static Go data. It is a\n")
+	b.WriteString("// package-level var, so its backing arrays live in the binary's static\n")
+	b.WriteString("// section (zero heap alloc on read). init() wires it into the Registry\n")
+	b.WriteString("// declared by stub.go with a single struct-header copy. No build tag is\n")
+	b.WriteString("// needed: when this generated file is absent (fresh checkout) stub.go's\n")
+	b.WriteString("// empty Registry stands alone; when present, init() augments it.\n")
+	b.WriteString("var registryData = metaschema.Registry{\n")
+	fmt.Fprintf(&b, "Version: %q,\n", gs(reg, "version"))
+	b.WriteString("Services: []metaschema.Service{\n")
+	svcs, _ := reg["services"].([]any)
+	for _, sv := range svcs {
+		s, _ := sv.(map[string]any)
+		if s == nil {
+			continue
+		}
+		b.WriteString("{")
+		fmt.Fprintf(&b, "Name: %q, Version: %q, Title: %q, Description: %q, ServicePath: %q,\n",
+			gs(s, "name"), gs(s, "version"), gs(s, "title"), gs(s, "description"), gs(s, "servicePath"))
+		b.WriteString("Resources: []metaschema.Resource{\n")
+		res := gm(s, "resources")
+		for _, rname := range sortedKeys(res) {
+			r, _ := res[rname].(map[string]any)
+			if r == nil {
+				continue
+			}
+			fmt.Fprintf(&b, "{Name: %q,\n", rname)
+			emitMethods(&b, gm(r, "methods"))
+			b.WriteString("},\n")
+		}
+		b.WriteString("},\n") // Resources
+		b.WriteString("},\n") // Service
+	}
+	b.WriteString("},\n")  // Services
+	b.WriteString("}\n\n") // registryData literal
+	b.WriteString("func init() { Registry = registryData }\n")
+
+	src, err := format.Source([]byte(b.String()))
+	if err != nil {
+		// Write unformatted for debugging, then fail.
+		_ = os.WriteFile(outPath+".broken", []byte(b.String()), 0644)
+		fmt.Fprintln(os.Stderr, "gofmt:", err)
+		os.Exit(1)
+	}
+	if err := os.WriteFile(outPath, src, 0644); err != nil {
+		fmt.Fprintln(os.Stderr, "write:", err)
+		os.Exit(1)
+	}
+	fmt.Printf("wrote %s (%d services, %d bytes)\n", outPath, len(svcs), len(src))
+}

internal/registry/metastatic/stub.go

@@ -0,0 +1,15 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package metastatic
+
+import "github.com/larksuite/cli/internal/registry/metaschema"
+
+// Registry is the command spec as static Go data. It is declared here (zero
+// value) so the package always compiles, and populated by meta_data_gen.go's
+// init() when that generated file is present. On a fresh checkout the generated
+// file is absent — it is gitignored and produced at build time by
+// `make gen_meta` — so Registry stays empty. This keeps the "heavy spec is
+// never committed, only generated" model, now without a build tag: the
+// generated file augments this one rather than replacing it under a tag.
+var Registry = metaschema.Registry{}

internal/registry/metastatic_validate_test.go

@@ -0,0 +1,90 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Validation for the static-meta registry: the generated metastatic.Registry is
+// the sole embedded baseline (no JSON parsed at runtime), and a deep read of it
+// allocates nothing. The data is generated from meta_data.json at build time
+// (`make fetch_meta`) and is gitignored, so these tests skip on a bare checkout
+// where it has not been generated yet.
+package registry
+
+import (
+	"testing"
+
+	"github.com/larksuite/cli/internal/registry/metaschema"
+	"github.com/larksuite/cli/internal/registry/metastatic"
+)
+
+func countFieldsStatic(fs []metaschema.Field) int {
+	n := 0
+	for _, f := range fs {
+		n++
+		n += countFieldsStatic(f.Properties)
+	}
+	return n
+}
+
+func countStatic() (svc, res, meth, fld int) {
+	svc = len(metastatic.Registry.Services)
+	for _, s := range metastatic.Registry.Services {
+		for _, r := range s.Resources {
+			res++
+			for _, m := range r.Methods {
+				meth++
+				fld += countFieldsStatic(m.Parameters) + countFieldsStatic(m.RequestBody) + countFieldsStatic(m.ResponseBody)
+			}
+		}
+	}
+	return
+}
+
+// TestStaticRegistryPopulated checks the generated registry carries data. It
+// skips on a bare checkout where meta_data_gen.go has not been generated yet.
+func TestStaticRegistryPopulated(t *testing.T) {
+	if len(metastatic.Registry.Services) == 0 {
+		t.Skip("static registry empty; run `make fetch_meta` to generate it")
+	}
+	svc, res, meth, fld := countStatic()
+	t.Logf("static: services=%d resources=%d methods=%d fields=%d", svc, res, meth, fld)
+	if svc == 0 || res == 0 || meth == 0 || fld == 0 {
+		t.Fatalf("static registry incomplete: svc=%d res=%d meth=%d fld=%d", svc, res, meth, fld)
+	}
+	if metastatic.Registry.Version == "" {
+		t.Error("static registry has empty Version")
+	}
+}
+
+var sinkInt int
+
+// --- zero-alloc: a deep read of the static registry must allocate nothing ---
+
+func deepReadStatic() int {
+	n := 0
+	for _, s := range metastatic.Registry.Services {
+		n += len(s.Name)
+		for _, r := range s.Resources {
+			for _, m := range r.Methods {
+				n += len(m.ID) + len(m.Scopes) + countFieldsStatic(m.Parameters) + countFieldsStatic(m.ResponseBody)
+			}
+		}
+	}
+	return n
+}
+
+func TestStaticReadZeroAlloc(t *testing.T) {
+	if len(metastatic.Registry.Services) == 0 {
+		t.Skip("static registry empty; run `make fetch_meta` to generate it")
+	}
+	avg := testing.AllocsPerRun(50, func() { sinkInt = deepReadStatic() })
+	t.Logf("static deep-read: %.1f allocs/op", avg)
+	if avg > 0 {
+		t.Errorf("static read allocates %.1f/op, want 0 (data should be in the binary, not heap)", avg)
+	}
+}
+
+func BenchmarkReadStaticRegistry(b *testing.B) {
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		sinkInt = deepReadStatic()
+	}
+}

internal/registry/registry_test.go

@@ -231,14 +231,9 @@ func TestLoadAutoApproveSet(t *testing.T) {
 		t.Fatal("expected non-empty auto-approve set")
 	}
 
-	// From scope_overrides.json allow list
-	if !aaSet["calendar:calendar.event:create"] {
-		t.Error("expected calendar:calendar.event:create in auto-approve set (from allow list)")
-	}
-
-	// Verify allow list entries are present
+	// From scope_priorities.json recommend=="true"
 	if !aaSet["sheets:spreadsheet:read"] {
-		t.Error("expected sheets:spreadsheet:read in auto-approve set (from allow list)")
+		t.Error("expected sheets:spreadsheet:read in auto-approve set (recommend=true in priorities)")
 	}
 
 	t.Logf("Auto-approve set has %d scopes", len(aaSet))
@@ -257,16 +252,10 @@ func TestLoadPlatformAutoApproveSet(t *testing.T) {
 
 func TestLoadOverrideAutoApproveAllow(t *testing.T) {
 	allowSet := LoadOverrideAutoApproveAllow()
-	if len(allowSet) == 0 {
-		t.Fatal("expected non-empty override allow set")
-	}
-
-	// Known entries from scope_overrides.json
-	if !allowSet["calendar:calendar.event:create"] {
-		t.Error("expected calendar:calendar.event:create in allow set")
-	}
-	if !allowSet["mail:event"] {
-		t.Error("expected mail:event in allow set")
+	// recommend.allow in scope_overrides.json is intentionally empty:
+	// no scopes are special-cased into the auto-approve set anymore.
+	if len(allowSet) != 0 {
+		t.Errorf("expected empty override allow set, got %d entries", len(allowSet))
 	}
 }
 
@@ -277,9 +266,9 @@ func TestLoadOverrideAutoApproveDeny(t *testing.T) {
 }
 
 func TestIsAutoApproveScope(t *testing.T) {
-	// Known auto-approve scope (in allow list)
-	if !IsAutoApproveScope("calendar:calendar.event:create") {
-		t.Error("expected calendar:calendar.event:create to be auto-approve")
+	// Known auto-approve scope (recommend=true in scope_priorities.json)
+	if !IsAutoApproveScope("sheets:spreadsheet:read") {
+		t.Error("expected sheets:spreadsheet:read to be auto-approve")
 	}
 
 	// Completely unknown scope
@@ -290,9 +279,8 @@ func TestIsAutoApproveScope(t *testing.T) {
 
 func TestFilterAutoApproveScopes(t *testing.T) {
 	scopes := []string{
-		"calendar:calendar.event:create", // auto-approve (in allow list)
-		"zzz:unknown:scope",              // not in auto-approve
-		"sheets:spreadsheet:read",        // auto-approve (in allow list)
+		"sheets:spreadsheet:read", // auto-approve (recommend=true in priorities)
+		"zzz:unknown:scope",       // not in auto-approve
 	}
 
 	result := FilterAutoApproveScopes(scopes)
@@ -300,10 +288,10 @@ func TestFilterAutoApproveScopes(t *testing.T) {
 		t.Fatal("expected at least 1 auto-approve scope in result")
 	}
 
-	// Check that calendar:calendar.event:create is included
+	// Check that sheets:spreadsheet:read is included
 	found := false
 	for _, s := range result {
-		if s == "calendar:calendar.event:create" {
+		if s == "sheets:spreadsheet:read" {
 			found = true
 		}
 		// Ensure unknown scopes are not included
@@ -312,7 +300,7 @@ func TestFilterAutoApproveScopes(t *testing.T) {
 		}
 	}
 	if !found {
-		t.Error("expected calendar:calendar.event:create in result")
+		t.Error("expected sheets:spreadsheet:read in result")
 	}
 }
 

internal/registry/remote.go

@@ -17,7 +17,7 @@ import (
 
 	"github.com/larksuite/cli/internal/build"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/util"
+	"github.com/larksuite/cli/internal/transport"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/internal/vfs"
 )
@@ -147,22 +147,6 @@ func saveCacheMeta(meta CacheMeta) error {
 	return validate.AtomicWrite(cacheMetaPath(), data, 0644)
 }
 
-func loadCachedMerged() (*MergedRegistry, error) {
-	path := cachePath()
-	data, err := vfs.ReadFile(path)
-	if err != nil {
-		return nil, err
-	}
-	var reg MergedRegistry
-	if err := json.Unmarshal(data, &reg); err != nil {
-		// Cache corrupted — remove it so next run triggers a fresh fetch
-		vfs.Remove(path)
-		vfs.Remove(cacheMetaPath())
-		return nil, err
-	}
-	return &reg, nil
-}
-
 func saveCachedMerged(data []byte, meta CacheMeta) error {
 	if err := vfs.MkdirAll(cacheDir(), 0700); err != nil {
 		return err
@@ -181,7 +165,7 @@ func saveCachedMerged(data []byte, meta CacheMeta) error {
 func fetchRemoteMerged(localVersion string) (data []byte, reg *MergedRegistry, err error) {
 	// Route through the shared proxy-plugin-aware transport so remote API
 	// definition fetches honor proxy plugin mode instead of bypassing it.
-	client := util.NewHTTPClient(fetchTimeout)
+	client := transport.NewHTTPClient(fetchTimeout)
 	req, err := http.NewRequest("GET", remoteMetaURL(localVersion), nil)
 	if err != nil {
 		return nil, nil, err
@@ -253,7 +237,7 @@ func doSyncFetch() {
 		Brand:       string(configuredBrand),
 	}
 	_ = saveCachedMerged(data, meta)
-	overlayMergedServices(reg)
+	_ = loadCachedTyped()
 }
 
 // --- background refresh ---
@@ -308,15 +292,3 @@ func shouldRefresh(meta CacheMeta) bool {
 	}
 	return time.Since(time.Unix(meta.LastCheckAt, 0)) > metaTTL()
 }
-
-// overlayMergedServices merges remote services into the in-memory map.
-// Remote entries override embedded entries with the same name.
-func overlayMergedServices(reg *MergedRegistry) {
-	for _, svc := range reg.Services {
-		name, ok := svc["name"].(string)
-		if !ok || name == "" {
-			continue
-		}
-		mergedServices[name] = svc
-	}
-}

internal/registry/remote_test.go

@@ -15,6 +15,8 @@ import (
 	"time"
 
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/registry/metaschema"
+	"github.com/larksuite/cli/internal/registry/metastatic"
 )
 
 // waitBackgroundRefresh blocks until any in-flight background refresh started by
@@ -30,8 +32,7 @@ func resetInit() {
 	// reads globals this function mutates (see CI race: TestComputeMinimumScopeSet → Tenant).
 	waitBackgroundRefresh()
 	initOnce = sync.Once{}
-	mergedServices = make(map[string]map[string]interface{})
-	mergedProjectList = nil
+	resetTyped()
 	embeddedVersion = ""
 	cachedAllScopes = nil
 	cachedScopePriorities = nil
@@ -55,16 +56,10 @@ func TestResetInitClearsEmbeddedVersion(t *testing.T) {
 	}
 }
 
-// hasEmbeddedServices returns true if meta_data.json with real services is compiled in.
+// hasEmbeddedServices returns true if the static registry has services compiled
+// in (generated from meta_data.json at build time).
 func hasEmbeddedServices() bool {
-	if len(embeddedMetaJSON) == 0 {
-		return false
-	}
-	var reg MergedRegistry
-	if err := json.Unmarshal(embeddedMetaJSON, &reg); err != nil {
-		return false
-	}
-	return len(reg.Services) > 0
+	return len(metastatic.Registry.Services) > 0
 }
 
 // testRegistry returns a minimal MergedRegistry with one service.
@@ -302,50 +297,36 @@ func TestMetaTTL(t *testing.T) {
 	}
 }
 
-func TestOverlayMergedServices(t *testing.T) {
+func TestRemoteOverlayTyped(t *testing.T) {
 	resetInit()
-	mergedServices = make(map[string]map[string]interface{})
-	mergedServices["existing"] = map[string]interface{}{"name": "existing", "version": "v1"}
+	setRemoteOverrides([]metaschema.Service{
+		{Name: "existing", Version: "v2"},
+		{Name: "brand_new", Version: "v1"},
+	})
 
-	reg := &MergedRegistry{
-		Services: []map[string]interface{}{
-			{"name": "existing", "version": "v2"},
-			{"name": "brand_new", "version": "v1"},
-		},
+	// override present
+	if s, ok := typedServiceByName("existing"); !ok || s.Version != "v2" {
+		t.Errorf("expected existing override v2, got %+v ok=%v", s, ok)
 	}
-	overlayMergedServices(reg)
-
-	// existing should be overridden
-	if v := mergedServices["existing"]["version"].(string); v != "v2" {
-		t.Errorf("expected existing to be overridden to v2, got %s", v)
-	}
-	// brand_new should be added
-	if _, ok := mergedServices["brand_new"]; !ok {
+	// new service added
+	if _, ok := typedServiceByName("brand_new"); !ok {
 		t.Error("expected brand_new to be added")
 	}
 }
 
-func TestOverlayMergedServicesDoesNotPolluteFollowingInit(t *testing.T) {
+func TestRemoteOverlayDoesNotPolluteFollowingInit(t *testing.T) {
 	resetInit()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	t.Setenv("LARKSUITE_CLI_REMOTE_META", "off")
 
-	const leakedExisting = "test_isolation_existing_sentinel"
-	const leakedOverlay = "test_isolation_overlay_sentinel"
-
-	mergedServices = map[string]map[string]interface{}{
-		leakedExisting: {"name": leakedExisting, "version": "v1"},
-	}
-	overlayMergedServices(&MergedRegistry{Services: []map[string]interface{}{{"name": leakedOverlay, "version": "v1"}}})
+	const leaked = "test_isolation_overlay_sentinel"
+	setRemoteOverrides([]metaschema.Service{{Name: leaked, Version: "v1"}})
 
 	resetInit()
 	Init()
 
-	if spec := LoadFromMeta(leakedExisting); spec != nil {
-		t.Fatalf("polluted service %q survived resetInit", leakedExisting)
-	}
-	if spec := LoadFromMeta(leakedOverlay); spec != nil {
-		t.Fatalf("polluted service %q survived resetInit", leakedOverlay)
+	if spec := LoadFromMeta(leaked); spec != nil {
+		t.Fatalf("polluted service %q survived resetInit", leaked)
 	}
 }
 
@@ -425,8 +406,8 @@ func TestCorruptedCache_SelfHeals(t *testing.T) {
 	metaData, _ := json.Marshal(meta)
 	os.WriteFile(filepath.Join(cDir, "remote_meta.meta.json"), metaData, 0644)
 
-	// loadCachedMerged should fail and remove the corrupted files
-	_, err := loadCachedMerged()
+	// loadCachedTyped should fail and remove the corrupted files
+	err := loadCachedTyped()
 	if err == nil {
 		t.Fatal("expected error for corrupted cache")
 	}

internal/registry/scope_overrides.json

@@ -12,25 +12,7 @@
     "vc:meeting.meetingevent:read": 75
   },
   "recommend": {
-    "allow": [
-      "calendar:calendar.event:create",
-      "calendar:calendar.event:delete",
-      "calendar:calendar.event:read",
-      "calendar:calendar.event:update",
-      "calendar:calendar.free_busy:read",
-      "calendar:calendar:create",
-      "calendar:calendar:delete",
-      "calendar:calendar:read",
-      "calendar:calendar:update",
-      "contact:user.basic_profile:readonly",
-      "mail:event",
-      "mail:user_mailbox.mail_contact:read",
-      "mail:user_mailbox.mail_contact:write",
-      "mail:user_mailbox.message.address:read",
-      "mail:user_mailbox.message.body:read",
-      "mail:user_mailbox.message.subject:read",
-      "mail:user_mailbox.message:readonly"
-    ],
+    "allow": [],
     "deny": [
       "im:chat",
       "im:message.send_as_user"

internal/registry/typed.go

@@ -0,0 +1,579 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package registry
+
+import (
+	"encoding/json"
+	"sort"
+	"sync"
+
+	"github.com/larksuite/cli/internal/registry/metaschema"
+	"github.com/larksuite/cli/internal/registry/metastatic"
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+// This file is the typed registry layer for the static-meta migration.
+//
+//   - The embedded baseline is metastatic.Registry: static Go data laid out in
+//     the binary at compile time (zero startup cost). It is empty on a fresh
+//     checkout (stub.go) until the generated meta_data_gen.go is produced by
+//     `make fetch_meta`; no build tag is involved.
+//   - The remote overlay (~/.lark-cli/cache/remote_meta.json) is still fetched
+//     and refreshed at runtime, decoded into the same typed shape, and merged
+//     over the baseline as per-service overrides.
+//
+// Startup (command-tree build) reads these typed structs directly. Execution-
+// path consumers that still expect map[string]interface{} go through
+// ServiceToMap, which rebuilds one service's map lazily, on demand — never the
+// whole spec at startup.
+
+var (
+	typedMu         sync.RWMutex
+	remoteOverrides map[string]metaschema.Service // service name -> remote override
+	typedNamesCache []string
+)
+
+// resetTyped clears the typed overlay state (test/teardown helper).
+func resetTyped() {
+	typedMu.Lock()
+	defer typedMu.Unlock()
+	remoteOverrides = nil
+	typedNamesCache = nil
+}
+
+// baselineServices returns the embedded baseline service specs: the static
+// compile-time data in metastatic.Registry (zero parse, zero alloc). It is
+// empty only on a fresh checkout where meta_data_gen.go has not been generated
+// yet (see stub.go).
+var (
+	baselineOnce sync.Once
+	baselineSvcs []metaschema.Service
+	baselineVer  string
+)
+
+func loadBaseline() {
+	baselineOnce.Do(func() {
+		baselineSvcs = metastatic.Registry.Services
+		baselineVer = metastatic.Registry.Version
+	})
+}
+
+func baselineServices() []metaschema.Service {
+	loadBaseline()
+	return baselineSvcs
+}
+
+func baselineVersion() string {
+	loadBaseline()
+	return baselineVer
+}
+
+// baselineServiceByName returns the embedded baseline service spec by name.
+func baselineServiceByName(name string) (metaschema.Service, bool) {
+	svcs := baselineServices()
+	for i := range svcs {
+		if svcs[i].Name == name {
+			return svcs[i], true
+		}
+	}
+	return metaschema.Service{}, false
+}
+
+// typedServiceByName returns the effective typed spec for a service: the remote
+// override if present, otherwise the static baseline.
+func typedServiceByName(name string) (metaschema.Service, bool) {
+	typedMu.RLock()
+	if s, ok := remoteOverrides[name]; ok {
+		typedMu.RUnlock()
+		return s, true
+	}
+	typedMu.RUnlock()
+	return baselineServiceByName(name)
+}
+
+// typedServiceNames returns all effective service names (baseline + remote
+// additions), sorted. Cached until the overlay changes.
+func typedServiceNames() []string {
+	typedMu.RLock()
+	if typedNamesCache != nil {
+		out := typedNamesCache
+		typedMu.RUnlock()
+		return out
+	}
+	typedMu.RUnlock()
+
+	seen := make(map[string]bool)
+	for _, s := range baselineServices() {
+		seen[s.Name] = true
+	}
+	typedMu.RLock()
+	for name := range remoteOverrides {
+		seen[name] = true
+	}
+	typedMu.RUnlock()
+
+	names := make([]string, 0, len(seen))
+	for n := range seen {
+		names = append(names, n)
+	}
+	sort.Strings(names)
+
+	typedMu.Lock()
+	typedNamesCache = names
+	typedMu.Unlock()
+	return names
+}
+
+// setRemoteOverrides installs the parsed remote overlay (called from Init).
+func setRemoteOverrides(svcs []metaschema.Service) {
+	typedMu.Lock()
+	defer typedMu.Unlock()
+	if remoteOverrides == nil {
+		remoteOverrides = make(map[string]metaschema.Service, len(svcs))
+	}
+	for _, s := range svcs {
+		remoteOverrides[s.Name] = s
+	}
+	typedNamesCache = nil
+}
+
+// TypedService returns the effective typed spec for a service (remote override
+// or static baseline). Public accessor for the command-tree builder.
+func TypedService(name string) (metaschema.Service, bool) {
+	Init()
+	return typedServiceByName(name)
+}
+
+// TypedServices returns all effective service specs, sorted by name. Reading
+// these builds nothing on the heap (static data); the remote overlay, if any,
+// was allocated once at Init.
+func TypedServices() []metaschema.Service {
+	Init()
+	names := typedServiceNames()
+	out := make([]metaschema.Service, 0, len(names))
+	for _, n := range names {
+		if s, ok := typedServiceByName(n); ok {
+			out = append(out, s)
+		}
+	}
+	return out
+}
+
+// hasTypedData reports whether any typed spec is available (static baseline or
+// remote overlay). False only when the static registry has not been generated
+// (fresh checkout) and there is no cache.
+func hasTypedData() bool {
+	if len(baselineServices()) > 0 {
+		return true
+	}
+	typedMu.RLock()
+	defer typedMu.RUnlock()
+	return len(remoteOverrides) > 0
+}
+
+// loadCachedTyped reads the on-disk remote cache, decodes it into the typed
+// shape, and installs it as the remote overlay (typed replacement for the old
+// map-based loadCachedMerged + overlay).
+func loadCachedTyped() error {
+	data, err := vfs.ReadFile(cachePath())
+	if err != nil {
+		return err
+	}
+	var reg wireRegistry
+	if err := json.Unmarshal(data, &reg); err != nil {
+		// Cache corrupted — remove it so the next run triggers a fresh fetch.
+		_ = vfs.Remove(cachePath())
+		_ = vfs.Remove(cacheMetaPath())
+		return err
+	}
+	svcs := make([]metaschema.Service, 0, len(reg.Services))
+	for _, ws := range reg.Services {
+		svcs = append(svcs, wireToService(ws))
+	}
+	setRemoteOverrides(svcs)
+	return nil
+}
+
+// --- typed -> map[string]interface{} shim (lazy, per service, execution-path) ---
+
+func strList(ss []string) []interface{} {
+	if len(ss) == 0 {
+		return nil
+	}
+	out := make([]interface{}, len(ss))
+	for i, s := range ss {
+		out[i] = s
+	}
+	return out
+}
+
+func fieldToMap(f metaschema.Field) map[string]interface{} {
+	m := map[string]interface{}{}
+	put := func(k, v string) {
+		if v != "" {
+			m[k] = v
+		}
+	}
+	put("type", f.Type)
+	put("location", f.Location)
+	put("description", f.Description)
+	put("default", f.Default)
+	put("example", f.Example)
+	put("enumName", f.EnumName)
+	put("min", f.Min)
+	put("max", f.Max)
+	put("ref", f.Ref)
+	if f.Required {
+		m["required"] = true
+	}
+	if v := strList(f.Enum); v != nil {
+		m["enum"] = v
+	}
+	if v := strList(f.Annotations); v != nil {
+		m["annotations"] = v
+	}
+	if len(f.Options) > 0 {
+		opts := make([]interface{}, len(f.Options))
+		for i, o := range f.Options {
+			opts[i] = map[string]interface{}{"value": o.Value, "description": o.Description}
+		}
+		m["options"] = opts
+	}
+	if len(f.Properties) > 0 {
+		m["properties"] = fieldsToMap(f.Properties)
+	}
+	return m
+}
+
+func fieldsToMap(fs []metaschema.Field) map[string]interface{} {
+	if len(fs) == 0 {
+		return nil
+	}
+	m := make(map[string]interface{}, len(fs))
+	for _, f := range fs {
+		m[f.Name] = fieldToMap(f)
+	}
+	return m
+}
+
+// affordanceToMap rebuilds the JSON-shaped affordance object (snake_case keys)
+// so the schema assembler's parseAffordance(method["affordance"]) keeps working
+// through the typed registry. Returns nil when the overlay carries nothing.
+func affordanceToMap(a *metaschema.Affordance) map[string]interface{} {
+	m := map[string]interface{}{}
+	if v := strList(a.UseWhen); v != nil {
+		m["use_when"] = v
+	}
+	if v := strList(a.DoNotUseWhen); v != nil {
+		m["do_not_use_when"] = v
+	}
+	if v := strList(a.Prerequisites); v != nil {
+		m["prerequisites"] = v
+	}
+	if len(a.Examples) > 0 {
+		ex := make([]interface{}, len(a.Examples))
+		for i, e := range a.Examples {
+			ex[i] = map[string]interface{}{"description": e.Description, "command": e.Command}
+		}
+		m["examples"] = ex
+	}
+	if v := strList(a.Related); v != nil {
+		m["related"] = v
+	}
+	if len(m) == 0 {
+		return nil
+	}
+	return m
+}
+
+func MethodToMap(mth metaschema.Method) map[string]interface{} {
+	m := map[string]interface{}{
+		"id":          mth.ID,
+		"path":        mth.Path,
+		"httpMethod":  mth.HTTPMethod,
+		"description": mth.Description,
+	}
+	if mth.Risk != "" {
+		m["risk"] = mth.Risk
+	}
+	if mth.DocURL != "" {
+		m["docUrl"] = mth.DocURL
+	}
+	if mth.Danger {
+		m["danger"] = true
+	}
+	if v := strList(mth.Scopes); v != nil {
+		m["scopes"] = v
+	}
+	if v := strList(mth.AccessTokens); v != nil {
+		m["accessTokens"] = v
+	}
+	if v := strList(mth.ParameterOrder); v != nil {
+		m["parameterOrder"] = v
+	}
+	if v := strList(mth.RequiredScopes); v != nil {
+		m["requiredScopes"] = v
+	}
+	if v := fieldsToMap(mth.Parameters); v != nil {
+		m["parameters"] = v
+	}
+	if v := fieldsToMap(mth.RequestBody); v != nil {
+		m["requestBody"] = v
+	}
+	if v := fieldsToMap(mth.ResponseBody); v != nil {
+		m["responseBody"] = v
+	}
+	if mth.Affordance != nil {
+		if am := affordanceToMap(mth.Affordance); am != nil {
+			m["affordance"] = am
+		}
+	}
+	return m
+}
+
+// ServiceToMap rebuilds the JSON-shaped map[string]interface{} for one service,
+// so execution-path consumers (and method RunE) keep working unchanged.
+func ServiceToMap(s metaschema.Service) map[string]interface{} {
+	resources := make(map[string]interface{}, len(s.Resources))
+	for _, r := range s.Resources {
+		methods := make(map[string]interface{}, len(r.Methods))
+		for _, mth := range r.Methods {
+			methods[mth.Name] = MethodToMap(mth)
+		}
+		resources[r.Name] = map[string]interface{}{"methods": methods}
+	}
+	return map[string]interface{}{
+		"name":        s.Name,
+		"version":     s.Version,
+		"title":       s.Title,
+		"description": s.Description,
+		"servicePath": s.ServicePath,
+		"resources":   resources,
+	}
+}
+
+// --- map[string]interface{} -> typed (for the map-based wrappers still used by
+// tests; production builds from typed directly) ---
+
+func ifaceStrs(v interface{}) []string {
+	raw, _ := v.([]interface{})
+	if len(raw) == 0 {
+		return nil
+	}
+	out := make([]string, 0, len(raw))
+	for _, e := range raw {
+		if s, ok := e.(string); ok {
+			out = append(out, s)
+		}
+	}
+	return out
+}
+
+func sortedMapKeys(m map[string]interface{}) []string {
+	ks := make([]string, 0, len(m))
+	for k := range m {
+		ks = append(ks, k)
+	}
+	sort.Strings(ks)
+	return ks
+}
+
+func mapToField(name string, m map[string]interface{}) metaschema.Field {
+	f := metaschema.Field{
+		Name: name, Type: GetStrFromMap(m, "type"), Location: GetStrFromMap(m, "location"),
+		Description: GetStrFromMap(m, "description"), Default: GetStrFromMap(m, "default"),
+		Example: GetStrFromMap(m, "example"), EnumName: GetStrFromMap(m, "enumName"),
+		Min: GetStrFromMap(m, "min"), Max: GetStrFromMap(m, "max"), Ref: GetStrFromMap(m, "ref"),
+		Enum: ifaceStrs(m["enum"]), Annotations: ifaceStrs(m["annotations"]),
+	}
+	if b, ok := m["required"].(bool); ok {
+		f.Required = b
+	}
+	if opts, ok := m["options"].([]interface{}); ok {
+		for _, o := range opts {
+			om, _ := o.(map[string]interface{})
+			f.Options = append(f.Options, metaschema.Option{Value: GetStrFromMap(om, "value"), Description: GetStrFromMap(om, "description")})
+		}
+	}
+	f.Properties = mapToFields(m["properties"])
+	return f
+}
+
+func mapToFields(v interface{}) []metaschema.Field {
+	fm, _ := v.(map[string]interface{})
+	if len(fm) == 0 {
+		return nil
+	}
+	out := make([]metaschema.Field, 0, len(fm))
+	for _, k := range sortedMapKeys(fm) {
+		em, _ := fm[k].(map[string]interface{})
+		out = append(out, mapToField(k, em))
+	}
+	return out
+}
+
+func MapToMethod(name string, m map[string]interface{}) metaschema.Method {
+	return metaschema.Method{
+		Name: name, ID: GetStrFromMap(m, "id"), Path: GetStrFromMap(m, "path"),
+		HTTPMethod: GetStrFromMap(m, "httpMethod"), Description: GetStrFromMap(m, "description"),
+		Risk: GetStrFromMap(m, "risk"), DocURL: GetStrFromMap(m, "docUrl"),
+		Danger:         boolFromMap(m, "danger"),
+		Scopes:         ifaceStrs(m["scopes"]),
+		AccessTokens:   ifaceStrs(m["accessTokens"]),
+		ParameterOrder: ifaceStrs(m["parameterOrder"]),
+		RequiredScopes: ifaceStrs(m["requiredScopes"]),
+		Parameters:     mapToFields(m["parameters"]),
+		RequestBody:    mapToFields(m["requestBody"]),
+		ResponseBody:   mapToFields(m["responseBody"]),
+	}
+}
+
+func boolFromMap(m map[string]interface{}, k string) bool {
+	b, _ := m[k].(bool)
+	return b
+}
+
+func MapToResources(v interface{}) []metaschema.Resource {
+	rm, _ := v.(map[string]interface{})
+	if len(rm) == 0 {
+		return nil
+	}
+	out := make([]metaschema.Resource, 0, len(rm))
+	for _, rk := range sortedMapKeys(rm) {
+		res, _ := rm[rk].(map[string]interface{})
+		mm, _ := res["methods"].(map[string]interface{})
+		methods := make([]metaschema.Method, 0, len(mm))
+		for _, mk := range sortedMapKeys(mm) {
+			methodMap, _ := mm[mk].(map[string]interface{})
+			methods = append(methods, MapToMethod(mk, methodMap))
+		}
+		out = append(out, metaschema.Resource{Name: rk, Methods: methods})
+	}
+	return out
+}
+
+// MapToService converts a JSON-shaped service spec (with embedded "resources")
+// into the typed form.
+func MapToService(spec map[string]interface{}) metaschema.Service {
+	return metaschema.Service{
+		Name: GetStrFromMap(spec, "name"), Version: GetStrFromMap(spec, "version"),
+		Title: GetStrFromMap(spec, "title"), Description: GetStrFromMap(spec, "description"),
+		ServicePath: GetStrFromMap(spec, "servicePath"), Resources: MapToResources(spec["resources"]),
+	}
+}
+
+// --- remote JSON (wire) -> typed ---
+
+type wireRegistry struct {
+	Version  string        `json:"version"`
+	Services []wireService `json:"services"`
+}
+
+type wireService struct {
+	Name        string                  `json:"name"`
+	Version     string                  `json:"version"`
+	Title       string                  `json:"title"`
+	Description string                  `json:"description"`
+	ServicePath string                  `json:"servicePath"`
+	Resources   map[string]wireResource `json:"resources"`
+}
+
+type wireResource struct {
+	Methods map[string]wireMethod `json:"methods"`
+}
+
+type wireMethod struct {
+	ID             string               `json:"id"`
+	Path           string               `json:"path"`
+	HTTPMethod     string               `json:"httpMethod"`
+	Description    string               `json:"description"`
+	Risk           string               `json:"risk"`
+	DocURL         string               `json:"docUrl"`
+	Danger         bool                 `json:"danger"`
+	Scopes         []string             `json:"scopes"`
+	AccessTokens   []string             `json:"accessTokens"`
+	ParameterOrder []string             `json:"parameterOrder"`
+	RequiredScopes []string             `json:"requiredScopes"`
+	Parameters     map[string]wireField `json:"parameters"`
+	RequestBody    map[string]wireField `json:"requestBody"`
+	ResponseBody   map[string]wireField `json:"responseBody"`
+}
+
+type wireField struct {
+	Type        string               `json:"type"`
+	Location    string               `json:"location"`
+	Description string               `json:"description"`
+	Default     string               `json:"default"`
+	Example     string               `json:"example"`
+	EnumName    string               `json:"enumName"`
+	Min         string               `json:"min"`
+	Max         string               `json:"max"`
+	Ref         string               `json:"ref"`
+	Required    bool                 `json:"required"`
+	Options     []metaschema.Option  `json:"options"`
+	Enum        []string             `json:"enum"`
+	Annotations []string             `json:"annotations"`
+	Properties  map[string]wireField `json:"properties"`
+}
+
+func sortedFieldKeys(m map[string]wireField) []string {
+	ks := make([]string, 0, len(m))
+	for k := range m {
+		ks = append(ks, k)
+	}
+	sort.Strings(ks)
+	return ks
+}
+
+func wireFields(m map[string]wireField) []metaschema.Field {
+	if len(m) == 0 {
+		return nil
+	}
+	out := make([]metaschema.Field, 0, len(m))
+	for _, name := range sortedFieldKeys(m) {
+		wf := m[name]
+		out = append(out, metaschema.Field{
+			Name: name, Type: wf.Type, Location: wf.Location, Description: wf.Description,
+			Default: wf.Default, Example: wf.Example, EnumName: wf.EnumName,
+			Min: wf.Min, Max: wf.Max, Ref: wf.Ref, Required: wf.Required,
+			Options: wf.Options, Enum: wf.Enum, Annotations: wf.Annotations,
+			Properties: wireFields(wf.Properties),
+		})
+	}
+	return out
+}
+
+func wireToService(ws wireService) metaschema.Service {
+	resKeys := make([]string, 0, len(ws.Resources))
+	for k := range ws.Resources {
+		resKeys = append(resKeys, k)
+	}
+	sort.Strings(resKeys)
+	resources := make([]metaschema.Resource, 0, len(resKeys))
+	for _, rk := range resKeys {
+		wr := ws.Resources[rk]
+		methKeys := make([]string, 0, len(wr.Methods))
+		for k := range wr.Methods {
+			methKeys = append(methKeys, k)
+		}
+		sort.Strings(methKeys)
+		methods := make([]metaschema.Method, 0, len(methKeys))
+		for _, mk := range methKeys {
+			wm := wr.Methods[mk]
+			methods = append(methods, metaschema.Method{
+				Name: mk, ID: wm.ID, Path: wm.Path, HTTPMethod: wm.HTTPMethod,
+				Description: wm.Description, Risk: wm.Risk, DocURL: wm.DocURL, Danger: wm.Danger,
+				Scopes: wm.Scopes, AccessTokens: wm.AccessTokens,
+				ParameterOrder: wm.ParameterOrder, RequiredScopes: wm.RequiredScopes,
+				Parameters: wireFields(wm.Parameters), RequestBody: wireFields(wm.RequestBody),
+				ResponseBody: wireFields(wm.ResponseBody),
+			})
+		}
+		resources = append(resources, metaschema.Resource{Name: rk, Methods: methods})
+	}
+	return metaschema.Service{
+		Name: ws.Name, Version: ws.Version, Title: ws.Title,
+		Description: ws.Description, ServicePath: ws.ServicePath, Resources: resources,
+	}
+}

internal/schema/assembler.go

@@ -4,290 +4,14 @@
 package schema
 
 import (
-	"bytes"
 	"encoding/json"
 	"sort"
 	"strconv"
-	"sync"
 
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/registry"
 )
 
-// MethodKeyOrder records the natural meta_data.json key order for one method's
-// parameters / requestBody / responseBody. Nested object key orders are stored
-// under NestedKeys, keyed by dotted path from the method root
-// (e.g. "responseBody.items.properties").
-type MethodKeyOrder struct {
-	Parameters   []string
-	RequestBody  []string
-	ResponseBody []string
-	NestedKeys   map[string][]string
-}
-
-var (
-	keyOrderIndex    map[string]*MethodKeyOrder // dottedPath -> order
-	keyOrderInitOnce sync.Once
-)
-
-// lookupKeyOrder returns the key-order record for service.resourcePath.method,
-// or nil if the method is not in the embedded data (e.g. remote-cached).
-func lookupKeyOrder(service string, resourcePath []string, method string) *MethodKeyOrder {
-	keyOrderInitOnce.Do(buildKeyOrderIndex)
-	if keyOrderIndex == nil {
-		return nil
-	}
-	dotted := dottedPath(service, resourcePath, method)
-	return keyOrderIndex[dotted]
-}
-
-func dottedPath(service string, resourcePath []string, method string) string {
-	var buf bytes.Buffer
-	buf.WriteString(service)
-	for _, r := range resourcePath {
-		buf.WriteByte('.')
-		buf.WriteString(r)
-	}
-	buf.WriteByte('.')
-	buf.WriteString(method)
-	return buf.String()
-}
-
-// buildKeyOrderIndex parses the embedded meta_data.json bytes once at init,
-// walking services -> resources -> methods -> {parameters,requestBody,responseBody}
-// and recording each map's key insertion order via json.Decoder.Token().
-func buildKeyOrderIndex() {
-	raw := registry.EmbeddedMetaJSON()
-	if len(raw) == 0 {
-		return
-	}
-	keyOrderIndex = make(map[string]*MethodKeyOrder)
-
-	dec := json.NewDecoder(bytes.NewReader(raw))
-	// Top-level: { "services": [...], "version": "..." }
-	if !expectDelim(dec, '{') {
-		return
-	}
-	for dec.More() {
-		key, _ := readKey(dec)
-		if key != "services" {
-			skipValue(dec)
-			continue
-		}
-		if !expectDelim(dec, '[') {
-			return
-		}
-		for dec.More() {
-			parseService(dec)
-		}
-		// closing ]
-		_, _ = dec.Token()
-	}
-}
-
-// parseService consumes one service object inside services[].
-// meta_data.json may emit "resources" before "name", so we first capture both
-// raw fields, then walk resources with the resolved service name.
-func parseService(dec *json.Decoder) {
-	if !expectDelim(dec, '{') {
-		return
-	}
-	var serviceName string
-	var resourcesRaw json.RawMessage
-	for dec.More() {
-		key, _ := readKey(dec)
-		switch key {
-		case "name":
-			tok, _ := dec.Token()
-			if s, ok := tok.(string); ok {
-				serviceName = s
-			}
-		case "resources":
-			if err := dec.Decode(&resourcesRaw); err != nil {
-				skipValue(dec)
-			}
-		default:
-			skipValue(dec)
-		}
-	}
-	_, _ = dec.Token() // closing }
-	if serviceName != "" && len(resourcesRaw) > 0 {
-		subDec := json.NewDecoder(bytes.NewReader(resourcesRaw))
-		parseResources(subDec, serviceName, nil)
-	}
-}
-
-// parseResources walks a resources map (resName -> resource object).
-// resourcePath is the accumulated path of parent resources (for nested resources).
-func parseResources(dec *json.Decoder, service string, resourcePath []string) {
-	if !expectDelim(dec, '{') {
-		return
-	}
-	for dec.More() {
-		resName, _ := readKey(dec)
-		parseResourceObj(dec, service, append(resourcePath, resName))
-	}
-	_, _ = dec.Token()
-}
-
-// parseResourceObj consumes one resource value: { methods: {...}, ... } and may
-// recurse into nested resources via "resources" key if present.
-func parseResourceObj(dec *json.Decoder, service string, resourcePath []string) {
-	if !expectDelim(dec, '{') {
-		return
-	}
-	for dec.More() {
-		key, _ := readKey(dec)
-		switch key {
-		case "methods":
-			parseMethods(dec, service, resourcePath)
-		case "resources":
-			parseResources(dec, service, resourcePath)
-		default:
-			skipValue(dec)
-		}
-	}
-	_, _ = dec.Token()
-}
-
-// parseMethods consumes the methods map (methodName -> method object).
-func parseMethods(dec *json.Decoder, service string, resourcePath []string) {
-	if !expectDelim(dec, '{') {
-		return
-	}
-	for dec.More() {
-		methodName, _ := readKey(dec)
-		mko := parseMethod(dec)
-		dotted := dottedPath(service, resourcePath, methodName)
-		keyOrderIndex[dotted] = mko
-	}
-	_, _ = dec.Token()
-}
-
-// parseMethod consumes one method object and records key orders.
-func parseMethod(dec *json.Decoder) *MethodKeyOrder {
-	mko := &MethodKeyOrder{NestedKeys: make(map[string][]string)}
-	if !expectDelim(dec, '{') {
-		return mko
-	}
-	for dec.More() {
-		key, _ := readKey(dec)
-		switch key {
-		case "parameters":
-			mko.Parameters = recordObjectKeysRecursive(dec, "parameters", mko.NestedKeys)
-		case "requestBody":
-			mko.RequestBody = recordObjectKeysRecursive(dec, "requestBody", mko.NestedKeys)
-		case "responseBody":
-			mko.ResponseBody = recordObjectKeysRecursive(dec, "responseBody", mko.NestedKeys)
-		default:
-			skipValue(dec)
-		}
-	}
-	_, _ = dec.Token()
-	return mko
-}
-
-// recordObjectKeysRecursive consumes an object and records the top-level key
-// order. It also recurses into each child's "properties" submap, recording
-// nested orders under prefix.subpath in nestedKeys. Returns the top-level keys
-// in order.
-func recordObjectKeysRecursive(dec *json.Decoder, prefix string, nestedKeys map[string][]string) []string {
-	if !expectDelim(dec, '{') {
-		return nil
-	}
-	var order []string
-	for dec.More() {
-		key, _ := readKey(dec)
-		order = append(order, key)
-		// Each child value is itself an object; we want its nested "properties" order if present.
-		consumeFieldRecursive(dec, prefix+"."+key, nestedKeys)
-	}
-	_, _ = dec.Token()
-	if prefix != "" && len(order) > 0 {
-		nestedKeys[prefix] = order
-	}
-	return order
-}
-
-// consumeFieldRecursive consumes a field object (e.g. one parameter spec) and,
-// if it contains "properties": {...}, recursively records that submap's order.
-func consumeFieldRecursive(dec *json.Decoder, path string, nestedKeys map[string][]string) {
-	tok, err := dec.Token()
-	if err != nil {
-		return
-	}
-	delim, ok := tok.(json.Delim)
-	if !ok || delim != '{' {
-		// Not an object — skip the rest of the value
-		skipValueAfterToken(dec, tok)
-		return
-	}
-	for dec.More() {
-		fieldKey, _ := readKey(dec)
-		if fieldKey == "properties" {
-			recordObjectKeysRecursive(dec, path+".properties", nestedKeys)
-		} else {
-			skipValue(dec)
-		}
-	}
-	_, _ = dec.Token()
-}
-
-// --- json.Decoder helpers ---
-
-func expectDelim(dec *json.Decoder, want json.Delim) bool {
-	tok, err := dec.Token()
-	if err != nil {
-		return false
-	}
-	delim, ok := tok.(json.Delim)
-	return ok && delim == want
-}
-
-func readKey(dec *json.Decoder) (string, error) {
-	tok, err := dec.Token()
-	if err != nil {
-		return "", err
-	}
-	s, _ := tok.(string)
-	return s, nil
-}
-
-// skipValue consumes the next complete value (scalar, object, or array).
-func skipValue(dec *json.Decoder) {
-	tok, err := dec.Token()
-	if err != nil {
-		return
-	}
-	skipValueAfterToken(dec, tok)
-}
-
-func skipValueAfterToken(dec *json.Decoder, tok json.Token) {
-	delim, ok := tok.(json.Delim)
-	if !ok {
-		return
-	}
-	// We started inside a container of type `delim` ({ or [) and must eat
-	// tokens until that container closes, tracking nested containers of any
-	// kind. depth counts how many open containers we are currently inside.
-	_ = delim
-	depth := 1
-	for depth > 0 {
-		t, err := dec.Token()
-		if err != nil {
-			return
-		}
-		if d, ok := t.(json.Delim); ok {
-			switch d {
-			case '{', '[':
-				depth++
-			case '}', ']':
-				depth--
-			}
-		}
-	}
-}
-
 // coerceLiteral converts a meta_data literal (default / enum / example) to
 // the JSON Schema type declared by the field (integer/number/boolean/string).
 // meta_data stores every literal as a string, so without coercion an
@@ -501,10 +225,6 @@ func buildOrderedProps(raw map[string]interface{}, nestedPath string) (*OrderedP
 	return op, required
 }
 
-// currentMethodOrder is the per-method key-order context used by orderedKeys.
-// It is set inside AssembleEnvelope (under assembleMu) and reset on return.
-var currentMethodOrder *MethodKeyOrder
-
 // parseAffordance lifts the affordance overlay from a method's raw meta_data.json
 // entry into a typed *Affordance. Returns nil when the field is absent, malformed,
 // or carries no populated subfields.
@@ -611,8 +331,6 @@ func buildMeta(method map[string]interface{}) *Meta {
 // The params / data wrapping mirrors the CLI's actual flag layout:
 // path+query → --params JSON, body → --data JSON, file → --file. AI consumers
 // can pluck inputSchema.properties.params and pass it verbatim to --params.
-//
-// Caller must set currentMethodOrder for property-order preservation.
 func buildInputSchema(method map[string]interface{}) *InputSchema {
 	is := &InputSchema{
 		Type:       "object",
@@ -738,27 +456,11 @@ func buildOutputSchema(method map[string]interface{}) *OutputSchema {
 	return os
 }
 
-// assembleMu serializes AssembleEnvelope calls so that the package-level
-// currentMethodOrder pointer is safe for concurrent callers.
-var assembleMu sync.Mutex
-
 // AssembleEnvelope is the main entry point: takes a service / resource path /
 // method name plus its meta_data spec, and produces a fully assembled MCP
 // envelope. Output is fully determined by inputs (same arguments → same
-// envelope), but assembly briefly publishes the per-method key-order context
-// through the package-level currentMethodOrder so orderedKeys can reach it
-// without threading it through every helper. assembleMu serializes that
-// publish, which is why concurrent callers are still safe — they queue
-// rather than run in parallel.
-//
-// If parallelism becomes a bottleneck, replace currentMethodOrder with an
-// assembler struct or pass *MethodKeyOrder explicitly down the call chain.
+// envelope).
 func AssembleEnvelope(serviceName string, resourcePath []string, methodName string, method map[string]interface{}) Envelope {
-	assembleMu.Lock()
-	defer assembleMu.Unlock()
-	currentMethodOrder = lookupKeyOrder(serviceName, resourcePath, methodName)
-	defer func() { currentMethodOrder = nil }()
-
 	name := serviceName
 	for _, r := range resourcePath {
 		name += " " + r
@@ -836,35 +538,10 @@ func walkMethods(resources map[string]interface{}, parentPath []string,
 	}
 }
 
-// orderedKeys returns the keys of raw in their meta_data natural order if
-// the current per-method key-order context has them recorded; otherwise
-// alphabetical fallback.
-func orderedKeys(raw map[string]interface{}, nestedPath string) []string {
-	if currentMethodOrder != nil && nestedPath != "" {
-		if order, ok := currentMethodOrder.NestedKeys[nestedPath]; ok {
-			// Filter to keys that actually exist in raw (defensive)
-			out := make([]string, 0, len(order))
-			seen := make(map[string]bool)
-			for _, k := range order {
-				if _, ok := raw[k]; ok {
-					out = append(out, k)
-					seen[k] = true
-				}
-			}
-			// Append any keys present in raw but missing from order (defensive),
-			// alphabetically for determinism.
-			var extra []string
-			for k := range raw {
-				if !seen[k] {
-					extra = append(extra, k)
-				}
-			}
-			sort.Strings(extra)
-			out = append(out, extra...)
-			return out
-		}
-	}
-	// Fallback: alphabetical
+// orderedKeys returns the keys of raw in alphabetical order. Field display
+// order is not preserved: the schema envelope is consumed as a JSON Schema (MCP
+// tool spec), where object property order carries no meaning.
+func orderedKeys(raw map[string]interface{}, _ string) []string {
 	keys := make([]string, 0, len(raw))
 	for k := range raw {
 		keys = append(keys, k)

internal/schema/assembler_test.go

@@ -7,10 +7,12 @@ import (
 	"encoding/json"
 	"os"
 	"reflect"
+	"sort"
 	"strings"
 	"testing"
 
 	"github.com/larksuite/cli/internal/registry"
+	"github.com/larksuite/cli/internal/registry/metaschema"
 )
 
 // TestMain isolates registry-backed tests from any host ~/.lark-cli cache so
@@ -35,58 +37,6 @@ func TestMain(m *testing.M) {
 	os.Exit(code)
 }
 
-func TestKeyOrderIndex_ImReactionsList(t *testing.T) {
-	// We only assert key-set membership, not absolute order — the upstream
-	// meta_data API does not guarantee a stable JSON key sequence across
-	// fetches, so hard-coding the order makes CI flaky. Order preservation
-	// from input to output is tested separately in TestBuildInputSchema_*.
-	order := lookupKeyOrder("im", []string{"reactions"}, "list")
-	if order == nil {
-		t.Fatal("expected key order for im.reactions.list, got nil")
-	}
-	wantParams := map[string]bool{
-		"message_id": true, "reaction_type": true, "page_token": true,
-		"page_size": true, "user_id_type": true,
-	}
-	if got, want := len(order.Parameters), len(wantParams); got != want {
-		t.Errorf("parameters count = %d, want %d (got %v)", got, want, order.Parameters)
-	}
-	for _, k := range order.Parameters {
-		if !wantParams[k] {
-			t.Errorf("unexpected parameter key %q", k)
-		}
-	}
-	// im.reactions.list 是 GET，没有 requestBody
-	if len(order.RequestBody) != 0 {
-		t.Errorf("expected empty RequestBody, got %v", order.RequestBody)
-	}
-}
-
-func TestKeyOrderIndex_ImImagesCreate(t *testing.T) {
-	// Membership-only assertion; see comment on TestKeyOrderIndex_ImReactionsList.
-	order := lookupKeyOrder("im", []string{"images"}, "create")
-	if order == nil {
-		t.Fatal("expected key order for im.images.create, got nil")
-	}
-	wantBody := map[string]bool{"image_type": true, "image": true}
-	if got, want := len(order.RequestBody), len(wantBody); got != want {
-		t.Errorf("requestBody count = %d, want %d (got %v)", got, want, order.RequestBody)
-	}
-	for _, k := range order.RequestBody {
-		if !wantBody[k] {
-			t.Errorf("unexpected requestBody key %q", k)
-		}
-	}
-}
-
-func TestKeyOrderIndex_UnknownPath(t *testing.T) {
-	// 远端缓存的命令（不在 embedded 内）查不到 key order，返回 nil 走字母序兜底
-	order := lookupKeyOrder("nonexistent_service", []string{"foo"}, "bar")
-	if order != nil {
-		t.Errorf("expected nil for unknown path, got %+v", order)
-	}
-}
-
 func TestConvertProperty_BasicTypes(t *testing.T) {
 	tests := []struct {
 		name     string
@@ -288,9 +238,6 @@ func TestConvertProperty_DescriptionDefaultExample(t *testing.T) {
 
 func TestBuildInputSchema_ReactionsList(t *testing.T) {
 	method := loadMethodFromRegistry(t, "im", []string{"reactions"}, "list")
-	mko := lookupKeyOrder("im", []string{"reactions"}, "list")
-	currentMethodOrder = mko
-	defer func() { currentMethodOrder = nil }()
 
 	is := buildInputSchema(method)
 
@@ -313,16 +260,15 @@ func TestBuildInputSchema_ReactionsList(t *testing.T) {
 	if !reflect.DeepEqual(params.Required, []string{"message_id"}) {
 		t.Errorf("params.Required = %v, want [message_id]", params.Required)
 	}
-	if !reflect.DeepEqual(params.Properties.Order, mko.Parameters) {
-		t.Errorf("params.properties order = %v, want (from key index) %v",
-			params.Properties.Order, mko.Parameters)
+	// Property order is alphabetical now: the envelope is a JSON Schema (MCP
+	// tool spec) where object property order carries no meaning.
+	if !sort.StringsAreSorted(params.Properties.Order) {
+		t.Errorf("params.properties order not alphabetical: %v", params.Properties.Order)
 	}
 }
 
 func TestBuildInputSchema_ImagesCreate_FileAndBody(t *testing.T) {
 	method := loadMethodFromRegistry(t, "im", []string{"images"}, "create")
-	currentMethodOrder = lookupKeyOrder("im", []string{"images"}, "create")
-	defer func() { currentMethodOrder = nil }()
 
 	is := buildInputSchema(method)
 
@@ -382,9 +328,6 @@ func TestBuildInputSchema_HighRiskWriteInjectsYes(t *testing.T) {
 			},
 		},
 	}
-	currentMethodOrder = nil
-	defer func() { currentMethodOrder = nil }()
-
 	is := buildInputSchema(method)
 
 	// yes lives at inputSchema.properties.yes (sibling of params/data)
@@ -413,9 +356,6 @@ func TestBuildInputSchema_HighRiskWriteInjectsYes(t *testing.T) {
 
 func TestBuildInputSchema_NoYesForReadRisk(t *testing.T) {
 	method := loadMethodFromRegistry(t, "im", []string{"reactions"}, "list")
-	mko := lookupKeyOrder("im", []string{"reactions"}, "list")
-	currentMethodOrder = mko
-	defer func() { currentMethodOrder = nil }()
 
 	is := buildInputSchema(method)
 	if _, ok := is.Properties.Map["yes"]; ok {
@@ -425,9 +365,6 @@ func TestBuildInputSchema_NoYesForReadRisk(t *testing.T) {
 
 func TestBuildOutputSchema_ReactionsList(t *testing.T) {
 	method := loadMethodFromRegistry(t, "im", []string{"reactions"}, "list")
-	mko := lookupKeyOrder("im", []string{"reactions"}, "list")
-	currentMethodOrder = mko
-	defer func() { currentMethodOrder = nil }()
 
 	os := buildOutputSchema(method)
 
@@ -613,6 +550,45 @@ func TestBuildMeta_AffordanceFromMethod(t *testing.T) {
 	}
 }
 
+// TestBuildMeta_AffordanceThroughTypedRegistry guards the static-registry path:
+// a method's affordance must survive metaschema.Method -> registry.MethodToMap
+// -> buildMeta, so `schema --format json` keeps emitting _meta.affordance after
+// the embedded-JSON-to-typed-registry migration. Without typed-side support the
+// overlay is silently stripped whenever meta_data.json carries affordance.
+func TestBuildMeta_AffordanceThroughTypedRegistry(t *testing.T) {
+	mth := metaschema.Method{
+		Name: "primary",
+		Affordance: &metaschema.Affordance{
+			UseWhen:       []string{"用户想拿到自己默认日历的 ID"},
+			DoNotUseWhen:  []string{"已经知道某个具体日历的 ID"},
+			Prerequisites: []string{"user 身份登录"},
+			Examples: []metaschema.AffordanceExample{
+				{Description: "取主日历", Command: "lark-cli calendar calendars primary"},
+			},
+			Related: []string{"calendars.list", "calendars.get"},
+		},
+	}
+	method := registry.MethodToMap(mth)
+	m := buildMeta(method)
+	if m.Affordance == nil {
+		t.Fatal("affordance dropped through the typed registry (MethodToMap -> buildMeta)")
+	}
+	a := m.Affordance
+	if len(a.UseWhen) != 1 || a.UseWhen[0] != "用户想拿到自己默认日历的 ID" {
+		t.Errorf("UseWhen = %v", a.UseWhen)
+	}
+	if len(a.DoNotUseWhen) != 1 || len(a.Prerequisites) != 1 {
+		t.Errorf("DoNotUseWhen=%v Prerequisites=%v", a.DoNotUseWhen, a.Prerequisites)
+	}
+	if len(a.Examples) != 1 || a.Examples[0].Description != "取主日历" ||
+		a.Examples[0].Command != "lark-cli calendar calendars primary" {
+		t.Errorf("Examples = %+v", a.Examples)
+	}
+	if len(a.Related) != 2 {
+		t.Errorf("Related = %v", a.Related)
+	}
+}
+
 func TestBuildMeta_MissingDocURLOmitted(t *testing.T) {
 	method := map[string]interface{}{
 		"scopes":       []interface{}{"x"},
@@ -634,7 +610,6 @@ func TestBuildMeta_MissingDocURLOmitted(t *testing.T) {
 func TestBuildOutputSchema_EmptyResponseBody(t *testing.T) {
 	// 装配器对空 responseBody 应生成 properties = {} （不 nil）
 	method := map[string]interface{}{}
-	currentMethodOrder = nil
 	os := buildOutputSchema(method)
 	if os.Type != "object" {
 		t.Errorf("Type = %q, want \"object\"", os.Type)

internal/schema/types.go

@@ -83,9 +83,13 @@ type AffordanceCase struct {
 	Command     string `json:"command"`
 }
 
-// OrderedProps is map[string]Property with preserved key order on MarshalJSON.
-// It is used wherever JSON output must reflect meta_data.json's natural field
-// order rather than Go's default alphabetical map encoding.
+// OrderedProps is map[string]Property that emits its keys in Order on
+// MarshalJSON. Order is now populated alphabetically (see orderedKeys): the
+// schema envelope is an MCP tool spec / JSON Schema, where object property
+// order carries no meaning. The machinery that once preserved meta_data.json's
+// natural field order was removed with the static-registry migration; Order is
+// retained so MarshalJSON has one stable key sequence (and callers that leave
+// it empty fall back to alphabetical over Map).
 type OrderedProps struct {
 	Order []string
 	Map   map[string]Property

internal/selfupdate/updater.go

@@ -10,10 +10,13 @@ import (
 	"bytes"
 	"context"
 	"fmt"
+	"io"
+	"net/http"
 	"os/exec"
 	"strings"
 	"time"
 
+	"github.com/larksuite/cli/internal/transport"
 	"github.com/larksuite/cli/internal/vfs"
 )
 
@@ -37,9 +40,15 @@ const (
 )
 
 const (
-	npmInstallTimeout   = 10 * time.Minute
-	skillsUpdateTimeout = 2 * time.Minute
-	verifyTimeout       = 10 * time.Second
+	npmInstallTimeout      = 10 * time.Minute
+	skillsUpdateTimeout    = 2 * time.Minute
+	skillsIndexMaxBodySize = 1 << 20
+	verifyTimeout          = 10 * time.Second
+)
+
+var (
+	skillsIndexFetchTimeout = 10 * time.Second
+	officialSkillsIndexURL  = "https://open.feishu.cn/.well-known/skills/index.json"
 )
 
 // DetectResult holds installation detection results.
@@ -83,6 +92,7 @@ func (r *NpmResult) CombinedOutput() string {
 type Updater struct {
 	DetectOverride           func() DetectResult
 	NpmInstallOverride       func(version string) *NpmResult
+	SkillsIndexFetchOverride func() *NpmResult
 	SkillsCommandOverride    func(args ...string) *NpmResult
 	VerifyOverride           func(expectedVersion string) error
 	RestoreAvailableOverride func() bool
@@ -153,6 +163,53 @@ func (u *Updater) RunNpmInstall(version string) *NpmResult {
 	return r
 }
 
+func (u *Updater) ListOfficialSkillsIndex() *NpmResult {
+	if u.SkillsIndexFetchOverride != nil {
+		return u.SkillsIndexFetchOverride()
+	}
+
+	r := &NpmResult{}
+	ctx, cancel := context.WithTimeout(context.Background(), skillsIndexFetchTimeout)
+	defer cancel()
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, officialSkillsIndexURL, nil)
+	if err != nil {
+		r.Err = err
+		return r
+	}
+
+	client := transport.NewHTTPClient(0)
+	client.CheckRedirect = func(req *http.Request, via []*http.Request) error {
+		if req.URL.Scheme != "https" {
+			return fmt.Errorf("official skills index redirected to non-HTTPS URL: %s", req.URL.Redacted())
+		}
+		return nil
+	}
+	resp, err := client.Do(req)
+	if err != nil {
+		r.Err = err
+		return r
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode < http.StatusOK || resp.StatusCode >= http.StatusMultipleChoices {
+		r.Err = fmt.Errorf("official skills index returned HTTP %d", resp.StatusCode)
+		return r
+	}
+
+	limited := io.LimitReader(resp.Body, skillsIndexMaxBodySize+1)
+	if _, err := io.Copy(&r.Stdout, limited); err != nil {
+		r.Err = err
+		return r
+	}
+	if r.Stdout.Len() > skillsIndexMaxBodySize {
+		r.Stdout.Reset()
+		r.Err = fmt.Errorf("official skills index exceeds %d bytes", skillsIndexMaxBodySize)
+		return r
+	}
+	return r
+}
+
 func (u *Updater) ListOfficialSkills() *NpmResult {
 	r := u.runSkillsListOfficial("https://open.feishu.cn")
 	if r.Err != nil {
@@ -165,6 +222,10 @@ func (u *Updater) ListGlobalSkills() *NpmResult {
 	return u.runSkillsListGlobal()
 }
 
+func (u *Updater) ListGlobalSkillsJSON() *NpmResult {
+	return u.runSkillsCommand("-y", "skills", "ls", "-g", "--json")
+}
+
 func (u *Updater) InstallSkill(nameList []string) *NpmResult {
 	r := u.runSkillsInstall("https://open.feishu.cn", nameList)
 	if r.Err != nil {

internal/selfupdate/updater_test.go

@@ -4,12 +4,18 @@
 package selfupdate
 
 import (
+	"context"
+	"errors"
 	"fmt"
+	"net"
+	"net/http"
+	"net/http/httptest"
 	"os"
 	"path/filepath"
 	"runtime"
 	"strings"
 	"testing"
+	"time"
 
 	"github.com/larksuite/cli/internal/vfs"
 )
@@ -188,6 +194,13 @@ func TestSkillsCommandsUseExpectedArgs(t *testing.T) {
 			},
 			want: "-y skills ls -g",
 		},
+		{
+			name: "list global json",
+			run: func(u *Updater) *NpmResult {
+				return u.ListGlobalSkillsJSON()
+			},
+			want: "-y skills ls -g --json",
+		},
 		{
 			name: "install skill primary",
 			run: func(u *Updater) *NpmResult {
@@ -225,6 +238,113 @@ func TestSkillsCommandsUseExpectedArgs(t *testing.T) {
 	}
 }
 
+func TestListOfficialSkillsIndexSuccess(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		fmt.Fprint(w, `{"skills":[{"name":"lark-calendar"}]}`)
+	}))
+	defer server.Close()
+
+	oldURL := officialSkillsIndexURL
+	officialSkillsIndexURL = server.URL
+	t.Cleanup(func() { officialSkillsIndexURL = oldURL })
+
+	result := New().ListOfficialSkillsIndex()
+	if result.Err != nil {
+		t.Fatalf("ListOfficialSkillsIndex() err = %v, want nil", result.Err)
+	}
+	if got := result.Stdout.String(); !strings.Contains(got, "lark-calendar") {
+		t.Fatalf("ListOfficialSkillsIndex() stdout = %q, want skill JSON", got)
+	}
+}
+
+func TestListOfficialSkillsIndexHTTPError(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Error(w, "not found", http.StatusNotFound)
+	}))
+	defer server.Close()
+
+	oldURL := officialSkillsIndexURL
+	officialSkillsIndexURL = server.URL
+	t.Cleanup(func() { officialSkillsIndexURL = oldURL })
+
+	result := New().ListOfficialSkillsIndex()
+	if result.Err == nil || !strings.Contains(result.Err.Error(), "HTTP 404") {
+		t.Fatalf("ListOfficialSkillsIndex() err = %v, want HTTP 404", result.Err)
+	}
+}
+
+func TestListOfficialSkillsIndexBodyTooLarge(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		fmt.Fprint(w, strings.Repeat("x", skillsIndexMaxBodySize+1))
+	}))
+	defer server.Close()
+
+	oldURL := officialSkillsIndexURL
+	officialSkillsIndexURL = server.URL
+	t.Cleanup(func() { officialSkillsIndexURL = oldURL })
+
+	result := New().ListOfficialSkillsIndex()
+	if result.Err == nil || !strings.Contains(result.Err.Error(), "exceeds") {
+		t.Fatalf("ListOfficialSkillsIndex() err = %v, want exceeds", result.Err)
+	}
+	if result.Stdout.Len() != 0 {
+		t.Fatalf("ListOfficialSkillsIndex() stdout len = %d, want 0", result.Stdout.Len())
+	}
+}
+
+func TestListOfficialSkillsIndexTimeout(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		time.Sleep(200 * time.Millisecond)
+		fmt.Fprint(w, `{"skills":[{"name":"lark-calendar"}]}`)
+	}))
+	defer server.Close()
+
+	oldURL := officialSkillsIndexURL
+	oldTimeout := skillsIndexFetchTimeout
+	officialSkillsIndexURL = server.URL
+	skillsIndexFetchTimeout = 50 * time.Millisecond
+	t.Cleanup(func() {
+		officialSkillsIndexURL = oldURL
+		skillsIndexFetchTimeout = oldTimeout
+	})
+
+	result := New().ListOfficialSkillsIndex()
+	var netErr net.Error
+	if result.Err == nil || (!errors.Is(result.Err, context.DeadlineExceeded) && !(errors.As(result.Err, &netErr) && netErr.Timeout())) {
+		t.Fatalf("ListOfficialSkillsIndex() err = %v, want timeout error", result.Err)
+	}
+}
+
+func TestListOfficialSkillsIndexRejectsNonHTTPSRedirect(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Redirect(w, r, "http://example.com/skills.json", http.StatusFound)
+	}))
+	defer server.Close()
+
+	oldURL := officialSkillsIndexURL
+	officialSkillsIndexURL = server.URL
+	t.Cleanup(func() { officialSkillsIndexURL = oldURL })
+
+	result := New().ListOfficialSkillsIndex()
+	if result.Err == nil || !strings.Contains(result.Err.Error(), "non-HTTPS") {
+		t.Fatalf("ListOfficialSkillsIndex() err = %v, want non-HTTPS redirect", result.Err)
+	}
+}
+
+func TestListOfficialSkillsIndexUsesOverride(t *testing.T) {
+	result := (&Updater{SkillsIndexFetchOverride: func() *NpmResult {
+		r := &NpmResult{}
+		r.Stdout.WriteString(`{"skills":[{"name":"override-skill"}]}`)
+		return r
+	}}).ListOfficialSkillsIndex()
+	if result.Err != nil {
+		t.Fatalf("ListOfficialSkillsIndex() err = %v, want nil", result.Err)
+	}
+	if !strings.Contains(result.Stdout.String(), "override-skill") {
+		t.Fatalf("ListOfficialSkillsIndex() stdout = %q, want override result", result.Stdout.String())
+	}
+}
+
 func TestListOfficialSkillsFallsBack(t *testing.T) {
 	called := []string{}
 	updater := &Updater{

internal/skillcontent/reader.go

@@ -0,0 +1,209 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package skillcontent reads embedded skill content from an injected fs.FS
+// rooted at the skill list (entries like "lark-calendar/SKILL.md").
+package skillcontent
+
+import (
+	"io/fs"
+	"path"
+	"sort"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"gopkg.in/yaml.v3"
+)
+
+type Reader struct {
+	fsys fs.FS
+}
+
+func New(fsys fs.FS) *Reader { return &Reader{fsys: fsys} }
+
+type SkillInfo struct {
+	Name        string         `json:"name"`
+	Description string         `json:"description"`
+	Version     string         `json:"version,omitempty"`
+	Metadata    map[string]any `json:"metadata,omitempty"`
+}
+
+// DirEntry.Path is skill-prefixed (e.g. "lark-doc/references/x.md") so it can be
+// fed straight back into `read`.
+type DirEntry struct {
+	Path  string `json:"path"`
+	IsDir bool   `json:"is_dir"`
+}
+
+func (r *Reader) List() ([]SkillInfo, error) {
+	entries, err := fs.ReadDir(r.fsys, ".")
+	if err != nil {
+		return nil, errs.NewInternalError(errs.SubtypeFileIO, "failed to read embedded skills: %v", err)
+	}
+	out := make([]SkillInfo, 0, len(entries))
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		// Skip dirs that aren't real skills (no SKILL.md).
+		if info, ok := r.skillInfo(e.Name()); ok {
+			out = append(out, info)
+		}
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
+	return out, nil
+}
+
+func (r *Reader) skillInfo(name string) (SkillInfo, bool) {
+	data, err := fs.ReadFile(r.fsys, name+"/SKILL.md")
+	if err != nil {
+		return SkillInfo{}, false
+	}
+	desc, version, metadata := parseFrontmatter(data)
+	return SkillInfo{Name: name, Description: desc, Version: version, Metadata: metadata}, true
+}
+
+// ListPath lists one directory layer (no recursion) under "<name>" or
+// "<name>/<sub>", returning the entries and the cleaned path listed.
+func (r *Reader) ListPath(arg string) ([]DirEntry, string, error) {
+	name, sub := SplitArg(arg)
+	if err := r.ensureSkill(name); err != nil {
+		return nil, "", err
+	}
+	dir := name
+	if sub != "" {
+		cleaned, err := cleanSubPath(sub)
+		if err != nil {
+			return nil, "", err
+		}
+		dir = name + "/" + cleaned
+		info, err := fs.Stat(r.fsys, dir)
+		if err != nil {
+			return nil, "", errs.NewValidationError(errs.SubtypeInvalidArgument,
+				"path %q not found in skill %q", sub, name).
+				WithHint("run 'lark-cli skills list " + name + "' to see files in this skill")
+		}
+		if !info.IsDir() {
+			return nil, "", errs.NewValidationError(errs.SubtypeInvalidArgument,
+				"path %q is a file, not a directory; use 'lark-cli skills read %s/%s' to read it", sub, name, cleaned)
+		}
+	}
+	entries, err := fs.ReadDir(r.fsys, dir)
+	if err != nil {
+		return nil, "", errs.NewInternalError(errs.SubtypeFileIO,
+			"failed to read embedded skill content: %v", err)
+	}
+	out := make([]DirEntry, 0, len(entries))
+	for _, e := range entries {
+		out = append(out, DirEntry{Path: dir + "/" + e.Name(), IsDir: e.IsDir()})
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Path < out[j].Path })
+	return out, dir, nil
+}
+
+// SplitArg splits "<name>/<rest>" at the first separator; an argument with no
+// separator is a bare skill name (rest "").
+func SplitArg(arg string) (name, rest string) {
+	name, rest, _ = strings.Cut(arg, "/")
+	return name, rest
+}
+
+// parseFrontmatter best-effort-extracts the frontmatter fields; missing or
+// unparseable frontmatter yields ("", "", nil), never an error.
+func parseFrontmatter(skillMD []byte) (description, version string, metadata map[string]any) {
+	lines := strings.Split(string(skillMD), "\n")
+	if strings.TrimRight(lines[0], "\r") != "---" {
+		return "", "", nil
+	}
+	block := make([]string, 0, len(lines))
+	closed := false
+	for _, ln := range lines[1:] {
+		if strings.TrimRight(ln, "\r") == "---" {
+			closed = true
+			break
+		}
+		block = append(block, ln)
+	}
+	if !closed {
+		return "", "", nil
+	}
+	var fm struct {
+		Description string         `yaml:"description"`
+		Version     string         `yaml:"version"`
+		Metadata    map[string]any `yaml:"metadata"`
+	}
+	if err := yaml.Unmarshal([]byte(strings.Join(block, "\n")), &fm); err != nil {
+		return "", "", nil
+	}
+	return fm.Description, fm.Version, fm.Metadata
+}
+
+func (r *Reader) ReadSkill(name string) ([]byte, error) {
+	if err := r.ensureSkill(name); err != nil {
+		return nil, err
+	}
+	data, err := fs.ReadFile(r.fsys, name+"/SKILL.md")
+	if err != nil {
+		return nil, errs.NewInternalError(errs.SubtypeFileIO,
+			"failed to read embedded skill content: %v", err)
+	}
+	return data, nil
+}
+
+func (r *Reader) ensureSkill(name string) error {
+	if name == "" || strings.ContainsAny(name, `/\`) || name == "." || name == ".." {
+		return unknownSkill(name)
+	}
+	info, err := fs.Stat(r.fsys, name)
+	if err != nil || !info.IsDir() {
+		return unknownSkill(name)
+	}
+	return nil
+}
+
+func unknownSkill(name string) error {
+	return errs.NewValidationError(errs.SubtypeInvalidArgument, "unknown skill %q", name).
+		WithHint("run 'lark-cli skills list' to see available skills")
+}
+
+// cleanSubPath returns the cleaned form of relpath, rejecting absolute paths and
+// ".." escapes. relpath must be non-empty (callers handle the skill-root case).
+func cleanSubPath(relpath string) (string, error) {
+	cleaned := path.Clean(relpath)
+	// path.Clean only treats '/' as a separator, so a Windows-style "..\" prefix
+	// survives; reject it explicitly alongside "../".
+	if relpath == "" || path.IsAbs(relpath) || cleaned == "." ||
+		cleaned == ".." || strings.HasPrefix(cleaned, "../") || strings.HasPrefix(cleaned, `..\`) {
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
+			"invalid path %q: must be a relative path without '..'", relpath)
+	}
+	return cleaned, nil
+}
+
+// ReadReference returns the bytes of <name>/<relpath> and the cleaned path.
+func (r *Reader) ReadReference(name, relpath string) ([]byte, string, error) {
+	if err := r.ensureSkill(name); err != nil {
+		return nil, "", err
+	}
+	cleaned, err := cleanSubPath(relpath)
+	if err != nil {
+		return nil, "", err
+	}
+	full := name + "/" + cleaned
+	info, err := fs.Stat(r.fsys, full)
+	if err != nil {
+		return nil, "", errs.NewValidationError(errs.SubtypeInvalidArgument,
+			"reference %q not found in skill %q", relpath, name).
+			WithHint("run 'lark-cli skills list " + name + "' to see files in this skill")
+	}
+	if info.IsDir() {
+		return nil, "", errs.NewValidationError(errs.SubtypeInvalidArgument,
+			"reference %q is a directory, not a file", relpath)
+	}
+	data, err := fs.ReadFile(r.fsys, full)
+	if err != nil {
+		return nil, "", errs.NewInternalError(errs.SubtypeFileIO,
+			"failed to read embedded skill content: %v", err)
+	}
+	return data, cleaned, nil
+}

internal/skillcontent/reader_test.go

@@ -0,0 +1,290 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package skillcontent
+
+import (
+	"errors"
+	"strings"
+	"testing"
+	"testing/fstest"
+
+	"github.com/larksuite/cli/errs"
+)
+
+func testFS() fstest.MapFS {
+	return fstest.MapFS{
+		"lark-calendar/SKILL.md":             {Data: []byte("---\nname: lark-calendar\nversion: 1.0.0\ndescription: \"Calendar skill\"\nmetadata:\n  requires:\n    bins: [\"lark-cli\"]\n  cliHelp: \"lark-cli calendar --help\"\n---\nbody\n")},
+		"lark-calendar/references/agenda.md": {Data: []byte("# Agenda")},
+		"lark-calendar/references/create.md": {Data: []byte("# Create")},
+		"lark-calendar/assets/tpl.html":      {Data: []byte("<html></html>")},
+		"lark-im/SKILL.md":                   {Data: []byte("no frontmatter here\n")},
+		"lark-im/references/send.md":         {Data: []byte("# Send")},
+	}
+}
+
+func TestList(t *testing.T) {
+	r := New(testFS())
+	skills, err := r.List()
+	if err != nil {
+		t.Fatalf("List() error: %v", err)
+	}
+	if len(skills) != 2 {
+		t.Fatalf("got %d skills, want 2", len(skills))
+	}
+	if skills[0].Name != "lark-calendar" || skills[1].Name != "lark-im" {
+		t.Fatalf("skills not sorted by name: %v", skills)
+	}
+	if skills[0].Description != "Calendar skill" {
+		t.Errorf("description: got %q, want %q", skills[0].Description, "Calendar skill")
+	}
+	// version is the frontmatter `version:` field, passed through for drift checks.
+	if skills[0].Version != "1.0.0" {
+		t.Errorf("version: got %q, want %q", skills[0].Version, "1.0.0")
+	}
+	// metadata is the frontmatter `metadata:` block, passed through verbatim.
+	if skills[0].Metadata == nil {
+		t.Fatal("expected metadata for lark-calendar")
+	}
+	if skills[0].Metadata["cliHelp"] != "lark-cli calendar --help" {
+		t.Errorf("metadata.cliHelp: got %v", skills[0].Metadata["cliHelp"])
+	}
+	// No frontmatter → empty description and nil metadata (omitted from JSON).
+	if skills[1].Description != "" {
+		t.Errorf("lark-im description: got %q, want empty", skills[1].Description)
+	}
+	if skills[1].Metadata != nil {
+		t.Errorf("lark-im metadata: got %v, want nil", skills[1].Metadata)
+	}
+	if skills[1].Version != "" {
+		t.Errorf("lark-im version: got %q, want empty", skills[1].Version)
+	}
+}
+
+func TestListPath(t *testing.T) {
+	r := New(testFS())
+
+	// Skill root: direct children only (one layer), each path skill-prefixed.
+	entries, listed, err := r.ListPath("lark-calendar")
+	if err != nil {
+		t.Fatalf("ListPath root error: %v", err)
+	}
+	if listed != "lark-calendar" {
+		t.Errorf("listed path: got %q", listed)
+	}
+	want := map[string]bool{ // path → isDir
+		"lark-calendar/SKILL.md":   false,
+		"lark-calendar/references": true,
+		"lark-calendar/assets":     true,
+	}
+	if len(entries) != len(want) {
+		t.Fatalf("root entries: got %v, want %d entries", entries, len(want))
+	}
+	for _, e := range entries {
+		isDir, ok := want[e.Path]
+		if !ok {
+			t.Errorf("unexpected entry %q", e.Path)
+			continue
+		}
+		if e.IsDir != isDir {
+			t.Errorf("%q is_dir: got %v, want %v", e.Path, e.IsDir, isDir)
+		}
+	}
+	// Entries are sorted by path.
+	if entries[0].Path != "lark-calendar/SKILL.md" {
+		t.Errorf("entries not sorted: %v", entries)
+	}
+
+	// Subdirectory: one layer under <name>/<subpath>.
+	subEntries, subListed, err := r.ListPath("lark-calendar/references")
+	if err != nil {
+		t.Fatalf("ListPath subdir error: %v", err)
+	}
+	if subListed != "lark-calendar/references" {
+		t.Errorf("listed subpath: got %q", subListed)
+	}
+	if len(subEntries) != 2 ||
+		subEntries[0].Path != "lark-calendar/references/agenda.md" ||
+		subEntries[1].Path != "lark-calendar/references/create.md" {
+		t.Errorf("subdir entries: got %v", subEntries)
+	}
+
+	// Unknown skill → typed validation error.
+	if _, _, err := r.ListPath("no-such-skill"); err == nil {
+		t.Error("expected error for unknown skill")
+	} else {
+		var verr *errs.ValidationError
+		if !errors.As(err, &verr) {
+			t.Errorf("expected *errs.ValidationError, got %T", err)
+		}
+	}
+
+	// Path that points at a file (not a dir) → validation error.
+	if _, _, err := r.ListPath("lark-calendar/SKILL.md"); err == nil {
+		t.Error("expected error listing a file")
+	} else if !strings.Contains(err.Error(), "is a file") {
+		t.Errorf("message: got %q", err.Error())
+	}
+
+	// Nonexistent subpath → validation error.
+	if _, _, err := r.ListPath("lark-calendar/nope"); err == nil {
+		t.Error("expected not-found error")
+	} else if !strings.Contains(err.Error(), "not found") {
+		t.Errorf("message: got %q", err.Error())
+	}
+
+	// Traversal in the subpath is rejected, no listing leaked.
+	for _, bad := range []string{"lark-calendar/../lark-im", "lark-calendar/../../etc", `lark-calendar/..\x`} {
+		entries, _, err := r.ListPath(bad)
+		if err == nil {
+			t.Errorf("expected rejection for %q", bad)
+		}
+		if entries != nil {
+			t.Errorf("entries leaked for %q: %v", bad, entries)
+		}
+	}
+}
+
+func TestReadSkill(t *testing.T) {
+	r := New(testFS())
+
+	data, err := r.ReadSkill("lark-calendar")
+	if err != nil {
+		t.Fatalf("ReadSkill error: %v", err)
+	}
+	if !strings.HasPrefix(string(data), "---\nname: lark-calendar") {
+		t.Errorf("unexpected content: %q", string(data))
+	}
+
+	_, err = r.ReadSkill("no-such-skill")
+	if err == nil {
+		t.Fatal("expected error for unknown skill")
+	}
+	var verr *errs.ValidationError
+	if !errors.As(err, &verr) {
+		t.Fatalf("expected *errs.ValidationError, got %T", err)
+	}
+	if !strings.Contains(verr.Message, `unknown skill "no-such-skill"`) {
+		t.Errorf("message: got %q", verr.Message)
+	}
+
+	if _, err := r.ReadSkill("../etc"); err == nil {
+		t.Error("expected error for name with separator")
+	}
+}
+
+func TestReadReference(t *testing.T) {
+	r := New(testFS())
+
+	data, cleaned, err := r.ReadReference("lark-calendar", "references/agenda.md")
+	if err != nil {
+		t.Fatalf("ReadReference error: %v", err)
+	}
+	if string(data) != "# Agenda" {
+		t.Errorf("content: got %q", string(data))
+	}
+	if cleaned != "references/agenda.md" {
+		t.Errorf("cleaned path: got %q", cleaned)
+	}
+
+	if _, _, err := r.ReadReference("lark-calendar", "references/nope.md"); err == nil {
+		t.Error("expected not-found error")
+	} else if !strings.Contains(err.Error(), "not found") {
+		t.Errorf("message: got %q", err.Error())
+	}
+
+	if _, _, err := r.ReadReference("lark-calendar", "references"); err == nil {
+		t.Error("expected directory error")
+	} else if !strings.Contains(err.Error(), "is a directory") {
+		t.Errorf("message: got %q", err.Error())
+	}
+
+	for _, bad := range []string{"../../etc/passwd", "/etc/passwd", "..", "", "references/../../im/SKILL.md", `..\..\x`} {
+		data, _, err := r.ReadReference("lark-calendar", bad)
+		if err == nil {
+			t.Errorf("expected rejection for %q", bad)
+		}
+		if data != nil {
+			t.Errorf("content leaked for %q: %q", bad, string(data))
+		}
+		var verr *errs.ValidationError
+		if !errors.As(err, &verr) {
+			t.Errorf("expected validation error for %q, got %T", bad, err)
+		}
+	}
+}
+
+func TestParseFrontmatter(t *testing.T) {
+	cases := []struct {
+		name        string
+		input       string
+		wantDesc    string
+		wantVer     string
+		wantHasMeta bool
+	}{
+		{
+			name:        "description, version and metadata",
+			input:       "---\ndescription: My skill\nversion: 2.1.0\nmetadata:\n  cliHelp: \"x\"\n---\nbody\n",
+			wantDesc:    "My skill",
+			wantVer:     "2.1.0",
+			wantHasMeta: true,
+		},
+		{
+			name:     "description only, no metadata",
+			input:    "---\ndescription: Plain\n---\nbody\n",
+			wantDesc: "Plain",
+		},
+		{
+			name:  "no frontmatter",
+			input: "no frontmatter here\n",
+		},
+		{
+			name:  "unclosed frontmatter",
+			input: "---\ndescription: Never closed\n",
+		},
+		{
+			name:  "malformed YAML inside frontmatter",
+			input: "---\n: bad: yaml: [\n---\nbody\n",
+		},
+		{
+			name:        "CRLF line endings",
+			input:       "---\r\ndescription: CRLF skill\r\nmetadata:\r\n  cliHelp: \"y\"\r\n---\r\nbody\r\n",
+			wantDesc:    "CRLF skill",
+			wantHasMeta: true,
+		},
+		{
+			name:  "empty input",
+			input: "",
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			desc, ver, meta := parseFrontmatter([]byte(tc.input))
+			if desc != tc.wantDesc {
+				t.Errorf("description = %q, want %q", desc, tc.wantDesc)
+			}
+			if ver != tc.wantVer {
+				t.Errorf("version = %q, want %q", ver, tc.wantVer)
+			}
+			if (meta != nil) != tc.wantHasMeta {
+				t.Errorf("metadata = %v, wantHasMeta %v", meta, tc.wantHasMeta)
+			}
+		})
+	}
+}
+
+func TestReadSkillMissingFile(t *testing.T) {
+	// Use a separate MapFS so testFS() (and TestList) are unaffected.
+	emptyFS := fstest.MapFS{
+		"lark-empty/references/x.md": {Data: []byte("# X")},
+	}
+	r := New(emptyFS)
+	_, err := r.ReadSkill("lark-empty")
+	if err == nil {
+		t.Fatal("expected error when SKILL.md is absent")
+	}
+	var ierr *errs.InternalError
+	if !errors.As(err, &ierr) {
+		t.Fatalf("expected *errs.InternalError, got %T: %v", err, err)
+	}
+}

internal/skillscheck/sync.go

@@ -4,6 +4,7 @@
 package skillscheck
 
 import (
+	"encoding/json"
 	"fmt"
 	"regexp"
 	"sort"
@@ -57,6 +58,52 @@ func ParseSkillsList(text string) []string {
 	return nil
 }
 
+func ParseGlobalSkillsJSON(text string) []string {
+	type globalSkill struct {
+		Name string `json:"name"`
+	}
+
+	var skills []globalSkill
+	if err := json.Unmarshal([]byte(text), &skills); err != nil {
+		return nil
+	}
+
+	seen := map[string]bool{}
+	for _, skill := range skills {
+		candidate := strings.TrimSpace(skill.Name)
+		if candidate == "" || !skillNamePattern.MatchString(candidate) {
+			continue
+		}
+		seen[candidate] = true
+	}
+
+	return sortedKeys(seen)
+}
+
+func ParseOfficialSkillsIndexJSON(text string) ([]string, error) {
+	type officialSkill struct {
+		Name string `json:"name"`
+	}
+	type officialIndex struct {
+		Skills []officialSkill `json:"skills"`
+	}
+
+	var index officialIndex
+	if err := json.Unmarshal([]byte(text), &index); err != nil {
+		return nil, err
+	}
+
+	seen := map[string]bool{}
+	for _, skill := range index.Skills {
+		candidate := strings.TrimSpace(skill.Name)
+		if skillNamePattern.MatchString(candidate) {
+			seen[candidate] = true
+		}
+	}
+
+	return sortedKeys(seen), nil
+}
+
 // parseGlobalSkillsList parses the output of "npx -y skills ls -g"
 func parseGlobalSkillsList(lines []string) []string {
 	seen := map[string]bool{}
@@ -77,8 +124,11 @@ func parseGlobalSkillsList(lines []string) []string {
 			continue
 		}
 
-		// Skip indented lines (Agents: ...)
-		if strings.HasPrefix(line, "  ") || strings.HasPrefix(line, "\t") {
+		if strings.HasPrefix(trimmed, "Agents:") {
+			continue
+		}
+
+		if isGlobalSkillsSectionHeader(trimmed) {
 			continue
 		}
 
@@ -91,21 +141,24 @@ func parseGlobalSkillsList(lines []string) []string {
 		candidate := parts[0]
 
 		// Validate and add
-		if candidate == "" || strings.Contains(candidate, " ") || strings.HasSuffix(candidate, ":") {
+		if candidate == "" || !skillNamePattern.MatchString(candidate) {
 			continue
 		}
-		if !skillNamePattern.MatchString(candidate) {
-			continue
-		}
-		if at := strings.Index(candidate, "@"); at > 0 {
-			candidate = candidate[:at]
-		}
 		seen[candidate] = true
 	}
 
 	return sortedKeys(seen)
 }
 
+func isGlobalSkillsSectionHeader(line string) bool {
+	switch line {
+	case "General", "Project", "Local":
+		return true
+	default:
+		return false
+	}
+}
+
 // parseOfficialSkillsList parses the output of "npx -y skills add ... --list"
 func parseOfficialSkillsList(lines []string) []string {
 	seen := map[string]bool{}
@@ -131,8 +184,7 @@ func parseOfficialSkillsList(lines []string) []string {
 
 			if len(parts) > 0 {
 				candidate := parts[0]
-				// Check if it's a valid official skill name
-				if strings.HasPrefix(candidate, "lark-") && skillNamePattern.MatchString(candidate) {
+				if skillNamePattern.MatchString(candidate) {
 					seen[candidate] = true
 				}
 			}
@@ -194,7 +246,9 @@ func PlanSync(input SyncInput) SyncPlan {
 }
 
 type SkillsRunner interface {
+	ListOfficialSkillsIndex() *selfupdate.NpmResult
 	ListOfficialSkills() *selfupdate.NpmResult
+	ListGlobalSkillsJSON() *selfupdate.NpmResult
 	ListGlobalSkills() *selfupdate.NpmResult
 	InstallSkill(nameList []string) *selfupdate.NpmResult
 	InstallAllSkills() *selfupdate.NpmResult
@@ -228,21 +282,15 @@ func SyncSkills(opts SyncOptions) *SyncResult {
 	}
 
 	// --- Step 1: List official skills ---
-	officialResult := opts.Runner.ListOfficialSkills()
-	if officialResult == nil || officialResult.Err != nil {
-		return fallbackFullInstall(opts, resultDetail(officialResult), nil)
-	}
-	official := ParseSkillsList(officialResult.Stdout.String())
-
-	if len(official) == 0 && strings.TrimSpace(officialResult.Stdout.String()) != "" {
-		return fallbackFullInstall(opts, "official skills list parsed as empty despite non-empty stdout", nil)
+	official, reason, ok := listOfficialSkills(opts.Runner)
+	if !ok {
+		return fallbackFullInstall(opts, reason, nil)
 	}
 
 	// --- Step 2: List local (installed) skills ---
-	local := []string{}
-	localResult := opts.Runner.ListGlobalSkills()
-	if localResult != nil && localResult.Err == nil {
-		local = ParseSkillsList(localResult.Stdout.String())
+	local, ok := listLocalSkills(opts.Runner)
+	if !ok {
+		return fallbackFullInstall(opts, "local skills list failed or parsed as empty", official)
 	}
 
 	// --- Step 3: Read previous state ---
@@ -270,6 +318,10 @@ func SyncSkills(opts SyncOptions) *SyncResult {
 		Force:          opts.Force,
 	}
 
+	if len(plan.ToUpdate) == 0 {
+		return fallbackFullInstall(opts, "toUpdate skills empty fallback", official)
+	}
+
 	if len(plan.ToUpdate) > 0 {
 		installResult := opts.Runner.InstallSkill(plan.ToUpdate)
 		if installResult == nil || installResult.Err != nil {
@@ -294,6 +346,58 @@ func SyncSkills(opts SyncOptions) *SyncResult {
 	return result
 }
 
+func listOfficialSkills(runner SkillsRunner) ([]string, string, bool) {
+	reasons := []string{}
+
+	indexResult := runner.ListOfficialSkillsIndex()
+	if indexResult == nil || indexResult.Err != nil {
+		reasons = append(reasons, "official skills index failed: "+resultDetail(indexResult))
+	} else {
+		official, err := ParseOfficialSkillsIndexJSON(indexResult.Stdout.String())
+		if err != nil {
+			reasons = append(reasons, "official skills index JSON invalid: "+err.Error())
+		} else if len(official) > 0 {
+			return official, "", true
+		} else {
+			reasons = append(reasons, "official skills index contains no skills")
+		}
+	}
+
+	officialResult := runner.ListOfficialSkills()
+	if officialResult == nil || officialResult.Err != nil {
+		reasons = append(reasons, "official skills list failed: "+resultDetail(officialResult))
+		return nil, strings.Join(reasons, "; "), false
+	}
+	official := ParseSkillsList(officialResult.Stdout.String())
+	if len(official) > 0 {
+		return official, "", true
+	}
+	if strings.TrimSpace(officialResult.Stdout.String()) != "" {
+		reasons = append(reasons, "official skills list parsed as empty despite non-empty stdout")
+	} else {
+		reasons = append(reasons, "official skills list returned no skills")
+	}
+	return nil, strings.Join(reasons, "; "), false
+}
+
+func listLocalSkills(runner SkillsRunner) ([]string, bool) {
+	jsonResult := runner.ListGlobalSkillsJSON()
+	if jsonResult != nil && jsonResult.Err == nil {
+		if local := ParseGlobalSkillsJSON(jsonResult.Stdout.String()); len(local) > 0 {
+			return local, true
+		}
+	}
+
+	textResult := runner.ListGlobalSkills()
+	if textResult != nil && textResult.Err == nil {
+		if local := ParseSkillsList(textResult.Stdout.String()); len(local) > 0 {
+			return local, true
+		}
+	}
+
+	return nil, false
+}
+
 // fallbackFullInstall performs a full skills install (npx -y skills add <source> -g -y)
 // when incremental sync is not possible. On success it writes a state file so that
 // subsequent syncs can use incremental mode. When official is non-nil the state

internal/skillscheck/sync_test.go

@@ -30,6 +30,19 @@ lark-cli-harness:dev@0.1.0
 	}
 }
 
+func TestParseOfficialSkillsListAcceptsNonLarkOfficialNames(t *testing.T) {
+	input := `Available Skills
+│    lark-calendar
+│    official-shared
+│    bad/name
+`
+	got := ParseSkillsList(input)
+	want := []string{"lark-calendar", "official-shared"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("ParseSkillsList() (Available Skills) = %#v, want %#v", got, want)
+	}
+}
+
 func TestParseGlobalSkillsList(t *testing.T) {
 	input := `Global Skills
 
@@ -67,6 +80,86 @@ func TestParseGlobalSkillsListWithANSI(t *testing.T) {
 	}
 }
 
+func TestParseGlobalSkillsListWithIndentedGroupedRows(t *testing.T) {
+	input := `Global Skills
+
+General
+  lark-apps ~/.agents/skills/lark-apps
+  lark-base ~/.agents/skills/lark-base
+`
+	got := ParseSkillsList(input)
+	want := []string{"lark-apps", "lark-base"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("ParseSkillsList() (indented Global Skills) = %#v, want %#v", got, want)
+	}
+}
+
+func TestParseGlobalSkillsJSON(t *testing.T) {
+	input := `[
+  {"name":"lark-calendar","path":"/Users/example/.agents/skills/lark-calendar","scope":"global","agents":["Codex"]},
+  {"name":"lark-mail@1.2.3","path":"/Users/example/.agents/skills/lark-mail","scope":"global","agents":["Codex"]},
+  {"name":"lark-calendar","path":"/Users/example/.agents/skills/lark-calendar","scope":"global","agents":["Codex"]},
+  {"name":"  lark-base  ","path":"/Users/example/.agents/skills/lark-base","scope":"global","agents":["Codex"]},
+  {"name":""},
+  {"name":"   "},
+  {"name":"bad skill"}
+]`
+	got := ParseGlobalSkillsJSON(input)
+	want := []string{"lark-base", "lark-calendar", "lark-mail@1.2.3"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("ParseGlobalSkillsJSON() = %#v, want %#v", got, want)
+	}
+}
+
+func TestParseGlobalSkillsJSONInvalidOrUnsupported(t *testing.T) {
+	for _, input := range []string{
+		`not json`,
+		`{"name":"lark-calendar"}`,
+		`[]`,
+	} {
+		if got := ParseGlobalSkillsJSON(input); len(got) != 0 {
+			t.Fatalf("ParseGlobalSkillsJSON(%q) = %#v, want empty", input, got)
+		}
+	}
+}
+
+func TestParseOfficialSkillsIndexJSON(t *testing.T) {
+	input := `{
+  "skills": [
+    {"name":"lark-calendar","description":"Calendar","files":["SKILL.md"]},
+    {"name":"lark-mail","description":"Mail","files":["SKILL.md","references/lark-mail-search.md"]},
+    {"name":"  lark-base  ","description":"Base","files":[]},
+    {"name":"lark-calendar","description":"duplicate","files":["SKILL.md"]},
+    {"name":"custom-skill","description":"not official","files":["SKILL.md"]},
+    {"name":"bad skill","description":"invalid","files":["SKILL.md"]},
+    {"name":"","description":"empty","files":["SKILL.md"]}
+  ]
+}`
+	got, err := ParseOfficialSkillsIndexJSON(input)
+	if err != nil {
+		t.Fatalf("ParseOfficialSkillsIndexJSON() err = %v, want nil", err)
+	}
+	want := []string{"custom-skill", "lark-base", "lark-calendar", "lark-mail"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("ParseOfficialSkillsIndexJSON() = %#v, want %#v", got, want)
+	}
+}
+
+func TestParseOfficialSkillsIndexJSONInvalidOrUnsupported(t *testing.T) {
+	for _, input := range []string{
+		`not json`,
+		`[{"name":"lark-calendar"}]`,
+		`{"name":"lark-calendar"}`,
+		`{"skills":[]}`,
+		`{"skills":[{"name":"bad skill"}]}`,
+	} {
+		got, err := ParseOfficialSkillsIndexJSON(input)
+		if err == nil && len(got) != 0 {
+			t.Fatalf("ParseOfficialSkillsIndexJSON(%q) = %#v, want empty", input, got)
+		}
+	}
+}
+
 func TestPlanNormal_WithReadableStatePreservesDeletedAndAddsNew(t *testing.T) {
 	previous := &SkillsState{OfficialSkills: []string{"lark-calendar", "lark-mail"}}
 	got := PlanSync(SyncInput{
@@ -113,14 +206,22 @@ func TestPlanForceRestoresAllOfficial(t *testing.T) {
 }
 
 type fakeSkillsRunner struct {
-	officialOut   string
-	globalOut     string
-	officialErr   error
-	globalErr     error
-	installErr    error
-	installAllErr error
-	installed     [][]string
-	installedAll  int
+	officialIndexOut string
+	officialOut      string
+	globalJSONOut    string
+	globalOut        string
+	officialIndexErr error
+	officialErr      error
+	globalJSONErr    error
+	globalErr        error
+	installErr       error
+	installAllErr    error
+	installed        [][]string
+	installedAll     int
+	listedIndex      int
+	listedOfficial   int
+	listedGlobalJSON int
+	listedGlobalText int
 }
 
 func officialSkillsOutput(names ...string) string {
@@ -134,6 +235,19 @@ func officialSkillsOutput(names ...string) string {
 	return b.String()
 }
 
+func officialSkillsIndexOutput(names ...string) string {
+	var b strings.Builder
+	b.WriteString(`{"skills":[`)
+	for i, name := range names {
+		if i > 0 {
+			b.WriteString(",")
+		}
+		fmt.Fprintf(&b, `{"name":%q,"description":"test skill","files":["SKILL.md"]}`, name)
+	}
+	b.WriteString(`]}`)
+	return b.String()
+}
+
 func globalSkillsOutput(names ...string) string {
 	var b strings.Builder
 	b.WriteString("Global Skills\n\n")
@@ -146,14 +260,45 @@ func globalSkillsOutput(names ...string) string {
 	return b.String()
 }
 
+func globalSkillsJSONOutput(names ...string) string {
+	var b strings.Builder
+	b.WriteString("[")
+	for i, name := range names {
+		if i > 0 {
+			b.WriteString(",")
+		}
+		fmt.Fprintf(&b, `{"name":%q,"path":"/Users/example/.agents/skills/%s","scope":"global","agents":["Codex"]}`, name, name)
+	}
+	b.WriteString("]")
+	return b.String()
+}
+
+func (f *fakeSkillsRunner) ListOfficialSkillsIndex() *selfupdate.NpmResult {
+	f.listedIndex++
+	r := &selfupdate.NpmResult{}
+	r.Stdout.WriteString(f.officialIndexOut)
+	r.Err = f.officialIndexErr
+	return r
+}
+
 func (f *fakeSkillsRunner) ListOfficialSkills() *selfupdate.NpmResult {
+	f.listedOfficial++
 	r := &selfupdate.NpmResult{}
 	r.Stdout.WriteString(f.officialOut)
 	r.Err = f.officialErr
 	return r
 }
 
+func (f *fakeSkillsRunner) ListGlobalSkillsJSON() *selfupdate.NpmResult {
+	f.listedGlobalJSON++
+	r := &selfupdate.NpmResult{}
+	r.Stdout.WriteString(f.globalJSONOut)
+	r.Err = f.globalJSONErr
+	return r
+}
+
 func (f *fakeSkillsRunner) ListGlobalSkills() *selfupdate.NpmResult {
+	f.listedGlobalText++
 	r := &selfupdate.NpmResult{}
 	r.Stdout.WriteString(f.globalOut)
 	r.Err = f.globalErr
@@ -186,8 +331,10 @@ func TestSyncSkills_WritesStateAndDoesNotWriteStamp(t *testing.T) {
 	}
 
 	runner := &fakeSkillsRunner{
-		officialOut: officialSkillsOutput("lark-calendar", "lark-mail", "lark-new"),
-		globalOut:   globalSkillsOutput("lark-calendar", "lark-custom"),
+		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-mail", "lark-new"),
+		officialOut:      officialSkillsOutput("lark-calendar", "lark-mail", "lark-new"),
+		globalJSONOut:    globalSkillsJSONOutput("lark-calendar", "lark-custom"),
+		globalOut:        globalSkillsOutput("lark-mail"),
 	}
 	result := SyncSkills(SyncOptions{
 		Version: "1.0.33",
@@ -199,6 +346,12 @@ func TestSyncSkills_WritesStateAndDoesNotWriteStamp(t *testing.T) {
 		t.Fatalf("SyncSkills() err = %v, want nil", result.Err)
 	}
 	assertStrings(t, runner.installed[0], []string{"lark-calendar", "lark-new"})
+	if runner.listedGlobalJSON != 1 {
+		t.Fatalf("listedGlobalJSON = %d, want 1", runner.listedGlobalJSON)
+	}
+	if runner.listedGlobalText != 0 {
+		t.Fatalf("listedGlobalText = %d, want 0 when JSON list succeeds", runner.listedGlobalText)
+	}
 
 	state, readable, err := ReadState()
 	if err != nil || !readable {
@@ -213,12 +366,119 @@ func TestSyncSkills_WritesStateAndDoesNotWriteStamp(t *testing.T) {
 	}
 }
 
+func TestSyncSkills_OfficialIndexSuccessSkipsOfficialListCommand(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	runner := &fakeSkillsRunner{
+		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-mail", "lark-new"),
+		officialOut:      officialSkillsOutput("lark-should-not-be-used"),
+		globalJSONOut:    globalSkillsJSONOutput("lark-calendar"),
+		globalOut:        globalSkillsOutput("lark-mail"),
+	}
+
+	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
+	if result.Err != nil {
+		t.Fatalf("SyncSkills() err = %v, want nil", result.Err)
+	}
+	assertStrings(t, result.Official, []string{"lark-calendar", "lark-mail", "lark-new"})
+	assertStrings(t, runner.installed[0], []string{"lark-calendar", "lark-mail", "lark-new"})
+	if runner.listedIndex != 1 {
+		t.Fatalf("listedIndex = %d, want 1", runner.listedIndex)
+	}
+	if runner.listedOfficial != 0 {
+		t.Fatalf("listedOfficial = %d, want 0 when index succeeds", runner.listedOfficial)
+	}
+}
+
+func TestSyncSkills_OfficialIndexFailureFallsBackToOfficialList(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	runner := &fakeSkillsRunner{
+		officialIndexErr: fmt.Errorf("index unavailable"),
+		officialOut:      officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONOut:    globalSkillsJSONOutput("lark-calendar"),
+	}
+
+	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
+	if result.Err != nil {
+		t.Fatalf("SyncSkills() err = %v, want nil", result.Err)
+	}
+	assertStrings(t, result.Official, []string{"lark-calendar", "lark-mail"})
+	if runner.listedIndex != 1 || runner.listedOfficial != 1 {
+		t.Fatalf("listed index/official = %d/%d, want 1/1", runner.listedIndex, runner.listedOfficial)
+	}
+	if runner.installedAll != 0 {
+		t.Fatalf("installedAll = %d, want 0", runner.installedAll)
+	}
+}
+
+func TestSyncSkills_OfficialIndexEmptyFallsBackToOfficialList(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	runner := &fakeSkillsRunner{
+		officialIndexOut: `{"skills":[]}`,
+		officialOut:      officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONOut:    globalSkillsJSONOutput("lark-calendar"),
+	}
+
+	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
+	if result.Err != nil {
+		t.Fatalf("SyncSkills() err = %v, want nil", result.Err)
+	}
+	assertStrings(t, result.Official, []string{"lark-calendar", "lark-mail"})
+	if runner.listedIndex != 1 || runner.listedOfficial != 1 {
+		t.Fatalf("listed index/official = %d/%d, want 1/1", runner.listedIndex, runner.listedOfficial)
+	}
+}
+
+func TestSyncSkills_OfficialDiscoveryFailuresFallBackToFullInstallWithReasons(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	runner := &fakeSkillsRunner{
+		officialIndexErr: fmt.Errorf("index unavailable"),
+		officialErr:      fmt.Errorf("list failed"),
+		installAllErr:    nil,
+	}
+
+	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
+	if result.Action != "fallback_synced" {
+		t.Fatalf("SyncSkills() action = %q, want fallback_synced", result.Action)
+	}
+	if runner.installedAll != 1 {
+		t.Fatalf("installedAll = %d, want 1", runner.installedAll)
+	}
+	if !strings.Contains(result.Detail, "official skills index failed") || !strings.Contains(result.Detail, "official skills list failed") {
+		t.Fatalf("SyncSkills() detail = %q, want both discovery failure reasons", result.Detail)
+	}
+}
+
+func TestSyncSkills_OfficialDiscoveryEmptyFallsBackToFullInstallWithReasons(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	runner := &fakeSkillsRunner{
+		officialIndexOut: `{"skills":[]}`,
+		installAllErr:    nil,
+	}
+
+	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
+	if result.Action != "fallback_synced" {
+		t.Fatalf("SyncSkills() action = %q, want fallback_synced", result.Action)
+	}
+	if runner.installedAll != 1 {
+		t.Fatalf("installedAll = %d, want 1", runner.installedAll)
+	}
+	if !strings.Contains(result.Detail, "official skills index contains no skills") || !strings.Contains(result.Detail, "official skills list returned no skills") {
+		t.Fatalf("SyncSkills() detail = %q, want both empty discovery reasons", result.Detail)
+	}
+}
+
 func TestSyncSkills_ListOfficialFailureFallsBackToFullInstall(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialErr:   fmt.Errorf("list failed"),
-		installAllErr: nil,
+		officialIndexErr: fmt.Errorf("index unavailable"),
+		officialErr:      fmt.Errorf("list failed"),
+		installAllErr:    nil,
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
@@ -246,8 +506,9 @@ func TestSyncSkills_ListOfficialFailureAndFullInstallFails(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialErr:   fmt.Errorf("list failed"),
-		installAllErr: fmt.Errorf("full install failed"),
+		officialIndexErr: fmt.Errorf("index unavailable"),
+		officialErr:      fmt.Errorf("list failed"),
+		installAllErr:    fmt.Errorf("full install failed"),
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
@@ -262,58 +523,123 @@ func TestSyncSkills_ListOfficialFailureAndFullInstallFails(t *testing.T) {
 	}
 }
 
-func TestSyncSkills_GlobalListFailureDegradesToColdStart(t *testing.T) {
+func TestSyncSkills_GlobalJSONFailureFallsBackToTextList(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialOut: officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalErr:   fmt.Errorf("global list failed"),
+		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-mail"),
+		officialOut:      officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONErr:    fmt.Errorf("json list failed"),
+		globalOut:        globalSkillsOutput("lark-calendar"),
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
 	if result.Err != nil {
-		t.Fatalf("SyncSkills() err = %v, want nil (degraded to cold start)", result.Err)
+		t.Fatalf("SyncSkills() err = %v, want nil", result.Err)
 	}
 	if result.Action != "synced" {
 		t.Fatalf("SyncSkills() action = %q, want synced", result.Action)
 	}
 	assertStrings(t, result.Updated, []string{"lark-calendar", "lark-mail"})
-	assertStrings(t, result.SkippedDeleted, []string{})
+	if runner.listedGlobalJSON != 1 || runner.listedGlobalText != 1 {
+		t.Fatalf("listed JSON/text = %d/%d, want 1/1", runner.listedGlobalJSON, runner.listedGlobalText)
+	}
+	if runner.installedAll != 0 {
+		t.Fatalf("installedAll = %d, want 0", runner.installedAll)
+	}
 }
 
-func TestSyncSkills_ParseEmptyGlobalListWithNonEmptyStdoutDegradesToColdStart(t *testing.T) {
+func TestSyncSkills_LocalListsFailureFallsBackToFullInstall(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialOut: officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalOut:   "Some unrecognized output format\n",
+		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-mail"),
+		officialOut:      officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONErr:    fmt.Errorf("json list failed with /Users/example/.agents/skills/lark-calendar agents Codex"),
+		globalErr:        fmt.Errorf("text list failed with /Users/example/.agents/skills/lark-mail agents Codex"),
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
-	if result.Err != nil {
-		t.Fatalf("SyncSkills() err = %v, want nil (degraded to cold start)", result.Err)
+	if result.Action != "fallback_synced" {
+		t.Fatalf("SyncSkills() action = %q, want fallback_synced", result.Action)
 	}
-	if result.Action != "synced" {
-		t.Fatalf("SyncSkills() action = %q, want synced", result.Action)
+	if len(runner.installed) != 0 {
+		t.Fatalf("installed = %#v, want no incremental installs", runner.installed)
 	}
+	if runner.installedAll != 1 {
+		t.Fatalf("installedAll = %d, want 1", runner.installedAll)
+	}
+	if strings.Contains(result.Detail, "/Users/example") || strings.Contains(result.Detail, "agents") {
+		t.Fatalf("SyncSkills() detail leaks local command output: %q", result.Detail)
+	}
+}
+
+func TestSyncSkills_ParseEmptyLocalListsFallBackToFullInstall(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	runner := &fakeSkillsRunner{
+		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-mail"),
+		officialOut:      officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONOut:    `[]`,
+		globalOut:        "Some unrecognized output format\n",
+	}
+
+	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
+	if result.Action != "fallback_synced" {
+		t.Fatalf("SyncSkills() action = %q, want fallback_synced", result.Action)
+	}
+	if len(runner.installed) != 0 {
+		t.Fatalf("installed = %#v, want no incremental installs", runner.installed)
+	}
+	if runner.installedAll != 1 {
+		t.Fatalf("installedAll = %d, want 1", runner.installedAll)
+	}
+}
+
+func TestSyncSkills_EmptyToUpdateFallsBackToFullInstall(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := WriteState(SkillsState{
+		Version:        "1.0.30",
+		OfficialSkills: []string{"lark-calendar", "lark-mail"},
+		UpdatedAt:      "2026-05-18T00:00:00Z",
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	runner := &fakeSkillsRunner{
+		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-mail"),
+		officialOut:      officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalOut:        globalSkillsOutput(),
+		installAllErr:    nil,
+	}
+
+	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
+	if result.Action != "fallback_synced" {
+		t.Fatalf("SyncSkills() action = %q, want fallback_synced", result.Action)
+	}
+	if len(runner.installed) != 0 {
+		t.Fatalf("installed = %#v, want no incremental installs", runner.installed)
+	}
+	if runner.installedAll != 1 {
+		t.Fatalf("installedAll = %d, want 1 (fallback triggered)", runner.installedAll)
+	}
+	assertStrings(t, result.Official, []string{"lark-calendar", "lark-mail"})
 	assertStrings(t, result.Updated, []string{"lark-calendar", "lark-mail"})
+	assertStrings(t, result.Added, []string{"lark-calendar", "lark-mail"})
 	assertStrings(t, result.SkippedDeleted, []string{})
-	if runner.installedAll != 0 {
-		t.Fatalf("installedAll = %d, want 0 (no fallback)", runner.installedAll)
-	}
-	if len(runner.installed) != 1 {
-		t.Fatalf("installed = %d calls, want 1 (incremental)", len(runner.installed))
-	}
 }
 
 func TestSyncSkills_InstallFailureFallsBackToFullInstall(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalOut:     globalSkillsOutput("lark-calendar", "lark-mail"),
-		installErr:    fmt.Errorf("incremental boom"),
-		installAllErr: nil,
+		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-mail"),
+		officialOut:      officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONOut:    globalSkillsJSONOutput("lark-calendar", "lark-mail"),
+		globalOut:        globalSkillsOutput("lark-calendar", "lark-mail"),
+		installErr:       fmt.Errorf("incremental boom"),
+		installAllErr:    nil,
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
@@ -341,10 +667,12 @@ func TestSyncSkills_InstallFailureAndFullInstallFails(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalOut:     globalSkillsOutput("lark-calendar", "lark-mail"),
-		installErr:    fmt.Errorf("incremental boom"),
-		installAllErr: fmt.Errorf("full install boom"),
+		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-mail"),
+		officialOut:      officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONOut:    globalSkillsJSONOutput("lark-calendar", "lark-mail"),
+		globalOut:        globalSkillsOutput("lark-calendar", "lark-mail"),
+		installErr:       fmt.Errorf("incremental boom"),
+		installAllErr:    fmt.Errorf("full install boom"),
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
@@ -373,8 +701,9 @@ func TestSyncSkills_ParseEmptyWithNonEmptyStdoutFallsBack(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialOut:   "Some unrecognized output format\n",
-		installAllErr: nil,
+		officialIndexErr: fmt.Errorf("index unavailable"),
+		officialOut:      "Some unrecognized output format\n",
+		installAllErr:    nil,
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
@@ -390,8 +719,9 @@ func TestSyncSkills_ParseEmptyWithNonEmptyStdoutAndFullInstallFails(t *testing.T
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialOut:   "Some unrecognized output format\n",
-		installAllErr: fmt.Errorf("full install failed"),
+		officialIndexErr: fmt.Errorf("index unavailable"),
+		officialOut:      "Some unrecognized output format\n",
+		installAllErr:    fmt.Errorf("full install failed"),
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
@@ -414,8 +744,9 @@ func TestSyncSkills_FallbackWithUnknownOfficialWritesMinimalState(t *testing.T)
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialOut:   "Some unrecognized output format\n",
-		installAllErr: nil,
+		officialIndexErr: fmt.Errorf("index unavailable"),
+		officialOut:      "Some unrecognized output format\n",
+		installAllErr:    nil,
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
@@ -439,10 +770,12 @@ func TestSyncSkills_FallbackWithKnownOfficialWritesFullState(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalOut:     globalSkillsOutput("lark-calendar", "lark-mail"),
-		installErr:    fmt.Errorf("incremental boom"),
-		installAllErr: nil,
+		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-mail"),
+		officialOut:      officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONOut:    globalSkillsJSONOutput("lark-calendar", "lark-mail"),
+		globalOut:        globalSkillsOutput("lark-calendar", "lark-mail"),
+		installErr:       fmt.Errorf("incremental boom"),
+		installAllErr:    nil,
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
@@ -463,10 +796,12 @@ func TestSyncSkills_FallbackResultContainsMetadata(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalOut:     globalSkillsOutput("lark-calendar", "lark-mail"),
-		installErr:    fmt.Errorf("incremental boom"),
-		installAllErr: nil,
+		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-mail"),
+		officialOut:      officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONOut:    globalSkillsJSONOutput("lark-calendar", "lark-mail"),
+		globalOut:        globalSkillsOutput("lark-calendar", "lark-mail"),
+		installErr:       fmt.Errorf("incremental boom"),
+		installAllErr:    nil,
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
@@ -486,8 +821,9 @@ func TestSyncSkills_FallbackBreaksDegradationLoop(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialErr:   fmt.Errorf("list failed"),
-		installAllErr: nil,
+		officialIndexErr: fmt.Errorf("index unavailable"),
+		officialErr:      fmt.Errorf("list failed"),
+		installAllErr:    nil,
 	}
 
 	result1 := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
@@ -504,8 +840,10 @@ func TestSyncSkills_FallbackBreaksDegradationLoop(t *testing.T) {
 	}
 
 	runner2 := &fakeSkillsRunner{
-		officialOut: officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalOut:   globalSkillsOutput("lark-calendar", "lark-mail"),
+		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-mail"),
+		officialOut:      officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONOut:    globalSkillsJSONOutput("lark-calendar", "lark-mail"),
+		globalOut:        globalSkillsOutput("lark-calendar", "lark-mail"),
 	}
 	result2 := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner2, Now: time.Now})
 	if result2.Action != "synced" {

internal/transport/config.go

@@ -1,14 +1,15 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
-// Package proxyplugin implements the ~/.lark-cli/proxy_config.json based security proxy plugin mode.
+// Package transport owns how the CLI assembles its outbound HTTP transport: the
+// shared base RoundTripper (Shared/Fallback/NewHTTPClient), the LARK_CLI_NO_PROXY
+// direct-egress clone, and the ~/.lark-cli/proxy_config.json proxy-plugin mode.
 //
-// It supports:
-// - forcing all outbound HTTP(S) requests through a fixed HTTP proxy
-// - trusting an additional root CA PEM bundle for MITM/inspection proxies
-//
-// Environment variables override matching values from proxy_config.json.
-package proxyplugin
+// Proxy-plugin mode forces all outbound HTTP(S) requests through a fixed loopback
+// proxy, optionally trusting an extra root CA PEM bundle for TLS-inspection
+// proxies, and fails closed on misconfiguration. Environment variables override
+// matching values from proxy_config.json.
+package transport
 
 import (
 	"encoding/json"
@@ -222,21 +223,6 @@ func (c *Config) proxyURL() (*url.URL, error) {
 	return u, nil
 }
 
-// redactProxyURL masks userinfo (username:password) in a proxy URL.
-// Handles both scheme-prefixed ("http://user:pass@host") and bare formats.
-func redactProxyURL(raw string) string {
-	u, err := url.Parse(raw)
-	if err == nil && u.User != nil {
-		u.User = url.User("***")
-		return u.String()
-	}
-	// Fallback: handle "user:pass@proxy:8080"
-	if at := strings.LastIndex(raw, "@"); at > 0 {
-		return "***@" + raw[at+1:]
-	}
-	return raw
-}
-
 // ApplyToTransport clones base and applies proxy plugin settings to the clone.
 // Caller owns the returned *http.Transport.
 func (c *Config) ApplyToTransport(base *http.Transport) (*http.Transport, error) {

internal/transport/config_test.go

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
-package proxyplugin
+package transport
 
 import (
 	"net/http"

internal/transport/shared.go

@@ -0,0 +1,83 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package transport
+
+import (
+	"net/http"
+	"os"
+	"sync"
+	"time"
+)
+
+// Shared returns the base http.RoundTripper for all CLI HTTP clients.
+//
+// Precedence (highest first):
+//  1. proxy-plugin mode — force traffic through a fixed loopback proxy;
+//     FAIL-CLOSED when the plugin config exists but is invalid.
+//  2. LARK_CLI_NO_PROXY — direct egress, proxy disabled.
+//  3. http.DefaultTransport — the stdlib process-wide singleton (honors
+//     HTTP(S)_PROXY), so every client shares one connection pool / TLS cache.
+//
+// The returned RoundTripper MUST NOT be mutated. Callers that need a customized
+// transport should assert to *http.Transport and Clone() it. A shared base is
+// required so persistConn read/write goroutines are reused; cloning per call
+// leaks them until IdleConnTimeout (~90s) fires.
+func Shared() http.RoundTripper {
+	// Proxy-plugin mode overrides everything, INCLUDING LARK_CLI_NO_PROXY. When
+	// the plugin config exists but is invalid, pluginTransport returns a
+	// fail-closed transport with ok=true and we return it here — we MUST NOT
+	// fall through to the NO_PROXY / DefaultTransport direct-egress paths below.
+	if t, ok := pluginTransport(); ok {
+		return t
+	}
+	if os.Getenv(EnvNoProxy) != "" {
+		return noProxyTransport()
+	}
+	return http.DefaultTransport
+}
+
+// Fallback returns a shared *http.Transport. It is a thin wrapper over Shared
+// retained so modules already on the leak-free singleton path (internal/auth,
+// internal/cmdutil transport decorators) do not have to migrate. New code
+// should prefer Shared and treat the base as an http.RoundTripper.
+//
+// Fail-closed invariant: pluginTransport always expresses its blocked transport
+// as a concrete *http.Transport (see failClosedTransport), so the assertion
+// below preserves the block. The noProxyTransport() fallback is therefore only
+// reached when no proxy plugin is configured and some external code replaced
+// http.DefaultTransport with a non-*http.Transport — a case with no fail-closed
+// intent, where a proxy-disabled transport is acceptable.
+func Fallback() *http.Transport {
+	if t, ok := Shared().(*http.Transport); ok {
+		return t
+	}
+	return noProxyTransport()
+}
+
+// NewHTTPClient returns an *http.Client whose Transport is the shared,
+// proxy-plugin-aware base (see Shared). Prefer this over a bare &http.Client{}
+// for outbound requests: a bare client falls back to http.DefaultTransport and
+// therefore silently bypasses proxy plugin mode (fixed proxy + trusted CA, or
+// fail-closed), creating an audit blind spot.
+//
+// A zero timeout means no client-level timeout (callers relying on context
+// deadlines pass 0).
+func NewHTTPClient(timeout time.Duration) *http.Client {
+	return &http.Client{
+		Transport: Shared(),
+		Timeout:   timeout,
+	}
+}
+
+// noProxyTransport is a proxy-disabled clone of http.DefaultTransport, lazily
+// built the first time LARK_CLI_NO_PROXY is observed set.
+var noProxyTransport = sync.OnceValue(func() *http.Transport {
+	def, ok := http.DefaultTransport.(*http.Transport)
+	if !ok {
+		return &http.Transport{}
+	}
+	t := def.Clone()
+	t.Proxy = nil
+	return t
+})

internal/transport/shared_test.go

@@ -0,0 +1,156 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package transport
+
+import (
+	"net/http"
+	"net/url"
+	"testing"
+	"time"
+)
+
+// TestShared_DefaultReturnsStdlibSingleton verifies the default shared transport.
+func TestShared_DefaultReturnsStdlibSingleton(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+	t.Setenv(EnvNoProxy, "")
+	if Shared() != http.DefaultTransport {
+		t.Error("Shared should return http.DefaultTransport when LARK_CLI_NO_PROXY is unset")
+	}
+}
+
+// TestShared_NoProxyReturnsClone verifies that disabling proxying returns a cloned transport.
+func TestShared_NoProxyReturnsClone(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+	t.Setenv(EnvNoProxy, "1")
+	tr := Shared()
+	if tr == http.DefaultTransport {
+		t.Fatal("Shared should return a clone, not DefaultTransport, when LARK_CLI_NO_PROXY is set")
+	}
+	ht, ok := tr.(*http.Transport)
+	if !ok {
+		t.Fatalf("expected *http.Transport, got %T", tr)
+	}
+	if ht.Proxy != nil {
+		t.Error("no-proxy transport should have Proxy == nil")
+	}
+}
+
+// TestShared_NoProxyIsCachedSingleton verifies singleton caching for the no-proxy transport.
+func TestShared_NoProxyIsCachedSingleton(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+	t.Setenv(EnvNoProxy, "1")
+	if Shared() != Shared() {
+		t.Error("repeated Shared calls with LARK_CLI_NO_PROXY set must return the same instance")
+	}
+}
+
+// TestShared_EnvUnsetAfterSetFallsBackToDefault verifies fallback to the stdlib
+// transport after unsetting LARK_CLI_NO_PROXY.
+func TestShared_EnvUnsetAfterSetFallsBackToDefault(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+	// Simulate a process that first runs with LARK_CLI_NO_PROXY=1 (populating
+	// the no-proxy singleton), then unsets it. Subsequent calls must return
+	// http.DefaultTransport, NOT the cached no-proxy clone.
+	t.Setenv(EnvNoProxy, "1")
+	if Shared() == http.DefaultTransport {
+		t.Fatal("precondition: first call with env set should not return DefaultTransport")
+	}
+
+	t.Setenv(EnvNoProxy, "")
+	if after := Shared(); after != http.DefaultTransport {
+		t.Errorf("after unsetting LARK_CLI_NO_PROXY, Shared must return http.DefaultTransport, got %T", after)
+	}
+}
+
+// TestShared_NoProxyOverridesSystemProxy verifies that LARK_CLI_NO_PROXY disables system proxies.
+func TestShared_NoProxyOverridesSystemProxy(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+	t.Setenv("HTTPS_PROXY", "http://should-be-ignored:8888")
+	t.Setenv(EnvNoProxy, "1")
+
+	ht, ok := Shared().(*http.Transport)
+	if !ok {
+		t.Fatalf("expected *http.Transport, got %T", Shared())
+	}
+	if ht.Proxy != nil {
+		t.Error("LARK_CLI_NO_PROXY should override system proxy settings")
+	}
+}
+
+// TestNewHTTPClient verifies the factory wires the shared proxy-plugin-aware
+// transport (instead of a bare client that bypasses proxy plugin mode).
+func TestNewHTTPClient(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+	t.Setenv(EnvNoProxy, "")
+
+	c := NewHTTPClient(7 * time.Second)
+	if c.Transport == nil {
+		t.Fatal("NewHTTPClient transport is nil; want shared transport")
+	}
+	if c.Transport != Shared() {
+		t.Errorf("NewHTTPClient transport = %v, want Shared()", c.Transport)
+	}
+	if c.Timeout != 7*time.Second {
+		t.Errorf("NewHTTPClient timeout = %v, want 7s", c.Timeout)
+	}
+}
+
+// TestShared_PluginOverridesNoProxy locks the contract that proxy-plugin mode wins
+// over LARK_CLI_NO_PROXY: even with NO_PROXY set, an enabled plugin forces the proxy.
+func TestShared_PluginOverridesNoProxy(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	t.Setenv(EnvNoProxy, "1") // NO_PROXY set, but the plugin must win
+	resetProxyPluginState()
+
+	writeFile(t, Path(), []byte(`{
+  "LARKSUITE_CLI_PROXY_ENABLE": true,
+  "LARKSUITE_CLI_PROXY_ADDRESS": "http://127.0.0.1:3128"
+}`), 0600)
+
+	tr, ok := Shared().(*http.Transport)
+	if !ok {
+		t.Fatalf("Shared() = %T, want proxy *http.Transport, not the NO_PROXY clone", tr)
+	}
+	u, err := tr.Proxy(&http.Request{URL: &url.URL{Scheme: "https", Host: "open.feishu.cn"}})
+	if err != nil || u == nil || u.String() != "http://127.0.0.1:3128" {
+		t.Fatalf("Proxy() = %v, %v; plugin must override NO_PROXY with the fixed proxy", u, err)
+	}
+}
+
+// TestShared_MalformedConfigFailsClosedEvenWithNoProxy locks the most dangerous
+// invariant of the fold: a malformed proxy_config.json must FAIL CLOSED, never
+// fall through to direct egress — not even to the LARK_CLI_NO_PROXY clone.
+func TestShared_MalformedConfigFailsClosedEvenWithNoProxy(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	t.Setenv(EnvNoProxy, "1")
+	resetProxyPluginState()
+
+	writeFile(t, Path(), []byte(`{`), 0600) // malformed
+
+	rt := Shared()
+	if rt == http.DefaultTransport {
+		t.Fatal("malformed config returned http.DefaultTransport — fail OPEN")
+	}
+	if rt == noProxyTransport() {
+		t.Fatal("malformed config fell through to the NO_PROXY direct-egress clone — fail OPEN")
+	}
+	resp, err := rt.RoundTrip(&http.Request{URL: &url.URL{Scheme: "https", Host: "open.feishu.cn"}})
+	if err == nil {
+		t.Fatalf("RoundTrip() err = nil (resp=%v); malformed config must fail closed", resp)
+	}
+}

internal/transport/tls_ca.go

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
-package proxyplugin
+package transport
 
 import (
 	"crypto/tls"

internal/transport/tls_ca_test.go

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
-package proxyplugin
+package transport
 
 import (
 	"crypto/rand"

internal/transport/transport.go

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
-package proxyplugin
+package transport
 
 import (
 	"fmt"
@@ -16,7 +16,7 @@ var proxyPluginTransport = sync.OnceValue(buildProxyPluginTransport)
 
 // cachedBlockedTransport is a fail-closed transport cached on first use when
 // the proxy plugin config exists but is invalid. This avoids cloning
-// http.DefaultTransport on every SharedTransport call.
+// http.DefaultTransport on every pluginTransport call.
 var cachedBlockedTransport = sync.OnceValue(buildBlockedTransport)
 
 func buildBlockedTransport() http.RoundTripper {
@@ -28,7 +28,7 @@ func buildProxyPluginTransport() http.RoundTripper {
 	if !ok {
 		// Cannot clone the stdlib transport. Fail closed with a concrete
 		// *http.Transport (not a bare RoundTripper) so downcasting callers such
-		// as util.FallbackTransport cannot silently degrade this into a
+		// as Fallback cannot silently degrade this into a
 		// direct-egress transport.
 		return failClosedTransport(fmt.Errorf("proxy plugin transport unavailable: http.DefaultTransport is %T, want *http.Transport", http.DefaultTransport))
 	}
@@ -51,9 +51,9 @@ func buildProxyPluginTransport() http.RoundTripper {
 	return t
 }
 
-// SharedTransport returns the proxy plugin transport when proxy plugin mode is
+// pluginTransport returns the proxy plugin transport when proxy plugin mode is
 // configured. The bool return is false when the plugin is not configured or not enabled.
-func SharedTransport() (http.RoundTripper, bool) {
+func pluginTransport() (http.RoundTripper, bool) {
 	cfg, err := Load()
 	if err != nil {
 		return cachedBlockedTransport(), true
@@ -68,7 +68,7 @@ func SharedTransport() (http.RoundTripper, bool) {
 // err. It clones http.DefaultTransport when possible (preserving dial/timeout
 // tuning); otherwise it builds a minimal transport. Returning a concrete
 // *http.Transport (rather than a bare RoundTripper) is required so downcasting
-// callers such as util.FallbackTransport cannot silently degrade a fail-closed
+// callers such as Fallback cannot silently degrade a fail-closed
 // signal into a direct-egress transport.
 func failClosedTransport(err error) *http.Transport {
 	if def, ok := http.DefaultTransport.(*http.Transport); ok {

internal/transport/transport_test.go

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
-package proxyplugin
+package transport
 
 import (
 	"io"
@@ -20,21 +20,21 @@ func resetProxyPluginState() {
 	cachedBlockedTransport = sync.OnceValue(buildBlockedTransport)
 }
 
-func TestSharedTransport_NotConfigured(t *testing.T) {
+func TestPluginTransport_NotConfigured(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	unsetProxyPluginEnv(t)
 	resetProxyPluginState()
 
-	tr, ok := SharedTransport()
+	tr, ok := pluginTransport()
 	if ok {
-		t.Fatalf("SharedTransport() ok = true, want false")
+		t.Fatalf("pluginTransport() ok = true, want false")
 	}
 	if tr != nil {
-		t.Fatalf("SharedTransport() transport = %T, want nil", tr)
+		t.Fatalf("pluginTransport() transport = %T, want nil", tr)
 	}
 }
 
-func TestSharedTransport_EnabledReturnsFixedProxy(t *testing.T) {
+func TestPluginTransport_EnabledReturnsFixedProxy(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	unsetProxyPluginEnv(t)
 	resetProxyPluginState()
@@ -46,13 +46,13 @@ func TestSharedTransport_EnabledReturnsFixedProxy(t *testing.T) {
   "LARKSUITE_CLI_CA_PATH": ""
 }`), 0600)
 
-	rt, ok := SharedTransport()
+	rt, ok := pluginTransport()
 	if !ok {
-		t.Fatal("SharedTransport() ok = false, want true")
+		t.Fatal("pluginTransport() ok = false, want true")
 	}
 	tr, ok := rt.(*http.Transport)
 	if !ok {
-		t.Fatalf("SharedTransport() = %T, want *http.Transport", rt)
+		t.Fatalf("pluginTransport() = %T, want *http.Transport", rt)
 	}
 	u, err := tr.Proxy(&http.Request{URL: &url.URL{Scheme: "https", Host: "open.feishu.cn"}})
 	if err != nil {
@@ -63,7 +63,7 @@ func TestSharedTransport_EnabledReturnsFixedProxy(t *testing.T) {
 	}
 }
 
-func TestSharedTransport_InvalidConfigWithNonTransportDefaultFailsClosed(t *testing.T) {
+func TestPluginTransport_InvalidConfigWithNonTransportDefaultFailsClosed(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	unsetProxyPluginEnv(t)
 	resetProxyPluginState()
@@ -72,12 +72,12 @@ func TestSharedTransport_InvalidConfigWithNonTransportDefaultFailsClosed(t *test
 
 	writeFile(t, Path(), []byte(`{`), 0600)
 
-	rt, ok := SharedTransport()
+	rt, ok := pluginTransport()
 	if !ok {
-		t.Fatal("SharedTransport() ok = false, want true")
+		t.Fatal("pluginTransport() ok = false, want true")
 	}
 	if rt == http.DefaultTransport {
-		t.Fatalf("SharedTransport() returned http.DefaultTransport, want fail-closed transport")
+		t.Fatalf("pluginTransport() returned http.DefaultTransport, want fail-closed transport")
 	}
 	resp, err := rt.RoundTrip(&http.Request{URL: &url.URL{Scheme: "https", Host: "open.feishu.cn"}})
 	if err == nil {
@@ -88,23 +88,23 @@ func TestSharedTransport_InvalidConfigWithNonTransportDefaultFailsClosed(t *test
 	}
 }
 
-func TestSharedTransport_InvalidConfigReturnsCachedInstance(t *testing.T) {
+func TestPluginTransport_InvalidConfigReturnsCachedInstance(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	unsetProxyPluginEnv(t)
 	resetProxyPluginState()
 
 	writeFile(t, Path(), []byte(`{`), 0600)
 
-	a, ok := SharedTransport()
+	a, ok := pluginTransport()
 	if !ok {
-		t.Fatal("SharedTransport() ok = false, want true")
+		t.Fatal("pluginTransport() ok = false, want true")
 	}
-	b, ok := SharedTransport()
+	b, ok := pluginTransport()
 	if !ok {
-		t.Fatal("SharedTransport() ok = false, want true")
+		t.Fatal("pluginTransport() ok = false, want true")
 	}
 	if a != b {
-		t.Fatalf("SharedTransport() returned different instances on repeated calls; blocked transport must be cached")
+		t.Fatalf("pluginTransport() returned different instances on repeated calls; blocked transport must be cached")
 	}
 }
 
@@ -148,13 +148,13 @@ func TestBuildProxyPluginTransport_NonTransportDefaultFailsClosed(t *testing.T)
 	}
 }
 
-// TestSharedTransport_InvalidConfigBlockerIsConcreteTransport guards the
-// fail-closed invariant that util.FallbackTransport relies on: even when
+// TestPluginTransport_InvalidConfigBlockerIsConcreteTransport guards the
+// fail-closed invariant that Fallback relies on: even when
 // http.DefaultTransport is not an *http.Transport, an invalid proxy config must
 // produce a blocked transport that is itself a concrete *http.Transport. If it
-// were a bare RoundTripper, util.FallbackTransport would downcast-fail and
+// were a bare RoundTripper, Fallback would downcast-fail and
 // silently degrade it into a direct-egress transport.
-func TestSharedTransport_InvalidConfigBlockerIsConcreteTransport(t *testing.T) {
+func TestPluginTransport_InvalidConfigBlockerIsConcreteTransport(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	unsetProxyPluginEnv(t)
 	resetProxyPluginState()
@@ -163,12 +163,12 @@ func TestSharedTransport_InvalidConfigBlockerIsConcreteTransport(t *testing.T) {
 
 	writeFile(t, Path(), []byte(`{`), 0600)
 
-	rt, ok := SharedTransport()
+	rt, ok := pluginTransport()
 	if !ok {
-		t.Fatal("SharedTransport() ok = false, want true")
+		t.Fatal("pluginTransport() ok = false, want true")
 	}
 	if _, isTransport := rt.(*http.Transport); !isTransport {
-		t.Fatalf("SharedTransport() blocked transport = %T, want *http.Transport so FallbackTransport cannot degrade it to direct egress", rt)
+		t.Fatalf("pluginTransport() blocked transport = %T, want *http.Transport so Fallback cannot degrade it to direct egress", rt)
 	}
 	// Must remain fail-closed.
 	resp, err := rt.RoundTrip(&http.Request{URL: &url.URL{Scheme: "https", Host: "open.feishu.cn"}})

internal/transport/warn.go

@@ -0,0 +1,104 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package transport
+
+import (
+	"fmt"
+	"io"
+	"net/url"
+	"os"
+	"strings"
+	"sync"
+
+	"github.com/larksuite/cli/internal/envvars"
+)
+
+// Proxy environment constants control shared transport proxy behavior.
+const (
+	// EnvNoProxy disables automatic proxy support when set to any non-empty value.
+	EnvNoProxy = "LARK_CLI_NO_PROXY"
+)
+
+// proxyEnvKeys lists environment variables that Go's ProxyFromEnvironment reads.
+var proxyEnvKeys = []string{
+	"HTTPS_PROXY", "https_proxy",
+	"HTTP_PROXY", "http_proxy",
+	"ALL_PROXY", "all_proxy",
+}
+
+// DetectProxyEnv returns the first proxy-related environment variable that is set,
+// or empty strings if none are configured.
+func DetectProxyEnv() (key, value string) {
+	for _, k := range proxyEnvKeys {
+		if v := os.Getenv(k); v != "" {
+			return k, v
+		}
+	}
+	return "", ""
+}
+
+// proxyWarningOnce ensures proxy environment warnings are emitted at most once.
+var proxyWarningOnce sync.Once
+
+// proxyPluginStatus reports the configured proxy plugin address, the extra
+// trusted CA path (if any), and whether proxy plugin mode is enabled. It is
+// indirected through a package variable so tests can simulate plugin-enabled
+// mode without the process-global Load() sync.Once cache.
+var proxyPluginStatus = func() (addr, caPath string, enabled bool) {
+	cfg, err := Load()
+	if err != nil || !cfg.Enabled() {
+		return "", "", false
+	}
+	return cfg.Proxy, cfg.CAPath, true
+}
+
+// redactProxyURL masks userinfo (username:password) in a proxy URL.
+// Handles both scheme-prefixed ("http://user:pass@host") and bare ("user:pass@host") formats.
+func redactProxyURL(raw string) string {
+	// Try standard url.Parse first (works when scheme is present)
+	u, err := url.Parse(raw)
+	if err == nil && u.User != nil {
+		return u.Scheme + "://***@" + u.Host + u.RequestURI()
+	}
+
+	// Fallback: handle bare URLs without scheme (e.g. "user:pass@proxy:8080")
+	if at := strings.LastIndex(raw, "@"); at > 0 {
+		return "***@" + raw[at+1:]
+	}
+
+	return raw
+}
+
+// WarnIfProxied prints a one-time warning to w when a proxy environment variable
+// is detected and proxy is not disabled via LARK_CLI_NO_PROXY. Proxy credentials
+// are redacted. Safe to call multiple times; only the first call prints.
+func WarnIfProxied(w io.Writer) {
+	proxyWarningOnce.Do(func() {
+		// Proxy plugin mode overrides env proxies and LARK_CLI_NO_PROXY (see
+		// Shared), so its warning and disable instructions take precedence.
+		// Emitting the env-proxy warning here would be misleading: it tells the
+		// user to set LARK_CLI_NO_PROXY=1, which does NOT disable the plugin proxy.
+		if addr, caPath, enabled := proxyPluginStatus(); enabled {
+			fmt.Fprintf(w, "[lark-cli] [WARN] proxy plugin enabled: all requests (including credentials) are forced through %s. To disable, set %s=false or remove %s.\n",
+				redactProxyURL(addr), envvars.CliProxyEnable, Path())
+			if strings.TrimSpace(caPath) != "" {
+				// A custom CA means upstream TLS can be intercepted/inspected by
+				// the proxy (MITM). Surface it so the operator is aware traffic
+				// (including Bearer tokens) is decryptable on this host.
+				fmt.Fprintf(w, "[lark-cli] [WARN] proxy plugin trusts a custom CA (%s); TLS to upstreams can be intercepted/inspected by this proxy.\n",
+					caPath)
+			}
+			return
+		}
+		if os.Getenv(EnvNoProxy) != "" {
+			return
+		}
+		key, val := DetectProxyEnv()
+		if key == "" {
+			return
+		}
+		fmt.Fprintf(w, "[lark-cli] [WARN] proxy detected: %s=%s — requests (including credentials) will transit through this proxy. Set %s=1 to disable proxy.\n",
+			key, redactProxyURL(val), EnvNoProxy)
+	})
+}

internal/transport/warn_test.go

@@ -1,44 +1,17 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
-package util
+package transport
 
 import (
 	"bytes"
-	"net/http"
-	"os"
 	"strings"
 	"sync"
 	"testing"
-	"time"
 
 	"github.com/larksuite/cli/internal/envvars"
 )
 
-// unsetEnv clears key for the duration of the test and restores its original value.
-func unsetEnv(t *testing.T, key string) {
-	t.Helper()
-	old, had := os.LookupEnv(key)
-	_ = os.Unsetenv(key)
-	t.Cleanup(func() {
-		if had {
-			_ = os.Setenv(key, old)
-		} else {
-			_ = os.Unsetenv(key)
-		}
-	})
-}
-
-// unsetProxyPluginEnv clears proxy-related environment variables for deterministic tests.
-func unsetProxyPluginEnv(t *testing.T) {
-	t.Helper()
-	// Ensure developer machine env doesn't accidentally enable proxy plugin mode
-	// and change expectations for SharedTransport().
-	unsetEnv(t, envvars.CliProxyEnable)
-	unsetEnv(t, envvars.CliProxyAddress)
-	unsetEnv(t, envvars.CliCAPath)
-}
-
 // TestDetectProxyEnv verifies proxy environment detection priority and empty-state behavior.
 func TestDetectProxyEnv(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
@@ -61,94 +34,17 @@ func TestDetectProxyEnv(t *testing.T) {
 	}
 }
 
-// TestSharedTransport_DefaultReturnsStdlibSingleton verifies the default shared transport.
-func TestSharedTransport_DefaultReturnsStdlibSingleton(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	unsetProxyPluginEnv(t)
-	t.Setenv(EnvNoProxy, "")
-	tr := SharedTransport()
-	if tr != http.DefaultTransport {
-		t.Error("SharedTransport should return http.DefaultTransport when LARK_CLI_NO_PROXY is unset")
-	}
-}
-
-// TestSharedTransport_NoProxyReturnsClone verifies that disabling proxying returns a cloned transport.
-func TestSharedTransport_NoProxyReturnsClone(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	unsetProxyPluginEnv(t)
-	t.Setenv(EnvNoProxy, "1")
-	tr := SharedTransport()
-	if tr == http.DefaultTransport {
-		t.Fatal("SharedTransport should return a clone, not DefaultTransport, when LARK_CLI_NO_PROXY is set")
-	}
-	ht, ok := tr.(*http.Transport)
-	if !ok {
-		t.Fatalf("expected *http.Transport, got %T", tr)
-	}
-	if ht.Proxy != nil {
-		t.Error("no-proxy transport should have Proxy == nil")
-	}
-}
-
-// TestSharedTransport_NoProxyIsCachedSingleton verifies singleton caching for the no-proxy transport.
-func TestSharedTransport_NoProxyIsCachedSingleton(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	unsetProxyPluginEnv(t)
-	t.Setenv(EnvNoProxy, "1")
-	a := SharedTransport()
-	b := SharedTransport()
-	if a != b {
-		t.Error("repeated SharedTransport calls with LARK_CLI_NO_PROXY set must return the same instance")
-	}
-}
-
-// TestSharedTransport_EnvUnsetAfterSetFallsBackToDefault verifies fallback to the stdlib transport after unsetting EnvNoProxy.
-func TestSharedTransport_EnvUnsetAfterSetFallsBackToDefault(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	unsetProxyPluginEnv(t)
-	// Simulate a process that first runs with LARK_CLI_NO_PROXY=1 (populating
-	// the no-proxy singleton), then unsets it. Subsequent calls must return
-	// http.DefaultTransport, NOT the cached no-proxy clone.
-	t.Setenv(EnvNoProxy, "1")
-	noProxy := SharedTransport()
-	if noProxy == http.DefaultTransport {
-		t.Fatal("precondition: first call with env set should not return DefaultTransport")
-	}
-
-	t.Setenv(EnvNoProxy, "")
-	after := SharedTransport()
-	if after != http.DefaultTransport {
-		t.Errorf("after unsetting LARK_CLI_NO_PROXY, SharedTransport must return http.DefaultTransport, got %T (%p)", after, after)
-	}
-}
-
-// TestSharedTransport_NoProxyOverridesSystemProxy verifies that EnvNoProxy disables system proxies.
-func TestSharedTransport_NoProxyOverridesSystemProxy(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	unsetProxyPluginEnv(t)
-	t.Setenv("HTTPS_PROXY", "http://should-be-ignored:8888")
-	t.Setenv(EnvNoProxy, "1")
-
-	ht, ok := SharedTransport().(*http.Transport)
-	if !ok {
-		t.Fatalf("expected *http.Transport, got %T", SharedTransport())
-	}
-	if ht.Proxy != nil {
-		t.Error("LARK_CLI_NO_PROXY should override system proxy settings")
-	}
-}
-
 // TestWarnIfProxied_WithProxy verifies that proxy detection emits a warning.
 func TestWarnIfProxied_WithProxy(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	unsetProxyPluginEnv(t)
-	// Reset the once guard for this test
+	resetProxyPluginState()
 	proxyWarningOnce = sync.Once{}
 
 	t.Setenv("HTTPS_PROXY", "http://corp-proxy:3128")
 
 	var buf bytes.Buffer
-	WarnIfProxied(&buf, true)
+	WarnIfProxied(&buf)
 
 	out := buf.String()
 	if out == "" {
@@ -166,6 +62,7 @@ func TestWarnIfProxied_WithProxy(t *testing.T) {
 func TestWarnIfProxied_WithoutProxy(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
 	proxyWarningOnce = sync.Once{}
 
 	for _, k := range proxyEnvKeys {
@@ -173,41 +70,25 @@ func TestWarnIfProxied_WithoutProxy(t *testing.T) {
 	}
 
 	var buf bytes.Buffer
-	WarnIfProxied(&buf, true)
+	WarnIfProxied(&buf)
 
 	if buf.Len() != 0 {
 		t.Errorf("expected no output when no proxy is set, got: %s", buf.String())
 	}
 }
 
-func TestWarnIfProxied_SilentWhenNonInteractive(t *testing.T) {
-	proxyWarningOnce = sync.Once{}
-
-	// Non-interactive (interactive=false) mirrors agent / CI / piped invocations
-	// where stdin is not a TTY. The proxy warning must be suppressed so callers
-	// that parse stdout as JSON — often merging streams with `2>&1` — are not
-	// corrupted by a stray stderr line.
-	t.Setenv("HTTPS_PROXY", "http://corp-proxy:3128")
-
-	var buf bytes.Buffer
-	WarnIfProxied(&buf, false)
-
-	if buf.Len() != 0 {
-		t.Errorf("expected no warning in non-interactive mode, got: %s", buf.String())
-	}
-}
-
-// TestWarnIfProxied_SilentWhenDisabled verifies that EnvNoProxy suppresses warnings.
+// TestWarnIfProxied_SilentWhenDisabled verifies that LARK_CLI_NO_PROXY suppresses warnings.
 func TestWarnIfProxied_SilentWhenDisabled(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
 	proxyWarningOnce = sync.Once{}
 
 	t.Setenv("HTTPS_PROXY", "http://proxy:8080")
 	t.Setenv(EnvNoProxy, "1")
 
 	var buf bytes.Buffer
-	WarnIfProxied(&buf, true)
+	WarnIfProxied(&buf)
 
 	if buf.Len() != 0 {
 		t.Errorf("expected no warning when proxy is disabled, got: %s", buf.String())
@@ -218,15 +99,16 @@ func TestWarnIfProxied_SilentWhenDisabled(t *testing.T) {
 func TestWarnIfProxied_OnlyOnce(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
 	proxyWarningOnce = sync.Once{}
 
 	t.Setenv("HTTP_PROXY", "http://proxy:1234")
 
 	var buf bytes.Buffer
-	WarnIfProxied(&buf, true)
+	WarnIfProxied(&buf)
 	first := buf.String()
 
-	WarnIfProxied(&buf, true)
+	WarnIfProxied(&buf)
 	second := buf.String()
 
 	if first == "" {
@@ -255,7 +137,7 @@ func TestWarnIfProxied_ProxyPluginEnabled(t *testing.T) {
 	t.Setenv(EnvNoProxy, "1")
 
 	var buf bytes.Buffer
-	WarnIfProxied(&buf, true)
+	WarnIfProxied(&buf)
 	out := buf.String()
 
 	if !strings.Contains(out, "127.0.0.1:3128") {
@@ -274,7 +156,7 @@ func TestWarnIfProxied_ProxyPluginEnabled(t *testing.T) {
 }
 
 // TestWarnIfProxied_ProxyPluginCustomCAWarns verifies that when a custom CA is
-// trusted, the warning surfaces the TLS-interception capability (V3).
+// trusted, the warning surfaces the TLS-interception capability.
 func TestWarnIfProxied_ProxyPluginCustomCAWarns(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	unsetProxyPluginEnv(t)
@@ -287,7 +169,7 @@ func TestWarnIfProxied_ProxyPluginCustomCAWarns(t *testing.T) {
 	t.Cleanup(func() { proxyPluginStatus = old })
 
 	var buf bytes.Buffer
-	WarnIfProxied(&buf, true)
+	WarnIfProxied(&buf)
 	out := buf.String()
 
 	if !strings.Contains(out, "custom CA") {
@@ -301,25 +183,6 @@ func TestWarnIfProxied_ProxyPluginCustomCAWarns(t *testing.T) {
 	}
 }
 
-// TestNewHTTPClient verifies the factory wires the shared proxy-plugin-aware
-// transport (instead of a bare client that bypasses proxy plugin mode).
-func TestNewHTTPClient(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	unsetProxyPluginEnv(t)
-	t.Setenv(EnvNoProxy, "")
-
-	c := NewHTTPClient(7 * time.Second)
-	if c.Transport == nil {
-		t.Fatal("NewHTTPClient transport is nil; want shared transport")
-	}
-	if c.Transport != SharedTransport() {
-		t.Errorf("NewHTTPClient transport = %v, want SharedTransport()", c.Transport)
-	}
-	if c.Timeout != 7*time.Second {
-		t.Errorf("NewHTTPClient timeout = %v, want 7s", c.Timeout)
-	}
-}
-
 // TestWarnIfProxied_ProxyPluginEnabledRedactsCredentials verifies the plugin
 // warning never leaks credentials embedded in the configured proxy address.
 func TestWarnIfProxied_ProxyPluginEnabledRedactsCredentials(t *testing.T) {
@@ -332,7 +195,7 @@ func TestWarnIfProxied_ProxyPluginEnabledRedactsCredentials(t *testing.T) {
 	t.Cleanup(func() { proxyPluginStatus = old })
 
 	var buf bytes.Buffer
-	WarnIfProxied(&buf, true)
+	WarnIfProxied(&buf)
 	out := buf.String()
 
 	if strings.Contains(out, "s3cret") {
@@ -348,8 +211,6 @@ func TestWarnIfProxied_ProxyPluginEnabledRedactsCredentials(t *testing.T) {
 
 // TestRedactProxyURL verifies redaction of proxy credentials across supported formats.
 func TestRedactProxyURL(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	unsetProxyPluginEnv(t)
 	tests := []struct {
 		input string
 		want  string
@@ -376,12 +237,13 @@ func TestRedactProxyURL(t *testing.T) {
 func TestWarnIfProxied_RedactsCredentials(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
 	proxyWarningOnce = sync.Once{}
 
 	t.Setenv("HTTPS_PROXY", "http://admin:s3cret@proxy:8080")
 
 	var buf bytes.Buffer
-	WarnIfProxied(&buf, true)
+	WarnIfProxied(&buf)
 
 	out := buf.String()
 	if bytes.Contains([]byte(out), []byte("s3cret")) {